injectionandresolution_full.asciidoc

Dependency injection and lookup in {cdi_full}

Modularity in {cdi_full}

In addition to rules defined in [selection], the following rules apply.

An alternative is not available for injection, lookup or name resolution to classes in a module unless the module is a bean archive and the alternative is explicitly selected for the bean archive or the application.

Declaring selected alternatives in {cdi_full}

{cdi_full} provides an additional way to select alternatives to the one defined in [declaring_selected_alternatives_application].

Declaring selected alternatives for an application in {cdi_full}

In addition to rules defined in [declaring_selected_alternatives_application], the following rule applies.

Custom bean implementations which are also alternatives may implement Prioritized interface in which case they will be enabled for entire application with given priority.

Declaring selected alternatives for a bean archive

An alternative may be explicitly declared using the <alternatives> element of the beans.xml file of the bean archive. The <alternatives> element contains a list of bean classes and stereotypes. An alternative is selected for the bean archive if either:

• the alternative is a managed bean and the bean class of the bean is listed,

• the alternative is a producer method, field or resource, and the bean class that declares the method or field is listed, or

• any @Alternative stereotype of the alternative is listed.

<beans xmlns="https://jakarta.ee/xml/ns/jakartaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/beans_3_0.xsd"
        version="3.0">
   <alternatives>
      <class>com.acme.myfwk.InMemoryDatabase</class>
      <stereotype>com.acme.myfwk.Mock</stereotype>
      <stereotype>com.acme.site.Australian</stereotype>
   </alternatives>
</beans>

For each child <class> element, the container verifies that either:

• a class with the specified name exists and is annotated with @Alternative or an @Alternative stereotype, or

• a class with the specified name exists and declares a field or method annotated with @Produces and, at the same time, annotated with @Alternative or an @Alternative stereotype, or

• an alternative bean whose bean class has the specified name exists.

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

Each child <stereotype> element must specify the name of an @Alternative stereotype annotation. If there is no annotation with the specified name, or the annotation is not an @Alternative stereotype, the container automatically detects the problem and treats it as a deployment problem.

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

For a custom implementation of the Bean interface defined in [bean], the container calls isAlternative() to determine whether the bean is an alternative, and getBeanClass() and getStereotypes() to determine whether an alternative is selected in a certain bean archive.

Enabled and disabled beans in {cdi_full}

The rules defined in [enablement] are overridden as follows.

A bean is said to be enabled if:

• it is deployed in a bean archive, and

• it is not a producer method or field of a disabled bean, and

• it is not specialized by any other enabled bean, as defined in [specialization], and either

• it is not an alternative, or it is a selected alternative of at least one bean archive or the application.

Otherwise, the bean is said to be disabled.

Inconsistent specialization

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

Inter-module injection in {cdi_full}

Instead of the rules in [inter_module_injection], the following rules apply in {cdi_full}.

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

• the bean is not an interceptor or decorator,

• the bean is enabled,

• the bean is either not an alternative, or the module is a bean archive and the bean is a selected alternative of the bean archive, or the bean is a selected alternative of the application, and

• the bean class is required to be accessible to classes in the module, according to the class accessibility requirements of the module architecture.

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

Typesafe resolution in {cdi_full}

Performing typesafe resolution in {cdi_full}

In addition to rules defined in [performing_typesafe_resolution], the following rules apply.

• Parameterized and raw types are considered to match if they are identical or if the bean type is assignable to the required type, as defined in [assignable_parameters] or [delegate_assignable_parameters].

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

Unsatisfied and ambiguous dependencies in {cdi_full}

In addition to rules defined in [unsatisfied_and_ambig_dependencies], the following rules apply.

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

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

Assignability of raw and parameterized types in {cdi_full}

In addition to rules defined in [assignable_parameters], the following rules apply.

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

Ambiguous names in {cdi_full}

In addition to rules defined in [ambig_names], the following rules apply.

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 bean archive or selected for the application, except for producer methods and fields of beans that are alternatives.

Client proxies in {cdi_full}

In addition to the reasons for indirection defined in [client_proxies], in {cdi_full} client proxies may be passivated, even when the bean itself may not be. Therefore, the container must use a client proxy whenever a bean with normal scope is injected into a bean with a passivating scope, as defined in [passivating_scope]. (On the other hand, beans with scope @Dependent must be serialized along with their client.)

Dependency injection in {cdi_full}

Injection point metadata in {cdi_full}

The behavior of InjectionPoint metadata is overridden as follows:

• The getAnnotated() method returns an instance of jakarta.enterprise.inject.spi.AnnotatedField or jakarta.enterprise.inject.spi.AnnotatedParameter, depending upon whether the injection point is an injected field or a constructor/method parameter. If the injection point represents a dynamically obtained instance, then the getAnnotated() method returns an instance of jakarta.enterprise.inject.spi.AnnotatedField or jakarta.enterprise.inject.spi.AnnotatedParameter representing the Instance injection point, depending upon whether the injection point is an injected field or a constructor/method parameter.

• The isDelegate() method returns true if the injection point is a decorator delegate injection point, and false otherwise. If the injection point represents a dynamically obtained instance then isDelegate() returns false.

If the injection point represents a dynamically obtained instance then the isTransient() method returns true if the Instance injection point is a transient field, and false otherwise. If this injection point is declared as transient, after bean’s passivation, the value will not be restored. Instance<> injection point is the preferred approach.

In {cdi_full}, the built-in implementation of InjectionPoint must be a passivation capable dependency, as defined in [passivation_capable_dependency].

Bean metadata in {cdi_full}

In addition to rules defined in [bean_metadata], the following rules apply.

The interfaces Decorator also provides metadata about a bean.

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

• a bean with scope @Dependent, qualifier @Default and type Decorator which can be injected into any decorator instance

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

• a bean with scope @Dependent, qualifier @Decorated and type Bean which can be injected into any decorator instance.

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

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

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

If:

• the injection point is a field, an initializer method parameter or a bean constructor, with qualifier @Default, then the type parameter of the injected Decorator must be the same as the type declaring the injection point, or

• the injection point is a field, an initializer method parameter or a bean constructor of a decorator, with qualifier @Decorated, then the type parameter of the injected Bean must be the same as the delegate type.

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

Programmatic lookup in {cdi_full}

The Instance interface in {cdi_full}

The built-in Instance in {cdi_full}

In addition to rules defined in [builtin_instance], the built-in implementation of Instance must be a passivation capable dependency, as defined in [passivation_capable_dependency].