javax.enterprise.inject

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 javax.enterprise.context.spi.Context 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 java.lang.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 javax.enterprise.context.NormalScope @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 javax.enterprise.context.Dependent @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 javax.el 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 javax.inject.Named#value() value member, the EL name is defaulted.

Interceptor bindings

javax.interceptor 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 javax.interceptor.Interceptor @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 javax.interceptor.InterceptorBinding @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 javax.decorator.Decorator @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 javax.enterprise.inject.spi.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 javax.enterprise.context.Dependent @Dependent.

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

Session beans

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

• A javax.ejb.Stateless stateless session bean must belong to the javax.enterprise.context.Dependent @Dependent pseudo-scope.
• A javax.ejb.Singleton singleton bean must belong to either the javax.enterprise.context.ApplicationScoped @ApplicationScoped scope or to the javax.enterprise.context.Dependent @Dependent pseudo-scope.
• A javax.ejb.Stateful stateful session bean may have any scope.

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

If a session bean is a stateful session bean:

• If the scope is javax.enterprise.context.Dependent @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 javax.enterprise.inject.spi.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 javax.enterprise.context.Dependent dependent object of the object it intercepts.