Using topics

This section discusses the use of JMS Topic objects in WebSphere MQ classes for Java Message Service applications.

Topic names

This section describes the use of topic names within WebSphere MQ classes for Java Message Service.

Note:
The JMS specification does not specify exact details about the use and maintenance of topic hierarchies. Therefore, this area can vary from one provider to the next.

Topic names in WebSphere MQ JMS are arranged in a tree-like hierarchy, an example of which is shown in Figure 3.

Figure 3. WebSphere MQ classes for Java Message Service topic name hierarchy

A diagram of part of a hierarchy of topic names, referenced in examples in the following text. The hierarchy shown has four levels: At the top level, the single topic Sport. At the second level, the three topics Rugby, Football, and Tennis. For lower levels, the diagram concentrates on Football while indicating that there are likely to be other sub-topics dependent on Rugby and Tennis. At the third level, there are two topics, Spurs and Arsenal. At the lowest level, there are three topics. The sub-topic Results is shown twice, once under both Spurs and Arsenal. The sub-topic Signings is shown under Spurs only.

In a topic name, levels in the tree are separated by the "/" character. This means that the "Signings" node in Figure 3 is identified by the topic name: 

Sport/Football/Spurs/Signings

A powerful feature of the topic system in WebSphere MQ classes for Java Message Service is the use of wildcards. These allow subscribers to subscribe to more than one topic at a time. Different brokers use different wildcard characters and different rules for their substitution. Use the broker version property of the topic (BROKERVER) to define which type of wildcards apply.

Note:
The broker version of a topic must match the broker version of the topic connection factory you are using.

Broker Version 1 wildcards
The "*" wildcard matches zero or more characters, while the "?" wildcard matches a single character.

If a subscriber subscribes to the topic represented by the following topic name: 

Sport/Football/*/Results

it receives publications on topics including:

If the subscription topic is: 

Sport/Football/Spurs/*

it receives publications on topics including:

If the subscription topic is: 

Sport/Football/*

it receives publications on topics including:

Broker Version 2 wildcards
The "#" wildcard matches multiple levels in a topic, the "+" wildcard matches a single level.

These wildcards can only be used to stand for complete levels within a topic; that is they can only be preceded by "/" or by start-of-string, and they can only be followed by "/" or by end-of-string.

If a subscriber subscribes to the topic represented by the following topic name: 

Sport/Football/+/Results

it receives publications on topics including:

If a subscriber subscribes to the topic represented by the following topic name: 

Sport/#/Results

it receives publications on topics including:

Although 

Sport/Football/Spur?/Results

works with broker version 1, there is no equivalent for broker version 2 which does not support single character substitutions.

There is no need to administer the topic hierarchies that you use on the broker-side of your system explicitly. When the first publisher or subscriber on a given topic comes into existence, the broker automatically creates the state of the topics currently being published on, and subscribed to.

Note:
A publisher cannot publish on a topic whose name contains wildcards.

Creating topics at runtime

There are four ways to create Topic objects at runtime:

  1. Construct a topic by using the one-argument MQTopic constructor
  2. Construct a topic by using the default MQTopic constructor, and then call the setBaseTopicName(..) method
  3. Use the session's createTopic(..) method
  4. Use the session's createTemporaryTopic() method

Method 1: Using MQTopic(..)
This method requires a reference to the WebSphere MQ implementation of the JMS Topic interface, and therefore renders the code non-portable.

The constructor takes one argument, which should be a uniform resource identifier (URI). For WebSphere MQ classes for Java Message Service Topics, this should be of the form: 

topic://TopicName[?property=value[&property=value]*]

For further details on URIs and the permitted name-value pairs, see Sending a message.

The following code creates a topic for non-persistent, priority 5 messages: 

// Create a Topic using the one-argument MQTopic constructor
String tSpec = "Sport/Football/Spurs/Results?persistence=1&priority=5";
Topic rtTopic = new MQTopic( "topic://" + tSpec );

Method 2: Using MQTopic(), then setBaseTopicName(..)
This method uses the default MQTopic constructor, and therefore renders the code non-portable.

After the object is created, set the baseTopicName property by using the setBaseTopicName method, passing in the required topic name.

Note:
The topic name used here is the non-URI form, and cannot include name-value pairs. Set these by using the "set" methods, as described in Setting properties with the 'set' method. The following code uses this method to create a topic: 
// Create a Topic using the default MQTopic constructor
Topic rtTopic = new MQTopic();
 
// Set the object properties using the setter methods
((MQTopic)rtTopic).setBaseTopicName( "Sport/Football/Spurs/Results" );
((MQTopic)rtTopic).setPersistence(1);
((MQTopic)rtTopic).setPriority(5);

Method 3: Using session.createTopic(..)
A Topic object may also be created by using the createTopic method of TopicSession, which takes a topic URI as follows: 
// Create a Topic using the session factory method
Topic rtTopic = session.createTopic( "topic://Sport/Football/Spurs/Results" );

Although the createTopic method is in the JMS specification, the format of the string argument is vendor-specific. Therefore, using this method may make your code non-portable.

Method 4: Using session.createTemporaryTopic()
A TemporaryTopic is a Topic that may be consumed only by subscribers that are created by the same TopicConnection. A TemporaryTopic is created as follows: 
// Create a TemporaryTopic using the session factory method
Topic rtTopic = session.createTemporaryTopic();

© IBM Corporation 1997, 2002. All Rights Reserved