82 lines
3.3 KiB
Markdown
82 lines
3.3 KiB
Markdown
# Intercepting Operations
|
|
|
|
Apache ActiveMQ 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.
|
|
|
|
## Implementing The Interceptors
|
|
|
|
An interceptor must implement the `Interceptor interface`:
|
|
|
|
``` java
|
|
package org.apache.activemq.api.core.interceptor;
|
|
|
|
public interface Interceptor
|
|
{
|
|
boolean intercept(Packet packet, RemotingConnection connection) throws ActiveMQException;
|
|
}
|
|
```
|
|
|
|
The returned boolean value is important:
|
|
|
|
- if `true` is returned, the process continues normally
|
|
|
|
- if `false` is returned, the process is aborted, no other
|
|
interceptors will be called and the packet will not be processed
|
|
further by the server.
|
|
|
|
## Configuring The Interceptors
|
|
|
|
Both incoming and outgoing interceptors are configured in
|
|
`activemq-configuration.xml`:
|
|
|
|
<remoting-incoming-interceptors>
|
|
<class-name>org.apache.activemq.jms.example.LoginInterceptor</class-name>
|
|
<class-name>org.apache.activemq.jms.example.AdditionalPropertyInterceptor</class-name>
|
|
</remoting-incoming-interceptors>
|
|
|
|
<remoting-outgoing-interceptors>
|
|
<class-name>org.apache.activemq.jms.example.LogoutInterceptor</class-name>
|
|
<class-name>org.apache.activemq.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.
|
|
|
|
## Interceptors on the Client Side
|
|
|
|
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
|
|
`ActiveMQException` 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 `ActiveMQException` 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.
|
|
|
|
## Example
|
|
|
|
See the examples for an example which shows how to use interceptors to add
|
|
properties to a message on the server.
|