The createQueue or createTopic method and the default messaging provider

We can use 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 previously, can be expressed with the following URI:

Queue q = mySession.createQueue("queue://Q1");

Name value pairs are introduced by a question mark ?. For example, an application might connect a session to one bus 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");

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 previous examples 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.1 applications can use createQueue and createTopic methods to create JMS Queue and Topic objects with the Version 5 embedded messaging provider (the Version 5.1 JMS messaging provider). To assist you in migrating these applications, the default messaging provider (the service integration bus) 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 omitted; for example: queue:///queue (note the three forward slash characters, ///). Because the interpretation of the default queue manager is logically consistent with the concept of a queue on the current bus, the bus tolerates the presence of three forward slash characters following the queue: prefix. This allows MA88 queue URIs with a default queue manager to be used by the bus without change.

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 the bus. 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 bus 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 bus and are ignored silently. However, the following MA88 properties are mapped to bus equivalents:

MA88 name	Service integration bus name	Notes
expiry	timeToLive
persistence	deliveryMode	1 = NonPersistent 2 = Persistent Anything else = Application

Topic wildcard translation

A topic used for consuming messages can include wildcards. The wildcard syntax used in MA88 differs from the XPath syntax used in the bus, so if an MA88 URI contains wildcards the bus 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.1 default messaging provider required any URI specifying a topic wildcard to include brokerVersion=1 in the name value pairs. The bus therefore uses brokerVersion=1 as the trigger to undertake MQSI to XPath wildcard 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 bus 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.

To use any of these characters in a URI, 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 the Java language, 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"

Reference topic