WS-Eventing for Dummies

WS-Eventing is a standard that enables interoperable publish/subscribe systems. The spec itself is quite short and sweet – I recommend taking a look at it. As a tester, I’m quite pleased by the simplicity because it makes implementations easier to test (and hopefully more robust). I hope that you, as developers writing to the spec, find it easy to create those implementations.

So let’s see how subscriptions work with WS-Eventing...

The Simplest Subscription

I'm writing a client app, and I want to receive notifications about shark attacks. I know there is a server out there that sends such notifications to anyone who subscribes. Here is a first cut at a subscription message:

<Envelope>

    <Body>

        <Subscribe />

    </Body>

<Envelope>

(This is not valid WS-Eventing)

 (For legibility I'm stripping out the namespaces; please refer to the spec to get that info.)

What’s It All About?

Ok, that’s not a valid WS-Eventing subscription message; it is missing a few things. First off, there is no mention of shark attacks there; we’ll fix that first:

<Envelope>

    <Header>

        <To>https://www.ocean.com/notifications/shark-attacks</To>

    </Header>

    <Body>

        <Subscribe />

    </Body>

<Envelope>

(This is not valid WS-Eventing)

Who Cares?

Well, that looks pretty sharp; but unfortunately having received our subscription, the service has no idea where to send the shark attack notifications! We need to let it know where to send that all-important shark attack info, and we do it like this:

<Envelope>

    <Header>

        <To>https://www.ocean.com/notifications/shark-attacks</To>

    </Header>

    <Body>

        <Subscribe>

           <NotifyTo>

               <Address>https://www.me.com/shark-attack-notification-handler</Address>

           </NotifyTo>

        </Subscribe>

    </Body>

<Envelope>

(This is not valid WS-Eventing)

Did It Work?

Ok, that’s starting to look pretty good. I’ve got a little surprise for you, though – according to the WS-Eventing spec, you get a response message to let you know that your subscription succeeded! Wow, that’s cool – but now we have to let the service know where to send the response message. We’ll use WS-Addressing’s handy-dandy ReplyTo header for that:

<Envelope>

    <Header>

        <ReplyTo>https://www.me.com/subscription-response-handler</ReplyTo>

        <To>https://www.ocean.com/notifications/shark-attacks</To>

    </Header>

    <Body>

        <Subscribe>

           <NotifyTo>

               <Address>https://www.me.com/shark-attack-notification-handler</Address>

           </NotifyTo>

        </Subscribe>

    </Body>

<Envelope>

(This is not valid WS-Eventing)

Insert Tab A Into Slot B

What else could we possibly need? Well, honestly that’s the most important stuff, but the WS-Eventing spec does require a few more elements. For example, we need to be able to handle multiple subscription requests from the same subscriber. If you sent two copies of the message above (perhaps with shark-attacks and jellyfish-attacks), then you wouldn’t have any way to distinguish the two subscription responses that come back. So let’s add an ID to each message that the service will return to us in the associated response:

<Envelope>

    <Header>

        <MessageID>https://www.me.com/subscriptions/583</MessageID>

        <ReplyTo>https://www.me.com/subscription-response-handler</ReplyTo>

        <To>https://www.ocean.com/notifications/shark-attacks</To>

    </Header>

    <Body>

        <Subscribe>

<NotifyTo>

<Address>https://www.me.com/shark-attack-notification-handler</Address>

</NotifyTo>

        </Subscribe>

    </Body>

<Envelope>

(This is not valid WS-Eventing)

Administrivia

We still don’t have a valid WS-Eventing subscription message, but we are so close! All we need now is a little bit of header fluff that says “yes, this really is a WS-Eventing subscription.” And here we go…

<Envelope>

    <Header>

        <Action>https://schemas.xmlsoap.org/ws/2004/01/eventing/Subscribe</Action>

        <MessageID>https://www.me.com/subscriptions/583</MessageID>

        <ReplyTo>https://www.me.com/subscription-response-handler</ReplyTo>

        <To>https://www.ocean.com/notifications/shark-attacks</To>

    </Header>

    <Body>

        <Subscribe>

<NotifyTo>

<Address>https://www.me.com/shark-attack-notification-handler</Address>

</NotifyTo>

        </Subscribe>

    </Body>

<Envelope>

(This is finally valid WS-Eventing)

And there it is.

There’s More Where That Came From

There are some optional elements in the subscription message that I haven’t discussed; and there are some other messages defined in the WS-Eventing spec. I’ll talk about those in the future. In the meantime, let me know if you found this useful.