javax.enterprise.inject
Date: 2015-09-11

# Package javax.enterprise.inject

Annotations relating to bean and stereotype definition, built-in qualifiers, and interfaces and classes relating to programmatic lookup.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  Instance<T> | Allows the application to dynamically obtain instances of beans with a specified combination of required type and qualifiers.

- Exception Summary
  Exception | Description
  --- | ---
  AmbiguousResolutionException | Indicates that multiple beans match a certain combination of required type and required qualifiers and are eligible for injection into a certain class.
  CreationException | Indicates that a checked exception was thrown during creation of a bean.
  IllegalProductException | Indicates that a producer method returned a null value or a producer field contained a null value, and the scope of the producer method or field was not `Dependent`.
  InjectionException | Indicates a problem relating to dependency injection.
  ResolutionException | Indicates a problem relating to typesafe resolution.
  UnproxyableResolutionException | Indicates that a contextual reference for a bean with a normal scope and a certain bean type cannot be obtained because the bean type cannot be proxied by the container.
  UnsatisfiedResolutionException | Indicates that no bean matches a certain combination of required type and required qualifiers and is eligible for injection into a certain class.

- Annotation Types Summary
  Annotation Type | Description
  --- | ---
  Alternative | Specifies that a bean is an alternative.
  Any | The built-in qualifier type.
  Default | The default qualifier type.
  Disposes | Identifies the disposed parameter of a disposer method.
  Model | The built-in stereotype intended for use with beans that define the model layer of an MVC web application architecture such as JSF.
  New | The built-in qualifier type.
  Produces | Identifies a producer method or field.
  Specializes | Indicates that a bean directly specializes another bean.
  Stereotype | Specifies that an annotation type is a stereotype.
  Typed | Restricts the bean types of a bean.

## Package javax.enterprise.inject Description

Annotations relating to bean and stereotype definition, built-in qualifiers, and interfaces and classes relating to programmatic lookup.

A bean is a source of contextual objects which define application state and/or logic. These objects are called contextual instances of the bean. The container creates and destroys these instances and associates them with the appropriate context. Contextual instances of a bean may be injected into other objects (including other bean instances) that execute in the same context, and may be used in Unified EL expressions that are evaluated in the same context.

The lifecycle of contextual instances is managed by the container according to the lifecycle context model. Annotations define the lifecycle of the bean and its interactions with other beans.

A bean comprises the following attributes:

- A (nonempty) set of bean types
- A (nonempty) set of qualifiers
- A scope
- Optionally, a bean EL name
- A set of interceptor bindings
- A bean implementation

### Bean types

A bean type is a client-visible type of the bean. A bean may have multiple bean types. The following bean has bean types `BookShop`, `Business`, `Shop<Book>` and `Object`.

     public class BookShop
           extends Business
           implements Shop<Book> {
        ...
     }

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

- A bean type may be an interface, a concrete class or an abstract class, and may be declared final or have final methods.
- A bean type may be a parameterized type with actual type parameters and type variables.
- A bean type may be an array type. Two array types are considered identical only if the element type is identical.
- A bean type may be a primitive type. Primitive types are considered to be identical to their corresponding wrapper types in `java.lang`.
- A bean type may be a raw type.

A type variable is not a legal bean type. A parameterized type that contains a wildcard type parameter is not a legal bean type.

The bean types of a bean are determined automatically. However, the set of bean types may be resticted using the `@Typed` annotation.

### Qualifiers

A qualifier represents some client-visible semantic associated with a type that is satisfied by some implementations of the type (and not by others). Qualifiers are applied to injection points to distinguish which implementation is required by the client.

     @Inject @Synchronous PaymentProcessor paymentProcessor;

A qualifier type is a Java annotation annotated `@Qualifier`. The qualifiers of a bean are declared by annotating the bean class or producer method or field with the qualifier types.

     @Synchronous @Reliable
     class SynchronousReliablePaymentProcessor
           implements PaymentProcessor {
        ...
     }

If a bean does not explicitly declare a qualifier other than `@Named`, the bean has the qualifier `@Default`.

### Scope

All beans have a scope. The scope of a bean determines the lifecycle of its instances, and which instances of the bean are visible to instances of other beans.

A scope type is a Java annotation annotated `@Scope` or `@NormalScope`. The scope of a bean is defined by annotating the bean class or producer method or field with a scope type or with a stereotype that declares a default scope.

     @ConversationScoped
     public class Order { ... }

A bean class or producer method or field may specify at most one scope type annotation.

If the bean does not explicitly declare a scope or a stereotype with a default scope, the scope defaults to `@Dependent`.

### Bean EL name

A bean may have a bean EL name. A bean with an EL name may be referred to by its name in Unified EL expressions. A valid bean EL name is a period-separated list of valid EL identifiers.

To specify the EL name of a bean, the qualifier `@Named` is applied to the bean class or producer method or field.

     @Named("currentOrder")
     public class Order { ... }

If the `@Named` annotation does not specify the `value` member, the EL name is defaulted.

### Interceptor bindings

Interceptors may be bound to any managed bean that is not itself an interceptor or decorator or to any EJB session or message-driven bean. An interceptor that is annotated `@Interceptor` may be identified by its interceptor bindings.

     @Transactional @Interceptor
     public class TransactionInterceptor {
        @AroundInvoke
        public Object manageTransaction(InvocationContext ctx) { ... }
     }

An interceptor binding type is a Java annotation annotated `@InterceptorBinding`. An interceptor binding of a bean may be declared by annotating the bean class, or a method of the bean class, with an interceptor binding type or with a stereotype that declares the interceptor binding.

In the following example, the `TransactionInterceptor` will be applied at the class level, and therefore applies to all business methods of the class:

     @Transactional
     public class ShoppingCart { ... }

In this example, the `TransactionInterceptor` will be applied at the method level:

     public class ShoppingCart {
        @Transactional
        public void placeOrder() { ... }
     }

If a managed bean class is declared final, it may not have any interceptor bindings. If a managed bean has a non-static, non-private, final method, it may not have any class-level interceptor bindings, and that method may not have any method-level interceptor bindings.

### Bean implementation

The container provides built-in support for injection and contextual lifecycle management of the following kinds of bean:

- Managed beans
- Session beans
- Producer methods and fields
- Resources (Java EE resources, persistence contexts, persistence units, remote EJBs and web services)

#### Managed beans

A managed bean is a bean that is implemented by a Java class. The basic lifecycle and semantics of managed beans are defined by the Managed Beans specification.

A top-level Java class is a managed bean if it is defined to be a managed bean by any other Java EE specification, or if it meets all of the following conditions:

- It is not a non-static inner class.
- It is a concrete class, or is annotated `@Decorator`.
- It is not annotated with an EJB component-defining annotation or declared as an EJB bean class in `ejb-jar.xml`.
- It does not implement `Extension`.
- It has an appropriate constructor; either the class has a constructor with no parameters, or the class declares a constructor annotated `@Inject`.

All Java classes that meet these conditions are managed beans and thus no special declaration is required to define a managed bean. Optionally, a managed bean may be annotated `javax.annotation.ManagedBean`.

If a managed bean has a public field, it must have scope `@Dependent`.

If the managed bean class is a generic type, it must have scope `@Dependent`.

#### Session beans

The basic lifecycle and semantics of EJB session beans are defined by the EJB specification.

- A stateless session bean must belong to the `@Dependent` pseudo-scope.
- A singleton bean must belong to either the `@ApplicationScoped` scope or to the `@Dependent` pseudo-scope.
- A stateful session bean may have any scope.

If the session bean class is a generic type, it must have scope `@Dependent`.

If a session bean is a stateful session bean:

- If the scope is `@Dependent`, the application may call any EJB remove method of a contextual instance of the session bean.
- Otherwise, the application may not directly call any EJB remove method of any contextual instance of the session bean.

#### Producer methods and fields

A producer method or field acts as a source of objects to be injected, where:

- the objects to be injected are not required to be instances of beans, or
- the concrete type of the objects to be injected may vary at runtime, or
- the objects require some custom initialization that is not performed by the bean constructor.

A producer method or field is a method or field of a bean class annotated `@Produces`.

A common pattern in generic code is a producer method that injects an `InjectionPoint` object.

#### Resources

A resource is a bean that represents a reference to a resource, persistence context, persistence unit, remote EJB or web service in the Java EE component environment.

A resource may be declared by specifying a Java EE component environment injection annotation as part of a producer field declaration.

- For a Java EE resource, `@Resource` must be specified.
- For a persistence context, `@PersistenceContext` must be specified.
- For a persistence unit, `@PersistenceUnit` must be specified.
- For a remote EJB, `@EJB` must be specified.
- or a web service, `@WebServiceRef` must be specified.

The injection annotation specifies the metadata needed to obtain the resources, entity manager, entity manager factory, remote EJB instance or web service reference from the component environment.

     @Produces @WebServiceRef(lookup="java:app/service/PaymentService")
     PaymentService paymentService;

     @Produces @EJB(ejbLink="../their.jar#PaymentService")
     PaymentService paymentService;

     @Produces @Resource(lookup="java:global/env/jdbc/CustomerDatasource")
     @CustomerDatabase Datasource customerDatabase;

     @Produces @PersistenceContext(unitName="CustomerDatabase")
     @CustomerDatabase EntityManager customerDatabasePersistenceContext;

     @Produces @PersistenceUnit(unitName="CustomerDatabase")
     @CustomerDatabase EntityManagerFactory customerDatabasePersistenceUnit;

A resource may not have an EL name.

### Enabled and disabled beans

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, and either
- it is not an alternative, or it is a selected alternative of at least one bean archive.

Otherwise, the bean is said to be disabled.

### Inter-module injection

Beans and their clients may be deployed in modules in a module architecture such as the Java EE environment. In a module architecture, certain modules are considered bean archives. In the Java EE module architecture, any Java EE module or library is a module. The Java EE module or library is a bean archive if it contains a `beans.xml` file in the metadata directory.

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, and
- the bean class is required to be accessible to classes in the module, according to the class accessibility requirements of the module architecture.

### Dependency injection

A bean is assignable to a given injection point if:

- The bean has a bean type that matches the type of the injection point. For this purpose, primitive types are considered to match their corresponding wrapper types in `java.lang` and array types are considered to match only if their element types are identical.
- The bean has all the qualifiers of the injection point. If the injection point does not explicitly declare a qualifier, it has the default qualifier `@Default`.
- The bean is eligible for injection into the class that declares the injection point.

A bean is eligible for injection into a given injection point if:

- it is available for injection in the module that contains the class that declares the injection point, and
- it is assignable to the injection point.

If more than one bean is eligible for injection to the injection point, the container attempts to resolve the ambiguity by eliminating all beans which are not alternatives, except for producer methods and fields of beans that are alternatives.

Certain legal bean types cannot be proxied by the container:

- classes which don't have a non-private constructor with no parameters,
- classes which are declared final or have final methods,
- primitive types,
- and array types.

An injection point whose declared type cannot be proxied by the container must not resolve to a bean with a normal scope.

### EL name resolution

EL names are resolved when Unified EL expressions are evaluated. An EL name resolves to a bean if:

- the bean has the given EL name, and
- the bean is available for injection in the war containing the JSP or JSF page with the EL expression.

If an EL name resolves to more than one bean, the container attempts to resolve the ambiguity by eliminating all beans which are not alternatives, except for producer methods and fields of beans that are alternatives.

### Enabled interceptors

By default, a bean archive has no enabled interceptors. An interceptor must be explicitly enabled by listing its bean class under the `<interceptors>` element of the `beans.xml` file of the bean archive. The order of the interceptor declarations determines the interceptor ordering. Interceptors which occur earlier in the list are called first.

An interceptor is bound to a bean if:

- The bean has all the interceptor bindings of the interceptor.
- The interceptor is enabled in the bean archive of the bean.

An interceptor instance is a dependent object of the object it intercepts.

See Also:
  `javax.enterprise.context`, `javax.inject`, `javax.interceptor`, `javax.decorator`, `javax.enterprise.event`, `Produces`, `Alternative`