javax.interceptor.package.html Maven / Gradle / Ivy
Show all versions of jakarta.interceptor-api Show documentation
Contains annotations and interfaces for defining interceptor methods and interceptor
classes, and for binding interceptor classes to target classes.
Interceptor methods
An interceptor method is a method of an interceptor class or of a target class
that is invoked to interpose on the invocation of a method of the target class,
a constructor of the target class, a lifecycle event of the target class, or a
timeout method of the target class.
An interceptor method for a target class may be declared in the target class, in
an interceptor class associated with the target class, or in a superclass of
the target class or interceptor class.
An {@link javax.interceptor.AroundConstruct} interceptor method may
be defined only in an interceptor class or superclass of an interceptor class.
The Jakarta Interceptors specification defines the interceptor method types listed
below. Extension specifications may define additional interceptor method types.
- {@link javax.interceptor.AroundInvoke} interceptor methods,
which interpose on business methods of the target class.
- {@link javax.interceptor.AroundTimeout} interceptor methods,
which interpose on the invocation of timeout methods, in response to timer events.
- {@link javax.annotation.PostConstruct} interceptor methods, which are invoked
after dependency injection has been completed on the target instance.
- {@link javax.annotation.PreDestroy} interceptor methods, which are invoked
before the target instance and all interceptor instances associated with it are
destroyed.
- {@link javax.interceptor.AroundConstruct} interceptor methods, which interpose
on the invocation of the constructor of the target instance.
{@link javax.annotation.PostConstruct}, {@link
javax.annotation.PreDestroy}, and {@link
javax.interceptor.AroundConstruct} interceptor methods are
collectively referred to as lifecycle callback interceptor methods.
An interceptor method may be defined using annotations or,
optionally, by means of a deployment descriptor. Interceptor methods
may not be declared abstract, 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 of a
given interceptor method type: {@link javax.interceptor.AroundInvoke},
{@link javax.interceptor.AroundTimeout}, {@link javax.annotation.PostConstruct},
{@link javax.annotation.PreDestroy}, {@link javax.interceptor.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 annotation. The set of
interceptor bindings for the interceptor are specified by annotating the interceptor
class with the binding types and the {@link javax.interceptor.Interceptor}
annotation.
- By using the {@link javax.interceptor.Interceptors Interceptors} annotation
to specify and associate one or more interceptor classes
with a target class or method or constructor of a target class.
- 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.
The {@link javax.interceptor.ExcludeClassInterceptors} annotation or, if supported,
a deployment descriptor may be used to exclude the invocation of class level
interceptors defined by the {@link javax.interceptor.Interceptors Interceptors} annotation
for a method or constructor 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.
The {@link javax.interceptor.ExcludeDefaultInterceptors} annotation may be used to
exclude the invocation of default interceptors for a target class or method or constructor 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 as noted below for {@link javax.interceptor.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 Naming and Directory Interface 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
of {@link javax.interceptor.AroundConstruct} lifecycle callback interceptors,
no interceptor methods are invoked until after dependency injection has been
completed on both the interceptor instances and the target instance.
{@link javax.annotation.PostConstruct} interceptor methods, if any, are invoked after
dependency injection has taken place on both the interceptor instances and the target
instance.
{@link javax.annotation.PreDestroy} interceptor methods, if any, are
invoked before the target instance and all interceptor instances associated with it are
destroyed.
When a {@link javax.interceptor.AroundConstruct} lifecycle callback interceptor
is used, the following rules apply:
- The {@link javax.interceptor.AroundConstruct} lifecycle callback is invoked
after 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 {@link javax.interceptor.AroundConstruct}
lifecycle callback is not supported.
- The target instance is created and its constructor injection is performed, if applicable,
after the last interceptor method in the {@link javax.interceptor.AroundConstruct}
interceptor chain invokes the {@link javax.interceptor.InvocationContext#proceed InvocationContext.proceed()} method.
If the {@link javax.interceptor.InvocationContext#proceed InvocationContext.proceed()} method is not invoked by an
interceptor method, the target instance will not be created.
- The {@link javax.interceptor.AroundConstruct} interceptor method can access
the constructed instance using the {@link javax.interceptor.InvocationContext#getTarget InvocationContext.getTarget()}
method after the {@link javax.interceptor.InvocationContext#proceed InvocationContext.proceed()} completes.
- Dependency injection on the target instance is not completed until after invocations
of all interceptor methods in the {@link javax.interceptor.AroundConstruct} interceptor chain complete successfully.
- The {@link javax.annotation.PostConstruct} lifecycle callback chain for the
target instance, if any, will be invoked after dependency injection has been completed
on the target instance.
- An {@link javax.interceptor.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 {@link javax.interceptor.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, except for {@link javax.interceptor.AroundConstruct} methods, which may
throw may throw any exceptions that are allowed by the throws clause of the constructor
on which they are interposing.
@see javax.interceptor.AroundConstruct
@see javax.interceptor.AroundInvoke
@see javax.interceptor.AroundTimeout
@see javax.interceptor.Interceptors
@see javax.interceptor.InvocationContext