| 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 |
|