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 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().

• The first is the name of the WebSphere MQ queue, as illustrated in the following fragment taken from the IVTRun program in the samples directory:

  public static final String QUEUE = "SYSTEM.DEFAULT.LOCAL.QUEUE" ;
   .
   .
   .
    ioQueue = session.createQueue( QUEUE );

• The second, and more powerful, form is based on uniform resource identifiers (URIs). This form allows you to specify remote queues (queues on a queue manager other than the one to which you are connected). It also allows you to set the other properties contained in a com.ibm.mq.jms.MQQueue object.

  The URI for a queue begins with the sequence queue://, followed by the name of the queue manager on which the queue resides. This is followed by a further /, the name of the queue, and optionally, a list of name-value pairs that set the remaining Queue properties. For example, the URI equivalent of the previous example is:

  ioQueue = session.createQueue("queue:///SYSTEM.DEFAULT.LOCAL.QUEUE");

  The name of the queue manager is omitted. This is interpreted as the queue manager to which the owning QueueConnection is connected at the time when the Queue object is used.

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 1 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 Set properties with the set method for an alternative way of setting properties.)

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);

If an application sends a message within a transaction, the message is not delivered to its destination until the transaction is committed. This means that an application cannot send a message and receive a reply to the message within the same transaction.

uj24420_