This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Functional Components

Owned by Former user (Deleted)
Last updated: Jul 12, 2012Version comment
4 min read

To learn more about eventing see the following functional components:

Event Source

Event source implementation within the WSO2 ESB 2.0 provides a service, where subscribers can send WS-Eventing complaint subscriptions and subscription related operation requests to the WSO2 ESB. The event source is capable of dispatching events, but it is recommend to use the event brokering capability that is shipped with the "eventPublisher" mediator to publish events.

Subscription Manager

Subscription manager implements a repository for filing subscriptions and exposes subscription handling operations for an event source.

The main operations provided by the subscription manager:

  • Subscriptional
  • Renewal
  • Unsubscription

In addition, the subscription manager is capable of providing a subset of subscriptions matching filtering criteria.

Subscription Manager Implementations

The WSO2 ESB contains two default subscription manager implementations:

  • Topic based In-Memory - In-Memory subscription manager requires two properties, subscriptions and the events should use the topic header name with the messages. The value inside a topic header name is subscriptions and events used by the topic based event filter to identify valid subscriptions and dispatch the events.
  • Topic based Remote registry - Topic based remote registry subscription manager uses three additional properties in addition to the above. They are:
    • URL to the remote registry
    • User Name
    • Password

Note

The In-Memory subscription manager will not persist subscriptions (will loose subscriptions upon WSO2 ESB restarts).
The Remote registry based subscription manager persists subscriptions in the defined remote registry (using the remote registry as a repository).

Remote registry subscription manager stores:

  • Subscription as a registry recourse
  • Resource content - Is the target endpoint URL (event sink).
  • Subscription metadata - Keeping as resource properties.

Resource storage paths are created taking into account subscribed topic and will maintaining topic hierarchy tree within the storage path.

Subscription Messages

The WSO2 ESB 2.0 accepts WS-Eventing compatible subscriptions and subscription related requests.

Subscription Request
<soapenv:Envelope
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
		<wsa:To>
			http://localhost:8280/services/SampleEventSource
		</wsa:To>
		<wsa:MessageID>
			urn:uuid:43CF968A43DB8BE9321234756365001
		</wsa:MessageID>
		<wsa:Action>
			http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe
		</wsa:Action>
	</soapenv:Header>
	<soapenv:Body>
		<wse:Subscribe
			xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing">
			<wse:Delivery
				Mode="http://schemas.xmlsoap.org/ws/2004/08/eventing/DeliveryModes/Push">
				<wse:NotifyTo>
					<wsa:Address
						xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
						http://localhost:9000/services/SimpleStockQuoteService
					</wsa:Address>
				</wse:NotifyTo>
			</wse:Delivery>
			<wse:Filter
				Dialect="http://synapse.apache.org/eventing/dialect/topicFilter">
				synapse/event/test
			</wse:Filter>
		</wse:Subscribe>
	</soapenv:Body>
</soapenv:Envelope>

The above subscription message is sent to the event source URL together with a request to forward matching events to the endpoint defined under the delivery element. Subscription has not defined an expiration time, and the system will take it as a "never expire" subscription. Subscription request to use the topic filter by defining the relevant dialect.

A subscription like the above will get a response as given below:

Subscription Response
<soapenv:Envelope
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
		<wsa:Action>
			http://schemas.xmlsoap.org/ws/2004/08/eventing/SubscribeResponse
		</wsa:Action>
		<wsa:RelatesTo>
			urn:uuid:43CF968A43DB8BE9321234756365001
		</wsa:RelatesTo>
	</soapenv:Header>
	<soapenv:Body>
		<wse:SubscribeResponse
			xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing">
			<wse:SubscriptionManager>
				<wsa:Address
					xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
					http://localhost:8280/services/SampleEventSource
				</wsa:Address>
				<wsa:ReferenceParameters
					xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
					<wse:Identifier>
						urn:uuid:64CA121181EFEE933E1234756365048592001-897443196
					</wse:Identifier>
				</wsa:ReferenceParameters>
			</wse:SubscriptionManager>
		</wse:SubscribeResponse>
	</soapenv:Body>
</soapenv:Envelope>

Subscription response provides a subscription ID that is defined under the Identifier element. ID is required for the subscription to interact with other requests. Subscription requests need to be sent to the URL defined within the SubscriptionManager element.

Subscription Renew Request
<soapenv:Envelope
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
		<wse:Identifier
			xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing">
			urn:uuid:64CA121181EFEE933E1234756365048592001-897443196
		</wse:Identifier>
		<wsa:To>
			http://localhost:8280/services/SampleEventSource
		</wsa:To>
		<wsa:MessageID>
			urn:uuid:F6CB32A7CD42D6F0BC1234759780828
		</wsa:MessageID>
		<wsa:Action>
			http://schemas.xmlsoap.org/ws/2004/08/eventing/Renew
		</wsa:Action>
	</soapenv:Header>
	<soapenv:Body>
		<wse:Renew
			xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing">
			<wse:Expires>2009-06-26T21:07:00.000-08:00</wse:Expires>
		</wse:Renew>
	</soapenv:Body>
</soapenv:Envelope>

To renew a subscription, new expiration dates need to be provided with a subscription ID. The date needs to be specified under the Expires element.

Subscription Renew Response
<soapenv:Envelope
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
		<wsa:Action>
			http://schemas.xmlsoap.org/ws/2004/08/eventing/RenewResponse
		</wsa:Action>
		<wsa:RelatesTo>
			urn:uuid:F6CB32A7CD42D6F0BC1234759780828
		</wsa:RelatesTo>
	</soapenv:Header>
	<soapenv:Body>
		<wse:RenewResponse
			xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing">
			<wse:Expires>2009-06-26T21:07:00.000-08:00</wse:Expires>
		</wse:RenewResponse>
	</soapenv:Body>
</soapenv:Envelope>

Renew response will send new expiration date of the subscription.

Subscription Get Status Request
<soapenv:Envelope
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
		<wse:Identifier
			xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing">
			urn:uuid:64CA121181EFEE933E1234756365048592001-897443196
		</wse:Identifier>
		<wsa:To>
			http://localhost:8280/services/SampleEventSource
		</wsa:To>
		<wsa:MessageID>
			urn:uuid:81D76A2219F3C6B0881234759384021
		</wsa:MessageID>
		<wsa:Action>
			http://schemas.xmlsoap.org/ws/2004/08/eventing/GetStatus
		</wsa:Action>
	</soapenv:Header>
	<soapenv:Body>
		<wse:GetStatus
			xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing" />
	</soapenv:Body>
</soapenv:Envelope>

Get status requires only subscription ID.

Subscription Get Status Response
<soapenv:Envelope
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
		<wsa:Action>
			http://schemas.xmlsoap.org/ws/2004/08/eventing/GetStatusResponse
		</wsa:Action>
		<wsa:RelatesTo>
			urn:uuid:81D76A2219F3C6B0881234759384021
		</wsa:RelatesTo>
	</soapenv:Header>
	<soapenv:Body>
		<wse:GetStatusResponse
			xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing">
			<wse:Expires>*</wse:Expires>
		</wse:GetStatusResponse>
	</soapenv:Body>
</soapenv:Envelope>
Unsubscribe Request
<soapenv:Envelope
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
		<wse:Identifier
			xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing">
			urn:uuid:64CA121181EFEE933E1234756365048592001-897443196
		</wse:Identifier>
		<wsa:To>
			http://localhost:8280/services/SampleEventSource
		</wsa:To>
		<wsa:MessageID>
			urn:uuid:EC76663766F0B078241234760085376
		</wsa:MessageID>
		<wsa:Action>
			http://schemas.xmlsoap.org/ws/2004/08/eventing/Unsubscribe
		</wsa:Action>
	</soapenv:Header>
	<soapenv:Body>
		<wse:Unsubscribe
			xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing" />
	</soapenv:Body>
</soapenv:Envelope>
Unsubscribe Response
<soapenv:Envelope
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
		<wsa:Action>
			http://schemas.xmlsoap.org/ws/2004/08/eventing/UnsubscribeResponse
		</wsa:Action>
		<wsa:RelatesTo>
			urn:uuid:EC76663766F0B078241234760085376
		</wsa:RelatesTo>
	</soapenv:Header>
	<soapenv:Body>
		<wse:UnsubscribeResponse
			xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing" />
	</soapenv:Body>
</soapenv:Envelope>
Fault Responses
<soapenv:Envelope
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
		<wsa:Action>
			http://www.w3.org/2005/08/addressing/fault
		</wsa:Action>
		<wsa:RelatesTo>
			urn:uuid:2D69A406E9AAEFE60D1234760763922
		</wsa:RelatesTo>
	</soapenv:Header>
	<soapenv:Body>
		<soapenv:Fault>
			<detail />
			<faultstring>Unable to Unsubscribe</faultstring>
			<faultcode
				xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing">
				wse:EventSourceUnableToProcess
			</faultcode>
		</soapenv:Fault>
	</soapenv:Body>
</soapenv:Envelope>

Event Broker

The WSO2 ESB 2.0 acts as an event broker dispatching events coming into the ESB. To dispatch an event, the event should fulfill requirements of the particular event source and match subscriptions using active event filter. Message brokering is done using the new mediator "eventPublisher" and Proxy Services. If there are more than one active subscription found for an event, "eventPublisher" will clone the message and send them out to endpoints described under the subscriptions.

The following information about event broker is available:

Event Filtering

WSO2 ESB 2.0 comes with one filter implementation, which is topic based on event filtering. It supports single topic or hierarchical topic trees. When an event arrives, the filter selects the matching subscriptions and parent subscriptions based on the topic. As an example see the following subscriptions:

Subscription

Topic

sub1

wso2

sub2

wso2/esb

sub3

wso2/wsas

sub4

wso2/esb/mediation

When an event arrives with topic x, it will dispatch for the EPR (Endpoint Reference) defined in the subscriptions as follows:

Event Topic

Matching subscriptions

wso2

sub1

wso2/esb

sub1, sub2

wso2/wsas

sub1, sub3

wso2/esb/mediation

sub1, sub2, sub4

Event Mediation

WSO2 ESB 2.0 provides mediation capability for events with the implementation "eventPublisher" mediator. Events are directed to a Proxy Service and the Proxy Service can have any number of sequences that associates with different mediators and finally falls into the "eventPublisher" mediator for dispatch.

As illustrated in the above diagram, a message (event) will flow through a configured sequence of mediators, and finally flow into the "eventPublisher" mediator. This is described below in detail with sample scenarios.

Sample Event

Sample event message for the topic filtering looks like the following message:

<soapenv:Envelope
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
		<aip:Topic xmlns:aip="http://apache.org/aip">
			synapse/event/test
		</aip:Topic>
		<wsa:To>http://localhost:8280/services/EventingProxy</wsa:To>
		<wsa:ReplyTo>
			<wsa:Address>
				http://www.w3.org/2005/08/addressing/none
			</wsa:Address>
		</wsa:ReplyTo>
		<wsa:MessageID>
			urn:uuid:69522E7A5DBF1FCE651234773847339
		</wsa:MessageID>
		<wsa:Action>urn:event</wsa:Action>
	</soapenv:Header>
	<soapenv:Body>
		<m:placeOrder xmlns:m="http://services.samples/xsd">
			<m:order>
				<m:price>10.10</m:price>
				<m:quantity>1000</m:quantity>
				<m:symbol>GOOG</m:symbol>
			</m:order>
		</m:placeOrder>
	</soapenv:Body>
</soapenv:Envelope>

Events needs to be sent to the Proxy Service URL that defines the "eventPublisher" mediator.