Debian Codegraph @

spec/src/main/doc/inheritance.asciidoc

raw
1 [[inheritance]]
2
3 == Inheritance and specialization
4
5 A bean may inherit type-level metadata and members from its superclasses.
6
7 Inheritance of type-level metadata by beans from their superclasses is controlled via use of the Java +@Inherited+ meta-annotation. Type-level metadata is never inherited from interfaces implemented by a bean.
8
9 Member-level metadata is not inherited. However, injected fields, initializer methods, lifecycle callback methods and non-static observer methods are inherited by beans from their superclasses.
10
11 The implementation of a bean may be extended by the implementation of a second bean. This specification recognizes two distinct scenarios in which this situation occurs:
12
13 * The second bean _specializes_ the first bean in certain deployment scenarios. In these deployments, the second bean completely replaces the first, fulfilling the same role in the system.
14 * The second bean is simply reusing the Java implementation, and otherwise bears no relation to the first bean. The first bean may not even have been designed for use as a contextual object.
15
16
17 The two cases are quite dissimilar.
18
19 By default, Java implementation reuse is assumed. In this case, the two beans have different roles in the system, and may both be available in a particular deployment.
20
21 The bean developer may explicitly specify that the second bean specializes the first. Then the second bean inherits, and may not override, the qualifiers and bean name of the first bean. The second bean is able to serve the same role in the system as the first. In a particular deployment, only one of the two beans may fulfill that role.
22
23 [[type_level_inheritance]]
24
25 === Inheritance of type-level metadata
26
27 Suppose a class X is extended directly or indirectly by the bean class of a managed bean or session bean Y.
28
29 * If X is annotated with a qualifier type, stereotype or interceptor binding type Z then Y inherits the annotation if and only if Z declares the +@Inherited+ meta-annotation and neither Y nor any intermediate class that is a subclass of X and a superclass of Y declares an annotation of type Z.
30 (This behavior is defined by the Java Language Specification.)
31 * If X is annotated with a scope type Z then Y inherits the annotation if and only if Z declares the +@Inherited+ meta-annotation and neither Y nor any intermediate class that is a subclass of X and a superclass of Y declares a scope type.
32 (This behavior is different to what is defined in the Java Language Specification.)
33
34
35 A scope type explicitly declared by X and inherited by Y from X takes precedence over default scopes of stereotypes declared or inherited by Y.
36
37 For annotations defined by the application or third-party extensions, it is recommended that:
38
39 * scope types should be declared +@Inherited+,
40 * qualifier types should not be declared +@Inherited+,
41 * interceptor binding types should be declared +@Inherited+, and
42 * stereotypes may be declared +@Inherited+, depending upon the semantics of the stereotype.
43
44
45 All scope types, qualifier types, and interceptor binding types defined by this specification adhere to these recommendations.
46
47 The stereotypes defined by this specification are not declared +@Inherited+.
48
49 However, in special circumstances, these recommendations may be ignored.
50
51 Note that the +@Named+ annotation is not declared +@Inherited+ and bean names are not inherited unless specialization is used.
52
53 [[member_level_inheritance]]
54
55 === Inheritance of member-level metadata
56
57 Suppose a class X is extended directly or indirectly by the bean class of a managed bean or session bean Y.
58
59 * If X declares an injected field +x+ then Y inherits +x+.
60 (This behavior is defined by the Common Annotations for the Java Platform specification.)
61 * If X declares an initializer, non-static observer, +@PostConstruct+ or +@PreDestroy+ method +x()+ then Y inherits +x()+ if and only if neither Y nor any intermediate class that is a subclass of X and a superclass of Y overrides the method +x()+.
62 (This behavior is defined by the Common Annotations for the Java Platform specification.)
63 * If X declares a non-static method +x()+ annotated with an interceptor binding type Z then Y inherits the binding if and only if neither Y nor any intermediate class that is a subclass of X and a superclass of Y overrides the method +x()+.
64 (This behavior is defined by the Common Annotations for the Java Platform specification.)
65 * If X declares a non-static producer or disposer method +x()+ then Y does not inherit this method.
66 (This behavior is different to what is defined in the Common Annotations for the Java Platform specification.)
67 * If X declares a non-static producer field +x+ then Y does not inherit this field.
68 (This behavior is different to what is defined in the Common Annotations for the Java Platform specification.)
69
70
71 If X is a generic type, and an injection point or observer method declared by X is inherited by Y, and the declared type of the injection point or event parameter contains type variables declared by X, the type of the injection point or event parameter inherited in Y is the declared type, after substitution of actual type arguments declared by Y or any intermediate class that is a subclass of X and a superclass of Y.
72
73 For example, the bean +DaoClient+ has an injection point of type +Dao<T>+.
74
75 [source, java]
76 ----
77 public class DaoClient<T> {
78
79 @Inject Dao<T> dao;
80 ...
81
82 }
83 ----
84
85 This injection point is inherited by +UserDaoClient+, but the type of the inherited injection point is +Dao<User>+.
86
87 [source, java]
88 ----
89 public class UserDaoClient
90 extends DaoClient<User> { ... }
91 ----
92
93 [[specialization]]
94
95 === Specialization
96
97 If two beans both support a certain bean type, and share at least one qualifier, then they are both eligible for injection to any injection point with that declared type and qualifier.
98
99 Consider the following beans:
100
101 [source, java]
102 ----
103 @Default @Asynchronous
104 public class AsynchronousService implements Service {
105 ...
106 }
107 ----
108
109 [source, java]
110 ----
111 @Alternative
112 public class MockAsynchronousService extends AsynchronousService {
113 ...
114 }
115 ----
116
117 Suppose that the +MockAsynchronousService+ alternative is selected, as defined in <<selection>>:
118
119 [source, java]
120 ----
121 @Alternative @Priority(APPLICATION+100)
122 public class MockAsynchronousService extends AsynchronousService {
123 ...
124 }
125 ----
126
127 Then, according to the rules of <<unsatisfied_and_ambig_dependencies>>, the following ambiguous dependency is resolvable, and so the attribute will receive an instance of +MockAsynchronousService+:
128
129 [source, java]
130 ----
131 @Inject Service service;
132 ----
133
134 However, the following attribute will receive an instance of +AsynchronousService+, even though +MockAsynchronousService+ is a selected alternative, because +MockAsynchronousService+ does not have the qualifier +@Asynchronous+:
135
136 [source, java]
137 ----
138 @Inject @Asynchronous Service service;
139 ----
140
141 This is a useful behavior in some circumstances, however, it is not always what is intended by the developer.
142
143 The only way one bean can completely override a second bean at all injection points is if it implements all the bean types and declares all the qualifiers of the second bean. However, if the second bean declares a producer method or observer method, then even this is not enough to ensure that the second bean is never called!
144
145 To help prevent developer error, the first bean may:
146
147 * directly extend the bean class of the second bean, or
148 * directly override the producer method, in the case that the second bean is a producer method, and then
149
150
151 explicitly declare that it _specializes_ the second bean.
152
153 [source, java]
154 ----
155 @Alternative @Specializes
156 public class MockAsynchronousService extends AsynchronousService {
157 ...
158 }
159 ----
160
161 When an enabled bean, as defined in <<enablement>>, specializes a second bean, we can be certain that the second bean is never instantiated or called by the container. Even if the second bean defines a producer or observer method, the method will never be called.
162
163 [[direct_and_indirect_specialization]]
164
165 ==== Direct and indirect specialization
166
167 The annotation [email protected]+ is used to indicate that one bean _directly specializes_ another bean, as defined in <<specialize_managed_bean>>, <<specialize_session_bean>> and <<specialize_producer_method>>.
168
169 Formally, a bean X is said to _specialize_ another bean Y if either:
170
171 * X directly specializes Y, or
172 * a bean Z exists, such that X directly specializes Z and Z specializes Y.
173
174
175 Then X will inherit the qualifiers and bean name of Y:
176
177 * the qualifiers of X include all qualifiers of Y, together with all qualifiers declared explicitly by X, and
178 * if Y has a bean name, the bean name of X is the same as the bean name of Y.
179
180
181 Furthermore, X must have all the bean types of Y. If X does not have some bean type of Y, the container automatically detects the problem and treats it as a definition error.
182
183 If Y has a bean name and X declares a bean name explicitly the container automatically detects the problem and treats it as a definition error.
184
185 For example, the following bean would have the inherited qualifiers +@Default+ and +@Asynchronous+:
186
187 [source, java]
188 ----
189 @Mock @Specializes
190 public class MockAsynchronousService extends AsynchronousService {
191 ...
192 }
193 ----
194
195 If +AsynchronousService+ declared a bean name:
196
197 [source, java]
198 ----
199 @Default @Asynchronous @Named("asyncService")
200 public class AsynchronousService implements Service{
201 ...
202 }
203 ----
204
205 Then the bean name would also automatically be inherited by +MockAsynchronousService+.
206
207 If an interceptor or decorator is annotated +@Specializes+, non-portable behavior results.
208