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

[weld-commits at lists.jboss.org]

Author: gavin.king at jboss.com
Date: 2009-10-23 21:44:44 -0400 (Fri, 23 Oct 2009)
New Revision: 4251

Modified:
   api/trunk/cdi/src/main/java/javax/enterprise/inject/Disposes.java
   api/trunk/cdi/src/main/java/javax/enterprise/inject/Produces.java
Log:
javadoc for @Disposes

Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/Disposes.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/inject/Disposes.java	2009-10-24 01:25:32 UTC (rev 4250)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/Disposes.java	2009-10-24 01:44:44 UTC (rev 4251)
@@ -25,9 +25,52 @@
 import java.lang.annotation.Target;
 
 /**
- * Specifies that a parameter of a method of bean is the disposed parameter 
- * of a disposal method.
+ * <p>Identifies the disposed parameter of a disposer method.
+ * May be applied to a parameter of a method of a bean class.</p>
  * 
+ * <pre>
+ * public class UserDatabaseEntityManager {
+ *
+ *    &#064;Produces &#064;ConversationScoped &#064;UserDatabase
+ *    public EntityManager create(EntityManagerFactory emf) {
+ *       return emf.createEntityManager();
+ *    }
+ *    
+ *    public void close(&#064;Disposes &#064;UserDatabase EntityManager em) {
+ *       em.close();
+ *    }
+ *
+ * }
+ * </pre>
+ * 
+ * <p>A disposer method allows the application to perform 
+ * customized cleanup of an object returned by a 
+ * {@linkplain javax.enterprise.inject.Produces producer method}.</p>
+ * 
+ * <p>A disposer method must be a non-abstract method of a 
+ * managed bean class  or session bean class. A disposer 
+ * method may be either static or non-static. If the bean is 
+ * a session bean, the disposer method must be a business 
+ * method of the EJB or a static method of the bean class.</p>
+ * 
+ * <p>A bean may declare multiple disposer methods.</p>
+ * 
+ * <p>Each disposer method must have exactly one disposed 
+ * parameter, of the same type as the corresponding producer 
+ * method return type. When searching for disposer methods 
+ * for a producer method, the container considers the type 
+ * and qualifiers of the disposed parameter. If a disposed 
+ * parameter resolves to a producer method declared by the 
+ * same bean class, the container must call this method when 
+ * destroying any instance returned by that producer method.</p>
+ * 
+ * <p>A disposer method may resolve to multiple producer 
+ * methods declared by the bean class, in which case the 
+ * container must call it when destroying any instance 
+ * returned by any of these producer methods.</p> 
+ * 
+ * @see javax.enterprise.inject.Produces &#064;Produces
+ * 
  * @author Gavin King
  * @author Pete Muir
  */

Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/Produces.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/inject/Produces.java	2009-10-24 01:25:32 UTC (rev 4250)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/Produces.java	2009-10-24 01:44:44 UTC (rev 4251)
@@ -91,6 +91,8 @@
  * <p>Interceptors and decorators may not declare producer methods 
  * or fields.</p>
  * 
+ * @see javax.enterprise.inject.Disposes &#064;Disposes
+ * 
  * @author Gavin King
  * @author Pete Muir
  */