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 Built-in 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 Built-in scope types 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 a 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 The Event interface 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 fields, 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 Declaring an observer method 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 metadata, 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 the interceptor bindings of an interceptor, identifies the AuthorizationInterceptor class as an interceptor. The @Secure annotation is a custom interceptor binding type, as defined in Interceptor binding types.

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 Declaring a decorator identifies the DataAccessAuthorizationDecorator class as a decorator. The @Delegate annotation defined in Decorator delegate injection points 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 bean types for beans with a normal scope, as defined in Normal scopes and pseudo-scopes.

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 qualified beans.

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 The default qualifier at injection points. 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 Programming model) 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 The Context interface, 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 the stereotypes for a bean.

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 archives. 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 Default bean name for a managed bean, Default bean name for a session bean, Default bean name for a producer method and Default bean name for a producer field.

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 the interceptor bindings of an interceptor and Declaring a decorator.

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 bean types.

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 Lifecycle of stateful session beans.

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 bean types.

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 bean types.

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 Bean types of a producer field.

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 Specializing a managed bean, Specializing a session bean and Specializing a 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 qualified beans 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 The Bean interface, 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 The Bean interface, 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 Decorator delegate injection points.

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 The Bean interface, 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 Assignability of raw and parameterized types for delegate injection points, 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 The active context object for a scope, 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 Destruction of objects with scope @Dependent, 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 Destruction of objects with scope @Dependent.

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 Destruction of objects with scope @Dependent.

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

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

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

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 for a bean, 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 The CreationalContext interface.

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 Programming model 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 The Bean interface, 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 Context management for built-in scopes 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.

If any method of Conversation is called when the conversation scope is not active, a ContextNotActiveException is thrown.

If end() is called, and the current conversation is marked transient, an IllegalStateException is thrown.

If begin() is called, and the current conversation is already marked long-running, an IllegalStateException is thrown.

If begin() is called with an explicit conversation identifier, and a long-running conversation with that identifier already exists, an IllegalArgumentException is thrown.

When the create() method of the Bean object that represents a managed bean is called, the container obtains an instance of the bean, as defined by the Managed Beans specification, calling the bean constructor as defined by Injection using the bean constructor, and performing dependency injection as defined in Injection of fields and initializer methods.

When the destroy() method is called, the container destroys the instance, as defined by the Managed Beans specification, and any dependent objects, as defined in Destruction of dependent objects.

When the create() method of a Bean object that represents a stateful session bean that is called, the container creates and returns a container-specific internal local reference to a new session bean instance. The reference must be passivation capable. This reference is not directly exposed to the application.

Before injecting or returning a contextual instance to the application, the container transforms its internal reference into an object that implements the bean types expected by the application and delegates method invocations to the underlying stateful session bean instance. This object must be passivation capable.

When the destroy() method is called, and if the underlying EJB was not already removed by direct invocation of a remove method by the application, the container removes the stateful session bean. The @PreDestroy callback must be invoked by the container.

Note that the container performs additional work when the underlying EJB is created and removed, as defined in Dependency injection

When the create() method of a Bean object that represents a stateless session or singleton session bean is called, the container creates and returns a container-specific internal local reference to the session bean. This reference is not directly exposed to the application.

Before injecting or returning a contextual instance to the application, the container transforms its internal reference into an object that implements the bean types expected by the application and delegates method invocations to the underlying session bean. This object must be passivation capable.

When the destroy() method is called, the container simply discards this internal reference.

Note that the container performs additional work when the underlying EJB is created and removed, as defined in Dependency injection

When the create() method of a Bean object that represents a producer method is called, the container must invoke the producer method as defined by Invocation of producer or disposer methods. The return value of the producer method, after method interception completes, is the new contextual instance to be returned by Bean.create().

If the producer method returns a null value and the producer method bean has the scope @Dependent, the create() method returns a null value.

Otherwise, if the producer method returns a null value, and the scope of the producer method is not @Dependent, the create() method throws an IllegalProductException.

When the destroy() method is called, and if there is a disposer method for this producer method, the container must invoke the disposer method as defined by Invocation of producer or disposer methods, passing the instance given to destroy() to the disposed parameter. Finally, the container destroys dependent objects, as defined in Destruction of dependent objects.

When the create() method of a Bean object that represents a producer field is called, the container must access the producer field as defined by Access to producer field values to obtain the current value of the field. The value of the producer field is the new contextual instance to be returned by Bean.create().

If the producer field contains a null value and the producer field bean has the scope @Dependent, the create() method returns a null value.

Otherwise, if the producer field contains a null value, and the scope of the producer field is not @Dependent, the create() method throws an IllegalProductException.

When the destroy() method is called, and if there is a disposer method for this producer field, the container must invoke the disposer method as defined by Invocation of producer or disposer methods, passing the instance given to destroy() to the disposed parameter.

When the create() method of a Bean object that represents a resource is called, the container creates and returns a container-specific internal reference to the Java EE component environment resource, entity manager, entity manager factory, remote EJB instance or web service reference. This reference is not directly exposed to the application.

Before injecting or returning a contextual instance to the application, the container transforms its internal reference into an object that implements the bean types expected by the application and delegates method invocations to the underlying resource, entity manager, entity manager factory, remote EJB instance or web service reference. This object must be passivation capable.

The container must perform ordinary Java EE component environment injection upon any non-static field that functions as a resource declaration, as defined by the Java EE platform and Common Annotations for the Java platform specifications. The container is not required to perform Java EE component environment injection upon a static field. Portable applications should not rely upon the value of a static field that functions as a resource declaration.

References to EJBs and web services are always dependent scoped and a new instance must be obtained for every injection performed.

For an entity manager associated with a resource definition, it must behave as though it were injected directly using @PersistencContext.

When the destroy() method of a bean which represents a remote stateful EJB reference is called, the container will not automatically destroy the EJB reference. The application must explicitly call the method annotated @Remove. This behavior differs to that specified in Lifecycle of stateful session beans for beans which represent a local stateful EJB reference

A decorator is declared by annotating the bean class with the @javax.decorator.Decorator stereotype.

All decorators have a delegate injection point. A delegate injection point is an injection point of the bean class. The type and qualifiers of the injection point are called the delegate type and delegate qualifiers. The decorator applies to beans that are assignable to the delegate injection point.

The delegate injection point must be declared by annotating the injection point with the annotation @javax.decorator.Delegate:

A decorator must have exactly one delegate injection point. If a decorator has more than one delegate injection point, or does not have a delegate injection point, the container automatically detects the problem and treats it as a definition error.

The delegate injection point must be an injected field, initializer method parameter or bean constructor method parameter. If an injection point that is not an injected field, initializer method parameter or bean constructor method parameter is annotated @Delegate, the container automatically detects the problem and treats it as a definition error.

If a bean class that is not a decorator has an injection point annotated @Delegate, the container automatically detects the problem and treats it as a definition error.

The container must inject a delegate object to the delegate injection point. The delegate object implements the delegate type and delegates method invocations to remaining uninvoked decorators and eventually to the bean. When the container calls a decorator during business method interception, the decorator may invoke any method of the delegate object.

If a decorator invokes the delegate object at any other time, the invoked method throws an IllegalStateException.

The delegate type of a decorator must implement or extend every decorated type (with exactly the same type parameters). If the delegate type does not implement or extend a decorated type of the decorator (or specifies different type parameters), the container automatically detects the problem and treats it as a definition error.

A decorator is not required to implement the delegate type.

A decorator may be an abstract Java class, and is not required to implement every method of every decorated type. Whenever the decorator does not implement a method of the decorated type, the container will provide an implicit implementation that calls the method on the delegate. If a decorator has abstract methods that are not declared by a decorated type, the container automatically detects the problem and treats it as a definition error.

The decorator intercepts every method which is declared by a decorated type of the decorator and is implemented by the bean class of the decorator.

A decorator may be enabled for the entire application by applying the @Priority annotation, along with a priority value, on the decorator class. Decorators with the smaller priority values are called first. The order of more than one decorator with the same priority is undefined.

The priority value ranges defined in the Java Interceptors specification section 5.5 should be used when defining decorator priorities.

A decorator may be explicitly enabled by listing its bean class under the <decorators> element of the beans.xml file of the bean archive.

The order of the decorator declarations determines the decorator ordering. Decorators which occur earlier in the list are called first.

Each child <class> element must specify the name of a decorator bean class. If there is no class with the specified name, or if the class with the specified name is not a decorator bean class, the container automatically detects the problem and treats it as a deployment problem.

If the same class is listed twice under the <decorators> element, the container automatically detects the problem and treats it as a deployment problem.

Decorator delegate injection points have a special set of rules for determining assignability of raw and parameterized types, as an exception to Assignability of raw and parameterized types.

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

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

Interceptor bindings may be applied to a stereotype by annotating the stereotype annotation:

An interceptor binding declared by a stereotype is inherited by any bean that declares that stereotype.

If a stereotype declares interceptor bindings, it must be defined as @Target(TYPE).

The Event interface provides a method for firing events with a specified combination of type and qualifiers:

For an injected Event:

For example, this injected Event has specified type LoggedInEvent and specified qualifier @Admin:

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

For example, this child Event has required type AdminLoggedInEvent and additional specified qualifier @Admin:

If the specified type contains a type variable, an IllegalArgumentException is thrown.

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 method fire() fires an event with the specified qualifiers and notifies observers, as defined by Observer notification. If the container is unable to resolve the parameterized type of the event object, it uses the specified type to infer the parameterized type of the event types.

If the runtime type of the event object contains an unresolvable type variable, an IllegalArgumentException is thrown.

If the runtime type of the event object is assignable to the type of a container lifecycle event, an IllegalArgumentException is thrown.

The container must provide a built-in bean with:

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

The built-in implementation must be a passivation capable dependency, as defined in Passivation capable dependencies.

An event type is considered assignable to a type variable if the event type is assignable to the upper bound, if any.

A parameterized event type is considered assignable to a raw observed event type if the raw types are identical.

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

As usual, the qualifier type may have annotation members:

Consider the following event:

Where RoleQualifier is an implementation of the qualifier type Role:

Then the following observer method will always be notified of the event:

Whereas this observer method may or may not be notified, depending upon the value of user.getRole():

As usual, the container uses equals() to compare event qualifier type member values.

An event parameter may have multiple qualifiers.

Then this observer method will only be notified if all the observed event qualifiers are specified when the event is fired:

Other, less specific, observers will also be notified of this event:

Each observer method must have exactly one event parameter, of the same type as the event type it observes. When searching for observer methods for an event, the container considers the type and qualifiers of the event parameter.

If the event parameter does not explicitly declare any qualifier, the observer method observes events with no qualifier.

The event parameter type may contain a type variable or wildcard.

The event parameter may be an array type whose component type contains a type variable or a wildcard.

An observer method may be declared by annotating a parameter @javax.enterprise.event.Observes of a default-access, public, protected or private method. That parameter is the event parameter. The declared type of the parameter is the observed event type.

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

Observed event qualifiers may be declared by annotating the event parameter:

If an observer method is annotated @Produces or @Inject or has a parameter annotated @Disposes, 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 @Observes, and the method is not a business method of the EJB, the container automatically detects the problem and treats it as a definition error.

Interceptors and decorators may not declare observer methods. If an interceptor or decorator has a method with a parameter annotated @Observes, the container automatically detects the problem and treats it as a definition error.

In addition to the event parameter, observer methods may declare additional parameters, which may declare qualifiers. These additional parameters are injection points.

The interface javax.enterprise.inject.spi.EventMetadata provides access to metadata about an observed event.

The container must provide a bean with scope @Dependent, bean type EventMetadata and qualifier @Default, allowing observer methods to obtain information about the events they observe.

If an injection point of type EventMetadata and qualifier @Default which is not a parameter of an observer method exists, the container automatically detects the problem and treats it as a definition error.

A conditional observer method is an observer method which is notified of an event only if an instance of the bean that defines the observer method already exists in the current context.

A conditional observer method may be declared by specifying receive=IF_EXISTS.

Beans with scope @Dependent may not have conditional observer methods. If a bean with scope @Dependent has an observer method declared receive=IF_EXISTS, the container automatically detects the problem and treats it as a definition error.

The enumeration javax.enterprise.event.Reception identifies the possible values of receive:

Transactional observer methods are observer methods which receive event notifications during the before or after completion phase of the transaction in which the event was fired. If no transaction is in progress when the event is fired, they are notified at the same time as other observers.

The enumeration javax.enterprise.event.TransactionPhase identifies the kind of transactional observer method:

A transactional observer method may be declared by specifying any value other than IN_PROGRESS for during:

The transaction context, client security context and lifecycle contexts active when an observer method is invoked depend upon what kind of observer method it is.

Of course, the transaction and security contexts for a business method of a session bean also depend upon the transaction attribute and @RunAs descriptor, if any.

The Bean object for a decorator must implement the interface javax.enterprise.inject.spi.Decorator.

An instance of Decorator exists for every enabled decorator.

The Bean object for an interceptor must implement javax.enterprise.inject.spi.Interceptor.

An InterceptionType identifies the kind of lifecycle callback, EJB timeout method or business method.

An instance of Interceptor exists for every enabled interceptor.

The interface javax.enterprise.inject.spi.ObserverMethod defines everything the container needs to know about an observer method.

An instance of ObserverMethod must exist for every observer method of every enabled bean.

Portable extensions and other objects sometimes interact directly with the container via programmatic API call. The abstract javax.enterprise.inject.spi.CDI provides access to the BeanManager as well providing lookup of bean instances.

A portable extension or other object may obtain a reference to the current container by calling CDI.current(). CDI.getBeanManager() may be called at any time after the container fires the BeforeBeanDiscovery container lifecycle event until the container fires the BeforeShutdown container lifecycle event. Other methods on CDI may be called after the application initialization is completed until the application shutdown starts. If methods on CDI are called at any other time, non-portable behavior results.

When CDI.current() is called, getCDI() method is called on javax.enterprise.inject.spi.CDIProvider.

The CDIProvider to use may be set by the application or container using the setCDIProvider() method. If the setCDIProvider() has not been called, the first service provider of the service javax.enterprise.inject.spi.CDIProvider declared in META-INF/services is used. If no provider is available an IllegalStateException is thrown.

A Java EE container is required to provide a CDI provider that will allow access to the current container for any Java EE application or Java EE module which contains enabled beans.

Java EE components may obtain an instance of BeanManager from JNDI by looking up the name java:comp/BeanManager.

The method BeanManager.getReference() returns a contextual reference for a given bean and bean type, as defined in Contextual reference for a bean.

The first parameter is the Bean object representing the bean. The second parameter represents a bean type that must be implemented by any client proxy that is returned. The third parameter is an instance of CreationalContext that may be used to destroy any object with scope @Dependent that is created.

If the given type is not a bean type of the given bean, an IllegalArgumentException is thrown.

The method BeanManager.getInjectableReference() returns an injectable reference for a given injection point, as defined in Injectable references.

The first parameter represents the target injection point. The second parameter is an instance of CreationalContext that may be used to destroy any object with scope @Dependent that is created.

If the InjectionPoint represents a decorator delegate injection point, getInjectableReference() returns a delegate, as defined in Decorator delegate injection points.

If typesafe resolution results in an unsatisfied dependency, the container must throw an UnsatisfiedResolutionException. If typesafe resolution results in an unresolvable ambiguous dependency, the container must throw an AmbiguousResolutionException.

Implementations of Bean usually maintain a reference to an instance of BeanManager. When the Bean implementation performs dependency injection, it must obtain the contextual instances to inject by calling BeanManager.getInjectableReference(), passing an instance of InjectionPoint that represents the injection point and the instance of CreationalContext that was passed to Bean.create().

A non-contextual instance can be obtained and injected from an InjectionTarget, however the InjectionTarget interface is designed to work on contextual instances. A helper class, Unmanaged provides a set of methods optimized for working with non-contextual instances.

For example:

An instance of CreationalContext for a certain instance of Contextual may be obtained by calling BeanManager.createCreationalContext().

An instance of CreationalContext for a non-contextual object may be obtained by passing a null value to createCreationalContext().

The method BeanManager.getBeans() returns the set of beans which have the given required type and qualifiers and are available for injection in the module or library containing the class into which the BeanManager was injected or the Java EE component from whose JNDI environment namespace the BeanManager was obtained, according to the rules for candidates of typesafe resolution defined in Performing typesafe resolution.

The first parameter is a required bean type. The remaining parameters are required qualifiers.

If no qualifiers are passed to getBeans(), the default qualifier @Default is assumed.

If the given type represents a type variable, an IllegalArgumentException is thrown.

If two instances of the same qualifier type are given, an IllegalArgumentException is thrown.

If an instance of an annotation that is not a qualifier type is given, an IllegalArgumentException is thrown.

The method BeanManager.getBeans() which accepts a string returns the set of beans which have the given bean name and are available for injection in the module or library containing the class into which the BeanManager was injected or the Java EE component from whose JNDI environment namespace the BeanManager was obtained, according to the rules of name resolution defined in EL name resolution.

The parameter is a bean name.

The method BeanManager.getPassivationCapableBean() returns the PassivationCapable bean with the given identifier (see Passivation capable beans).

The method BeanManager.resolve() applies the ambiguous dependency resolution rules defined in Unsatisfied and ambiguous dependencies to a set of Bean s.

If the ambiguous dependency resolution rules fail (as defined in Unsatisfied and ambiguous dependencies, the container must throw an AmbiguousResolutionException.

BeanManager.resolve() must return null if:

The BeanManager.validate() operation validates an injection point and throws an InjectionException if there is a deployment problem (for example, an unsatisfied or unresolvable ambiguous dependency) associated with the injection point.

The method BeanManager.fireEvent() fires an event and notifies observers, according to Observer notification.

The first argument is the event object. The remaining parameters are event qualifiers.

If the runtime type of the event object contains a type variable, an IllegalArgumentException is thrown.

If two instances of the same qualifier type are given, an IllegalArgumentException is thrown.

If an instance of an annotation that is not a qualifier type is given, an IllegalArgumentException is thrown.

If the runtime type of the event object is assignable to the type of a container lifecycle event, an IllegalArgumentException is thrown.

The method BeanManager.resolveObserverMethods() resolves observer methods for an event according to the rules of observer resolution defined in Observer resolution.

The first parameter of resolveObserverMethods() is the event object. The remaining parameters are event qualifiers.

If the runtime type of the event object contains a type variable, an IllegalArgumentException is thrown.

If two instances of the same qualifier type are given, an IllegalArgumentException is thrown.

If an instance of an annotation that is not a qualifier type is given, an IllegalArgumentException is thrown.

The method BeanManager.resolveDecorators() returns the ordered list of decorators for a set of bean types and a set of qualifiers and which are enabled in the module or library containing the class into which the BeanManager was injected or the Java EE component from whose JNDI environment namespace the BeanManager was obtained, as defined in Decorator resolution.

The first argument is the set of bean types of the decorated bean. The annotations are qualifiers declared by the decorated bean.

If two instances of the same qualifier type are given, an IllegalArgumentException is thrown.

If an instance of an annotation that is not a qualifier type is given, an IllegalArgumentException is thrown.

If the set of bean types is empty, an IllegalArgumentException is thrown.

The method BeanManager.resolveInterceptors() returns the ordered list of interceptors for a set of interceptor bindings and a type of interception and which are enabled in the module or library containing the class into which the BeanManager was injected or the Java EE component from whose JNDI environment namespace the BeanManager was obtained, as defined in Interceptor resolution.

If two instances of the same interceptor binding type are given, an IllegalArgumentException is thrown.

If no interceptor binding type instance is given, an IllegalArgumentException is thrown.

If an instance of an annotation that is not an interceptor binding type is given, an IllegalArgumentException is thrown.

A portable extension may test an annotation to determine if it is a qualifier type, scope type, stereotype or interceptor binding type, obtain the set of meta-annotations declared by a stereotype or interceptor binding type, or determine if a scope type is a normal or passivating scope.

A portable extension may determine if two qualifiers or two interceptor bindings are considered equivalent for the purposes of typesafe resolution, as defined in Performing typesafe resolution.

A portable extension may determine the hash code of a qualifier or interceptor binding, ignoring any members annotated with @Nonbinding.

The method BeanManager.getContext() retrieves an active context object associated with the given scope, as defined in The active context object for a scope.

The method BeanManager.getELResolver() returns the javax.el.ELResolver specified in Integration with Unified EL.

The method BeanManager.wrapExpressionFactory() returns a wrapper javax.el.ExpressionFactory that delegates MethodExpression and ValueExpression creation to the given ExpressionFactory. When a Unified EL expression is evaluated using a MethodExpression or ValueExpression returned by the wrapper ExpressionFactory, the rules defined in Dependent pseudo-scope and Unified EL are enforced by the container.

The method BeanManager.createAnnotatedType() returns an AnnotatedType that may be used to read the annotations of the given Java class or interface.

The method BeanManager.getInjectionTargetFactory() returns a factory capable of creating container provided implementations of InjectionTarget for a given AnnotatedType or throws an IllegalArgumentException if there is a definition error associated with any injection point of the type.

Null should be passed to InjectionTargetFactory.createInjectionTarget() to create a non-contextual injection target. The method BeanManager.createInjectionTarget() is deprecated since version 1.1 of Contexts and Dependency Injection.

The method BeanManager.getProducerFactory() returns a factory capable of creating container provided implementations of Producer for a given AnnotatedMethod or AnnotatedField, and declaring bean, or throws an IllegalArgumentException if there is a definition error associated with the producer method or field.

Null should be passed to ProducerFactory.createProducer() to create a producer of non-contextual objects.

The method BeanManager.createInjectionPoint() returns a container provided implementation of InjectionPoint for a given AnnotatedField or AnnotatedParameter or throws an IllegalArgumentException if there is a definition error associated with the injection point.

The method BeanManager.createBeanAttributes() returns a container provided implementation of BeanAttributes by reading the annotations of a given AnnotatedType or AnnotatedMember, according to the rules defined in Concepts, or throws an IllegalArgumentException if there is a definition error associated with the declared bean attributes.

The method BeanManager.createBean() returns a container provided implementation of Bean. The methods accept:

A second version of the method is provided to create a Bean from a producer. The method accepts:

The method BeanManager.getExtension() returns the container’s instance of an Extension class declared in META-INF/services, or throws an IllegalArgumentException if the container has no instance of the given class.

The container must fire an event before it begins the type discovery process. The event object must be of type javax.enterprise.inject.spi.BeforeBeanDiscovery:

If any observer method of the BeforeBeanDiscovery event throws an exception, the exception is treated as a definition error by the container.

If any BeforeBeanDiscovery method is called outside of the observer method invocation, an IllegalStateException is thrown.

The container must fire an event when it has fully completed the type discovery process and before it begins the bean discovery process. The event object must be of type javax.enterprise.inject.spi.AfterTypeDiscovery.

If an alternative, interceptor or decorator is added using AfterTypeDiscovery.addAnnotatedType(), non-portable behavior results.

Any observer of this event is permitted to add classes to, or remove classes from, the list of alternatives, list of interceptors or list of decorators. The container must use the final values of these collections, after all observers of AfterTypeDiscovery have been called, to determine the order of the enabled alternatives, interceptors, and decorators for application. The initial values of these collections are defined by the @Priority annotation.

If any observer method of a AfterTypeDiscovery event throws an exception, the exception is treated as a definition error by the container.

If any AfterTypeDiscovery method is called outside of the observer method invocation, an IllegalStateException is thrown.

The container must fire an event when it has fully completed the bean discovery process, validated that there are no definition errors relating to the discovered beans, and registered Bean and ObserverMethod objects for the discovered beans.

The event object must be of type javax.enterprise.inject.spi.AfterBeanDiscovery:

A portable extension may take advantage of this event to register beans, interceptors, decorators, observer methods and custom context objects with the container.

If any observer method of the AfterBeanDiscovery event throws an exception, the exception is treated as a definition error by the container.

If any AfterBeanDiscovery method is called outside of the observer method invocation, an IllegalStateException is thrown.

The container must fire an event after it has validated that there are no deployment problems and before creating contexts or processing requests.

The event object must be of type javax.enterprise.inject.spi.AfterDeploymentValidation:

If any observer method of the AfterDeploymentValidation event throws an exception, the exception is treated as a deployment problem by the container.

If any AfterDeploymentValidation method is called outside of the observer method invocation, an IllegalStateException is thrown.

The container must not allow any request to be processed by the deployment until all observers of this event return.

The container must fire a final event after it has finished processing requests and destroyed all contexts.

The event object must be of type javax.enterprise.inject.spi.BeforeShutdown:

If any observer method of the BeforeShutdown event throws an exception, the exception is ignored by the container.

The container must fire an event, before it processes a type, for every Java class, interface (excluding the special kind of interface declaration annotation type) or enum discovered

as defined in Type discovery

An event is not fired for any type annotated with @Vetoed, or in a package annotated with @Vetoed.

The event object must be of type javax.enterprise.inject.spi.ProcessAnnotatedType<X>, where X is the class, for types discovered in a bean archive, or of type javax.enterprise.inject.spi.ProcessSyntheticAnnotatedType<X> for types added by BeforeBeanDiscovery.addAnnotatedType() or AfterTypeDiscovery.addAnnotatedType().

The annotation @WithAnnotations may be applied to the event parameter. If the annotation is applied, the container must only deliver ProcessAnnotatedType events for types which contain at least one of the annotations specified. The annotation can appear on the annotated type, or on any member, or any parameter of any member of the annotated type, as defined in Alternative metadata sources. The annotation may be applied as a meta-annotation on any annotation considered.

If the @WithAnnotations annotation is applied to any other event parameter, the container automatically detects the problem and treats it as a definition error.

Any observer of this event is permitted to wrap and/or replace the AnnotatedType. The container must use the final value of this property, after all observers have been called, as the only source of types and annotations for the program elements.

For example, the following observer decorates the AnnotatedType for every class that is discovered by the container.

If any observer method of a ProcessAnnotatedType event throws an exception, the exception is treated as a definition error by the container.

If any ProcessAnnotatedType method is called outside of the observer method invocation, an IllegalStateException is thrown.

The container must fire an event for every injection point of every Java EE component class supporting injection that may be instantiated by the container at runtime, including every managed bean declared using @ManagedBean, EJB session or message-driven bean, bean, interceptor or decorator.

The event object must be of type javax.enterprise.inject.spi.ProcessInjectionPoint<T, X> where T is the managed bean class, session bean class or Java EE component class supporting injection, and X is the declared type of the injection point.

Any observer of this event is permitted to wrap and/or replace the InjectionPoint. The container must use the final value of this property, after all observers have been called, whenever it performs injection upon the injection point.

If any observer method of a ProcessInjectionPoint event throws an exception, the exception is treated as a definition error by the container.

If any ProcessInjectionPoint method is called outside of the observer method invocation, an IllegalStateException is thrown.

The container must fire an event for every Java EE component class supporting injection that may be instantiated by the container at runtime, including every managed bean declared using @ManagedBean, EJB session or message-driven bean, bean, interceptor or decorator.

The event object must be of type javax.enterprise.inject.spi.ProcessInjectionTarget<X>, where X is the managed bean class, session bean class or Java EE component class supporting injection.

Any observer of this event is permitted to wrap and/or replace the InjectionTarget. The container must use the final value of this property, after all observers have been called, whenever it performs injection upon the managed bean, session bean or other Java EE component class supporting injection.

For example, this observer decorates the InjectionTarget for all servlets.

If any observer method of a ProcessInjectionTarget event throws an exception, the exception is treated as a definition error by the container.

If any ProcessInjectionTarget method is called outside of the observer method invocation, an IllegalStateException is thrown.

The container must fire an event for each bean, interceptor or decorator deployed in a bean archive, before registering the Bean object. No event is fired for any:

The event object must be of type javax.enterprise.inject.spi.ProcessBeanAttributes<T> where T is the bean class of the managed bean or session bean, the return type of the producer method, or the type of the producer field.

Resources are considered to be producer fields.

Any observer of this event is permitted to wrap and/or replace the BeanAttributes. The container must use the final value of this property, after all observers have been called, to manage instances of the bean. Changes to BeanAttributes are not propagated to the annotated type from which the bean definition was created.

Any bean which has its bean attributes altered must have it’s definition validated during deployment validation.

If any observer method of a ProcessBeanAttributes event throws an exception, the exception is treated as a definition error by the container.

If any ProcessBeanAttributes method is called outside of the observer method invocation, an IllegalStateException is thrown.

The container must fire an event for each bean, interceptor or decorator deployed in a bean archive, after firing the ProcessBeanAttributes for the bean and before registering the Bean object. No event is fired for any @New qualified bean, defined in @New qualified beans.

The event object type in the package javax.enterprise.inject.spi depends upon what kind of bean was discovered:

Resources are considered to be producer fields.

The interface javax.enterprise.inject.spi.ProcessBean is a supertype of all these event types:

If any observer method of a ProcessBean event throws an exception, the exception is treated as a definition error by the container.

If any ProcessBean method is called outside of the observer method invocation, an IllegalStateException is thrown.

The container must fire an event for each producer method or field of each bean, including resources.

The event object must be of type javax.enterprise.inject.spi.ProcessProducer<T, X>, where T is the bean class of the bean that declares the producer method or field and X is the return type of the producer method or the type of the producer field.

Any observer of this event is permitted to wrap and/or replace the Producer. The container must use the final value of this property, after all observers have been called, whenever it calls the producer or disposer.

For example, this observer decorates the Producer for all producer methods and fields of type EntityManager.

If any observer method of a ProcessProducer event throws an exception, the exception is treated as a definition error by the container.

If any ProcessProducer method is called outside of the observer method invocation, an IllegalStateException is thrown.

The container must fire an event for each observer method of each bean, before registering the ObserverMethod object.

The event object must be of type javax.enterprise.inject.spi.ProcessObserverMethod<T, X>, where T is the observed event type of the observer method and X is the bean class of the bean that declares the observer method.

If any observer method of a ProcessObserverMethod event throws an exception, the exception is treated as a definition error by the container.

If any ProcessObserverMethod method is called outside of the observer method invocation, an IllegalStateException is thrown.

First the container must discover types. The container discovers:

that is not excluded from discovery by an exclude filter as defined in Exclude filters.

Then, for every type discovered the container must create an AnnotatedType representing the type and fire an event of type ProcessAnnotatedType, as defined in ProcessAnnotatedType event.

If an extension calls BeforeBeanDiscovery.addAnnotatedType() or AfterTypeDiscovery.addAnnotatedType(), the type passed must be added to the set of discovered types and the container must fire an event of type ProcessSyntheticAnnotatedType for every type added, as defined in ProcessAnnotatedType event+

Exclude filters are defined by <exclude> elements in the beans.xml for the bean archive as children of the <scan> element. By default an exclude filter is active. If the exclude filter definition contains: