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

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

Class Summary

Class	Description
Interceptor.Priority	Priorities that define the order in which interceptors are invoked.

Annotation Types Summary

Annotation Type	Description
AroundConstruct	Designates an interceptor method that receives a callback when the target class constructor is invoked.
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 lifecycle callback, business, or timeout method of a target class, or a constructor of a target class.
ExcludeDefaultInterceptors	Used to exclude default interceptors for a target class or a lifecycle callback, business, or timeout method of a target class, or a constructor 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, a method or a constructor 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. AroundConstruct interceptor may be defined only on an interceptor class.

There are three kinds of interceptor method:

• around-invoke interceptor methods for business methods of the target class
• around-timeout interceptor methods for timeout methods of the target class
• lifecycle callback interceptor methods, such as AroundConstruct, PostConstruct and PreDestroy

An interceptor method may be defined using annotations or, optionally, by means of a 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, AroundConstruct.

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 methods and interceptor classes may be defined for a class by means of metadata annotations or, optionally, by means of a deployment descriptor.

Associating an interceptor class with the target class

An interceptor class may be associated with the target class or a method of the target class in several ways:

• By annotating both the interceptor class and the target class with an interceptor binding. The set of interceptor bindings for the interceptor are specified by annotating the interceptor class with the binding types and the Interceptor annotation.
• By using the Interceptors annotation to denote interceptor classes and associate one or more interceptor classes with a target class and/or one or more of its methods.
• If a deployment descriptor is supported, it can be used to associate interceptor classes with the target class and/or methods of the target class and specify the order of interceptor invocation or override metadata specified by annotations.

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

ExcludeClassInterceptors annotation or, if supported, a deployment descriptor may be used to exclude the invocation of class level interceptors for a method of a target class.

An around-invoke interceptor may be defined to apply only to a specific method of the target class. Likewise, an around-timeout 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 are interceptors that apply to a set of target classes. If a deployment descriptor is supported, it may be used to define default interceptors and their relative ordering.

ExcludeDefaultInterceptors annotation 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. Except for the AroundConstruct lifecycle callback interceptors, 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 fails to be created or when it is removed.

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.

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. With the exception of AroundConstruct lifecycle callback interceptors, all interceptor methods, including PostConstruct interceptor callback method are invoked after this dependency injection has taken place on both the interceptor instances and the target instance.

PreDestroy interceptor callback method, if any, is invoked before the target instance and all interceptor instances associated with it are destroyed.

When a AroundConstruct lifecycle callback interceptor is used, the following rules apply:

• The AroundConstruct lifecycle callback is invoked after the dependency injection has been completed on instances of all interceptor classes associated with the target class. Injection of the target component into interceptor instances that are invoked during the AroundConstruct lifecycle callback is not supported.
• The target instance is created and its constructor injection is performed, if applicable, when the last interceptor method in the AroundConstruct interceptor chain invokes the InvocationContext.proceed() method. If the InvocationContext.proceed() method is not invoked by an interceptor method, the target instance will not be created.
• The AroundConstruct interceptor method can access the constructed instance using the InvocationContext.getTarget() method after the InvocationContext.proceed() completes.
• Dependency injection on the target instance is not completed until after invocation of all interceptor methods in the AroundConstruct interceptor chain complete successfully.
• The PostConstruct lifecycle callback chain for the target instance, if any, will be invoked after the dependency injection has been completed on the target instance.
• An AroundConstruct lifecycle callback interceptor method should exercise caution when invoking methods of the target instance since its dependency injection may not have been completed.

Interceptors for lifecycle callbacks

A lifecycle callback interceptor method is a non-final, non-static method. 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 methods are invoked in an unspecified security context. Lifecycle callback interceptor methods are invoked in a transaction context determined by their target class and/or method. The transaction context may be also changed by transactional interceptors in the invocation chain.

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

See Also:

AroundConstruct, AroundInvoke, AroundTimeout, Interceptors, InvocationContext