Figure 1: The TopicSubscribeAsynchronous Application: This application catches the messages sent by running the TopicPublish application three times.

Reading from a Topic (a.k.a. Subscribing)
The code for retrieving messages from the topic is programmatically very similar to retrieving messages from a queue. You can retrieve messages both synchronously and asynchronously in the publish/subscribe message domain, just as you can in the point-to-point messaging domain. Listings 3 and 4 show examples of each. Paralleling the point-to-point examples, the class TopicSubscribeSynchronous.java (see Listing 2) uses the "receive" method.

On the other hand, the TopicSubscribeAsynchronous.java class (see Listing 3) uses the onMessage method, which it is obligated to do because it implements the MessageListener interface.

After running TopicPublish a number of times, you'll see that the TopicSubscribeAsynchronous application processes each incoming message on the topic1 topic (see Figure 1).

Figure 2: The OpenJMS Administrator GUI: You can use the Administrator GUI application to create and configure queues and topics, as well as configure JNDI, security, and garbage collection settings.

Creating Your Own Topics and Queues
The sample code for this article uses instances (queues and topics) preconfigured by the install program for OpenJMS. You can create your own queues and topics using the OpenJMS administration API, via the OpenJMS configuration file (openjms.xml) or via the OpenJMS Administrator GUI. You launch the Administrator GUI by running the admin batch file in the bin directory (see Figure 2).

You can configure a number of items (JNDI, Security, Garbage Collection) via XML configuration files (see the OpenJMS configuration documentation on SourceForge).

To add queues and topics, simply add to the <AdministeredDestinations> section of the openjms.xml file (located in the config directory of your OpenJMS installation):

   <AdministeredDestinations>
       <AdministeredTopic name="topic1">
         <Subscriber name="sub1" />
         <Subscriber name="sub2" />
       </AdministeredTopic>
       <AdministeredTopic name="topic2"/>
     
       <AdministeredQueue name="queue1" />
       <AdministeredQueue name="queue2" />
       <AdministeredQueue name="queue3" />
     </AdministeredDestinations>

For example, to add a topic named "kulvirTopic" and a queue named "kulvirQueue" you would modify the configuration file as follows:

   <AdministeredDestinations>
       <AdministeredTopic name="topic1">
         <Subscriber name="sub1" />
         <Subscriber name="sub2" />
       </AdministeredTopic>
       <AdministeredTopic name="topic2"/>
       <AdministeredTopic name="kulvirTopic" />  
   
       <AdministeredQueue name="queue1" />
       <AdministeredQueue name="queue2" />
       <AdministeredQueue name="queue3" />
       <AdministeredQueue name="kulvirQueue" />
     </AdministeredDestinations>

After modifying the configuration file, restart OpenJMS. The new configuration binds both the new kulvirTopic topic and the new kulvirQueue queue in JNDI.

OpenJMS Limitations
OpenJMS does have some limitations. For example, OpenJMS does not support XA transactions or high availability through clustering and failover. Consequently, if you need those more advanced and coveted features, a commercial JMS implementation might be more appropriate. Despite its enterprise-level limitations, OpenJMS is a great tool for learning JMS programming.

In this article, you saw how to interact with the JMS server programmatically using small client applications and how to create new queues and topics for the OpenJMS server by modifying its configuration file. I have covered only the basics of OpenJMS; there is a lot more to it than appears in this article. You can learn more about OpenJMS on the project homepage. The open source community improves OpenJMS constantly, so check for updates often.