Application Instances in IBM MQ classes for JMS/Jakarta Messaging

By default, the IBM® MQ classes for JMS and IBM MQ classes for Jakarta Messaging providers treat all IBM MQ client connections that are created for the same JMSConnection or JMSContext object as a single application instance.

An individual IBM MQ connection is created for each JMSSession object that is allocated under a JMSConnection object but these connections share the same socket (where SHARECNV settings permit) and are allocated the same CONNTAG value. If uniform clusters are in use, these connections move as a unit if the application instance is rebalanced to a new queue manager.

Discrete JMS connections are considered unrelated; each JMSConnection or JMSContext object represents a discrete application instance. This behavior is desirable in some situations, such as an application server environment that is running many distinct application threads within a single large Java virtual machine process.

JVM mode

From IBM MQ 9.4.2, you can specify a mode of operation in which all IBM MQ connections from the entire Java process (the Java virtual machine) are treated as a single application instance, regardless of JMS connection affinity. This behavior might be more desirable for some styles of microservice application, with implicit coupling between a relatively small number of connections that always run within the same Java virtual machine.

Specify this mode of operation by using one of the following methods:

Set the following environment variable: AMQ_APP_INSTANCE_MODE=JVM.
Set the following Java system property on the command line when you run the application: com.ibm.mq.cfg.jmqi.AppInstanceMode=JVM. For example:
```
java -Dcom.ibm.mq.cfg.jmqi.AppInstanceMode=JVM MyApplication
```

If you use both methods, the system property takes precedence. To change the mode of operation back to the default setting (for example, if the default JVM properties file sets the mode to JVM and you want to override that on the command line), use the value JMSConnection.

An application can modify the Java system property after you start the Java process. However, the application must not modify the property after it has established MQ connections.

When you use this mode, the queue manager shows an extra IBM MQ connection handle. This handle represents the control connection for the application instance. This handle is in addition to handles that are created on behalf of JMSConnection and JMSSession objects and persists until the last JMSConnection object from this application disconnects.

JVM mode restrictions

This mode of operation imposes restrictions on the IBM MQ JMS connections that the application makes. For connections to be treated as a single application instance, all their relevant options must be compatible:

All connections must specify the same queue manager name (QMANAGER). If a connection uses a queue manager group style name (*qMgrName, where * is followed by the name of the queue manager), which is common in a uniform cluster, all connections must specify the same group name.
All connections must be reconnectable and specify the same reconnect option values (QMR or ANY, as described in Using the CLIENTRECONNECTOPTIONS property to enable automatic client reconnection within the IBM MQ classes for JMS).
All connections must specify the same application name (APPLICATIONNAME, also known in some places as APPLTAG).

If two connections have options that do not match, the later connection is rejected.