JBoss.orgCommunity Documentation

Chapter 34. Client Reconnection and Session Reattachment

34.1. 100% Transparent session re-attachment
34.2. Session reconnection
34.3. Configuring reconnection/reattachment attributes
34.4. ExceptionListeners and SessionFailureListeners

HornetQ clients can be configured to automatically reconnect or re-attach to the server in the event that a failure is detected in the connection between the client and the server.

If the failure was due to some transient failure such as a temporary network failure, and the target server was not restarted, then the sessions will still be existent on the server, asssuming the client hasn't been disconnected for more than connection-ttl Chapter 17, Detecting Dead Connections.

In this scenario, HornetQ will automatically re-attach the client sessions to the server sessions when the connection reconnects. This is done 100% transparently and the client can continue exactly as if nothing had happened.

The way this works is as follows:

As HornetQ clients send commands to their servers they store each sent command in an in-memory buffer. In the case that connection failure occurs and the client subsequently reattaches to the same server, as part of the reattachment protocol the server informs the client during reattachment with the id of the last command it successfully received from that client.

If the client has sent more commands than were received before failover it can replay any sent commands from its buffer so that the client and server can reconcile their states.

The size of this buffer is configured by the ConfirmationWindowSize parameter, when the server has received ConfirmationWindowSize bytes of commands and processed them it will send back a command confirmation to the client, and the client can then free up space in the buffer.

If you are using JMS and you're using the JMS service on the server to load your JMS connection factory instances into JNDI then this parameter can be configured in hornetq-jms.xml using the element confirmation-window-size a. If you're using JMS but not using JNDI then you can set these values directly on the HornetQConnectionFactory instance using the appropriate setter method.

If you're using core you can set these values directly on the ClientSessionFactory instance using the appropriate setter method.

The window is specified in bytes.

Setting this parameter to -1 disables any buffering and prevents any re-attachment from occurring, forcing reconnect instead. The default value for this parameter is -1. (Which means by default no auto re-attachment will occur)

Alternatively, the server might have actually been restarted after crashing or being stopped. In this case any sessions will no longer be existent on the server and it won't be possible to 100% transparently re-attach to them.

In this case, HornetQ will automatically reconnect the connection and recreate any sessions and consumers on the server corresponding to the sessions and consumers on the client. This process is exactly the same as what happens during failover onto a backup server.

Client reconnection is also used internally by components such as core bridges to allow them to reconnect to their target servers.

Please see the section on failover Section 39.2.1, “Automatic Client Failover” to get a full understanding of how transacted and non-transacted sessions are reconnected during failover/reconnect and what you need to do to maintain once and only once delivery guarantees.

Client reconnection is configured using the following parameters:

If you're using JMS, and you're using the JMS Service on the server to load your JMS connection factory instances directly into JNDI, then you can specify these parameters in the xml configuration in hornetq-jms.xml, for example:

<connection-factory name="ConnectionFactory">
   <connector-ref connector-name="netty"/>
   <entry name="ConnectionFactory"/>
   <entry name="XAConnectionFactory"/>

If you're using JMS, but instantiating your JMS connection factory directly, you can specify the parameters using the appropriate setter methods on the HornetQConnectionFactory immediately after creating it.

If you're using the core API and instantiating the ClientSessionFactory instance directly you can also specify the parameters using the appropriate setter methods on the ClientSessionFactory immediately after creating it.

If your client does manage to reconnect but the session is no longer available on the server, for instance if the server has been restarted or it has timed out, then the client won't be able to re-attach, and any ExceptionListener or FailureListener instances registered on the connection or session will be called.

Please note, that when a client reconnects or re-attaches, any registered JMS ExceptionListener or core API SessionFailureListener will be called.