Debian Codegraph @

spec/src/main/doc/definition.asciidoc

raw
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