Automatic balancing of JMS applications

When Jakarta Messaging 3.0 or Java Message Service 2.0 applications are balanced automatically, the underlying groups of IBM® MQ connections that JMS applications create are moved together.

From IBM MQ 9.3.0, the dynamicallyBalanced property is available when configuring ActivationSpecs. This property specifies whether an MDB can be requested to receive messages from a different queue manager as part of application balancing in a uniform cluster. For more information, see Configuring the resource adapter for inbound communication.

For handling JMS connections, uniform clusters have the concept of an application instance. For JMS, an application instance is defined as a JMS Connection and all its associated JMS Sessions.

A unique connection tag is allocated on the client connection that corresponds to the JMS Connection, and the same tag is then applied to the client connections that correspond to JMS Sessions that are created by that JMS Connection.

For example, if a pair of client applications are running JMS applications against a uniform cluster with a single active queue manager (Queue Manager 1):

Client 1 creates a connection factory on which it sets an application name of "App1", and creates a JMS Connection and three JMS Sessions. Client 1 creates four client connections in Queue Manager 1 each sharing the same connection tag, and this is treated as a single instance of "App1".
Client 2 also creates a connection factory on which it sets an application name of "App1", and creates a JMS Connection and two JMS Sessions. Client 2 creates three client connections each sharing the same connection tag (distinct from that assigned to Client 1), and this is treated as a single, separate, instance of "App1".
So the queue manager sees two instances of "App1"

When automatic balancing is performed, application instances are moved. A queue manager chooses an application instance (a group of client connections sharing the same connection tag) and requests that the instance moves to a different queue manager. The client code receives the request and ensures that all the related connections (corresponding to a JMS Connection and its associated JMS Sessions) move to the new queue manager.

For example, take the set of application instances previously outlined, and assume that a new queue manager (Queue Manager 2) starts up in the uniform cluster.

Queue Manager 2 has no work but Queue Manager 1 has 2 instances of "App1", so Queue Manager 2 requests that Queue Manager 1 transfer an instance of "App1" to Queue Manager 2.

Queue Manager 1 chooses an instance of "App1" to be moved. For the purposes of the example, assume that it chooses the instance created by Client 1.

Queue Manager 1 sends a request to Client 1 to move its instance of "App1" to QM2.
The client closes its four existing client connections to Queue Manager 1 and creates four new connections to Queue Manager 2.
The JMS Connection and its JMS Sessions, except for a short pause in processing, should not normally be disturbed.

Note:

An application might receive a JMS exception if certain operations are in progress at the time that an application instance is moved.

The JMS exception will have a linked IBM MQ exception, from which the reason code can be retrieved to determine the cause of the failure.

The expected reason codes are as follows:

MQRC_CALL_INTERRUPTED: This occurs when, for example, a message which is persistent (the default in JMS) is put outside a syncpoint, but the operation is interrupted by a reconnection.
MQRC_BACKED_OUT: This occurs when, for example, an attempt to put a message inside a syncpoint is interrupted by a reconnection.