From e5ad5c090ff0b2a7b226f41ef38dac575c3f7550 Mon Sep 17 00:00:00 2001 From: Jonathan Robie Date: Tue, 20 Apr 2010 20:43:21 +0000 Subject: Applied Gordon's patch ... will now start merging in changes from my own reorg. git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@936056 13f79535-47bb-0310-9956-ffa450edef68 --- qpid/doc/book/src/High-Level-API.xml | 1965 ++++++++++++++++++---------------- 1 file changed, 1060 insertions(+), 905 deletions(-) diff --git a/qpid/doc/book/src/High-Level-API.xml b/qpid/doc/book/src/High-Level-API.xml index a1607f149d..f958903edd 100644 --- a/qpid/doc/book/src/High-Level-API.xml +++ b/qpid/doc/book/src/High-Level-API.xml @@ -1,102 +1,111 @@ + ]> - - - Apache Qpid Messaging API - - Apache Qpid is a reliable, asynchronous messaging system that - supports the AMQP messaging protocol in several common programming - languages on the Linux, Windows, Java, and Unix platforms. On the - Java platform, Qpid uses the established Java JMS API. On the - .NET platform, Qpid uses a WCF binding. For - Python and C++, Qpid uses the Qpid Messaging API, which has - implementations in both languages. Support for this API in Ruby will - be added soonRuby currently uses an API that is - closely tied to the AMQP version.. - - - Unlike earlier Qpid APIs, the Qpid Messaging API does not - expose the details of the underlying messaging protocol or the - software components defined by the protocol. Instead, it defines a - declarative syntax for addressing messaging components; to use it - with a given messaging protocol, a protocol mapping must be defined. - This specification provides a mapping to AMQP 0-10. - - Qpid uses the same addressing scheme in Java JMS, WCF, and the - Qpid Messaging API. An address is a simple - string that represents the name of a node on a messaging broker. In - the AMQP 0-10 mapping, an address resolves to an exchange or a - queue. - - - Here are the most important classes in the Qpid Messaging API - programming model. - - - - - A connection represents a - network connection. The parameters for the network connection are - specified using a URL-based syntax when the connection is - opened. - - A session represents the - interface between a messaging client and a - messaging broker. A session is created by a - connection. - - A message consists of - message content (the body of the message), - and message properties, which may include a - subject, a reply address, etc. Message content is a blob which may - contain text or binary data. Map messages allow binary data to be - exchanged portably across languages and - platforms. - - A sender is a messaging - client that sends messages to a destination - on a messaging broker. A sender is created by - a session. - - A receiver is a messaging - client that receives messages from a - source on a Messaging Broker. A Receiver - is created by a Session. - - + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + --> + + + Using Qpid for Messaging
- A Simple Messaging Program in C++ + Supported APIs + + Apache Qpid is a reliable, asynchronous messaging system that + supports the AMQP messaging protocol in several common programming + languages. On the Java platform, Qpid uses the + established Java JMS + API. On the .NET platform, Qpid defines + a WCF + binding. For Python and C++ however, Qpid defines its own + messaging API which is conceptually similar in each supported + language. Support for this API in Ruby will be added + soonRuby currently uses an API that is closely tied + to the AMQP version.. + +
+ +
+ Using the Qpid messaging API - The following C++ program shows how to create a Connection, - create a Session, send messages to a queue using a Sender, and - receive messages from a queue using a Receiver. + The Qpid messaging API is quite simple, consisting of only a + handful of core classes. + + + + + + + A connection manages a group + of sessions and connects them with a + remote endpoint. + + + + + + Sessions provide a linear context for + sending and receiving messages. + + + + + + Messages are sent using the send method on + a sender. A sender is obtained from a + session for a given target address. + + + + + + Messages are received using the fetch method of + a receiver. A receiver is obtained from a + session for a given source address. + + + + + + A message consists of a standard set of + fields, an application defined set of properties, and some + content. + + + + + + + The following sections show how these classes might be used in a + simple example program. + + +
+ A Simple Messaging Program in C++ + + The following C++ program shows how to create a connection, + create a session, send messages using a sender, and receive + messages using a receiver. - #include #include @@ -134,18 +143,16 @@ int main(int argc, char** argv) { }]]> -
- -
- A Simple Messaging Program in Python - +
- The following Python program shows how to create a - Connection, create a Session, send messages to a queue using a - Sender, and receive messages from a queue using a Receiver. +
+ A Simple Messaging Program in Python + The following Python program shows how to create a + connection, create a session, send messages using a sender, and + receive messages using a receiver. - -
- -
- A Simple Messaging Program in Java JMS - - The following program shows how to use address strings and - JNDI for Qpid programs that use Java JMS. - - This program uses a JNDI file that defines a connection - factory for the broker we are using, and the address of the topic - exchange node that we will bind the sender and receiver to. (The - syntax of a ConnectionURL is given in .) - - - - In the Java JMS code, we use create a JNDI context, use the context to find a connection factory and create and start a connection, create a session, and create a destination that corresponds to the topic exchange. Then we create a sender and a receiver, send a message with the sender, and receive it with the receiver. This code should be straightforward for anyone familiar with Java JMS. - - +
+ Addresses + + + When creating a sender or receiver, an address is + specified. An address identifies a + target or source for messages. This makes it easy to change + the target to which messages are being sent without affecting + the application doing the sending. Likewise it is easy to + change the source from which messages are received without + changing the code that controls their receipt. + - public static void main(String[] args) { - Hello producer = new Hello(); - producer.runTest(); - } + + The Qpid messaging API currently recognises two broad types of + address. The first is an address that resolves to + a queue, the second is an address that + resolves to a topicThe + terms queue + and topic here were chosen to align well + with their meaning in JMS. These two addressing 'patterns', + queue and topic, are sometimes refered as point-to-point and + publish-subscribe.. There are two key differences + in behaviour between these two types of address. The first + difference is that a queue will store messages sent to it + until a receiver wants that message, whereas a topic will in + general discard a message for which there is no interested + receiver at the time the message is sent. The second + difference is that multiple receivers on a queue will in + general compete for the messages sent to that queue, that is + each message will go to one receiver only. By contrast each of + multiple receivers for a topic may receive the same message. + - private void runTest() { - try { - Properties properties = new Properties(); - properties.load(this.getClass().getResourceAsStream("hello.properties")); - Context context = new InitialContext(properties); + + We can see the different message flows here, and how they + are independent of the application code, by an example. This + example, and indeed those in the following sections, send + messages using drain, and receive messages + using spout. The source code for + drain and spout is available + in both C++ and Python, and can be found in the examples directory + for each language. These programs can use any address string as a source + or a destination, and have many command line options to configure + behavior—use the -h option for + documentation on these options. + - ConnectionFactory connectionFactory = (ConnectionFactory) context.lookup("qpidConnectionfactory"); - Connection connection = connectionFactory.createConnection(); - connection.start(); + + In the AMQP 0-10 implementation of the API The + only implementation of the API there is at + present. queue addresses specify the name of + the AMQP queue while topic addresses specify the name of an + exchange. We can use the + qpid-config utility to configure AMQP 0-10 + queues and exchanges on a Qpid broker to demonstrate the + behaviour of the different types of address. + - Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE); - Destination destination = (Destination) context.lookup("topicExchange"); - MessageProducer messageProducer = session.createProducer(destination); - MessageConsumer messageConsumer = session.createConsumer(destination); + + Queues and Topics + + Create a queue with qpid-config, send a message using + spout, and read it using drain: + + + $ qpid-config add queue hello-world + $ ./spout -a hello-world + $ ./drain -a hello-world + + Message(properties={spout-id:c877e622-d57b-4df2-bf3e-6014c68da0ea:0}, content='') + + + The queue stored the message we sent and delivered it to + drain when requested. If we now delete the queue named + hello-world and create an exchange with the + same name, we can observe different behaviour: + + + $ qpid-config del queue hello-world + $ qpid-config add exchange topic hello-world + $ ./spout -a hello-world + $ ./drain -a hello-world + $ + + + As hello-world now resolves to an exchange, i.e. to a + topic address, the message is not stored. On receiving a message + for which there are no interested receivers, the exchange + discards the message. When drain was then run there were no + messages to deliver and so 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. - TextMessage message = session.createTextMessage("Hello world!"); - messageProducer.send(message); + + + First Window: - message = (TextMessage)messageConsumer.receive(); - System.out.println(message.getText()); + + $ ./drain -a hello-word -t 30 + + - connection.close(); - context.close(); - } - catch (Exception exp) { - exp.printStackTrace(); - } - } -} -]]> + Second Window: -
+ + $ ./spout -a hello-word + -
- Address Strings + Once spout has sent a message, return + to the first window to see the output from + drain: - As we have seen, an address is a string that identifies - objects on the messaging broker. An address - is simply a name. + + Message(properties={spout-id:7da2d27d-93e6-4803-8a61-536d87b8d93f:0}, content='') + - An address string can also have a - subject and - options. + You can run drain in several separate + windows; each will create a subscription for the exchange, and + each will receive all messages sent to the exchange. - The syntax for an address string is: + - [ / ] [ ; ] + In addition to naming a target or a source for messages, + an address string can also contain a + subject and + options. + + The syntax for an address string is: + + [ / ] [ ; ] options ::= { : , ... } ]]> - - Addresses, subjects, and keys are strings. - - Values can be numbers, strings (with optional single or double quotes), maps, or lists. - - In most cases, queues, bindings, and exchanges are - configured externally with management tools. Qpid Messaging API - clients send to and receive from these queues and exchanges. - - In AMQP 0-10, messages are sent to exchanges, and received - from queues. The Qpid Messaging API allows programs to - send to or receive from any node. To make this possible, the - mapping defines the semantics of sending and receiving for all - AMQP 0-10 exchange types and queues as follows: - - - When a Sender sends a message to an exchange, - the transfer destination is set to the exchange name, and the - routing key is set to the value of the address string's - subject. - When a Receiver receives messages from an - exchange, the API automatically creates a subscription queue and - binds it to the exchange. If the address string contains a subject, - then it is used as the binding key. If the address string does not - contain a subject, then the binding key depends on the exchange - type: - - topic exchange: wildcard match - direct exchange: error — the address string must specify a subject - fanout: none - - The subscription queue's durability - and autodelete properties can be set - using options. - - When a Sender sends a message to a queue, the - message is sent to the AQMP 0-10 default queue, using the name - of the queue as the routing key. - When a Receiver receives messages from a queue, - it is treated as a normal AMQP 0-10 queue subscription. The - accept-mode property can be set using - options. - - - - The following sections describe the various kinds of - address strings in detail. The examples in these sections use the - qpid-config utility to configure AMQP 0-10 - queues and exchanges, send messages using - drain, and receive messages using - spout. The source code for - drain and spout is available - in both C++ and Python, and can be found in the examples directory - for each language. These programs can use any address string as a source - or a destination, and have many command line options to configure - behavior—use the -h option for - documentation on these options. - - -
- Simple Address Strings - - If an address string contains only a name, it is the address - of a named node. On AMQP 0-10, a named node maps to a queue or an - exchange with the same name. - - Address resolution is not yet well-defined if a queue and - an exchange have the same name. This is a known problem, and is - being resolved. - - - For many applications, there is no need to use anything more - complex than a simple address string. - - - Simple Address Strings - - Create a queue with qpid-config, send a message using - spout, and read it using drain: - - -$ qpid-config add queue hello-world -$ ./spout -a hello-world -$ ./drain -a hello-world - -Message(properties={spout-id:c877e622-d57b-4df2-bf3e-6014c68da0ea:0}, content='') - - - Exchanges and queues are addressed in exactly the same way - in the Qpid Messaging API. If we delete the queue named - hello-world and create an exchange with the - same name, we can write to and read from the exchange in the - same way as for the queue: - - -$ qpid-config del queue hello-world -$ qpid-config add exchange topic hello-world -$ ./spout -a hello-world -$ ./drain -a hello-world -$ - - - 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. - - - First Window: - - -$ ./drain -a hello-word -t 30 - + Addresses, subjects, and keys are strings. + Values can be numbers, strings (with optional single or + double quotes), maps, or lists. - Second Window: - - -$ ./spout -a hello-word - - - Once spout has sent a message, return - to the first window to see the output from - drain: - - -Message(properties={spout-id:7da2d27d-93e6-4803-8a61-536d87b8d93f:0}, content='') - - - You can run drain in several separate - windows; each will create a subscription for the exchange, and - each will receive all messages sent to the exchange. - - -
- -
- Subjects - 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. + + Subjects are used to classify messages. When an address is used as + a target for a sender, any subject specified in the address is + used as the default subject of outgoing messages for that + target. When an address is used as a source for a receiver, any + subject specified is treated as an indication of the set of + messages of interest, the details of how this works depend on the + exact configuration of the source. - 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. + + At present if the source address is a queue, then the + subject is not used by any receiver created for that + address. Filtering by subject is only supported for topics + and varies depending on the type of exchange used to + represent the topic. + -
- 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 Qpid Messaging 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, + + Using subjects + + In this example we will show how use of subjects can + affect the message flow. + + First lets create a topic address. Recall from above + that this means an exchange in the AMQP model. We will again + use qpid-config to create oneIn AMQP there are + different types of exchange. One type is called + a topic exchange. This is a slightly + different use of the term topic from that we introduced + earlier. This is indeed a little confusing but we have + prefered to alig the terminology used by the Qpid messaging + API with the more commonly understood meaning of topic + (e.g. as in JMS).. + + $ qpid-config add exchange topic news-service + + + Now we will use drain to receive messages from this + address using a particular subject. + First Window: + + $ ./drain -a news-service/sports -t 30 + + + In a second window, let's send messages to this address: + + Second Window: + + $ ./spout -a news-service/sports + $ ./spout -a news-service/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. + + The exchange type we are using here offers a more + sophisticated matching if desired. The subject can contain + multiple words separated by a . + delimiter. For instance, in a news application, messages + might be sent with subjects + like 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.weather. The subject (or more + properly in this context subject pattern) used in the source + address for a receiver can then include wildcard + characters— # matches one or more words + in the message's subject, * matches a single + word. For instance, if the subject in the source address + is *.news, it matches messages with the + subject europe.news or + usa.news; if it is europe.#, it matches messages with subjects like europe.news or europe.pseudo.news. + + Let's try this out using drain and spout. This time, + let's use two-word keys. - 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='') - + First Window: + + $ ./drain -a news-service/*.news -t 30 + - 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 + The drain program uses the subject *.news to listen for messages in which the second word of the key is - news: + news. Now let's send messages using + several different two-word keys: + Second Window: - First Window: + + $ ./spout -a news-service/usa.news + $ ./spout -a news-service/usa.sports + $ ./spout -a news-service/europe.sports + $ ./spout -a news-service/europe.news + - -$ ./drain -a topic-exchange/*.news -t 30 - - - Now let's send messages using several different - two-word keys: - - Second Window: - - -$ ./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 + 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='') - + + 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: + Finally, let's use the # wildcard to + match any number of words in the key. - First Window: + First Window: - -$ ./drain -a topic-exchange/#.news -t 30 - + + $ ./drain -a news-service/#.news -t 30 + - Now let's send messages using a variety of different + Now let's send messages using a variety of different multi-word keys: - Second Window: + 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 - + + $ ./spout -a news-service/news + $ ./spout -a news-service/sports + $ ./spout -a news-service/usa.news + $ ./spout -a news-service/usa.sports + $ ./spout -a news-service/usa.faux.news + $ ./spout -a news-service/usa.faux.sports + - Now look at the first window, and you will see the + 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. + + 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='') + + - 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. - - Second Window: - - -$ ./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. - - - -
- -
- - -
- Extended Address Options - - Extended Address Options are parameters that affect the behavior of Senders and Receivers. - - Some of these options specify aspects of the resolution process; for instance, they may make assertions that must be satisfied in order for resolution to succeed, or they may state that the node should be created if it does not already exist. - - Let's use drain and spout to show how this works. First, let's use the assert option to insist that an address must resolve to a queue. In the Qpid Messaging API, a node is either a queue or a topic. A queue is used the same way as in AMQP 0-10, a topic node is the same thing AMQP 0-10 calls an exchange. (In this section, we will use the term topic node for a Qpid Messaging API topic node, and AMQP 0-10 topic exchange for the exchange type that has the same name.) + + More detail on the handling of subjects with AMQP 0-10 is + presented in the section on the AMQP 0-10 mapping. Let's now + turn our attention to the third and final component of an + address string, the options map. + - AMQP 0-10 has several built-in exchanges that are predeclared: amq.topic, amq.direct, amq.match, and amq.fanout. In the Qpid Messaging API, any of these exchanges is considered a topic node. Let's use drain, and assert that amq.fanout is a topic node: + + The options map contains additional information about the + address including: + + + + + policies for asserting facts about the node to which an address refers + + + + + policies for automatically creating, and deleting the node to which an address refers + + + + + extension points that can be used for sender/receiver configuration + + + - $ ./drain -a "amq.fanout; { assert: always, node: { type: topic }}" + + Let's use drain and spout + to show some options in action. + + + + First, let's use the assert option to + ensure that the address resolves to a node of the required + type. Recall that in the Qpid Messaging API, an address may + resolve to a queue or a topic + Queue here means the same as it does in AMQP + 0-10. Topic is used to describe a publish-subscribe based + addressing scheme and resolves to what AMQP 0-10 calls an + exchange.. We use qpid-config to create a + queue and an topic. + - The address resolves succesfully. No exception is raised, because a topic node named amq.fanout exists. Now let's assert that amq.fanout is a queue node: + + $ qpid-config add queue my-queue + $ qpid-config add exchange topic my-topic + + + + We can now use the address specified to drain to assert that it is + of a particular type: + - $ ./drain -a "amq.fanout; { assert: always, node: { type: queue }}" -2010-04-09 14:01:35 warning Exception received from broker: not-found: not-found: Queue not found: amq.fanout (qpid/broker/SessionAdapter.cpp:753) [caused by 0 \x08:\x01] -Queue amq.fanout does not exist + + $ ./drain -a 'my-queue; {assert: always, node:{ type: queue }}' + $ ./drain -a 'my-queue; {assert: always, node:{ type: topic }}' + 2010-04-20 17:30:46 warning Exception received from broker: not-found: not-found: Exchange not found: my-queue (../../src/qpid/broker/ExchangeRegistry.cpp:92) [caused by 2 \x07:\x01] + Exchange my-queue does not exist + - An exception was raised because there is no queue named amq.fanout, so address resolution failed. + + The first attempt passed without error as my-queue is indeed a + queue. The second attempt however failed; my-queue is not a + topic. + + + + We can do the same thing for my-topic: + + + $ ./drain -a 'my-topic; {assert: always, node:{ type: topic }}' + $ ./drain -a 'my-topic; {assert: always, node:{ type: queue }}' + 2010-04-20 17:31:01 warning Exception received from broker: not-found: not-found: Queue not found: my-topic (../../src/qpid/broker/SessionAdapter.cpp:754) [caused by 1 \x08:\x01] + Queue my-topic does not exist + Now let's use the create option with drain, telling it to create the queue xoxox if it does not already exist: @@ -732,521 +572,836 @@ Queue amq.fanout does not exist In previous examples, we created the queue before listening for messages on it. Using create: always, the queue is automatically created if it does not exist. Now we can send messages to this queue: Second Window: - $ ./drain -a "xoxox ; {create: always}" -t 30 + $ ./spout -a "xoxox ; {create: always}" Returning to the first window, we see that drain has received this message: Message(properties={spout-id:1a1a3842-1a8b-4f88-8940-b4096e615a7d:0}, content='') - - - - Other options specify message transfer semantics; for instance, they may state whether messages should be consumed or read in browsing mode, or specify reliability characteristics. For instance, we can use browse mode to receive messages without removing them from the queue, thus allowing other Readers to receive them: - - -$ ./drain 'hello-queue; {mode: browse}' - - - + + + Other options specify message transfer semantics; for + instance, they may state whether messages should be consumed or + read in browsing mode, or specify reliability characteristics. + + + Browsing a queue + + Let's use the browse mode to receive messages without + removing them from the queue. First we send three messages to the + queue: + + + $ ./spout -a my-queue --content one + $ ./spout -a my-queue --content two + $ ./spout -a my-queue --content three + + + Now we use drain to get those messages, but specify the browse option: + + $ ./drain -a 'my-queue; {mode: browse}' + Message(properties={spout-id:fbb93f30-0e82-4b6d-8c1d-be60eb132530:0}, content='one') + Message(properties={spout-id:ab9e7c31-19b0-4455-8976-34abe83edc5f:0}, content='two') + Message(properties={spout-id:ea75d64d-ea37-47f9-96a9-d38e01c97925:0}, content='three') + + + We can confirm the messages are still on the queue my repeating the drain: + + $ ./drain -a 'my-queue; {mode: browse}' + Message(properties={spout-id:fbb93f30-0e82-4b6d-8c1d-be60eb132530:0}, content='one') + Message(properties={spout-id:ab9e7c31-19b0-4455-8976-34abe83edc5f:0}, content='two') + Message(properties={spout-id:ea75d64d-ea37-47f9-96a9-d38e01c97925:0}, content='three') + + + + - Extended Address Options - - + Address Options + + option - parameters + value semantics - - + + - assert + assert - node + one of: always, never, sender or receiver - Asserts that the node properties are satisfied for a - node. If they are not, node resolution fails and an - exception is raised. + Asserts that the properties specified in the node option + match whatever the address resolves to. If they don't, + resolution fails and an exception is raised. - create + create - node (optional) + one of: always, never, sender or receiver - Creates the node if it does not exist. No error is raised if the node does exist. + Creates the node to which an address refers if it does + not exist. No error is raised if the node does + exist. The details of the node may be specified in the + node option. - delete + delete - N/A + one of: always, never, sender or receiver - Delete the node when the Sender or Receiver is closed. + Delete the node when the sender or receiver is closed. - reliability + node - unreliable, at-least-once, at-most-once, exactly-once + A nested map the valid entries in which are described by + the node properties table below. + Specifies properties of the node to which the address + refers. These are used in conjunction with the assert or + create options. - mode + link - browse, consume + A nested map the valid entries in which are described by + the link properties table below. + Used to control the establishment of a conceptual link + from the client application to or from the target/source + address. - reconnect + mode - True, False + one of: browse, consume - Transparently reconnect if the connection is lost. + This option is only of relevance for source addresses + that resolve to a queue. If browse is specified the + messages delivered to the receiver are left on the queue + rather than being removed. If consume is specified the + normal behaviour applies; messages are removed from teh + queue once the client acknoweldges their receipt. + + +
+ + + + Node Properties + + - - reconnect_timeout - - - N - - - Total number of seconds to continue reconnection attempts before giving up and raising an exception. - + property + value + semantics + + - reconnect_limit + type - N + topic, queue - Maximum number of reconnection attempts before giving up and raising an exception. - reconnect_interval_min - + durable + - N + True, False - Minimum number of seconds between reconnection attempts. The first reconnection attempt is made immediately; if that fails, the first reconnection delay is set to the value of reconnect_interval_min; if that attempt fails, the reconnection interval increases exponentially until a reconnection attempt succeeds or reconnect_interval_max is reached. + Indicates whether the node will survive a loss of + volatile storage e.g. if the broker is restarted. - reconnect_interval_max + x-declare - N + A nested map whose values correspond to the valid fields + on an AMQP 0-10 queue-declare or exchange-declare + command. - Maximum reconnection interval. + These values are used to fine tune the creation or + assertion process. Note however that they are protocol + specific. - reconnection_interval + x-bindings - N + A nested list each of whose entries is a map that may + contain fields (queue, exchange, key and arguments) + describing an AMQP 0-10 binding. - Sets both reconnection_interval_min and reconnection_interval_max to the same value. + In conjunction with the create option, each of these + bindings will be established as the address is + resolved. In conjunction with the assert option, the + existence of each of these bindings will be verified + during resolution. Again, these are protocol specific. - - + +
- - Node Properties - - + Link Properties + + - property - parameters + option + value semantics - - + + - type + reliability - topic, queue + one of: unreliable, at-least-once, at-most-once, exactly-once - durable + durable - True, False + True, False + Indicates whether the link will survive a loss of + volatile storage e.g. if the broker is restarted. - x-declare + x-declare - unrestricted map + A nested map whose values correspond to the valid fields + on an AMQP 0-10 queue-declare command. - If the property is defined in the underlying protocol (AMQP 0-10), the values and semantics are defined by the protocol. Otherwise, values are added to the arguments map used to declare topicsThe Qpid Messaging API, like Java JMS, uses the term topic to refer to what AMQP 0-10 calls an exchange. One kind of AMQP 0-10 exchange is called a topic exchange, that is not what is meant here. or queues. + These values can be used to customise the subscription + queue in the case of receiving from an exchange. Note + however that they are protocol specific. - - -
- - - - - x-declare properties for AMQP 0-10 - - - - property - parameters - semantics - - - - type + x-subscribe - direct, topic, fanout, header, xml + A nested map whose values correspond to the valid fields + on an AMQP 0-10 message-subscribe command. - The AMQP 0-10 exchange type. + These values can be used to customise the subscription. - bindings + x-bindings - ["exchange/binding-key", ... ] + A nested list each of whose entries is a map that may + contain fields (queue, exchange, key and arguments) + describing an AMQP 0-10 binding. - This property is used to create bindings for queues. If the Address does not resolve to a queue, an error is raised. + These bindings will be established during resolution + independent of the create option. They are considered + logically part of the linking process rathe rthan of + node creation. - - -
- - -
- - -
- Messaging Properties - - This section shows how Qpid Messaging API message - properties are mapped to AMQP message properties and delivery - properties. - - Request-response applications frequently use a reply-to property to tell a server where to send a response. The following C++ code shows how a server extracts the reply-to property and uses it to set the address to respond to a client. - - -Message request = receiver.fetch(); -const Address& address = request.getReplyTo(); // Get "reply-to" from request ... -if (address) { - Sender sender = session.createSender(address); // ... send response to "reply-to" - std::string s = request.getContent(); - std::transform(s.begin(), s.end(), s.begin(), toupper); - Message response(s); - sender.send(response); - session.acknowledge(); -} - - - In the following table, msg refers to the - Message class defined in the Qpid Messaging API, - mp refers to an AMQP 0-10 - message-properties struct, and - dp refers to an AMQP 0-10 - delivery-properties struct. - - - Mapping to AMQP 0-10 Message Properties - - - - Python API - C++ API - AMQP 0-10 Property - - - - - msg.idmsg.{get,set}MessageId()mp.message_id - - - msg.to- -mp.application_headers["qpid.to"] - - - msg.subjectmsg.{get,set}Subject()mp.application_headers["qpid.subject"] - - - msg.user_idmsg.{get,set}UserId()mp.user_id - - - msg.reply_tomsg.{get,set}ReplyTo()mp.reply_toThe reply_to is converted from the protocol representation into an address. - - - msg.correlation_idmsg.{get,set}CorrelationId()mp.correlation_id - - - msg.durablemsg.{get,set}Durable()dp.delivery_mode == delivery_mode.persistentNote that msg.durable is a boolean, not an enum. - - - msg.prioritymsg.{get,set}Priority()dp.priority - - - msg.ttlmsg.{get,set}Ttl()dp.ttl - - - msg.redeliveredmsg.isRedelivered()dp.redelivered - - msg.propertiesmsg.{get,set}Headers()mp.application_headers - - - msg.content_typemsg.{get,set}ContentType()mp.content_type - - - -
- - - -
-
- Apache Qpid JNDI Properties for AMQP Messaging - - - Apache Qpid defines JNDI properties that can be used to - specify the parameters for a connection. Here is a typical JNDI properties file: - - java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory - -# register some connection factories -# connectionfactory.[jndiname] = [ConnectionURL] -connectionfactory.qpidConnectionfactory - = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672' - -# Register an AMQP destination in JNDI -# destination.[jndiName] = [Address] -destination.directQueue - = direct://amq.direct//message_queue?routingkey='routing_key' - + + + - The following sections describe the JNDI properties that Qpid uses. +
-
- JNDI Properties for Apache Qpid - - Apache Qpid supports the properties shown in the following table: - + Reconnect/Failover - JNDI Properties supported by Apache Qpid - - + Connection properties + + - - Property - - - Purpose - + property + value + semantics - - + + - connectionfactory.<jndiname> + reconnect - - The Connection URL that the connection factory will use to perform connections. - - - - - - queue.<jndiname> + True, False - - A JMS queue, which is implemented as an amq.direct exchange in Apache Qpid. - + Transparently reconnect if the connection is lost. - topic.<jndiname> - - - - A JMS topic, which is implemented as an amq.topic exchange in Apache Qpid. - + reconnect_timeout - - - destination.<jndiname> + N - - Can be used for defining all amq destinations, queues, topics and header matching, using an address string. - + Total number of seconds to continue reconnection attempts before giving up and raising an exception. - - -
-
- -
- Connection URLs - - In JNDI properties, a Connection URL specifies properties for a connection. The format for a Connection URL is: - - - amqp://[<user>:<pass>@][<clientid>]<virtualhost>[?<option>='<value>'[&<option>='<value>']] - - - For instance, the following Connection URL specifies a user name, a password, a client ID, a virtual host ("test"), a broker list with a single broker, and a TCP host with the host name localhost using port 5672: - - - amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672' - - - Apache Qpid supports the following properties in Connection URLs: - - - Connection URL Properties - - - Option + reconnect_limit - Type + N - Description + Maximum number of reconnection attempts before giving up and raising an exception. - - - brokerlist + reconnect_interval_min - see below + N - The broker to use for this connection. In the current release, precisely one broker must be specified. + Minimum number of seconds between reconnection attempts. The first reconnection attempt is made immediately; if that fails, the first reconnection delay is set to the value of reconnect_interval_min; if that attempt fails, the reconnection interval increases exponentially until a reconnection attempt succeeds or reconnect_interval_max is reached. - maxprefetch + reconnect_interval_max - -- + N - The maximum number of pre-fetched messages per destination. + Maximum reconnection interval. - sync_persistence + reconnection_interval - false + N - When true, a sync command is sent after every persistent message to guarantee that it has been received. + Sets both reconnection_interval_min and reconnection_interval_max to the same value. - - + +
+
+
+ The AMQP 0-10 mapping in more detail + - Broker lists are specified using a URL in this format: + The interaction with the broker triggered by creating a sender + or receiver depends on what the specified address resolves + to. Where the node type is not specified in the address, the + client queries the broker to determine whether it refers to a + queue or an exchange. - - brokerlist=<transport>://<host>[:<port>] - - For instance, this is a typical broker list: + When sending to a queue, the queue's name is set as the + routing key and the message is transfered to the default (or + nameless) exchange. When sending to an exchange, the message + is transfered to that exchange and the routing key is set to + the message subject if one is specified. A default subject may + be specified in the target address. The subject may also be + set on each message individually to override the default if + required. In each case any specified subject is also added as + a qpid.subject entry in the application-headers field of the + message-properties. + + + When receiving from a queue, any subject in the source address + is currently ignored. The client sends a message-subscribe + request for the queue in question. The accept-mode is + determined by the reliability option in the link properties; + for unreliable links the accept-mode is none, for reliable + links it is explicit. The default for a queue is reliable. The + acquire-mode is determined by the value of the mode option. If + the mode is set to browse the acquire mode is not-acquired, + otherwise it is set to pre-acquired. The exclusive and + arguments fields in the message-subscribe command can be + controlled using the x-subscribe map. + + + When receiving from an exchange, the client creates a + subscription queue and binds that to the exchange. The + subscription queue's arguments can be specified using the + x-declare map within the link properties. The reliability + option determines most of the other parameters. If the + reliability is set to unreliable then an auto-deleted, + exclusive queue is used meaning that if the client or + connection fails messages may be lost. For exactly-once the + queue is not set to be auto-deleted. The durability of the + subscription queue is determined by the durable option in the + link properties. The binding process depends on the type of + the exchange the source address resolves to. + + + + + + For a topic exchange, if no subject is specified and no + x-bindings are defined for the link, the subscription + queue will by be bound using a wildcard matching any + routing key (thus satisfying the expectation that any + message sent to that address will be received from it). If + a subject is specified in the source address however, it + will be used for the binding key (this means that the + subject in the source address may be a binding pattern + incuding wildcards). + + + + + For a fanout exchange the binding key is irrelevant to + matching. A receiver created from a source address that + resolves to a fanout exchange will receive all messages + sent to that exchange regardless of any subject the source + address may contain. An x-bindings element in the link + properties should be used if there is any need to set the + arguments to the bind. + + + + + A source address that resolves to a direct exchange must + either contain a subject or must include a value for the + x-bindings option in the link properties. This is because + there is no way to receive all messages sent to an + exchange of that type. The subject specified will be used + as the binding key (this means it must match the message + subject exactly). + + + + + For a headers exchange, if no subject is specified the + binding arguments will simply contain an x-match entry an + no other entries, causing all messages to match. If a + subject is specified then the binding arguments will + contain an x-match entry set to all and an entry for + qpid.subject whose value is the subject in the source + address (this means the subject in the source address must + match the message subject exactly). For more control the + x-bindings element in the link properties must be used. + + + + + For the XML exchangeNote that the XML + exchange is not a standard AMQP exchange type. It is a + Qpid extension and is currently only supported by the c++ + broker. if a subject is specified it is + used as the bidning key and an xquery is defined that will + match any message with that value for qpid.subject. Again + this means that only messages whose subject exactly match + that specified in the source address will be received. For + more control the x-bindings element in the link properties + must be used. A source address that resolves to the XML + exchange must contain either a subject or an x-bindings + element in the link properties as there is no way at + present to receive any message regardless of routing key. + + + + + + If an x-bindings list is present in the link options a binding + is created for each element within that list. Each element is + a nested map that may contain values named queue, exchange, + key or arguments. If the queue value is absent the queue name + the address resolves to is implied. If the exchange value is + absent the exchange name the address resolves to is implied. + + The following table shows how Qpid Messaging API message + properties are mapped to AMQP 0-10 message properties and + delivery properties. In this table msg + refers to the Message class defined in the Qpid Messaging API, + mp refers to an AMQP 0-10 + message-properties struct, and + dp refers to an AMQP 0-10 + delivery-properties struct. + + + Mapping to AMQP 0-10 Message Properties + + + + Python API + C++ API + AMQP 0-10 Property + + + + + msg.idmsg.{get,set}MessageId()mp.message_id + + + msg.subjectmsg.{get,set}Subject()mp.application_headers["qpid.subject"] + + + msg.user_idmsg.{get,set}UserId()mp.user_id + + + msg.reply_tomsg.{get,set}ReplyTo()mp.reply_toThe reply_to is converted from the protocol representation into an address. + + + msg.correlation_idmsg.{get,set}CorrelationId()mp.correlation_id + + + msg.durablemsg.{get,set}Durable()dp.delivery_mode == delivery_mode.persistentNote that msg.durable is a boolean, not an enum. + + + msg.prioritymsg.{get,set}Priority()dp.priority + + + msg.ttlmsg.{get,set}Ttl()dp.ttl + + + msg.redeliveredmsg.{get,set}Redelivered()dp.redelivered + + msg.propertiesmsg.{get,set}Properties()mp.application_headers + + + msg.content_typemsg.{get,set}ContentType()mp.content_type + + + +
- brokerlist='tcp://localhost:5672' -
-
+ + +
+ Using the Qpid JMS client +
+ A Simple Messaging Program in Java JMS + + The following program shows how to use address strings and + JNDI for Qpid programs that use Java JMS. + + This program uses a JNDI file that defines a connection + factory for the broker we are using, and the address of the topic + exchange node that we will bind the sender and receiver to. (The + syntax of a ConnectionURL is given in .) + + + + In the Java JMS code, we use create a JNDI context, use the context to find a connection factory and create and start a connection, create a session, and create a destination that corresponds to the topic exchange. Then we create a sender and a receiver, send a message with the sender, and receive it with the receiver. This code should be straightforward for anyone familiar with Java JMS. + + + +
+ +
+ Apache Qpid JNDI Properties for AMQP Messaging + + + Apache Qpid defines JNDI properties that can be used to + specify the parameters for a connection. Here is a typical JNDI properties file: + + java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory + + # register some connection factories + # connectionfactory.[jndiname] = [ConnectionURL] + connectionfactory.qpidConnectionfactory + = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672' + + # Register an AMQP destination in JNDI + # destination.[jndiName] = [Address] + destination.directQueue + = direct://amq.direct//message_queue?routingkey='routing_key' + + + The following sections describe the JNDI properties that Qpid uses. + + +
+ JNDI Properties for Apache Qpid + + Apache Qpid supports the properties shown in the following table: + + + JNDI Properties supported by Apache Qpid + + + + + Property + + + Purpose + + + + + + + connectionfactory.<jndiname> + + + + The Connection URL that the connection factory will use to perform connections. + + + + + + queue.<jndiname> + + + + A JMS queue, which is implemented as an amq.direct exchange in Apache Qpid. + + + + + + topic.<jndiname> + + + + A JMS topic, which is implemented as an amq.topic exchange in Apache Qpid. + + + + + + destination.<jndiname> + + + + Can be used for defining all amq destinations, queues, topics and header matching, using an address string. + + + + + +
+
+ +
+ Connection URLs + + In JNDI properties, a Connection URL specifies properties for a connection. The format for a Connection URL is: + + + amqp://[<user>:<pass>@][<clientid>]<virtualhost>[?<option>='<value>'[&<option>='<value>']] + + + For instance, the following Connection URL specifies a user name, a password, a client ID, a virtual host ("test"), a broker list with a single broker, and a TCP host with the host name localhost using port 5672: + + + amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672' + + + Apache Qpid supports the following properties in Connection URLs: + + + Connection URL Properties + + + + + Option + + + Type + + + Description + + + + + + + brokerlist + + + see below + + + The broker to use for this connection. In the current release, precisely one broker must be specified. + + + + + maxprefetch + + + -- + + + The maximum number of pre-fetched messages per destination. + + + + + sync_persistence + + + false + + + When true, a sync command is sent after every persistent message to guarantee that it has been received. + + + + +
+ + Broker lists are specified using a URL in this format: + + + brokerlist=<transport>://<host>[:<port>] + + + For instance, this is a typical broker list: + + + brokerlist='tcp://localhost:5672' + +
+
+
+ - client code remains exactly the same, but routing behavior + changes + - exchanges drop messages if nobody is listening, so we need to + start drain first + - drain will exit immediately if the source is empty (note that + this is actually a semantic guarantee provided by the API, we + know for a fact that the source is empty when drain/fetch + reports it, no fudge factor timeout is required [this assumes + nobody is concurrently publishing of course]) + - drain -f invokes blocking fetch (you could use a timeout here also) + --> -- cgit v1.2.1