Interceptors

What are they :

Interceptors are simple POJOs written to intercept Message Exchanges and/or Messages flowing between two components.

How to write an interceptor :

A simple java class can intercept message exchanges and/or messages by defining interceptor methods. An interceptor method is one which :

1. Is annotated with the Intercept annotation. See Intercept annotation below.
2. Has a single parameter. Based on the parameter type the method intercepts : Messages, Message Exchanges or Message Payloads. For instance if the parameter type is javax.jbi.messaging. MessageExchange then the method intercepts the exchange if the type is java.lang.String and the Message has an Object payload of type java.lang.String then the method intercepts the payload. If the parameter type does not match any of the message exchange content, then the interceptor method will not be invoked.

• Interceptor method details :
  • The interceptor method can throw a java.lang.Exception, in which case the MessageExchange is flagged as an error and sent back to the sender of the exchange.
  • There can be more than one interceptor method in a java class.
  • A single class can implement more than one method to intercept messages and message exchanges.
  • If a method does not have the @Intercept annotation it is not considered to be an interceptor method.
  • An interceptor method may modify the parameter being passed in, in which case it should return the modified object.
  • Should have "public" accessibility

Examples of annotated interceptor methods :

• A read-write message interceptor :

       @Intercept()
       public ServiceMessage foo(ServiceMessage message)

• A read-only message interceptor :

       @Intercept()
       public void foo(ServiceMessage message)

• A read-write message interceptor, which throws an Exception

       @Intercept()
       public ServiceMessage foo(ServiceMessage message)
               throws Exception;

• A read-write message exchange interceptor

       @Intercept()
       public MessageExchange someInterceptorMethod(MessageExchange exchange)

Interception scope :

The interceptor methods in the example above are invoked on each message exchange, this might be overwhelming for the interceptor. The scope of the interception can be limited by specifying additional properties on the Intercept annotation, these being : provider, consumer, message and service.

The following interceptor method is invoked when the message being exchanged is from provider "p1" providing a service "s1" to consumer "c1"

       @Intercept (provider="p1", consumer="c1", service="s1")
       public void myInterceptorMethod(MessageExchange exchange)

If an annotation property is not specified, it implies "*" i.e. all.

Interceptor priority :

Since there will be many such interceptor methods defined, and one interceptor might need to be called before another. For example a message needs to be decrypted before validating the signature, in this case a higher priority can be assigned to the decryption interceptor method, by specifying the priority on the Intercept Annotation :

Example :

       @Intercept (priority="0")
       public ServiceMessage decrypt(ServiceMessage message)

       @Intercept (priority="1")
       public ServiceMessage validateSignature(ServiceMessage message)
               throws Exception;

The values for priority are in the range 0 .. Integer.MAX_VALUE , with 0 being the highest priority and Integer.MAX_VALUE being the lowest. The default priority if not specified is 100.

Intercept Annotation :

The Intercept annotation is the key to flagging a method as an interceptor, specifying the scope of the interception and it's priority.

It is defined as follows :

@Target(value = {ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Intercept      
{
    String consumer() default "";
    String provider() default "";
    String message()  default "";
    String service() default "";
    int priority() default 100;
}

How to add an interceptor to the runtime :

• In Service Assemblies : Any application class can be an interceptor.
• In OSGi Bundles : Any bundle class can be an interceptor.

Runtime details :

Interceptor classes in Service Assemblies :

When a service assembly is deployed the runtime will introspect each and every class in the bundle and register the interceptor classes as Interceptor's in the OSGi service registry. This is done by wrapping the application class instance in a service object that implements the Interceptor interface and registering the service in the service registry.

The Interceptor interface is an empty marker interface :

     public interface Interceptor{}

Interceptor classes in OSGi Bundles :

Bundles installed in the runtime will be examined similar to service assemblies and any interceptor classes will be registered in the service registry in a similar process.

Interceptor Wrapper

This is a POJO that implements the Interceptor interface and wraps the interceptor class.

Interception Point

Message Exchanges are intercepted just after the message exchange is sent on the delivery channel and before the NMR routes it to the receiving component. At this point all the interceptors registered in the service registry are queried and those in scope are invoked based on priority. If an interceptor method throws a exception the exchange status is set as ERROR and the exchange is sent back to the sender.

The interceptors are invoked on the same thread on which the send operation is invoked.

This page (revision-18) was last changed on 02-Oct-08 22:23 PM, -0700 by Mark Saunders.
This page was created on 20-May-08 10:52 AM, -0700 by JBIWIKI.

More info...