CDI 4.1 no longer specifies integration with Jakarta EE. This will now be specified in the Jakarta EE Platform, Web Profile and Core Profile specifications.

The Unified EL integration API in BeanManager has been deprecated and the relevant methods added to a dedicated interface ELAwareBeanManager, which is present in a new supplemental API artifact: jakarta.enterprise:jakarta.enterprise.cdi-el-api. This supplemental artifact declares a JPMS module jakarta.cdi.el, which declares a dependency on jakarta.cdi and jakarta.el.

The method invokers API has been added to allow frameworks to more easily call methods on managed beans and optionally look up the bean instance and arguments using CDI.

New methods have been added to BeanContainer to check assignability of beans and events and to obtain contexts for a scope.

The @Priority annotation can now be placed on producer methods and producer fields directly.

A new beans.xml 4.1 schema file has been added and the namespace of the beans_4_1.xsd schema file is xmlns:jakartaee="https://jakarta.ee/xml/ns/jakartaee". The only change in the schema is to update the default value for the version to 4.1 and update the example to use the new version.

CDI 4.0 splits the CDI core into Lite and Full. Lite contains a subset of original features which are designed to work in more restricted environments. CDI Full contains everything that is in Lite plus all other features that were formerly in core CDI and are not in Lite.

A new beans.xml 4.0 schema file has been added and the namespace of the beans_4_0.xsd schema file is xmlns:jakartaee="https://jakarta.ee/xml/ns/jakartaee", the same as 3.0. The key changes in the schema are to make the bean-discovery-mode attribute default to annotated and to use annotated as the default when an empty beans.xml is seen in a deployment. When running in a CDI Lite environment, only the bean-discovery-mode attribute is read from the beans.xml file. This means that by default, only those types with Bean defining annotations will be considered. Deployment relying on discovery of all types will either need to include a beans.xml with bean-discovery-mode=all, or introduce bean defining annotations to beans in the deployment.

A new jakarta.enterprise:jakarta.enterprise.lang-model API artifact has been aded for the Build Compatible (Reflection-Free) Java Language Model for CDI introduced by CDI Lite, and used in the new jakarta.enterprise.inject.build.compatible.spi package of the main jakarta.enterprise:jakarta.enterprise.cdi-api artifact. This new package is described in the Build compatible extensions section.

Java Platform Module System(JPMS) module-info.class files have been added to the CDI API artifacts. The cdi-api artifact defines a jakarta.cdi module with the following descriptor:

The lang-model artifact defines a jakarta.cdi.lang.model module with the following descriptor:

CDI 3.0 is an incompatible update to Jakarta Contexts and Dependency Injection 2.0 (CDI 2.0).

CDI 3.0 includes a change in the base namespace used by the APIs from javax to jakarta. For example, the BeanManager interface has moved from javax.enterprise.inject.spi.BeanManager to jakarta.enterprise.inject.spi.BeanManager.

A new beans.xml 3.0 schema file was added and the namespace of the beans_3_0.xsd schema file has changed from xmlns:javaee="http://xmlns.jcp.org/xml/ns/javaee" to xmlns:jakartaee="https://jakarta.ee/xml/ns/jakartaee".

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

The Jakarta EE platform specification defines a facility for injecting resources that exist in the Jakarta 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.

Jakarta Enterprise Bean defines a programming model for application components that access transactional resources in a multi-user environment. Jakarta Enterprise Bean 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 Jakarta Enterprise Bean container at runtime.

Jakarta Enterprise Bean 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 Jakarta Enterprise Bean 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 Jakarta Dependency Injection 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 Jakarta 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.

Jakarta 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 Jakarta Faces application may take advantage of the sophisticated context and dependency injection model defined by this specification.

Jakarta 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 Jakarta Validation specification defines beans for certain managed objects, including Validator and ValidatorFactory. A number of Jakarta Validation managed instances, including ConstraintValidators, can take advantage of dependency injection. Jakarta Validation also provides support for method parameter validation on any bean.

The following Jakarta Faces page defines a login prompt for a web application:

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

The Credentials bean has a lifecycle that is bound to the Jakarta Faces 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 Jakarta Dependency Injection 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 Jakarta Persistence persistence unit is required.

When the login form is submitted, Jakarta Faces assigns the entered username and password to an instance of the Credentials bean that is automatically instantiated by the container. Next, Jakarta Faces 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 Jakarta Enterprise Bean:

The Jakarta Enterprise Bean @Stateful annotation specifies that this bean is an Jakarta Enterprise Bean stateful session bean. The Jakarta Enterprise Bean @TransactionAttribute and @RolesAllowed annotations declare the Jakarta Enterprise Bean 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 Jakarta EE component environment in Java code.

The Jakarta Persistence @PersistenceContext and @PersistenceUnit annotations identify the Jakarta Persistence 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 @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 that has a parameter 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, except for producer methods and fields of beans that are alternatives. If:

For the purpose of determining the priority of any producer method or field during ambiguity resolution, the priority of the producer method or field is considered first. If the producer method or field does not have a priority, the priority of the managed bean that declares the producer method or field is used.

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, 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, 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 an observed event type that is a type variable if the event type is assignable to the upper bound of the type variable, 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 observed event 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 one or more of its notified observers, the CompletionStage returned by fireAsync will complete exceptionally with java.util.concurrent.CompletionException. 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.

If the target method is static, the instance is ignored; by convention, it should be null. If the target method is not static and instance is null, a RuntimeException is thrown. If the target method is not static and the instance is not permissible for the target method, a RuntimeException is thrown.

The instance is permissible for the target method when:

Correspondence between given arguments and declared parameters of the target method is positional: the Nth element of the arguments array is passed as the Nth argument to the target method. If the target method is a variable arity method, the last element of the arguments array corresponds to the variable arity parameter (and therefore must be an array). When passing an argument to the method, the applicable method invocation conversion is performed.

If the target method declares no parameter, arguments are ignored. If the target method declares any parameter and arguments is null, RuntimeException is thrown. If the arguments array has fewer elements than the number of parameters of the target method, RuntimeException is thrown. If the arguments array has more elements than the number of parameters of the target method, the excess elements are ignored. If a method invocation conversion does not exist from the class of some of the arguments (or from the null type if the argument is null) to the declared type of the corresponding parameter of the target method, RuntimeException is thrown.

When the declared type of a parameter of the target method is not a reifiable type, callers of Invoker.invoke() must ensure that the corresponding argument is constructed appropriately. Otherwise, runtime failures are likely to occur.

If the target method returns normally, its return value is returned (after boxing conversion if the target method’s return type is a primitive type), unless the target method is declared void, in which case null is returned. If the target method throws an exception, it is rethrown directly.

To illustrate how method invokers work, let’s take a look at an example. Say that the following bean exists in an application and has a method that you, the framework author, want to invoke indirectly:

In a CDI extension, you obtain an InvokerBuilder for the hello() method and use it to build an invoker. In a portable extension (see Using InvokerBuilder in CDI Full), this results in an invoker which should be stored for later usage:

In a build compatible extension (see Using InvokerBuilder), this results in an opaque token that materializes as an Invoker at application runtime:

To call the hello() method through this invoker, assuming that myService is a contextual reference for the bean, call:

The return value is "Hello world!".

Internally, the container will create an implementation of the invoker, equivalent to the following class:

The InvokerBuilder allows configuring that the instance or any of the arguments passed to Invoker.invoke() should be ignored and a value should be looked up from the CDI container instead.

When withInstanceLookup() is called on an invoker builder and the target method is not static, the invoke() method of the built invoker shall ignore the instance argument and instead obtain and use a contextual reference for the target bean and the bean type that declares the target method. Calling withInstanceLookup() on an invoker builder for a static target method has no effect.

When withArgumentLookup() is called on an invoker builder, the invoke() method of the built invoker shall ignore the given element of the arguments array and instead:

Calling withArgumentLookup() with position less than 0 or greater than or equal to the number of parameters of the target method leads to an IllegalArgumentException.

Configuring a lookup using withInstanceLookup() or withArgumentLookup() does not relax the requirements defined in Behavior of invoke(). Notably, the arguments array must still have an element for each argument, regardless of whether a lookup was configured for it. This means that for a target method with N parameters, the arguments array must always have at least N elements.

In the following paragraphs, the beans whose instances shall be obtained by Invoker.invoke() as a result of calling withInstanceLookup() and withArgumentLookup() are called looked up beans.

During deployment validation, implementations are required to identify all looked up beans for all built invokers, as described above. It is a deployment problem if an attempt to identify a looked up bean results in an unsatisfied dependency or an ambiguous dependency that is not resolvable. Implementations are permitted to remember the identified beans and not repeat the resolution process for each invocation of Invoker.invoke().

All instances of @Dependent looked up beans obtained during Invoker.invoke() are destroyed before the invoke() method returns or throws. The order in which the instances of @Dependent looked up beans are destroyed is not specified.

This specification recognizes the existence of asynchronous methods, where the action represented by the method does not always finish when the method returns; the completion of the action is asynchronous to the method call. For target methods that are considered asynchronous by the CDI container, the requirement to destroy instances of @Dependent looked up beans is relaxed: the instances of @Dependent looked up beans need not be destroyed before Invoker.invoke() returns. It is recommended that the instances of @Dependent looked up beans are destroyed after the asynchronous action completes and before the completion is propagated to the caller of Invoker.invoke(); if an asynchronous target method completes synchronously or throws synchronously, it is recommended that the instances of @Dependent looked up beans are destroyed before invoke() returns or rethrows the exception.

The order in which instances of looked up beans are obtained during Invoker.invoke() in not specified.

If an exception is thrown when creating an instance of a looked up bean during Invoker.invoke(), the exception is rethrown.

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.

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.getContexts() retrieves all context objects, active and inactive, associated with the given scope, as defined in Scopes and contexts.

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.

The methods BeanContainer.isMatchingBean() and isMatchingEvent() provide access to assignability rules defined in Typesafe resolution and Observer resolution.