IBM®
Skip to main content
    Country/region [select]      Terms of use
 
 
      
     Home      Products      Services & solutions      Support & downloads      My account     

developerWorks > WebSphere | Java technology >
developerWorks
WebSphere MQ V6 Java and JMS clients and the client channel definition table
e-mail it!
Contents:
Client channel definition table
WebSphere MQ Classes for Java
WebSphere MQ JMS
Connection pooling
Secure Sockets Layer
Conclusion
Resources
About the author
Subscriptions:
dW newsletters
dW Subscription
(CDs and downloads)

Level: Intermediate

Ann Barrago (barraga@uk.ibm.com)
Software developer, IBM
27 Apr 2005

The WebSphere MQ V6 JMS client lets you use the Client Channel Definition Table (CCDT) to connect to WebSphere MQ Queue Managers. Support for the CCDT in WebSphere MQ Java and JMS clients will enable existing channel exits written in C to run unchanged against Java/JMS applications.

Client channel definition table
The client channel definition table (CCDT) is used to define the channel name, QueueManager name, TCP/IP port, and other details required for a client channel definition. These definitions are used by client applications in order to create connections to a WMQ QueueManager. The CCDT is typically used by applications that are not running on the same machine as the QueueManager.

A corresponding server connection channel (SVRCONN) must be defined on the QueueManager machine for every corresponding client channel definition.

The CCDT is initially stored on the QueueManager machine and is updated by defining new client channels or by altering existing ones. All this can be done using the IBM® WebSphere® MQ GUI tooling or the runmqsc tool. The CCDT file itself can be made available to client applications by just copying it to the client machine, or serving it via FTP/HTTP.

Assuming WebSphere MQ is installed in the default directory, the location of the CCDT on the server is in a file named AMQCLCHL.TAB. Default locations per platform are shown here where QM_NAME is the name of your queue manager against which the client channel definition table is defined.

AS400/I5OS
QIBM/UserData/mqm/qmgrs/QM_NAME/&ipcc
UNIX based Systems
var/mqm/qmgrs/QM_NAME/@ipcc
Windows
c:\Program Files\IBM\WebSphere MQ\qmgrs\QM_NAME\@ipcc

The properties required for a client channel, and therefore held in the definition table are listed here, the property names are those used by the CCDT to describe the fields.

Client Channel Name
The name for the client channel, a corresponding server connection channel of the same name will need to be available on the server machine.
Transport Type
For WebSphere MQ Java™ and JMS clients, set this needs to TCP : TRPTYPE(TCP), as this is the only supported transport type for these clients.
QueueManager name
The name of the intended Queue Manager to connect to or the name of the logical QueueManager group.
Connection name
The host name or IP address of the server machine and the port to connect to.
Local Communication Address
Used for TCP/IP connections; If the channel this local address is specified for is stopped/restarted, this value will be used to ensure that for example, the same IP socket is used. This is required when connecting through firewalls.
SendExit, ReceiveExit, and SecurityExit
(Exit Name and UserData properties) Send, Receive and Security exits written in both C and Java are supported with the Java and JMS clients and their details can be defined in the CCDT.
SSL Cipher Spec
The CipherSpec for the channel to use, for example, RC4_MD5_EXPORT. (For Java programmers this is different from the CipherSuite.)
SSL Peer
The distinguished Name pattern that WebSphere MQ uses to restrict the entities from which connections and therefore messages are accepted. The SSLPeer name (such as CN=IBM, C=UK) filters the names of connecting parties.
SSLCAUTH
Whether the SSL server requires the SSL client to send its digital certificate for authentication (Required/Optional is actually set on the SVRCONN channel)

For more details on all of these properties, see the WebSphere MQ Client and Security books. This article focuses on what there properties mean to Java and JMS clients.

The runmqsc tool output for a client channel and its corresponding server channel are shown in Figure 1:

Figure 1. Runmqsc tool output for a client and server connection channel definition

The WebSphere MQ V6 GUI tool displaying a client channel properties is shown in Figure 2. The example exit names are for Java classes. Native exits would specify a library name and entry point, such as ExampleSecurityExit(SycExit).

Figure 2. WebSphere MQ V6 GUI page for a Client Channel Definition.

WebSphere MQ Classes for Java
The CCDT is supplied to the MQ classes for Java client, in the form of a java.net.URL object. This is a Java class that encapsulates the concept of URL. Java URLs support various protocols, including file, http, ftp, and ldap. The URL class has several constructors, one of which is:

java.net.URL url = new java.net.URL(String spec);

The following examples illustrate accessing CCDT files on both local and remote systems:


java.net.URL channelTable1 = new URL("file:///definitionPath/ AMQCLCHL.TAB");
java.net.URL channelTable2 =
     new URL("ftp://userName:password@myServer/definitionPath/ AMQCLCHL.TAB");

The created URL object is then used as a parameter to the com.ibm.mq.MQQueueManager class constructors:


MQQueueManager qmgr =
     new MQQueueManager(String QM_NAME, URL ccdt_url)

MQQueueManager qmgr =
     new MQQueueManager(String QM_NAME, Hashtable properties, URL ccdt_url)

MQQueueManager qmgr =
     new MQQueueManager(String QM_NAME, URL ccdt_url, ConnectionManager connMgr)

MQQueueManager qmgr =
     new MQQueueManager(String QM_NAME, URL ccdt_url, MQConnectionManager mqConnMgr)

Normally for TCP/IP connection with MQ Java clients, a channel name must be supplied in the MQEnvironment to use for the connection. This is normally done in application code, such as MQEnvironment.channel="DEFAULT.JAVA.CHANNEL";.

The default value for this channel is the SYSTEM.DEF.SVRCONN channel. However. if you wish to use a CCDT to make your connection, the application must not set this channel property. The default value is ignored, but if the application supplies a channel name and a CCDT, an MQException will be thrown with reason code 2423: MQRC_CLIENT_CHANNEL_CONFLICT.

Explanation text for this exception:


An attempt is being made to specify a client channel definition table when the name
of the channel has already been defined. This reason code occurs only with Java applications.
Corrective action: Change the channel name to blank and try again.

The reason for doing this is to ensure that there is no confusion as to whether the channel named by the application or by an entry in the CCDT is used for the application's connection.

So if a client channel definition table URL has been correctly specified, the MQ Java client will work through all of the channel definitions from the URL in alphabetic order of channel name, until it finds one which it can make a successful connection.

The search for suitable channel definitions is done by matching the MQ Queue Manager name field in the CCDT, with the QueueManager name string that was passed into the MQQueueManager class constructor:

MQQueueManager qmgr = new MQQueueManager(String, URL ccdt_url)

This queue manager name will be used to match with definition entries in the CCDT, although this queue manager name may not always end up being the name of the queue manager that is actually connected to.

The following rules are used to decide a definitions suitability:

  • If just a queue manager name is specified, for example QM_default, then the CCDT will be searched in alphabetical order for a client channel that contains in its definition a QueueManager name that matches exactly (case sensitive) to the one specified.
  • If an asterisk is included at the beginning of the specified queue manager name in the constructor, for example *QM_default, then the CCDT will be searched in alphabetical order of channel name, for an entry that matches the queue manager name with or without the asterisk, so either QM_default or *QM_default for this example will be matched.

    The reason for including the asterisk is so that the connection name defined for the selected client channel definition may actually define a server and port number that will result in a connection to a queue manager with a different name. Including the asterisk in the name tells the server to not validate that the actual queue manager name that it finally connects to, is the same as the name specified in the Client Channel definition and by the application. This is provided so that it is possible to create a group of logically name back end servers that can cover workload and availability.

  • If "*", Null, blank, or zero-length string specified for the QueueManager name, then the empty queue manager name must match an empty queue manager name in a client channel definition in the table. Empty queue manager names are used to denote the default queue manager for one or more backend servers.

Each definition in the table is tried at most once only and if no suitable connection can be found, the call to the constructor fails specifying an MQException with reason code 2278 MQRC_CLIENT_CONN_ERROR.

If a suitable definition is matched, then the MQ Java client will try to create a connection to the queue manager using the information supplied in the definition. As in the previous section the connection name specifies the host name and port to connect to, the channel name that is expected is that in the definition that was matched.

The queue manager name will match that specified in the MQQueueManager constructor unless an asterisk was included in it.

The CCDT may also include information on user exits to be used, including Send, Receive, and Security exits that may be written in Java and/or C.

If an Exit name and optionally the initialization data are specified in the CCDT, the MQ Java client needs to create the appropriate user exit objects.

Java exits are specified by the class name, the MQ Java client will create an instance of this class, which must specify a single constructor that takes a string as its parameter. If initialization data is also set in the CCDT, this will be passed into the constructor.

  • instantiate any Java exit classes named by the RCVEXIT and/or SENDEXIT fields in the channels definition, using the initial data specified by RCVDATA and/or SENDDATA fields. Java exits are specified by just the class name.
  • Set up external native exits using the MQExternalReceiveExit and/or MQExternalSendExit classes. The native Exits are specified in the RCVEXIT and SENDEXIT fields as libraryName(EntryPoint). The initial data is specified by RCVDATA and/or SENDDATA as it is for Java exits.
  • Where exit chaining is specified, suitable instances of MQSendExitChain and MQReceiveExitChain need to be created on behalf of the client application.

SSL Cipher Spec as specified in the CCDT needs to undergo translation from CipherSpec to CipherSuite to be used in the Java code. The full list of ciphers is JSSE-dependent. The Using Java book specifies the currently supported list, any others are left for users to override in their client applications.

WebSphere MQ JMS
In order for JMS applications to use a CCDT to create the underlying connection to a WebSphere MQ queue manager, the CCDT URL object as described earlier, is supplied to the ConnectionFactory, QueueConnectionFactory, and TopicConnectionFactory objects, using JNDI or programmatically in the application.

To administer JNDI objects using the JMSAdmin command-line tool an extra property is available to all ConnectionFactory objects:

CCDTURL (short form CCDT)
A string that identifies the URL of channel definition table.

The String supplied here should be the same as the string you would supply to the java.io.URL constructor.

This new property is only valid with the CLIENT transport type so is unavailable for BINDINGS and DIRECT transport. The JMSAdmin tool itself will not check that a valid entry for the transport type has been submitted, this validation will be done when the createConnection() method call is made on this ConnectionFactory object.

Sample JMSAdmin syntax to create a ConnectionFactory definition to connect using a CCDT:


create CF(CF_TEST)
alter CF(CF_TEST) TRANSPORT(CLIENT)
alter CF(CF_TEST) CCDT(file://C:/directory/ AMQCLCHL.TAB)

Alternatively, a JMS application does not need to use JNDI and can define the objects programmatically in application code by using the com.ibm.mq.jms.MQConnectionFactory (or MQQueue/MQTopicConnectionFactory classes).

The following methods are available for these classes to specify the client channel definition table:


public void setCCDTURL(URL channelTable)
     The parameter defines a URL which references a channel definition file.
public URL getCCDTURL()
     Returns the URL of the channel definition file, or null if it is not defined to the ConnectionFactory

The settings in the CCDT are only used if the channel name has not been set in the MQConnectionFactory object either by JMSAdmin or programmatically. Even if the channel name that is set matches a channel name in a definition in the CCDT an exception will be thrown, because it must be clear how a connection is created and which channel was used to do so. Therefore, calling setCCDTURL and setChannelName() creates a potential conflict that throws a JMSException and an underlying MQException with reason code 2423 MQRC_CLIENT_CHANNEL_CONFLICT when the createConnection() method is called.

Connection pooling
Overview

The WebSphere MQ classes for Java provide additional support for applications that need to create multiple connections to WebSphere MQ queue managers. When a connection is no longer required instead of destroying it, it can be retained in an internal pool and later reused. This reduces the overhead of having to re-establish that connection.

WebSphere MQ Java and JMS clients provide a default connection pool. Applications can activate or deactivate this connection pool by registering and de-registering tokens through the MQEnvironment class.

Code example from Using Java:


import com.ibm.mq.*; public class MQApp2
{
    public static void main(String[] args) throws MQException
    {
		MQPoolToken token=MQEnvironment.addConnectionPoolToken();
		for (int i=0; i<args.length; i++) {
 			MQQueueManager qmgr=new MQQueueManager(args[i]);
 				// (do something with qmgr)
  			qmgr.disconnect();
 		}
		MQEnvironment.removeConnectionPoolToken(token);
	}
}

The first bold line activates the default connection pool by adding a token to the MQEnvironment, the second bold statement deactivates the pool by removing this token.

If the pool is active when WebSphere MQ base Java constructs an MQQueueManager object, it will search the pool for an appropriate connection, only creating a new physical connection to the queue manager if a suitable existing one cannot be found.

If a CCDTURL is specified the pool will be searched firstly for a Connection that matches a suitable entry in the CCDT. As described above, the CCDT definitions are compared to the application specified Queue Manager name for suitability and matched in alphabetical order of channel name.

If all suitable entries in the CCDT have been checked against available connections in the pool, a new connection attempt is then made for suitable entries in the CCDT again in alphabetical order of channel name until one succeeds.

If a connection cannot be made after this, the exception from the last attempt to connect is thrown, or if no attempt was made to connect, an MQ_CLIENT_CONN Error MQ reason code 2278 is thrown.

When an MQQueueManager.disconnect() method call occurs, the underlying connection is returned to the pool for later reuse.

Alternatively, applications can construct an MQSimpleConnectionManager object to override the default connection pools behavior. Then, the application can either specify that pool during construction of an MQQueueManager object, or pass that pool to MQEnvironment for use as the default connection pool.

To prevent connections from using too much resource, you can limit the total number of connections that an MQSimpleConnectionManager object can accept and also you can limit the size of the connection pool.

When connection pooling is in use with a CCDT, the pooling will work with connections specified and created using the CCDT just as it would with connections created in the usual manner where the channel name is specified by the application. There are no separate connection pools created for CCDT connections.

If a queue manager name of blank ("") or "*" is specified in the MQQueueManager Constructor or as the Queue manager field in the JMS ConnectionFactory, the CCDT is used to obtain a connection to this Queue Manager as follows:

  1. The CCDT is scanned, in alphabetical order of channel name, for a queue manager name that is "" or "*". If a name match is found and a connection to the host and port specified by this CCDT entry's connection name property (host(port)) also exists in the connection pool, it will be used.

    If there are no connections to queue managers with names specified as "" in the pool, then the first CCDT entry that was matched will be used to create a new connection. This connection will then be pooled.

  2. From this point on, the connection pool manager takes over and either reuses an existing connection, makes a new connection, or fails.

If the CCDT does not contain an entry that is suitable for the requested Queue Manager name, then an MQException, wrapped in a JMSException for JMS clients, will be thrown specifying MQ reason code 2278.

The default Connection Manager is used for connection pooling for JMS applications and can also be used for MQ Java application connection pooling. The MQSimpleConnectionManager operates in the same way regardless of the usage of a CCDT, with the following rules governing its usage:

  1. If there is a connection in the pool which is connected to a Queue Manager that matches the queue manager name specified by the application and CCDT entry, it will be used.
  2. If the ConnectionManager class has specified a large enough maximum number of connections, and an existing connection in the pool cannot be found, a new connection will be created and managed by the pool manager.
  3. If the maximum number of connection has already been reached and a new connection is now required, destroy enough of the longest running unused connections to allow a new connection to be made and make that connection.
  4. Fail: Throw an MQException with MQ reason code 2278.

A CCDT entry may actually connect to a different Queue Manager than is stated by the CCDT or the application. This is acceptable if the queue manager name supplied by the application is of the form *QMName.

In the connection pool we can only match an existing connection if it has a QueueManagerName attribute that matches the specified queue manager name.

If we are unable to match the queue manager name in the pool then an attempt to create a new connection will be made.

Secure Sockets Layer
Secure Sockets Layer (SSL) information held on a Client channel definition consists of the SSL CipherSpec and the SSL Peer Name. A CCDT can also include information on Certification Revocation Lists (CRLs) in the form of a NameList.

The MQ Java and JMS clients will read the SSL CipherSpec provided on the client channel and translate it to the corresponding supported Java CipherSuite. For more information on this translation, see WebSphere MQ V6 Using Java, Appendix D.

The SSLPeer name is a set of names and values which make up the distinguished name used to uniquely identify an entity in a X.509 certificate as used with SSL. The format of the SSLPeer name can include the following attributes separated by commas, for example CN=Common Name, T=Title, O=Organization Name, L=locality, C=Country. For more information on how WebSphere MQ implements X.509 and SSL, see the WebSphere MQ Security book Chapter 3.

The SSLCAUTH attribute is defined on the Server connection channel that corresponds to your Client Channel definition. It can be set to required or optional.

If required is specified then the WebSphere JMS/Java client must authenticate itself and have a distinguished name in their certificate that matches the SSLPeer name defined for the channel.

The objects defined against a queue manager to enable WebSphere MQ to retrieve the Certification Revocation List (CRL) information from an LDAP server, are called Authentication Information objects (AUTH_INFO).

These auth_info objects correspond to Java CertStore objects.

WebSphere MQ Namelist objects are simply a collection of AUTH_INFO objects and therefore in a Java application are converted into java.security.cert.CertStores.

Figure 3 shows the Version GUI representation of an Authentication Information object

Figure 4 shows a name list object including the Authentication Information entries from figure 3.

Figure 5 shows the runmqsc output for this same NameList and Authentication Information objects:

MQ classes for Java applications will usually need to create their own CertStores and supply them using the MQEnvironment property defined by MQC.SSL_CERT_STORE_PROPERTY:

code example:


java.util.Collection crlCollection = new ArrayList();
java.security.cert.CertStoreParameters csp = null;
try {
	csp = new
	java.security.cert.LDAPCertStoreParameters("ServerName","portNumber");
	java.security.cert.CertStore cs =
	java.security.cert.CertStore.getInstance("LDAP",csp);
	crlCollection.add(cs);
}catch(NoSuchAlgorithmException nsae)
{
}

The CCDT holds the details of the Authentication information objects defined by a namelist. When the Java or JMS client is using a CCDT to make the connection, it will overwrite any SSL information provided by the application code with the details supplied for the Channel definition that matches the required QueueManager name. This will happen even if there are no Authentication objects or Namelists included in the CCDT.

Conclusion
This article has shown how tThe WebSphere MQ V6 JMS client lets you use the Client Channel Definition Table to connect to WebSphere MQ Queue Managers.

Resources

  • WebSphere MQ online manuals. As of June 2005, WebSphere MQ online manuals are at the V5.3 level. The V6 manuals will be available soon.

  • Online manual: WebSphere MQ V6 Clients. Complete information about the WebSphere MQ client/server environment, including how to install a WebSphere MQ client, how to configure communication links, and how to set up WebSphere MQ channels so that your WebSphere MQ applications can run on a client machine.

  • Online manual: WebSphere MQ V6 Security. Factors you need to consider when planning for to meet your security requirements in a WebSphere MQ environment, including information on Secure Sockets Layer (SSL) support in WebSphere MQ.

  • WebSphere MQ product page. Product descriptions, product news, trial downloads, training information, and more.

  • Trial downloads for IBM software products. No-charge trial downloads for selected IBM DB2, Lotus, Rational, Tivoli, and WebSphere products.

  • Developer Bookstore. Hundreds of technical books for developers at up to 35% off retail

  • WebSphere forums. Product-specific forums where you can ask questions and share your opinions with other WebSphere users

  • developerWorks blogs. Ongoing, free-form columns by software experts, to which you can add your comments. Check out Grady Booch's blog on Software architecture and engineering.

About the author
Photo of Ann BarragoAnn Barrago works as a software developer on the WebSphere MQ clients team at the IBM Hursley Lab in England. She received a B.S. in Software Engineering from the University of Portsmouth in 2000. Ann has extensive Java development experience, having worked on the WebSphere MQ Java and JMS clients with WebSphere Application Server since joining IBM. She is now working on WebSphere platform messaging and on the .NET XMS client for WebSphere MQ. You can reach Ann at barraga@uk.ibm.com.


e-mail it!

developerWorks > WebSphere | Java technology >
developerWorks
    About IBM Privacy Contact