From 6d1532b40eae7ca08a44d8b5cdee22663c939be5 Mon Sep 17 00:00:00 2001 From: Jonathan Robie Date: Wed, 7 Apr 2010 23:28:00 +0000 Subject: Now discusses mapping to 0-10, and uses drain and spout to show how Sender and Receiver work when bound to various exchange types or queues. Includes full discussion of subject. (Still need to do options, and to show the code for request/response in the section on message properties). git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@931721 13f79535-47bb-0310-9956-ffa450edef68 --- doc/book/src/High-Level-API.xml | 392 ++++++++++++++++++++++++++++++++-------- 1 file changed, 318 insertions(+), 74 deletions(-) (limited to 'doc') diff --git a/doc/book/src/High-Level-API.xml b/doc/book/src/High-Level-API.xml index 3116846159..4049dfbafb 100644 --- a/doc/book/src/High-Level-API.xml +++ b/doc/book/src/High-Level-API.xml @@ -108,7 +108,7 @@ int main() { A Message Sender The sender program creates a Sender object that sends messages to message_queue, which happens to be a queue on - on AMQP 0-10 messaging broker: + on AMQP 0-10 messaging broker. + The AMQP 0-10 mapping implements this by sending messages + to the default exchange, with message_queue as + the routing key. +
A Message Receiver @@ -268,73 +272,330 @@ $ ./drain -a hello-world $ - In AMQP 0-10, exchanges discard messages if #### + However, in AMQP 0-10, exchanges discard messages if no + queue is bound to the exchange, unlike queues, which store + messages until they are retrieved. Because of this, no messages + were output in the above screen. If drain is + called before spout, a Receiver is created + for the exchange, which also creates a subscription queue and a + binding. Run drain in one terminal window + using -t to specify a timeout in seconds, and + run spout in another window to send a message + for drain to receive. -
Subjects - - A simple name with a subject will also resolve to a node, but the - presence of the subject will cause a sender using this address to - set the subject on outgoing messages, and receivers to filter based - on the subject: + Subjects are used to classify messages. + + A Sender's subject is assigned to each message that it + sends (this can be overridden by specifying a subject directly + on the message). In the AMQP 0-10 mapping, the message's subject + is used as the routing key for all messages sent to the + messaging broker. If a Sender is bound to an AMQP 0-10 exchange, + it sends messages to that exchange. If a Sender is bound to an + AMQP 0-10 queue, the message is sent to the default + exchange. + + A Receiver's subject is used to filter messages; only + messages with a subject that matches the Receiver's subject will + be received. If a Receiver's name resolves to an AMQP 0-10 + exchange, the subject is used as a binding key for the + corresponding AMQP 0-10 exchange type. + - my-queue-or-topic/my-subject + + The C++ implementation of the Qpid messaging broker does + not currently support selectors, so a Receiver's subject does + not filter messages if the Receiver's address resolves to a + queue. + + +
+ Direct Exchanges + + In an AMQP 0-10 direct exchange, messages are routed + to queues if the routing key exactly matches the binding + key. In the High Level Client API, if a Sender and a + Receiver are bound to the same exchange, the Receiver will + receive messages if the Sender's subject matches the + Receiver's subject. + + Let's create a direct exchange and listen for messages + whose subject is sports: + + First window: + +$ qpid-config add exchange direct direct-exchange +$ ./drain -a direct-exchange/sports -t 30 + + + In a second window, let's send messages to the + exchange we created: + + Second window: + +$ ./spout -a direct-exchange/sports +$ ./spout -a direct-exchange/news + + + Now look at the first window, and you will see the + message with the subject sports has been + received, but not the message with the subject + news: + + +Message(properties={qpid.subject:sports, spout-id:9441674e-a157-4780-a78e-f7ccea998291:0}, content='') + + + If you run drain in multiple + windows using the same subject, all instances of + drain receive the messages for that + subject. + +
+
+ Topic Exchanges + + An AMQP 0-10 topic exchange uses routing keys that + contain multiple words separated by a . + delimiter. For instance, in a news application, a Sender's + subject might be usa.news, + usa.weather, + europe.news, or + europe.weather. A Receiver's subject can + include wildcard characters— # matches + one or more words in the message's subject, * + matches a single word. For instance, if the Receiver's + subject is *.news, it matches messages + with the subject europe.news or + usa.news; if the Receiver's subject is + europe.#, it matches messages with + subjects like europe.news or + europe.pseudo.news. + + Let's create a topic exchange and listen for messages + whose subject is news: + + First window: + + +$ qpid-config add exchange topic topic-exchange +$ ./drain -a topic-exchange/news -t 30 + + + In a second window, let's send messages to the + exchange we created: + + Second window: + +$ ./spout -a topic-exchange/news +$ ./spout -a topic-exchange/sports + + + + Now look at the first window, and you will see the + message with the subject news has been + received, but not the message with the subject + sports: + + +Message(properties={qpid.subject:news, spout-id:bafefb74-c5be-4a8b-9e4b-45f7a855e250:0}, content='') + + + + Now let's use the topic exchange with wildcards in the + Receiver and multi-word keys in the Sender. This time, let's + use two-word keys. The Receiver uses the subject + *.news to listen for messages in which + the second word of the key is + news: + + + First window: + + +$ ./drain -a topic-exchange/*.news -t 30 + + + Now let's send messages using several different + two-word keys: - A subject pattern can be used and will cause filtering if used by - the receiver. If used for a sender, the literal value gets set as - the subject:: + Second window: - my-queue-or-topic/my-* + +$ ./spout -a topic-exchange/usa.news +$ ./spout -a topic-exchange/usa.sports +$ ./spout -a topic-exchange/europe.sports +$ ./spout -a topic-exchange/europe.news +$ + + + Now look at the first window, and you will see the + messages with news in the second word of + the key have been received: + + +Message(properties={qpid.subject:usa.news, spout-id:73fc8058-5af6-407c-9166-b49a9076097a:0}, content='') +Message(properties={qpid.subject:europe.news, spout-id:f72815aa-7be4-4944-99fd-c64c9747a876:0}, content='') + + + Finally, let's use the # wildcard + in the Receiver to match any number of words in the key. The + Receiver uses the key #.news to listen + for messages in which the last word of the key is + news, no matter how many words are in the + key: + + First window: + + +$ ./drain -a topic-exchange/#.news -t 30 + + + Now let's send messages using a variety of different + multi-word keys: + + Second window: + + +$ ./spout -a topic-exchange/news +$ ./spout -a topic-exchange/sports +$ ./spout -a topic-exchange/usa.news +$ ./spout -a topic-exchange/usa.sports +$ ./spout -a topic-exchange/usa.faux.news +$ ./spout -a topic-exchange/usa.faux.sports + + + Now look at the first window, and you will see the + messages with news in the last word of + the key have been received: + + +Message(properties={qpid.subject:news, spout-id:cbd42b0f-c87b-4088-8206-26d7627c9640:0}, content='') +Message(properties={qpid.subject:usa.news, spout-id:234a78d7-daeb-4826-90e1-1c6540781eac:0}, content='') +Message(properties={qpid.subject:usa.faux.news, spout-id:6029430a-cfcb-4700-8e9b-cbe4a81fca5f:0}, content='') + + +
+ +
+ Fanout Exchanges + + A fanout exchange ignores the subject, and no + filtering is done. + + Let's create a fanout exchange and listen for + messages. We will use the subject news + in the Receiver to demonstrate that this subject is not + actually used to filter messages: + + + First window: + + +$ qpid-config add exchange fanout fanout-exchange +$ ./drain -a fanout-exchange/news -t 30 + + + Now let's send a message using a different + subject: + + Second window: + + +$ ./spout -a fanout-exchange/sports + + + Returning to the first window, we see that the message + was received even though the Receiver's subject was + different from the Sender's subject: + + +Message(properties={qpid.subject:sports, spout-id:931399a1-27fc-471c-8dbe-3048260f9441:0}, content='') + + + This happens because of the routing semantics of the AMQP 0-10 fanout exchange. + +
+ +
+
+ Queues + + If a Sender is bound to a queue, its messages are sent + to the default exchange using the queue's name as the + routing key. If a Receiver is bound to a queue, it receives + messages from the queue. + + Let's create a queue and listen for messages on it. + + First window: + + +$ ./qpid-config add queue amqp010-queue +$ ./drain -a amqp010-queue -t 30 + + + Now let's send some messages. The subject is not used for routing purposes. + +$ ./spout -a amqp010-queue/news +$ ./spout -a amqp010-queue + + + Now look at the first window, and you will see that + both messages have been received: + + +Message(properties={qpid.subject:news, spout-id:6c769437-60be-4bc0-9bf6-5a77cb6ba65f:0}, content='') +Message(properties={spout-id:c8ab5013-a19e-4f54-967c-797c8ad6568b:0}, content='') + + +
+ + + +
+ Custom Exchanges + + AMQP 0-10 also supports custom exchanges. The + Qpid messaging broker includes the XML Exchange, which uses an + XQuery to filter messages based on message properties and XML + message content. + + + +
- + +
Options @@ -442,7 +703,6 @@ SH: spout small-world/news.local --> -
@@ -512,28 +772,12 @@ SH: spout small-world/news.local - - - -