Please note this page is present for reference only. QMan has been removed and is no longer a released component.

Subscribe

Description

This interface allows a requestor to register itself as a listener of one or more QMan topics.

Request

Depending on filter and termination time we could have different combination of subscribe requests.

In general let's say we could specify the following :

a topic filter : contains a name of a valid and existent topic.
In this case the subscriber is interested to receive only messages that are published on a given topic;
If there's no such filter the subscriber is supposed to be interested on all topics;
a message filter : contains an expression that is evaluated against the current message.
Only if the evaluation of the given expression returns true this filter allows the message delivery.
a producer properties filter : contains an expression that is evaluated against the resource properties document of the producer.
Only if the evaluation of the given expression returns true this filter allows the message delivery.

a termination time : allows a requestor to specify a termination time of the Subscription being created.
If it is not present the subscription will never expire.

Filters are not mandatory. That means if you omit lines 23 - 34 a subscription will be created for all messages / all topics without expiration date.
Filters are processed in AND mode. That means if one of them fails, the message won't be delivered.
Note that only XPath is supported as Dialect for filter expressions.

In the example reported below QMan (acting as a consumer) is running on localhost:8080 while the consumer is an endpoint service located on consumer.host.name:8726.

01.	<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
02.		<soap:Header>
03.			<wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">
04.				http://localhost:8080/qman/services/adapter
05.			</wsa:To>
06.     	        <wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">
07.				http://docs.oasis-open.org/wsn/bw-2/NotificationProducer/SubscribeRequest
08.			</wsa:Action>
09.     	        <wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">
10.				uuid:0cdb5112-09e0-ac39-06ba-393843f06e42
11.			</wsa:MessageID>
12.			<wsa:From xmlns:wsa="http://www.w3.org/2005/08/addressing">
13.     		        <wsa:Address>
14.					http://www.w3.org/2005/08/addressing/role/anonymous
15.				</wsa:Address>
16.			</wsa:From>
		</soap:Header>
		<soap:Body xmlns:qman="http://amqp.apache.org/qpid/management/qman">
17.			<wsnt:Subscribe xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2">
18.				<wsnt:ConsumerReference>
19.					<wsa:Address xmlns:wsa="http://www.w3.org/2005/08/addressing">
20.						http://consumer.host.name:8726/qman/services/consumer
21.					</wsa:Address>
22.				</wsnt:ConsumerReference>
23.				<wsnt:Filter>
24.					<wsnt:TopicExpression Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Concrete">
25.						qman:EventsLifeCycleTopic
26.					</wsnt:TopicExpression>
27.					<wsnt:MessageContent Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116">
28.						/NotificationMessage/Message/LifeCycleEvent/Resource/Name/text()='connection'
29.					</wsnt:MessageContent>
30.                	                <wsnt:ProducerProperties Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116">
31.						boolean(/*/MgtPubInterval > 100)
32.					</wsnt:ProducerProperties>
33.				</wsnt:Filter>
34.				<wsnt:TerminationTime>2009-02-20T13:29:24+01:00</wsnt:TerminationTime>
35.			</wsnt:Subscribe>
		</soap:Body>
	</soap:Envelope>

Line(s)	Description
01	The SOAP <Envelope> is the root element in every SOAP message, and contains two child elements, <Header> and <Body>.
02	The SOAP Header will contain all metadata used for identifying the conversation participants (requestor and provider).
03 - 05	Convey the target endpoint also known (in the request phase) as service provider.
06 - 08	Indicate this is a Subscribe request.
09 - 11	Convey a unique identifier associated with the current message. This will be used for request / response messages correlation.
12 - 15	Provide the address of the source endpoint also known (in the request phase) as service requestor.
17 - 23	This is the Subscribe request.
19 - 21	This element contains the address (line 20) of the consumer service endpoint. After this request has been processed it will be referred as Subscriber.
23 - 33	This is the most interesting part of the message : filters.
24 - 26	Topic filter : the consumer wants subscribe only the messages that are published on qman:EventsLifeCycleTopic (line 25) topic.
27 - 29	Message filter : the consumer wants receive notification only when the message is referred to a resource with "connection" as name (28). Basically it wants to monitor connections on broker.
30 - 32	Producer RSP filter : the consumer wants receive notification only when the producer has a property named MgmtPubInterval that is greater than 100.

Response

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
		<soap:Header>
01.			<wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">
02.				http://www.w3.org/2005/08/addressing/role/anonymous
03.			</wsa:To>
04.			<wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">
05.				http://docs.oasis-open.org/wsn/bw-2/NotificationProducer/SubscribeResponse
06.			</wsa:Action>
07.			<wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">
08.				uuid:980617c8-e3a0-ebf1-8f5a-2b43d3d6d416
09.			</wsa:MessageID>
10.			<wsa:RelatesTo RelationshipType="wsa:Reply" xmlns:wsa="http://www.w3.org/2005/08/addressing">
11.				uuid:0cdb5112-09e0-ac39-06ba-393843f06e42
12.			</wsa:RelatesTo>
13.			<wsa:From xmlns:wsa="http://www.w3.org/2005/08/addressing">
14.				<wsa:Address>
15.					http://localhost:8080/qman/services/adapter
16.				</wsa:Address>
			</wsa:From>
		</soap:Header>
		<soap:Body>
17.			<wsnt:SubscribeResponse xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2">
18.				<wsnt:SubscriptionReference>
19.					<wsa:Address xmlns:wsa="http://www.w3.org/2005/08/addressing">
20.						http://localhost:8080/qman/services/SubscriptionManager
21.					</wsa:Address>
22.					<wsa:ReferenceParameters xmlns:wsa="http://www.w3.org/2005/08/addressing">
23.						<qman-wsa:ResourceId xmlns:qman-wsa="http://amqp.apache.org/qpid/management/qman/addressing">
24.							e067f34f-e7e9-4cb2-b13c-185a7e0d1d16
25.						</qman-wsa:ResourceId>
26.					</wsa:ReferenceParameters>
27.				</wsnt:SubscriptionReference>
28.			<wsnt:CurrentTime>2009-02-10T20:41:07+01:00</wsnt:CurrentTime>
29.			<wsnt:TerminationTime>2009-02-10T20:41:26+01:00</wsnt:TerminationTime>
30.			</wsnt:SubscribeResponse>
		</soapBody>
	</soap:Envelope>

Line(s)	Description
01 - 03	Convey the recipient of the response message. Note that this time we are talking about the service requestor; The address matches the <wsa:From> previously found in the corresponding request.
04 - 06	Indicate this is a Subscribe response. This is done as usual using a wsa:Action that is part of WS-Addressing specification.
07 - 09	Convey a unique identifier associated with the current response message.
10 - 12	This element provides the identifier of the correlated (request) message.
13	The <wsa:From> element (part of WS-Addressing specs too) identifies the source endpoint, the originator of this response message.
14 - 16	This is the address of the source service endpoint. As said for lines 01-03 this time this is referred to service provider (the message originator).
17 - 30	This is the body of the subscribe response.
18 - 27	Conveys the details of the subscription that has been created.
19 - 24	A subscription, as any other WS-Resource, has an address (20) and a resource identifier (24).
28	The creation date of the subscription.
29	The expiration / termination time of the subscription.

Faults

ResourceUnknownFault : There's no resource on QMan associated with the given reference information (soap address and identifier).
InvalidFilterFault : The request contains a filter that is not supported.
TopicExpressionDialectUnknownFault : The request contains a topic filter with an unknown / not supported dialect.
TopicNotSupportedFault : The request contains a topic that is not supported.
InvalidTopicExpressionFault : The request contains a topic filter with an invalid expression.
InvalidProducerPropertiesExpressionFault : The request contains a producer properties filter with an invalid expression.
InvalidMessageContentExpressionFault : The request contains a message properties filter with an invalid expression.
SubscribeCreationFailedFault : The notification producer failed to process the subscribe request.

Quick links

Web Services Base Notification 1.3