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 @jakarta.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 jakarta.enterprise.inject. In addition, the built-in qualifier type @Named is defined by the package jakarta.inject.

Every bean has the built-in qualifier @Any, even if it does not explicitly declare this qualifier.

If a bean does not explicitly declare a qualifier other than @Named or @Any, 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 @jakarta.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:

In some cases, it may be useful to have a repeated qualifier for your type safe resolution. A repeated qualifier behaves just as any other qualifier does. For example, the below qualifier is a repeatable qualifier

Now you can define appropriate producers and injection points for repeated qualifiers.

A partial match injection point will still work in this case (from the same producer method)

However, adding the follow producer method will continue to give you an ambiguous resolution error (assuming the other producer exists as well)

There are three standard scope types defined in CDI Lite, all defined in the package jakarta.enterprise.context.

If an interceptor 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 @jakarta.inject.Scope or @jakarta.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 extensions, which must also provide an implementation of the Context interface, as defined in The Context interface, that implements the custom scope. Portable extensions provide a context object directly, while build compatible extensions provide a class that the container has to instantiate to obtain the context object.

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 Jakarta Dependency Injection 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 @jakarta.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:

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 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 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 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 @jakarta.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 @jakarta.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 stereotype is defined in Declaring the interceptor bindings of an interceptor.

A Java class is a managed bean if it meets all of the following conditions:

In CDI Full environment, a Java class is a managed bean also if:

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 JAR File Specification.

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

The resulting set of bean types for a managed bean consists only of legal bean types, all other types are removed from the set of bean types.

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 CDI based integration testing environment.

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.

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

The resulting set of bean types for a producer method consists only of legal bean types, all other types are removed from the set of bean types.

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 @jakarta.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, has a parameter annotated @Observes, or has a parameter annotated @ObservesAsync, the container automatically detects the problem and treats it as a definition error.

Interceptors may not declare producer methods. If an interceptor 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.

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:

The resulting set of bean types for a producer field consists only of legal bean types, all other types are removed from the set of bean types.

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 @jakarta.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.

Interceptors may not declare producer fields. If an interceptor 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 @jakarta.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, has a parameter annotated @Observes or has a parameter annotated @ObservesAsync, the container automatically detects the problem and treats it as a definition error.

Interceptors may not declare disposer methods. If an interceptor 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.

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, @Observes, or @ObservesAsync, 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 @jakarta.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 @jakarta.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, has a parameter annotated @Observes, or has a parameter annotated @ObservesAsync, 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.

CDI Lite defines one method of selecting alternatives: the @Priority annotation allows an alternative to be selected for an entire application. CDI Full defines an additional method of selecting alternatives, which is specified therein.

A bean is said to be enabled if:

Otherwise, the bean is said to be disabled.

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

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:

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.

When an ambiguous dependency exists, the container attempts to resolve the ambiguity. The container eliminates all eligible beans that are not alternatives selected for the application, 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 and all disposer methods 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.

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.

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 name exists when a name resolves to multiple beans. When an ambiguous name exists, the container attempts to resolve the ambiguity. The container eliminates all eligible beans that are not alternatives selected for the application, except for producer methods and fields of beans that are alternatives. If:

All unresolvable ambiguous names are detected by the container when the application is initialized. Suppose two beans are both available for injection in a certain module, 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 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, the container must:

The container must ensure that:

When the container destroys an instance of a bean, the container destroys all dependent objects, as defined in Destruction of objects with scope @Dependent, after the @PreDestroy callback completes.

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 jakarta.enterprise.inject.spi.InjectionPoint provides access to metadata about an injection point. An instance of InjectionPoint may represent:

Occasionally, a bean 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.

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 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 and Interceptor provide metadata about a bean.

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

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

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

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. Rules specified at The default qualifier at injection points are applied before performing typesafe resolution.

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 non repeating 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 stream() method must:

The methods isUnsatisfied(), isAmbiguous() and isResolvable() must:

The method destroy() instructs the container to destroy the instance. The bean instance passed to destroy() should be a dependent scoped bean instance obtained from the same Instance object, 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 getHandle() method must:

The handles() method must:

The handlesStream() is a Stream equivalent of the aforementioned handles() method.

The container must provide a built-in bean that:

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

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

The following built-in annotations define a Literal static nested class to support inline instantiation of the specific annotation type:

The Literal class might be used to instantiate the matching AnnotationLiteral:

Annotations without members provide the default AnnotationLiteral instance declared as a constant named INSTANCE:

Annotations having members do not provide the default AnnotationLiteral instance. Instead, a constructor or factory method named of can be used:

See also the annotation javadoc for more information about specific Literal members.

In addition, CDI also provides annotation literals for the following JSR 330 annotations:

They can be used like static nested classes described above.

The interface jakarta.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 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).

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.

Certain built in contexts support the ability to be activated and deactivated. This allows developers to control built-in contexts in ways that they could also manage custom built contexts.

When activating and deactivating built in contexts, it is important to realize that they can only be activated if not already active within a given thread.

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.

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.

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

An event with qualifier @Initialized(RequestScoped.class) is synchronously fired when the request context is initialized. An event with qualifier @BeforeDestroyed(RequestScoped.class) is synchronously fired when the request context is about to be destroyed, i.e. before the actual destruction. An event with qualifier @Destroyed(RequestScoped.class) is synchronously fired when the request context is destroyed, i.e. after the actual destruction.

The request context is active:

The request context is destroyed:

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

An event with qualifier @Initialized(ApplicationScoped.class) is synchronously fired when the application context is initialized. An event with qualifier @BeforeDestroyed(ApplicationScoped.class) is synchronously fired when the application context is about to be destroyed, i.e. before the actual destruction. An event with qualifier @Destroyed(ApplicationScoped.class) is synchronously fired when the application context is destroyed, i.e. after the actual destruction.

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

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 method fire() accepts an event object:

Event fired with the fire() method is fired synchronously. All the resolved synchronous observers (as defined in Observer resolution) are called in the thread in which fire() was called. A synchronous observer notification blocks the calling thread until it completes.

Events may also be fired asynchronously using one of the methods fireAsync()

Event fired with the fireAsync() method is fired asynchronously. All the resolved asynchronous observers (as defined in Observer resolution) are called in one or more different threads.

Method fireAsync() returns immediately.

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:

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 non repeating 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 methods fire() and fireAsync() fire an event with the specified qualifiers and notify 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.

The method fireAsync() may be called with a NotificationOptions object to configure the observer methods notification, e.g. to specify an Executor object to be used for asynchronous delivery. The container is permitted to define other non-portable notification options.

The following elements are container specific:

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.

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

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

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 be notified if the set of observer qualifiers is a subset of the fired event’s qualifiers or an empty set:

In the above example the event is fired with @ByAdmin, @Updated, and @Clarification qualifiers. The observer qualifiers are @Updated and @ByAdmin. Observer qualifiers therefore form a subset of event qualifiers and the observer will be notified.

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

On the other hand, following observer will not be notified as slightly different behaviour applies to observers with @Default qualifier:

Such observer will only be notified for events having either no qualifiers or only @Default qualifier:

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.

Modifications made to the event parameter in an observer method are propagated to following observers. The container is not required to guarantee a consistent state for an event parameter modified by asynchronous observers.

An observer method may be declared by annotating a parameter @jakarta.enterprise.event.Observes or @jakarta.enterprise.event.ObservesAsync 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 @Observes is used the observer method is a synchronous observer method.

If @ObservesAsync is used the observer method is an asynchronous observer method.

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

If a method has a parameter annotated @Observes and @ObservesAsync, 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.

Interceptors may not declare observer methods. If an interceptor has a method with a parameter annotated @Observes or @ObservesAsync, 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 jakarta.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 notifyObserver=IF_EXISTS.

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

The enumeration jakarta.enterprise.event.Reception identifies the possible values of notifyObserver:

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.

If the transaction is in progress, but jakarta.transaction.Synchronization callback cannot be registered due to the transaction being already marked for rollback or in state where jakarta.transaction.Synchronization callbacks cannot be registered, the before completion, after completion and after failure observer methods are notified at the same time as other observers, but after_success observer methods get skipped.

The enumeration jakarta.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:

Asynchronous observer cannot be declared transactional.

If an event is asynchronous, and an exception is thrown by any of its notified observers, the CompletionStage returned by fireAsync will complete exceptionally with java.util.concurrent.CompletionException exception. CompletionException contains all exceptions thrown by observers as suppressed exceptions. They can be accessed as an array of Throwable with the getSuppressed method.

It can be handled with one of the CompletionStage methods related to exceptions:

If no exception is thrown by observers then the resulting CompletionStage is completed normally with the event object.

Before the actual observer notification, the container determines an order in which the observer methods for a certain event are invoked. The priority of an observer method may be declared by annotating the event parameter with @Priority annotation. If a @Priority annotation is declared on an event parameter of an asynchronous observer method, non-portable behavior results. If no @Priority annotation is specified, the default priority jakarta.interceptor.Interceptor.Priority.APPLICATION + 500 is assumed. Observers with smaller priority values are called first.

The order of more than one observer with the same priority is undefined and the observer methods are notified therefore in a non predictable order.

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

Implementations are required to synchronously fire an event with payload jakarta.enterprise.event.Startup and qualifier jakarta.enterprise.inject.Any during application initialization. This event is fired after the event with qualifier @Initialized(ApplicationScope.class) but before processing requests.

This event can be observed by integrators and libraries to perform any kind of early initialization as well as by users as a reliable entry point for when the CDI container is ready.

Observer methods for this event are encouraged to specify @Priority to determine ordering with lower priority numbers being recommended for platform/framework/library integration and higher numbers for user applications.

Applications must never manually fire any events with payload type jakarta.enterprise.event.Startup.

Implementations are required to synchronously fire an event with payload jakarta.enterprise.event.Shutdown and qualifier jakarta.enterprise.inject.Any during application shutdown. This event is fired during CDI container shutdown but not later than the event with qualifier @BeforeDestroyed(ApplicationScoped.class).

This event can be observed by integrators and libraries to perform any kind of pre-shutdown operation as well as by users as a reliable entry point for when the CDI container is about to shut down.

Observer methods for this event are encouraged to specify @Priority to determine ordering with lower priority numbers being recommended for user applications and higher numbers for platform/framework/library integration.

Applications must never manually fire any events with payload type jakarta.enterprise.event.Shutdown.

Application objects sometimes interact directly with the container via programmatic API call. The abstract class jakarta.enterprise.inject.spi.CDI provides access to the BeanContainer as well providing lookup of bean instances.

An object may obtain a reference to the current container by calling CDI.current(). CDI.getBeanContainer(), as well as 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.

CDI implements jakarta.enterprise.inject.Instance and therefore might be used to perform programmatic lookup as defined in The Instance interface. If no qualifier is passed to CDI.select() method, the @Default qualifier is assumed.

When CDI.current() is called, getCDI() method is called on jakarta.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 service provider with highest priority of the service jakarta.enterprise.inject.spi.CDIProvider declared in META-INF/services is used. The order of more than one CDIProvider with the same priority is undefined. If no provider is available an IllegalStateException is thrown.

The method BeanContainer.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 BeanContainer.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 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 BeanContainer. When the Bean implementation performs dependency injection, it must obtain the contextual instances to inject by calling BeanContainer.getInjectableReference(), passing an instance of InjectionPoint that represents the injection point and the instance of CreationalContext that was passed to Bean.create().

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

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

The method BeanContainer.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 BeanContainer was injected, 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 non repeating 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 BeanContainer.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 BeanContainer was injected, according to the rules of name resolution defined in Name resolution.

The parameter is a bean name.

The method BeanContainer.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.

BeanContainer.resolve() must return null if:

The method BeanContainer.getEvent() returns an instance of Event with specified type java.lang.Object and specified qualifier @Default.

The returned instance can be used like a standard Event as described in Events.

The method BeanContainer.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 non repeating 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 BeanContainer.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 BeanContainer was injected, as defined in Interceptor resolution.

If two instances of the same non repeating 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.

An application may test an annotation to determine if it is a qualifier type, scope type, stereotype or interceptor binding type, or determine if a scope type is a normal scope.

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

The method BeanContainer.createInstance() returns an Instance<Object> to request bean instances programmatically as described in The Instance interface.

The returned Instance object can only access instances of beans that are available for injection in the module or library containing the class into which the BeanContainer was injected, according to the rules defined in Typesafe resolution.

Instances of dependent scoped beans obtained with this Instance object must be explicitly released by calling Instance.destroy() method.

If no qualifier is passed to Instance.select() method, the @Default qualifier is assumed.

First the container must discover types. The container discovers each Java class with a bean defining annotation in an implicit bean archive.

The container must also execute the @Discovery phase of build compatible extensions and discover all classes added using the ScannedClasses API.

When all types are discovered, the container must execute the @Enhancement phase of build compatible extensions and alter its metadata representation of discovered types accordingly.

For every type in the set of discovered types (as defined in Type discovery), the container must:

For each enabled bean, the container must search the class for producer methods and fields, as defined in Producer methods and in Producer fields, including resources, and for disposer methods as defined in Disposer methods, and for observer methods.

Then, the container registers the Bean and ObserverMethod objects:

The container must execute the @Registration phase of build compatible extensions for each registered bean, interceptor, and observer method.

Next, the container must execute the @Synthesis phase of build compatible extensions. For each registered synthetic bean, the container registers an instance of the Bean interface. For each registered synthetic observer, the container registers an instance of the ObserverMethod interface.

Finally, the container must execute the @Registration phase of build compatible extensions for each synthetic bean and synthetic observer method.

In addition to built-in stereotypes defined in Built-in stereotypes, the following built-in stereotype is present.

The special-purpose @Decorator stereotype is defined in Declaring a decorator.

The annotation @jakarta.enterprise.inject.Specializes is used to indicate that one bean directly specializes another bean, as defined in Specializing a managed bean and Specializing a producer method.

Formally, a bean X is said to specialize another bean Y if there is 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: