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

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; 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:

  • Sport/Football/Spurs/Results

  • Sport/Football/Arsenal/Results

If the subscription topic is: 

Sport/Football/Spurs/*

it receives publications on topics including:

  • Sport/Football/Spurs/Results

  • Sport/Football/Spurs/Signings

If the subscription topic is: 

Sport/Football/*

it receives publications on topics including:

  • Sport/Football/Arsenal/Results

  • Sport/Football/Spurs/Results

  • Sport/Football/Spurs/Signings

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

These wildcards can be used only to stand for complete levels within a topic; that is they can be preceded only by / or start-of-string, and they can be followed only by / or 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:

  • Sport/Football/Spurs/Results

  • Sport/Football/Arsenal/Results

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

Sport/#/Results

it receives publications on topics including:

  • Sport/Football/Spurs/Results

  • Sport/Football/Arsenal/Results

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 using the one-argument MQTopic constructor

  2. Construct a topic 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 must be a uniform resource identifier (URI). For WebSphere MQ classes for Java Message Service Topics, this must 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 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(..)
You can also create a Topic object 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 might make your code non-portable.

Method 4: Using session.createTemporaryTopic()
A TemporaryTopic is a Topic that can 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();

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.