Operations on queue managers

This section describes how to connect to, and disconnect from, a queue manager using WebSphere MQ base Java.

Setting up the WebSphere MQ environment

The information in this section is not relevant if your application connects to a queue manager in bindings mode.

Before an application can connect to a queue manager in client mode, the application must set certain fields in the MQEnvironment class. These fields specify the following information, which is used during the connection attempt:

To specify the channel name and host name, use the following code:

MQEnvironment.hostname = "host.domain.com";
MQEnvironment.channel  = "java.client.channel";

This is equivalent to an MQSERVER environment variable setting of:

"java.client.channel/TCP/host.domain.com".

By default, the Java(TM) clients attempt to connect to a WebSphere(R) MQ listener at port 1414. To specify a different port, use the code:

MQEnvironment.port = nnnn;

Connecting to a queue manager

You are now ready to connect to a queue manager by creating a new instance of the MQQueueManager class:

MQQueueManager queueManager = new MQQueueManager("qMgrName");

To disconnect from a queue manager, call the disconnect() method on the queue manager:

queueManager.disconnect();

If you call the disconnect method, all open queues and processes that you have accessed through that queue manager are closed. However, it is good programming practice to close these resources explicitly when you finish using them. To do this, use the close() method.

The commit() and backout() methods on a queue manager replace the MQCMIT and MQBACK calls that are used with the procedural interface.

Using a client channel definition table

As an alternative to creating a client connection channel definition by setting certain fields and environment properties in the MQEnvironment class, a WebSphere MQ base Java client application can use client connection channel definitions that are stored in a client channel definition table. These definitions are created by WebSphere MQ Script (MQSC) commands or WebSphere MQ Programmable Command Format (PCF) commands. When the application creates an MQQueueManager object, the WebSphere MQ base 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 WebSphere MQ Clients.

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 to 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 WebSphere MQ base 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:

Specifying a range of ports for client connections

When a WebSphere MQ base Java application attempts to connect to a WebSphere MQ queue manager in client mode, a firewall might allow only those connections that originate from specified ports or range of ports. In this situation, you can specify a port, or a range of points, that the application can bind to. You can do this in either of the following ways:

In each of these examples, when the application connects to a queue manager subsequently, the application binds to a local IP address and port number in the range 9.20.0.1(2000) to 9.20.0.1(3000).

In a system with more than one network interface, you can also use the localAddressSetting field, or the environment property MQC.LOCAL_ADDRESS_PROPERTY, to specify which network interface must be used for a connection.

Connection errors might occur if you restrict the range of ports. If an error occurs, an MQException is thrown containing the WebSphere MQ reason code MQRC_Q_MGR_NOT_AVAILABLE and the following message:

Socket connection attempt refused due to LOCAL_ADDRESS_PROPERTY restrictions

An error might occur if all the ports in the specified range are in use, or if the specified IP address, host name, or port number is not valid (a negative port number, for example).