PubSub

Subscription Set 

<subscription-set max-failures="...">
    <!-- the uri of the service registering the subscription set -->
    <uri.owner>...</uri.owner>

    <!-- the set can have 1 or more subscription blocks. @id will be assigned by
        the server if none was provided -->
    <subscription id="...">

        <!-- each subscription can include 1 or more channels. Channels are OR-ed
            for matching events. Channels can use a wildcard '*' for host
            and end of path -->
        <channel>channel:///some/channel</channel>
        ...

        <!-- each subscription can include 0 or more resources to subscribe to. Resources
            are OR-ed for matching events.  Resource Uri's can use a wildcard '*' for host
            and end of path -->
        <uri.resource>http://canonical/path/to/resource</uri.resource>
        ...

        <!-- There can be zero or one proxy. If it exists it is used as the
            destination for matched events -->
        <uri.proxy>...</uri.proxy>

        <!-- There can be 1 or more recipients. If there is more than one recipient
            a proxy must be defined. If the event has recipients, the intersection
            between event and subscription recipients is used to filter matches. Recipient
            comparison is done solely on the recipient uri, although end points can employ
            their own contracts based on additional data included in the recipient document -->
        <recipient>
            <uri>...</uri>
            ...
        </recipient>
        ... 

    </subscription>
    ...
</subscription-set>

 

Channels

Channels are URIs. There generalized format is:

{system}://{instance}/{action-path}

In subscription sets, channels accept wild cards at the instance or end of action. The following are all valid channel patterns:

channel://*/some/exact/path
foo://some-instance/wildcard/path/*
channel://*/*

The PubSubService is also a publisher itself of change events on its subscription set, which it POSTs against subscribers that subscribe to the channel pattern

Accces: Internal

This feature is internal, but the services provided the URI for this service are generally also provided the appropriate cookie along for the automatically provided publish.

Request body

The request body can be anything, accompanied by a proper mime-type. However, there are some header requirements.

Headers	Occurence	Description
X-Dream-Event-Id	1	The id of the event. If one was not provided, one will assigned and returned in the response body
X-Dream-Event-Origin-Uri	1+	one or more resource uri's for resources related to the event. Generally additional uri's denote previous locations of that resource
X-Dream-Event-Channel	1	the channel this event is published to
X-Dream-Event-Via-Uri	0+	zero or more publishers the event has passed through (to determine circular routes)
X-Dream-Event-Recipient-Uri	0+	a list of recipients authorized to receive the event. Generally should be set by a EventSubscriber based on the set of recipient subscribers so that known downstream subscribers are in this list

Response

Response	Response Body	Description
Ok (200)	see below	operation completed successfully and a new event was created
Bad Request (400)	text/html	request could not be completed, because of invalid data in the request

Response body

The response body is always an empty envelope with an id, either the one provided in the header by the caller or assigned by service, if none existed.

<event id="ad232fdd0ed" />

Access: Internal

Request body

Xml document following the subscription set specified above.

Response

Status	Response Body	Description
Created (201)	text/xml	operation completed successfully. Response contains Location header
Conflict (409)	--	A set for that owner already exists. Response contains a Content-Location header for the location of the conflicting subscription set

Response body

<subscription-set>
  <uri.location>...</uri.location>
  <access-key>...</access-key>
</subscription-set>

The response also includes a Location header that has the access-key appended as a query-argument. Access is granted to the location either by using the location uri from the header directly (which may expose the access key), or by constructing an access-key cookie for the location.

---

Access: Internal

Response

Status	Response Body	Description
OK (200)	text/xml	operation completed successfully

 

---

Access: Private

A private key is issued upon creation of the location

Access: Private

A private key is issued upon creation of the location

Response

Status	Response Body	Description
OK (200)	--	operation completed successfully

 

---

Access: Private

A private key is issued upon creation of the location

Response

Status	Response Body	Description
OK (200)	--	operation completed successfully