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

[weld-commits at lists.jboss.org]

Author: dallen6
Date: 2009-10-25 13:56:07 -0400 (Sun, 25 Oct 2009)
New Revision: 4308

Modified:
   api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/AfterBeanDiscovery.java
   api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/AfterDeploymentValidation.java
Log:
Updated JavaDocs for some additional container lifecycle events.

Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/AfterBeanDiscovery.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/AfterBeanDiscovery.java	2009-10-25 17:16:47 UTC (rev 4307)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/AfterBeanDiscovery.java	2009-10-25 17:56:07 UTC (rev 4308)
@@ -18,14 +18,75 @@
 
 import javax.enterprise.context.spi.Context;
 
+/**
+ * <p>
+ * The event type of the second event fired by the container when it has fully
+ * completed the bean discovery process, validated that there are no definition
+ * errors relating to the discovered beans, and registered
+ * {@link javax.enterprise.inject.spi.Bean} and
+ * {@link javax.enterprise.inject.spi.ObserverMethod} objects for the discovered
+ * beans, but before detecting deployment problems.
+ * </p>
+ * <p>
+ * A portable extension may take advantage of this event to register
+ * {@linkplain javax.enterprise.inject.spi.Bean beans},
+ * {@linkplain javax.enterprise.inject.spi.Interceptor interceptors},
+ * {@linkplain javax.decorator.Decorator decorators},
+ * {@linkplain javax.enterprise.event.Observes observer methods} and
+ * {@linkplain javax.enterprise.context custom context} objects with the
+ * container.
+ * </p>
+ * 
+ * <pre>
+ *     void afterBeanDiscovery(@Observes AfterBeanDiscovery event, BeanManager manager) { ... }
+ * </pre>
+ * <p>
+ * If any observer method of the {@code AfterBeanDiscovery} event throws an
+ * exception, the exception is treated as a definition error by the container.
+ * </p>
+ * 
+ * @author David Allen
+ */
 public interface AfterBeanDiscovery
 {
+   /**
+    * Registers a definition error with the container, causing the container to
+    * abort deployment after all observers have been notified.
+    * 
+    * @param t The definition error as a {@link java.lang.Throwable}
+    */
    public void addDefinitionError(Throwable t);
 
+   /**
+    * Fires an event of type {@link javax.enterprise.inject.spi.ProcessBean}
+    * containing the given {@link javax.enterprise.inject.spi.Bean} and then
+    * registers the {@link javax.enterprise.inject.spi.Bean} with the container,
+    * thereby making it available for injection into other beans. The given
+    * {@link javax.enterprise.inject.spi.Bean} may implement
+    * {@link javax.enterprise.inject.spi.Interceptor} or
+    * {@link javax.decorator.Decorator}.
+    * 
+    * @param bean The bean to add to the deployment
+    */
    public void addBean(Bean<?> bean);
 
+   /**
+    * Fires an event of type
+    * {@link javax.enterprise.inject.spi.ProcessObserverMethod} containing the
+    * given {@link javax.enterprise.inject.spi.ObserverMethod} and then
+    * registers the {@link javax.enterprise.inject.spi.ObserverMethod} with the
+    * container, thereby making it available for event notifications.
+    * 
+    * @param observerMethod The custom observer method to add to the deployment
+    */
    public void addObserverMethod(ObserverMethod<?, ?> observerMethod);
 
+   /**
+    * Registers a custom {@link javax.enterprise.context.spi.Context} object
+    * with the container.
+    * 
+    * @param context The custom context to add to the deployment
+    */
    public void addContext(Context context);
 
 }

Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/AfterDeploymentValidation.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/AfterDeploymentValidation.java	2009-10-25 17:16:47 UTC (rev 4307)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/AfterDeploymentValidation.java	2009-10-25 17:56:07 UTC (rev 4308)
@@ -16,9 +16,30 @@
  */
 package javax.enterprise.inject.spi;
 
-public interface AfterDeploymentValidation 
+/**
+ * <p>
+ * The event type of the third event fired by the container after it has
+ * validated that there are no deployment problems and before creating contexts
+ * or processing requests. If any observer method of the {@code
+ * AfterDeploymentValidation} event throws an exception, the exception is
+ * treated as a deployment problem by the container.
+ * </p>
+ * <p>
+ * No requests will be processed by the deployment until all observers of this
+ * event return.
+ * </p>
+ * 
+ * @author David Allen
+ */
+public interface AfterDeploymentValidation
 {
-   
+
+   /**
+    * Registers a deployment problem with the container, causing the container
+    * to abort deployment after all observers have been notified.
+    * 
+    * @param t The deployment problem as a {@link java.lang.Throwable}
+    */
    public void addDeploymentProblem(Throwable t);
 
 }