Destinations

 

The Destination interface is the abstract superclass of Queue and Topic. In the WebSphere MQ JMS implementation of JMS 1.1, Queue and Topic objects encapsulate addresses in WebSphere MQ and the broker. For example, a Queue object encapsulates the name of a WebSphere MQ queue.

For information about using Queue objects in the point-to-point domain, see Sending a message and, for information about using Topic objects in the publish/subscribe domain, see Using topics. The following is a overview from a domain independent perspective.

Queue and Topic objects are retrieved from a JNDI namespace in the following way:

Queue ioQueue;
ioQueue = (Queue)ctx.lookup( qLookup );
.
.
.
Topic ioTopic;
ioTopic = (Topic)ctx.lookup( tLookup );

The WebSphere MQ JMS implementation of Queue and Topic interfaces are in the com.ibm.mq.jms.MQQueue and com.ibm.qm.jms.MQTopic classes respectively. These classes contain properties that control the behavior of WebSphere MQ and the broker but, in many cases, it is possible to use the default values. As well as being able to administer Queue and Topic objects in a JNDI namespace, JMS defines a standard way of specifying a destination at runtime that minimizes the WebSphere MQ specific code in the application. This mechanism uses the Session.createQueue() and Session.createTopic() methods, which take a string parameter that specifies the destination. The string is still in a provider specific format, but this approach is more flexible than referring directly to the provider classes.

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

• The first is the name of a WebSphere MQ queue:

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

• The second, and more powerful, form is a uniform resource identifier (URI). This form allows you to specify a remote queue, which is a queue on a queue manager other than the one to which you are connected. It also allows you to set the other properties of 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 forward slash (/), 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 the following:

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

  The name of the queue manager is omitted. This is interpreted to mean as the queue manager to which the owning Connection object 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 Queue object blank. This enables an MQOPEN call 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 a queue at runtime.

WebSphere MQ JMS accepts a topic URI for the string parameter of createTopic(), as shown in the following example:

Topic topic = session.createTopic( "topic://Sport/Football/Spurs/Results" );

Although the createTopic() method is in the JMS specification, the format of the string argument is provider specific. Therefore, using this method can make your code non-portable.

Other ways of creating a Topic object at runtime are as follows:

Using MQTopic(..)

This way requires a reference to the WebSphere MQ JMS implementation of the Topic interface, and therefore renders the code non-portable.

The constructor takes one argument, which must be a URI. For a WebSphere MQ JMS topic, this must be of the form:

topic://TopicName[?property=value[&property=value]*]

For example, the following code creates a topic for nonpersistent messages with a priority of 5:

// Create a Topic using the one-argument MQTopic constructor
String tSpec = "Sport/Football/Spurs/Results?persistence=1&priority=5";
Topic rtTopic = new MQTopic( "topic://" + tSpec );

Using MQTopic(), then setBaseTopicName(..)

This way uses the default MQTopic constructor, and therefore renders the code non-portable. Here is an example:

// Create a Topic using the default MQTopic constructor
Topic rtTopic = new MQTopic();
.
.
.
// Set the object properties using the setter methods
((MQTopic)rtTopic).setBaseTopicName( "Sport/Football/Spurs/Results" );
((MQTopic)rtTopic).setPersistence(1);
((MQTopic)rtTopic).setPriority(5);

Using session.createTemporaryTopic()

A temporary topic is created by a session, and only message consumers created by the same session can consume messages from the topic. A TemporaryTopic object is created as follows:

// Create a TemporaryTopic using the session factory method
Topic rtTopic = session.createTemporaryTopic();

uj25070_