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
Instance<T> Allows the application to dynamically obtain instances of beans with a specified combination of required type and qualifiers.
 

Exception Summary
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
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:

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

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:

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.

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

If a session bean is a stateful session bean:

Producer methods and fields

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

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.

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:

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:

Dependency injection

A bean is assignable to a given injection point if:

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

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:

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:

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:

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


Copyright © 2008-2009 Seam Framework. All Rights Reserved.