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.

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.PARIS, and causes all messages to be sent as non-persistent and priority 5:

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

Table 15 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 15. Property names for queue URIs

Property	Description	Values
expiry	Lifetime of the message in milliseconds	0 for unlimited, positive integers for timeout (ms)
priority	Priority of the message	0 through 9, -1=QDEF, -2=APP
persistence	Whether the message should be hardened to disk	1=non-persistent, 2=persistent, -1=QDEF, -2=APP
CCSID	Character set of the destination	integers - valid values listed in base WebSphere MQ documentation
targetClient	Whether the receiving application is JMS compliant	0=JMS, 1=MQ
encoding	How to represent numeric fields	An integer value as described in the base WebSphere MQ documentation
HEADERS="COL1 COL2 COL3" COLSPAN="3" 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.PARIS");
      q1.setBaseQueueName("Q1");
      q1.setPersistence(DeliveryMode.NON_PERSISTENT);
      q1.setPriority(5);

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

Table 16. 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

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:

• BytesMessage
• MapMessage
• ObjectMessage
• StreamMessage
• TextMessage

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.