Creating destinations in a JMS application
Instead of retrieving destinations as administered objects from a Java Naming and Directory Interface (JNDI) namespace, a JMS application can use a session to create destinations dynamically at run time. An application can use a uniform resource identifier (URI) to identify an IBM® MQ queue or a topic and, optionally, to specify one or more properties of a Queue or Topic object.
Using a session to create Queue objects
Session session;
.
Queue q1 = session.createQueue("Q1");
This code creates
a Queue object with the default values for all its properties. The
object represents an IBM MQ queue called Q1 that belongs to the local queue manager. This queue can be a local queue, an alias queue, or a remote queue definition.
Queue q2 = session.createQueue("queue://QM2/Q2?persistence=2&priority=5");
The
Queue object created by this statement represents an IBM MQ queue called Q2 that is owned by a queue manager called QM2, and all messages sent to this destination are persistent and have a priority of 5. The queue manager identified in this way can be the local queue manager or a remote queue manager. If it is a remote queue manager, IBM MQ must be configured so that, when the application sends a message to this destination, WebSphere MQ can route the message from the local queue manager to queue manager QM2. For more information about URIs, see Uniform resource identifiers (URIs).
Note that the parameter on the createQueue() method contains provider specific information. Therefore, using the createQueue() method to create a Queue object, instead of retrieving a Queue object as an administered object from a JNDI namespace, might make your application less portable.
TemporaryQueue q3 = session.createTemporaryQueue();
Although
a session is used to create a temporary queue, the scope of a temporary
queue is the connection that was used to create the session. Any of
the connection's sessions can create message producers and message
consumers for the temporary queue. The temporary queue remains until
the connection ends or the application explicitly deletes the temporary
queue by using the TemporaryQueue.delete() method, whichever is the
sooner.
When an application creates a temporary queue, IBM MQ classes for JMS creates a dynamic queue in the queue manager to which the application is connected. The TEMPMODEL property of the connection factory specifies the name of the model queue that is used to create the dynamic queue, and the TEMPQPREFIX property of the connection factory specifies the prefix that is used to form the name of the dynamic queue.
Using a session to create Topic objects
Session session;
.
Topic t1 = session.createTopic("Sport/Football/Results");
This
code creates an Topic object with the default values for all its properties.
The object represents a topic called Sport/Football/Results.
String uri = "topic://Sport/Tennis/Results?persistence=1&priority=0";
Topic t2 = session.createTopic(uri);
The Topic object created
by this code represents a topic called Sport/Tennis/Results, and all
messages sent to this destination are nonpersistent and have a priority
of 0. For more information about topic URIs, see Uniform resource identifiers (URIs).
Note that the parameter on the createTopic() method contains provider specific information. Therefore, using the createTopic() method to create a Topic object, instead of retrieving a Topic object as an administered object from a JNDI namespace, might make your application less portable.
TemporaryTopic t3 = session.createTemporaryTopic();
Although
a session is used to create a temporary topic, the scope of a temporary
topic is the connection that was used to create the session. Any of
the connection's sessions can create message producers and message
consumers for the temporary topic. The temporary topic remains until
the connection ends or the application explicitly deletes the temporary
topic by using the TemporaryTopic.delete() method, whichever is the
sooner.
When an application creates a temporary topic, IBM MQ classes for JMS creates a topic with a name that commences with the characters TEMP/tempTopicPrefix, where tempTopicPrefix is the value of the TEMPTOPICPREFIX property of the connection factory.
Uniform resource identifiers (URIs)
A queue URI is a string that specifies the name of an IBM MQ queue and, optionally, the name of the queue manager that owns the queue and one or more properties of the Queue object created by the application. A topic URI is a string that specifies the name of a topic and, optionally, one or more properties of the Topic object created by the application.
queue://[ qMgrName ]/qName [? propertyName1 = propertyValue1
& propertyName2 = propertyValue2
&...]
A topic URI has the
following format:
topic://topicName [? propertyName1 = propertyValue1
& propertyName2 = propertyValue2
&...]
The variables in these formats
have the following meanings:- qMgrName
- The name of the queue manager that owns the queue identified by the URI.
The queue manager can the local queue manager or a remote queue manager. If it is a remote queue manager, IBM MQ must be configured so that, when an application sends a message to the queue, WebSphere MQ can route the message from the local queue manager to the remote queue manager.
If no name is specified, the local queue manager is assumed.
- qName
- The name of the IBM MQ queue.
The queue can be a local queue, an alias queue, or a remote queue definition.
For the rules for creating queue names, see Rules for naming IBM MQ objects.
- topicName
- The name of the topic.
For the rules for creating topic names, see Rules for naming IBM MQ objects. Avoid the use of the wildcard characters +, #, *, and ? in topic names. Topic names containing these characters can cause unexpected results when you subscribe to them. See Using topic strings.
- propertyName1, propertyName2, ...
- The names of the properties of the Queue or Topic object created by the application. Table 1 lists the valid property names that can be used in a URI.
If no properties are specified, the Queue or Topic object has the default values for all its properties.
- propertyValue1, propertyValue2, ...
- The values of the properties of the Queue or Topic object created by the application. Table 1 lists the valid property values that can be used in a URI.
Property name | Description | Valid values |
---|---|---|
CCSID | How the character data in the body of a message is represented when IBM MQ classes for JMS forwards the message to the destination |
|
encoding | How the numeric data in the body of a message is represented when IBM MQ classes for JMS forwards the message to the destination |
|
expiry | The time to live for messages sent to the destination |
|
multicast | The multicast setting for a topic when using a real-time connection to a broker | The following list contains the valid values. Associated with each value is the corresponding value of the MULTICAST property as used in the IBM MQ JMS administration tool. For a description of the MULTICAST property and its valid values, see Properties of IBM MQ classes for JMS objects.
|
persistence | The persistence of messages sent to the destination |
|
priority | The priority of messages sent to the destination |
|
targetClient | Whether messages sent to the destination contain an MQRFH2 header |
|
queue:///Q1
The
following URI identifies an IBM MQ queue called Q2 that is owned by a queue manager called QM2. All messages sent to this destination have a priority of 6. The remaining properties of the Queue object created using this URI have their default values.
queue://QM2/Q2?priority=6
The
following URI identifies a topic called Sport/Athletics/Results. All
messages sent to this destination are nonpersistent and have a priority
of 0. The remaining properties of the Topic object created using this
URI have their default values.
topic://Sport/Athletics/Results?persistence=1&priority=0