Contexts and Dependency Injection for the Java EE platform

In the Java EE 6 environment, all component classes supporting injection, as defined by the Java EE 6 platform specification, may inject beans via the dependency injection service.

The Java EE platform specification defines a facility for injecting resources that exist in the Java EE component environment. Resources are identified by string-based names. This specification bolsters that functionality, adding the ability to inject an open-ended set of object types, including, but not limited to, component environment resources, based upon typesafe qualifiers.

EJB defines a programming model for application components that access transactional resources in a multi-user environment. EJB allows concerns such as role-based security, transaction demarcation, concurrency and scalability to be specified declaratively using annotations and XML deployment descriptors and enforced by the EJB container at runtime.

EJB components may be stateful, but are not by nature contextual. References to stateful component instances must be explicitly passed between clients and stateful instances must be explicitly destroyed by the application.

This specification enhances the EJB component model with contextual lifecycle management.

Any session bean instance obtained via the dependency injection service is a contextual instance. It is bound to a lifecycle context and is available to other objects that execute in that context. The container automatically creates the instance when it is needed by a client. When the context ends, the container automatically destroys the instance.

Message-driven and entity beans are by nature non-contextual objects and may not be injected into other objects.

The container performs dependency injection on all session and message-driven bean instances, even those which are not contextual instances.

The Managed Beans specification defines the basic programming model for application components managed by the Java EE container.

As defined by this specification, most Java classes, including all JavaBeans, are managed beans.

This specification defines contextual lifecycle management and dependency injection as generic services applicable to all managed beans.

Any managed bean instance obtained via the dependency injection service is a contextual instance. It is bound to a lifecycle context and is available to other objects that execute in that context. The container automatically creates the instance when it is needed by a client. When the context ends, the container automatically destroys the instance.

The container performs dependency injection on all managed bean instances, even those which are not contextual instances.

The Dependency Injection for Java specification defines a set of annotations for the declaring injected fields, methods and constructors of a bean. The dependency injection service makes use of these annotations.

The Java Interceptors specification defines the basic programming model and semantics for interceptors. This specification enhances that model by providing the ability to associate interceptors with beans using typesafe interceptor bindings.

JavaServer Faces is a web-tier presentation framework that provides a component model for graphical user interface components and an event-driven interaction model that binds user interface components to objects accessible via Unified EL.

This specification allows any bean to be assigned a name. Thus, a JSF application may take advantage of the sophisticated context and dependency injection model defined by this specification.

Bean Validation provides a unified way of declaring and defining constraints on an object model, defines a runtime engine to validate objects and provides method validation.

The Bean Validation specification defines beans for Bean Validation managed objects including Validator and ValidatorFactory. A number of Bean Validation managed instances, including ConstraintValidator s can take advantage of dependency injection. Bean Validation also provides support for method parameter validation on any bean.

The following JSF page defines a login prompt for a web application:

The Unified EL expressions in this page refer to beans named credentials and login.

The Credentials bean has a lifecycle that is bound to the JSF request:

The @Model annotation defined in [builtin_stereotypes] is a stereotype that identifies the Credentials bean as a model object in an MVC architecture.

The Login bean has a lifecycle that is bound to the HTTP session:

The @SessionScoped annotation defined in [builtin_scopes] is a scope type that specifies the lifecycle of instances of Login. Managed beans with this scope must be serializable.

The @Inject annotation defined by the Dependency Injection for Java specification identifies an injected field which is initialized by the container when the bean is instantiated, or an initializer method which is called by the container after the bean is instantiated, with injected parameters.

The @Users annotation is a qualifier type defined by the application:

The @LoggedIn annotation is another qualifier type defined by the application:

The @Produces annotation defined in [declaring_producer_method] identifies the method getCurrentUser() as a producer method, which will be called whenever another bean in the system needs the currently logged-in user, for example, whenever the user attribute of the DocumentEditor class is injected by the container:

The @Documents annotation is another application-defined qualifier type. The use of distinct qualifier types enables the container to distinguish which JPA persistence unit is required.

When the login form is submitted, JSF assigns the entered username and password to an instance of the Credentials bean that is automatically instantiated by the container. Next, JSF calls the login() method of an instance of Login that is automatically instantiated by the container. This instance continues to exist for and be available to other requests in the same HTTP session, and provides the User object representing the current user to any other bean that requires it (for example, DocumentEditor). If the producer method is called before the login() method initializes the user object, it throws a NotLoggedInException.

Alternatively, we could write our Login bean to take advantage of the functionality defined by EJB:

The EJB @Stateful annotation specifies that this bean is an EJB stateful session bean. The EJB @TransactionAttribute and @RolesAllowed annotations declare the EJB transaction demarcation and security attributes of the annotated methods.

In the previous examples, we injected container-managed persistence contexts using qualifier types. We need to tell the container what persistence context is being referred to by which qualifier type. We can declare references to persistence contexts and other resources in the Java EE component environment in Java code.

The JPA @PersistenceContext and @PersistenceUnit annotations identify the JPA persistence unit.

Beans may raise events. For example, our Login class could raise events when a user logs in or out.

The method fire() of the built-in bean of type Event defined in [event] allows the application to fire events. Events consist of an event object - in this case the User - and event qualifiers. Event qualifier - such as @LoggedIn and @LoggedOut - allow event consumers to specify which events of a certain type they are interested in.

Other beans may observe these events and use them to synchronize their internal state, with no coupling to the bean producing the events:

The @Produces annotation applied to a field identifies the field as a producer field, as defined in [producer_field], a kind of shortcut version of a producer method. This producer field allows the permissions of the current user to be injected to an injection point of type Set<Permission>.

The @Observes annotation defined in [observes] identifies the method with the annotated parameter as an observer method that is called by the container whenever an event matching the type and qualifiers of the annotated parameter is fired.

It is possible to implement generic beans that introspect the injection point to which they belong. This makes it possible to implement injection for Logger s, for example.

The InjectionPoint interface defined in [injection_point], provides metadata about the injection point to the object being injected into it.

Then this class will have a Logger named "Permissions" injected:

Interceptors allow common, cross-cutting concerns to be applied to beans via custom annotations. Interceptor types may be individually enabled or disabled at deployment time.

The AuthorizationInterceptor class defines a custom authorization check:

The @Interceptor annotation, defined in [declaring_interceptor], identifies the AuthorizationInterceptor class as an interceptor. The @Secure annotation is a custom interceptor binding type, as defined in [interceptor_bindings].

The @Secure annotation is used to apply the interceptor to a bean:

When the save() method is invoked, the authorize() method of the interceptor will be called. The invocation will proceed to the DocumentEditor class only if the authorization check is successful.

Decorators are similar to interceptors, but apply only to beans of a particular Java interface. Like interceptors, decorators may be easily enabled or disabled at deployment time. Unlike interceptors, decorators are aware of the semantics of the intercepted method.

For example, the DataAccess interface might be implemented by many beans:

The DataAccessAuthorizationDecorator class defines the authorization checks:

The @Decorator annotation defined in [decorator_annotation] identifies the DataAccessAuthorizationDecorator class as a decorator. The @Delegate annotation defined in [delegate_attribute] identifies the delegate, which the decorator uses to delegate method calls to the container. The decorator applies to any bean that implements DataAccess.

The decorator intercepts invocations just like an interceptor. However, unlike an interceptor, the decorator contains functionality that is specific to the semantics of the method being called.

Decorators may be declared abstract, relieving the developer of the responsibility of implementing all methods of the decorated interface. If a decorator does not implement a method of a decorated interface, the decorator will simply not be called when that method is invoked upon the decorated bean.

Almost any Java type may be a bean type of a bean:

However, some Java types are not legal bean types :

Note that certain additional restrictions are specified in [unproxyable] for beans with a normal scope, as defined in [normal_scope].

The bean types of a bean may be restricted by annotating the bean class or producer method or field with the annotation @javax.enterprise.inject.Typed.

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.

In the example, the bean has a two bean types: Shop<Book> and Object.

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.

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:

Then the following typecast is legal:

However, the following typecast is not legal and might result in an exception at runtime:

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.

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

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.

The following declarations are equivalent:

Both declarations result in a bean with two qualifiers: @Any and @Default.

The following declaration results in a bean with three qualifiers: @Any, @Default and @Named("ord").

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:

A qualifier type is a Java annotation defined as @Retention(RUNTIME). Typically a qualifier type is defined as @Target({METHOD, FIELD, PARAMETER, TYPE}).

A qualifier type may be declared by specifying the @javax.inject.Qualifier meta-annotation.

A qualifier type may define annotation members.

The qualifiers of a bean are declared by annotating the bean class or producer method or field with the qualifier types.

Any bean may declare multiple qualifier types.

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

A bean may only be injected to an injection point if it has all the qualifiers of the injection point.

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.

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:

There are five standard scope types defined by this specification, all defined in the package javax.enterprise.context.

If an interceptor or decorator has any scope other than @Dependent, non-portable behavior results.

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 @javax.inject.Scope or @javax.enterprise.context.NormalScope meta-annotation.

A scope type must not have any attributes. If a scope type has attributes non-portable behavior results.

For example, the following annotation declares a "business process scope":

Custom scopes are normally defined by portable extensions, which must also provide a context object, as defined in [context], that implements the custom scope.

The scope of a bean is defined by annotating the bean class or producer method or field with a scope type.

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.

Likewise, a bean with the custom business process scope may be declared by annotating it with the @BusinessProcessScoped annotation:

Alternatively, a scope type may be specified using a stereotype annotation, as defined in [declaring_stereotypes].

When no scope is explicitly declared by annotating the bean class or producer method or field the scope of a bean is defaulted.

The default scope for a bean which does not explicitly declare a scope depends upon its declared stereotypes:

If a bean explicitly declares a scope, any default scopes declared by stereotypes are ignored.

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.

The set of bean defining annotations contains:

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:

whilst this dependent scoped bean does not have a bean defining annotation:

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.

To specify the name of a bean, the qualifier @javax.inject.Named is applied to the bean class or producer method or field. This bean is named currentOrder:

In the following circumstances, a default name must be assigned by the container:

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.

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

If @Named is not declared by the bean, nor by its stereotypes, a bean has no name.

If an interceptor or decorator has a name, non-portable behavior results.

An alternative may be declared by annotating the bean class or producer method or field with the @Alternative annotation.

Alternatively, an alternative may be declared by annotating a bean, producer method or producer field with a stereotype that declares an @Alternative annotation.

If an interceptor or decorator is an alternative, non-portable behavior results.

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}).

A stereotype may be declared by specifying the @javax.enterprise.inject.Stereotype meta-annotation.

Stereotype annotations may be applied to a bean class or producer method or field.

The default scope declared by the stereotype may be overridden by the bean:

Multiple stereotypes may be applied to the same bean:

The built-in stereotype @javax.enterprise.inject.Model is intended for use with beans that define the model layer of an MVC web application architecture such as JSF:

In addition, the special-purpose @Interceptor and @Decorator stereotypes are defined in [declaring_interceptor] and [decorator_annotation].

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:

All Java classes that meet these conditions are managed beans and thus no special declaration is required to define a managed bean.

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 Extension Mechanism Architecture.

The unrestricted set of bean types for a managed bean contains the bean class, every superclass and all interfaces it implements directly or indirectly.

Note the additional restrictions upon bean types of beans with normal scopes defined in [unproxyable].

A managed bean with a constructor that takes no parameters does not require any special annotations. The following classes are beans:

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.

A bean class may specify a scope, bean name, stereotypes and/or qualifiers:

A managed bean may extend another managed bean:

The second bean is a "mock object" that overrides the implementation of LoginAction when running in an embedded EJB Lite based integration testing environment.

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

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.

For example, MockLoginAction directly specializes LoginAction:

The default name for a managed bean is the unqualified class name of the bean class, after converting the first character to lower case.

For example, if the bean class is named ProductList, the default bean name is productList.

If a session bean is a stateful session bean:

The session bean is not required to have an EJB remove method in order for the container to destroy it.

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.

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

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.

Remote interfaces are not included in the set of bean types.

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:

A bean class may also specify a scope, bean name, stereotypes and/or qualifiers:

A session bean class may extend another bean class:

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

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.

For example, MockLoginActionBean directly specializes LoginActionBean:

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.

For example, if the bean class is named ProductList, the default bean name is productList.

The bean types of a producer method depend upon the method return type:

Note the additional restrictions upon bean types of beans with normal scopes defined in [unproxyable].

A producer method may be declared by annotating a method with the @javax.enterprise.inject.Produces annotation.

A producer method may also specify scope, bean name, stereotypes and/or qualifiers.

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.

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.

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.

A producer method may have any number of parameters. All producer method parameters are injection points.

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

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.

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.

For example, this producer method is named products:

This producer method is named paymentProcessor:

The bean types of a producer field depend upon the field type:

Note the additional restrictions upon bean types of beans with normal scopes defined in [unproxyable].

A producer field may be declared by annotating a field with the @javax.enterprise.inject.Produces annotation.

A producer field may also specify scope, bean name, stereotypes and/or qualifiers.

If a producer field is annotated @Inject, the container automatically detects the problem and treats it as a definition error.

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.

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.

The default name for a producer field is the field name.

For example, this producer field is named products:

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.

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.

A disposer method may be declared by annotating a parameter @javax.enterprise.inject.Disposes. That parameter is the disposed parameter. Qualifiers may be declared by annotating the disposed parameter:

If a method has more than one parameter annotated @Disposes, the container automatically detects the problem and treats it as a definition error.

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.

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.

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.

In addition to the disposed parameter, a disposer method may declare additional parameters, which may also specify qualifiers. These additional parameters are injection points.

A disposer method is bound to a producer method or producer field if:

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.

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.

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.

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.

The bean type and qualifiers of the resource are determined by the producer field declaration.

If the producer field declaration specifies a bean name, the container automatically detects the problem and treats it as a definition error.

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.

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

The bean constructor may be identified by annotating the constructor @Inject.

If a bean class does not explicitly declare a constructor using @Inject, the constructor that accepts no parameters is the bean constructor.

If a bean class has more than one constructor annotated @Inject, the container automatically detects the problem and treats it as a definition error.

If a bean constructor has a parameter annotated @Disposes, or @Observes, the container automatically detects the problem and treats it as a definition error.

A bean constructor may have any number of parameters. All parameters of a bean constructor are injection points.

An injected field may be declared by annotating the field @javax.inject.Inject.

If an injected field is annotated @Produces, the container automatically detects the problem and treats it as a definition error.

An initializer method may be declared by annotating the method @javax.inject.Inject.

If a generic method of a bean is annotated @Inject, the container automatically detects the problem and treats it as a definition error.

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.

An initializer method may have any number of parameters. All initializer method parameters are injection points.

The annotation @javax.enterprise.inject.Specializes is used to indicate that one bean directly specializes another bean, as defined in [specialize_managed_bean], [specialize_session_bean] and [specialize_producer_method].

Formally, a bean X is said to specialize another bean Y if either:

Then X will inherit the qualifiers and bean name of Y:

Furthermore, X must have all the bean types of Y. If X does not have some bean type of Y, the container automatically detects the problem and treats it as a definition error.

If Y has a bean name and X declares a bean name explicitly the container automatically detects the problem and treats it as a definition error.

For example, the following bean would have the inherited qualifiers @Default and @Asynchronous:

If AsynchronousService declared a bean name:

Then the bean name would also automatically be inherited by MockAsynchronousService.

If an interceptor or decorator is annotated @Specializes, non-portable behavior results.

This specification defines two methods of selecting alternatives. From Contexts and Dependency Injection 1.1 onwards the @Priority annotation allows an alternative to be selected for an entire application. Contexts and Dependency Injection 1.0 allowed only for an alternative to be selected for a bean archive.

A bean is said to be enabled if:

Otherwise, the bean is said to be disabled.

Note that [new] defines a special rule that determines whether a @New qualified bean is enabled or disabled. This rule applies as only to @New qualified beans, as an exception to the normal rule defined here.

Suppose an enabled bean X specializes a second bean Y. If there is another enabled bean that specializes Y we say that inconsistent specialization exists. The container automatically detects inconsistent specialization and treats it as a deployment problem.

A bean is available for injection in a certain module if:

For a custom implementation of the Bean interface defined in [bean], the container calls getBeanClass() to determine the bean class of the bean and InjectionPoint.getMember() and then Member.getDeclaringClass() to determine the class that declares an injection point.

The container considers bean type and qualifiers when resolving a bean to be injected to an injection point. The type and qualifiers of the injection point are called the required type and required qualifiers.

A bean is assignable to a given injection point if:

A bean is eligible for injection to a certain injection point if:

For a custom implementation of the Bean interface defined in [bean], the container calls getTypes() and getQualifiers() to determine the bean types and qualifiers.

An unsatisfied dependency exists at an injection point when no bean is eligible for injection to the injection point. An ambiguous dependency exists at an injection point when multiple beans are eligible for injection to the injection point.

Note that an unsatisfied or ambiguous dependency cannot exist for a decorator delegate injection point, defined in [delegate_attribute].

When an ambiguous dependency exists, the container attempts to resolve the ambiguity. The container eliminates all eligible beans that are not alternatives, except for producer methods and fields of beans that are alternatives. If:

The container must validate all injection points of all enabled beans, all observer methods, all disposer methods and all other Java EE component classes supporting injection when the application is initialized to ensure that there are no unsatisfied or unresolvable ambiguous dependencies. If an unsatisfied or unresolvable ambiguous dependency exists, the container automatically detects the problem and treats it as a deployment problem.

For a custom implementation of the Bean interface defined in [bean], the container calls getInjectionPoints() to determine the set of injection points.

Any legal bean type, as defined in [legal_bean_types] may be the required type of an injection point. Furthermore, the required type of an injection point may contain a wildcard type parameter. However, a type variable is not a legal injection point type.

If an injection point type is a type variable, the container automatically detects the problem and treats it as a definition error.

A parameterized bean type is considered assignable to a raw required type if the raw types are identical and all type parameters of the bean type are either unbounded type variables or java.lang.Object.

A parameterized bean type is considered assignable to a parameterized required type if they have identical raw type and for each parameter:

For example, Dao is eligible for injection to any injection point of type @Default Dao<Order>, @Default Dao<User>, @Default Dao<?>, @Default Dao<? extends Persistent> or @Default Dao<X extends Persistent> where X is a type variable.

Furthermore, UserDao is eligible for injection to any injection point of type @Default Dao<User>, @Default Dao<?>, @Default Dao<? extends Persistent> or @Default Dao<? extends User>.

A raw bean type is considered assignable to a parameterized required type if the raw types are identical and all type parameters of the required type are either unbounded type variables or java.lang.Object.

Note that a special set of rules, defined in [delegate_assignable_parameters], apply if and only if the injection point is a decorator delegate injection point.

For the purposes of typesafe resolution and dependency injection, primitive types and their corresponding wrapper types in the package java.lang are considered identical and assignable. If necessary, the container performs boxing or unboxing when it injects a value to a field or parameter of primitive or wrapper type.

If an injection point of primitive type resolves to a producer method or producer field that returns a null value at runtime, the container must inject the primitive type’s default value as defined by the Java Language Specification.

Qualifier types may have annotation members.

Then only ChequePaymentProcessor is a candidate for injection to the following attribute:

On the other hand, only CreditCardPaymentProcessor is a candidate for injection to this attribute:

The container calls the equals() method of the annotation member value to compare values.

An annotation member may be excluded from consideration using the @Nonbinding annotation.

Array-valued or annotation-valued members of a qualifier type should be annotated @Nonbinding in a portable application. If an array-valued or annotation-valued member of a qualifier type is not annotated @Nonbinding, non-portable behavior results.

A bean class or producer method or field may declare multiple qualifiers.

Then ChequePaymentProcessor would be considered a candidate for injection into any of the following attributes:

A bean must declare all of the qualifiers that are specified at the injection point to be considered a candidate for injection.

An ambiguous EL name exists in an EL expression when an EL name resolves to multiple beans. When an ambiguous EL name exists, the container attempts to resolve the ambiguity. The container eliminates all eligible beans that are not alternatives selected for the bean archive or selected for the application, except for producer methods and fields of beans that are alternatives. If:

All unresolvable ambiguous EL names are detected by the container when the application is initialized. Suppose two beans are both available for injection in a certain war, and either:

the container automatically detects the problem and treats it as a deployment problem.

Every time a method of the bean is invoked upon a client proxy, the client proxy must:

If the scope is not active, as specified in [active_context], the client proxy rethrows the ContextNotActiveException or IllegalStateException.

The behavior of all methods declared by java.lang.Object, except for toString(), is undefined for a client proxy. Portable applications should not invoke any method declared by java.lang.Object, except for toString(), on a client proxy.

When the container instantiates a managed bean or session bean with a constructor annotated @Inject, the container calls this constructor, passing an injectable reference to each parameter. If there is no constructor annotated @Inject, the container calls the constructor with no parameters.

When the container creates a new instance of a managed bean, session bean, or of any other Java EE component class supporting injection the container must:

The container must ensure that:

When the container destroys an instance of a bean or of any Java EE component class supporting injection, the container destroys all dependent objects, as defined in [dependent_destruction], after the @PreDestroy callback completes and after the servlet destroy() method is called.

When the container calls a producer or disposer method, the behavior depends upon whether the method is static or non-static:

The container passes an injectable reference to each injected method parameter. The container is also responsible for destroying dependent objects created during this invocation, as defined in [dependent_destruction].

When the container accesses the value of a producer field, the value depends upon whether the field is static or non-static:

When the container calls an observer method (defined in [observer_methods]), the behavior depends upon whether the method is static or non-static:

The container must pass the event object to the event parameter and an injectable instance to each injected method parameter. The container is also responsible for destroying dependent objects created during this invocation, as defined in [dependent_destruction].

The interface javax.enterprise.inject.spi.InjectionPoint provides access to metadata about an injection point. An instance of InjectionPoint may represent:

Occasionally, a component with scope @Dependent needs to access metadata relating to the object into which it is injected. For example, the following producer method creates injectable Logger s. The log category of a Logger depends upon the class of the object into which it is injected:

The container must provide a bean with scope @Dependent, bean type InjectionPoint and qualifier @Default, allowing dependent objects, as defined in [dependent_objects], to obtain information about the injection point to which they belong. The built-in implementation must be a passivation capable dependency, as defined in [passivation_capable_dependency].

If a bean that declares any scope other than @Dependent has an injection point of type InjectionPoint and qualifier @Default, the container automatically detects the problem and treats it as a definition error.

If a disposer method has an injection point of type InjectionPoint and qualifier Default, the container automatically detects the problem and treats it as a definition error.

If a Java EE component class supporting injection that is not a bean has an injection point of type InjectionPoint and qualifier @Default, the container automatically detects the problem and treats it as a definition error.

The interfaces Bean, Interceptor and Decorator provide metadata about a bean.

The container must provide beans allowing a bean instance to obtain a Bean, Interceptor or Decorator instance containing its metadata:

Additionally, the container must provide beans allowing interceptors and decorators to obtain information about the beans they intercept and decorate:

These beans are passivation capable dependencies, as defined in [passivation_capable_dependency].

If an Interceptor instance is injected into a bean instance other than an interceptor instance, the container automatically detects the problem and treats it as a definition error.

If a Decorator instance is injected into a bean instance other than a decorator instance, the container automatically detects the problem and treats it as a definition error.

If a Bean instance with qualifier @Intercepted is injected into a bean instance other than an interceptor instance, the container automatically detects the problem and treats it as a definition error.

If a Bean instance with qualifier @Decorated is injected into a bean instance other than a decorator instance, the container automatically detects the problem and treats it as a definition error.

The injection of bean metadata is restricted. If:

Otherwise, the container automatically detects the problem and treats it as a definition error.

The Instance interface provides a method for obtaining instances of beans with a specified combination of required type and qualifiers, and inherits the ability to iterate beans with that combination of required type and qualifiers from java.lang.Iterable:

For an injected Instance:

For example, this injected Instance has required type PaymentProcessor and required qualifier @Any:

The select() method returns a child Instance for a given required type and additional required qualifiers. If no required type is given, the required type is the same as the parent.

For example, this child Instance has required type AsynchronousPaymentProcessor and additional required qualifier @Asynchronous:

If an injection point of raw type Instance is defined, the container automatically detects the problem and treats it as a definition error.

If two instances of the same qualifier type are passed to select(), an IllegalArgumentException is thrown.

If an instance of an annotation that is not a qualifier type is passed to select(), an IllegalArgumentException is thrown.

The get() method must:

The iterator() method must:

The method isUnsatisfied() returns true if there is no bean that has the required type and qualifiers and is eligible for injection into the class into which the parent Instance was injected, or false otherwise.

The method isAmbiguous() returns true if there is more than one bean that has the required type and qualifiers and is eligible for injection into the class into which the parent Instance was injected, or false otherwise.

The method destroy() instructs the container to destroy the instance. The bean instance passed to destroy() should be a dependent scoped bean instance, or a client proxy for a normal scoped bean. Applications are encouraged to always call destroy() when they no longer require an instance obtained from Instance. All built-in normal scoped contexts support destroying bean instances. An UnsupportedOperationException is thrown if the active context object for the scope type of the bean does not support destroying bean instances.

The container must provide a built-in bean with:

The built-in implementation must be a passivation capable dependency, as defined in [passivation_capable_dependency].

javax.enterprise.util.AnnotationLiteral makes it easier to specify qualifiers when calling select():

javax.enterprise.util.TypeLiteral makes it easier to specify a parameterized type with actual type parameters when calling select():

The interface javax.enterprise.context.spi.CreationalContext provides operations that are used by the Contextual implementation during instance creation and destruction.

The implementation of Contextual is not required to call push(). However, for certain bean scopes, invocation of push() between instantiation and injection helps the container minimize the use of client proxy objects (which would otherwise be required to allow circular dependencies).

If Contextual.create() calls push(), it must also return the instance passed to push().

Contextual.create() should use the given CreationalContext when obtaining contextual references to inject, as defined in [contextual_reference], in order to ensure that any dependent objects are associated with the contextual instance that is being created.

Contextual.destroy() should call release() to allow the container to destroy dependent objects of the contextual instance.

Many instances of beans with scope @Dependent belong to some other bean or Java EE component class instance and are called dependent objects.

Dependent objects of a contextual instance are destroyed when Contextual.destroy() calls CreationalContext.release(), as defined in [creational_context].

Additionally, the container must ensure that:

Finally, the container is permitted to destroy any @Dependent scoped contextual instance at any time if the instance is no longer referenced by the application (excluding weak, soft and phantom references).

Suppose a Unified EL expression in a JSF or JSP page refers to a bean with scope @Dependent by its bean name. Each time the EL expression is evaluated:

Portable extensions that integrate with the container via Unified EL should also ensure that these rules are enforced.

From time to time, the container must obtain an active context object for a certain scope type. The container must search for an active instance of Context associated with the scope type.

If there is exactly one active instance of Context associated with the scope type, we say that the scope is active.

From time to time, the container must obtain a contextual instance of a bean. The container must:

From time to time, the container attempts to obtain a contextual instance of a bean that already exists, without creating a new contextual instance. The container must determine if the scope of the bean is active and if it is:

If the scope is not active, or if Context.get() returns a null value, there is no contextual instance that already exists.

A contextual instance of any of the built-in kinds of bean defined in [implementation] is considered an internal container construct, and it is therefore not strictly required that a contextual instance of a built-in kind of bean directly implement the bean types of the bean. However, in this case, the container is required to transform its internal representation to an object that does implement the bean types expected by the application before injecting or returning a contextual instance to the application.

For a custom implementation of the Bean interface defined in [bean], the container calls getScope() to determine the bean scope.

From time to time, the container must obtain a contextual reference for a bean and a given bean type of the bean. A contextual reference implements the given bean type and all bean types of the bean which are Java interfaces. A contextual reference is not, in general, required to implement all concrete bean types of the bean.

Contextual references must be obtained with a given CreationalContext, allowing any instance of scope @Dependent that is created to be later destroyed.

The container must ensure that every injection point of type InjectionPoint and qualifier @Default of any dependent object instantiated during this process receives:

A contextual reference for a bean is valid only for a certain period of time. The application should not invoke a method of an invalid reference.

The validity of a contextual reference for a bean depends upon whether the scope of the bean is a normal scope or a pseudo-scope.

From time to time, the container must obtain an injectable reference for an injection point. The container must:

For certain combinations of scopes, the container is permitted to optimize the above procedure:

However, in performing these optimizations, the container must respect the rules of injectable reference validity.

Injectable references to a bean must respect the rules of contextual reference validity, with the following exceptions:

The application should not invoke a method of an invalid injected reference. If the application invokes a method of an invalid injected reference, the behavior is undefined.

A bean is called passivation capable if the container is able to temporarily transfer the state of any idle instance to secondary storage.

A custom implementation of Bean is passivation capable if it implements the interface PassivationCapable. An implementation of Contextual that is not a bean is passivation capable if it implements both PassivationCapable and Serializable.

The getId() method must return a value that uniquely identifies the instance of Bean or Contextual. It is recommended that the string contain the package name of the class that implements Bean or Contextual.

We call an injection point of a bean passivation capable if the injection point is:

A bean is called a passivation capable dependency if any contextual reference for that bean is preserved when the object holding the reference is passivated and then activated.

The container must guarantee that:

A custom implementation of Bean is a passivation capable dependency if it implements PassivationCapable.

A passivating scope requires that:

Passivating scopes must be explicitly declared @NormalScope(passivating=true).

For example, the built-in session and conversation scopes defined in [builtin_contexts] are passivating scopes. No other built-in scopes are passivating scopes.

For every bean which declares a passivating scope, the container must validate that the bean truly is passivation capable and that, in addition, its dependencies are passivation capable.

If a managed bean which declares a passivating scope, a stateful session bean which declares a passivating scope, or a built-in bean:

then the container automatically detects the problem and treats it as a deployment problem.

If a producer method declares a passivating scope and:

then the container automatically detects the problem and treats it as a deployment problem.

If a producer method declares a passivating scope and doesn’t only return Serializable types at runtime, then the container must throw an IllegalProductException.

If a producer field declares a passivating scope and has a type that is declared final and does not implement or extend Serializable then the container automatically detects the problem and treats it as a deployment problem.

If a producer field declares a passivating scope and doesn’t only contain Serializable values at runtime then the container must throw an IllegalProductException.

If a producer method or field of scope @Dependent returns an unserializable object for injection into an injection point that requires a passivation capable dependency, the container must throw an IllegalProductException

For a custom implementation of Bean, the container calls getInjectionPoints() to determine the injection points, and InjectionPoint.isTransient() to determine whether the injection point is a transient field.

If a managed bean or a stateful session bean which declares a passivating scope type, has a decorator or interceptor which is not a passivation capable dependency, the container automatically detects the problem and treats it as a deployment problem.

The request context is provided by a built-in context object for the built-in scope type @RequestScoped. The request scope is active:

The request context is destroyed:

An event with qualifier @Initialized(RequestScoped.class) is fired when the request context is initialized and an event with qualifier @Destroyed(RequestScoped.class) when the request context is destroyed. The event payload is:

The session context is provided by a built-in context object for the built-in passivating scope type @SessionScoped. The session scope is active:

The session context is shared between all servlet requests that occur in the same HTTP session. The session context is destroyed when the HTTPSession times out, after all HttpSessionListener s have been called, and at the very end of any request in which invalidate() was called, after all filters and ServletRequestListener s have been called.

An event with the HttpSession as payload and with qualifier @Initialized(SessionScoped.class) is fired when the session context is initialized and an event with qualifier @Destroyed(SessionScoped.class) when the session context is destroyed.

The application context is provided by a built-in context object for the built-in scope type @ApplicationScoped. The application scope is active:

The application context is shared between all servlet requests, web service invocations, EJB remote method invocations, EJB asynchronous method invocations, EJB timeouts and message deliveries to message-driven beans that execute within the same application. The application context is destroyed when the application is shut down.

An event with qualifier @Initialized(ApplicationScoped.class) is fired when the application context is initialized and an event with qualifier @Destroyed(ApplicationScoped.class) is fired when the application is destroyed. The event payload is:

The conversation context is provided by a built-in context object for the built-in passivating scope type @ConversationScoped. The conversation scope is active during all Servlet requests.

An event with qualifier @Initialized(ConversationScoped.class) is fired when the conversation context is initialized and an event with qualifier @Destroyed(ConversationScoped.class) is fired when the conversation is destroyed. The event payload is:

The conversation context provides access to state associated with a particular conversation. Every Servlet request has an associated conversation. This association is managed automatically by the container according to the following rules:

Any conversation is in one of two states: transient or long-running.

All long-running conversations have a string-valued unique identifier, which may be set by the application when the conversation is marked long-running, or generated by the container.

If the conversation associated with the current Servlet request is in the transient state at the end of a Servlet request, it is destroyed, and the conversation context is also destroyed.

If the conversation associated with the current Servlet request is in the long-running state at the end of a Servlet request, it is not destroyed. The long-running conversation associated with a request may be propagated to any Servlet request via use of a request parameter named cid containing the unique identifier of the conversation. In this case, the application must manage this request parameter.

If the current Servlet request is a JSF request, and the conversation is in long-running state, it is propagated according to the following rules:

When no conversation is propagated to a Servlet request, or if a request parameter named conversationPropagation has the value none the request is associated with a new transient conversation.

All long-running conversations are scoped to a particular HTTP servlet session and may not cross session boundaries.

In the following cases, a propagated long-running conversation cannot be restored and reassociated with the request:

The conversation timeout, which may be specified by calling Conversation.setTimeout() is a hint to the container that a conversation should not be destroyed if it has been active within the last given interval in milliseconds.

If the propagated conversation cannot be restored, the container must associate the request with a new transient conversation and throw an exception of type javax.enterprise.context.NonexistentConversationException.

The container ensures that a long-running conversation may be associated with at most one request at a time, by blocking or rejecting concurrent requests. If the container rejects a request, it must associate the request with a new transient conversation and throw an exception of type javax.enterprise.context.BusyConversationException.

The container provides a built-in bean with bean type Conversation, scope @RequestScoped, and qualifier @Default, named javax.enterprise.context.conversation.