Automatic JMS client reconnection with CCDTs

If a stand-alone IBM® MQ classes for JMS application uses a Connection Factory that has the CCDTURL property set, the application is eligible to use automatic client reconnection.

The behavior of the automatic client reconnection functionality that is provided by the IBM MQ classes for JMS depends on the following properties:

The JMS Connection Factory property TRANSPORT (Short name TRAN): TRANSPORT specifies how applications that use the Connection Factory connects to a queue manager. This property must be set to the value CLIENT for automatic client reconnection to be used. Automatic client reconnection is not available to applications that connect to a queue manager by using a Connection Factory that has the TRANSPORT property set to BIND, DIRECT, or DIRECTHTTP.
The JMS Connection Factory property QMANAGER (Short name QMGR): The QMANAGER property specifies the name of the queue manager that the Connection Factory connects to.
The JMS Connection Factory property CCDTURL (Short name CCDT): The CCDTURL property points to the client channel definition table that the IBM MQ classes for JMS uses when it connects to a queue manager.
The JMS Connection Factory property CLIENTRECONNECTOPTIONS (Short name CROPT): CLIENTRECONNECTOPTIONS controls whether the IBM MQ classes for JMS attempts to automatically connect to a queue manager on behalf of an application if a queue manager becomes available.
The DefRecon attribute in the Channels stanza of the client configuration file: The DefRecon attribute provides an administrative option to enable all applications to automatically reconnect, or to disable the automatic reconnection for applications that are written to reconnect automatically.

Automatic client reconnection is only available when an application successfully connects to a queue manager.

When an application connects to a queue manager by using the CLIENT transport, the IBM MQ classes for JMS use the value of the Connection Factory property CLIENTRECONNECTOPTIONS to determine whether to use automatic client reconnection, if the queue manager that the application is connected to becomes unavailable. Table 1 shows the possible values for the CLIENTRECONNECTOPTIONS property, and the behavior of the IBM MQ classes for JMS for each of these values:

Table 1. Possible CLIENTRECCECTOPTIONS property
CLIENTRECONNECTOPTIONS	Behavior of IBM MQ classes for JMS
ANY	Open the client channel definition table that is specified by the CCDTURL property, pick an entry in the table, and then use that entry to start a client connection channel to a queue manager. To use this automatic client reconnection option, the QMANAGER property must be set to either: An asterisk () An asterisk () followed by the name of a queue manager group An empty string, or a string that contains all blank characters
ASDEF	Use the value of DefRecon to determine whether automatic client reconnection is available.
DISABLED	Do not perform any automatic client reconnection and return a JMSException to the application.
QMGR	Open the client channel definition table that is specified by the CCDTURL property, find the entries in the table that match the queue manager name that is specified by the QMANAGER property and then use those entries to start a client connection channel to that queue manager.

When performing automatic client reconnection, the IBM MQ classes for JMS uses the client channel definition table that is specified in the CCDTURL property to determine what system to reconnect to.

The IBM MQ classes for JMS initially parses the client channel definition table and finds a suitable entry that matches the value of the QMANAGER property. When an entry is found, the IBM MQ classes for JMS tries to reconnect to the required queue manager using that entry. If a connection to the queue manager can be established, the IBM MQ classes for JMS reopens all of the IBM MQ objects that the application had open before automatic client reconnection and continue running as before.

If a connection cannot be established to the required queue manager, the IBM MQ classes for JMS looks for another suitable entry in the client channel definition table and tries to use that, and so on.

When the IBM MQ classes for JMS have tried all of the suitable entries in the client channel definition table, they wait for a period of time before trying to reconnect again. To perform the new reconnection attempt, the IBM MQ classes for JMS parses the client channel definition table again and tries the first suitable entry. They will then try each suitable entry in the client channel definition table in turn until either a reconnection occurs or the last suitable entry in the client channel definition table has been tried, at which point the IBM MQ classes for JMS waits for a period of time before trying again.

This process of automatic client reconnection continues until the IBM MQ classes for JMS successfully reconnects to the queue manager specified by the QMANAGER property.

By default, the reconnection attempts happen at the following intervals:

The first attempt is made after an initial delay of 1 second, plus a random element up to 250 milliseconds.
The second attempt is made 2 seconds, plus a random interval of up to 500 milliseconds, after the first attempt fails.
The third attempt is made 4 seconds, plus a random interval of up to 1 second, after the second attempt fails.
The fourth attempt is made 8 seconds, plus a random interval of up to 2 seconds, after the third attempt fails.
The fifth attempt is made 16 seconds, plus a random interval of up to 4 seconds, after the fourth attempt fails.
The sixth attempt, and all subsequent attempts are made 25 seconds, plus a random interval of up to 6 seconds and 250 milliseconds after the previous attempt fails.

The reconnection attempts are delayed by intervals that are partly fixed and partly random. This prevents all of the IBM MQ classes for JMS applications, that were connected to a queue manager that is no longer available, from reconnecting simultaneously.

If you need to increase the default values, to more accurately reflect the amount of time that is required for a queue manager to recover, or a standby queue manager to become active, modify the ReconDelay attribute in the Channel stanza of the client configuration file, for more information, see CHANNELS stanza of the client configuration file.

Whether an IBM MQ classes for JMS application continues to work correctly after it has been reconnected automatically depends on its design. Read the related topics to understand how to design applications that can use the automatic reconnection functionality.