[[interceptors]]

== Interceptor bindings

Managed beans support interception.
_Interceptors_ are used to separate cross-cutting concerns from business logic.
The Java Interceptors specification defines the basic programming model and semantics, and how to associate interceptors with target classes.
This specification defines various extensions to the Java Interceptors specification, including how to override the interceptor order defined by the `@Priority` annotation.

[[interceptor_bindings]]

=== Interceptor binding types

This specification extends the Java Interceptors specification and allows interceptor bindings to be applied to CDI stereotypes.

[[stereotype_interceptor_bindings]]

==== Interceptor bindings for stereotypes

Interceptor bindings may be applied to a stereotype by annotating the stereotype annotation:

[source, java]
----
@Transactional
@Secure
@RequestScoped
@Stereotype
@Target(TYPE)
@Retention(RUNTIME)
public @interface Action {}
----

An interceptor binding declared by a stereotype is inherited by any bean that declares that stereotype.

If a stereotype declares interceptor bindings, it must be defined as `@Target(TYPE)`.

[[declaring_interceptor]]

=== Declaring the interceptor bindings of an interceptor

This specification extends the Java Interceptors specification and defines how the container must behave if a definition error is encountered.


[[binding_interceptor_to_bean]]

=== Binding an interceptor to a bean

This specification extends the Java Interceptors specification and defines:

* additional restrictions about the type of bean to which an interceptor can be bound, and
* how the container must behave if a definition error is encountered, and
* how interceptors are bound using stereotypes.

Interceptor bindings may be used to associate interceptors with any managed bean that is not a decorator.

The set of interceptor bindings for a method declared at class level includes those declared on stereotypes.
An interceptor binding declared on a bean class replaces an interceptor binding of the same type declared by a stereotype that is applied to the bean class.

The set of interceptor bindings for a producer method is not used to associate interceptors with the return value of the producer method.

Since CDI 2.0 it is possible to apply interceptors programmatically to the return value of a producer method, with the `InterceptionFactory` interface as defined in <<interception_factory>>.

If a managed bean has a class-level or method-level interceptor binding, the managed bean must be a proxyable bean type, as defined in <<unproxyable>>.

[[enabled_interceptors]]

=== Interceptor enablement and ordering

This specification extends the Java Interceptors specification and defines:

* support for enabling interceptors only for a bean archive, as defined by Contexts and Dependency Injection 1.0, and
* the ability to override the interceptor order using the portable extension SPI, defined in <<after_type_discovery>>.

An interceptor may be explicitly enabled for a bean archive by listing its class under the `<interceptors>` element of the `beans.xml` file of the bean archive.

[source,xml]
----
<beans xmlns="http://xmlns.jcp.org/xml/ns/javaee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/beans_2_0.xsd" bean-discovery-mode="all" version="2.0">
   <interceptors>
      <class>com.acme.myfwk.TransactionInterceptor</class>
      <class>com.acme.myfwk.LoggingInterceptor</class>
   </interceptors>
</beans>
----

The order of the interceptor declarations determines the interceptor ordering. Interceptors which occur earlier in the list are called first.

Each child `<class>` element must specify the name of an interceptor class.
If there is no class with the specified name, or if the class with the specified name is not an interceptor class, the container automatically detects the problem and treats it as a deployment problem.

If the same class is listed twice under the `<interceptors>` element, the container automatically detects the problem and treats it as a deployment problem.

Interceptors enabled using `@Priority` are called before interceptors enabled using `beans.xml`.

An interceptor is said to be *enabled* if it is enabled in at least one bean archive or is listed in the final list of interceptors for the application, as defined in <<after_type_discovery>>.

If an interceptor declares any scope other than `@Dependent`, the container automatically detects the problem and treats it as a definition error.

If an interceptor is enabled for the application and for the bean archive, then the enablement from the bean archive is ignored by the container.  The interceptor will only be executed once based on the `@Priority` annotation's invocation chain.

[[interceptor_resolution]]

=== Interceptor resolution

This specification extends the Java Interceptors specification and defines:

* the effect of applying `@Nonbinding` to an interceptor binding member, and
* how the interceptor bindings of a custom implementation of the `Interceptor` interface are determined.

If any interceptor binding has a member annotated `@javax.enterprise.util.Nonbinding`, the member is ignored when performing interceptor resolution, and the method does not need to have the same annotation member value.

For a custom implementation of the `Interceptor` interface defined in <<interceptor>>, the container calls `getInterceptorBindings()` to determine the interceptor bindings of the interceptor and `intercepts()` to determine if the interceptor intercepts a given kind of lifecycle callback or business method.

A custom implementation of the `Interceptor` interface may implement the <<prioritized, `Prioritized` interface>> to be enabled for the entire application with a priority value.


