Chapter 3. The ActiveMQ in Action examples

ActiveMQ provides all the features from the JMS specification and adds many more powerful features on top of that. This is depicted in figure 3.1 and these features will be discussed through the rest of the book. In order to best demonstrate these features, two new examples have been created that are modeled after real business domains. Compared to the example that’s part of the ActiveMQ distribution, these examples lend themselves to demonstrating the features in ActiveMQ in a more complete and easy manner.

One of the examples is based on a stock portfolio and the other is based on a job queue. These two examples are more extensive than the examples that come with ActiveMQ. The use case for each of these examples is introduced briefly, followed by a deeper discussion of how to use them. You can refer back to this chapter at any time throughout the book if you need a refresher on the examples.

The stock portfolio demonstrates the publish/subscribe messaging domain. Publishers broadcast stock price messages to many interested subscribers. Messages are published to a JMS destination called a topic and clients with active subscriptions receive messages. Using this model, the broker delivers messages to each subscriber without the need to poll for messages. Every active subscriber receives its own copy of each message published to the topic. Publishers are decoupled from subscribers via the topic. Unless durable subscriptions are used, subscribers must be active in order to receive messages sent by publishers to the topic. A copy of each message on a given destination is delivered to all topic subscribers using the pub/sub domain.

The job queue demonstrates the point-to-point (PTP) messaging domain. Message producers send job messages to a JMS queue, from which message consumers receive the job messages for processing. There’s no timing requirement for the producers and consumers to be online at the same time with the point-to-point domain. The queue holds messages until consumers are available to receive them. As consumers are available, messages are delivered to all consumers, but no two consumers receive the same message. Messages on a given destination are delivered to queue consumers in a round-robin fashion using the PTP domain.

Not only is each example focused on a different messaging domain, but each is also focused on a separate use case. Additionally, although the diagrams depicted later in this chapter for each example look nearly the same at first glance, the important difference between the two lies in the two messaging domains. The stock portfolio example uses topics for pub/sub messaging, whereas the job queue example uses queues for point-to-point messaging. The source for these examples is readily available and can be downloaded from the Manning website via the following URL: http://manning.com/snyder/activemq-in-action-examples-src.zip.

In this chapter, first we’ll download Maven and install it in order to compile and run the examples. After this is complete, we’ll review each example and demonstrate how each one should behave. After the completion of these exercises, you’ll be familiar enough with the examples to recognize them throughout the book and see how they’re used to demonstrate the features in ActiveMQ.

3.1. Downloading Maven and compiling the examples

Here are the steps to download and install Maven:

1.  Download Maven from the Apache Software Foundation: http://maven.apache.org/.

Maven is provided in both tarball and zip format, depending on your operating system.

2.  Expand the downloaded archive to a permanent location on your computer.

3.  Create an environment variable named M2_HOME that points to the Maven directory.

4.  On Unix, add the $M2_HOME/bin directory to the PATH environment variable (on Windows, add the %M2_HOME%\bin directory to the %PATH% environment variable).

5.  Verify the Maven installation by running the following command from the command line:

$ mvn -version
Apache Maven 2.2.1 (r801777; 2009-08-06 13:16:01-0600)
Java version: 1.5.0_19
Java home: /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/
Home
Default locale: en_US, platform encoding: MacRoman
OS name: "mac os x" version: "10.6.2" arch: "i386" Family: "unix"

You should see similar output which indicates that Maven is properly installed. If you don’t see similar output, you’ll need to rectify this before proceeding. See the Maven installation instructions for more information: http://maven.apache.org/download.html#Installation.

If you’ve successfully installed Maven, the examples need to be unzipped and compiled. After expanding the zip file containing the example source code, you’ll be ready to compile the examples. To do so, move into the amq-in-action-example-src directory and run the command shown next. For the convenience of recognizing the actual command apart from the rest of the output, the command itself is listed in bold.

Much of the output from the compilation of the examples has been elided for brevity. Suffice it to say that this output represents a successful compilation. As long as you see the BUILD SUCCESSFUL message, you’re ready to move on to the next section. If, on the other hand, you see the BUILD FAILURE message, you’ll need to troubleshoot and correct the situation before proceeding.

3.2. Use case one: the stock portfolio example

As mentioned earlier in the chapter, the first use case revolves around a stock portfolio use case for demonstrating publish/subscribe messaging. This example is simple and utilizes a Publisher class for sending stock price messages to a topic, as well as a Consumer class for registering a Listener class to consume messages from topics in an asynchronous manner. These three classes embody the functionality of generating ever-changing stock prices that are published to topics on which the consumer is subscribed.

In this example, stock prices are published to an arbitrary number of topics. The number of topics is based on the number of arguments sent to the Publisher and the Consumer on the command line. Each class will dynamically send and receive to/from the topics (an example is provided next). Take a look at figures 3.2 and 3.3 to see at a high level what the examples seek to achieve.

For the sake of this demonstration, two topics will be used. The Publisher class uses a single JMS MessageProducer to send 1,000 fictitious stock price messages in blocks of 10, randomly distributed across the topics named in the command-line argument. After it sends 1,000 messages, it shuts down. The Consumer class creates one JMS MessageConsumer per topic and registers a JMS MessageListener for each topic. Because this example demonstrates publish/subscribe, the Consumers must be online to consume messages being sent by the Publisher, because durable consumers aren’t used in the basic stock portfolio example. The next step is to actually run the example so that you can see them in action.

3.2.1. Running the stock portfolio example

There are three basic steps to running this example:

1.  Start up ActiveMQ

2.  Run the Consumer class

3.  Run the Publisher class

These steps appear to be simple, and they are. The only item of note is that the Consumer should be started before the Publisher, in order to receive all messages that are published. This is because this example demonstrates pub/sub messaging and topics won’t hold messages unless the consumer makes a durable subscription, and we’re not using durable subscriptions here. So let’s get started with the stock portfolio example.

The first task is to open a terminal or command line and execute ActiveMQ. This only requires a single command as demonstrated in the following listing.

The next task is to open a second terminal or command line to execute the Consumer class. The Consumer is executed using the maven-exec-plugin (http://mng.bz/bf7g) by passing it some system properties as arguments using the exec.args property. An example of running the Consumer is shown next.

You can see in listing 3.3 that Maven downloads the necessary artifacts it needs to run the examples. Once this has completed, the Publisher can start up and begin publishing stock prices to the two topics named on the command line, CSCO and ORCL. These two topic names were picked at random and can be replaced with any Strings you desire. The important part is that the same arguments be used for both the Consumer and the Publisher (the Publisher is shown next) via the system property exec.args.

Note that the output just seems to stop as the Consumer hangs there. This behavior is correct because it’s waiting for messages to arrive in the topics to be consumed. When the Publisher begins sending messages, the Consumer will begin to consume them.

The next task is to open a third terminal or command line to execute the Publisher class. Note that the same arguments are used in exec.args that were used for executing the Consumer class earlier, because the maven-exec-plugin is used to execute the Publisher class as well. An example of running Publisher is shown here.

When executing the Publisher class, Maven already has all the necessary dependencies from the earlier execution of the Consumer class, so nothing should be downloaded. The lower portion of the output shows the stock price messages being sent to the two topics in blocks of 10. The example output is truncated for space, so just know that the Publisher will run until it sends a total of 1,000 messages.

After running the Publisher, if you switch back to the second terminal where the Consumer was started, you should see that it’s now consuming messages from the topics:

The preceding output comes from the Listener class that’s registered by the Consumer on the two topics named ORCL and CSCO. This output shows the consumption of the stock price messages from the same two topics to which the Publisher is sending messages. Once the Publisher reaches 1,000 messages sent, it’ll shut down. But the Consumer will continue to run and just hang there waiting for more messages to arrive on those two topics. You can press CTRL-C in the second terminal to shut down the Consumer at this point.

Now that you’ve seen how ActiveMQ works well in a pub/sub messaging scenario, the following section will explore how it works in point-to-point messaging.

3.3. Use case two: the job queue example

The second use case focuses on job queues to illustrate point-to-point messaging. This example uses a Producer class to send job messages to a job queue and a Consumer class for registering a Listener class to consume messages from queues in an asynchronous manner. These three classes provide the functionality necessary to show how JMS point-to-point messaging should work. The classes in this example are extremely similar to those used in the stock portfolio example. The difference between the two examples is the JMS messaging domain that each uses.

The Producer class in this example sends messages to the JOBS.suspend and JOBS.delete queues and the Consumer class consumes. Figure 3.3 contains a high-level diagram of the job queue example’s functionality.

The Producer class uses a single JMS MessageProducer to send 1,000 job messages in blocks of 10 randomly across the two queues. After sending 1,000 messages total, it’ll shut down. The Consumer class uses one JMS MessageConsumer per queue and registers a JMS MessageListener on each queue to utilize the message and output its contents.

3.3.1. Running the job queue example

The steps for executing the job queues example are nearly identical to the previous example:

1.  Start up ActiveMQ

2.  Run the Producer class

3.  Run the Consumer class

Again, these steps are simple, but there’s one exception to note. When using PTP messaging, queues will hold messages until they’re consumed or the messages expire. So the Producer can be started before the Consumer and the Consumer won’t miss any messages.

Just as in the stock portfolio example, the first task is to start up ActiveMQ. You’ll be spared the output from this task, as it’s the same as shown in section 1.6 and none of the default configuration has been changed.

Next, open a second terminal or command line to execute the Producer as shown here.

Note that no arguments are necessary to execute the Producer in listing 3.5. The Publisher class contains two queues to which it publishes named delete and suspend; hence, the use of those words in the output. The Producer will continue until it sends a total of 1,000 messages to the two queues and then it’ll shut down.

The third task is to open another terminal or command line and execute the Consumer to consume the messages from the two queues. This command is shown next.

The Consumer will run fast at first, consuming all the messages already on the queues. When it catches up to where the Producer is in sending the 1,000 messages, the Consumer slows down and keeps up with the Publisher until it completes. When all the messages have been sent and the Producer shuts itself down, you’ll need to press CTRL-C in the third terminal where the Consumer is running to shut it down.

This concludes the job queue example. Now you’ve seen how well ActiveMQ works in a point-to-point messaging scenario.

3.4. Summary

This brief introduction to the book examples is meant to be just that—quick and focused. The jobs and portfolio use cases are common in the business world, but they’re only two use cases of many available for using messaging. Although these two use cases are meant to demonstrate the two JMS messaging domains at a high level, that doesn’t mean that they can’t do more. Using the features available in ActiveMQ, these two examples will be changed and adapted as the book progresses. So you’ll see much more of these examples throughout the chapters, just with slight variations.

Part 1 of the book took you through an introduction to ActiveMQ, where you gained a quick high-level understanding of ActiveMQ. Then the focus shifted to understanding message-oriented middleware and the JMS spec. Although these topics aren’t strictly about only ActiveMQ, each is important when it comes to understanding ActiveMQ. You also walked through the examples that will be used throughout the rest of the book. The subjects in this first part of the book are meant to be a warm-up for diving deeper into ActiveMQ. In part 2, you’ll learn about configuring various aspects of ActiveMQ for connectivity, message persistence, and security.