JBoss.orgCommunity Documentation

Chapter 46. Intercepting Operations

46.1. Implementing The Interceptors
46.2. Configuring The Interceptors
46.3. Interceptors on the Client Side
46.4. Example

HornetQ supports interceptors to intercept packets entering and exiting the server. Incoming and outgoing interceptors are be called for any packet entering or exiting the server respectively. This allows custom code to be executed, e.g. for auditing packets, filtering or other reasons. Interceptors can change the packets they intercept. This makes interceptors powerful, but also potentially dangerous.

An interceptor must implement the Interceptor interface:

package org.hornetq.api.core.interceptor;

public interface Interceptor
{   
   boolean intercept(Packet packet, RemotingConnection connection) throws HornetQException;
}

The returned boolean value is important:

Both incoming and outgoing interceptors are configured in hornetq-configuration.xml:

<remoting-incoming-interceptors>
   <class-name>org.hornetq.jms.example.LoginInterceptor</class-name>
   <class-name>org.hornetq.jms.example.AdditionalPropertyInterceptor</class-name>
</remoting-incoming-interceptors>
<remoting-outgoing-interceptors>
   <class-name>org.hornetq.jms.example.LogoutInterceptor</class-name>
   <class-name>org.hornetq.jms.example.AdditionalPropertyInterceptor</class-name>
</remoting-outgoing-interceptors>

The interceptors classes (and their dependencies) must be added to the server classpath to be properly instantiated and called.

The interceptors can also be run on the client side to intercept packets either sent by the client to the server or by the server to the client. This is done by adding the interceptor to the ServerLocator with the addIncomingInterceptor(Interceptor) or addOutgoingInterceptor(Interceptor) methods.

As noted above, if an interceptor returns false then the sending of the packet is aborted which means that no other interceptors are be called and the packet is not be processed further by the client. Typically this process happens transparently to the client (i.e. it has no idea if a packet was aborted or not). However, in the case of an outgoing packet that is sent in a blocking fashion a HornetQException will be thrown to the caller. The exception is thrown because blocking sends provide reliability and it is considered an error for them not to succeed. Blocking sends occurs when, for example, an application invokes setBlockOnNonDurableSend(true) or setBlockOnDurableSend(true) on its ServerLocator or if an application is using a JMS connection factory retrieved from JNDI that has either block-on-durable-send or block-on-non-durable-send set to true. Blocking is also used for packets dealing with transactions (e.g. commit, roll-back, etc.). The HornetQException thrown will contain the name of the interceptor that returned false.

As on the server, the client interceptor classes (and their dependencies) must be added to the classpath to be properly instantiated and invoked.

See Section 11.1.27, “Interceptor” for an example which shows how to use interceptors to add properties to a message on the server.