Master JMS Messaging with OpenJMS

rganizations are increasingly demanding applications where communication between software components is loosely coupled and often asynchronous. In asynchronous communication, an application sends a message, and then continues program execution without waiting for a response. In a loosely coupled system, the sending program might not even know where or what the recipient is, because the communication between software components takes place via messaging. The Java Messaging Service (JMS) is the only messaging API supported by J2EE.

OpenJMS, a SourceForge project, is a free open source implementation of Sun Microsystems' JMS API 1.0.2 specification. In this article you'll see how to install and use OpenJMS, along with code samples that illustrate the point-to-point and publish/subscribe messaging models it supports.

This article is not intended to be a tutorial on JMS; rather, it's intended to show you how to use OpenJMS. If you are unfamiliar with JMS basics you should consider taking a look at Sun's Java Message Service Tutorial before reading this article.

Obtaining and Installing OpenJMS
You can download OpenJMS from http://openjms.sourceforge.net/downloads.html. OpenJMS runs in both Windows and UNIX environments, and requires a Java 2 runtime environment. Throughout this article, I'll assume you're using Windows as your operating platform. Refer to the OpenJMS documentation for UNIX instructions. At the time of this article's writing, OpenJMS was in version 0.7.6. The download contains the code necessary for running the OpenJMS server as well as the client JARS needed to write client applications that interact with the server. The download also includes documentation and sample programs.

To install OpenJMS, simply extract the files from the downloaded archive with WinZip, or with the JAR tool using the command:

   jar xvf openjms-0.7.6.zip

Before firing up the OpenJMS server, you need to set a couple of environment variables: a JAVA_HOME variable pointing to the directory where your Java 2 runtime is installed (e.g., C:\jdk1.3.1_11\bin) and an OPENJMS_HOME variable pointing to the OpenJMS install directory (e.g., C:\openjms-0.7.6).

To start the OpenJMS messaging server, use the following commands:

   cd %OPENJMS_HOME%\bin
   startup

Similarly, you can shut down the server using the shutdown command.

   cd %OPENJMS_HOME%\bin
   shutdown

After launching the server, you are ready to interact with it using Java programs that leverage the JMS API. Client applications must have the appropriate jar files: jms-1.02a.jar, openjms-0.7.6.jar, and openjms-client-0.7.6.jar on the Java build path. You'll find all these in the lib directory of your OpenJMS installation.

Getting a JNDI Context
By default, OpenJMS uses an embedded JNDI (Java Naming and Directory Interface) provider which listens to port 1099. As you will see, you can use JNDI to store connection factories, topics, and queues. OpenJMS allows you to use a third-party JNDI provider, but this article's code uses the embedded provider. To access topics and queues, you will need to create a JNDI context exemplified with the code below:

   import java.util.Hashtable;
   import javax.naming.Context;
   import javax.naming.InitialContext;
   ...
   Hashtable properties = new Hashtable();
   properties.put(Context.INITIAL_CONTEXT_FACTORY,
      "org.exolab.jms.jndi.InitialContextFactory");
   properties.put(Context.PROVIDER_URL,
      "rmi://localhost:1099/");
   Context context = new InitialContext(properties);

You'll see the syntax above in all the provided code samples, so for brevity, in the remainder of this article you'll see a comment where the boilerplate code belongs.