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.

Use a session to create Queue objects

To create a Queue object, an application can use the createQueue() method of a Session object, as shown in the following example:

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. The createQueue() method also accepts a queue URI as a parameter. 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. The following statement contains an example of a queue URI:

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 our application less portable.

An application can create a TemporaryQueue object by using the createTemporaryQueue() method of a Session object, as shown in the following example:

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.

Use a session to create Topic objects

To create a Topic object, an application can use the createTopic() method of a Session object, as shown in the following example:

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. The createTopic() method also accepts a topic URI as a parameter. A topic URI is a string that specifies the name of a topic and, optionally, one or more properties of the Topic object. The following code contains an example of a topic URI:

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 our application less portable.

An application can create a TemporaryTopic object by using the createTemporaryTopic() method of a Session object, as shown in the following example:

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.

A queue URI has the following format:

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 Use 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.

Brackets ([]) denotes an optional component, and the ellipsis (...) means that the list of property name-value pairs, if present, can contain one or more name-value pairs. Table 1 lists the valid property names and valid values that can be used in queue and topic URIs. Although the IBM MQ JMS administration tool uses symbolic constants for the values of properties, URIs cannot contain symbolic constants.

Table 1. Property names and valid values for use in queue and topic URIs
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	Any coded character set identifier supported by IBM MQ.
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	Any valid value for the Encoding field in an IBM MQ message descriptor.
expiry	The time to live for messages sent to the destination	-2 - As specified on the send() call or, if not specified on the send() call, the default time to live of the message producer. 0 - A message sent to the destination never expires. A positive integer specifying the time to live in milliseconds.
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. -1 - ASCF 0 - DISABLED 3 - NOTR 5 - RELIABLE 7 - ENABLED
persistence	The persistence of messages sent to the destination	-2 - As specified on the send() call or, if not specified on the send() call, the default persistence of the message producer. -1 - As specified by the DefPersistence attribute of the IBM MQ queue or topic. 1 - Nonpersistent. 2 - Persistent. 3 - Equivalent to the value HIGH for the PERSISTENCE property as used in the IBM MQ JMS administration tool. For an explanation of this value, see JMS persistent messages.
priority	The priority of messages sent to the destination	-2 - As specified on the send() call or, if not specified on the send() call, the default priority of the message producer. -1 - As specified by the DefPriority attribute of the IBM MQ queue or topic. An integer in the range 0-9 specifying the priority of messages sent to the destination.
targetClient	Whether messages sent to the destination contain an MQRFH2 header	0 - Messages contain an MQRFH2 header. 1 - Messages do not contain an MQRFH2 header.

For example, the following URI identifies an IBM MQ queue called Q1 that is owned by the local queue manager. A Queue object created using this URI has the default values for all its properties.

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