[weld-commits] Weld SVN: r4274 - 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:07:08 -0400 (Sat, 24 Oct 2009)
New Revision: 4274

Modified:
   api/trunk/cdi/src/main/java/javax/enterprise/event/package-info.java
Log:
package javadoc

Modified: api/trunk/cdi/src/main/java/javax/enterprise/event/package-info.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/event/package-info.java	2009-10-25 00:38:16 UTC (rev 4273)
+++ api/trunk/cdi/src/main/java/javax/enterprise/event/package-info.java	2009-10-25 01:07:08 UTC (rev 4274)
@@ -1,6 +1,43 @@
+/**
+ * <p>This contains annotations and interfaces relating to events.<p>
+ * 
+ * <p>Beans may produce and consume events. This facility allows 
+ * beans to interact in a completely decoupled fashion, with no 
+ * compile-time dependency between the two beans. Most importantly, 
+ * it allows stateful beans in one architectural or physical tier 
+ * of the application to synchronize their internal state with 
+ * state changes that occur in a different tier.</p>
+ * 
+ * <p>An event comprises:</p>
+ * 
+ * <ul>
+ * <li>A Java objectÑthe event object</li>
+ * <li>A (possibly empty) set of instances of qualifier typesÑthe event qualifiers</li>
+ * </ul>
+ * 
+ * <p>The event object acts as a payload, to propagate state from 
+ * producer to consumer. The event qualifiers act as topic selectors, 
+ * allowing the consumer to narrow the set of events it observes.</p>
+ * 
+ * <p>An event object is an instance of a concrete Java class with 
+ * no type variables. The event types of the event include all 
+ * superclasses and interfaces of the runtime class of the event object.
+ * An event type may not contain a type variable.</p>
+ * 
+ * <p>An event qualifier type is just an ordinary qualifier type</p>
+ * 
+ * <p>An {@linkplain javax.enterprise.event.Observes observer method} 
+ * acts as event consumer, observing events of a specific type, the 
+ * observed event type, with a specific set of qualifiers, the observed 
+ * event qualifiers. Any Java type may be an observed event type.</p>
+ * 
+ * <p>An observer method will be notified of an event if the observed 
+ * event type it specifies is one of the event types of the event, and 
+ * if all the observed event qualifiers it specifies are event qualifiers 
+ * of the event.</p>
+ * 
+ * @see javax.enterprise.event.Observes
+ * @see javax.enterprise.event.Event
+ */
 package javax.enterprise.event;
 
-/**
- * The package javax.enterprise.event contains annotations and interfaces
- * relating to events.
- */