| <div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">5.3. Connection</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="JMS-Client-0-8-Client-Understanding-ConnectionFactory.html">Prev</a> </td><th align="center" width="60%">Chapter 5. Understanding the Client</th><td align="right" width="20%"> <a accesskey="n" href="JMS-Client-0-8-Client-Understanding-Session.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="JMS-Client-0-8-Client-Understanding-Connection"></a>5.3. Connection</h2></div></div></div><p>A Connection represents an open communication channel between application and |
| Broker.</p><p>Connections are created from the ConnectionFactory <a class="footnote" href="#ftn.d0e390" id="d0e390"><sup class="footnote">[4]</sup></a>.</p><p>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. </p><p>The underlying TCP/IP connection remains open for the lifetime of the JMS connection. It |
| is closed when the application calls <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/Connection.html#close()" target="_top">Connection#close()</a>, 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.</p><p>Qpid connections have failover and heartbeating capabilities. They support SSL and |
| client-auth. These are described in the sub-sections that follow.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-Connection-Failover"></a>5.3.1. Failover</h3></div></div></div><p>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.</p><p>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.</p><p>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 <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/TransactionRolledBackException.html" target="_top">TransactionRolledBackException</a> from the <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/Session.html#commit" target="_top">Session#commit()</a> 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.</p><p>If, after all retries are exhausted, failover has failed to reconnect the application, |
| the Connection's <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/ExceptionListener.html" target="_top">ExceptionListener</a> will receive a JMSException with a linked exception of <a class="link" href="JMS-Client-0-8-Appendix-Exceptions-AMQDisconnectedException" target="_top">AMQDisconnectedException</a>. Any further use of the JMS objects (Connection, Session |
| etc), will results in a <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/IllegalStateException.html" target="_top">IllegalStateException</a>.</p><p>Configure failover using the Connection URL. Here's an example Connection URL utilising |
| failover between two brokers. Note the use of the broker options <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-Retries"><code class="literal">retries</code></a> and <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-ConnectDelay"><code class="literal">connectdelay</code></a> to control the number of connection attempts to |
| each individual broker, and the delay between each connection attempt. Also note the use of |
| the <span class="emphasis"><em>failover option</em></span> |
| <code class="literal">cyclecount</code> to control the number of times the failover mechanism will |
| traverse the brokerlist.</p><div class="example"><a id="d0e445"></a><p class="title"><strong>Example 5.1. Connection URL configured for failover</strong></p><div class="example-contents"><pre class="screen"> |
| amqp://username:password@clientid/test |
| ?brokerlist='tcp://localhost:15672?retries='10'&connectdelay='1000';tcp://localhost:25672?retries='10'&connectdelay='1000'' |
| &failover='roundrobin?cyclecount='20'' |
| </pre></div></div><br class="example-break" /><p>For full details see <a class="xref" href="JMS-Client-0-8-Connection-URL.html" title="Chapter 7. Connection URLs">Chapter 7, <em>Connection URLs</em></a></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>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 |
| <code class="literal">nofailover</code> as in the example below </p><div class="example"><a id="d0e459"></a><p class="title"><strong>Example 5.2. Connection URL configured with nofailover</strong></p><div class="example-contents"><pre class="screen"> |
| amqp://username:password@clientid/test |
| ?brokerlist='tcp://localhost:15672?failover='nofailover' |
| </pre></div></div><p><br class="example-break" /> |
| </p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-Connection-Heartbeating"></a>5.3.2. Heartbeating</h3></div></div></div><p>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.</p><p>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.</p><p>It is also allows the both the JMS client and the Broker to confirm that the other is |
| <span class="emphasis"><em>minimally</em></span> 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.</p><p>If the client ever fails to receive two consecutive heartbeats, the Connection will be |
| automatically closed and the Connection's <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/ExceptionListener.html" target="_top">ExceptionListener</a> will |
| receive a JMSException with a linked exception of AMQDisconnectedException. Any further use |
| of the JMS objects (Connection, Session etc), will results in a <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/IllegalStateException.html" target="_top">IllegalStateException</a>.</p><p>To enable heartbeating either use a Connection URL including the broker option <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-Heartbeat"><code class="literal">heartbeat</code></a>, or use the system property <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-Heartbeat"><code class="literal">qpid.heartbeat</code></a>. </p><div class="example"><a id="d0e495"></a><p class="title"><strong>Example 5.3. Connection URL configured for heartbeating</strong></p><div class="example-contents"><pre class="screen"> |
| amqp://guest:guest@clientid/?brokerlist='localhost:5672?heartbeat='5'' |
| </pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-Connection-SSL"></a>5.3.3. SSL</h3></div></div></div><p>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.</p><p>Some example Connection URLs using SSL follow:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Simple SSL when the Broker is secured by a certificate that is signed by a CA which |
| is trusted by the JVM.</p><div class="example"><a id="d0e511"></a><p class="title"><strong>Example 5.4. Connection URL configured for SSL - CA trusted by JVM</strong></p><div class="example-contents"><pre class="screen"> |
| amqp://guest:guest@clientid/?brokerlist='localhost:5671'&ssl='true' |
| </pre></div></div><br class="example-break" /></li><li class="listitem"><p>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 <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-TrustStore"><code class="literal">trust_store</code></a> and <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-TrustStorePassword"><code class="literal">trust_store_password</code></a> to specify a path a truststore file |
| (containing the certificate of the private-CA) and the truststore password.</p><div class="example"><a id="d0e527"></a><p class="title"><strong>Example 5.5. Connection URL configured for SSL - CA not trusted by JVM</strong></p><div class="example-contents"><pre class="screen"> |
| amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/acme_org_ca.ts'&trust_store_password='secret''&ssl='true' |
| </pre></div></div><br class="example-break" /></li><li class="listitem"><p>SSL with SSL client-auth. For this case, we use <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-KeyStore"><code class="literal">key_store</code></a> and <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-KeyStorePassword"><code class="literal">key_store_password</code></a> to specify a path a keystore file |
| (containing the certificate of the client) and the keystore password.</p><div class="example"><a id="d0e543"></a><p class="title"><strong>Example 5.6. Connection URL configured for SSL - SSL client-auth</strong></p><div class="example-contents"><pre class="screen"> |
| amqp://guest:guest@clientid/?brokerlist='localhost:5671?key_store='/path/to/app1_client_cert.ks'&key_store_password='secret''&ssl='true' |
| </pre></div></div><br class="example-break" /><p>Alternatively we can use <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-ClientCertPath"><code class="literal">client_cert_path</code></a> and <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-ClientCertPrivKeyPath"><code class="literal">client_cert_priv_key_ath</code></a> 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.</p><div class="example"><a id="d0e558"></a><p class="title"><strong>Example 5.7. Connection URL configured for SSL - SSL client-auth (2)</strong></p><div class="example-contents"><pre class="screen"> |
| 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' |
| </pre></div></div><br class="example-break" /></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-Connection-MessageCompression"></a>5.3.4. Message Compression</h3></div></div></div><p>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.</p><p>In order to make use of message compression, the Broker must enable the feature too, |
| otherwise the compression options will be ignored.</p><p> To enable message compression on the client use the connection url property <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-ConnectionOptions-CompressMessages"><code class="literal">compressMessages</code></a> (or JVM wide using the system property <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-ConnectionCompressMessages"><code class="literal">qpid.connection_compress_messages</code></a>)</p><p>It is also possible to control the threshold at which the client will begin to compress |
| message payloads. See connection url property <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-ConnectionOptions-MessageCompressionThresholdSize"><code class="literal">messageCompressionThresholdSize</code></a> (or JVM wide using the system |
| property <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-MessageCompressionThresholdSize"><code class="literal">qpid.message_compression_threshold_size</code></a>)</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>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.</p></div></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div class="footnote" id="ftn.d0e390"><p><a class="para" href="#d0e390"><sup class="para">[4] </sup></a>Constructors of the AMQConnection class must not be used.</p></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="JMS-Client-0-8-Client-Understanding-ConnectionFactory.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="JMS-Client-0-8-Client-Understanding.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="JMS-Client-0-8-Client-Understanding-Session.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">5.2. ConnectionFactory </td><td align="center" width="20%"><a accesskey="h" href="JMS-Client-Book.html">Home</a></td><td align="right" valign="top" width="40%"> 5.4. Session</td></tr></table></div></div> |
