[weld-commits] Weld SVN: r5091 - in api/trunk/cdi/src/main/java/javax/enterprise: inject and 1 other directory.

[weld-commits at lists.jboss.org]

Author: gavin.king at jboss.com
Date: 2009-11-17 22:10:00 -0500 (Tue, 17 Nov 2009)
New Revision: 5091

Modified:
   api/trunk/cdi/src/main/java/javax/enterprise/event/Observes.java
   api/trunk/cdi/src/main/java/javax/enterprise/inject/Disposes.java
   api/trunk/cdi/src/main/java/javax/enterprise/inject/Produces.java
   api/trunk/cdi/src/main/java/javax/enterprise/inject/package-info.java
Log:
javadoc injection points

Modified: api/trunk/cdi/src/main/java/javax/enterprise/event/Observes.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/event/Observes.java	2009-11-17 17:14:26 UTC (rev 5090)
+++ api/trunk/cdi/src/main/java/javax/enterprise/event/Observes.java	2009-11-18 03:10:00 UTC (rev 5091)
@@ -50,6 +50,14 @@
  * 
  * <p>The event parameter type may contain a type variable or wildcard.</p>
  * 
+ * <p>In addition to the event parameter, observer methods may declare 
+ * additional parameters, which may declare qualifiers. These additional 
+ * parameters are injection points.</p>
+ * 
+ * <pre>
+ * public void afterLogin(&#064;Observes LoggedInEvent event, &#064;Manager User user, Logger log) { ... }
+ * </pre>
+ * 
  * <p>A bean (or extension) may declare multiple observer methods.</p>
  * 
  * <p>Observer methods are inherited by bean subclasses.</p>

Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/Disposes.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/inject/Disposes.java	2009-11-17 17:14:26 UTC (rev 5090)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/Disposes.java	2009-11-18 03:10:00 UTC (rev 5091)
@@ -64,6 +64,14 @@
  * same bean class, the container must call this method when 
  * destroying any instance returned by that producer method.</p>
  * 
+ * <p>In addition to the disposed parameter, a disposer method 
+ * may declare additional parameters, which may also specify 
+ * qualifiers. These additional parameters are injection points.</p>
+ * 
+ * <pre>
+ * public void close(&#064Disposes &#064UserDatabase EntityManager em, Logger log) { ... }
+ * </pre>
+ *    
  * <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 

Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/Produces.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/inject/Produces.java	2009-11-17 17:14:26 UTC (rev 5090)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/Produces.java	2009-11-18 03:10:00 UTC (rev 5091)
@@ -74,7 +74,20 @@
  * <p>If the producer method return type or producer field type is 
  * a parameterized type with a type variable, it must have scope 
  * {@link javax.enterprise.context.Dependent &#064;Dependent}.</p>
+ *
+ * <p>A producer method may have any number of parameters. All 
+ * producer method parameters are injection points.</p>
  * 
+ * <pre>public class OrderFactory {
+ * 
+ *    &#064;Produces &#064;ConversationScoped
+ *    public Order createCurrentOrder(&#064;New(Order.class) Order order, &#064;Selected Product product) {
+ *       order.setProduct(product);
+ *       return order;
+ *    }
+ * 
+ * }</pre>
+
  * <p>A bean may declare multiple producer methods or fields.</p>
  * 
  * <p>Producer methods and fields are not inherited by bean subclasses.</p>

Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/package-info.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/inject/package-info.java	2009-11-17 17:14:26 UTC (rev 5090)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/package-info.java	2009-11-18 03:10:00 UTC (rev 5091)
@@ -360,6 +360,33 @@
  * according to the class accessibility requirements of the module architecture.</li>
  * </ul>
  * 
+ * <h3>Injection points</h3>
+ * 
+ * <p>The following kinds of injection point exist:<p>
+ * 
+ * <ul>
+ * <li>When the container instantiates a bean class, it calls the bean constructor. 
+ * The bean constructor is a constructor of the bean class. The bean constructor may 
+ * be identified by annotating the constructor 
+ * {@link javax.inject.Inject &#064;javax.inject.Inject}. If a bean class does not 
+ * explicitly declare a constructor using <tt>&#064;Inject</tt>, the constructor that 
+ * accepts no parameters is the bean constructor. A bean constructor may have any number 
+ * of parameters. All parameters of a bean constructor are injection points.</li>
+ * <li>An injected field is a non-static, non-final field of a bean class, or of any 
+ * Java EE component class supporting injection. An injected field may be declared by 
+ * annotating the field {@link javax.inject.Inject &#064;javax.inject.Inject}.</li>
+ * <li>An initializer method is a non-abstract, non-static, non-generic method of a 
+ * bean class, or of any Java EE component class supporting injection. If the bean is 
+ * a session bean, the initializer method is not required to be a business method of 
+ * the session bean. An initializer method may be declared by annotating the method
+ * {@link javax.inject.Inject &#064;javax.inject.Inject}. An initializer method may 
+ * have any number of parameters. All initializer method parameters are injection 
+ * points.</li>
+ * <li>Finally, parameters of {@linkplain javax.enterprise.inject.Produces producer methods},
+ * {@linkplain javax.enterprise.inject.Disposes diposer methods} and 
+ * {@linkplain javax.enterprise.event.Observes observer methods} are injection points.</li>
+ * </ul>
+ * 
  * <h3>Dependency injection</h3>
  * 
  * <p>A bean is assignable to a given injection point if:</p>