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.
