THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
| Note | ||
|---|---|---|
| ||
Please note this page is present for reference only. QMan has been removed and is no longer a released component. |
Subscribe
| Table of Contents | ||||
|---|---|---|---|---|
|
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.
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.Note - 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.
Code Block xml xml 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
| Code Block | ||||
|---|---|---|---|---|
| ||||
<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.