javax.enterprise.inject.package-info Maven / Gradle / Ivy
Show all versions of cdi-api Show documentation
/*
* JBoss, Home of Professional Open Source
* Copyright 2010, Red Hat, Inc., and individual contributors
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* 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
* {@linkplain 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
* {@linkplain javax.enterprise.context 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 {@link 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
* {@link javax.enterprise.inject.Typed @Typed} annotation.
*
* Qualifiers
*
* A {@linkplain javax.inject.Qualifier 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
* {@link javax.inject.Qualifier @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
* {@link javax.inject.Named @Named}, the bean has the qualifier
* {@link javax.enterprise.inject.Default @Default}.
*
* Scope
*
* All beans have a {@linkplain javax.enterprise.context 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
* {@link javax.inject.Scope @Scope} or
* {@link 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
* {@link 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 {@linkplain 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
* {@link javax.inject.Named @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
* {@link javax.inject.Named#value() value} member, the EL name is defaulted.
*
* Interceptor bindings
*
* {@linkplain 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
* {@link 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
* {@link 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
* {@link 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 {@link 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
* {@link javax.inject.Inject @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 {@link javax.annotation.ManagedBean}.
*
* If a managed bean has a public field, it must have scope
* {@link javax.enterprise.context.Dependent @Dependent}.
*
* If the managed bean class is a generic type, it must have scope
* {@link javax.enterprise.context.Dependent @Dependent}.
*
* Session beans
*
* The basic lifecycle and semantics of EJB session beans are defined by the
* EJB specification.
*
*
* - A {@linkplain javax.ejb.Stateless stateless session bean} must belong to
* the {@link javax.enterprise.context.Dependent @Dependent} pseudo-scope.
* - A {@linkplain javax.ejb.Singleton singleton bean} must belong to either the
* {@link javax.enterprise.context.ApplicationScoped @ApplicationScoped}
* scope or to the {@link javax.enterprise.context.Dependent @Dependent}
* pseudo-scope.
* - A {@linkplain javax.ejb.Stateful stateful session bean} may have any scope.
*
*
* If the session bean class is a generic type, it must have scope
* {@link javax.enterprise.context.Dependent @Dependent}.
*
* If a session bean is a stateful session bean:
*
*
* - If the scope is {@link 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 {@linkplain javax.enterprise.inject.Produces 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
* {@link javax.enterprise.inject.Produces @Produces}.
*
* A common pattern in generic code is a producer method that injects an
* {@link 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
* {@linkplain javax.enterprise.inject.Produces producer method or field}
* of a disabled bean, and
* - it is not {@linkplain javax.enterprise.inject.Specializes specialized}
* by any other enabled bean, and either
* - it is not an {@linkplain javax.enterprise.inject.Alternative 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.
*
*
* Injection points
*
* The following kinds of injection point exist:
*
*
* - When the container instantiates a bean class, it calls the bean constructor.
* The bean constructor is a constructor of the bean class. The bean constructor may
* be identified by annotating the constructor
* {@link javax.inject.Inject @javax.inject.Inject}. If a bean class does not
* explicitly declare a constructor using @Inject, the constructor that
* accepts no parameters is the bean constructor. A bean constructor may have any number
* of parameters. All parameters of a bean constructor are injection points.
* - An injected field is a non-static, non-final field of a bean class, or of any
* Java EE component class supporting injection. An injected field may be declared by
* annotating the field {@link javax.inject.Inject @javax.inject.Inject}.
* - An initializer method is a non-abstract, non-static, non-generic method of a
* bean class, or of any Java EE component class supporting injection. If the bean is
* a session bean, the initializer method is not required to be a business method of
* the session bean. An initializer method may be declared by annotating the method
* {@link javax.inject.Inject @javax.inject.Inject}. An initializer method may
* have any number of parameters. All initializer method parameters are injection
* points.
* - Finally, parameters of {@linkplain javax.enterprise.inject.Produces producer methods},
* {@linkplain javax.enterprise.inject.Disposes diposer methods} and
* {@linkplain javax.enterprise.event.Observes observer methods} are injection points.
*
*
* 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 {@link 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
* {@link javax.enterprise.inject.Default @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 {@linkplain javax.enterprise.context 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
* {@linkplain javax.enterprise.context.Dependent dependent object}
* of the object it intercepts.
*
* @see javax.enterprise.context
* @see javax.inject
* @see javax.interceptor
* @see javax.decorator
* @see javax.enterprise.event
*
* @see javax.enterprise.inject.Produces
* @see javax.enterprise.inject.Alternative
*
*/
package javax.enterprise.inject;