Menu Search

5.3. Connection

A Connection represents an open communication channel between application and Broker.

Connections are created from the ConnectionFactory [4].

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 conditions 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.

5.3.1. Failover

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 retries and 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

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

amqp://username:password@clientid/test
            ?brokerlist='tcp://localhost:15672?failover='nofailover'
        


5.3.2. Heartbeating

Qpid connections support heartbeating. When enabled, the 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.

To enable heartbeating either use a Connection URL including the broker option heartbeat, or use the system property qpid.heartbeat.

Example 5.3. Connection URL configured for heartbeating

amqp://guest:guest@clientid/?brokerlist='localhost:5672?heartbeat='5''
        

5.3.3. SSL

The 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

    amqp://guest:guest@clientid/?brokerlist='localhost:5671'&ssl='true'
                

  • 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 and 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

    amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/acme_org_ca.ts'&trust_store_password='secret''&ssl='true'
                

  • SSL with SSL client-auth. For this case, we use key_store and key_store_password to specify a path a keystore file (containing the certificate of the client) and the keystore password.

    Example 5.6. Connection URL configured for SSL - SSL client-auth

    amqp://guest:guest@clientid/?brokerlist='localhost:5671?key_store='/path/to/app1_client_cert.ks'&key_store_password='secret''&ssl='true'
                

    Alternatively we can use client_cert_path and client_cert_priv_key_ath to specify a path to a certificate file (in PEM or DER format) and the private key information (again in either PEM or DER format) respectively.

    Example 5.7. Connection URL configured for SSL - SSL client-auth (2)

    amqp://guest:guest@clientid/?brokerlist='localhost:5671?client_cert_path='/path/to/app1_client.crt'&client_cert_priv_key_path='/path/to/app1_client.key''&ssl='true'
                

5.3.4. Message Compression

The client has the ability to transparently compress message payloads on outgoing messages and decompress them on incoming messages. In some environments and with some payloads this feature might offer performance improvements by reducing the number of bytes transmitted over the connection.

In order to make use of message compression, the Broker must enable the feature too, otherwise the compression options will be ignored.

To enable message compression on the client use the connection url property compressMessages (or JVM wide using the system property qpid.connection_compress_messages)

It is also possible to control the threshold at which the client will begin to compress message payloads. See connection url property messageCompressionThresholdSize (or JVM wide using the system property qpid.message_compression_threshold_size)

Note

The Broker, where necessary, takes care of compressing/decompressing messages of the fly so that clients using message compression can exchange messages with clients not supporting message compression transparently, without application intervention.



[4] Constructors of the AMQConnection class must not be used.