[weld-commits] Weld SVN: r4338 - api/trunk/cdi/src/main/java/javax/enterprise/inject/spi.

[weld-commits at lists.jboss.org]

Author: dallen6
Date: 2009-10-26 14:14:09 -0400 (Mon, 26 Oct 2009)
New Revision: 4338

Modified:
   api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Producer.java
Log:
Added JavaDoc for Producer

Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Producer.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Producer.java	2009-10-26 17:34:51 UTC (rev 4337)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Producer.java	2009-10-26 18:14:09 UTC (rev 4338)
@@ -21,18 +21,68 @@
 import javax.enterprise.context.spi.CreationalContext;
 
 /**
+ * <p>
  * The interface {@link javax.enterprise.inject.spi.Producer} provides a generic
  * operation for producing an instance of a type.
+ * </p>
  * 
  * @author Pete Muir
- * 
+ * @author David Allen
  * @param <T> The class of object produced by the producer
  */
 public interface Producer<T>
 {
+   /**
+    * <p>
+    * Causes an instance to be produced via the {@code Producer}.
+    * </p>
+    * <p>
+    * If the {@code Producer} represents a class, this will invoke the
+    * constructor annotated {@link javax.inject.Inject} if it exists, or the
+    * constructor with no parameters. If the class has interceptors, produce()
+    * is responsible for building the interceptor and decorator stacks for the
+    * instance.
+    * </p>
+    * <p>
+    * If the {@code Producer} represents a producer field or method, this will
+    * invoke the producer method on, or access the producer field of, a
+    * contextual instance of the bean that declares the producer.
+    * </p>
+    * 
+    * @param ctx The {@link javax.enterprise.context.spi.CreationalContext} to
+    *           use for the produced object
+    * @return an instance of the produced object
+    */
    public T produce(CreationalContext<T> ctx);
 
+   /**
+    * <p>
+    * Destroys the instance.
+    * </p>
+    * <p>
+    * If the {@code Producer} represents a class, then this operation does
+    * nothing. Otherwise, this calls the disposer method, if any, on a
+    * contextual instance of the bean that declares the disposer method or
+    * performs any additional required cleanup, if any, to destroy state
+    * associated with a resource.
+    * 
+    * @param instance The instance to dispose
+    */
    public void dispose(T instance);
 
+   /**
+    * <p>
+    * Returns the set of all {@code InjectionPoints} for the producer. If the
+    * {@code Producer} represents a class, then this returns returns the set of
+    * {@code InjectionPoint} objects representing all injected fields, bean
+    * constructor parameters and initializer method parameters. For a producer
+    * method, this returns the set of {@code InjectionPoint} objects
+    * representing all parameters of the producer method.
+    * </p>
+    * 
+    * @return the set of all
+    *         {@linkplain javax.enterprise.inject.spi.InjectionPoint injection
+    *         points} for the producer
+    */
    public Set<InjectionPoint> getInjectionPoints();
 }
\ No newline at end of file