The Qpid Messaging API supports automatic reconnect, guaranteed delivery via persistent messages, reliability options in senders and receivers, and cluster failover. This section shows how programs can take advantage of these features.
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.
Example 2.18. Specifying Connection Options in C++ and Python
In C++, these options are set using Connection::setOption():
Connection connection(broker);
connection.setOption("reconnect", true);
try {
connection.open();
!!! SNIP !!!
In Python, these options are set using named arguments in
the Connection constructor:
connection = Connection("localhost:5672", reconnect=True)
try:
connection.open()
!!! SNIP !!!
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.
Table 2.6. 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.
|
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.
Example 2.19. Guaranteed Delivery
C++:
Sender sender = session.createSender("durable-queue");
Message message("Hello world!");
message.setDurable(1);
sender.send(Message("Hello world!"));
When creating a sender or a receiver, you can specify a reliability option in the address string. For instance, the following specifies at-least-once as the reliability mode for a sender:
Sender = session.createSender("topic;{create:always,link:{reliability:at-least-once}}");
The modes unreliable, at-most-once, at-least-once, and exactly-once are supported. These modes govern the reliability of the connection between the client and the messaging broker.
The modes unreliable and at-most-once are currently synonyms. In a receiver, this mode means that messages received on an auto-delete subscription queue may be lost in the event of a broker failure. In a sender, this mode means that the sender can consider a message sent as soon as it is written to the wire, and need not wait for broker acknowledgement before considering the message sent.
The mode at-most-once ensures that messages are not lost, but duplicates of a message may occur. In a receiver, this mode ensures that messages are not lost in event of a broker failure. In a sender, this means that messages are kept in a replay buffer after they have been sent, and removed from this buffer only after the broker acknowledges receipt; if a broker failure occurs, messages in the replay buffer are resent upon reconnection. The mode exactly-once is similar to at-most-once, but eliminates duplicate messages.
The messaging broker can be run in clustering mode, which provides high reliability at-least-once messaging. If one broker in a cluster fails, clients can choose another broker in the cluster and continue their work.
In C++, the FailoverUpdates class keeps track of the brokers in a cluster, so a reconnect can select another broker in the cluster to connect to:
Example 2.20. Cluster Failover in C++
#include <qpid/messaging/FailoverUpdates.h>
...
Connection connection(broker);
connection.setOption("reconnect", true);
try {
connection.open();
std::auto_ptr<FailoverUpdates> updates(new FailoverUpdates(connection));