svn commit: r1427694 - in /geronimo/specs/trunk/geronimo-jcdi_1.1_spec/src/main/java/javax/enterprise: context/spi/CreationalContext.java inject/spi/BeanManager.java

[st...@apache.org]

Author: struberg
Date: Wed Jan  2 08:09:27 2013
New Revision: 1427694

URL: http://svn.apache.org/viewvc?rev=1427694&view=rev
Log:
GERONIMO-6182 add/fix JavaDoc

Modified:
    geronimo/specs/trunk/geronimo-jcdi_1.1_spec/src/main/java/javax/enterprise/context/spi/CreationalContext.java
    geronimo/specs/trunk/geronimo-jcdi_1.1_spec/src/main/java/javax/enterprise/inject/spi/BeanManager.java

Modified: geronimo/specs/trunk/geronimo-jcdi_1.1_spec/src/main/java/javax/enterprise/context/spi/CreationalContext.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-jcdi_1.1_spec/src/main/java/javax/enterprise/context/spi/CreationalContext.java?rev=1427694&r1=1427693&r2=1427694&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-jcdi_1.1_spec/src/main/java/javax/enterprise/context/spi/CreationalContext.java (original)
+++ geronimo/specs/trunk/geronimo-jcdi_1.1_spec/src/main/java/javax/enterprise/context/spi/CreationalContext.java Wed Jan  2 08:09:27 2013
@@ -19,22 +19,29 @@
 package javax.enterprise.context.spi;
 
 /**
- * The CreationalContext holds incomplete Bean instances. This may be caused by
- * a situation like in the following example: <code>
- * &#x0040;ApplicationScoped class Foo 
- * { 
- *   &#x0040;Current Bar _bar; 
- * }
- * 
- * &#x0040;ApplicationScoped class Bar 
- * { 
- *   &#x0040;Current Foo _bar; 
- * } 
- * </code>
- * 
- * <p>
- * Generally it is used for prohibiting the circular references of the webbeans.
+ * <p>The <code>CreationalContext</code> holds incomplete Bean instances and
+ * references to all{@link javax.enterprise.context.Dependent} scoped
+ * contextual instances injected into a {@link javax.enterprise.context.NormalScope}d
+ * bean.</p>
+ *
+ * <p>E.g. consider we create a Contextual Instance of a
+ * {@link javax.enterprise.context.SessionScoped} <code>UserInformation</code>
+ * bean which has a dependent injection point
+ * (e.g. a field <code>private &#064;Inject Helper helper;</code> )
+ * In that case the CreationalContext of the <code>UserInformation</code> instance
+ * will contain the information about the <code>helper</code> instance.
+ * This is needed to properly destroy the <code>helper</code> once the
+ * <code>UserInformation</code> gets destroyed. In our example this will
+ * happen at the end of the Session.
  * </p>
+ *
+ * <p><b>Attention:</b> If you create a {@link javax.enterprise.context.Dependent} instance
+ * manually using
+ * {@link javax.enterprise.inject.spi.BeanManager#getReference(javax.enterprise.inject.spi.Bean, java.lang.reflect.Type, CreationalContext)}
+ * then you must store away the CreationalContext. You will need it for properly destroying the created instance
+ * via {@link javax.enterprise.inject.spi.Bean#destroy(Object, CreationalContext)}.
+ * This is <i>not</i> needed for {@link javax.enterprise.context.NormalScope}d beans as they
+ * maintain their lifecycle themself!</p>
  * 
  * @version $Rev$ $Date$
  */

Modified: geronimo/specs/trunk/geronimo-jcdi_1.1_spec/src/main/java/javax/enterprise/inject/spi/BeanManager.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-jcdi_1.1_spec/src/main/java/javax/enterprise/inject/spi/BeanManager.java?rev=1427694&r1=1427693&r2=1427694&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-jcdi_1.1_spec/src/main/java/javax/enterprise/inject/spi/BeanManager.java (original)
+++ geronimo/specs/trunk/geronimo-jcdi_1.1_spec/src/main/java/javax/enterprise/inject/spi/BeanManager.java Wed Jan  2 08:09:27 2013
@@ -35,27 +35,18 @@ import javax.enterprise.inject.Unsatisfi
 
 
 /**
- * The interface <code>Manager</code> provides operations for
- * obtaining the contextual instance of the webbeans. There are operations
- * related with;
+ * <p>The interface <code>BeanManager</code> is the central point for dealing with CDI.
+ * The BeanManager provides operations for resolving CDI {@link Bean}s,
+ * obtaining the Contextual References of them, etc. There are operations
+ * related with;</p>
  * 
  * <ul>
- *  <li>Adding new webbeans</li>
- *  <li>Adding new contexts</li>
- *  <li>Adding new decorators</li>
- *  <li>Adding new interceptors</li>
- *  <li>Firing the observer events</li>
- *  <li>Creating the instance of the contextual beans</li>
+ *  <li>Firing observer events</li>
+ *  <li>Creating {@link CreationalContext}s</li>
  *  <li>Resolution of beans, interceptors, decorators and observers</li>
  *  <li>Other utility methods etc..</li>
  * </ul>
- * 
- * <p>
- * There is always one root manager in the system. You can set the
- * current activity via call to the {@link BeanManager#setCurrent(Class)} method.
- * </p>
- * 
- * @version $Rev$ $Date$ 
+ *
  */
 public interface BeanManager
 {
@@ -259,7 +250,7 @@ public interface BeanManager
     public Context getContext(Class<? extends Annotation> scope);
     
     /**
-     * Returns el resolver.
+     * Returns CDI container Expression Language resolver.
      * 
      * @return el resolver
      */
@@ -276,7 +267,7 @@ public interface BeanManager
     public <T> AnnotatedType<T> createAnnotatedType(Class<T> type);
     
     /**
-     * Creates a new instance of injection target.
+     * Creates a new instance of injection target Bean.
      * 
      * @param <T> bean type
      * @param type annotated type
@@ -285,9 +276,9 @@ public interface BeanManager
     public <T> InjectionTarget<T> createInjectionTarget(AnnotatedType<T> type);
     
     /**
-     * Wrapped around given expression factory.
+     * Wrapped around given expression factory and add CDI functionality.
      * @param expressionFactory expression factory
      * @return wrapped expression factory
      */
     public ExpressionFactory wrapExpressionFactory(javax.el.ExpressionFactory expressionFactory);
-}
\ No newline at end of file
+}