A Connection represents an open communication channel between application and Broker.
Connections are created from the ConnectionFactory .
Each connection utilises a single TCP/IP connection between the process of the application and the process of the Broker. The act of establishing a connection is therefore a relatively expensive operation. It is recommended that the same connection is used for a series of message interactions. Patterns utilising a connection per message should not be used.
The underlying TCP/IP connection remains open for the lifetime of the JMS connection. It is closed when the application calls Connection#close(), but it can also be closed if the connection is closed from the Broker side (via a Management operation or broker shutdown or running into coditions which AMQP specifications treats as errors and mandates closing the connection). The JMS connection will also be closed if the underlying TCP/IP connection is broken.
Qpid connections have failover and heartbeating capabilities. They support SSL and client-auth. These are described in the sub-sections that follow.
Qpid connections support a failover feature. This is the ability to automatically re-establish a failed connection, either to the same Broker, or the next Broker in the broker list.
This failover process is done in a manner that is mostly transparent to the application. After a successful failover, any existing Connection, Session, MessageConsumer and MessageProducer objects held by the application remain valid.
If a failover occurs during the scope of a JMS Transaction, any work performed by that transaction is lost. The application is made aware of this loss by way of the TransactionRolledBackException from the Session#commit() call. Applications utilising failover must be prepared to catch this exception and respond by either repeating the work of the transaction, or by propagating a rollback to the originating system.
If, after all retries are exhausted, failover has failed to reconnect the application, the Connection's ExceptionListener will receive a JMSException with a linked exception of AMQDisconnectedException. Any further use of the JMS objects (Connection, Session etc), will results in a IllegalStateException.
Configure failover using the Connection URL. Here's an example Connection URL utilising
failover between two brokers. Note the use of the broker options
connectdelay to control the number of connection attempts to
each individual broker, and the delay between each connection attempt. Also note the use of
the failover option
cyclecount to control the number of times the failover mechanism will
traverse the brokerlist.
Example 5.1. Connection URL configured for failover
amqp://username:password@clientid/test ?brokerlist='tcp://localhost:15672?retries='10'&connectdelay='1000';tcp://localhost:25672?retries='10'&connectdelay='1000'' &failover='roundrobin?cyclecount='20''
For full details see Chapter 7, Connection URLs
Note, that a single broker failover is enabled by default. If the failover behaviour is not desired it can be switched off by setting a failover option to nofailover as in the example below
Example 5.2. Connection URL configured with nofailover
Qpid connections support heartbeating. When enabled, the Qpid JMS client and Broker exchange a heartbeat during periods of inactivity. This allows both peers to discover if the TCP/IP connection becomes inoperable in a timely manner.
This feature is sometimes useful in applications that must traverse firewalls as the heartbeat prevents connections from being closed during periods when there is no application traffic.
It is also allows the both the JMS client and the Broker to confirm that the other is minimally responsive. (It does nothing however to determine the health of the higher level tiers of application, for this reason, applications may implement an application level heartbeat either in addition to, or instead of the heartbeat.
If the client ever fails to receive two consecutive heartbeats, the Connection will be automatically closed and the Connection's ExceptionListener will receive a JMSException with a linked exception of AMQDisconnectedException. Any further use of the JMS objects (Connection, Session etc), will results in a IllegalStateException.
Example 5.3. Connection URL configured for heartbeating
The Qpid JMS client supports connections encrypted using Secure Socket Layer (SSL) and SSL-Client Authentication. SSL is configured using Connection URL. To use SSL, SSL must be be configured on the Broker.
Some example Connection URLs using SSL follow:
Simple SSL when the Broker is secured by a certificate that is signed by a CA which is trusted by the JVM.
Example 5.4. Connection URL configured for SSL - CA trusted by JVM
SSL when the Broker is secured by a certificate that is signed by a CA which is NOT
trusted by the JVM (such as when a organisation is using a private CA, or self-signed
certificates are in use). For this case, we use
trust_store_password to specify a path a truststore file
(containing the certificate of the private-CA) and the truststore password.
Example 5.5. Connection URL configured for SSL - CA not trusted by JVM
Example 5.6. Connection URL configured for SSL - SSL client-auth
 Constructors of the AMQConnection class must not be used.
Apache Qpid, Messaging built on AMQP; Copyright © 2013 The Apache Software Foundation; Licensed under the Apache License, Version 2.0; Apache Qpid, Qpid, Qpid Proton, Proton, Apache, the Apache feather logo, and the Apache Qpid project logo are trademarks of The Apache Software Foundation; All other marks mentioned may be trademarks or registered trademarks of their respective owners