101 lines
6.2 KiB
XML
101 lines
6.2 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
||
<!-- ============================================================================= -->
|
||
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
|
||
<!-- -->
|
||
<!-- The text of and illustrations in this document are licensed by Red Hat under -->
|
||
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
|
||
<!-- -->
|
||
<!-- An explanation of CC-BY-SA is available at -->
|
||
<!-- -->
|
||
<!-- http://creativecommons.org/licenses/by-sa/3.0/. -->
|
||
<!-- -->
|
||
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
|
||
<!-- of it, you must provide the URL for the original version. -->
|
||
<!-- -->
|
||
<!-- Red Hat, as the licensor of this document, waives the right to enforce, -->
|
||
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
|
||
<!-- permitted by applicable law. -->
|
||
<!-- ============================================================================= -->
|
||
|
||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||
<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent">
|
||
%BOOK_ENTITIES;
|
||
]>
|
||
|
||
<chapter id="intercepting-operations">
|
||
<title>Intercepting Operations</title>
|
||
<para>HornetQ supports <emphasis>interceptors</emphasis> 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.</para>
|
||
<section>
|
||
<title>Implementing The Interceptors</title>
|
||
<para>An interceptor must implement the <literal>Interceptor interface</literal>:</para>
|
||
<programlisting>
|
||
package org.apache.activemq.api.core.interceptor;
|
||
|
||
public interface Interceptor
|
||
{
|
||
boolean intercept(Packet packet, RemotingConnection connection) throws ActiveMQException;
|
||
}</programlisting>
|
||
<para>The returned boolean value is important:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>if <literal>true</literal> is returned, the process continues normally</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>if <literal>false</literal> is returned, the process is aborted, no other interceptors
|
||
will be called and the packet will not be processed further by the server.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
<section>
|
||
<title>Configuring The Interceptors</title>
|
||
<para>Both incoming and outgoing interceptors are configured in
|
||
<literal>hornetq-configuration.xml</literal>:</para>
|
||
<programlisting>
|
||
<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></programlisting>
|
||
<programlisting>
|
||
<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></programlisting>
|
||
<para>The interceptors classes (and their dependencies) must be added to the server classpath
|
||
to be properly instantiated and called.</para>
|
||
</section>
|
||
<section>
|
||
<title>Interceptors on the Client Side</title>
|
||
<para>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 <code>ServerLocator</code> with the <code>addIncomingInterceptor(Interceptor)</code> or
|
||
<code>addOutgoingInterceptor(Interceptor)</code> methods.</para>
|
||
<para>As noted above, if an interceptor returns <literal>false</literal> 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 <literal>blocking</literal> fashion a <literal>ActiveMQException</literal> 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. <literal>Blocking</literal> sends occurs when,
|
||
for example, an application invokes <literal>setBlockOnNonDurableSend(true)</literal> or
|
||
<literal>setBlockOnDurableSend(true)</literal> on its <literal>ServerLocator</literal> or if an
|
||
application is using a JMS connection factory retrieved from JNDI that has either
|
||
<literal>block-on-durable-send</literal> or <literal>block-on-non-durable-send</literal>
|
||
set to <literal>true</literal>. Blocking is also used for packets dealing with transactions (e.g.
|
||
commit, roll-back, etc.). The <literal>ActiveMQException</literal> thrown will contain the name
|
||
of the interceptor that returned false.</para>
|
||
<para>As on the server, the client interceptor classes (and their dependencies) must be added to the classpath
|
||
to be properly instantiated and invoked.</para>
|
||
</section>
|
||
<section>
|
||
<title>Example</title>
|
||
<para>See <xref linkend="examples.interceptor" /> for an example which
|
||
shows how to use interceptors to add properties to a message on the server.</para>
|
||
</section>
|
||
</chapter>
|