Using automatic JMS client reconnection

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

Automatic client reconnection can be used to reconnect to queue managers including those that are part of a high availability (HA) configuration. HA configurations include multi-instance queue managers, RDQM queue managers, or HA queue managers on an IBM MQ appliance.

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

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 that uses 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 CONNECTIONNAMELIST (Short name CRHOSTS): The CONNECTIONNAMELIST property is a comma-separated list, where each entry contains information on the host name and port that are to be used to connect to the queue manager specified by the QMANAGER property when you are using the CLIENT transport. The list has the following format: host name(port), host name(port).
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 using a CCDT.
The JMS Connection Factory property CLIENTRECONNECTOPTIONS (Short name CROPT): CLIENTRECONNECTOPTIONS controls whether the IBM MQ classes for JMS will attempt 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 that uses 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 values.
CLIENTRECONNECTOPTIONS	Behavior of IBM MQ classes for JMS
ANY	If CONNECTIONNAMELIST is set, use the value of the CONNECTIONNAMELIST property to open a connection to a host name and port combination, and connect to any queue manager. In order to use this automatic client reconnection option, the QMANAGER property must be set to either the default value or "". If CCDTURL is set, 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	Specifies that the client must reconnect to the same queue manager. This option must be used for high availability solutions, where reconnection to another instance of the same queue manager is required. If CONNECTIONNAMELIST is set, use the value of the CONNECTIONNAMELIST property to open a connection to a host name and port combination, and connect to the queue manager specified by the QMANAGER property. If CCDTURL is set, 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.

If CONNECTIONNAMELIST is set, when you perform automatic client reconnection, the IBM MQ classes for JMS uses the information in the Connection Factory property CONNNECTIONNAMELIST to determine what system to reconnect to.

The IBM MQ classes for JMS initially tries to reconnect by using the host name and port that is specified in the first entry in the CONNECTIONNAMELIST. If a connection is made, the IBM MQ classes for JMS then tries to connect to the queue manager that has the name specified in the QMANAGER property. 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 by using the first entry in the CONNECTIONNAMELIST, the IBM MQ classes for JMS tries the second entry in the CONNECTIONNAMELIST, and so on.

When the IBM MQ classes for JMS have tried all of the entries in the CONNECTIONNAMELIST, they wait for a period of time before they try to reconnect again. To perform the new reconnection attempt, the IBM MQ classes for JMS start with the first entry in the CONNECTIONNAMELIST. They then try each entry in the CONNECTIONNAMELIST in turn until either a reconnection occurs or the end of the CONNECTIONNAMELIST is reached, at which point the IBM MQ classes for JMS waits for a period of time before they try again.

If CCDTURL is set, 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.

Whether using CONNECTIONNAMELIST, or CCDTURL, the process of automatic client reconnection continues until the IBM MQ classes for JMS successfully reconnected 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 is to prevent 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 being reconnected automatically depends on its design. Read the related topics to understand how to design applications can use the automatic reconnection functionality.