This article is based on ActiveMQ in Action, published 24-March-2011. It is being reproduced here by permission from Manning Publications. Manning publishes MEAP (Manning Early Access Program,) ebooks and pbooks. MEAPs are sold exclusively through Manning.com. All print book purchases include an ebook free of charge. When mobile formats become available all customers will be contacted and upgraded. Visit Manning.com for more information.
Extending functionality with interceptor plugins
Introduction
ActiveMQ provides the ability to supply custom code in order to extend broker functionality. Doing so requires a good understanding of the ActiveMQ broker internals, which, unfortunately, is outside the scope of this article. However, there are some ActiveMQ broker interceptor plugins that are provided with the ActiveMQ distribution.
We will start with visualisation, which in fact is two different plugins and generates graphical representations of Connections and Destinations.
Visualization
There are two visualisation plugins that you can use to generate a graph visualisation file, which contains structural information for viewing structured data. Several tools allow you to visualise the generated files, like Graphviz (www.graphviz.org).
There are two types of visualisation plugins available, one for Connections (and associated Consumers and Producers)—called connectionDotFilePlugin—and one for generating a destination hierarchy of all the Queues and Topics used in the ActiveMQ Broker—called destinationDotFilePlugin. When these plugins are enabled, they generate a DOT file on disk. A DOT file contains the structural information in a directed graph notation, suitable to be read by a graph visualisation tool.
connectionDotFilePlugin writes the information about the client connections attached to the ActiveMQ broker to a DOT file on disk. By default, the file is written into the current directory from which the ActiveMQ broker was started and is called ActiveMQConnections.dot. The information about each client connection, including the Destinations to or from that client connection is sending or receiving messages, is also written to the DOT file.
Every time a change in a client connection occurs (for example, a MessageConsumer starts, or stops or a new
client connection starts, or an old one stops), the DOT file will be overwritten.
connectionDotFilePlugin has only one property, the name of file to write the state information into, as shown in
table 1.
destinationDotFilePlugin is very similar to connectionDotFilePlugin. When this plugin is enabled, it writes the state information about the Destinations currently in use by the ActiveMQ broker to a DOT file that, by default, is called ActiveMQDestinations.dot. Whenever the state information of Destinations changes within the broker, this DOT file is updated. An example of the rendered DOT file for the destinationDotFilePlugin is shown in figure 1.
destinationDotFilePlugin has only one property, the name of the file for the state information, as shown in table
2.
All ActiveMQ broker plugins can be enabled within the configuration file for the broker. Listing 1 shows an ActiveMQ broker configuration file that has connectionDotFilePlugin and destinationDotFilePlugin enabled.
Listing 1 Configuring visualization plugins for the ActiveMQ Broker
<beans>
<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>
<broker useJmx="false" persistent="true" xmlns="http://activemq.apache.org/schema/core">
<plugins>
<connectionDotFilePlugin file = "ActiveMQConnections.dot" />
<destinationDotFilePlugin file ="ActiveMQDestinations.dot"/>
</plugins>
</broker>
</beans>
Visualisation can be a really useful tool for identifying usage patterns for an ActiveMQ broker. For example, being able to see a diagram of all the connections and the Destinations that they are consuming messages from has helped identify rogue applications in production environments on more than one occasion.
The next Plugin we will look at was developed by one of the many users of ActiveMQ, to enhance the logging available for the ActiveMQ broker.
Enhanced logging
If configured, Logging Interceptor (loggingInterceptor), allows you to log messages that are sent or acknowledged on an ActiveMQ broker. This is in addition to the normal logging done by ActiveMQ. Using the Logging Interceptor can be useful for tracing problems or auditing messages. A few properties for the Logging Interceptor can be configured, as shown in table 3.
Central timestamp messages with Timestamp Interceptor Plugin
If configured, Timestamp plugin (timestampingBrokerPlugin), is an ActiveMQ Broker interceptor plugin that updates the timestamp on messages as they arrive at the broker. This can be useful when there is a difference (however
small) between the system clocks on the computer sending messages to an ActiveMQ broker and the computer on which the broker resides. When messages are sent with the timeToLive property set, it’s important that the system clocks between the sending machine and the broker are in sync; else messages may get expired erroneously. A few properties for the Timestamp plugin can be configured, as shown in table 4.
It is recommended that the timestampingBrokerPlugin is enabled on the ActiveMQ broker if you are using timeToLive on messages. The next interceptor plugin is used for generating messages about management statistics for the ActiveMQ broker.
Statistics
statisticsBrokerPlugin will send MapMessages containing information regarding the statistics about the running of the ActiveMQ broker. There are two types of message, one for destinations and one that gives an overview of the broker itself.
To retrieve the statistics of the running broker with statisticsBrokerPlugin plugin enabled, send an empty message to the destination (Queue or Topic—it doesn’t matter) called ActiveMQ.Statistics.Broker. The JMSReplyTo destination of the message is used to send the statistics message.
Similarly, to retrieve information about a destination, send an empty message to the name of the destination, prepended with ActiveMQ.Statistics.Destination. For example, to retrieve the statistics for the destination Topic.Foo send a message to the destination ActiveMQ.Statistics.DestinationTopic.Foo.
You enable an ActiveMQ Broker plugin by including it in the Broker configuration file, as shown in listing 2.
Listing 2 Configuring plugins for the Broker
<beans>
<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>
<broker useJmx="false" persistent="false" xmlns="http://activemq.apache.org/schema/core">
<plugins>
<loggingBrokerPlugin logAll="true" logConnectionEvents="false"/>
<timeStampingBrokerPlugin zeroExpirationOverride="1000" ttlCeiling="60000" futureOnly="
<statisticsBrokerPlugin/>
</plugins>
</broker>
</beans>
Broker Interceptors are a useful addition for extending the functionality of ActiveMQ. However, you can provide more features and flexibility by embedding Apache Camel, the powerful integration framework, in the ActiveMQ Broker.
Summary
In this article, we have covered how to use interceptor plugins in ActiveMQ for extending flexibility and functionality of the message broker.