Using Interceptors

An interceptor is defined using one of the interceptor metadata annotations listed in Table 50-1 within the target class, or in a separate interceptor class. The following code declares an @AroundTimeout interceptor method within a target class.

@Stateless
public class TimerBean {
...
    @Schedule(minute="*/1", hour="*")
    public void automaticTimerMethod() { ... }

    @AroundTimeout
    public void timeoutInterceptorMethod(InvocationContext ctx) { ... }
...
}

If interceptor classes are used, use the javax.interceptor.Interceptors annotation to declare one or more interceptors at the class or method level of the target class. The following code declares interceptors at the class level.

@Stateless
@Interceptors({PrimaryInterceptor.class, SecondaryInterceptor.class})
public class OrderBean { ... }

The following code declares a method-level interceptor class.

@Stateless
public class OrderBean {
...
    @Interceptors(OrderInterceptor.class)
    public void placeOrder(Order order) { ... }
...
}

Intercepting Method Invocations

The @AroundInvoke annotation is used to designate interceptor methods for managed object methods. Only one around-invoke interceptor method per class is allowed. Around-invoke interceptor methods have the following form:

@AroundInvoke
visibility Object method-name(InvocationContext) throws Exception { ... }

For example:

@AroundInvoke
public void interceptOrder(InvocationContext ctx) { ... }

Around-invoke interceptor methods can have public, private, protected, or package-level access, and must not be declared static or final.

An around-invoke interceptor can call any component or resource callable by the target method on which it interposes, have the same security and transaction context as the target method, and run in the same Java virtual machine call-stack as the target method.

Around-invoke interceptors can throw any exception allowed by the throws clause of the target method. They may catch and suppress exceptions, and then recover by calling the InvocationContext.proceed method.

Using Multiple Method Interceptors

Use the @Interceptors annotation to declare multiple interceptors for a target method or class.

@Interceptors({PrimaryInterceptor.class, SecondaryInterceptor.class, 
        LastInterceptor.class})
public void updateInfo(String info) { ... }

The order of the interceptors in the @Interceptors annotation is the order in which the interceptors are invoked.

Multiple interceptors may also be defined in the deployment descriptor. The order of the interceptors in the deployment descriptor is the order in which the interceptors will be invoked.

...
<interceptor-binding>
    <target-name>myapp.OrderBean</target-name>
    <interceptor-class>myapp.PrimaryInterceptor.class</interceptor-class>
    <interceptor-class>myapp.SecondaryInterceptor.class</interceptor-class>
    <interceptor-class>myapp.LastInterceptor.class</interceptor-class>
    <method-name>updateInfo</method-name>
</interceptor-binding>
...

To explicitly pass control to the next interceptor in the chain, call the InvocationContext.proceed method.

Data can be shared across interceptors:

• The same InvocationContext instance is passed as an input parameter to each interceptor method in the interceptor chain for a particular target method. The InvocationContext instance’s contextData property is used to pass data across interceptor methods. The contextData property is a java.util.Map<String, Object> object. Data stored in contextData is accessible to interceptor methods further down the interceptor chain.

• The data stored in contextData is not sharable across separate target class method invocations. That is, a different InvocationContext object is created for each invocation of the method in the target class.

Accessing Target Method Parameters From an Interceptor Class

The InvocationContext instance passed to each around-invoke method may be used to access and modify the parameters of the target method. The parameters property of InvocationContext is an array of Object instances that corresponds to the parameter order of the target method. For example, for the following target method, the parameters property, in the InvocationContext instance passed to the around-invoke interceptor method in PrimaryInterceptor, is an Object array containing two String objects (firstName and lastName) and a Date object (date):

@Interceptors(PrimaryInterceptor.class)
public void updateInfo(String firstName, String lastName, Date date) { ... }

The parameters can be accessed and modified using the InvocationContext.getParameters and InvocationContext.setParameters methods, respectively.

Intercepting Lifecycle Callback Events

Interceptors for lifecycle callback events (post-create and pre-destroy) may be defined in the target class or in interceptor classes. The @PostCreate annotation is used to designate a method as a post-create lifecycle event interceptor. The @PreDestroy annotation is used to designate a method as a pre-destroy lifecycle event interceptor.

Lifecycle event interceptors defined within the target class have the following form:

void method-name() { ... }

For example:

@PostCreate
void initialize() { ... }

Lifecycle event interceptors defined in an interceptor class have the following form:

void <method-name>(InvocationContext) { ... }

For example:

@PreDestroy
void cleanup(InvocationContext ctx) { ... }

Lifecycle interceptor methods can have public, private, protected, or package-level access, and must not be declared static or final.

Lifecycle interceptor methods are called in an unspecified security and transaction context. That is, portable Java EE applications should not assume the lifecycle event interceptor method has access to a security or transaction context. Only one interceptor method for each lifecycle event (post-create and pre-destroy) is allowed per class.

Using Multiple Lifecycle Callback Interceptors

Multiple lifecycle interceptors may be defined for a target class by specifying the interceptor classes in the @Interceptors annotation:

@Interceptors({PrimaryInterceptor.class, SecondaryInterceptor.class, 
        LastInterceptor.class})
@Stateless
public class OrderBean { ... }

The order in which the interceptor classes are listed in the @Interceptors annotation defines the order in which the interceptors are invoked.

Data stored in the contextData property of InvocationContext is not sharable across different lifecycle events.

Intercepting Timeout Events

Interceptors for EJB timer service timeout methods may be defined using the @AroundTimeout annotation on methods in the target class or in an interceptor class. Only one @AroundTimeout method per class is allowed.

Timeout interceptors have the following form:

Object <method-name>(InvocationContext) throws Exception { ... }

For example:

@AroundTimeout
protected void timeoutInterceptorMethod(InvocationContext ctx) { ... }

Timeout interceptor methods can have public, private, protected, or package-level access, and must not be declared static or final.

Timeout interceptors can call any component or resource callable by the target timeout method, and are invoked in the same transaction and security context as the target method.

Timeout interceptors may access the timer object associated with the target timeout method through the InvocationContext instance’s getTimer method.

Using Multiple Timeout Interceptors

Multiple timeout interceptors may be defined for a given target class by specifying the interceptor classes containing @AroundTimeout interceptor methods in an @Interceptors annotation at the class level.

If a target class specifies timeout interceptors in an interceptor class, and also has a @AroundTimeout interceptor method within the target class itself, the timeout interceptors in the interceptor classes are called first, followed by the timeout interceptors defined in the target class. For example, in the following example, assume that both the PrimaryInterceptor and SecondaryInterceptor classes have timeout interceptor methods.

@Interceptors({PrimaryInterceptor.class, SecondaryInterceptor.class})
@Stateful
public class OrderBean {
...
    @AroundTimeout
    private void last(InvocationContext ctx) { ... }
...
}

The timeout interceptor in PrimaryInterceptor will be called first, followed by the timeout interceptor in SecondaryInterceptor, and finally the last method defined in the target class.