Overview of Interceptors - The Java EE 6 Tutorial (original) (raw)

Interceptors are used in conjunction with Java EE managed classes to allow developers to invoke interceptor methods on an associated target class, in conjunction with method invocations or lifecycle events. Common uses of interceptors are logging, auditing, and profiling.

The Interceptors 1.1 specification is part of the final release of JSR 318, Enterprise JavaBeans 3.1, available from http://jcp.org/en/jsr/detail?id=318.

An interceptor can be defined within a target class as an interceptor method, or in an associated class called an interceptor class. Interceptor classes contain methods that are invoked in conjunction with the methods or lifecycle events of the target class.

Interceptor classes and methods are defined using metadata annotations, or in the deployment descriptor of the application containing the interceptors and target classes.

Note - Applications that use the deployment descriptor to define interceptors are not portable across Java EE servers.

Interceptor methods within the target class or in an interceptor class are annotated with one of the metadata annotations defined in Table 50-1.

Table 50-1 Interceptor Metadata Annotations

Interceptor Metadata Annotation	Description
javax.interceptor.AroundInvoke	Designates the method as an interceptor method.
javax.interceptor.AroundTimeout	Designates the method as a timeout interceptor, for interposing on timeout methods for enterprise bean timers.
javax.annotation.PostConstruct	Designates the method as an interceptor method for post-construct lifecycle events.
javax.annotation.PreDestroy	Designates the method as an interceptor method for pre-destroy lifecycle events.

Interceptor Classes

Interceptor classes may be designated with the optional javax.interceptor.Interceptor annotation, but interceptor classes aren’t required to be so annotated. An interceptor class must have a public, no-argument constructor.

The target class can have any number of interceptor classes associated with it. The order in which the interceptor classes are invoked is determined by the order in which the interceptor classes are defined in the javax.interceptor.Interceptors annotation. However, this order can be overridden in the deployment descriptor.

Interceptor classes may be targets of dependency injection. Dependency injection occurs when the interceptor class instance is created, using the naming context of the associated target class, and before any @PostConstruct callbacks are invoked.

Interceptor Lifecycle

Interceptor classes have the same lifecycle as their associated target class. When a target class instance is created, an interceptor class instance is also created for each declared interceptor class in the target class. That is, if the target class declares multiple interceptor classes, an instance of each class is created when the target class instance is created. The target class instance and all interceptor class instances are fully instantiated before any @PostConstruct callbacks are invoked, and any @PreDestroycallbacks are invoked before the target class and interceptor class instances are destroyed.

Interceptors and CDI

Contexts and Dependency Injection for the Java EE Platform (CDI) builds on the basic functionality of Java EE interceptors. For information on CDI interceptors, including a discussion of interceptor binding types, see Using Interceptors in CDI Applications.