Sending a message

Messages are sent using a MessageProducer. For point-to-point this is a QueueSender that is created using the createSender method on QueueSession. A QueueSender is normally created for a specific queue, so that all messages sent using that sender are sent to the same destination. The destination is specified using a Queue object. Queue objects can be either created at runtime, or built and stored in a JNDI namespace.

Queue objects are retrieved from JNDI in the following way:

Queue ioQueue;
ioQueue = (Queue)ctx.lookup( qLookup );

WebSphere MQ JMS provides an implementation of Queue in com.ibm.mq.jms.MQQueue. It contains properties that control the details of WebSphere(R) MQ specific behavior, but in many cases it is possible to use the default values. JMS defines a standard way to specify the destination that minimizes the WebSphere MQ specific code in the application. This mechanism uses the QueueSession.createQueue method, which takes a string parameter describing the destination. The string itself is still in a vendor-specific format, but this is a more flexible approach than directly referring to the vendor classes.

WebSphere MQ JMS accepts two forms for the string parameter of createQueue().

Note:
When sending a message to a cluster, leave the Queue Manager field in the JMS Queue object blank. This enables an MQOPEN to be performed in BIND_NOT_FIXED mode, which allows the queue manager to be determined. Otherwise an exception is returned reporting that the queue object cannot be found. This applies when using JNDI or defining queues at runtime.

The following example connects to queue Q1 on queue manager HOST1.QM1, and causes all messages to be sent as non-persistent and priority 5:

ioQueue = session.createQueue("queue://HOST1.QM1/Q1?persistence=1&priority=5");

The following is an example of creating a topic URI:

session.createTopic("topic://Sport/Football/Results?multicast=7");

Table 13 lists the names that can be used in the name-value part of the URI. A disadvantage of this format is that it does not support symbolic names for the values, so where appropriate, the table also indicates special values, which might change. (See Setting properties with the set method for an alternative way of setting properties.)

Table 13. Property names for queue and topic URIs
Property Description Values
CCSID Character set of the destination integers - valid values listed in base WebSphere MQ documentation
encoding How to represent numeric fields An integer value as described in the base WebSphere MQ documentation
expiry Lifetime of the message in milliseconds 0 for unlimited, positive integers for timeout (ms)
multicast Sets multicast mode for direct connections -1=ASCF, 0=DISABLED, 3=NOTR, 5=RELIABLE, 7=ENABLED
persistence Whether the message should be hardened to disk 1=non-persistent, 2=persistent, -1=QDEF, -2=APP
priority Priority of the message 0 through 9, -1=QDEF, -2=APP
targetClient Whether the receiving application is JMS compliant 0=JMS, 1=MQ
The special values are:
QDEF
Determine the property from the configuration of the WebSphere MQ queue.
APP
The JMS application can control this property.

Once the Queue object is obtained (either using createQueue as above or from JNDI), it must be passed into the createSender method to create a QueueSender:

QueueSender queueSender = session.createSender(ioQueue);

The resulting queueSender object is used to send messages by using the send method:

queueSender.send(outMessage);

Setting properties with the set method

You can set Queue properties by first creating an instance of com.ibm.mq.jms.MQQueue using the default constructor. Then you can fill in the required values by using public set methods. This method means that you can use symbolic names for the property values. However, because these values are vendor-specific, and are embedded in the code, the applications become less portable.

The following code fragment shows the setting of a queue property with a set method.

com.ibm.mq.jms.MQQueue q1 = new com.ibm.mq.jms.MQQueue();
      q1.setBaseQueueManagerName("HOST1.QM1");
      q1.setBaseQueueName("Q1");
      q1.setPersistence(DeliveryMode.NON_PERSISTENT);
      q1.setPriority(5);

Table 14 shows the symbolic property values that are supplied with WebSphere MQ JMS for use with the set methods.

Table 14. Symbolic values for queue properties
Property Admin tool keyword Values
expiry
UNLIM
APP
JMSC.MQJMS_EXP_UNLIMITED
JMSC.MQJMS_EXP_APP
priority
APP
QDEF
JMSC.MQJMS_PRI_APP
JMSC.MQJMS_PRI_QDEF
persistence
APP
QDEF
PERS
NON
JMSC.MQJMS_PER_APP
JMSC.MQJMS_PER_QDEF
JMSC.MQJMS_PER_PER
JMSC.MQJMS_PER_NON
targetClient
JMS
MQ
JMSC.MQJMS_CLIENT_JMS_COMPLIANT
JMSC.MQJMS_CLIENT_NONJMS_MQ
encoding
Integer(N)
Integer(R)
Decimal(N)
Decimal(R)
Float(N)
Float(R)
Native
JMSC.MQJMS_ENCODING_INTEGER_NORMAL
JMSC.MQJMS_ENCODING_INTEGER_REVERSED
JMSC.MQJMS_ENCODING_DECIMAL_NORMAL
JMSC.MQJMS_ENCODING_DECIMAL_REVERSED
JMSC.MQJMS_ENCODING_FLOAT_IEEE_NORMAL
JMSC.MQJMS_ENCODING_FLOAT_IEEE_REVERSED
JMSC.MQJMS_ENCODING_NATIVE
multicast
ASCF
DISABLED
NOTR
RELIABLE
ENABLED
JMSC.MQJMS_MULTICAST_AS_CF
JMSC.MQJMS_MULTICAST_DISABLED
JMSC.MQJMS_MULTICAST_NOT_RELIABLE
JMSC.MQJMS_MULTICAST_RELIABLE
JMSC.MQJMS_MULTICAST_ENABLED

See The ENCODING property for a discussion of encoding.

Message types

JMS provides several message types, each of which embodies some knowledge of its content. To avoid referring to the vendor-specific class names for the message types, methods are provided on the Session object for message creation.

In the sample program, a text message is created in the following manner:

System.out.println( "Creating a TextMessage" );
TextMessage outMessage = session.createTextMessage();
System.out.println("Adding Text");
outMessage.setText(outString);

The message types that can be used are:

Details of these types are in WebSphere MQ JMS API reference.