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

[weld-commits at lists.jboss.org]

Author: gavin.king at jboss.com
Date: 2009-10-24 21:55:54 -0400 (Sat, 24 Oct 2009)
New Revision: 4281

Modified:
   api/trunk/cdi/src/main/java/javax/enterprise/event/Event.java
Log:
finish

Modified: api/trunk/cdi/src/main/java/javax/enterprise/event/Event.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/event/Event.java	2009-10-25 01:36:19 UTC (rev 4280)
+++ api/trunk/cdi/src/main/java/javax/enterprise/event/Event.java	2009-10-25 01:55:54 UTC (rev 4281)
@@ -22,8 +22,7 @@
 import javax.enterprise.inject.TypeLiteral;
 
 /**
- * <p>Allows the application to fire events of a particular type, 
- * and register observers for events of that type.</p>
+ * <p>Allows the application to fire events of a particular type.</p>
  * 
  * <p>Beans fire events via an instance of the <tt>Event</tt> 
  * interface, which may be injected:</p>
@@ -52,13 +51,12 @@
  * <p>For an injected <tt>Event</tt>:</p>
  * 
  * <ul>
- * <li>the specified type is the type parameter specified at the injection 
- * point, and</li>
- * <li>the specified qualifiers are the qualifiers specified at the injection 
- * point.</li>
+ * <li>the <em>specified type</em> is the type parameter specified at the 
+ * injection point, and</li>
+ * <li>the <em>specified qualifiers</em> are the qualifiers specified at 
+ * the injection point.</li>
  * </ul>
  * 
- * 
  * @author Gavin King
  * @author Pete Muir
  * @author David Allen
@@ -70,34 +68,51 @@
 {
 
    /**
-    * Fire an event
+    * <p>Fires an event with the specified qualifiers and notifies 
+    * observers.</p>
     * 
-    * @param event the event type
+    * @param event the event object
+    * @throws IllegalArgumentException if the runtime type of the event object contains a type variable
     */
    public void fire(T event);
    
    /**
-    * Returns a child Event with the additional specified qualifiers.
-    * @param qualifiers Additional qualifiers to add to child Event
-    * @return new child Event
+    * <p>Obtains a child <tt>Event</tt> for the given additional 
+    * required qualifiers.</p>
+    * 
+    * @param qualifiers the additional specified qualifiers
+    * @return the child <tt>Event</tt>
+    * @throws IllegalArgumentException if passed two instances of the 
+    * same qualifier type, or an instance of an annotation that is not 
+    * a qualifier type
     */
    public Event<T> select(Annotation... qualifiers);
    
    /**
-    * Returns a child Event of the type specified and additional specified qualifiers.
-    * @param <U> The subtype of T for the child Event
-    * @param subtype The class of the subtype of T
-    * @param qualifiers Additional specified qualifiers
-    * @return new child Event
+    * <p>Obtains a child <tt>Event</tt> for the given required type and 
+    * additional required qualifiers.</p>
+    * 
+    * @param <U> the specified type
+    * @param subtype a {@link java.lang.Class} representing the specified type
+    * @param qualifiers the additional specified qualifiers
+    * @return the child <tt>Event</tt>
+    * @throws IllegalArgumentException if passed two instances of the 
+    * same qualifier type, or an instance of an annotation that is not 
+    * a qualifier type
     */
    public <U extends T> Event<U> select(Class<U> subtype, Annotation... qualifiers);
    
    /**
-    * Returns a child Event of the type specified and additional specified qualifiers.
-    * @param <U> The subtype of T for the child Event
-    * @param subtype The TypeLiteral of the subtype of T
-    * @param qualifiers Additional specified qualifiers
-    * @return new child Event
-    */   
+    * <p>Obtains a child <tt>Event</tt> for the given required type and 
+    * additional required qualifiers.</p>
+    * 
+    * @param <U> the specified type
+    * @param subtype a {@link javax.enterprise.inject.TypeLiteral} representing the specified type
+    * @param qualifiers the additional specified qualifiers
+    * @return the child <tt>Event</tt>
+    * @throws IllegalArgumentException if passed two instances of the 
+    * same qualifier type, or an instance of an annotation that is not 
+    * a qualifier type
+    */
    public <U extends T> Event<U> select(TypeLiteral<U> subtype, Annotation... qualifiers);
 }