The createQueue or createTopic method and the default messaging provider
You 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.
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 then use the following format to create a JMS Queue instance for Q2 on a different bus, called otherBus:
When sending messages to IBM 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?busName=otherBus");
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 5.1 版 applications can use createQueue and createTopic methods to create JMS Queue and Topic objects with the Version 5 embedded messaging provider (the 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 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
- : (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.
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"