Debian Codegraph @

spec/src/main/doc/interceptors.asciidoc

raw
1 [[interceptors]]
2
3 == Interceptor bindings
4
5 Managed beans and EJB session and message-driven 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.
6
7 [[interceptor_bindings]]
8
9 === Interceptor binding types
10
11 This specification extends the Java Interceptors specification and allows interceptor bindings to be applied to CDI stereotypes.
12
13 [[stereotype_interceptor_bindings]]
14
15 ==== Interceptor bindings for stereotypes
16
17 Interceptor bindings may be applied to a stereotype by annotating the stereotype annotation:
18
19 [source, java]
20 ----
21 @Transactional
22 @Secure
23 @RequestScoped
24 @Stereotype
25 @Target(TYPE)
26 @Retention(RUNTIME)
27 public @interface Action {}
28 ----
29
30 An interceptor binding declared by a stereotype is inherited by any bean that declares that stereotype.
31
32 If a stereotype declares interceptor bindings, it must be defined as +@Target(TYPE)+.
33
34 [[declaring_interceptor]]
35
36 === Declaring the interceptor bindings of an interceptor
37
38 This specification extends the Java Interceptors specification and defines how the container must behave if a definition error is encountered.
39
40
41 [[binding_interceptor_to_bean]]
42
43 === Binding an interceptor to a bean
44
45 This specification extends the Java Interceptors specification and defines:
46
47 * additional restrictions about the type of bean to which an interceptor can be bound, and
48 * how the container must behave if a definition error is encountered, and
49 * how interceptors are bound using stereotypes.
50
51 Interceptor bindings may be used to associate interceptors with any managed bean that is not a decorator.
52
53 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.
54
55 The set of interceptor bindings for a producer method is not used to associate interceptors with the return value of the producer method.
56
57 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>>.
58
59 [[enabled_interceptors]]
60
61 === Interceptor enablement and ordering
62
63 This specification extends the Java Interceptors specification and defines:
64
65 * support for enabling interceptors only for a bean archive, as defined by Contexts and Dependency Injection 1.0, and
66 * the ability to override the interceptor order using the portable extension SPI, defined in <<atd>>.
67
68 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.
69
70 [source,xml]
71 ----
72 <beans xmlns="http://xmlns.jcp.org/xml/ns/javaee"
73 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
74 xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/beans_1_1.xsd"">
75 <interceptors>
76 <class>com.acme.myfwk.TransactionInterceptor</class>
77 <class>com.acme.myfwk.LoggingInterceptor</class>
78 </interceptors>
79 </beans>
80 ----
81
82 The order of the interceptor declarations determines the interceptor ordering. Interceptors which occur earlier in the list are called first.
83
84 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.
85
86 If the same class is listed twice under the +<interceptors>+ element, the container automatically detects the problem and treats it as a deployment problem.
87
88 Interceptors enabled using +@Priority+ are called before interceptors enabled using +beans.xml+.
89
90 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 <<atd>>.
91
92 [[interceptor_resolution]]
93
94 === Interceptor resolution
95
96 This specification extends the Java Interceptors specification and defines:
97
98 * the effect of applying +@Nonbinding+ to an interceptor binding member, and
99 * how the interceptor bindings of a custom implementation of the +Interceptor+ interface are determined.
100
101 If any interceptor binding has a member annotated [email protected]+, the member is ignored when performing interceptor resolution, and the method does not need to have the same annotation member value.
102
103 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, EJB timeout or business method.
104