From 443d264e9c682d09502940ecd52cc308b100bbe9 Mon Sep 17 00:00:00 2001 From: Jonathan Robie Date: Mon, 3 May 2010 19:47:36 +0000 Subject: Renamed to "Programming In Apache Qpid". git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@940588 13f79535-47bb-0310-9956-ffa450edef68 --- qpid/doc/book/src/High-Level-API.xml | 2497 ---------------------- qpid/doc/book/src/Programming-In-Apache-Qpid.xml | 2497 ++++++++++++++++++++++ qpid/doc/book/src/schemas.xml | 2 + 3 files changed, 2499 insertions(+), 2497 deletions(-) delete mode 100644 qpid/doc/book/src/High-Level-API.xml create mode 100644 qpid/doc/book/src/Programming-In-Apache-Qpid.xml (limited to 'qpid') diff --git a/qpid/doc/book/src/High-Level-API.xml b/qpid/doc/book/src/High-Level-API.xml deleted file mode 100644 index c0256a4bb2..0000000000 --- a/qpid/doc/book/src/High-Level-API.xml +++ /dev/null @@ -1,2497 +0,0 @@ - - - - - - - Programming in Apache Qpid - Cross-Platform AMQP Messaging in Java JMS, .NET, C++, and Python - -
- Supported APIs - - Apache Qpid is a reliable, asynchronous messaging system that - supports the AMQP messaging protocol in several common programming - languages. Qpid is supported on most common platforms. - - - - - - On the Java platform, Qpid uses the - established Java JMS - API. - - - - - On the .NET platform, Qpid defines - a WCF - binding. - - - - - For Python and C++, Qpid defines its own messaging API, the - Qpid Messaging API, which is - conceptually similar in each supported language. - - - - - Support for this API in Ruby will be added - soon - Ruby currently uses an API that is closely - tied to the AMQP version.. - - - -
- -
- Using the Qpid Messaging API - - The Qpid Messaging API is quite simple, consisting of only a - handful of core classes. - - - - - - - A message consists of a standard set - of fields (e.g. subject, - reply-to), an application-defined set of - properties, and message content (the main body of the - message). - - - - - - A connection represents a network - connection to a remote endpoint. - - - - - - A session provides a sequentially - ordered context for sending and receiving - messages. A session is obtained from a - connection. - - - - - - A sender sends messages to a target - using the sender.send method. A sender is - obtained from a session for a given target address. - - - - - - A receiver receives messages from a - source using the receiver.fetch method. - A receiver is obtained from a session for a given source - address. - - - - - - - The following sections show how to use these classes in a - simple messaging 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. - - - "Hello world!" in C++ - -#include -#include -#include -#include - -#include - -using namespace qpid::messaging; - -int main(int argc, char** argv) { - std::string broker = argc > 1 ? argv[1] : "localhost:5672"; - std::string address = argc > 2 ? argv[2] : "amq.topic"; - Connection connection(broker); - try { - connection.open(); - Session session = connection.createSession(); - - Receiver receiver = session.createReceiver(address); - Sender sender = session.createSender(address); - - sender.send(Message("Hello world!")); - - Message message = receiver.fetch(Duration::SECOND * 1); - std::cout << message.getContent() << std::endl; - session.acknowledge(); - - connection.close(); - return 0; - } catch(const std::exception& error) { - std::cerr << error.what() << std::endl; - connection.close(); - return 1; - } -}]]> - - - -
- -
- 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. - - - "Hello world!" in Python - - - -
-
- Addresses - - An address is the name of a message - target or message source. In the programs we have just seen, we - used the address amq.topic (which is the name - of an exchange on an AMQP 0-10 messaging broker). - - The methods that create senders and receivers require an - address. The details of sending to a particular target or - receiving from a particular source are then handled by the - sender or receiver. A different target or source can be used - simply by using a different address. - - - An address resolves to a node. The - Qpid Messaging API recognises two kinds of nodes, - queues and topics. - - The terms queue and - topic here were chosen to align with - their meaning in JMS. These two addressing 'patterns', - queue and topic, are sometimes refered as point-to-point - and publish-subscribe. AMQP 0-10 has an exchange type - called a topic exchange. When the term - topic occurs alone, it refers to a - Messaging API topic, not the topic - exchange.. - - A queue stores each message until it has been received and - acknowledged, and only one receiver can receive a given message - There are exceptions to this rule; for instance, - a receiver can use browse mode, which leaves - messages on the queue for other receivers to - read. - - A topic immediately delivers a message to all eligible - receivers; if there are no eligible receivers, it discards the - message. In the AMQP 0-10 implementation of the API, - - The AMQP 0-10 implementation is the only one - that currently exists. - - queues map to AMQP queues, and topics map to AMQP exchanges. - - In AMQP 0-10, messages are sent to - exchanges, and read from queues. The Messaging API also - allows a sender to send messages to a queue; internally, - Qpid implements this by sending the message to the default - exchange, with the name of the queue as the routing key. The - Messaging API also allows a receiver to receive messages - from a topic; internally, Qpid implements this by setting up - a private subscription queue for the receiver and binding - the subscription queue to the exchange that corresponds to - the topic. - - - In the rest of this tutorial, we present many examples - using two programs that take an address as a command line - parameter. spout sends messages to the - target address, drain receives messages from - the source address. The source code 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. - - Currently, the Python and C++ - implementations of drain and - spout have slightly different - options. This tutorial uses the C++ implementation. The - options will be reconciled in the near - future. - - - The examples in this tutorial also use the - qpid-config utility to configure AMQP 0-10 - queues and exchanges on a Qpid broker. - - - - - Queues - - 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 sent by spout and delivered - it to drain when requested. - - Once the message has been delivered and and acknowledged - by drain, it is no longer available on the queue. If we run - drain one more time, no messages will be retrieved. - - -$ ./drain -a hello-world -$ - - - - - - Topics - - This example is similar to the previous example, but it - uses a topic instead of a queue. - - First, use qpid-config to remove the queue - and create an exchange with the same name: - - -$ qpid-config del queue hello-world -$ qpid-config add exchange topic hello-world - - - Now run drain and spout the same way we did in the previous example: - - -$ ./spout -a hello-world -$ ./drain -a hello-world -$ - - - Topics deliver messages immediately to any interested - receiver, and do not store messages. Because there were no - receivers at the time spout sent the - message, it was simply discarded. When we ran - drain, there were no messages to - receive. - - Now let's run drain first, using the - -t option to specify a timeout in seconds. - While drain is waiting for messages, - run spout in another window. - - First Window: - - -$ ./drain -a hello-word -t 30 - - - - 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 creates a subscription for the exchange, and - each receives all messages sent to the exchange. - - - -
- Address Strings - - So far, our examples have used address strings that - contain only the name of a node. 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. A complete BNF for address strings appears in - . - - - So far, the address strings in this tutorial have used - only addresses. The following sections show how to use - subjects and options. - -
- -
- Subjects - - - Every message has a property called - subject, which is analogous to the - subject on an email message. If no subject is specified, the - message's subject is null. For convenience, address strings - also allow a subject. If a sender's address contains a - subject, it is used as the default subject for the messages - it sends. - - If a receiver's address contains a subject, it is used to - select only messages that match the subject—the matching - algorithm depends on the message source. - - - - In AMQP 0-10, each exchange type has its own matching - algorithm, and queues do not provide filtering. This is - discussed in . - - - - - Currently, a receiver bound to a queue ignores subjects, - receiving messages from the queue without filtering. - - In the future, if a receiver is bound to a queue, and its - address contains a subject, the subject will be used as a - selector to filter messages. - - - - - - Using subjects - - In this example we show how subjects affect message - flow. - - First, let's use qpid-config to create a topic exchange. - - -$ qpid-config add exchange topic news-service - - - Now we use drain to receive messages from news-service that match the subject sports. - First Window: - -$ ./drain -a news-service/sports -t 30 - - - In a second window, let's send messages to news-service using two different subjects: - - Second Window: - -$ ./spout -a news-service/sports -$ ./spout -a news-service/news - - - Now look at the first window, 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 AMQP exchange type we are using here, - amq.topic, can also do more sophisticated - matching. - - A sender's subject can contain multiple words separated by a - . delimiter. For instance, in a news - application, the sender might use subjects like - usa.news, usa.weather, - europe.news, or - europe.weather. - - The 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 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. - - - Subjects with multi-word keys - - This example uses drain and spout to demonstrate the - use of subjects with two-word keys. - - Let's use drain with the subject - *.news to listen for messages in which - the second word of the key is - news. - - First Window: - - -$ ./drain -a news-service/*.news -t 30 - - - Now let's send messages using several different - two-word keys: - - Second 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 - - - In the first window, 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='') - - - - Next, let's use drain with the - subject #.news to match any sequence of - words that ends with news. - - First Window: - - -$ ./drain -a news-service/#.news -t 30 - - - In the second window, let's send messages using a - variety of different multi-word keys: - - Second Window: - - -$ ./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 - - - In the first window, 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='') - - - -
- -
- Address String Options - - - The options in an address string contain additional - information for the senders or receivers created for it, - including: - - - - - Policies for assertions about the node to which an address - refers. - - - For instance, in the address string my-queue; - {assert: always, node:{ type: queue }}, the node - named my-queue must be a queue; if not, - the address does not resolve to a node, and an exception - is raised. - - - - - Policies for automatically creating or deleting the node to which an address refers. - - - For instance, in the address string xoxox ; {create: always}, - the queue xoxox is created, if it does - not exist, before the address is resolved. - - - - - Extension points that can be used for sender/receiver configuration. - - - For instance, if the address for a receiver is - my-queue; {mode: browse}, the receiver - works in browse mode, leaving messages - on the queue so other receivers can receive them. - - - - - - - Let's use some examples to show how these different kinds of - address string options affect the behavior of senders and - receives. - - - - - First, let's use the assert option to - ensure that the address resolves to a node of the required - type. - - - - - Assertions on Nodes - - Let's use qpid-config to create a - queue and a topic. - - -$ 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 '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 - - - - 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 to - create the queue xoxox if it does not already - exist: - - - Creating a Queue Automatically - - First Window: - $ ./drain -a "xoxox ; {create: always}" -t 30 - - 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: - $ ./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. The following example uses the - browse option to receive messages without - removing them from a queue. - - - 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, using 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 by 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') - - - - - - - Address String Options - - - - option - value - semantics - - - - - - assert - - - one of: always, never, sender or receiver - - - Asserts that the properties specified in the node option - match whatever the address resolves to. If they do not, - resolution fails and an exception is raised. - - - - - - create - - - one of: always, never, sender or receiver - - - 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 - - - one of: always, never, sender or receiver - - - Delete the node when the sender or receiver is closed. - - - - - node - - - A nested map containing the entries shown in . - - - Specifies properties of the node to which the address - refers. These are used in conjunction with the assert or - create options. - - - - - link - - - A nested map containing the entries shown in . - - - Used to control the establishment of a conceptual link - from the client application to or from the target/source - address. - - - - - mode - - - one of: browse, consume - - - 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 - - - - property - value - semantics - - - - - - type - - - topic, queue - - - - - - - durable - - - True, False - - - Indicates whether the node survives a loss of - volatile storage e.g. if the broker is restarted. - - - - - x-declare - - - A nested map whose values correspond to the valid fields - on an AMQP 0-10 queue-declare or exchange-declare - command. - - - These values are used to fine tune the creation or - assertion process. Note however that they are protocol - specific. - - - - - x-bindings - - - A nested list in which each binding is represented by - a map. The entries of the map for a binding contain - the fields that describe an AMQP 0-10 binding. Here is - the format for x-bindings: - -, - queue: , - key: , - arguments: { : , ..., : } - }, - ... -] -]]> - - - In conjunction with the create option, each of these - bindings is established as the address is resolved. In - conjunction with the assert option, the existence of - each of these bindings is verified during - resolution. Again, these are protocol specific. - - - - -
- - - Link Properties - - - - option - value - semantics - - - - - - reliability - - - one of: unreliable, at-least-once, at-most-once, exactly-once - - - - - - - durable - - - True, False - - - Indicates whether the link survives a loss of - volatile storage e.g. if the broker is restarted. - - - - - x-declare - - - A nested map whose values correspond to the valid fields - of an AMQP 0-10 queue-declare command. - - - 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-subscribe - - - A nested map whose values correspond to the valid fields - of an AMQP 0-10 message-subscribe command. - - - These values can be used to customise the subscription. - - - - - x-bindings - - - 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. - - - These bindings are established during resolution - independent of the create option. They are considered - logically part of the linking process rather than of - node creation. - - - - - - -
- - -
- Address String Grammar - - This section provides a formal grammar for address strings. - - - Tokens - The following regular expressions define the tokens used - to parse address strings: - - - - Grammar - The formal grammar for addresses is given below: - - - - - - - Address String Options - The address string options map supports the following parameters: - - - [ / ] ; { - create: always | sender | receiver | never, - delete: always | sender | receiver | never, - assert: always | sender | receiver | never, - mode: browse | consume, - node: { - type: queue | topic, - durable: True | False, - x-declare: { ... ... }, - x-bindings: [, ... ] - }, - link: { - name: , - durable: True | False, - reliability: unreliable | at-most-once | at-least-once | exactly-once, - x-declare: { ... ... }, - x-bindings: [, ... ], - x-subscribe: { ... ... } - } -} -]]> - - - - Create, Delete, and Assert Policies - The create, delete, and assert policies specify who should - perfom the associated action: - always: the action is performed by any messaging client - sender: the action is only performed by a sender - receiver: the action is only performed by a receiver - never: the action is never performed (this is the default) - - - - Node-Type - The node-type is one of: - topic: in the AMQP 0-10 - mapping, a topic node defaults to the topic exchange, x-declare - may be used to specify other exchange types - queue: this is the default node-type - -
- - -
- -
- Logging - The Qpidd broker and C++ clients can both use environment - variables to enable logging. Use QPID_LOG_ENABLE to set the - level of logging you are interested in (trace, debug, info, - notice, warning, error, or critical): - - -$ export QPID_LOG_ENABLE="warning+" - - - The Qpidd broker and C++ clients use QPID_LOG_OUTPUT to - determine where logging output should be sent. This is either a - file name or the special values stderr, stdout, or syslog: - - -export QPID_LOG_TO_FILE="/tmp/myclient.out" - - -
- - - -
- Reconnect and Failover - Connections in the Qpid Messaging API support automatic - reconnect if a connection is lost. This is done using connection - options. The following example shows how to use connection options in C++ and Python. - - - Specifying Connection Options in C++ and Python - - In C++, these options are set using Connection::setOption(): - - - - In Python, these options are set using named arguments in - the Connection constructor: - - - - See the reference documentation for details on how to set - these on connections for each language. - - - The following table lists the connection options that can - be used. - - - Connection Options - - - - option - value - semantics - - - - - - reconnect - - - True, False - - - Transparently reconnect if the connection is lost. - - - - - reconnect_timeout - - - N - - - Total number of seconds to continue reconnection attempts before giving up and raising an exception. - - - - - reconnect_limit - - - N - - - Maximum number of reconnection attempts before giving up and raising an exception. - - - - - reconnect_interval_min - - - N - - - 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 reconnect interval increases exponentially until a reconnection attempt succeeds or reconnect_interval_max is reached. - - - - - reconnect_interval_max - - - N - - - Maximum reconnect interval. - - - - - reconnect_interval - - - N - - - Sets both reconnection_interval_min and reconnection_interval_max to the same value. - - - - -
-
- -
- Receiving Messages from Multiple Sources - - A receiver can only read from one source, but many - programs need to be able to read messages from many sources, - preserving the original sequence of the messages. In the Qpid - Messaging API, a program can ask a session for the next - receiver; that is, the receiver that is responsible for - the next available message. The following example shows how this - is done in C++ and Python. - - - Receiving Messages from Multiple Sources - - C++: - - - - Python: - - -
- -
- Request / Response - Request / Response applications use the reply-to property, - described in , to allow a server - to respond to the client that sent a message. A server sets up a - service queue, with a name known to clients. A client creates a - private queue for the server's response, creates a message for a - request, sets the request's reply-to property to the address of - the client's response queue, and sends the request to the - service queue. The server sends the response to the address - specified in the request's reply-to property. - - - Request / Response Applications in C++ - - This example shows the C++ code for a client and server - that use the request / response pattern. - - The server creates a service queue and waits for a - message to arrive. If it receives a message, it sends a - message back to the sender. - - - - The client creates a sender for the service queue, and - also creates a response queue that is deleted when the - client closes the receiver for the response queue. In the C++ - client, if the address starts with the character - #, it is given a unique name. - - " << response.getContent() << std::endl; -]]> - - The client sends the string ping to - the server. The server sends the response - pong back to the same client, using the - replyTo property. - - - -
- - - -
- XML Exchange - - The XML Exchange is an AMQP 0-10 custom exchange provided by the Apache Qpid C++ broker. It allows messages to be filtered using XQuery; queries can address either message properties or XML content in the body of the message. - - An instance of the XML Exchange must be added before it can be used: - - -$ qpid-config add exchange xml xml - - - When using the XML exchange, a sender's address string must provide a subject, e.g. xml/weather. - - If a receiver that is using the XML exchange also provides a subject, it receives messages if the subject exactly matches a message's subject. - - - When using the XML Exchange, a receiver normally provides an XQuery as an x-binding argument. If the query contains a context item (a path starting with .), then it is applied to the content of the message, which must be well-formed XML. For instance, ./weather is a valid XQuery, which matches any message in which the root element is named weather. Here is an address string that contains this query: - - - - Note that each x-binding is created in addition to any other bindings that may exist, and each x-binding must include the exchange name, the key, and the xquery. If you specify the subject in the address string (e.g. xml/weather; link ...), it creates a binding that is used in addition to the x-bindings; the binding created for the subject matches any message whose subject is weather, the binding created for the x-binding matches any message that satisfies the query, i.e. any message with a root element named weather. - - - - The XML Exchange can also be used to query message properties by declaring an external variable with the same name as each property that is to be queried. The following XQuery queries the control property, as well as the content of the message: - - - - If the XQuery addresses message content, and the message is not well-formed XML, the message will not be received. If the XQuery does not query message content, the message need not contain XML. - - - - Using the XML Exchange with <command>drain</command> - - The following shows the arguments used with drain to retrieve messages whose root element is named weather: - - - - - - Using the XML Exchange with C++ - - In C++, it is convenient to place an XQuery in a string, and use a stringstream to add the query to the template for an address string that specifies an x-binding. - - 50" - " and $w/temperature_f - $w/dewpoint > 5" - " and $w/wind_speed_mph > 7" - " and $w/wind_speed_mph < 20"; - -stringstream address; - -address << "xml; {" - " link: { " - " x-bindings: [{ exchange: xml, key: weather, arguments: { xquery:\"" - << query - << "\"} }] " - " } " - "}"; - - -Receiver receiver = session.createReceiver(address.str()); -Message response = receiver.fetch(); -session.acknowledge(); -std::cout << response.getContent() << std::endl; - - ]]> - - - - - Using the XML Exchange with Python - - In Python, it is often convenient to place the query in - a separate string, and use the repr() value of the query - string in an address template string. - - 50 - and $w/temperature_f - $w/dewpoint > 5 - and $w/wind_speed_mph > 7 - and $w/wind_speed_mph < 20 """ - - address = """ - xml; { - link: { - x-bindings: [{ exchange: xml, key: weather, arguments: { xquery: %r} }] - } - } - """ % query - - receiver = session.receiver(address) - -# Retrieve matching message from the receiver and print it - - message = receiver.fetch(timeout=1) - print message.content - session.acknowledge() - ]]> - - -
- -
- Performance - - Clients can often be made significantly faster by batching acknowledgements and setting the capacity of receivers to allow prefetch. - -
- Batching Acknowledgements - - Many of the simple examples we have shown retrieve a message and immediately acknowledge it. Because each acknowledgement results in network traffic, you can dramatically increase performance by acknowledging messages in batches. For instance, an application can read a number of related messages, then acknowledge the entire batch, or an application can acknowledge after a certain number of messages have been received or a certain time period has elapsed. Messages are not removed from the broker until they are acknowledged, so guaranteed delivery is still available when batching acknowledgements. -
- - -
- Prefetch - - By default, a receiver retrieves the next message from the server, one message at a time, which provides intuitive results when writing and debugging programs, but does not provide optimum performance. To create an input buffer, set the capacity of the receiver to the size of the desired input buffer; for many applications, a capacity of 100 performs well. - - - - - Prefetch - - C++ - -Receiver receiver = session.createReceiver(address); -receiver.setCapacity(100); -Message message = receiver.fetch(); - - - - -
- -
- -
- Reliability - -
- Guaranteed Delivery - - If a queue is durable, the queue survives a messaging - broker crash, as well as any durable messages that have been - placed on the queue. These messages will be delivered when the - messaging broker is restarted. Delivery is guaranteed if and - only if both the message and the queue are durable. Guaranteed - delivery requires a persistence module, such as the one - available from QpidComponents.org. - - - Guaranteed Delivery - - C++: - - - - - - -
- -
- - - -
- Transactions - In AMQP, transactions cover the semantics of enqueues and - dequeues. - - When sending messages, a transaction tracks enqueues - without actually delivering the messages, a commit places - messages on their queues, and a rollback discards the - enqueues. - - When receiving messages, a transaction tracks dequeues - without actually removing acknowledged messages, a commit - removes all acknowledged messages, and a rollback discards - acknowledgements. A rollback does not release the message, it - must be explicitly released to return it to the queue. - - - Transactions - C++: - - - - -
- - - - - -
- The AMQP 0-10 mapping - - - This section describes the AMQP 0-10 mapping for the Qpid - Messaging API. - - - 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. - - - 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 is 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 is used for - the binding key (this means that the subject in the source - address may be a binding pattern including 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 receives 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 is 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 simply contain an x-match entry and no - other entries, causing all messages to match. If a subject - is specified then the binding arguments 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 exchange,Note 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 binding key and an XQuery is defined that - matches any message with that value for - qpid.subject. Again this means that only messages whose - subject exactly match that specified in the source address - are 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 PropertyIn these entries, mp refers to an AMQP message property, and dp refers to an AMQP delivery 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 - - - -
- -
-
- - -
- 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. - - The Qpid JMS client uses Qpid Messaging API to identify sources and - targets. 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 bind the sender and receiver - to. (The syntax of a ConnectionURL is given in .) - - - JNDI Properties File for "Hello world!" example - - - - 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. - - - "Hello world!" in Java - - - -
- -
- Apache Qpid JNDI Properties for AMQP Messaging - - - - Apache Qpid defines JNDI properties that can be used to specify JMS Connections and Destinations. Here is a typical JNDI properties file: - - - - JNDI Properties File - - - - 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 uses 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. - - Binding URLs, which were used in - earlier versions of the Qpid Java JMS client, can - still be used instead of address - strings. - - - - - -
-
- -
- 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_publish - - - {'persistent' | 'all'} - - - A sync command is sent after every persistent message to guarantee that it has been received; if the value is 'persistent', this is done only for persistent messages. - - - - - sync_ack - - - Boolean - - - A sync command is sent after every acknowledgement to guarantee that it has been received. - - - - - use_legacy_map_msg_format - - - Boolean - - - If you are using JMS Map messages and deploying a new client with any JMS client older than 0.7 release, you must set this to true to ensure the older clients can understand the map message encoding. - - - - - failover - - - {'roundrobin' | 'failover_exchange'} - - - If roundrobin is selected it will try each broker given in the broker list. - If failover_exchange is selected it connects to the initial broker given in the broker URL and will receive membership updates via the failover exchange. - - - - -
- - Broker lists are specified using a URL in this format: - - - brokerlist=<transport>://<host>[:<port>](?<param>=<value>)?(&<param>=<value>)* - - For instance, this is a typical broker list: - - - brokerlist='tcp://localhost:5672' - - - - A broker list can contain more than one broker address; if so, the connection is made to the first broker in the list that is available. In general, it is better to use the failover exchange when using multiple brokers, since it allows applications to fail over if a broker goes down. - - - - Broker Lists - A broker list can specify properties to be used when connecting to the broker, such as security options. This broker list specifies options for a Kerberos connection using GSSAPI: - - - This broker list specifies SSL options: - - - - - The following broker list options are supported. - - - Broker List Options - - - - - Option - - - Type - - - Description - - - - - - - heartbeat - - - integer - - - frequency of heartbeat messages (in seconds) - - - - - sasl_mechs - - - -- - - - For secure applications, we suggest CRAM-MD5, - DIGEST-MD5, or GSSAPI. The ANONYMOUS method is not - secure. The PLAIN method is secure only when used - together with SSL. - For Kerberos, sasl_mechs must be set to GSSAPI, - sasl_protocol must be set to the principal for the qpidd broker, e.g. qpidd/, and - sasl_server must be set to the host for the SASL server, e.g. sasl.com. - SASL External is supported using SSL certification, e.g. - ssl='true'&sasl_mechs='EXTERNAL' - - - - - sasl_encryption - - - Boolean - - - If sasl_encryption='true', the JMS client attempts to negotiate a security layer with the broker using GSSAPI to encrypt the connection. Note that for this to happen, GSSAPI must be selected as the sasl_mech. - - - - - ssl - - - Boolean - - - If ssl='true', the JMS client will encrypt the connection using SSL. - - - - - tcp_nodelay - - - Boolean - - - If tcp_nodelay='true', TCP packet - batching is disabled. - - - - - sasl_protocol - - - -- - - - Used only for - Kerberos. sasl_protocol must be - set to the principal for the qpidd broker, - e.g. qpidd/ - - - - - sasl_server - - - -- - - - For Kerberos, sasl_mechs must be set to GSSAPI, - sasl_server must be set to the host for the SASL - server, e.g. sasl.com. - - - - - trust_store - - - -- - - - path to Keberos trust store - - - - - trust_store_password - - - - - Kerberos trust store password - - - - - key_store - - - - - path to Kerberos key store - - - - - key_store_password - - - -- - - - Kerberos key store password - - - - - ssl_verify_hostname - - - Boolean - - - When using SSL you can enable hostname verification - by using "ssl_verify_hostname=true" in the broker - URL. - - - - - ssl_cert_alias - - - - - - If multiple certificates are present in the keystore, the alias will be used to extract the correct certificate. - - - - -
-
-
- -
- Java JMS Message Properties - - 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. - - - Java JMS Mapping to AMQP 0-10 Message Properties - - - - Java JMS Message Property - AMQP 0-10 PropertyIn these entries, mp refers to an AMQP message property, and dp refers to an AMQP delivery property. - - - - - - JMSMessageIDmp.message_id - - - qpid.subjectThis is a custom JMS property, set automatically by the Java JMS client implementation.mp.application_headers["qpid.subject"] - - - JMSXUserIDmp.user_id - - - JMSReplyTomp.reply_toThe reply_to is converted from the protocol representation into an address. - - - JMSCorrelationIDmp.correlation_id - - - JMSDeliveryModedp.delivery_mode - - - JMSPrioritydp.priority - - - JMSExpirationdp.ttlJMSExpiration = dp.ttl + currentTime - - - JMSRedelivereddp.redelivered - - - JMS Propertiesmp.application_headers - - - JMSTypemp.content_type - - - -
- -
- -
- Java JMS Selector Syntax - The AMQP Java JMS Messaging Client supports the following syntax for JMS selectors. - - - Comments: - - - - - - Reserved Words (case insensitive) - - - - - - Literals (case insensitive) - - )? // eg: 5.5 or 5. or 5.5E10 or 5.E10 - | "." (["0"-"9"])+ ()? // eg: .5 or .5E10 - | (["0"-"9"])+ // eg: 5E10 -) -EXPONENT: "E" (["+","-"])? (["0"-"9"])+ -STRING_LITERAL: "'" ( ("''") | ~["'"] )* "'" -]]> - - - - - Identifiers (case insensitive) - - - - - - - Grammar - - andExpression )* ) -andExpression := ( equalityExpression ( equalityExpression )* ) -equalityExpression := ( comparisonExpression ( "=" comparisonExpression - | "<>" comparisonExpression - | - | )* ) -comparisonExpression := - ( addExpression - ( ">" addExpression - | ">=" addExpression - | "<" addExpression - | "<=" addExpression - | stringLitteral ( stringLitteral )? - | ( )? - | addExpression addExpression - | addExpression addExpression - | "(" ( "," )* ")" - | "(" ( "," )* ")" - )* - ) - -addExpression := multExpr ( ( "+" multExpr | "-" multExpr ) )* -multExpr := unaryExpr ( "*" unaryExpr | "/" unaryExpr | "%" unaryExpr )* -unaryExpr := ( "+" unaryExpr | "-" unaryExpr | unaryExpr | primaryExpr ) -primaryExpr := ( literal | variable | "(" orExpression ")" ) -literal := ( - | - | - | - | - | - | - | - ) - -variable := ( | )]]> - - - -
- -
- - - diff --git a/qpid/doc/book/src/Programming-In-Apache-Qpid.xml b/qpid/doc/book/src/Programming-In-Apache-Qpid.xml new file mode 100644 index 0000000000..c0256a4bb2 --- /dev/null +++ b/qpid/doc/book/src/Programming-In-Apache-Qpid.xml @@ -0,0 +1,2497 @@ + + + + + + + Programming in Apache Qpid + Cross-Platform AMQP Messaging in Java JMS, .NET, C++, and Python + +
+ Supported APIs + + Apache Qpid is a reliable, asynchronous messaging system that + supports the AMQP messaging protocol in several common programming + languages. Qpid is supported on most common platforms. + + + + + + On the Java platform, Qpid uses the + established Java JMS + API. + + + + + On the .NET platform, Qpid defines + a WCF + binding. + + + + + For Python and C++, Qpid defines its own messaging API, the + Qpid Messaging API, which is + conceptually similar in each supported language. + + + + + Support for this API in Ruby will be added + soon + Ruby currently uses an API that is closely + tied to the AMQP version.. + + + +
+ +
+ Using the Qpid Messaging API + + The Qpid Messaging API is quite simple, consisting of only a + handful of core classes. + + + + + + + A message consists of a standard set + of fields (e.g. subject, + reply-to), an application-defined set of + properties, and message content (the main body of the + message). + + + + + + A connection represents a network + connection to a remote endpoint. + + + + + + A session provides a sequentially + ordered context for sending and receiving + messages. A session is obtained from a + connection. + + + + + + A sender sends messages to a target + using the sender.send method. A sender is + obtained from a session for a given target address. + + + + + + A receiver receives messages from a + source using the receiver.fetch method. + A receiver is obtained from a session for a given source + address. + + + + + + + The following sections show how to use these classes in a + simple messaging 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. + + + "Hello world!" in C++ + +#include +#include +#include +#include + +#include + +using namespace qpid::messaging; + +int main(int argc, char** argv) { + std::string broker = argc > 1 ? argv[1] : "localhost:5672"; + std::string address = argc > 2 ? argv[2] : "amq.topic"; + Connection connection(broker); + try { + connection.open(); + Session session = connection.createSession(); + + Receiver receiver = session.createReceiver(address); + Sender sender = session.createSender(address); + + sender.send(Message("Hello world!")); + + Message message = receiver.fetch(Duration::SECOND * 1); + std::cout << message.getContent() << std::endl; + session.acknowledge(); + + connection.close(); + return 0; + } catch(const std::exception& error) { + std::cerr << error.what() << std::endl; + connection.close(); + return 1; + } +}]]> + + + +
+ +
+ 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. + + + "Hello world!" in Python + + + +
+
+ Addresses + + An address is the name of a message + target or message source. In the programs we have just seen, we + used the address amq.topic (which is the name + of an exchange on an AMQP 0-10 messaging broker). + + The methods that create senders and receivers require an + address. The details of sending to a particular target or + receiving from a particular source are then handled by the + sender or receiver. A different target or source can be used + simply by using a different address. + + + An address resolves to a node. The + Qpid Messaging API recognises two kinds of nodes, + queues and topics. + + The terms queue and + topic here were chosen to align with + their meaning in JMS. These two addressing 'patterns', + queue and topic, are sometimes refered as point-to-point + and publish-subscribe. AMQP 0-10 has an exchange type + called a topic exchange. When the term + topic occurs alone, it refers to a + Messaging API topic, not the topic + exchange.. + + A queue stores each message until it has been received and + acknowledged, and only one receiver can receive a given message + There are exceptions to this rule; for instance, + a receiver can use browse mode, which leaves + messages on the queue for other receivers to + read. + + A topic immediately delivers a message to all eligible + receivers; if there are no eligible receivers, it discards the + message. In the AMQP 0-10 implementation of the API, + + The AMQP 0-10 implementation is the only one + that currently exists. + + queues map to AMQP queues, and topics map to AMQP exchanges. + + In AMQP 0-10, messages are sent to + exchanges, and read from queues. The Messaging API also + allows a sender to send messages to a queue; internally, + Qpid implements this by sending the message to the default + exchange, with the name of the queue as the routing key. The + Messaging API also allows a receiver to receive messages + from a topic; internally, Qpid implements this by setting up + a private subscription queue for the receiver and binding + the subscription queue to the exchange that corresponds to + the topic. + + + In the rest of this tutorial, we present many examples + using two programs that take an address as a command line + parameter. spout sends messages to the + target address, drain receives messages from + the source address. The source code 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. + + Currently, the Python and C++ + implementations of drain and + spout have slightly different + options. This tutorial uses the C++ implementation. The + options will be reconciled in the near + future. + + + The examples in this tutorial also use the + qpid-config utility to configure AMQP 0-10 + queues and exchanges on a Qpid broker. + + + + + Queues + + 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 sent by spout and delivered + it to drain when requested. + + Once the message has been delivered and and acknowledged + by drain, it is no longer available on the queue. If we run + drain one more time, no messages will be retrieved. + + +$ ./drain -a hello-world +$ + + + + + + Topics + + This example is similar to the previous example, but it + uses a topic instead of a queue. + + First, use qpid-config to remove the queue + and create an exchange with the same name: + + +$ qpid-config del queue hello-world +$ qpid-config add exchange topic hello-world + + + Now run drain and spout the same way we did in the previous example: + + +$ ./spout -a hello-world +$ ./drain -a hello-world +$ + + + Topics deliver messages immediately to any interested + receiver, and do not store messages. Because there were no + receivers at the time spout sent the + message, it was simply discarded. When we ran + drain, there were no messages to + receive. + + Now let's run drain first, using the + -t option to specify a timeout in seconds. + While drain is waiting for messages, + run spout in another window. + + First Window: + + +$ ./drain -a hello-word -t 30 + + + + 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 creates a subscription for the exchange, and + each receives all messages sent to the exchange. + + + +
+ Address Strings + + So far, our examples have used address strings that + contain only the name of a node. 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. A complete BNF for address strings appears in + . + + + So far, the address strings in this tutorial have used + only addresses. The following sections show how to use + subjects and options. + +
+ +
+ Subjects + + + Every message has a property called + subject, which is analogous to the + subject on an email message. If no subject is specified, the + message's subject is null. For convenience, address strings + also allow a subject. If a sender's address contains a + subject, it is used as the default subject for the messages + it sends. + + If a receiver's address contains a subject, it is used to + select only messages that match the subject—the matching + algorithm depends on the message source. + + + + In AMQP 0-10, each exchange type has its own matching + algorithm, and queues do not provide filtering. This is + discussed in . + + + + + Currently, a receiver bound to a queue ignores subjects, + receiving messages from the queue without filtering. + + In the future, if a receiver is bound to a queue, and its + address contains a subject, the subject will be used as a + selector to filter messages. + + + + + + Using subjects + + In this example we show how subjects affect message + flow. + + First, let's use qpid-config to create a topic exchange. + + +$ qpid-config add exchange topic news-service + + + Now we use drain to receive messages from news-service that match the subject sports. + First Window: + +$ ./drain -a news-service/sports -t 30 + + + In a second window, let's send messages to news-service using two different subjects: + + Second Window: + +$ ./spout -a news-service/sports +$ ./spout -a news-service/news + + + Now look at the first window, 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 AMQP exchange type we are using here, + amq.topic, can also do more sophisticated + matching. + + A sender's subject can contain multiple words separated by a + . delimiter. For instance, in a news + application, the sender might use subjects like + usa.news, usa.weather, + europe.news, or + europe.weather. + + The 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 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. + + + Subjects with multi-word keys + + This example uses drain and spout to demonstrate the + use of subjects with two-word keys. + + Let's use drain with the subject + *.news to listen for messages in which + the second word of the key is + news. + + First Window: + + +$ ./drain -a news-service/*.news -t 30 + + + Now let's send messages using several different + two-word keys: + + Second 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 + + + In the first window, 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='') + + + + Next, let's use drain with the + subject #.news to match any sequence of + words that ends with news. + + First Window: + + +$ ./drain -a news-service/#.news -t 30 + + + In the second window, let's send messages using a + variety of different multi-word keys: + + Second Window: + + +$ ./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 + + + In the first window, 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='') + + + +
+ +
+ Address String Options + + + The options in an address string contain additional + information for the senders or receivers created for it, + including: + + + + + Policies for assertions about the node to which an address + refers. + + + For instance, in the address string my-queue; + {assert: always, node:{ type: queue }}, the node + named my-queue must be a queue; if not, + the address does not resolve to a node, and an exception + is raised. + + + + + Policies for automatically creating or deleting the node to which an address refers. + + + For instance, in the address string xoxox ; {create: always}, + the queue xoxox is created, if it does + not exist, before the address is resolved. + + + + + Extension points that can be used for sender/receiver configuration. + + + For instance, if the address for a receiver is + my-queue; {mode: browse}, the receiver + works in browse mode, leaving messages + on the queue so other receivers can receive them. + + + + + + + Let's use some examples to show how these different kinds of + address string options affect the behavior of senders and + receives. + + + + + First, let's use the assert option to + ensure that the address resolves to a node of the required + type. + + + + + Assertions on Nodes + + Let's use qpid-config to create a + queue and a topic. + + +$ 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 '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 + + + + 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 to + create the queue xoxox if it does not already + exist: + + + Creating a Queue Automatically + + First Window: + $ ./drain -a "xoxox ; {create: always}" -t 30 + + 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: + $ ./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. The following example uses the + browse option to receive messages without + removing them from a queue. + + + 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, using 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 by 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') + + + + + + + Address String Options + + + + option + value + semantics + + + + + + assert + + + one of: always, never, sender or receiver + + + Asserts that the properties specified in the node option + match whatever the address resolves to. If they do not, + resolution fails and an exception is raised. + + + + + + create + + + one of: always, never, sender or receiver + + + 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 + + + one of: always, never, sender or receiver + + + Delete the node when the sender or receiver is closed. + + + + + node + + + A nested map containing the entries shown in . + + + Specifies properties of the node to which the address + refers. These are used in conjunction with the assert or + create options. + + + + + link + + + A nested map containing the entries shown in . + + + Used to control the establishment of a conceptual link + from the client application to or from the target/source + address. + + + + + mode + + + one of: browse, consume + + + 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 + + + + property + value + semantics + + + + + + type + + + topic, queue + + + + + + + durable + + + True, False + + + Indicates whether the node survives a loss of + volatile storage e.g. if the broker is restarted. + + + + + x-declare + + + A nested map whose values correspond to the valid fields + on an AMQP 0-10 queue-declare or exchange-declare + command. + + + These values are used to fine tune the creation or + assertion process. Note however that they are protocol + specific. + + + + + x-bindings + + + A nested list in which each binding is represented by + a map. The entries of the map for a binding contain + the fields that describe an AMQP 0-10 binding. Here is + the format for x-bindings: + +, + queue: , + key: , + arguments: { : , ..., : } + }, + ... +] +]]> + + + In conjunction with the create option, each of these + bindings is established as the address is resolved. In + conjunction with the assert option, the existence of + each of these bindings is verified during + resolution. Again, these are protocol specific. + + + + +
+ + + Link Properties + + + + option + value + semantics + + + + + + reliability + + + one of: unreliable, at-least-once, at-most-once, exactly-once + + + + + + + durable + + + True, False + + + Indicates whether the link survives a loss of + volatile storage e.g. if the broker is restarted. + + + + + x-declare + + + A nested map whose values correspond to the valid fields + of an AMQP 0-10 queue-declare command. + + + 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-subscribe + + + A nested map whose values correspond to the valid fields + of an AMQP 0-10 message-subscribe command. + + + These values can be used to customise the subscription. + + + + + x-bindings + + + 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. + + + These bindings are established during resolution + independent of the create option. They are considered + logically part of the linking process rather than of + node creation. + + + + + + +
+ + +
+ Address String Grammar + + This section provides a formal grammar for address strings. + + + Tokens + The following regular expressions define the tokens used + to parse address strings: + + + + Grammar + The formal grammar for addresses is given below: + + + + + + + Address String Options + The address string options map supports the following parameters: + + + [ / ] ; { + create: always | sender | receiver | never, + delete: always | sender | receiver | never, + assert: always | sender | receiver | never, + mode: browse | consume, + node: { + type: queue | topic, + durable: True | False, + x-declare: { ... ... }, + x-bindings: [, ... ] + }, + link: { + name: , + durable: True | False, + reliability: unreliable | at-most-once | at-least-once | exactly-once, + x-declare: { ... ... }, + x-bindings: [, ... ], + x-subscribe: { ... ... } + } +} +]]> + + + + Create, Delete, and Assert Policies + The create, delete, and assert policies specify who should + perfom the associated action: + always: the action is performed by any messaging client + sender: the action is only performed by a sender + receiver: the action is only performed by a receiver + never: the action is never performed (this is the default) + + + + Node-Type + The node-type is one of: + topic: in the AMQP 0-10 + mapping, a topic node defaults to the topic exchange, x-declare + may be used to specify other exchange types + queue: this is the default node-type + +
+ + +
+ +
+ Logging + The Qpidd broker and C++ clients can both use environment + variables to enable logging. Use QPID_LOG_ENABLE to set the + level of logging you are interested in (trace, debug, info, + notice, warning, error, or critical): + + +$ export QPID_LOG_ENABLE="warning+" + + + The Qpidd broker and C++ clients use QPID_LOG_OUTPUT to + determine where logging output should be sent. This is either a + file name or the special values stderr, stdout, or syslog: + + +export QPID_LOG_TO_FILE="/tmp/myclient.out" + + +
+ + + +
+ Reconnect and Failover + Connections in the Qpid Messaging API support automatic + reconnect if a connection is lost. This is done using connection + options. The following example shows how to use connection options in C++ and Python. + + + Specifying Connection Options in C++ and Python + + In C++, these options are set using Connection::setOption(): + + + + In Python, these options are set using named arguments in + the Connection constructor: + + + + See the reference documentation for details on how to set + these on connections for each language. + + + The following table lists the connection options that can + be used. + + + Connection Options + + + + option + value + semantics + + + + + + reconnect + + + True, False + + + Transparently reconnect if the connection is lost. + + + + + reconnect_timeout + + + N + + + Total number of seconds to continue reconnection attempts before giving up and raising an exception. + + + + + reconnect_limit + + + N + + + Maximum number of reconnection attempts before giving up and raising an exception. + + + + + reconnect_interval_min + + + N + + + 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 reconnect interval increases exponentially until a reconnection attempt succeeds or reconnect_interval_max is reached. + + + + + reconnect_interval_max + + + N + + + Maximum reconnect interval. + + + + + reconnect_interval + + + N + + + Sets both reconnection_interval_min and reconnection_interval_max to the same value. + + + + +
+
+ +
+ Receiving Messages from Multiple Sources + + A receiver can only read from one source, but many + programs need to be able to read messages from many sources, + preserving the original sequence of the messages. In the Qpid + Messaging API, a program can ask a session for the next + receiver; that is, the receiver that is responsible for + the next available message. The following example shows how this + is done in C++ and Python. + + + Receiving Messages from Multiple Sources + + C++: + + + + Python: + + +
+ +
+ Request / Response + Request / Response applications use the reply-to property, + described in , to allow a server + to respond to the client that sent a message. A server sets up a + service queue, with a name known to clients. A client creates a + private queue for the server's response, creates a message for a + request, sets the request's reply-to property to the address of + the client's response queue, and sends the request to the + service queue. The server sends the response to the address + specified in the request's reply-to property. + + + Request / Response Applications in C++ + + This example shows the C++ code for a client and server + that use the request / response pattern. + + The server creates a service queue and waits for a + message to arrive. If it receives a message, it sends a + message back to the sender. + + + + The client creates a sender for the service queue, and + also creates a response queue that is deleted when the + client closes the receiver for the response queue. In the C++ + client, if the address starts with the character + #, it is given a unique name. + + " << response.getContent() << std::endl; +]]> + + The client sends the string ping to + the server. The server sends the response + pong back to the same client, using the + replyTo property. + + + +
+ + + +
+ XML Exchange + + The XML Exchange is an AMQP 0-10 custom exchange provided by the Apache Qpid C++ broker. It allows messages to be filtered using XQuery; queries can address either message properties or XML content in the body of the message. + + An instance of the XML Exchange must be added before it can be used: + + +$ qpid-config add exchange xml xml + + + When using the XML exchange, a sender's address string must provide a subject, e.g. xml/weather. + + If a receiver that is using the XML exchange also provides a subject, it receives messages if the subject exactly matches a message's subject. + + + When using the XML Exchange, a receiver normally provides an XQuery as an x-binding argument. If the query contains a context item (a path starting with .), then it is applied to the content of the message, which must be well-formed XML. For instance, ./weather is a valid XQuery, which matches any message in which the root element is named weather. Here is an address string that contains this query: + + + + Note that each x-binding is created in addition to any other bindings that may exist, and each x-binding must include the exchange name, the key, and the xquery. If you specify the subject in the address string (e.g. xml/weather; link ...), it creates a binding that is used in addition to the x-bindings; the binding created for the subject matches any message whose subject is weather, the binding created for the x-binding matches any message that satisfies the query, i.e. any message with a root element named weather. + + + + The XML Exchange can also be used to query message properties by declaring an external variable with the same name as each property that is to be queried. The following XQuery queries the control property, as well as the content of the message: + + + + If the XQuery addresses message content, and the message is not well-formed XML, the message will not be received. If the XQuery does not query message content, the message need not contain XML. + + + + Using the XML Exchange with <command>drain</command> + + The following shows the arguments used with drain to retrieve messages whose root element is named weather: + + + + + + Using the XML Exchange with C++ + + In C++, it is convenient to place an XQuery in a string, and use a stringstream to add the query to the template for an address string that specifies an x-binding. + + 50" + " and $w/temperature_f - $w/dewpoint > 5" + " and $w/wind_speed_mph > 7" + " and $w/wind_speed_mph < 20"; + +stringstream address; + +address << "xml; {" + " link: { " + " x-bindings: [{ exchange: xml, key: weather, arguments: { xquery:\"" + << query + << "\"} }] " + " } " + "}"; + + +Receiver receiver = session.createReceiver(address.str()); +Message response = receiver.fetch(); +session.acknowledge(); +std::cout << response.getContent() << std::endl; + + ]]> + + + + + Using the XML Exchange with Python + + In Python, it is often convenient to place the query in + a separate string, and use the repr() value of the query + string in an address template string. + + 50 + and $w/temperature_f - $w/dewpoint > 5 + and $w/wind_speed_mph > 7 + and $w/wind_speed_mph < 20 """ + + address = """ + xml; { + link: { + x-bindings: [{ exchange: xml, key: weather, arguments: { xquery: %r} }] + } + } + """ % query + + receiver = session.receiver(address) + +# Retrieve matching message from the receiver and print it + + message = receiver.fetch(timeout=1) + print message.content + session.acknowledge() + ]]> + + +
+ +
+ Performance + + Clients can often be made significantly faster by batching acknowledgements and setting the capacity of receivers to allow prefetch. + +
+ Batching Acknowledgements + + Many of the simple examples we have shown retrieve a message and immediately acknowledge it. Because each acknowledgement results in network traffic, you can dramatically increase performance by acknowledging messages in batches. For instance, an application can read a number of related messages, then acknowledge the entire batch, or an application can acknowledge after a certain number of messages have been received or a certain time period has elapsed. Messages are not removed from the broker until they are acknowledged, so guaranteed delivery is still available when batching acknowledgements. +
+ + +
+ Prefetch + + By default, a receiver retrieves the next message from the server, one message at a time, which provides intuitive results when writing and debugging programs, but does not provide optimum performance. To create an input buffer, set the capacity of the receiver to the size of the desired input buffer; for many applications, a capacity of 100 performs well. + + + + + Prefetch + + C++ + +Receiver receiver = session.createReceiver(address); +receiver.setCapacity(100); +Message message = receiver.fetch(); + + + + +
+ +
+ +
+ Reliability + +
+ Guaranteed Delivery + + If a queue is durable, the queue survives a messaging + broker crash, as well as any durable messages that have been + placed on the queue. These messages will be delivered when the + messaging broker is restarted. Delivery is guaranteed if and + only if both the message and the queue are durable. Guaranteed + delivery requires a persistence module, such as the one + available from QpidComponents.org. + + + Guaranteed Delivery + + C++: + + + + + + +
+ +
+ + + +
+ Transactions + In AMQP, transactions cover the semantics of enqueues and + dequeues. + + When sending messages, a transaction tracks enqueues + without actually delivering the messages, a commit places + messages on their queues, and a rollback discards the + enqueues. + + When receiving messages, a transaction tracks dequeues + without actually removing acknowledged messages, a commit + removes all acknowledged messages, and a rollback discards + acknowledgements. A rollback does not release the message, it + must be explicitly released to return it to the queue. + + + Transactions + C++: + + + + +
+ + + + + +
+ The AMQP 0-10 mapping + + + This section describes the AMQP 0-10 mapping for the Qpid + Messaging API. + + + 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. + + + 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 is 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 is used for + the binding key (this means that the subject in the source + address may be a binding pattern including 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 receives 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 is 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 simply contain an x-match entry and no + other entries, causing all messages to match. If a subject + is specified then the binding arguments 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 exchange,Note 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 binding key and an XQuery is defined that + matches any message with that value for + qpid.subject. Again this means that only messages whose + subject exactly match that specified in the source address + are 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 PropertyIn these entries, mp refers to an AMQP message property, and dp refers to an AMQP delivery 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 + + + +
+ +
+
+ + +
+ 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. + + The Qpid JMS client uses Qpid Messaging API to identify sources and + targets. 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 bind the sender and receiver + to. (The syntax of a ConnectionURL is given in .) + + + JNDI Properties File for "Hello world!" example + + + + 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. + + + "Hello world!" in Java + + + +
+ +
+ Apache Qpid JNDI Properties for AMQP Messaging + + + + Apache Qpid defines JNDI properties that can be used to specify JMS Connections and Destinations. Here is a typical JNDI properties file: + + + + JNDI Properties File + + + + 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 uses 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. + + Binding URLs, which were used in + earlier versions of the Qpid Java JMS client, can + still be used instead of address + strings. + + + + + +
+
+ +
+ 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_publish + + + {'persistent' | 'all'} + + + A sync command is sent after every persistent message to guarantee that it has been received; if the value is 'persistent', this is done only for persistent messages. + + + + + sync_ack + + + Boolean + + + A sync command is sent after every acknowledgement to guarantee that it has been received. + + + + + use_legacy_map_msg_format + + + Boolean + + + If you are using JMS Map messages and deploying a new client with any JMS client older than 0.7 release, you must set this to true to ensure the older clients can understand the map message encoding. + + + + + failover + + + {'roundrobin' | 'failover_exchange'} + + + If roundrobin is selected it will try each broker given in the broker list. + If failover_exchange is selected it connects to the initial broker given in the broker URL and will receive membership updates via the failover exchange. + + + + +
+ + Broker lists are specified using a URL in this format: + + + brokerlist=<transport>://<host>[:<port>](?<param>=<value>)?(&<param>=<value>)* + + For instance, this is a typical broker list: + + + brokerlist='tcp://localhost:5672' + + + + A broker list can contain more than one broker address; if so, the connection is made to the first broker in the list that is available. In general, it is better to use the failover exchange when using multiple brokers, since it allows applications to fail over if a broker goes down. + + + + Broker Lists + A broker list can specify properties to be used when connecting to the broker, such as security options. This broker list specifies options for a Kerberos connection using GSSAPI: + + + This broker list specifies SSL options: + + + + + The following broker list options are supported. + + + Broker List Options + + + + + Option + + + Type + + + Description + + + + + + + heartbeat + + + integer + + + frequency of heartbeat messages (in seconds) + + + + + sasl_mechs + + + -- + + + For secure applications, we suggest CRAM-MD5, + DIGEST-MD5, or GSSAPI. The ANONYMOUS method is not + secure. The PLAIN method is secure only when used + together with SSL. + For Kerberos, sasl_mechs must be set to GSSAPI, + sasl_protocol must be set to the principal for the qpidd broker, e.g. qpidd/, and + sasl_server must be set to the host for the SASL server, e.g. sasl.com. + SASL External is supported using SSL certification, e.g. + ssl='true'&sasl_mechs='EXTERNAL' + + + + + sasl_encryption + + + Boolean + + + If sasl_encryption='true', the JMS client attempts to negotiate a security layer with the broker using GSSAPI to encrypt the connection. Note that for this to happen, GSSAPI must be selected as the sasl_mech. + + + + + ssl + + + Boolean + + + If ssl='true', the JMS client will encrypt the connection using SSL. + + + + + tcp_nodelay + + + Boolean + + + If tcp_nodelay='true', TCP packet + batching is disabled. + + + + + sasl_protocol + + + -- + + + Used only for + Kerberos. sasl_protocol must be + set to the principal for the qpidd broker, + e.g. qpidd/ + + + + + sasl_server + + + -- + + + For Kerberos, sasl_mechs must be set to GSSAPI, + sasl_server must be set to the host for the SASL + server, e.g. sasl.com. + + + + + trust_store + + + -- + + + path to Keberos trust store + + + + + trust_store_password + + + + + Kerberos trust store password + + + + + key_store + + + + + path to Kerberos key store + + + + + key_store_password + + + -- + + + Kerberos key store password + + + + + ssl_verify_hostname + + + Boolean + + + When using SSL you can enable hostname verification + by using "ssl_verify_hostname=true" in the broker + URL. + + + + + ssl_cert_alias + + + + + + If multiple certificates are present in the keystore, the alias will be used to extract the correct certificate. + + + + +
+
+
+ +
+ Java JMS Message Properties + + 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. + + + Java JMS Mapping to AMQP 0-10 Message Properties + + + + Java JMS Message Property + AMQP 0-10 PropertyIn these entries, mp refers to an AMQP message property, and dp refers to an AMQP delivery property. + + + + + + JMSMessageIDmp.message_id + + + qpid.subjectThis is a custom JMS property, set automatically by the Java JMS client implementation.mp.application_headers["qpid.subject"] + + + JMSXUserIDmp.user_id + + + JMSReplyTomp.reply_toThe reply_to is converted from the protocol representation into an address. + + + JMSCorrelationIDmp.correlation_id + + + JMSDeliveryModedp.delivery_mode + + + JMSPrioritydp.priority + + + JMSExpirationdp.ttlJMSExpiration = dp.ttl + currentTime + + + JMSRedelivereddp.redelivered + + + JMS Propertiesmp.application_headers + + + JMSTypemp.content_type + + + +
+ +
+ +
+ Java JMS Selector Syntax + The AMQP Java JMS Messaging Client supports the following syntax for JMS selectors. + + + Comments: + + + + + + Reserved Words (case insensitive) + + + + + + Literals (case insensitive) + + )? // eg: 5.5 or 5. or 5.5E10 or 5.E10 + | "." (["0"-"9"])+ ()? // eg: .5 or .5E10 + | (["0"-"9"])+ // eg: 5E10 +) +EXPONENT: "E" (["+","-"])? (["0"-"9"])+ +STRING_LITERAL: "'" ( ("''") | ~["'"] )* "'" +]]> + + + + + Identifiers (case insensitive) + + + + + + + Grammar + + andExpression )* ) +andExpression := ( equalityExpression ( equalityExpression )* ) +equalityExpression := ( comparisonExpression ( "=" comparisonExpression + | "<>" comparisonExpression + | + | )* ) +comparisonExpression := + ( addExpression + ( ">" addExpression + | ">=" addExpression + | "<" addExpression + | "<=" addExpression + | stringLitteral ( stringLitteral )? + | ( )? + | addExpression addExpression + | addExpression addExpression + | "(" ( "," )* ")" + | "(" ( "," )* ")" + )* + ) + +addExpression := multExpr ( ( "+" multExpr | "-" multExpr ) )* +multExpr := unaryExpr ( "*" unaryExpr | "/" unaryExpr | "%" unaryExpr )* +unaryExpr := ( "+" unaryExpr | "-" unaryExpr | unaryExpr | primaryExpr ) +primaryExpr := ( literal | variable | "(" orExpression ")" ) +literal := ( + | + | + | + | + | + | + | + ) + +variable := ( | )]]> + + + +
+ +
+ + + diff --git a/qpid/doc/book/src/schemas.xml b/qpid/doc/book/src/schemas.xml index 3563398252..635ad96a22 100644 --- a/qpid/doc/book/src/schemas.xml +++ b/qpid/doc/book/src/schemas.xml @@ -21,6 +21,8 @@ --> + + -- cgit v1.2.1