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

An IBM MQ classes for Java client application can use client connection channel definitions stored in a client channel definition table (CCDT).

As an alternative to creating a client connection channel definition by setting certain fields and environment properties in the MQEnvironment class or passing them to an MQQueueManager in a properties hash table, an IBM MQ classes for Java client 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, or using the IBM MQ Explorer .

When the application creates an MQQueueManager object, the IBM MQ classes for Java client 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, an application must first create a URL object. 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.

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 create a URL object in the following way: 
java.net.URL chanTab1 = new URL("file:///home/admdata/ccdt1.tab");
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 create a URL object in the following way: 
java.net.URL chanTab2 = new URL("ftp://ftp.server/admdata/ccdt2.tab");
After the application has created a URL object, the application can create an MQQueueManager object using one of the constructors that takes a URL object as a parameter. Here is an example: 
MQQueueManager mars = new MQQueueManager("MARS", chanTab2);
This statement causes the IBM MQ classes for Java client to access the client channel definition table identified by the URL object chanTab2, search the table for a suitable client connection channel definition, and then use the channel definition to start an MQI channel to the queue manager called MARS. Note the following points that apply if an application uses a client channel definition table:

  • When the application creates an MQQueueManager object using a constructor that takes a URL object as a parameter, no channel name must be set in the MQEnvironment class, either as a field or as an environment property. If a channel name is set, the IBM MQ classes for Java client throws an MQException. The field or environment property specifying the channel name is considered to be set if its value is anything other than null, an empty string, or a string containing all blank characters.
  • The queueManagerName parameter on the MQQueueManager constructor can have one of the following values:

    • The name of a queue manager
    • An asterisk (*) followed by the name of a queue manager group
    • An asterisk (*)
    • Null, 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, seeThe Message Queue Interface overview.

    If our application uses connection pooling, seeControlling the default connection pool in IBM MQ classes for Java.

  • When the IBM MQ classes for Java client finds a suitable client connection channel definition in the client channel definition table, it uses only the information extracted from this channel definition to start an MQI channel. Any channel related fields or environment properties that the application might have set in the MQEnvironment class are ignored. In particular, note the following points if you are using Transport Layer Security (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 the IBM MQ classes for Java client.
    • A client channel definition table also contains information about the location of Lightweight Directory Access Protocol (LDAP) servers that hold certificate revocation lists (CRLs). The IBM MQ classes for Java client 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 Java cannot use the OCSP information in a client channel definition table file. However, we can configure OCSP as described in the section Use Online Certificate Protocol
    For more information about using TLS with a client channel definition table, see Specifying that an MQI channel uses TLS. Note also the following points if you are using channel exits:

    • An MQI channel uses the channel exits and associated user data specified by the channel definition extracted from the client channel definition table in preference to channel exits and data specified using other methods.
    • A channel definition extracted from a client channel definition table can specify channel exits that are written in Java, C, or C++. For more information about how to write a channel exit in Java , seeCreating a channel exit in IBM MQ classes for Java. For more information about how to write a channel exit in other languages, see Use channel exits not written in Java with IBM MQ classes for Java.