Use a client channel definition table with IBM MQ classes for JMS

An IBM MQ classes for JMS application can use client connection channel definitions that are stored in a client channel definition table (CCDT). You configure a ConnectionFactory object to use the CCDT. There are some restrictions on its use.

As an alternative to creating a client connection channel definition by setting certain properties of a ConnectionFactory object, an IBM MQ classes for JMS application can use client connection channel definitions that are stored in a client channel definition table. These definitions are created by IBM MQ Script (MQSC) commands or IBM MQ Programmable Command Format (PCF) commands. When the application creates a Connection object, IBM MQ classes for JMS searches the client channel definition table for a suitable client connection channel definition, and uses the channel definition to start an MQI channel. For more information about client channel definition tables and how to construct one, see Client channel definition table.

To use a client channel definition table, the CCDTURL property of a ConnectionFactory object must be set to a URL object. IBM MQ classes for JMS do not read the information about the CCDT from the IBM MQ MQI client configuration file, although some other values are used from there (see The IBM MQ classes for JMS configuration file for which value apply). The URL object encapsulates a uniform resource locator (URL) that identifies the name and location of the file containing the client channel definition table and specifies how the file can be accessed. We can set the CCDTURL property by using the IBM MQ JMS administration tool, or an application can set the property by creating a URL object and calling the setCCDTURL() method of the ConnectionFactory object.

For example, if the file ccdt1.tab contains a client channel definition table and is stored on the same system on which the application is running, the application can set the CCDTURL property in the following way: 
java.net.URL chanTab1 = new URL("file:///home/admdata/ccdt1.tab");
factory.setCCDTURL(chanTab1);
As another example, suppose the file ccdt2.tab contains a client channel definition table and is stored on a system that is different from the one on which the application is running. If the file can be accessed using the FTP protocol, the application can set the CCDTURL property in the following way: 
java.net.URL chanTab2 = new URL("ftp://ftp.server/admdata/ccdt2.tab");
factory.setCCDTURL(chanTab2);
In addition to setting the CCDTURL property of the ConnectionFactory object, the QMANAGER property of the same object must be set to one of the following values:

  • The name of a queue manager
  • An asterisk (*) followed by the name of a queue manager group
  • An asterisk (*)
  • An empty string, or a string containing all blank characters
These are the same values that can be used for the QMgrName parameter on an MQCONN call issued by a client application that is using Message Queue Interface (MQI). For more information about the meaning of these values therefore, see MQCONN. We can set the QMANAGER property by using the IBM MQ JMS administration tool or IBM MQ Explorer. Alternatively, an application can set the property by calling the setQueueManager() method of the ConnectionFactory object.

If an application then creates a Connection object from the ConnectionFactory object, IBM MQ classes for JMS accesses the client channel definition table identified by the CCDTURL property, uses the QMANAGER property to search the table for a suitable client connection channel definition, and then uses the channel definition to start an MQI channel to a queue manager.

Note that the CCDTURL and CHANNEL properties of a ConnectionFactory object cannot both be set when the application calls the createConnection() method. If both properties are set, the method throws an exception. The CCDTURL or CHANNEL property is considered to be set if its value is anything other than null, an empty string, or a string containing all blank characters.

When IBM MQ classes for JMS finds a suitable client connection channel definition in the client channel definition table, it uses only the information extracted from the table to start an MQI channel. Any channel related properties of the ConnectionFactory object are ignored.

In particular, note the following points if you are using TLS:

  • An MQI channel uses TLS only if the channel definition extracted from the client channel definition table specifies the name of a CipherSpec supported by IBM MQ classes for JMS.
  • A client channel definition table also contains information about the location of Lightweight Directory Access Protocol (LDAP) servers that hold certificate revocation lists (CRLs). IBM MQ classes for JMS uses only this information to access LDAP servers that hold CRLs.
  • A client channel definition table can also contain the location of an OCSP responder. IBM MQ classes for JMS cannot use the OCSP information in a client channel definition table file. However, we can configure OCSP as described in the section Online Certificate Status Protocol (OCSP) in Java and JMS client applications.
For more information about using TLS with a client channel definition table, see Use the extended transactional client with TLS channels. Note also the following points if you are using channel exits:

  • An MQI channel uses only the channel exits and associated user data specified by the channel definition extracted from the client channel definition table.
  • A channel definition extracted from a client channel definition table can specify channel exits that are written in Java. This means, for example, that the SCYEXIT parameter on the DEFINE CHANNEL command to create a client connection channel definition can specify the name of a class that implements the WMQSecurityExit interface. Similarly, the SENDEXIT parameter can specify the name of a class that implements the WMQSendExit interface, and the RCVEXIT parameter can specify the name of a class that implements the WMQReceiveExit interface. For more information about how to write a channel exit in Java, seeWriting channel exits in Java for IBM MQ classes for JMS.

    The use of channel exits written in a language other than Java is also supported. For information about how to specify the SCYEXIT, SENDEXIT, and RCVEXIT parameters on the DEFINE CHANNEL command for channel exits written in another language, see DEFINE CHANNEL.