Debian Codegraph @

spec/src/main/doc/decorators.asciidoc

raw
1 [[decorators]]
2
3 == Decorators
4
5 A _decorator_ implements one or more bean types and intercepts business method invocations of beans which implement those bean types. These bean types are called _decorated types_.
6
7 Decorators are superficially similar to interceptors, but because they directly implement operations with business semantics, they are able to implement business logic and, conversely, unable to implement the cross-cutting concerns for which interceptors are optimized.
8
9 Decorators may be associated with any managed bean that is not itself an interceptor or decorator, with any EJB session bean or with any built-in bean other than the built-in bean with type +BeanManager+ and qualifier +@Default+. Decorators are not applied to the return value of a producer method or the current value of a producer field. A decorator instance is a dependent object of the object it decorates.
10
11 [[decorator_bean]]
12
13 === Decorator beans
14
15 A decorator is a managed bean. The set of decorated types of a decorator includes all bean types of the managed bean which are Java interfaces, except for +java.io.Serializable+. The decorator bean class and its superclasses are not decorated types of the decorator. The decorator class may be abstract.
16
17 If the set of decorated types of a decorator is empty, the container automatically detects the problem and treats it as a definition error.
18
19 Decorators of a session bean must comply with the bean provider programming restrictions defined by the EJB specification. Decorators of a stateful session bean must comply with the rules for instance passivation and conversational state defined by the EJB specification.
20
21 [[decorator_annotation]]
22
23 ==== Declaring a decorator
24
25 A decorator is declared by annotating the bean class with the [email protected]+ stereotype.
26
27 [source, java]
28 ----
29 @Decorator @Priority(APPLICATION)
30 class TimestampLogger implements Logger { ... }
31 ----
32
33 [[delegate_attribute]]
34
35 ==== Decorator delegate injection points
36
37 All decorators have a _delegate injection point_. A delegate injection point is an injection point of the bean class. The type and qualifiers of the injection point are called the _delegate type_ and _delegate qualifiers_. The decorator applies to beans that are assignable to the delegate injection point.
38
39 The delegate injection point must be declared by annotating the injection point with the annotation [email protected]+:
40
41 [source, java]
42 ----
43 @Decorator @Priority(APPLICATION)
44 class TimestampLogger implements Logger {
45 @Inject @Delegate @Any Logger logger;
46 ...
47 }
48 ----
49
50 [source, java]
51 ----
52 @Decorator @Priority(APPLICATION)
53 class TimestampLogger implements Logger {
54 private Logger logger;
55
56 @Inject
57 public TimestampLogger(@Delegate @Debug Logger logger) {
58 this.logger=logger;
59 }
60 ...
61 }
62 ----
63
64 A decorator must have exactly one delegate injection point. If a decorator has more than one delegate injection point, or does not have a delegate injection point, the container automatically detects the problem and treats it as a definition error.
65
66 The delegate injection point must be an injected field, initializer method parameter or bean constructor method parameter. If an injection point that is not an injected field, initializer method parameter or bean constructor method parameter is annotated +@Delegate+, the container automatically detects the problem and treats it as a definition error.
67
68 If a bean class that is not a decorator has an injection point annotated +@Delegate+, the container automatically detects the problem and treats it as a definition error.
69
70 The container must inject a _delegate_ object to the delegate injection point. The delegate object implements the delegate type and delegates method invocations to remaining uninvoked decorators and eventually to the bean. When the container calls a decorator during business method interception, the decorator may invoke any method of the delegate object.
71
72 [source, java]
73 ----
74 @Decorator @Priority(APPLICATION)
75 class TimestampLogger implements Logger {
76 @Inject @Delegate @Any Logger logger;
77
78 void log(String message) {
79 logger.log( timestamp() + ": " + message );
80 }
81 ...
82 }
83 ----
84
85 If a decorator invokes the delegate object at any other time, the invoked method throws an +IllegalStateException+.
86
87 [[decorated_types]]
88
89 ==== Decorated types of a decorator
90
91 The delegate type of a decorator must implement or extend every decorated type (with exactly the same type parameters). If the delegate type does not implement or extend a decorated type of the decorator (or specifies different type parameters), the container automatically detects the problem and treats it as a definition error.
92
93 A decorator is not required to implement the delegate type.
94
95 A decorator may be an abstract Java class, and is not required to implement every method of every decorated type. Whenever the decorator does not implement a method of the decorated type, the container will provide an implicit implementation that calls the method on the delegate. If a decorator has abstract methods that are not declared by a decorated type, the container automatically detects the problem and treats it as a definition error.
96
97 The decorator intercepts every method which is declared by a decorated type of the decorator and is implemented by the bean class of the decorator.
98
99 [[enabled_decorators]]
100
101 === Decorator enablement and ordering
102
103 This specification defines two methods of enabling and ordering decorators. From Contexts and Dependency Injection 1.1 onwards the +@Priority+ annotation allows a decorator to be enabled and ordered for an entire application. Contexts and Dependency Injection 1.0 allowed only for a decorator to be enabled and ordered for a bean archive.
104
105 Decorators are called after interceptors. Decorators enabled using +@Priority+ are called before decorators enabled using +beans.xml+.
106
107 A decorator is said to be *enabled* if it is enabled in at least one bean archive or is listed in the final list of decorators for the application, as defined in <<atd>>.
108
109 [[enabled_decorators_priority]]
110
111 ==== Decorator enablement and ordering for an application
112
113
114 A decorator may be enabled for the entire application by applying the +@Priority+ annotation, along with a priority value, on the decorator class. Decorators with the smaller priority values are called first. The order of more than one decorator with the same priority is undefined.
115
116 [source,java]
117 ----
118 @Decorator @Priority(APPLICATION)
119 class TimestampLogger implements Logger {
120
121 ...
122 }
123 ----
124
125 The priority value ranges defined in the Java Interceptors specification section 5.5 should be used when defining decorator priorities.
126
127 [[enabled_decorators_bean_archive]]
128
129 ==== Decorator enablement and ordering for a bean archive
130
131 A decorator may be explicitly enabled by listing its bean class under the +<decorators>+ element of the +beans.xml+ file of the bean archive.
132
133 [source,xml]
134 ----
135 <beans xmlns="http://xmlns.jcp.org/xml/ns/javaee"
136 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
137 xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/beans_1_1.xsd">
138 <decorators>
139 <class>com.acme.myfwk.TimestampLogger</class>
140 <class>com.acme.myfwk.IdentityLogger</class>
141 </decorators>
142 </beans>
143 ----
144
145 The order of the decorator declarations determines the decorator ordering. Decorators which occur earlier in the list are called first.
146
147 Each child +<class>+ element must specify the name of a decorator bean class. If there is no class with the specified name, or if the class with the specified name is not a decorator bean class, the container automatically detects the problem and treats it as a deployment problem.
148
149 If the same class is listed twice under the +<decorators>+ element, the container automatically detects the problem and treats it as a deployment problem.
150
151
152 [[decorator_resolution]]
153
154 === Decorator resolution
155
156 The process of matching decorators to a certain bean is called _decorator resolution_. A decorator is bound to a bean if:
157
158 * The bean is assignable to the delegate injection point according to the rules defined in <<typesafe_resolution>> (using <<delegate_assignable_parameters>>).
159 * The decorator is enabled in the bean archive containing the bean.
160
161
162 If a decorator matches a managed bean, the managed bean class must be a proxyable bean type, as defined in <<unproxyable>>.
163
164 For a custom implementation of the +Decorator+ interface defined in <<decorator>>, the container calls +getDelegateType()+, +getDelegateQualifiers()+ and +getDecoratedTypes()+ to determine the delegate type and qualifiers and decorated types of the decorator.
165
166 [[delegate_assignable_parameters]]
167
168 ==== Assignability of raw and parameterized types for delegate injection points
169
170 Decorator delegate injection points have a special set of rules for determining assignability of raw and parameterized types, as an exception to <<assignable_parameters>>.
171
172 A raw bean type is considered assignable to a parameterized delegate type if the raw types are identical and all type parameters of the delegate type are either unbounded type variables or +java.lang.Object+.
173
174 A parameterized bean type is considered assignable to a parameterized delegate type if they have identical raw type and for each parameter:
175
176 * the delegate type parameter and the bean type parameter are actual types with identical raw type, and, if the type is parameterized, the bean type parameter is assignable to the delegate type parameter according to these rules, or
177 * the delegate type parameter is a wildcard, the bean type parameter is an actual type and the actual type is assignable to the upper bound, if any, of the wildcard and assignable from the lower bound, if any, of the wildcard, or
178 * the delegate type parameter is a wildcard, the bean type parameter is a type variable and the upper bound of the type variable is assignable to the upper bound, if any, of the wildcard and assignable from the lower bound, if any, of the wildcard, or
179 * the delegate type parameter and the bean type parameter are both type variables and the upper bound of the bean type parameter is assignable to the upper bound, if any, of the delegate type parameter, or
180 * the delegate type parameter is a type variable, the bean type parameter is an actual type, and the actual type is assignable to the upper bound, if any, of the type variable.
181
182
183 [[decorator_invocation]]
184
185 === Decorator invocation
186
187 Whenever a business method is invoked on an instance of a bean with decorators, the container intercepts the business method invocation and, after processing all interceptors of the method, invokes decorators of the bean.
188
189 The container searches for the first decorator of the instance that implements the method that is being invoked as a business method. If no such decorator exists, the container invokes the business method of the intercepted instance. Otherwise, the container calls the method of the decorator.
190
191 When any decorator is invoked by the container, it may in turn invoke a method of the delegate. The container intercepts the delegate invocation and searches for the first decorator of the instance such that:
192
193 * the decorator occurs after the decorator invoking the delegate, and
194 * the decorator implements the method that is being invoked upon the delegate.
195
196
197 If no such decorator exists, the container invokes the business method of the intercepted instance. Otherwise, the container calls the method of the decorator.
198