Using createQueue or createTopic with the default messaging provider

This topic describes the general considerations for using the Session.createQueue(String) method or Session.createTopic(String) method instead of using JNDI lookup to create a JMS Queue or JMS Topic with the default messaging provider.

Applications can use the InitialContext.lookup() method to retrieve administered objects. An alternative, but less manageable, approach to obtaining administratively defined JMS destination objects by JNDI lookup is to use the Session.createQueue(String) method or Session.createTopic(String) method. For example,
Queue q = mySession.createQueue("Q1");
creates a JMS Queue instance that can be used to reference the existing destination Q1.

With the default messaging provider, the existing destination exists as a queue or topic space on the bus to which the session is connected.

createQueue

The Session.createQueue(String) method is used to create a JMS Queue object representing an existing destination. This provides an alternative, but less manageable, approach to obtaining administratively-defined JMS Queue objects by JNDI lookup.

Simple form
In its simplest form, the parameter to the createQueue method is the name of an existing destination on the bus to which the session is connected. For example, if there exists a queue named Q1 then the following method creates a JMS Queue instance that can be used to reference that destination:
Queue q = mySession.createQueue("Q1");
URI form
For more complex situations, applications can use a URI-based format. The URI format allows an arbitrary number of name value pairs to be supplied to set various properties of the Queue object. The queue URI is identified by the prefix queue://, followed by the name of the destination. The simple form for Q1 above can be expressed with the following URI:
Queue q = mySession.createQueue("queue://Q1");
[Updated in August 2011] Name value pairs are introduced by a question mark "?". For example, an application might connect a session to one bus then use the following format to create a JMS Queue instance for Q2 on a different bus, called otherBus:
Queue q = mySession.createQueue("queue://Q2?busName=otherBus");
When sending messages to WebSphere® MQ, the queue name must be followed by an at sign (@) and the name of the queue manager on which the queue is located, for example :
Queue q = mySession.createQueue("queue://Q2@qmgr?busName=otherBus");
[Updated in August 2011]
aug2011
Multiple name value pairs are separated by an ampersand character "&", for example:
Queue q = mySession.createQueue("queue://Q2?busName=otherBus&deliveryMode=Application&readAhead=AsConnection&priority=6");
Properties
busName, deliveryMode, priority, readAhead, and timeToLive. See the generated API information for a description of these properties.

createTopic

The Session.createTopic(String) method is used to create a JMS Topic object representing an existing destination. (Note that for topics it is the topic space rather than the topic that exists.) This provides an alternative, but less manageable, approach to obtaining administratively-defined JMS Topic objects by JNDI lookup.

Simple form
In its simplest form, the parameter to the createTopic method is the name of a topic in the default topic space on the bus to which the session is connected. For example, if the default topic space exists, then a JMS Topic instance that can be used to reference the "cats" topic on the default topic space:
Topic t = mySession.createTopic("cats");
To specify a non-default topic space, the special syntax of the form topicSpace:topic can be used. For example:
Topic t = mySession.createTopic("kennelTopicSpace:dogs");
URI form
For more complex situations a URI based format can be used. The topic URI is identified by the prefix "topic://" followed by the name of the topic. The examples above can be expressed as the following URIs:
Topic t = mySession.createTopic("topic://cats");

Topic t = mySession.createTopic("topic://dogs?topicSpace=kennelTopicSpace");

As for queues, multiple name value pairs are separated by an ampersand "&".

Properties
busName, deliveryMode, priority, readAhead, timeToLive, and topicSpace. See the generated API information for a description of these properties.

Support for MA88 URIs

WebSphere Application Server Version 5 applications can use createQueue and createTopic methods to create JMS Queue and Topic objects with the embedded JMS provider (the Version 5 default messaging provider). To assist in migration of such applications, the Version 6 default messaging provider supports a large subset of valid MA88-specific string parameters to the createQueue and createTopic methods.

Default queue manager
An MA88 URI for a queue includes the name of the queue manager; for example:
queue://qm/queue

To specify the default queue manager, the queue manager name is left out; for example: queue:///queue (note the three forward slash characters, ///). Because the interpretation of the default queue manager is logically consistent with the Version 6 concept of a queue on the current bus, the Version 6 default messaging provider tolerates presence of three forward slash characters after the "queue:" prefix. This allows MA88 queue URIs with a default queue manager to be used without change in Version 6.

Non-default queue manager
If an MA88 queue URI specifies a non-default queue manager, as in queue://qm/queue, then this has an ambiguous interpretation in Version 6. To highlight the potential problem and ensure that the destination is given consideration during the porting process, such a URI generates a JMSException if passed to the createQueue() method.
MA88 properties
As with the Version 6 URIs, MA88 URIs can contain a number of name value pairs specifying destination properties. Many of the MA88 specific properties have no direct equivalent in the Version 6 default messaging provider and are ignored silently. However, the following MA88 properties are mapped to Version 6 equivalents:
MA88 name Version 6 name Notes®
expiry timeToLive
persistence deliveryMode

1 = NonPersistent
2 = Persistent
Anything else = Application

Topic wildcard translation

A topic used for consuming messages can include wild cards. The wild card syntax used in MA88 differs from the XPath syntax used in WebSphere Application Server Version 6, so if an MA88 URI contains wild cards the Version 6 code attempts to convert them to XPath equivalents. The conversion performed depends on the presence of the brokerVersion property in the MA88 URI. The WebSphere Application Server Version 5 default messaging provider required any URI specifying a topic wild card to include brokerVersion=1 in the name value pairs. The Version 6 code therefore uses brokerVersion=1 as the trigger to perform MQSI to XPath wild card conversion.

Case sensitivity

All parts of the string parameter for createQueue and createTopic are case sensitive.

Multiple instances of same property

If a URI contains multiple occurrences of a given property with conflicting values, it is not specified which value is used.

Conflicting MA88 and Version 6 properties

If a URI contains both a property and the MA88 equivalent of that property with conflicting values, it is not specified which value is used.

Unknown properties

Any name value pairs for which the property name is not recognized are ignored without any error reporting.

Escaping special characters

The following characters have special significance in the createQueue and createTopic string parameters:
: (colon)
This is used as a separator between the topic space and the topic in short form topic strings
? (question mark)
This is used to indicate the start of the name value pairs.
& (ampersand)
This is used to separate multiple name value pairs.
If you want to use any of these characters in a URI, you must prefix it with a backward slash "\". The "\" character can also be escaped by doubling it; "\\"'. Note that the "\" character is treated as a special character by Java, and so must be doubled when placed in character string constants; for example:
createTopic("myTop\\:ic")                         creates a topic with the name "myTop:ic"
createTopic("topic://my\\?Topi\\\\c")             creates a topic with the name "my?Topi\c"
createQueue("queue://q1?busName=silly\\&bus")     creates a queue with bus name "silly&bus"



Related concepts
Learning about the default messaging provider
Related tasks
Programming to use JMS and messaging directly
Reference topic Reference topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Aug 31, 2013 12:02:36 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-zos&topic=rjn0001_
File name: rjn0001_.html