Using Virtual Destinations (Advanced)

Exclusive offer: get 50% off this eBook here
Instant Apache ActiveMQ Messaging Application Development How-to [Instant]

Instant Apache ActiveMQ Messaging Application Development How-to [Instant] — Save 50%

Develop message-based applications using ActiveMQ and the JMS with this book and ebook

$14.99    $7.50
by Timothy Bish | September 2013 | Open Source

In this article by Timothy Bish, the author of the book Instant Apache ActiveMQ Messaging Application, we are going to look at ActiveMQ's Virtual Destinations feature and learn how it can save us from the many limitations that come with using durable topic subscriptions.

(For more resources related to this topic, see here.)

Getting ready

For this article we will use the sample application virtual-destinations to demonstrate the use of Virtual Destinations.

How to do it...

To run the sample for this article, open a terminal, change the path to point to the directory where virtual-destinations is located, and run it by typing mvn compile exec:java.

In the terminal where you started the example, you will see output similar to the following snippet, indicating that the application is running:

Starting Virtual Destination example now...
Queue A Consumer 1 processed 500 Messages
Queue A Consumer 2 processed 500 Messages
Queue B Consumer processed 1000 Messages
Finished running the Virtual Destination example.

How it works...

Our example takes advantage of ActiveMQ's Virtual Destination feature to allow a JMS Producer to send messages to a topic and have those messages be received by a number of queue consumers. Let's take a look at the sent code first:

private void sendMessages() throws Exception {
Connection connection =
Session session = connection.createSession(false,
Destination destination =
MessageProducer producer =
for (int i = 0; i < 1000; ++i) {

As we can see, there's not much new here; we are just using standard JMS API code to send our messages. The important part is in the name of the topic destination VirtualTopic.Foo, which informs ActiveMQ Broker we want this topic to be one of those special Virtual Destinations.

Now let's take a look at the consumer code, and then we'll try and make sense of how this works:

Queue queueA =
VirtualMessageListener listenerA1 = new
MessageConsumer consumerA1 =
VirtualMessageListener listenerA2 = new
MessageConsumer consumerA2 =

 Queue queueB =
VirtualMessageListener listenerB = new
MessageConsumer consumerB =

As we can see, the consumer code is also not very mysterious; we create two consumers on the Consumer.A.VirtualTopic.Foo queue and one on the Consumer.B.VirtualTopic.Foo queue, and yet when we run the example, the two consumers on queue A split 500 of the topic message and the consumer on queue B gets its own copy of the 1,000 messages. So what's happening on the broker then to make this happen?

By default, whenever a topic is created with a name matching the pattern VirtualTopic.<TopicName>, we gain access to the feature known as Virtual Destinations. These Virtual Destinations allow us to send a message to a topic but create consumers that have all the benefits of queue consumers, namely, those of load balancing and message persistence. Our queue consumers just need to use their own naming convention to access the Virtual Destination functionality. Each queue that we want to create must be named using the pattern Consumer.<Name>.VirtualTopic.<TopicName>.

In the following figure we can see a visual representation of the message flow in our example:

As messages are sent to our example's topic, they are distributed to both the queues we created. Two of our consumers split the work of processing messages from queue A, while the other consumer gets all the messages from queue B. In our example we didn't attach a listener to the topic itself, but we could have done so and it would also have received all the messages we sent. It's easy to imagine using the topic as a way to monitor the messages that are being distributed to the queue consumers in this scenario; this pattern is often referred to as a wiretap.

If it isn't already apparent, Virtual Destinations are a very powerful feature for your messaging applications. Topics are great for broadcasting events but when we need to be able to consume messages that were sent while a client was offline, the only recourse is to use a durable topic subscription. Unfortunately, durable subscriptions have a number of limitations, the least of which is that only one JMS connection can be actively subscribed to a logical topic subscription. This means that we can't load balance messages and we can't have fast failover if a subscriber goes down. Virtual Destinations solve these problems since all of our consumers subscribe to a queue so their messages are persistent, and the work of processing the messages on the queue can be shared by more than one active subscription.

There's more...

The naming pattern for Virtual Destinations is not set in stone. By default, ActiveMQ is configured to use the pattern we used in our sample application, but you can easily change this. In the following XML snippet, we configured our broker to all topics on our broker into virtual topics. We use the wildcard syntax here, which matches every topic name a client sends messages to:

<virtualDestinations><virtualTopic name=">" prefix="VirtualTopic

More information on Virtual Destinations can be found on the ActiveMQ website,


This article thus explained what Virtual Destinations are and how to use them to avoid the limitations of JMS's durable topic subscriptions.

Resources for Article:

Further resources on this subject:

Instant Apache ActiveMQ Messaging Application Development How-to [Instant] Develop message-based applications using ActiveMQ and the JMS with this book and ebook
Published: May 2013
eBook Price: $14.99
See more
Select your format and quantity:

About the Author :

Timothy Bish

Timothy Bish is a senior software engineer currently working for RedHat Inc. He currently works out of his home in Alexandria, VA, actively contributing to the ActiveMQ Project. Timothy started his work in the open source world as a side project while working for a company in Syracuse NY. What started as something fun turned into a full time career and remains a passion for Timothy.

Timothy started his career in software development in 1999 and has worked for several years in the private sector before moving into full time open source development. During that time Timothy earned his Masters of Computer Engineering from Syracuse University. Having worked on a number of home grown Messaging frameworks Timothy has seen firsthand how the world of open source software like ActiveMQ has transformed the development world.

Besides working on new development projects Timothy also enjoys reading, skiing, scuba diving, and traveling to new and exotic places.

Books From Packt

Instant Apache ServiceMix How-to [Instant]
Instant Apache ServiceMix How-to [Instant]


Instant Apache Camel Message Routing [Instant]
Instant Apache Camel Message Routing [Instant]

HornetQ Messaging Developer’s Guide
HornetQ Messaging Developer’s Guide

Instant RabbitMQ Messaging Application Development How-to [Instant]
Instant RabbitMQ Messaging Application Development How-to [Instant]

Apache Solr 4 Cookbook
Apache Solr 4 Cookbook

Apache Solr 3 Enterprise Search Server
Apache Solr 3 Enterprise Search Server

Microsoft BizTalk Server 2010 Patterns
Microsoft BizTalk Server 2010 Patterns

Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software