Author: gavin.king(a)jboss.com Date: 2009-10-25 20:26:45 -0400 (Sun, 25 Oct 2009) New Revision: 4317 Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/Dependent.java Log: doc @Dependent Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/Dependent.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/context/Dependent.java 2009-10-25 23:16:04 UTC (rev 4316) +++ api/trunk/cdi/src/main/java/javax/enterprise/context/Dependent.java 2009-10-26 00:26:45 UTC (rev 4317) @@ -27,11 +27,74 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +import javax.enterprise.context.spi.Contextual; import javax.inject.Scope; /** - * Specifies that a bean is dependent scoped. + * <p>Specifies that a bean belongs to the dependent pseudo-scope.</p> * + * <p>Beans declared with scope <tt>@Dependent</tt> behave differently + * to beans with other built-in scope types. When a bean is declared + * to have scope <tt>@Dependent</tt>:</p> + * + * <ul> + * <li>No injected instance of the bean is ever shared between + * multiple injection points.</li> + * <li>Any instance of the bean injected into an object that is being + * created by the container is bound to the lifecycle of the newly + * created object.</li> + * <li>When a Unified EL expression in a JSF or JSP page that refers + * to the bean by its EL name is evaluated, at most one instance of + * the bean is instantiated. This instance exists to service just a + * single evaluation of the EL expression. It is reused if the bean + * EL name appears multiple times in the EL expression, but is never + * reused when the EL expression is evaluated again, or when another + * EL expression is evaluated.</li> + * <li>Any instance of the bean that receives a producer method, + * producer field, disposer method or observer method invocation + * exists to service that invocation only.</li> + * <li>Any instance of the bean injected into method parameters of a + * disposer method or observer method exists to service the method + * invocation only.</li> + * </ul> + * + * <p>Every invocation of the + * {@link javax.enterprise.context.spi.Context#get(Contextual, CreationalContext)} + * operation of the context object for the <tt>@Dependent</tt> scope + * returns a new instance of the given bean.</p> + * + * <p>Every invocation of the + * {@link javax.enterprise.context.spi.Context#get(Contextual)} + * operation of the context object for the <tt>@Dependent</tt> scope + * returns a null value.</p> + * + * <p>The <tt>@Dependent</tt> scope is always active.</p> + * + * <p>Many instances of beans with scope <tt>@Dependent</tt> belong + * to some other bean or Java EE component class instance and are + * called dependent objects.</p> + * + * <ul> + * <li>Instances of decorators and interceptors are dependent + * objects of the bean instance they decorate.</li> + * <li>An instance of a bean with scope <tt>@Dependent</tt> injected + * into a field, bean constructor or initializer method is a dependent + * object of the bean or Java EE component class instance into + * which it was injected.</li> + * <li>An instance of a bean with scope <tt>@Dependent</tt> injected + * into a producer method is a dependent object of the producer method + * bean instance that is being produced.</li> + * <li>An instance of a bean with scope <tt>@Dependent</tt> obtained by + * direct invocation of an {@link javax.enterprise.inject.Instance} is + * a dependent object of the instance of + * {@link javax.enterprise.inject.Instance}.</li> + * </ul> + * + * <p>When the container destroys an instance of a bean or of any Java + * EE component class supporting injection, the container destroys all + * its dependent objects, after the <tt>@PreDestroy</tt> callback completes + * and after the servlet <tt>destroy()</tt> method is called.</p> + * * @author Gavin King * @author Pete Muir */