JSR-318: Interceptors Specification TCK Coverage

Any number of interceptor classes may be associated with a target class.

Up to one interceptor method of each interceptor method type may be defined in the same class. More specifically, up to one around-invoke interceptor method, one around-timeout interceptor method, and one lifecycle callback interceptor method for each of the different lifecycle events may be defined in the same class. Only the interceptor methods of the interceptor class that are relevant for the given invocation context are invoked. For example, when a business method is invoked, around-invoke interceptor methods are invoked, but any around-construct, around-timeout, post-construct, or pre-destroy methods are ignored.

Except as noted below, when the target instance is created, a corresponding interceptor instance is created for each associated interceptor class.

With the exception of around-construct lifecycle callback interceptor methods, no interceptor methods are invoked until after dependency injection has been completed on both the interceptor instances an 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.

Around-invoke and around-timeout interceptor methods run in the same Java thread as the associated target method.

It is possible to carry state across multiple interceptor method invocations for a single method invocation or lifecycle callback event in the context data of the InvocationContext object. The InvocationContext object also provides information that enables interceptor methods to control the behavior of the interceptor invocation chain, including whether the next method in the chain is invoked and the values of its parameters and result.

The same InvocationContext instance is passed to each interceptor method for a given target class method or lifecycle event interception. This allows an interceptor to save information in the context data property of the InvocationContext that can be subsequently retrieved in other interceptors as a means to pass contextual data between interceptors. The contextual data is not sharable across separate target class method invocations or lifecycle callback events.

The getTarget method returns the associated target instance. For the AroundConstruct lifecycle callback interceptor method, getTarget returns null if called before the proceed method returns.

The getTimer method returns null for around-invoke methods and lifecycle callback interceptor methods.

The getMethod method returns the method of the target class for which the interceptor was invoked.

In a lifecycle callback interceptor for which there is no corresponding lifecycle callback method on the target class or in the AroundConstruct lifecycle callback interceptor method, getMethod returns null.

The getParameters method returns the parameters of the method or constructor invocation. If the setParameters method has been called, getParameters returns the values to which the parameters have been set.

For AroundConstruct lifecycle callback interceptor methods, the invocation of the last interceptor method in the chain causes the target instance to be created.

Interceptor methods must always call the InvocationContext.proceed method or no subsequent interceptor methods, target class method, or lifecycle callback methods will be invoked, or the target instance will not be created.

If a method is of type void, the invocation of the proceed method returns null.

For all other lifecycle callback interceptor methods, if there is no callback method defined on the target class, the invocation of proceed in the last interceptor method in the chain is a no-op, and null is returned.

Interceptor methods are allowed to throw runtime exceptions or any checked exceptions that the associated target method allows within its throws clause.

The invocation of the InvocationContext.proceed method will throw the same exception as any thrown by the associated target method unless an interceptor further down the Java call stack has caught it and thrown a different exception.

Interceptor methods that interpose on business method invocations are denoted by the AroundInvoke annotation.

Around-invoke methods may be defined on interceptor classes and/or the target class and/or superclasses of the target class or the interceptor classes. However, only one around-invoke method may be defined on a given class.

An around-invoke method can invoke any component or resource that the method it is intercepting can invoke.

The AroundConstruct annotation denotes lifecycle callback interceptor methods that interpose on invocation of the target instance’s constructor.

The PostConstruct annotation denotes lifecycle callback interceptor methods that are invoked after the target instance has been constructed and dependency injection on that instance has been completed, but before any business method or other event can be invoked on the target instance.

The PreDestroy annotation denotes lifecycle callback interceptor methods that interpose on the target instance’s removal.

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

Lifecycle callback interceptor methods are invoked in a transaction context determined by their target class and/or method.

AroundConstruct lifecycle callback interceptor methods may be defined on superclasses of interceptor classes. All other lifecycle callback interceptor methods may be defined on superclasses of the target class or of interceptor classes. However, a given class may not have more than one lifecycle callback interceptor method for the same lifecycle event. Any subset or combination of lifecycle callback annotations may otherwise be specified on a target class or interceptor class.

If a lifecycle callback interceptor method returns a value, it is ignored by the container.

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

A lifecycle callback interceptor method (other than a method on the target class or its superclasses) may catch an exception thrown by another lifecycle callback interceptor method in the invocation chain, and clean up before returning.

The PreDestroy callbacks are not invoked when the target instance and the interceptors are discarded as a result of such exceptions: the lifecycle callback interceptor methods in the chain should perform any necessary clean-up operations as the interceptor chain unwinds.

An around-timeout method can invoke any component or resource that its corresponding timeout method can invoke.

The InvocationContext.getTimer method allows an around-timeout method to retrieve the timer object associated with the timeout.

Method-level interceptors are interceptor classes associated with a specific business or timeout method of the target class.

Constructor-level interceptors are interceptor classes associated with a constructor of the target class.

Only the interceptor methods of the interceptor class that are relevant for the context in which the interceptor is bound are invoked. For example, if the interceptor is bound only to a business method, any AroundConstruct, AroundTimeout, PostConstruct, or PreDestroy methods on the interceptor are not called.

The same interceptor may be applied to more than one business or timeout method of the target class.

The applicability of a method-level interceptor to more than one method of an associated target class does not affect the relationship between the interceptor instance and the target class - only a single instance of the interceptor class is created per target class instance.

An interceptor binding type is a Java annotation defined as Retention(RUNTIME). Typically an interceptor binding is defined as Target({TYPE, METHOD, CONSTRUCTOR}) or any subset of valid target types.

An interceptor binding type may be declared by specifying the InterceptorBinding meta-annotation.

An interceptor binding type may declare other interceptor bindings.

Interceptor bindings are transitive - an interceptor binding declared by an interceptor binding type is inherited by all components and other interceptor binding types that declare that interceptor binding type.

An extension specification may define other sources of interceptor bindings, such as via a CDI stereotype.

The interceptor bindings of an interceptor are specified by annotating the interceptor class with the binding types and the Interceptor annotation and are called the set of interceptor bindings for the interceptor.

An interceptor class may declare multiple interceptor bindings.

Multiple interceptors may declare the same interceptor bindings.

The set of interceptor bindings for a method or constructor are those declared at class level combined with those declared at method or constructor level.

An extension specification may define additional rules for combining interceptor bindings, such as interceptors defined via a CDI stereotype.

For a lifecycle callback, the interceptor bindings include the interceptor bindings declared or inherited by the component at the class level, including, recursively, interceptor bindings declared as meta-annotations of other interceptor bindings.

An interceptor class may specify multiple interceptor bindings.

Interceptor binding types may have annotation members.

If the set of interceptor bindings of a component class or interceptor, including bindings inherited from stereotypes and other interceptor bindings, has two instances of a certain interceptor binding type and the instances have different values of some annotation member, the container automatically detects the problem and treats it as a definition error.

The Interceptors annotation can be used to denote interceptor classes and associate one or more interceptor classes with a target class, and/or one or more of its methods, and/or a constructor of the target class.

Method-level around-invoke and around-timeout interceptors can be defined by applying the Interceptors annotation to the method for which the interceptors are to be invoked.

Constructor-level interceptors can be defined by applying the Interceptors annotation to the constructor for which the interceptors are to be invoked.

Interceptors declared using the Interceptors annotation are enabled by that annotation. Using the Interceptors annotation to associate interceptor classes with a target class or a method or constructor of a target class enables them for that target class, method, or constructor. The order in which the interceptor classes are specified in the Interceptors annotation controls interceptor ordering (see Section 5.2).

If an interceptor method is overridden by another method (regardless whether that method is itself an interceptor method), it will not be invoked.

The ExcludeClassInterceptors annotation can be used to exclude the invocation of the class-level interceptors defined by means of the Interceptors annotation.