Debian Codegraph @

spec/src/main/doc/implementation.asciidoc

raw
1 [[implementation]]
2
3 == Programming model
4
5 The container provides built-in support for injection and contextual lifecycle management of the following kinds of bean:
6
7 * Managed beans
8 * Session beans
9 * Producer methods and fields
10 * Resources (Java EE resources, persistence contexts, persistence units, remote EJBs and web services)
11
12
13 All containers must support managed beans, producer methods and producer fields. Java EE and embeddable EJB containers are required by the Java EE and EJB specifications to support EJB session beans and the Java EE component environment. Other containers are not required to provide support for injection or lifecycle management of session beans or resources.
14
15 A portable extension may provide other kinds of beans by implementing the interface +Bean+ defined in <<bean>>.
16
17 [[managed_beans]]
18
19 === Managed beans
20
21 A _managed bean_ is a bean that is implemented by a Java class. This class is called the _bean class_ of the managed bean. The basic lifecycle and semantics of managed beans are defined by the Managed Beans specification.
22
23 If the bean class of a managed bean is annotated with both +@Interceptor+ and +@Decorator+, the container automatically detects the problem and treats it as a definition error.
24
25 If a managed bean has a non-static public field, it must have scope +@Dependent+. If a managed bean with a non-static public field declares any scope other than +@Dependent+, the container automatically detects the problem and treats it as a definition error.
26
27 If the managed bean class is a generic type, it must have scope +@Dependent+. If a managed bean with a parameterized bean class declares any scope other than +@Dependent+, the container automatically detects the problem and treats it as a definition error.
28
29 [[what_classes_are_beans]]
30
31 ==== Which Java classes are managed beans?
32
33 A top-level Java class is a managed bean if it is defined to be a managed bean by any other Java EE specification, or if it meets all of the following conditions:
34
35 * It is not a non-static inner class.
36 * It is a concrete class, or is annotated +@Decorator+.
37 * It is not annotated with an EJB component-defining annotation or declared as an EJB bean class in +ejb-jar.xml+.
38 * It does not implement +javax.enterprise.inject.spi.Extension+.
39 * It is not annotated +@Vetoed+ or in a package annotated +@Vetoed+.
40 * It has an appropriate constructor - either:
41 ** the class has a constructor with no parameters, or
42 ** the class declares a constructor annotated +@Inject+.
43
44 All Java classes that meet these conditions are managed beans and thus no special declaration is required to define a managed bean.
45
46 If packages annotated +@Vetoed+ are split across classpath entries, non-portable behavior results. An application can prevent packages being split across jars by sealing the package as defined by the link::http://download.java.net/jdk8/docs/technotes/guides/extensions/spec.html#sealing[Extension Mechanism Architecture].
47
48 [[managed_bean_types]]
49
50 ==== Bean types of a managed bean
51
52 The unrestricted set of bean types for a managed bean contains the bean class, every superclass and all interfaces it implements directly or indirectly.
53
54 Note the additional restrictions upon bean types of beans with normal scopes defined in <<unproxyable>>.
55
56 [[declaring_managed_bean]]
57
58 ==== Declaring a managed bean
59
60 A managed bean with a constructor that takes no parameters does not require any special annotations. The following classes are beans:
61
62 [source, java]
63 ----
64 public class Shop { .. }
65 ----
66
67 [source, java]
68 ----
69 class PaymentProcessorImpl implements PaymentProcessor { ... }
70 ----
71
72 If the managed bean does not have a constructor that takes no parameters, it must have a constructor annotated +@Inject+. No additional special annotations are required.
73
74 A bean class may specify a scope, bean name, stereotypes and/or qualifiers:
75
76 [source, java]
77 ----
78 @ConversationScoped @Default
79 public class ShoppingCart { ... }
80 ----
81
82 A managed bean may extend another managed bean:
83
84 [source, java]
85 ----
86 @Named("loginAction")
87 public class LoginAction { ... }
88 ----
89
90 [source, java]
91 ----
92 @Mock
93 @Named("loginAction")
94 public class MockLoginAction extends LoginAction { ... }
95 ----
96
97 The second bean is a "mock object" that overrides the implementation of +LoginAction+ when running in an embedded EJB Lite based integration testing environment.
98
99 [[specialize_managed_bean]]
100
101 ==== Specializing a managed bean
102
103 If a bean class of a managed bean X is annotated +@Specializes+, then the bean class of X must directly extend the bean class of another managed bean Y. Then X _directly specializes_ Y, as defined in <<specialization>>.
104
105 If the bean class of X does not directly extend the bean class of another managed bean, the container automatically detects the problem and treats it as a definition error.
106
107 For example, +MockLoginAction+ directly specializes +LoginAction+:
108
109 [source, java]
110 ----
111 public class LoginAction { ... }
112 ----
113
114 [source, java]
115 ----
116 @Mock @Specializes
117 public class MockLoginAction extends LoginAction { ... }
118 ----
119
120 [[managed_bean_name]]
121
122 ==== Default bean name for a managed bean
123
124 The default name for a managed bean is the unqualified class name of the bean class, after converting the first character to lower case.
125
126 For example, if the bean class is named +ProductList+, the default bean name is +productList+.
127
128 [[session_beans]]
129
130 === Session beans
131
132 A _session bean_ is a bean that is implemented by a session bean with an EJB 3.x client view that is not annotated with +@Vetoed+ or in a package annotated +@Vetoed+. The basic lifecycle and semantics of EJB session beans are defined by the EJB specification.
133
134 A stateless session bean must belong to the +@Dependent+ pseudo-scope. A singleton session bean must belong to either the +@ApplicationScoped+ scope or to the +@Dependent+ pseudo-scope. If a session bean specifies an illegal scope, the container automatically detects the problem and treats it as a definition error. A stateful session bean may have any scope.
135
136 When a contextual instance of a session bean is obtained via the dependency injection service, the behavior of +SessionContext.getInvokedBusinessInterface()+ is specific to the container implementation. Portable applications should not rely upon the value returned by this method.
137
138 If the bean class of a session bean is annotated +@Interceptor+ or +@Decorator+, the container automatically detects the problem and treats it as a definition error.
139
140 If the session bean class is a generic type, it must have scope +@Dependent+. If a session bean with a parameterized bean class declares any scope other than +@Dependent+, the container automatically detects the problem and treats it as a definition error.
141
142 If packages annotated +@Vetoed+ are split across classpath entries, non-portable behavior results. An application can prevent packages being split across jars by sealing the package as defined by the link::http://download.java.net/jdk8/docs/technotes/guides/extensions/spec.html#sealing[Extension Mechanism Architecture].
143
144 [[session_bean_ejb_remove_method]]
145
146 ==== EJB remove methods of session beans
147
148 If a session bean is a stateful session bean:
149
150 * If the scope is +@Dependent+, the application _may_ call any EJB remove method of a contextual instance of the session bean.
151 * Otherwise, the application _may not_ directly call any EJB remove method of any contextual instance of the session bean.
152
153 The session bean is not required to have an EJB remove method in order for the container to destroy it.
154
155 If the application directly calls an EJB remove method of a contextual instance of a session bean that is a stateful session bean and declares any scope other than +@Dependent+, an +UnsupportedOperationException+ is thrown.
156
157 If the application directly calls an EJB remove method of a contextual instance of a session bean that is a stateful session bean and has scope +@Dependent+ then no parameters are passed to the method by the container. Furthermore, the container ignores the instance instead of destroying it when +Contextual.destroy()+ is called, as defined in <<stateful_lifecycle>>.
158
159 [[session_bean_types]]
160
161 ==== Bean types of a session bean
162
163 The unrestricted set of bean types for a session bean contains all local interfaces of the bean and their superinterfaces. If the session bean has a no-interface view, the unrestricted set of bean types contains the bean class and all superclasses. In addition, +java.lang.Object+ is a bean type of every session bean.
164
165 Remote interfaces are not included in the set of bean types.
166
167 [[declaring_session_bean]]
168
169 ==== Declaring a session bean
170
171 A session bean does not require any special annotations apart from the component-defining annotation (or XML declaration) required by the EJB specification. The following EJBs are beans:
172
173 [source, java]
174 ----
175 @Singleton
176 class Shop { .. }
177 ----
178
179 [source, java]
180 ----
181 @Stateless
182 class PaymentProcessorImpl implements PaymentProcessor { ... }
183 ----
184
185 A bean class may also specify a scope, bean name, stereotypes and/or qualifiers:
186
187 [source, java]
188 ----
189 @ConversationScoped @Stateful @Default @Model
190 public class ShoppingCart { ... }
191 ----
192
193 A session bean class may extend another bean class:
194
195 [source, java]
196 ----
197 @Stateless
198 @Named("loginAction")
199 public class LoginActionImpl implements LoginAction { ... }
200 ----
201
202 [source, java]
203 ----
204 @Stateless
205 @Mock
206 @Named("loginAction")
207 public class MockLoginActionImpl extends LoginActionImpl { ... }
208 ----
209
210 [[specialize_session_bean]]
211
212 ==== Specializing a session bean
213
214 If a bean class of a session bean X is annotated +@Specializes+, then the bean class of X must directly extend the bean class of another session bean Y. Then X _directly specializes_ Y, as defined in <<specialization>>.
215
216 If the bean class of X does not directly extend the bean class of another session bean, the container automatically detects the problem and treats it as a definition error.
217
218 For example, +MockLoginActionBean+ directly specializes +LoginActionBean+:
219
220 [source, java]
221 ----
222 @Stateless
223 public class LoginActionBean implements LoginAction { ... }
224 ----
225
226 [source, java]
227 ----
228 @Stateless @Mock @Specializes
229 public class MockLoginActionBean extends LoginActionBean implements LoginAction { ... }
230 ----
231
232 [[session_bean_name]]
233
234 ==== Default bean name for a session bean
235
236 The default name for a session bean is the unqualified class name of the session bean class, after converting the first character to lower case.
237
238 For example, if the bean class is named +ProductList+, the default bean name is +productList+.
239
240 [[producer_method]]
241
242 === Producer methods
243
244 A _producer method_ acts as a source of objects to be injected, where:
245
246 * the objects to be injected are not required to be instances of beans, or
247 * the concrete type of the objects to be injected may vary at runtime, or
248 * the objects require some custom initialization that is not performed by the bean constructor.
249
250
251 A producer method must be a default-access, public, protected or private, non-abstract method of a managed bean class or session bean class. A producer method may be either static or non-static. If the bean is a session bean, the producer method must be either a business method of the EJB or a static method of the bean class.
252
253 If a producer method sometimes returns a null value, then the producer method must have scope +@Dependent+. If a producer method returns a null value at runtime, and the producer method declares any other scope, an +IllegalProductException+ is thrown by the container. This restriction allows the container to use a client proxy, as defined in <<client_proxies>>.
254
255 If the producer method return type is a parameterized type, it must specify an actual type parameter or type variable for each type parameter.
256
257 If a producer method return type contains a wildcard type parameter or is an array type whose component type contains a wildcard type parameter, the container automatically detects the problem and treats it as a definition error.
258
259 If the producer method return type is a parameterized type with a type variable, it must have scope +@Dependent+. If a producer method with a parameterized return type with a type variable declares any scope other than +@Dependent+, the container automatically detects the problem and treats it as a definition error.
260
261 If a producer method return type is a type variable or an array type whose component type is a type variable the container automatically detects the problem and treats it as a definition error.
262
263 The application may call producer methods directly. However, if the application calls a producer method directly, no parameters will be passed to the producer method by the container; the returned object is not bound to any context; and its lifecycle is not managed by the container.
264
265 A bean may declare multiple producer methods.
266
267 [[producer_method_types]]
268
269 ==== Bean types of a producer method
270
271 The bean types of a producer method depend upon the method return type:
272
273 * If the return type is an interface, the unrestricted set of bean types contains the return type, all interfaces it extends directly or indirectly and +java.lang.Object+.
274 * If a return type is primitive or is a Java array type, the unrestricted set of bean types contains exactly two types: the method return type and +java.lang.Object+.
275 * If the return type is a class, the unrestricted set of bean types contains the return type, every superclass and all interfaces it implements directly or indirectly.
276
277
278 Note the additional restrictions upon bean types of beans with normal scopes defined in <<unproxyable>>.
279
280 [[declaring_producer_method]]
281
282 ==== Declaring a producer method
283
284 A producer method may be declared by annotating a method with the [email protected]+ annotation.
285
286 [source, java]
287 ----
288 public class Shop {
289 @Produces PaymentProcessor getPaymentProcessor() { ... }
290 @Produces List<Product> getProducts() { ... }
291 }
292 ----
293
294 A producer method may also specify scope, bean name, stereotypes and/or qualifiers.
295
296 [source, java]
297 ----
298 public class Shop {
299 @Produces @ApplicationScoped @Catalog @Named("catalog")
300 List<Product> getProducts() { ... }
301 }
302 ----
303
304 If a producer method is annotated +@Inject+, has a parameter annotated +@Disposes+, or has a parameter annotated +@Observes+, the container automatically detects the problem and treats it as a definition error.
305
306 If a non-static method of a session bean class is annotated +@Produces+, and the method is not a business method of the session bean, the container automatically detects the problem and treats it as a definition error.
307
308 Interceptors and decorators may not declare producer methods. If an interceptor or decorator has a method annotated +@Produces+, the container automatically detects the problem and treats it as a definition error.
309
310 A producer method may have any number of parameters. All producer method parameters are injection points.
311
312 [source, java]
313 ----
314 public class OrderFactory {
315
316 @Produces @ConversationScoped
317 public Order createCurrentOrder(Shop shop, @Selected Product product) {
318 Order order = new Order(product, shop);
319 return order;
320 }
321
322 }
323 ----
324
325 [[specialize_producer_method]]
326
327 ==== Specializing a producer method
328
329 If a producer method X is annotated +@Specializes+, then it must be non-static and directly override another producer method Y. Then X _directly specializes_ Y, as defined in <<specialization>>.
330
331 If the method is static or does not directly override another producer method, the container automatically detects the problem and treats it as a definition error.
332
333 [source, java]
334 ----
335 @Mock
336 public class MockShop extends Shop {
337
338 @Override @Specializes
339 @Produces
340 PaymentProcessor getPaymentProcessor() {
341 return new MockPaymentProcessor();
342 }
343
344 @Override @Specializes
345 @Produces
346 List<Product> getProducts() {
347 return PRODUCTS;
348 }
349
350 ...
351
352 }
353 ----
354
355 [[producer_method_name]]
356
357 ==== Default bean name for a producer method
358
359 The default name for a producer method is the method name, unless the method follows the JavaBeans property getter naming convention, in which case the default name is the JavaBeans property name.
360
361 For example, this producer method is named +products+:
362
363 [source, java]
364 ----
365 @Produces @Named
366 public List<Product> getProducts() { ... }
367 ----
368
369 This producer method is named +paymentProcessor+:
370
371 [source, java]
372 ----
373 @Produces @Named
374 public PaymentProcessor paymentProcessor() { ... }
375 ----
376
377 [[producer_field]]
378
379 === Producer fields
380
381 A _producer field_ is a slightly simpler alternative to a producer method.
382
383 A producer field must be a default-access, public, protected or private, field of a managed bean class or session bean class. A producer field may be either static or non-static. If the bean is a session bean, the producer field must be a static field of the bean class.
384
385 If a producer field sometimes contains a null value when accessed, then the producer field must have scope +@Dependent+. If a producer field contains a null value at runtime, and the producer field declares any other scope, an +IllegalProductException+ is thrown by the container. This restriction allows the container to use a client proxy, as defined in <<client_proxies>>.
386
387 If the producer field type is a parameterized type, it must specify an actual type parameter or type variable for each type parameter.
388
389 If a producer field type contains a wildcard type parameter or is an array type whose component type contains a wildcard parameter, the container automatically detects the problem and treats it as a definition error.
390
391 If the producer field type is a parameterized type with a type variable, it must have scope +@Dependent+. If a producer field with a parameterized type with a type variable declares any scope other than +@Dependent+, the container automatically detects the problem and treats it as a definition error.
392
393 If a producer field type is a type variable or is an array type whose component type is a type variable the container automatically detects the problem and treats it as a definition error.
394
395 The application may access producer fields directly. However, if the application accesses a producer field directly, the returned object is not bound to any context; and its lifecycle is not managed by the container.
396
397 A bean may declare multiple producer fields.
398
399 [[producer_field_types]]
400
401 ==== Bean types of a producer field
402
403 The bean types of a producer field depend upon the field type:
404
405 * If the field type is an interface, the unrestricted set of bean types contains the field type, all interfaces it extends directly or indirectly and +java.lang.Object+.
406 * If a field type is primitive or is a Java array type, the unrestricted set of bean types contains exactly two types: the field type and +java.lang.Object+.
407 * If the field type is a class, the unrestricted set of bean types contains the field type, every superclass and all interfaces it implements directly or indirectly.
408
409
410 Note the additional restrictions upon bean types of beans with normal scopes defined in <<unproxyable>>.
411
412 [[declaring_producer_field]]
413
414 ==== Declaring a producer field
415
416 A producer field may be declared by annotating a field with the [email protected]+ annotation.
417
418 [source, java]
419 ----
420 public class Shop {
421 @Produces PaymentProcessor paymentProcessor = ....;
422 @Produces List<Product> products = ....;
423 }
424 ----
425
426 A producer field may also specify scope, bean name, stereotypes and/or qualifiers.
427
428 [source, java]
429 ----
430 public class Shop {
431 @Produces @ApplicationScoped @Catalog @Named("catalog")
432 List<Product> products = ....;
433 }
434 ----
435
436 If a producer field is annotated +@Inject+, the container automatically detects the problem and treats it as a definition error.
437
438 If a non-static field of a session bean class is annotated +@Produces+, the container automatically detects the problem and treats it as a definition error.
439
440 Interceptors and decorators may not declare producer fields. If an interceptor or decorator has a field annotated +@Produces+, the container automatically detects the problem and treats it as a definition error.
441
442 [[producer_field_name]]
443
444 ==== Default bean name for a producer field
445
446 The default name for a producer field is the field name.
447
448 For example, this producer field is named +products+:
449
450 [source, java]
451 ----
452 @Produces @Named
453 public List<Product> products = ...;
454 ----
455
456 [[disposer_method]]
457
458 === Disposer methods
459
460 A disposer method allows the application to perform customized cleanup of an object returned by a producer method or producer field.
461
462 A disposer method must be a default-access, public, protected or private, non-abstract method of a managed bean class or session bean class. A disposer method may be either static or non-static. If the bean is a session bean, the disposer method must be a business method of the EJB or a static method of the bean class.
463
464 A bean may declare multiple disposer methods.
465
466 [[disposer_method_disposed_parameter]]
467
468 ==== Disposed parameter of a disposer method
469
470 Each disposer method must have exactly one _disposed parameter_, of the same type as the corresponding producer method return type or producer field type. When searching for disposer methods for a producer method or producer field the container considers the type and qualifiers of the disposed parameter. If a producer method or producer field declared by the same bean class is assignable to the disposed parameter, according to the rules of typesafe resolution defined in <<typesafe_resolution>>, the container must call this method when destroying any instance returned by that producer method or producer field.
471
472 A disposer method may resolve to multiple producer methods or producer fields declared by the bean class, in which case the container must call it when destroying any instance returned by any of these producer methods or producer fields.
473
474 [[declaring_disposer_method]]
475
476 ==== Declaring a disposer method
477
478 A disposer method may be declared by annotating a parameter [email protected]+. That parameter is the disposed parameter. Qualifiers may be declared by annotating the disposed parameter:
479
480 [source, java]
481 ----
482 public class UserDatabaseEntityManager {
483
484 @Produces @ConversationScoped @UserDatabase
485 public EntityManager create(EntityManagerFactory emf) {
486 return emf.createEntityManager();
487 }
488
489 public void close(@Disposes @UserDatabase EntityManager em) {
490 em.close();
491 }
492
493 }
494 ----
495
496 [source, java]
497 ----
498 public class Resources {
499
500 @PersistenceContext
501 @Produces @UserDatabase
502 private EntityManager em;
503
504 public void close(@Disposes @UserDatabase EntityManager em) {
505 em.close();
506 }
507
508 }
509 ----
510
511 If a method has more than one parameter annotated +@Disposes+, the container automatically detects the problem and treats it as a definition error.
512
513 If a disposer method is annotated +@Produces+ or +@Inject+ or has a parameter annotated +@Observes+, the container automatically detects the problem and treats it as a definition error.
514
515 If a non-static method of a session bean class has a parameter annotated +@Disposes+, and the method is not a business method of the session bean, the container automatically detects the problem and treats it as a definition error.
516
517 Interceptors and decorators may not declare disposer methods. If an interceptor or decorator has a method annotated +@Disposes+, the container automatically detects the problem and treats it as a definition error.
518
519 In addition to the disposed parameter, a disposer method may declare additional parameters, which may also specify qualifiers. These additional parameters are injection points.
520
521 [source, java]
522 ----
523 public void close(@Disposes @UserDatabase EntityManager em, Logger log) { ... }
524 ----
525
526 [[disposer_method_resolution]]
527
528 ==== Disposer method resolution
529
530 A disposer method is bound to a producer method or producer field if:
531
532 * the producer method or producer field is declared by the same bean class as the disposer method, and
533 * the producer method or producer field is assignable to the disposed parameter, according to the rules of typesafe resolution defined in <<typesafe_resolution>> (using <<assignable_parameters>>).
534
535
536 If there are multiple disposer methods for a single producer method or producer field, the container automatically detects the problem and treats it as a definition error.
537
538 If there is no producer method or producer field declared by the bean class that is assignable to the disposed parameter of a disposer method, the container automatically detects the problem and treats it as a definition error.
539
540 [[javaee_components]]
541
542 === Java EE components
543
544 Most Java EE components support injection and interception, as defined in the Java Platform, Enterprise Edition Specification 7, table EE.5-1, but are not considered beans (as defined by this specification). EJBs, as defined in <<session_beans>> are an exception.
545
546 The instance used by the container to service an invocation of a Java EE component will not be the same instance obtained when using +@Inject+, instantiated by the container to invoke a producer method, observer method or disposer method, or instantiated by the container to access the value of a producer field. It is recommended that Java EE components should not define observer methods, producer methods, producer fields or disposer methods. It is safe to annotate Java EE components with +@Vetoed+ to prevent them being considered beans.
547
548 [[resources]]
549
550 === Resources
551
552 A _resource_ is a bean that represents a reference to a resource, persistence context, persistence unit, remote EJB or web service in the Java EE component environment.
553
554 By declaring a resource, we enable an object from the Java EE component environment to be injected by specifying only its type and qualifiers at the injection point. For example, if +@CustomerDatabase+ is a qualifier:
555
556 [source, java]
557 ----
558 @Inject @CustomerDatabase Datasource customerData;
559 ----
560
561 [source, java]
562 ----
563 @Inject @CustomerDatabase EntityManager customerDatabaseEntityManager;
564 ----
565
566 [source, java]
567 ----
568 @Inject @CustomerDatabase EntityManagerFactory customerDatabaseEntityManagerFactory;
569 ----
570
571 [source, java]
572 ----
573 @Inject PaymentService remotePaymentService;
574 ----
575
576 The container is not required to support resources with scope other than +@Dependent+. Portable applications should not define resources with any scope other than +@Dependent+.
577
578 A resource may not have a bean name.
579
580 [[declaring_resource]]
581
582 ==== Declaring a resource
583
584 A resource may be declared by specifying a Java EE component environment injection annotation as part of a producer field declaration. The producer field may be static.
585
586 * For a Java EE resource, +@Resource+ must be specified.
587 * For a persistence context, +@PersistenceContext+ must be specified.
588 * For a persistence unit, +@PersistenceUnit+ must be specified.
589 * For a remote EJB, +@EJB+ must be specified.
590 * For a web service, +@WebServiceRef+ must be specified.
591
592
593 The injection annotation specifies the metadata needed to obtain the resource, entity manager, entity manager factory, remote EJB instance or web service reference from the component environment.
594
595 [source, java]
596 ----
597 @Produces @WebServiceRef(lookup="java:app/service/PaymentService")
598 PaymentService paymentService;
599 ----
600
601 [source, java]
602 ----
603 @Produces @EJB(ejbLink="../their.jar#PaymentService")
604 PaymentService paymentService;
605 ----
606
607 [source, java]
608 ----
609 @Produces @Resource(lookup="java:global/env/jdbc/CustomerDatasource")
610 @CustomerDatabase Datasource customerDatabase;
611 ----
612
613 [source, java]
614 ----
615 @Produces @PersistenceContext(unitName="CustomerDatabase")
616 @CustomerDatabase EntityManager customerDatabasePersistenceContext;
617 ----
618
619 [source, java]
620 ----
621 @Produces @PersistenceUnit(unitName="CustomerDatabase")
622 @CustomerDatabase EntityManagerFactory customerDatabasePersistenceUnit;
623 ----
624
625 The bean type and qualifiers of the resource are determined by the producer field declaration.
626
627 If the producer field declaration specifies a bean name, the container automatically detects the problem and treats it as a definition error.
628
629 If the matching object in the Java EE component environment is not of the same type as the producer field declaration, the container automatically detects the problem and treats it as a definition error.
630
631 [[resource_types]]
632
633 ==== Bean types of a resource
634
635 The unrestricted set of bean types of a resource is determined by the declared type of the producer field, as specified by <<producer_field_types>>.
636
637 [[additional_builtin_beans]]
638
639 === Additional built-in beans
640
641 A Java EE or embeddable EJB container must provide the following built-in beans, all of which have qualifier +@Default+:
642
643 * a bean with bean type +javax.transaction.UserTransaction+, allowing injection of a reference to the JTA +UserTransaction+, and
644 * a bean with bean type +javax.security.Principal+, allowing injection of a +Principal+ representing the current caller identity.
645
646
647 A servlet container must provide the following built-in beans, all of which have qualifier +@Default+:
648
649 * a bean with bean type +javax.servlet.http.HttpServletRequest+, allowing injection of a reference to the +HttpServletRequest+
650 * a bean with bean type +javax.servlet.http.HttpSession+, allowing injection of a reference to the +HttpSession+,
651 * a bean with bean type +javax.servlet.ServletContext+, allowing injection of a reference to the +ServletContext+,
652
653
654 These beans are passivation capable dependencies, as defined in <<passivation_capable_dependency>>.
655
656 If a Java EE component class has an injection point of type +UserTransaction+ and qualifier +@Default+, and may not validly make use of the JTA +UserTransaction+ according to the Java EE platform specification, the container automatically detects the problem and treats it as a definition error.
657
658 [[bean_constructors]]
659
660 === Bean constructors
661
662 When the container instantiates a bean class, it calls the _bean constructor_. The bean constructor is a default-access, public, protected or private constructor of the bean class.
663
664 The application may call bean constructors directly. However, if the application directly instantiates the bean, no parameters are passed to the constructor by the container; the returned object is not bound to any context; no dependencies are injected by the container; and the lifecycle of the new instance is not managed by the container.
665
666 [[declaring_bean_constructor]]
667
668 ==== Declaring a bean constructor
669
670 The bean constructor may be identified by annotating the constructor +@Inject+.
671
672 [source, java]
673 ----
674 @SessionScoped
675 public class ShoppingCart implements Serializable {
676
677 private User customer;
678
679 @Inject
680 public ShoppingCart(User customer) {
681 this.customer = customer;
682 }
683
684 public ShoppingCart(ShoppingCart original) {
685 this.customer = original.customer;
686 }
687
688 ShoppingCart() {}
689
690 ...
691
692 }
693 ----
694
695 [source, java]
696 ----
697 @ConversationScoped
698 public class Order {
699
700 private Product product;
701 private User customer;
702
703 @Inject
704 public Order(@Selected Product product, User customer) {
705 this.product = product;
706 this.customer = customer;
707 }
708
709 public Order(Order original) {
710 this.product = original.product;
711 this.customer = original.customer;
712 }
713
714 Order() {}
715
716 ...
717
718 }
719 ----
720
721 If a bean class does not explicitly declare a constructor using +@Inject+, the constructor that accepts no parameters is the bean constructor.
722
723 If a bean class has more than one constructor annotated +@Inject+, the container automatically detects the problem and treats it as a definition error.
724
725 If a bean constructor has a parameter annotated +@Disposes+, or +@Observes+, the container automatically detects the problem and treats it as a definition error.
726
727 A bean constructor may have any number of parameters. All parameters of a bean constructor are injection points.
728
729 [[injected_fields]]
730
731 === Injected fields
732
733 An _injected field_ is a non-static, non-final field of a bean class or of any Java EE component class supporting injection.
734
735 [[declaring_injected_field]]
736
737 ==== Declaring an injected field
738
739 An injected field may be declared by annotating the field [email protected]+.
740
741 [source, java]
742 ----
743 @ConversationScoped
744 public class Order {
745
746 @Inject @Selected Product product;
747 @Inject User customer;
748
749 }
750 ----
751
752 If an injected field is annotated +@Produces+, the container automatically detects the problem and treats it as a definition error.
753
754 [[initializer_methods]]
755
756 === Initializer methods
757
758 An _initializer method_ is a default-access, public, protected or private, non-abstract, non-static, non-generic method of a bean class or of any Java EE component class supporting injection. If the bean is a session bean, the initializer method is _not_ required to be a business method of the session bean.
759
760 A bean class may declare multiple (or zero) initializer methods.
761
762 Method interceptors are never called when the container calls an initializer method.
763
764 The application may call initializer methods directly, but then no parameters will be passed to the method by the container.
765
766 [[declaring_initializer]]
767
768 ==== Declaring an initializer method
769
770 An initializer method may be declared by annotating the method [email protected]+.
771
772 [source, java]
773 ----
774 @ConversationScoped
775 public class Order {
776
777 private Product product;
778 private User customer;
779
780 @Inject
781 void setProduct(@Selected Product product) {
782 this.product = product;
783 }
784
785 @Inject
786 public void setCustomer(User customer) {
787 this.customer = customer;
788 }
789
790 }
791 ----
792
793 If a generic method of a bean is annotated +@Inject+, the container automatically detects the problem and treats it as a definition error.
794
795 If an initializer method is annotated +@Produces+, has a parameter annotated +@Disposes+, or has a parameter annotated +@Observes+, the container automatically detects the problem and treats it as a definition error.
796
797 An initializer method may have any number of parameters. All initializer method parameters are injection points.
798
799 [[injection_point_default_qualifier]]
800
801 === The default qualifier at injection points
802
803 If an injection point declares no qualifier, the injection point has exactly one qualifier, the default qualifier +@Default+.
804
805 The following are equivalent:
806
807 [source, java]
808 ----
809 @ConversationScoped
810 public class Order {
811
812 private Product product;
813 private User customer;
814
815 @Inject
816 public void init(@Selected Product product, User customer) {
817 this.product = product;
818 this.customer = customer;
819 }
820
821 }
822 ----
823
824 [source, java]
825 ----
826 @ConversationScoped
827 public class Order {
828
829 private Product product;
830 private User customer;
831
832 @Inject
833 public void init(@Selected Product product, @Default User customer) {
834 this.product = product;
835 this.customer = customer;
836 }
837
838 }
839 ----
840
841 The following definitions are equivalent:
842
843 [source, java]
844 ----
845 public class Payment {
846
847 public Payment(BigDecimal amount) { ... }
848
849 @Inject Payment(Order order) {
850 this(order.getAmount();
851 }
852
853 }
854 ----
855
856 [source, java]
857 ----
858 public class Payment {
859
860 public Payment(BigDecimal amount) { ... }
861
862 @Inject Payment(@Default Order order) {
863 this(order.getAmount();
864 }
865
866 }
867 ----
868
869 Finally, the following are equivalent:
870
871 [source, java]
872 ----
873 @Inject Order order;
874 ----
875
876 [source, java]
877 ----
878 @Inject @Default Order order;
879 ----
880
881 [[named_at_injection_point]]
882
883 === The qualifier +@Named+ at injection points
884
885 The use of +@Named+ as an injection point qualifier is not recommended, except in the case of integration with legacy code that uses string-based names to identify beans.
886
887 If an injected field declares a +@Named+ annotation that does not specify the +value+ member, the name of the field is assumed. For example, the following field has the qualifier +@Named("paymentService")+:
888
889 [source, java]
890 ----
891 @Inject @Named PaymentService paymentService;
892 ----
893
894 If any other injection point declares a +@Named+ annotation that does not specify the +value+ member, the container automatically detects the problem and treats it as a definition error.
895
896 [[new]]
897
898 === +@New+ qualified beans
899
900 _The @New qualifier was deprecated in CDI 1.1. CDI applications are encouraged to inject @Dependent scoped beans instead._
901
902 For each managed bean, and for each session bean, a second bean exists which:
903
904 * has the same bean class,
905 * has the same bean types,
906 * has the same bean constructor, initializer methods and injected fields, and
907 * has the same interceptor bindings.
908
909
910 However, this second bean:
911
912 * has scope +@Dependent+,
913 * has exactly one qualifier: [email protected](X.class)+ where +X+ is the bean class,
914 * has no bean name,
915 * has no stereotypes,
916 * has no observer methods, producer methods or fields or disposer methods, and
917 * is not an alternative, and
918 * is enabled, in the sense of <<enablement>>, if and only if some other enabled bean has an injection point with the qualifier +@New(X.class)+ where +X+ is the bean class.
919
920
921 This bean is called the _@New qualified bean_ for the class +X+.
922
923 Note that this second bean exists - and may be enabled and available for injection - even if the first bean is disabled, as defined by <<enablement>>, or if the bean class is deployed outside of a bean archive, as defined in <<bean_archive>>, and is therefore not discovered during the bean discovery process defined in <<packaging_deployment>>. The container discovers +@New+ qualified beans by inspecting injection points of other enabled beans.
924
925 This allows the application to obtain a new instance of a bean which is not bound to the declared scope, but has had dependency injection performed.
926
927 [source, java]
928 ----
929 @Produces @ConversationScoped
930 @Special Order getSpecialOrder(@New(Order.class) Order order) {
931 ...
932 return order;
933 }
934 ----
935
936 When the qualifier +@New+ is specified at an injection point and no +value+ member is explicitly specified, the container defaults the +value+ to the declared type of the injection point. So the following injection point has qualifier +@New(Order.class)+:
937
938 [source, java]
939 ----
940 @Produces @ConversationScoped
941 @Special Order getSpecialOrder(@New Order order) { ... }
942 ----
943
944 [[unproxyable]]
945
946 === Unproxyable bean types
947
948 The container uses proxies to provide certain functionality. Certain legal bean types cannot be proxied by the container:
949
950 * classes which don't have a non-private constructor with no parameters,
951 * classes which are declared final,
952 * classes which have non-static, final methods with public, protected or default visibility,
953 * primitive types,
954 * and array types.
955
956
957 A bean type must be proxyable if an injection point resolves to a bean:
958
959 * that requires a client proxy, or
960 * that has an associated decorator, or
961 * that has a bound interceptor.
962
963
964 Otherwise, the container automatically detects the problem, and treats it as a deployment problem.
965