The Apache Qpid High Level Client API is a reliable, asynchronous messaging API that is similar to Java JMS, but designed to support programming in other commonly used programming languages, and to support cross-platform messaging using the AMQP protocol. It is currently implemented for C++ and Python. The addressing mechanisms it defines can also be used in Java JMS. Unlike earlier Qpid APIs, the High Level Client API does not expose the details of the underlying messaging protocol or the software components defined by the protocol. Instead, it defines a declarative syntax for addressing messaging components; to use it with a given messaging protocol, a protocol mapping must be defined. This specification provides a mapping to AMQP 0-10. At this point, AMQP 1.0 is not yet final, but we expect that applications written using the High Level Client API can be migrated to AMQP 1.0 with minimal changes, and applications that do not need to configure messaging components can be used without change. The Qpid High Level Client API programming model is very similar to the Java JMS programming model. Here are the most important classes in the high level programming model: A connection represents a network connection. The parameters for the network connection are specified using a URL-based syntax when the connection is opened. A session represents the interface between a messaging client and a messaging broker. A session is created by a connection. An address is a string that represents a node on a messaging broker. In the AMQP 0-10 mapping, an address represents either an exchange or a queue. In the AMQP 1.0 mapping, an address will represent an AMQP 1.0 node. Most addresses are simple names. An extended address can also specify options. A sender is a messaging client that sends messages to a destination on a messaging broker. A sender is created by a session. A receiver is a messaging client that receives messages from a source on a Messaging Broker. A Receiver is created by a Session.

This section shows the code for two programs. One is a simple sender, the other is a simple receiver.

Both of these programs use the same skeleton, which includes the headers that define the Connection, Message, Receiver, Sender, and Session objects. The code in main() opens a connection using a URL that identifies a messaging broker, creates a session, and catches any errors that occur during messaging: #include #include #include #include #include using namespace qpid::messaging; int main() { Connection connection; try { connection.open("amqp:tcp:127.0.0.1:5672"); Session session = connection.newSession(); /* #### Main body of messaging code goes here #### */ connection.close(); return 0; } catch(const std::exception& error) { std::cout << error.what() << std::endl; connection.close(); } return 1; }]]>

The sender program creates a Sender object that sends messages to message_queue, which happens to be a queue on on AMQP 0-10 messaging broker. The AMQP 0-10 mapping implements this by sending messages to the default exchange, with message_queue as the routing key.

The receiver program creates a Receiver object, reads messages from message_queue, acknowledging them so the messaging broker knows they have been received and can be safely removed from the queue, and prints them: The Receiver::fetch() method can be used with or without a timeout. In either case, it is guaranteed to receive any messages on the queue. Here, the timeout is used in case sender is publishing at the same time message are being read.

As we have seen, an address is a string that identifies objects on the messaging broker. There are two kinds of addresses. A simple address is a name. An extended address can also have a subject and options. The syntax for an address is: [ / ] [ ; ] options ::= { : , ... } ]]> Names, subjects, and keys are strings. Values can be numbers, strings (with optional single or double quotes), maps, or lists. In most cases, queues, bindings, and exchanges are configured externally with management tools. Qpid High Level API clients send to and receive from these queues and exchanges. In AMQP 0-10, messages are sent to exchanges, and received from queues. The Qpid High Level Client API allows programs to send to or receive from any node. To make this possible, the mapping defines the semantics of sending and receiving for all AMQP 0-10 exchange types and queues as follows: When a Sender sends a message to an exchange, the transfer destination is set to the exchange name, and the routing key is set to the value of the address subject. When a Receiver receives messages from an exchange, the API automatically creates a subscription queue and binds it to the exchange. If the address contains a subject, then it is used as the binding key. If the address does not contain a subject, then the binding key depends on the exchange type: topic exchange: wildcard match direct exchange: error — the address must specify a subject fanout: none The subscription queue's durability and autodelete properties can be set using options. When a Sender sends a message to a queue, the message is sent to the AQMP 0-10 default queue, using the name of the queue as the routing key. When a Receiver receives messages from a queue, it is treated as a normal AMQP 0-10 queue subscription. The accept-mode property can be set using options. The following sections describe the various kinds of addresses in detail. The examples in these sections use the qpid-config utility to configure AMQP 0-10 queues and exchanges, send messages using drain, and receive messages using spout. The source code for drain and spout is available in both C++ and Python, and can be found in the examples directory for each language. These programs can use any address as a source or a destination, and have many command line options to configure behavior—use the -h option for documentation on these options.

If an address contains only a name, it resolves to a named node. On AMQP 0-10, a named node maps to a queue or an exchange with the same name. Address resolution is not yet well-defined if a queue and an exchange have the same name. This is a known problem, and is being resolved. Create a queue with qpid-config, send a message using spout, and read it using drain: $ qpid-config add queue hello-world $ ./spout -a hello-world $ ./drain -a hello-world Message(properties={spout-id:c877e622-d57b-4df2-bf3e-6014c68da0ea:0}, content='') Exchanges and queues are addressed in exactly the same way in the Qpid High Level Client API. If we delete the queue named hello-world and create an exchange with the same name, we can write to and read from the exchange in the same way as for the queue: $ qpid-config del queue hello-world $ qpid-config add exchange topic hello-world $ ./spout -a hello-world $ ./drain -a hello-world $ However, in AMQP 0-10, exchanges discard messages if no queue is bound to the exchange, unlike queues, which store messages until they are retrieved. Because of this, no messages were output in the above screen. If drain is called before spout, a Receiver is created for the exchange, which also creates a subscription queue and a binding. Run drain in one terminal window using -t to specify a timeout in seconds, and run spout in another window to send a message for drain to receive. First Window: $ ./drain -a hello-word -t 30 Second Window: $ ./spout -a hello-word Once spout has sent a message, return to the first window to see the output from drain: Message(properties={spout-id:7da2d27d-93e6-4803-8a61-536d87b8d93f:0}, content='') You can run drain in several separate windows; each will create a subscription for the exchange, and each will receive all messages sent to the exchange.

Subjects are used to classify messages. A Sender's subject is assigned to each message that it sends (this can be overridden by specifying a subject directly on the message). In the AMQP 0-10 mapping, the message's subject is used as the routing key for all messages sent to the messaging broker. If a Sender is bound to an AMQP 0-10 exchange, it sends messages to that exchange. If a Sender is bound to an AMQP 0-10 queue, the message is sent to the default exchange. A Receiver's subject is used to filter messages; only messages with a subject that matches the Receiver's subject will be received. If a Receiver's name resolves to an AMQP 0-10 exchange, the subject is used as a binding key for the corresponding AMQP 0-10 exchange type. The C++ implementation of the Qpid messaging broker does not currently support selectors, so a Receiver's subject does not filter messages if the Receiver's address resolves to a queue.

In an AMQP 0-10 direct exchange, messages are routed to queues if the routing key exactly matches the binding key. In the High Level Client API, if a Sender and a Receiver are bound to the same exchange, the Receiver will receive messages if the Sender's subject matches the Receiver's subject. Let's create a direct exchange and listen for messages whose subject is sports: First Window: $ qpid-config add exchange direct direct-exchange $ ./drain -a direct-exchange/sports -t 30 In a second window, let's send messages to the exchange we created: Second Window: $ ./spout -a direct-exchange/sports $ ./spout -a direct-exchange/news Now look at the first window, and you will see the message with the subject sports has been received, but not the message with the subject news: Message(properties={qpid.subject:sports, spout-id:9441674e-a157-4780-a78e-f7ccea998291:0}, content='') If you run drain in multiple windows using the same subject, all instances of drain receive the messages for that subject.

An AMQP 0-10 topic exchange uses routing keys that contain multiple words separated by a . delimiter. For instance, in a news application, a Sender's subject might be usa.news, usa.weather, europe.news, or europe.weather. A Receiver's subject can include wildcard characters— # matches one or more words in the message's subject, * matches a single word. For instance, if the Receiver's subject is *.news, it matches messages with the subject europe.news or usa.news; if the Receiver's subject is europe.#, it matches messages with subjects like europe.news or europe.pseudo.news. Let's create a topic exchange and listen for messages whose subject is news: First Window: $ qpid-config add exchange topic topic-exchange $ ./drain -a topic-exchange/news -t 30 In a second window, let's send messages to the exchange we created: Second Window: $ ./spout -a topic-exchange/news $ ./spout -a topic-exchange/sports Now look at the first window, and you will see the message with the subject news has been received, but not the message with the subject sports: Message(properties={qpid.subject:news, spout-id:bafefb74-c5be-4a8b-9e4b-45f7a855e250:0}, content='') Now let's use the topic exchange with wildcards in the Receiver and multi-word keys in the Sender. This time, let's use two-word keys. The Receiver uses the subject *.news to listen for messages in which the second word of the key is news: First Window: $ ./drain -a topic-exchange/*.news -t 30 Now let's send messages using several different two-word keys: Second Window: $ ./spout -a topic-exchange/usa.news $ ./spout -a topic-exchange/usa.sports $ ./spout -a topic-exchange/europe.sports $ ./spout -a topic-exchange/europe.news $ Now look at the first window, and you will see the messages with news in the second word of the key have been received: Message(properties={qpid.subject:usa.news, spout-id:73fc8058-5af6-407c-9166-b49a9076097a:0}, content='') Message(properties={qpid.subject:europe.news, spout-id:f72815aa-7be4-4944-99fd-c64c9747a876:0}, content='') Finally, let's use the # wildcard in the Receiver to match any number of words in the key. The Receiver uses the key #.news to listen for messages in which the last word of the key is news, no matter how many words are in the key: First Window: $ ./drain -a topic-exchange/#.news -t 30 Now let's send messages using a variety of different multi-word keys: Second Window: $ ./spout -a topic-exchange/news $ ./spout -a topic-exchange/sports $ ./spout -a topic-exchange/usa.news $ ./spout -a topic-exchange/usa.sports $ ./spout -a topic-exchange/usa.faux.news $ ./spout -a topic-exchange/usa.faux.sports Now look at the first window, and you will see the messages with news in the last word of the key have been received: Message(properties={qpid.subject:news, spout-id:cbd42b0f-c87b-4088-8206-26d7627c9640:0}, content='') Message(properties={qpid.subject:usa.news, spout-id:234a78d7-daeb-4826-90e1-1c6540781eac:0}, content='') Message(properties={qpid.subject:usa.faux.news, spout-id:6029430a-cfcb-4700-8e9b-cbe4a81fca5f:0}, content='')

A fanout exchange ignores the subject, and no filtering is done. Let's create a fanout exchange and listen for messages. We will use the subject news in the Receiver to demonstrate that this subject is not actually used to filter messages: First Window: $ qpid-config add exchange fanout fanout-exchange $ ./drain -a fanout-exchange/news -t 30 Now let's send a message using a different subject: Second Window: $ ./spout -a fanout-exchange/sports Returning to the first window, we see that the message was received even though the Receiver's subject was different from the Sender's subject: Message(properties={qpid.subject:sports, spout-id:931399a1-27fc-471c-8dbe-3048260f9441:0}, content='') This happens because of the routing semantics of the AMQP 0-10 fanout exchange.

If a Sender is bound to a queue, its messages are sent to the default exchange using the queue's name as the routing key. If a Receiver is bound to a queue, it receives messages from the queue. Let's create a queue and listen for messages on it. First Window: $ ./qpid-config add queue amqp010-queue $ ./drain -a amqp010-queue -t 30 Now let's send some messages. The subject is not used for routing purposes. $ ./spout -a amqp010-queue/news $ ./spout -a amqp010-queue Now look at the first window, and you will see that both messages have been received: Message(properties={qpid.subject:news, spout-id:6c769437-60be-4bc0-9bf6-5a77cb6ba65f:0}, content='') Message(properties={spout-id:c8ab5013-a19e-4f54-967c-797c8ad6568b:0}, content='')

AMQP 0-10 also supports custom exchanges. The Qpid messaging broker includes the XML Exchange, which uses an XQuery to filter messages based on message properties and XML message content.

Extended Address Options are parameters that affect the behavior of Senders and Receivers. Some of these options specify aspects of the resolution process; for instance, they may make assertions that must be satisfied in order for resolution to succeed, or they may state that the node should be created if it does not already exist. Let's use drain and spout to show how this works. First, let's use the assert option to insist that an address must resolve to a queue. In the High Level Client API, a node is either a queue or a topic. A queue is used the same way as in AMQP 0-10, but for consistency with Java JMS, a topic node is the same thing AMQP 0-10 calls an exchange.(In this section, we will use the term topic node for a High Level Client API topic node, and AMQP 0-10 topic exchange for the exchange type that has the same name.) AMQP 0-10 has several built-in exchanges that are predeclared: amq.topic, amq.direct, amq.match, and amq.fanout. To the High Level Exchange, any of these exchanges is considered a topic node. Let's use drain, and assert that amq.fanout is a topic node: $ ./drain -a "amq.fanout; { assert: always, node: { type: topic }}" The address resolves succesfully. No exception is raised, because a topic node named amq.fanout exists. Now let's assert that amq.fanout is a queue node: $ ./drain -a "amq.fanout; { assert: always, node: { type: queue }}" 2010-04-09 14:01:35 warning Exception received from broker: not-found: not-found: Queue not found: amq.fanout (qpid/broker/SessionAdapter.cpp:753) [caused by 0 \x08:\x01] Queue amq.fanout does not exist An exception was raised because there is no queue named amq.fanout, so address resolution failed. Now let's use the create option with drain, telling it to create the queue xoxox if it does not already exist: 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: $ ./drain -a "xoxox ; {create: always}" -t 30 Returning to the first window, we see that drain has received this message: Message(properties={spout-id:1a1a3842-1a8b-4f88-8940-b4096e615a7d:0}, content='') Other options specify message transfer semantics; for instance, they may state whether messages should be consumed or read in browsing mode, or specify reliability characteristics. For instance, we can use browse mode to receive messages without removing them from the queue, thus allowing other Readers to receive them: $ ./drain 'hello-queue; {mode: browse}' option parameters semantics assert node Asserts that the node properties are satisfied for a node. If they are not, node resolution fails and an exception is raised. create node (optional) Creates the node if it does not exist. No error is raised if the node does exist. delete N/A Delete the node when the Sender or Receiver is closed. reliability unreliable, at-least-once, at-most-once, exactly-once mode browse, consume 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 reconnection interval increases exponentially until a reconnection attempt succeeds or reconnect_interval_max is reached. reconnect_interval_max N Maximum reconnection interval. reconnection_interval N Sets both reconnection_interval_min and reconnection_interval_max to the same value. property parameters semantics type topic, queue durable True, False x-declare unrestricted map If the property is defined in the underlying protocol (AMQP 0-10), the values and semantics are defined by the protocol. Otherwise, values are added to the arguments map used to declare topicsThe High Level Client API, like Java JMS, uses the term topic to refer to what AMQP 0-10 calls an exchange. One kind of AMQP 0-10 exchange is called a topic exchange, that is not what is meant here. or queues. property parameters semantics type direct, topic, fanout, header, xml The AMQP 0-10 exchange type. bindings ["exchange/binding-key", ... ] This property is used to create bindings for queues. If the Address does not resolve to a queue, an error is raised.

This section shows how Qpid High Level Client API message properties are mapped to AMQP message properties and delivery properties. Request-response applications frequently use a reply-to property to tell a server where to send a response. The following code shows how a server extracts the reply-to property and uses it to set the address to respond to a client. Message request = receiver.fetch(); const Address& address = request.getReplyTo(); Get "reply-to" field from request ... if (address) { Sender sender = session.createSender(address); ... and use it as the address to send response std::string s = request.getContent(); std::transform(s.begin(), s.end(), s.begin(), toupper); Message response(s); sender.send(response); std::cout << "Processed request: " << request.getContent() << " -> " << response.getContent() << std::endl; session.acknowledge(); In the following table, msg refers to the Message class defined in the High Level Client API, mp refers to an AMQP 0-10 message-properties struct, and dp refers to an AMQP 0-10 delivery-properties struct. Python API C++ API AMQP 0-10 Property msg.idmsg.{get,set}MessageId()mp.message_id msg.to- -mp.application_headers["qpid.to"] msg.subjectmsg.{get,set}Subject()mp.application_headers["qpid.subject"] msg.user_idmsg.{get,set}UserId()mp.user_id msg.reply_tomsg.{get,set}ReplyTo()mp.reply_toThe reply_to is converted from the protocol representation into an address. msg.correlation_idmsg.{get,set}CorrelationId()mp.correlation_id msg.durablemsg.{get,set}Durable()dp.delivery_mode == delivery_mode.persistentNote that msg.durable is a boolean, not an enum. msg.prioritymsg.{get,set}Priority()dp.priority msg.ttlmsg.{get,set}Ttl()dp.ttl msg.redeliveredmsg.isRedelivered()dp.redelivered msg.propertiesmsg.{get,set}Headers()mp.application_headers msg.content_typemsg.{get,set}ContentType()mp.content_type