Package javax.interceptor

Contains annotations and interfaces for defining interceptor methods, interceptor classes and for binding interceptor classes to target classes.

See:
Description

Interface Summary

InvocationContext

Exposes context information about the intercepted invocation and operations that enable interceptor methods to control the behavior of the invocation chain.

Annotation Types Summary

AroundInvoke	Defines an interceptor method that interposes on business methods.
AroundTimeout	Defines an interceptor method that interposes on timeout methods.
ExcludeClassInterceptors	Used to exclude class-level interceptors for a business method or timeout method of a target class.
ExcludeDefaultInterceptors	Used to exclude default interceptors for a target class or for a business method or timeout method of a target class.
Interceptor	Specifies that a class is an interceptor.
InterceptorBinding	Specifies that an annotation type is an interceptor binding type.
Interceptors	Declares an ordered list of interceptors for a target class or method of a target class.

Package javax.interceptor Description

Contains annotations and interfaces for defining interceptor methods, interceptor classes and for binding interceptor classes to target classes.

Interceptor methods

An interceptor method may be defined on a target class itself or on an interceptor class associated with the target class.

There are three kinds of interceptor method:

• method interceptor methods for methods of a target class (e.g. managed bean / EJB component)
• timeout method interceptor methods for timeout methods of a target class (e.g. EJB component)
• lifecycle callback interceptor methods for @PostConstruct and @PreDestroy callbacks of managed beans and EJB components and for @PrePassivate and @PostActivate methods of EJB stateful session beans.

An interceptor method may be defined by annotating the method, or using the EJB deployment descriptor. Interceptor methods may not be declared static or final.

An interceptor class or target class may have multiple interceptor methods. However, an interceptor class or target class may have no more than one interceptor method for a certain type of interception: AroundInvoke, AroundTimeout, PostConstruct, PreDestroy, PrePassivate or PostActivate.

Interceptor classes

An interceptor class is a class (distinct from the target class) whose methods are invoked in response to invocations and/or lifecycle events on the target class. Any number of interceptor classes may be associated with a target class.

An interceptor class must have a public constructor with no parameters.

Interceptor classes may be annotated @Interceptor, but this is not required when @Interceptors or the EJB deployment descriptor are used to bind the interceptor to its target classes.

Defining the interceptor classes of a target class

Interceptor classes of a target class or method of a target class may be defined in several ways:

• By annotating the target class or method of the target class with @Interceptors and specifying the interceptor class.
• If the target class is an EJB component, by using the EJB deployment descriptor.
• If the target class is a CDI bean, by annotating both the interceptor class and the target class with an interceptor binding.

Any interceptor class may be defined to apply to a target class at the class level. In the case of method interceptors, the interceptor applies to all methods of the target class. In the case of timeout method interceptors, the interceptor applies to all timeout methods of the target class.

@ExcludeClassInterceptors or the EJB deployment descriptor may be used to exclude the invocation of class level interceptors for a method of a target class.

A method interceptor may be defined to apply only to a specific method of the target class. Likewise, a timeout method interceptor may be defined to apply only to a specific timeout method of the target class. However, if an interceptor class that defines lifecycle callback interceptor methods is defined to apply to a target class at the method level, the lifecycle callback interceptor methods are not invoked.

Default Interceptors

Default interceptors may be defined to apply to a set of target classes using the EJB deployment descriptor. The default interceptors are invoked before any other interceptors for a target class. The EJB deployment descriptor may be used to specify alternative orderings.

@ExcludeDefaultInterceptors or the EJB deployment descriptor may be used to exclude the invocation of default interceptors for a target class or method of a target class.

Interceptor lifecycle

The lifecycle of an interceptor instance is the same as that of the target class instance with which it is associated. When the target instance is created, a corresponding interceptor instance is created for each associated interceptor class. These interceptor instances are destroyed when the target instance is destroyed.

Both the interceptor instance and the target instance are created before any @PostConstruct callbacks are invoked. Any @PreDestroy callbacks are invoked before the destruction of either the target instance or interceptor instance.

An interceptor instance may hold state. An interceptor instance may be the target of dependency injection. Dependency injection is performed when the interceptor instance is created, using the naming context of the associated target class. The @PostConstruct interceptor callback method is invoked after this dependency injection has taken place on both the interceptor instances and the target instance.

An interceptor class shares the enterprise naming context of its associated target class. Annotations and/or XML deployment descriptor elements for dependency injection or for direct JNDI lookup refer to this shared naming context.

Interceptors for lifecycle callbacks

A lifecycle callback interceptor method is a non-final, non-static method with return type void of the target class (or superclass) or of any interceptor class. A lifecycle callback interceptor method declared by the target class (or superclass) must have no parameters. A lifecycle callback interceptor method declared by an interceptor class must have a single parameter of type InvocationContext.

@PostConstruct
public void interceptPostConstruct(InvocationContext ctx) { ... }

A single lifecycle callback interceptor method may be used to interpose on multiple callback events.

@PostConstruct @PreDestroy
public void interceptLifecycle(InvocationContext ctx) { ... }

A class may not declare more than one lifecycle callback interceptor method for a particular lifecycle event.

Lifecycle callback interceptor method invocations occur within unspecified transaction and security contexts.

Lifecycle callback interceptor methods may throw runtime exceptions but not checked exceptions.

See Also:

AroundInvoke, AroundTimeout, Interceptors, InvocationContext