Use connection property override in IBM MQ classes for Java

In the IBM MQ classes for Java, connection details are set as properties using a combination of different values. The connection override functionality can be used to override the connection details that an application uses if it is not possible to modify the source code for the application.

About this task

The different values that are used to set the connection properties are a combination of:

• Assigning values to static fields on the MQEnvironment class.
• Set property values in the properties Hashtable in the MQEnvironment class.
• Set property values in a Hashtable passed into an MQQueueManager constructor.

These properties are then used when an application constructs an MQQueueManager object, which represents a connection to a queue manager.

If it is not possible to modify the source code for an application that uses the IBM MQ classes for Java to specify different properties that must be used when creating a connection to a queue manager, the connection override functionality allows you to override the connection details in the short term. In the long term, though, we must put plans in place to allow the connection details used by the application to be modified without using the connection override functionality.

When an application creates an MQQueueManager, the IBM MQ classes for Java look at the properties that have been overridden and use those property values when creating a connection to the queue manager, rather than the values in any of the following locations:

• The static fields on the MQEnvironment class
• The properties Hashtable stored in the MQEnvironment class
• The properties Hashtable that is passed into an MQQueueManager constructor

For example, suppose an application creates an MQQueueManager, passing in a properties Hashtable that has the CHANNEL property set to MY.OLD.CHANNEL. If the connection override functionality has been used to set the CHANNEL property to MY.NEW.CHANNEL, then when the MQQueueManager is constructed, the IBM MQ classes for Java attempt to create a connection to the queue manager by using the channel MY.NEW.CHANNEL rather than MY.OLD.CHANNEL.

Note: If an MQQueueManager is configured to use a Client Channel Definition Table (CCDT), then the information in the CCDT is used in preference to the overridden properties. If the connection details that the application creating the MQQueueManager uses need to be changed, then a new version of the CCDT must be created and made available to the application. To modify any of the connection properties that are used when creating an MQQueueManager, the following steps need to be carried out:

1. Create a properties file called mqclassesforjava.config.
2. Enable the connection property override functionality by setting the OverrideConnectionDetails property to true.
3. Start the application, specifying the configuration file as part of the Java invocation.

Procedure

1. Create a properties file called mqclassesforjava.config containing the properties and values that need to be overridden. It is possible to override 13 properties that are used by the IBM MQ classes for Java when connecting to a queue manager as part of the MQQueueManager constructor. The names of these properties, and the keys that must be specified when we are overriding them, are shown in the following table:

   Property	Property key
   CCSID	$CCSID_PROPERTY
   Channel	$CHANNEL_PROPERTY
   Connect options	$CONNECT_OPTIONS_PROPERTY
   Hostname	$HOST_NAME_PROPERTY
   SSL key reset	$SSL_RESET_COUNT_PROPERTY
   Local address	$LOCAL_ADDRESS_PROPERTY
   Queue manager name	qmgr
   Password	$PASSWORD_PROPERTY
   Port	$PORT_PROPERTY
   Cipher suite	$SSL_CIPHER_SUITE_PROPERTY
   FIPS required	$SSL_FIPS_REQUIRED_PROPERTY
   SSL peer name	$SSL_PEER_NAME_PROPERTY
   User ID	$USER_ID_PROPERTY
   Application name	$APPNAME_PROPERTY

   Note: All of the property keys start with the $ character, except for the queue manager name. The reason for this is because the queue manager name is passed in to the MQQueueManager constructor as an argument, rather than being set as either a static field on the MQEnvironment class, or a property in a Hashtable, and so internally this property needs to be treated slightly differently from the other properties. To override a property, add an entry in the following format to the properties file:

   mqj.property key=value
   

   For example, to set the name of the channel to be used when creating MQQueueManager objects, you can add the following entry to the properties file:

   mqj.$CHANNEL_PROPERTY=MY.NEW.CHANNEL
   

   To change the name of the queue manager that an MQQueueManager object connects to, we can add the following entry to the properties file:

   mqj.qmgr=MY.OTHER.QMGR
   

2. Enable the connection override functionality by setting the com.ibm.mq.overrideConnectionDetails property to be true. Setting the property com.ibm.mq.overrideConnectionDetails to be true means that the properties that are specified in the properties file are used to override the values specified in the application. We can either set the extra property as another property in the configuration file itself, or pass the property as a system property, by using:

   -Dcom.ibm.mq.overrideConnectionDetails=true
   

   The file specified by overrideConnectionDetailsFile contains a list of properties prefixed by mqj. Applications need to define the mqj.APPNAME property. The value of the mqj.APPNAME property specifies the name used to identify the connection to the queue manager, with only the first 28 characters are used. For example:

   mqj.APPNAME=ExampleApplName

   The MQC.APPNAME_PROPERTY is defined with the value APPNAME. We can pass this value to the MQQueueManager constructor, with only the first 28 characters being used. For example:

   Hashtable properties = new Hashtable();
   properties.Add( MQC.APPNAME_PROPERTY, "ExampleApplName" );
   MQQueueManager qMgr = new MQQueueManager("qmgrname", properties);
   

   The AppName property has been added to the MQEnvironment class, with only the first 28 characters being used. For example:

   MQEnvironment.AppName = "ExampleApplName";

3. Start the application. Pass the properties file you created to the client application at run time by setting the Java system property:

   -Dcom.ibm.msg.client.config.location 
   

   Note that the location of the configuration file must be specified as a URI, for example:

   -Dcom.ibm.msg.client.config.location=file:///classesforjava/mqclassesforjava.config
   

Parent topic: Use IBM MQ connection property override