| 1 |
[[concepts]] |
| 2 |
|
| 3 |
== Concepts |
| 4 |
|
| 5 |
A Java EE component is a _bean_ if the lifecycle of its instances may be managed by the container according to the lifecycle context model defined in <<contexts>>. A bean may bear metadata defining its lifecycle and interactions with other components. |
| 6 |
|
| 7 |
Speaking more abstractly, a bean is a source of contextual objects which define application state and/or logic. These objects are called _contextual instances of the bean_. The container creates and destroys these instances and associates them with the appropriate context. Contextual instances of a bean may be injected into other objects (including other bean instances) that execute in the same context, and may be used in EL expressions that are evaluated in the same context. |
| 8 |
|
| 9 |
A bean comprises the following attributes: |
| 10 |
|
| 11 |
* A (nonempty) set of bean types |
| 12 |
* A (nonempty) set of qualifiers |
| 13 |
* A scope |
| 14 |
* Optionally, a bean name |
| 15 |
* A set of interceptor bindings |
| 16 |
* A bean implementation |
| 17 |
|
| 18 |
|
| 19 |
Furthermore, a bean may or may not be an alternative. |
| 20 |
|
| 21 |
In most cases, a bean developer provides the bean implementation by writing business logic in Java code. The developer then defines the remaining attributes by explicitly annotating the bean class, or by allowing them to be defaulted by the container, as specified in <<implementation>>. In certain other cases - for example, Java EE component environment resources, defined in <<resources>> - the developer provides only the annotations and the bean implementation is provided by the container. |
| 22 |
|
| 23 |
The bean types and qualifiers of a bean determine where its instances will be injected by the container, as defined in <<injection_el_resolution>>. |
| 24 |
|
| 25 |
The bean developer may also create interceptors and/or decorators or reuse existing interceptors and/or decorators. The interceptor bindings of a bean determine which interceptors will be applied at runtime. The bean types and qualifiers of a bean determine which decorators will be applied at runtime. Interceptors are defined by Java interceptors specification, and interceptor bindings are specified in <<interceptors>>. Decorators are defined in <<decorators>>. |
| 26 |
|
| 27 |
[[capabilities]] |
| 28 |
|
| 29 |
=== Functionality provided by the container to the bean |
| 30 |
|
| 31 |
A bean is provided by the container with the following capabilities: |
| 32 |
|
| 33 |
* transparent creation and destruction and scoping to a particular context, specified in <<contexts>> and <<lifecycle>>, |
| 34 |
* scoped resolution by bean type and qualifier annotation type when injected into a Java-based client, as defined by <<typesafe_resolution>>, |
| 35 |
* scoped resolution by bean name when used in a Unified EL expression, as defined by <<name_resolution>>, |
| 36 |
* lifecycle callbacks and automatic injection of other bean instances, specified in <<implementation>> and <<injection_el_resolution>>, |
| 37 |
* method interception, callback interception, and decoration, as defined in <<interceptors>> and <<decorators>>, and |
| 38 |
* event notification, as defined in <<events>>. |
| 39 |
|
| 40 |
|
| 41 |
[[bean_types]] |
| 42 |
|
| 43 |
=== Bean types |
| 44 |
|
| 45 |
A bean type defines a client-visible type of the bean. A bean may have multiple bean types. For example, the following bean has four bean types: |
| 46 |
|
| 47 |
[source, java] |
| 48 |
---- |
| 49 |
public class BookShop |
| 50 |
extends Business |
| 51 |
implements Shop<Book> { |
| 52 |
... |
| 53 |
} |
| 54 |
---- |
| 55 |
|
| 56 |
The bean types are +BookShop+, +Business+, +Shop<Book>+ and +Object+. |
| 57 |
|
| 58 |
Meanwhile, this session bean has only the local interfaces +BookShop+ and +Auditable+, along with +Object+, as bean types, since the bean class is not a client-visible type. |
| 59 |
|
| 60 |
[source, java] |
| 61 |
---- |
| 62 |
@Stateful |
| 63 |
public class BookShopBean |
| 64 |
extends Business |
| 65 |
implements BookShop, Auditable { |
| 66 |
... |
| 67 |
} |
| 68 |
---- |
| 69 |
|
| 70 |
The rules for determining the (unrestricted) set of bean types for a bean are defined in <<managed_bean_types>>, <<session_bean_types>>, <<producer_method_types>>, <<producer_field_types>> and <<resource_types>>. |
| 71 |
|
| 72 |
All beans have the bean type +java.lang.Object+. |
| 73 |
|
| 74 |
The bean types of a bean are used by the rules of typesafe resolution defined in <<typesafe_resolution>>. |
| 75 |
|
| 76 |
[[legal_bean_types]] |
| 77 |
|
| 78 |
==== Legal bean types |
| 79 |
|
| 80 |
Almost any Java type may be a bean type of a bean: |
| 81 |
|
| 82 |
* A bean type may be an interface, a concrete class or an abstract class, and may be declared final or have final methods. |
| 83 |
* A bean type may be a parameterized type with actual type parameters and type variables. |
| 84 |
* A bean type may be an array type. Two array types are considered identical only if the element type is identical. |
| 85 |
* A bean type may be a primitive type. Primitive types are considered to be identical to their corresponding wrapper types in +java.lang+. |
| 86 |
* A bean type may be a raw type. |
| 87 |
|
| 88 |
However, some Java types are not legal bean types : |
| 89 |
|
| 90 |
* A type variable is not a legal bean type. |
| 91 |
* A parameterized type that contains a wildcard type parameter is not a legal bean type. |
| 92 |
* An array type whose component type is not a legal bean type. |
| 93 |
|
| 94 |
Note that certain additional restrictions are specified in <<unproxyable>> for beans with a normal scope, as defined in <<normal_scope>>. |
| 95 |
|
| 96 |
[[restricting_bean_types]] |
| 97 |
|
| 98 |
==== Restricting the bean types of a bean |
| 99 |
|
| 100 |
The bean types of a bean may be restricted by annotating the bean class or producer method or field with the annotation [email protected]+. |
| 101 |
|
| 102 |
[source, java] |
| 103 |
---- |
| 104 |
@Typed(Shop.class) |
| 105 |
public class BookShop |
| 106 |
extends Business |
| 107 |
implements Shop<Book> { |
| 108 |
... |
| 109 |
} |
| 110 |
---- |
| 111 |
|
| 112 |
When a +@Typed+ annotation is explicitly specified, only the types whose classes are explicitly listed using the +value+ member, together with +java.lang.Object+, are bean types of the bean. |
| 113 |
|
| 114 |
In the example, the bean has a two bean types: +Shop<Book>+ and +Object+. |
| 115 |
|
| 116 |
If a bean class or producer method or field specifies a +@Typed+ annotation, and the +value+ member specifies a class which does not correspond to a type in the unrestricted set of bean types of a bean, the container automatically detects the problem and treats it as a definition error. |
| 117 |
|
| 118 |
[[typecasting_between_bean_types]] |
| 119 |
|
| 120 |
==== Typecasting between bean types |
| 121 |
|
| 122 |
A client of a bean may typecast its contextual reference to a bean to any bean type of the bean which is a Java interface. However, the client may not in general typecast its contextual reference to an arbitrary concrete bean type of the bean. For example, if our managed bean was injected to the following field: |
| 123 |
|
| 124 |
[source, java] |
| 125 |
---- |
| 126 |
@Inject Business biz; |
| 127 |
---- |
| 128 |
|
| 129 |
Then the following typecast is legal: |
| 130 |
|
| 131 |
[source, java] |
| 132 |
---- |
| 133 |
Shop<Book> bookShop = (Shop<Book>) biz; |
| 134 |
---- |
| 135 |
|
| 136 |
However, the following typecast is not legal and might result in an exception at runtime: |
| 137 |
|
| 138 |
[source, java] |
| 139 |
---- |
| 140 |
BookShop bookShop = (BookShop) biz; |
| 141 |
---- |
| 142 |
|
| 143 |
[[qualifiers]] |
| 144 |
|
| 145 |
=== Qualifiers |
| 146 |
|
| 147 |
For a given bean type, there may be multiple beans which implement the type. For example, an application may have two implementations of the interface +PaymentProcessor+: |
| 148 |
|
| 149 |
[source, java] |
| 150 |
---- |
| 151 |
class SynchronousPaymentProcessor |
| 152 |
implements PaymentProcessor { |
| 153 |
... |
| 154 |
} |
| 155 |
---- |
| 156 |
|
| 157 |
[source, java] |
| 158 |
---- |
| 159 |
class AsynchronousPaymentProcessor |
| 160 |
implements PaymentProcessor { |
| 161 |
... |
| 162 |
} |
| 163 |
---- |
| 164 |
|
| 165 |
A client that needs a +PaymentProcessor+ that processes payments synchronously needs some way to distinguish between the two different implementations. One approach would be for the client to explicitly specify the class that implements the +PaymentProcessor+ interface. However, this approach creates a hard dependence between client and implementation - exactly what use of the interface was designed to avoid! |
| 166 |
|
| 167 |
A _qualifier type_ represents some client-visible semantic associated with a type that is satisfied by some implementations of the type (and not by others). For example, we could introduce qualifier types representing synchronicity and asynchronicity. In Java code, qualifier types are represented by annotations. |
| 168 |
|
| 169 |
[source, java] |
| 170 |
---- |
| 171 |
@Synchronous |
| 172 |
class SynchronousPaymentProcessor |
| 173 |
implements PaymentProcessor { |
| 174 |
... |
| 175 |
} |
| 176 |
---- |
| 177 |
|
| 178 |
[source, java] |
| 179 |
---- |
| 180 |
@Asynchronous |
| 181 |
class AsynchronousPaymentProcessor |
| 182 |
implements PaymentProcessor { |
| 183 |
... |
| 184 |
} |
| 185 |
---- |
| 186 |
|
| 187 |
Finally, qualifier types are applied to injection points to distinguish which implementation is required by the client. For example, when the container encounters the following injected field, an instance of +SynchronousPaymentProcessor+ will be injected: |
| 188 |
|
| 189 |
[source, java] |
| 190 |
---- |
| 191 |
@Inject @Synchronous PaymentProcessor paymentProcessor; |
| 192 |
---- |
| 193 |
|
| 194 |
But in this case, an instance of +AsynchronousPaymentProcessor+ will be injected: |
| 195 |
|
| 196 |
[source, java] |
| 197 |
---- |
| 198 |
@Inject @Asynchronous PaymentProcessor paymentProcessor; |
| 199 |
---- |
| 200 |
|
| 201 |
The container inspects the qualifier annotations and type of the injected attribute to determine the bean instance to be injected, according to the rules of typesafe resolution defined in <<typesafe_resolution>>. |
| 202 |
|
| 203 |
An injection point may even specify multiple qualifiers. |
| 204 |
|
| 205 |
Qualifier types are also used as event selectors by event consumers, as defined in <<events>>, and to bind decorators to beans, as specified in <<decorators>>. |
| 206 |
|
| 207 |
[[builtin_qualifiers]] |
| 208 |
|
| 209 |
==== Built-in qualifier types |
| 210 |
|
| 211 |
Three standard qualifier types are defined in the package +javax.enterprise.inject+. In addition, the built-in qualifier type +@Named+ is defined by the package +javax.inject+. |
| 212 |
|
| 213 |
Every bean has the built-in qualifier +@Any+, even if it does not explicitly declare this qualifier, except for the special +@New+ qualified beans defined in <<new>>. |
| 214 |
|
| 215 |
If a bean does not explicitly declare a qualifier other than +@Named+, the bean has exactly one additional qualifier, of type +@Default+. This is called the _default qualifier_. |
| 216 |
|
| 217 |
The following declarations are equivalent: |
| 218 |
|
| 219 |
[source, java] |
| 220 |
---- |
| 221 |
@Default |
| 222 |
public class Order { ... } |
| 223 |
---- |
| 224 |
|
| 225 |
[source, java] |
| 226 |
---- |
| 227 |
public class Order { ... } |
| 228 |
---- |
| 229 |
|
| 230 |
Both declarations result in a bean with two qualifiers: +@Any+ and +@Default+. |
| 231 |
|
| 232 |
The following declaration results in a bean with three qualifiers: +@Any+, +@Default+ and +@Named("ord")+. |
| 233 |
|
| 234 |
[source, java] |
| 235 |
---- |
| 236 |
@Named("ord") |
| 237 |
public class Order { ... } |
| 238 |
---- |
| 239 |
|
| 240 |
The default qualifier is also assumed for any injection point that does not explicitly declare a qualifier, as defined in <<injection_point_default_qualifier>>. The following declarations, in which the use of the +@Inject+ annotation identifies the constructor parameter as an injection point, are equivalent: |
| 241 |
|
| 242 |
[source, java] |
| 243 |
---- |
| 244 |
public class Order { |
| 245 |
@Inject |
| 246 |
public Order(@Default OrderProcessor processor) { ... } |
| 247 |
} |
| 248 |
---- |
| 249 |
|
| 250 |
[source, java] |
| 251 |
---- |
| 252 |
public class Order { |
| 253 |
@Inject |
| 254 |
public Order(OrderProcessor processor) { ... } |
| 255 |
} |
| 256 |
---- |
| 257 |
|
| 258 |
[[defining_qualifier_types]] |
| 259 |
|
| 260 |
==== Defining new qualifier types |
| 261 |
|
| 262 |
A qualifier type is a Java annotation defined as +@Retention(RUNTIME)+. Typically a qualifier type is defined as +@Target({METHOD, FIELD, PARAMETER, TYPE})+. |
| 263 |
|
| 264 |
A qualifier type may be declared by specifying the [email protected]+ meta-annotation. |
| 265 |
|
| 266 |
[source, java] |
| 267 |
---- |
| 268 |
@Qualifier |
| 269 |
@Retention(RUNTIME) |
| 270 |
@Target({METHOD, FIELD, PARAMETER, TYPE}) |
| 271 |
public @interface Synchronous {} |
| 272 |
---- |
| 273 |
|
| 274 |
[source, java] |
| 275 |
---- |
| 276 |
@Qualifier |
| 277 |
@Retention(RUNTIME) |
| 278 |
@Target({METHOD, FIELD, PARAMETER, TYPE}) |
| 279 |
public @interface Asynchronous {} |
| 280 |
---- |
| 281 |
|
| 282 |
A qualifier type may define annotation members. |
| 283 |
|
| 284 |
[source, java] |
| 285 |
---- |
| 286 |
@Qualifier |
| 287 |
@Retention(RUNTIME) |
| 288 |
@Target({METHOD, FIELD, PARAMETER, TYPE}) |
| 289 |
public @interface PayBy { |
| 290 |
PaymentMethod value(); |
| 291 |
} |
| 292 |
---- |
| 293 |
|
| 294 |
[[declaring_bean_qualifiers]] |
| 295 |
|
| 296 |
==== Declaring the qualifiers of a bean |
| 297 |
|
| 298 |
The qualifiers of a bean are declared by annotating the bean class or producer method or field with the qualifier types. |
| 299 |
|
| 300 |
[source, java] |
| 301 |
---- |
| 302 |
@LDAP |
| 303 |
class LdapAuthenticator |
| 304 |
implements Authenticator { |
| 305 |
... |
| 306 |
} |
| 307 |
---- |
| 308 |
|
| 309 |
[source, java] |
| 310 |
---- |
| 311 |
public class Shop { |
| 312 |
|
| 313 |
@Produces @All |
| 314 |
public List<Product> getAllProducts() { ... } |
| 315 |
|
| 316 |
@Produces @WishList |
| 317 |
public List<Product> getWishList() { ... } |
| 318 |
|
| 319 |
} |
| 320 |
---- |
| 321 |
|
| 322 |
Any bean may declare multiple qualifier types. |
| 323 |
|
| 324 |
[source, java] |
| 325 |
---- |
| 326 |
@Synchronous @Reliable |
| 327 |
class SynchronousReliablePaymentProcessor |
| 328 |
implements PaymentProcessor { |
| 329 |
... |
| 330 |
} |
| 331 |
---- |
| 332 |
|
| 333 |
[[injected_field_qualifiers]] |
| 334 |
|
| 335 |
==== Specifying qualifiers of an injected field |
| 336 |
|
| 337 |
Qualifier types may be applied to injected fields (see <<injected_fields>>) to determine the bean that is injected, according to the rules of typesafe resolution defined in <<typesafe_resolution>>. |
| 338 |
|
| 339 |
[source, java] |
| 340 |
---- |
| 341 |
@Inject @LDAP Authenticator authenticator; |
| 342 |
---- |
| 343 |
|
| 344 |
A bean may only be injected to an injection point if it has all the qualifiers of the injection point. |
| 345 |
|
| 346 |
[source, java] |
| 347 |
---- |
| 348 |
@Inject @Synchronous @Reliable PaymentProcessor paymentProcessor; |
| 349 |
---- |
| 350 |
|
| 351 |
[source, java] |
| 352 |
---- |
| 353 |
@Inject @All List<Product> catalog; |
| 354 |
---- |
| 355 |
|
| 356 |
[source, java] |
| 357 |
---- |
| 358 |
@Inject @WishList List<Product> wishList; |
| 359 |
---- |
| 360 |
|
| 361 |
[[method_constructor_parameter_qualifiers]] |
| 362 |
|
| 363 |
==== Specifying qualifiers of a method or constructor parameter |
| 364 |
|
| 365 |
Qualifier types may be applied to parameters of producer methods, initializer methods, disposer methods, observer methods or bean constructors (see <<implementation>>) to determine the bean instance that is passed when the method is called by the container. The container uses the rules of typesafe resolution defined in <<typesafe_resolution>> to determine values for these parameters. |
| 366 |
|
| 367 |
For example, when the container encounters the following producer method, an instance of +SynchronousPaymentProcessor+ will be passed to the first parameter and an instance of +AsynchronousPaymentProcessor+ will be passed to the second parameter: |
| 368 |
|
| 369 |
[source, java] |
| 370 |
---- |
| 371 |
@Produces |
| 372 |
PaymentProcessor getPaymentProcessor(@Synchronous PaymentProcessor sync, |
| 373 |
@Asynchronous PaymentProcessor async) { |
| 374 |
return isSynchronous() ? sync : async; |
| 375 |
} |
| 376 |
---- |
| 377 |
|
| 378 |
[[scopes]] |
| 379 |
|
| 380 |
=== Scopes |
| 381 |
|
| 382 |
Java EE components such as servlets, EJBs and JavaBeans do not have a well-defined _scope_. These components are either: |
| 383 |
|
| 384 |
* _singletons_, such as EJB singleton session beans, whose state is shared between all clients, |
| 385 |
* _stateless objects_, such as servlets and stateless session beans, which do not contain client-visible state, or |
| 386 |
* objects that must be explicitly created and destroyed by their client, such as JavaBeans and stateful session beans, whose state is shared by explicit reference passing between clients. |
| 387 |
|
| 388 |
|
| 389 |
Scoped objects, by contrast, exist in a well-defined lifecycle context: |
| 390 |
|
| 391 |
* they may be automatically created when needed and then automatically destroyed when the context in which they were created ends, and |
| 392 |
* their state is automatically shared by clients that execute in the same context. |
| 393 |
|
| 394 |
|
| 395 |
All beans have a scope. The scope of a bean determines the lifecycle of its instances, and which instances of the bean are visible to instances of other beans, as defined in <<contexts>>. A scope type is represented by an annotation type. |
| 396 |
|
| 397 |
For example, an object that represents the current user is represented by a session scoped object: |
| 398 |
|
| 399 |
[source, java] |
| 400 |
---- |
| 401 |
@Produces @SessionScoped User getCurrentUser() { ... } |
| 402 |
---- |
| 403 |
|
| 404 |
An object that represents an order is represented by a conversation scoped object: |
| 405 |
|
| 406 |
[source, java] |
| 407 |
---- |
| 408 |
@ConversationScoped |
| 409 |
public class Order { ... } |
| 410 |
---- |
| 411 |
|
| 412 |
A list that contains the results of a search screen might be represented by a request scoped object: |
| 413 |
|
| 414 |
[source, java] |
| 415 |
---- |
| 416 |
@Produces @RequestScoped @Named("orders") |
| 417 |
List<Order> getOrderSearchResults() { ... } |
| 418 |
---- |
| 419 |
|
| 420 |
The set of scope types is extensible. |
| 421 |
|
| 422 |
[[builtin_scopes]] |
| 423 |
|
| 424 |
==== Built-in scope types |
| 425 |
|
| 426 |
There are five standard scope types defined by this specification, all defined in the package +javax.enterprise.context+. |
| 427 |
|
| 428 |
* The container must provide an implementation of the @RequestScoped, @ApplicationScoped and @SessionScoped annotations defined in <<builtin_contexts>> representing the standard scopes defined by the Java Servlets specification. Note that these standard scopes can be extended by third-party extensions as defined in <<context>> |
| 429 |
* The +@ConversationScoped+ annotation represents the conversation scope defined in <<conversation_context>>. |
| 430 |
* Finally, there is a +@Dependent+ pseudo-scope for dependent objects, as defined in <<dependent_context>>. |
| 431 |
|
| 432 |
|
| 433 |
If an interceptor or decorator has any scope other than +@Dependent+, non-portable behavior results. |
| 434 |
|
| 435 |
[[defining_new_scope_type]] |
| 436 |
|
| 437 |
==== Defining new scope types |
| 438 |
|
| 439 |
A scope type is a Java annotation defined as +@Retention(RUNTIME)+. Typically a scope type is defined as +@Target({TYPE, METHOD, FIELD})+. All scope types must also specify the [email protected]+ or [email protected]+ meta-annotation. |
| 440 |
|
| 441 |
A scope type must not have any attributes. If a scope type has attributes non-portable behavior results. |
| 442 |
|
| 443 |
For example, the following annotation declares a "business process scope": |
| 444 |
|
| 445 |
[source, java] |
| 446 |
---- |
| 447 |
@Inherited |
| 448 |
@NormalScope |
| 449 |
@Target({TYPE, METHOD, FIELD}) |
| 450 |
@Retention(RUNTIME) |
| 451 |
public @interface BusinessProcessScoped {} |
| 452 |
---- |
| 453 |
|
| 454 |
Custom scopes are normally defined by portable extensions, which must also provide a _context object_, as defined in <<context>>, that implements the custom scope. |
| 455 |
|
| 456 |
[[declaring_bean_scope]] |
| 457 |
|
| 458 |
==== Declaring the bean scope |
| 459 |
|
| 460 |
The scope of a bean is defined by annotating the bean class or producer method or field with a scope type. |
| 461 |
|
| 462 |
A bean class or producer method or field may specify at most one scope type annotation. If a bean class or producer method or field specifies multiple scope type annotations, the container automatically detects the problem and treats it as a definition error. |
| 463 |
|
| 464 |
[source, java] |
| 465 |
---- |
| 466 |
public class Shop { |
| 467 |
|
| 468 |
@Produces @ApplicationScoped @All |
| 469 |
public List<Product> getAllProducts() { ... } |
| 470 |
|
| 471 |
@Produces @SessionScoped @WishList |
| 472 |
public List<Product> getWishList() { ..... } |
| 473 |
|
| 474 |
} |
| 475 |
---- |
| 476 |
|
| 477 |
Likewise, a bean with the custom business process scope may be declared by annotating it with the +@BusinessProcessScoped+ annotation: |
| 478 |
|
| 479 |
[source, java] |
| 480 |
---- |
| 481 |
@BusinessProcessScoped |
| 482 |
public class Order { ... } |
| 483 |
---- |
| 484 |
|
| 485 |
Alternatively, a scope type may be specified using a stereotype annotation, as defined in <<declaring_stereotypes>>. |
| 486 |
|
| 487 |
[[default_scope]] |
| 488 |
|
| 489 |
==== Default scope |
| 490 |
|
| 491 |
When no scope is explicitly declared by annotating the bean class or producer method or field the scope of a bean is defaulted. |
| 492 |
|
| 493 |
The _default scope_ for a bean which does not explicitly declare a scope depends upon its declared stereotypes: |
| 494 |
|
| 495 |
* If the bean does not declare any stereotype with a declared default scope, the default scope for the bean is +@Dependent+. |
| 496 |
* If all stereotypes declared by the bean that have some declared default scope have the same default scope, then that scope is the default scope for the bean. |
| 497 |
* If there are two different stereotypes declared by the bean that declare different default scopes, then there is no default scope and the bean must explicitly declare a scope. If it does not explicitly declare a scope, the container automatically detects the problem and treats it as a definition error. |
| 498 |
|
| 499 |
|
| 500 |
If a bean explicitly declares a scope, any default scopes declared by stereotypes are ignored. |
| 501 |
|
| 502 |
[[default_bean_discovery]] |
| 503 |
|
| 504 |
=== Default bean discovery mode |
| 505 |
|
| 506 |
The default _bean discovery mode_ for a bean archive is `annotated`, and such a bean archive is said to be an _implicit bean archive_ as defined in <<bean_archive>>. |
| 507 |
|
| 508 |
If the _bean discovery mode_ is `annotated` then: |
| 509 |
|
| 510 |
* bean classes that don't have _bean defining annotation_ (as defined in <<bean_defining_annotations>>) and are not bean classes of sessions beans, are not discovered, and |
| 511 |
* producer methods (as defined in <<producer_method>>) that are not on a session bean and whose bean class does not have a _bean defining annotation_ are not discovered, and |
| 512 |
* producer fields (as defined in <<producer_field>>) that are not on a session bean and whose bean class does not have a _bean defining annotation_ are not discovered, and |
| 513 |
* disposer methods (as defined in <<disposer_method>>) that are not on a session bean and whose bean class does not have a _bean defining annotation_ are not discovered, and |
| 514 |
* observer methods (as defined in <<observes>>) that are not on a session bean and whose bean class does not have a _bean defining annotation_ are not discovered. |
| 515 |
|
| 516 |
[[bean_defining_annotations]] |
| 517 |
|
| 518 |
==== Bean defining annotations |
| 519 |
|
| 520 |
A bean class may have a _bean defining annotation_, allowing it to be placed anywhere in an application, as defined in <<bean_archive>>. A bean class with a _bean defining annotation_ is said to be an _implicit bean_. |
| 521 |
|
| 522 |
The set of bean defining annotations contains: |
| 523 |
|
| 524 |
* `@ApplicationScoped`, `@SessionScoped`, `@ConversationScoped` and `@RequestScoped` annotations, |
| 525 |
* all other normal scope types, |
| 526 |
* `@Interceptor` and `@Decorator` annotations, |
| 527 |
* all stereotype annotations (i.e. annotations annotated with `@Stereotype`), |
| 528 |
* and the `@Dependent` scope annotation. |
| 529 |
|
| 530 |
If one of these annotations is declared on a bean class, then the bean class is said to have a bean defining annotation. For example, this dependent scoped bean has a bean defining annotation: |
| 531 |
|
| 532 |
[source,java] |
| 533 |
---- |
| 534 |
@Dependent |
| 535 |
public class BookShop |
| 536 |
extends Business |
| 537 |
implements Shop<Book> { |
| 538 |
... |
| 539 |
} |
| 540 |
---- |
| 541 |
|
| 542 |
whilst this dependent scoped bean does not have a bean defining annotation: |
| 543 |
|
| 544 |
[source,java] |
| 545 |
---- |
| 546 |
public class CoffeeShop |
| 547 |
extends Business |
| 548 |
implements Shop<Coffee> { |
| 549 |
... |
| 550 |
} |
| 551 |
---- |
| 552 |
|
| 553 |
Note that to ensure compatibility with other JSR-330 implementations, all pseudo-scope annotations except `@Dependent` *are not* bean defining annotations. However, a stereotype annotation including a pseudo-scope annotation *is* a bean defining annotation. |
| 554 |
|
| 555 |
[[names]] |
| 556 |
|
| 557 |
=== Bean names |
| 558 |
|
| 559 |
A bean may have a _bean name_. A bean with a name may be referred to by its name in Unified EL expressions. A valid bean name is a period-separated list of valid EL identifiers. |
| 560 |
|
| 561 |
The following strings are valid bean names: |
| 562 |
|
| 563 |
---- |
| 564 |
com.acme.settings |
| 565 |
---- |
| 566 |
|
| 567 |
---- |
| 568 |
orderManager |
| 569 |
---- |
| 570 |
|
| 571 |
There is no relationship between the bean name of a session bean and the EJB name of the bean. |
| 572 |
|
| 573 |
Subject to the restrictions defined in <<ambig_names>>, multiple beans may share the same bean name. |
| 574 |
|
| 575 |
Bean names allow the direct use of beans in JSP or JSF pages, as defined in <<el>>. For example, a bean with the name +products+ could be used like this: |
| 576 |
|
| 577 |
[source, xml] |
| 578 |
---- |
| 579 |
<h:outputText value="#{products.total}"/> |
| 580 |
---- |
| 581 |
|
| 582 |
Bean names are used by the rules of EL name resolution defined in <<name_resolution>>. |
| 583 |
|
| 584 |
[[declaring_bean_name]] |
| 585 |
|
| 586 |
==== Declaring the bean name |
| 587 |
|
| 588 |
To specify the name of a bean, the qualifier [email protected]+ is applied to the bean class or producer method or field. This bean is named +currentOrder+: |
| 589 |
|
| 590 |
[source, java] |
| 591 |
---- |
| 592 |
@Named("currentOrder") |
| 593 |
public class Order { ... } |
| 594 |
---- |
| 595 |
|
| 596 |
[[default_name]] |
| 597 |
|
| 598 |
==== Default bean names |
| 599 |
|
| 600 |
In the following circumstances, a _default name_ must be assigned by the container: |
| 601 |
|
| 602 |
* A bean class or producer method or field of a bean declares a +@Named+ annotation and no bean name is explicitly specified by the +value+ member. |
| 603 |
* A bean declares a stereotype that declares an empty +@Named+ annotation, and the bean does not explicitly specify a bean name. |
| 604 |
|
| 605 |
|
| 606 |
If a bean class or producer method or field of a bean declares a +@Named+ annotation and no bean name is explicitly specified the value of the +value+ member is defaulted. |
| 607 |
|
| 608 |
The default name for a bean depends upon the kind of the bean. The rules for determining the default name for a bean are defined in <<managed_bean_name>>, <<session_bean_name>>, <<producer_method_name>> and <<producer_field_name>>. |
| 609 |
|
| 610 |
[[beans_with_no_name]] |
| 611 |
|
| 612 |
==== Beans with no name |
| 613 |
|
| 614 |
If +@Named+ is not declared by the bean, nor by its stereotypes, a bean has no name. |
| 615 |
|
| 616 |
If an interceptor or decorator has a name, non-portable behavior results. |
| 617 |
|
| 618 |
[[alternatives]] |
| 619 |
|
| 620 |
=== Alternatives |
| 621 |
|
| 622 |
An _alternative_ is a bean that must be explicitly selected if it should be available for lookup, injection or EL resolution. |
| 623 |
|
| 624 |
[[declaring_alternative]] |
| 625 |
|
| 626 |
==== Declaring an alternative |
| 627 |
|
| 628 |
An alternative may be declared by annotating the bean class or producer method or field with the +@Alternative+ annotation. |
| 629 |
|
| 630 |
[source, java] |
| 631 |
---- |
| 632 |
@Alternative |
| 633 |
public class MockOrder extends Order { ... } |
| 634 |
---- |
| 635 |
|
| 636 |
Alternatively, an alternative may be declared by annotating a bean, producer method or producer field with a stereotype that declares an +@Alternative+ annotation. |
| 637 |
|
| 638 |
If an interceptor or decorator is an alternative, non-portable behavior results. |
| 639 |
|
| 640 |
[[stereotypes]] |
| 641 |
|
| 642 |
=== Stereotypes |
| 643 |
|
| 644 |
In many systems, use of architectural patterns produces a set of recurring bean roles. A _stereotype_ allows a framework developer to identify such a role and declare some common metadata for beans with that role in a central place. |
| 645 |
|
| 646 |
A stereotype encapsulates any combination of: |
| 647 |
|
| 648 |
* a default scope, and |
| 649 |
* a set of interceptor bindings. |
| 650 |
|
| 651 |
|
| 652 |
A stereotype may also specify that: |
| 653 |
|
| 654 |
* all beans with the stereotype have defaulted bean names, or that |
| 655 |
* all beans with the stereotype are alternatives. |
| 656 |
|
| 657 |
|
| 658 |
A bean may declare zero, one or multiple stereotypes. |
| 659 |
|
| 660 |
[[defining_new_stereotype]] |
| 661 |
|
| 662 |
==== Defining new stereotypes |
| 663 |
|
| 664 |
A bean stereotype is a Java annotation defined as +@Retention(RUNTIME)+. Typically a bean stereotype is defined as +@Target({TYPE, METHOD, FIELD})+, +@Target(TYPE)+, +@Target(METHOD)+, +@Target(FIELD)+ or +@Target({METHOD, FIELD})+. |
| 665 |
|
| 666 |
A stereotype may be declared by specifying the [email protected]+ meta-annotation. |
| 667 |
|
| 668 |
[source, java] |
| 669 |
---- |
| 670 |
@Stereotype |
| 671 |
@Target(TYPE) |
| 672 |
@Retention(RUNTIME) |
| 673 |
public @interface Action {} |
| 674 |
---- |
| 675 |
|
| 676 |
[[stereotype_default_scope]] |
| 677 |
|
| 678 |
===== Declaring the default scope for a stereotype |
| 679 |
|
| 680 |
The default scope of a stereotype is defined by annotating the stereotype with a scope type. A stereotype may declare at most one scope. If a stereotype declares more than one scope, the container automatically detects the problem and treats it as a definition error. |
| 681 |
|
| 682 |
For example, the following stereotype might be used to identify action classes in a web application: |
| 683 |
|
| 684 |
[source, java] |
| 685 |
---- |
| 686 |
@RequestScoped |
| 687 |
@Stereotype |
| 688 |
@Target(TYPE) |
| 689 |
@Retention(RUNTIME) |
| 690 |
public @interface Action {} |
| 691 |
---- |
| 692 |
|
| 693 |
Then actions would have scope +@RequestScoped+ unless the scope is explicitly specified by the bean. |
| 694 |
|
| 695 |
[[specify_stereotype_interceptor_bindings]] |
| 696 |
|
| 697 |
===== Specifying interceptor bindings for a stereotype |
| 698 |
|
| 699 |
The interceptor bindings of a stereotype are defined by annotating the stereotype with the interceptor binding types. A stereotype may declare zero, one or multiple interceptor bindings, as defined in <<stereotype_interceptor_bindings>>. |
| 700 |
|
| 701 |
We may specify interceptor bindings that apply to all actions: |
| 702 |
|
| 703 |
[source, java] |
| 704 |
---- |
| 705 |
@RequestScoped |
| 706 |
@Secure |
| 707 |
@Transactional |
| 708 |
@Stereotype |
| 709 |
@Target(TYPE) |
| 710 |
@Retention(RUNTIME) |
| 711 |
public @interface Action {} |
| 712 |
---- |
| 713 |
|
| 714 |
[[named_stereotype]] |
| 715 |
|
| 716 |
===== Declaring a +@Named+ stereotype |
| 717 |
|
| 718 |
A stereotype may declare an empty +@Named+ annotation, which specifies that every bean with the stereotype has a defaulted name when a name is not explicitly specified by the bean. A +@Named+ qualifier declared by a stereotype is not added to the qualifiers of a bean with the stereotype. |
| 719 |
|
| 720 |
If a stereotype declares a non-empty +@Named+ annotation, the container automatically detects the problem and treats it as a definition error. |
| 721 |
|
| 722 |
We may specify that all actions have bean names: |
| 723 |
|
| 724 |
[source, java] |
| 725 |
---- |
| 726 |
@RequestScoped |
| 727 |
@Secure |
| 728 |
@Transactional |
| 729 |
@Named |
| 730 |
@Stereotype |
| 731 |
@Target(TYPE) |
| 732 |
@Retention(RUNTIME) |
| 733 |
public @interface Action {} |
| 734 |
---- |
| 735 |
|
| 736 |
A stereotype should not declare any qualifier annotation other than +@Named+. If a stereotype declares any other qualifier annotation, non-portable behavior results. |
| 737 |
|
| 738 |
A stereotype should not be annotated +@Typed+. If a stereotype is annotated +@Typed+, non-portable behavior results. |
| 739 |
|
| 740 |
[[alternative_stereotype]] |
| 741 |
|
| 742 |
===== Declaring an +@Alternative+ stereotype |
| 743 |
|
| 744 |
A stereotype may declare an +@Alternative+ annotation, which specifies that every bean with the stereotype is an alternative. |
| 745 |
|
| 746 |
We may specify that all mock objects are alternatives: |
| 747 |
|
| 748 |
[source, java] |
| 749 |
---- |
| 750 |
@Alternative |
| 751 |
@Stereotype |
| 752 |
@Target(TYPE) |
| 753 |
@Retention(RUNTIME) |
| 754 |
public @interface Mock {} |
| 755 |
---- |
| 756 |
|
| 757 |
[[stereotypes_with_additional_stereotypes]] |
| 758 |
|
| 759 |
===== Stereotypes with additional stereotypes |
| 760 |
|
| 761 |
A stereotype may declare other stereotypes. |
| 762 |
|
| 763 |
[source, java] |
| 764 |
---- |
| 765 |
@Auditable |
| 766 |
@Action |
| 767 |
@Stereotype |
| 768 |
@Target(TYPE) |
| 769 |
@Retention(RUNTIME) |
| 770 |
public @interface AuditableAction {} |
| 771 |
---- |
| 772 |
|
| 773 |
Stereotype declarations are transitive - a stereotype declared by a second stereotype is inherited by all beans and other stereotypes that declare the second stereotype. |
| 774 |
|
| 775 |
Stereotypes declared +@Target(TYPE)+ may not be applied to stereotypes declared +@Target({TYPE, METHOD, FIELD})+, +@Target(METHOD)+, +@Target(FIELD)+ or +@Target({METHOD, FIELD})+. |
| 776 |
|
| 777 |
[[declaring_stereotypes]] |
| 778 |
|
| 779 |
==== Declaring the stereotypes for a bean |
| 780 |
|
| 781 |
Stereotype annotations may be applied to a bean class or producer method or field. |
| 782 |
|
| 783 |
[source, java] |
| 784 |
---- |
| 785 |
@Action |
| 786 |
public class LoginAction { ... } |
| 787 |
---- |
| 788 |
|
| 789 |
The default scope declared by the stereotype may be overridden by the bean: |
| 790 |
|
| 791 |
[source, java] |
| 792 |
---- |
| 793 |
@Mock @ApplicationScoped @Action |
| 794 |
public class MockLoginAction extends LoginAction { ... } |
| 795 |
---- |
| 796 |
|
| 797 |
Multiple stereotypes may be applied to the same bean: |
| 798 |
|
| 799 |
[source, java] |
| 800 |
---- |
| 801 |
@Dao @Action |
| 802 |
public class LoginAction { ... } |
| 803 |
---- |
| 804 |
|
| 805 |
[[builtin_stereotypes]] |
| 806 |
|
| 807 |
==== Built-in stereotypes |
| 808 |
|
| 809 |
The built-in stereotype [email protected]+ is intended for use with beans that define the _model_ layer of an MVC web application architecture such as JSF: |
| 810 |
|
| 811 |
[source, java] |
| 812 |
---- |
| 813 |
@Named |
| 814 |
@RequestScoped |
| 815 |
@Stereotype |
| 816 |
@Target({TYPE, METHOD, FIELD}) |
| 817 |
@Retention(RUNTIME) |
| 818 |
public @interface Model {} |
| 819 |
---- |
| 820 |
|
| 821 |
In addition, the special-purpose +@Interceptor+ and +@Decorator+ stereotypes are defined in <<declaring_interceptor>> and <<decorator_annotation>>. |
| 822 |
|
| 823 |
[[exceptions]] |
| 824 |
|
| 825 |
=== Problems detected automatically by the container |
| 826 |
|
| 827 |
When the application violates a rule defined by this specification, the container automatically detects the problem. There are three kinds of problem: |
| 828 |
|
| 829 |
* Definition errors - occur when a single bean definition violates the rules of this specification. If a definition error exists, the container must throw a subclass of +javax.enterprise.inject.spi.DefinitionException+. |
| 830 |
* Deployment problems - occur when there are problems resolving dependencies, or inconsistent specialization, in a particular deployment. If a deployment problem occurs, the container must throw a subclass of +javax.enterprise.inject.spi.DeploymentException+. |
| 831 |
* Exceptions - occur at runtime |
| 832 |
|
| 833 |
|
| 834 |
Definition errors are _developer errors_. They may be detected by tooling at development time, and are also detected by the container at initialization time. If a definition error exists in a deployment, initialization will be aborted by the container. |
| 835 |
|
| 836 |
Deployment problems are detected by the container at initialization time. If a deployment problem exists in a deployment, initialization will be aborted by the container. |
| 837 |
|
| 838 |
The container is permitted to define a non-portable mode, for use at development time, in which some definition errors and deployment problems do not cause application initialization to abort. |
| 839 |
|
| 840 |
Exceptions represent problems that may not be detected until they actually occur at runtime. All exceptions defined by this specification are unchecked exceptions. All exceptions defined by this specification may be safely caught and handled by the application. |
| 841 |
|