Using the IBM MQ JMS extensions

IBM® MQ classes for JMS contains a set of extensions to the JMS API called the IBM MQ JMS extensions. An application can use these extensions to create connection factories and destinations dynamically at run time, and to set the properties of connection factories and destinations.

IBM MQ classes for JMS contains a set of classes in the packages com.ibm.jms and com.ibm.mq.jms. These classes implement the JMS interfaces and contain the IBM MQ JMS extensions. The examples of code that follow assume that these packages have been imported by the following statements: 

import com.ibm.jms.*;
import com.ibm.mq.jms.*;
import com.ibm.msg.client.wmq.WMQConstants;
An application can use the IBM MQ JMS extensions to perform the following functions:
  • Create connection factories and destinations dynamically at run time, instead of retrieving them as administered objects from a Java Naming and Directory Interface (JNDI) namespace
  • Set the properties of connection factories and destinations

Creating connection factories

To create a connection factory, an application can use the MQConnectionFactory constructor, as shown in the following example: 

MQConnectionFactory factory = new MQConnectionFactory();
This statement creates an MQConnectionFactory object with the default values for all its properties, which means that the application connects to the default queue manager in bindings mode. If you want an application to connect in client mode, or connect to a queue manager other than the default queue manager, the application must set the appropriate properties of the MQConnectionFactory object before creating the connection. For information about how to do this, see Setting the properties of connection factories.
An application can create connection factories of the following types in a similar way:
  • MQQueueConnectionFactory
  • MQTopicConnectionFactory
  • MQXAConnectionFactory
  • MQXAQueueConnectionFactory
  • MQXATopicConnectionFactory

Setting the properties of connection factories

An application can set the properties of a connection factory by calling the appropriate methods of the connection factory. The connection factory can either be an administered object or an object created dynamically at run time.

Consider the following code, for example: 

MQConnectionFactory factory = new MQConnectionFactory();
.
factory.setTransportType(WMQConstants.WMQ_CM_CLIENT);
factory.setQueueManager("QM1");
factory.setHostName("HOST1");
factory.setPort(1415);
factory.setChannel("QM1.SVR");
This code creates an MQConnectionFactory object and then sets five properties of the object. The effect of setting these properties is that the application connects to queue manager QM1 in client mode using an MQI channel called QM1.SVR. The queue manager is running on a system with host name HOST1, and the listener for the queue manager is listening in port number 1415.

An application that uses a real-time connection to a broker can use only the publish/subscribe style of messaging. It cannot use the point-to-point style of messaging.

Only certain combinations of properties of a connection factory are valid. For information about which combinations are valid, see Dependencies between properties of IBM MQ classes for JMS objects.

For more information about the properties of a connection factory, and the methods used to set its properties, see Properties of IBM MQ classes for JMS objects.

Creating destinations

To create a Queue object, an application can use the MQQueue constructor, as shown in the following example: 

MQQueue q1 = new MQQueue("Q1");
This statement creates an MQQueue object with the default values for all its properties. The object represents an IBM MQ queue called Q1 that belongs to the local queue manager. This queue can be a local queue, an alias queue, or a remote queue definition.
An alternative form of the MQQueue constructor has two parameters, as shown in the following example: 

MQQueue q2 = new MQQueue("QM2", "Q2");
The MQQueue object created by this statement represents an IBM MQ queue called Q2 that is owned by queue manager QM2. The queue manager identified in this way can be the local queue manager or a remote queue manager. If it is a remote queue manager, IBM MQ must be configured so that, when the application sends a message to this destination, WebSphere MQ can route the message from the local queue manager to the remote queue manager.
The MQQueue constructor can also accept a queue uniform resource identifier (URI) as a single parameter. A queue URI is a string that specifies the name of an IBM MQ queue and, optionally, the name of the queue manager that owns the queue, and one or more properties of the MQQueue object. The following statement contains an example of a queue URI: 

MQQueue q3 = new MQQueue("queue://QM3/Q3?persistence=2&priority=5");
The MQQueue object created by this statement represents an IBM MQ queue called Q3 that is owned by queue manager QM3, and all messages sent to this destination are persistent and have a priority of 5. For more information about queue URIs, see Uniform resource identifiers (URIs). For an alternative way of setting the properties of an MQQueue object, see Setting the properties of destinations.
To create a Topic object, an application can use the MQTopic constructor, as shown in the following example: 

MQTopic t1 = new MQTopic("Sport/Football/Results");
This statement creates an MQTopic object with the default values for all its properties. The object represents a topic called Sport/Football/Results.
The MQTopic constructor can also accept a topic URI as a parameter. A topic URI is a string that specifies the name of a topic and, optionally, one or more properties of the MQTopic object. The following statement contains an example of a topic URI: 

MQTopic t2 = new MQTopic("topic://Sport/Tennis/Results?persistence=1&priority=0");
The MQTopic object created by this statement represents a topic called Sport/Tennis/Results, and all messages sent to this destination are nonpersistent and have a priority of 0. For more information about topic URIs, see Uniform resource identifiers (URIs). For an alternative way of setting the properties of an MQTopic object, see Setting the properties of destinations.

Setting the properties of destinations

An application can set the properties of a destination by calling the appropriate methods of the destination. The destination can either be an administered object or an object created dynamically at run time.

Consider the following code, for example: 

MQQueue q1 = new MQQueue("Q1");
.
q1.setPersistence(WMQConstants.WMQ_PER_PER);
q1.setPriority(5);
This code creates an MQQueue object and then sets two properties of the object. The effect of setting these properties is that all messages sent to the destination are persistent and have a priority of 5.
An application can set the properties of MQTopic object in a similar way, as shown in the following example: 

MQTopic t1 = new MQTopic("Sport/Football/Results");
.
t1.setPersistence(WMQConstants.WMQ_PER_NON);
t1.setPriority(0);
This code creates an MQTopic object and then sets two properties of the object. The effect of setting these properties is that all messages sent to the destination are nonpersistent and have a priority of 0.

For more information about the properties of a destination, and the methods used to set its properties, see Properties of IBM MQ classes for JMS objects.