Programming in Apache Qpid

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"; std::string connectionOptions = argc > 3 ? argv[3] : ""; Connection connection(broker, connectionOptions); 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); session.acknowledge(); connection.close(); return 0; } catch(const std::exception& error) { connection.close(); return 1; } } Establishes the connection with the messaging broker. Creates a session object on which messages will be sent and received. Creates a receiver that receives messages from the given address. Creates a sender that sends to the given address. Receives the next message. The duration is optional, if omitted, will wait indefinitely for the next message. Acknowledges receipt of all fetched messages on the session. This informs the broker that the messages were transferred and processed by the client successfully. Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.

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 connection = Connection(broker) try: connection.open() session = connection.session() sender = session.sender(address) receiver = session.receiver(address) sender.send(Message("Hello world!")); message = receiver.fetch(timeout=1) print message.content session.acknowledge() except MessagingError,m: print m finally: connection.close() Establishes the connection with the messaging broker. Creates a session object on which messages will be sent and received. Creates a receiver that receives messages from the given address. Creates a sender that sends to the given address. Receives the next message. The duration is optional, if omitted, will wait indefinitely for the next message. Acknowledges receipt of all fetched messages on the session. This informs the broker that the messages were transfered and processed by the client successfully. Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.

A Simple Messaging Program in .NET C# The following .NET C# The .NET binding for the Qpid C++ Messaging API applies to all .NET Framework managed code languages. C# was chosen for illustration purposes only. program shows how to create a connection, create a session, send messages using a sender, and receive messages using a receiver. "Hello world!" in .NET C# using System; using Org.Apache.Qpid.Messaging; namespace Org.Apache.Qpid.Messaging { class Program { static void Main(string[] args) { String broker = args.Length > 0 ? args[0] : "localhost:5672"; String address = args.Length > 1 ? args[1] : "amq.topic"; Connection connection = null; try { connection = new Connection(broker); connection.Open(); Session session = connection.CreateSession(); Receiver receiver = session.CreateReceiver(address); Sender sender = session.CreateSender(address); sender.Send(new Message("Hello world!")); Message message = new Message(); message = receiver.Fetch(DurationConstants.SECOND * 1); Console.WriteLine("{0}", message.GetContent()); session.Acknowledge(); connection.Close(); } catch (Exception e) { Console.WriteLine("Exception {0}.", e); if (null != connection) connection.Close(); } } } } Permits use of Org.Apache.Qpid.Messaging types and methods without explicit namespace qualification. Any .NET project must have a project reference to the assembly file Org.Apache.Qpid.Messaging.dll in order to obtain the definitions of the .NET Binding for Qpid Messaging namespace. Establishes the connection with the messaging broker. Creates a session object on which messages will be sent and received. Creates a receiver that receives messages from the given address. Creates a sender that sends to the given address. Receives the next message. The duration is optional, if omitted, will wait indefinitely for the next message. Acknowledges receipt of all fetched messages on the session. This informs the broker that the messages were transfered and processed by the client successfully. Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.

Addresses An address is the name of a message target or message source. In the programs we have just seen, we used amq.topic as the default address if none is passed in. This is the name of a standard exchange that always exists 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 C++, Python, and .NET C# 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 C++, Python, and .NET 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 hello-world $ ./drain 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 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 hello-world $ ./drain 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 -t 30 hello-word Second Window: $ ./spout 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 only used simple names. 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. This is discussed in . Currently, a receiver bound to a queue ignores subjects, receiving messages from the queue without filtering. Support for subject filtering on queues will be implemented soon. 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 -t 30 news-service/sports In a second window, let's send messages to news-service using two different subjects: Second Window: $ ./spout news-service/sports $ ./spout 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 -t 30 news-service/*.news Now let's send messages using several different two-word keys: Second Window: $ ./spout news-service/usa.news $ ./spout news-service/usa.sports $ ./spout news-service/europe.sports $ ./spout 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 -t 30 news-service/#.news In the second window, let's send messages using a variety of different multi-word keys: Second Window: $ ./spout news-service/news $ ./spout news-service/sports $ ./spout news-service/usa.news $ ./spout news-service/usa.sports $ ./spout news-service/usa.faux.news $ ./spout 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 can 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. Extension points providing more direct control over the underlying protocol. For instance, the x-bindings property allows greater control over the AMQP 0-10 binding process when an address is resolved. Let's use some examples to show how these different kinds of address string options affect the behavior of senders and receives.

assert In this section, we 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 'my-queue; {assert: always, node:{ type: queue }}' $ ./drain '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 'my-topic; {assert: always, node:{ type: topic }}' $ ./drain '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:

create 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. Creating a Queue Automatically First Window: $ ./drain -t 30 "xoxox ; {create: always}" Now we can send messages to this queue: Second Window: $ ./spout "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='') The details of the node thus created can be controlled by further options within the node. See for details.

browse Some 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 my-queue --content one $ ./spout my-queue --content two $ ./spout my-queue --content three Now we use drain to get those messages, using the browse option: $ ./drain '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 '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')

x-bindings Greater control over the AMQP 0-10 binding process can be achieved by including an x-bindings option in an address string. For instance, 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. The xquery is specified in the arguments field of the AMQP 0-10 command. When using the messaging API an xquery can be specified in and address that resolves to an XML exchange by using the x-bindings property. 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 receiver 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: When using longer queries with drain, it is often useful to place the query in a file, and use cat in the command line. We do this in the following example. Using the XML Exchange This example uses an x-binding that contains queries, which filter based on the content of XML messages. Here is an XQuery that we will use in this example: 50 and $w/temperature_f - $w/dewpoint > 5 and $w/wind_speed_mph > 7 and $w/wind_speed_mph < 20 ]]> We can specify this query in an x-binding to listen to messages that meet the criteria specified by the query: First Window: $ ./drain -f "xml; {link:{x-bindings:[{key:'weather', arguments:{xquery:\"$(cat rdu.xquery )\"}}]}}" In another window, let's create an XML message that meets the criteria in the query, and place it in the file rdu.xml: Raleigh-Durham International Airport (KRDU) 16 70 35 ]]> Now let's use spout to send this message to the XML exchange: Second Window: spout --content "$(cat rdu.xml)" xml/weather Returning to the first window, we see that the message has been received: Raleigh-Durham International Airport (KRDU) 16 40 35 ') ]]>

Address String Options - Reference 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 the queue once the client acknowledges their receipt.

Node Properties property value semantics type topic, queue Indicates the type of the node. 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 Reliability indicates the level of reliability that the sender or receiver. unreliable and at-most-once are currently treated as synonyms, and allow messages to be lost if a broker crashes or the connection to a broker is lost. at-least-once guarantees that a message is not lost, but duplicates may be received. exactly-once guarantees that a message is not lost, and is delivered precisely once. Currently only unreliable and at-least-once are supported. If at-most-once is requested, unreliable will be used and for durable messages on durable queues there is the possibility that messages will be redelivered; if exactly-once is requested, at-most-once will be used and the application needs to be able to deal with duplicates. 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

Sender Capacity and Replay The send method of a sender has an optional second parameter that controls whether the send call is synchronous or not. A synchronous send call will block until the broker has confirmed receipt of the message. An asynchronous send call will return before the broker confirms receipt of the message, allowing for example further send calls to be made without waiting for a roundtrip to the broker for each message. This is desirable where increased throughput is important. The sender maintains a list of sent messages whose receipt has yet to be confirmed by the broker. The maximum number of such messages that it will hold is defined by the capacity of the sender, which can be set by the application. If an application tries to send with a sender whose capacity is already fully used up, the send call will block waiting for capacity regardless of the value of the sync flag. The sender can be queried for the available space (i.e. the unused capacity), and for the current count of unsettled messages (i.e. those held in the replay list pending confirmation by the server). When the unsettled count is zero, all messages on that sender have been successfully sent. If the connection fails and is transparently reconnected (see for details on how to control this feature), the unsettled messages for each sender over that connection will be re-transmitted. This provides a transparent level of reliability. This feature can be controlled through the link's reliability as defined in the address (see ). At present only at-least-once guarantees are offered.

Receiver Capacity (Prefetch) By default, a receiver requests the next message from the server in response to each fetch call, resulting in messages being sent to the receiver one at a time. As in the case of sending, it is often desirable to avoid this roundtrip for each message. This can be achieved by allowing the receiver to prefetch messages in anticipation of fetch calls being made. The receiver needs to be able to store these prefetched messages, the number it can hold is controlled by the receivers capacity.

Acknowledging Received Messages Applications that receive messages should acknowledge their receipt by calling the session's acknowledge method. As in the case of sending messages, acknowledged transfer of messages to receivers provides at-least-once reliability, which means that the loss of the connection or a client crash does not result in lost messages; durable messages are not lost even if the broker is restarted. Some cases may not require this however and the reliability can be controlled through a link property in the address options (see ). The acknowledge call acknowledges all messages received on the session (i.e. all message that have been returned from a fetch call on a receiver created on that session). The acknowledge call also support an optional parameter controlling whether the call is synchronous or not. A synchronous acknowledge will block until the server has confirmed that it has received the acknowledgement. In the asynchronous case, when the call returns there is not yet any guarantee that the server has received and processed the acknowledgement. The session may be queried for the number of unsettled acknowledgements; when that count is zero all acknowledgements made for received messages have been successful.

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. 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 examples show how this is done in C++, Python, and .NET C#. Note that to use this pattern you must enable prefetching for each receiver of interest so that the broker will send messages before a fetch call is made. See for more on this. Receiving Messages from Multiple Sources C++: Python: .NET C#:

Transactions Sometimes it is useful to be able to group messages transfers - sent and/or received - on a session into atomic grouping. This can be done be creating the session as transactional. On a transactional session sent messages only become available at the target address on commit. Likewise any received and acknowledged messages are only discarded at their source on commit Note that this currently is only true for messages received using a reliable mode e.g. at-least-once. Messages sent by a broker to a receiver in unreliable receiver will be discarded immediately regardless of transctionality. . Transactions C++: .NET C#: Connection connection = new Connection(broker); Session session = connection.CreateTransactionalSession(); ... if (smellsOk()) session.Commit(); else session.Rollback();

Connection Options Aspects of the connections behaviour can be controlled through specifying connection options. For example, connections can be configured to automatically reconnect if the connection to a broker is lost. Specifying Connection Options in C++, Python, and .NET In C++, these options can be set using Connection::setOption() or by passing in a set of options to the constructor. The options can be passed in as a map or in string form: or In Python, these options can be set as attributes of the connection or using named arguments in the Connection constructor: or In .NET, these options can be set using Connection.SetOption() or by passing in a set of options to the constructor. The options can be passed in as a map or in string form: Connection connection= new Connection("localhost:5672", "{reconnect: true}"); try { connection.Open(); !!! SNIP !!! or Connection connection = new Connection("localhost:5672"); connection.SetOption("reconnect", true); try { connection.Open(); !!! SNIP !!! See the reference documentation for details in each language. The following table lists the supported connection options. Connection Options option name value type semantics username string The username to use when authenticating to the broker. password string The password to use when authenticating to the broker. sasl_mechanisms string The specific SASL mechanisms to use with the python client when authenticating to the broker. The value is a space separated list. reconnect boolean Transparently reconnect if the connection is lost. reconnect_timeout integer Total number of seconds to continue reconnection attempts before giving up and raising an exception. reconnect_limit integer Maximum number of reconnection attempts before giving up and raising an exception. reconnect_interval_min integer representing time in seconds 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 integer representing time in seconds Maximum reconnect interval. reconnect_interval integer representing time in seconds Sets both reconnection_interval_min and reconnection_interval_max to the same value. heartbeat integer representing time in seconds Requests that heartbeats be sent every N seconds. If two successive heartbeats are missed the connection is considered to be lost. protocol string Sets the underlying protocol used. The default option is 'tcp'. To enable ssl, set to 'ssl'. The C++ client additionally supports 'rdma'. tcp-nodelay boolean Set tcp no-delay, i.e. disable Nagle algorithm. [C++ only]

Maps and Lists in Message Content Many messaging applications need to exchange data across languages and platforms, using the native datatypes of each programming language. The Qpid Messaging API supports map and list in message content. Unlike JMS, there is not a specific message type for map messages. Note that the Qpid JMS client supports MapMessages whose values can be nested maps or lists. This is not standard JMS behaviour. Specific language support for map and list objects are shown in the following table. Map and List Representation in Supported Languages Language map list Python dict list C++ Variant::Map Variant::List Java MapMessage .NET Dictionary<string, object> Collection<object>

In all languages, messages are encoded using AMQP's portable datatypes. Because of the differences in type systems among languages, the simplest way to provide portable messages is to rely on maps, lists, strings, 64 bit signed integers, and doubles for messages that need to be exchanged across languages and platforms.

Qpid Maps and Lists in Python In Python, Qpid supports the dict and list types directly in message content. The following code shows how to send these structures in a message: Sending Qpid Maps and Lists in Python The following table shows the datatypes that can be sent in a Python map message, and the corresponding datatypes that will be received by clients in Java or C++. Python Datatypes in Maps Python Datatype → C++ → Java boolboolbooleanintint64longlongint64longfloatdoubledoubleunicodestringjava.lang.Stringuuidqpid::types::Uuidjava.util.UUIDdictVariant::Mapjava.util.MaplistVariant::Listjava.util.List

Qpid Maps and Lists in C++ In C++, Qpid defines the the Variant::Map and Variant::List types, which can be encoded into message content. The following code shows how to send these structures in a message: Sending Qpid Maps and Lists in C++ The following table shows the datatypes that can be sent in a C++ map message, and the corresponding datatypes that will be received by clients in Java and Python. C++ Datatypes in Maps C++ Datatype → Python → Java boolboolbooleanuint16int | longshortuint32int | longintuint64int | longlongint16int | longshortint32int | longintint64int | longlongfloatfloatfloatdoublefloatdoublestringunicodejava.lang.Stringqpid::types::Uuiduuidjava.util.UUIDVariant::Mapdictjava.util.MapVariant::Listlistjava.util.List

Qpid Maps and Lists in .NET The .NET binding for the Qpid Messaging API binds .NET managed data types to C++ Variant data types. The following code shows how to send Map and List structures in a message: Sending Qpid Maps and Lists in .NET C# content = new Dictionary(); Dictionary subMap = new Dictionary(); Collection