[weld-commits] Weld SVN: r4317 - api/trunk/cdi/src/main/java/javax/enterprise/context.

[weld-commits at lists.jboss.org]

Author: gavin.king at 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
  */