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

Thu Oct 29 14:52:14 EDT 2009

Author: gavin.king at jboss.com
Date: 2009-10-29 14:52:14 -0400 (Thu, 29 Oct 2009)
New Revision: 4409

Modified:
   api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessBean.java
   api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/package-info.java
Log:
much better SPI overview

Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessBean.java
===================================================================

--- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessBean.java	2009-10-29 17:41:57 UTC (rev 4408)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessBean.java	2009-10-29 18:52:14 UTC (rev 4409)
@@ -22,8 +22,7 @@
  * registering the {@link javax.enterprise.inject.spi.Bean} object.
  * </p>
  * <p>
- * The event object type in the package javax.enterprise.inject.spi depends upon
- * what kind of bean was discovered:
+ * The event object type depends upon what kind of bean was discovered:
  * </p>
  * <ul>
  * <li>For a managed bean with bean class X, the container must raise an event

Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/package-info.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/package-info.java	2009-10-29 17:41:57 UTC (rev 4408)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/package-info.java	2009-10-29 18:52:14 UTC (rev 4409)
@@ -13,6 +13,29 @@
  * metadata from some other source</li>
  * </ul>
  * 
+ * <h3>The <tt>BeanManager</tt> object</h3>
+ * 
+ * <p>Portable extensions sometimes interact directly with the container 
+ * via programmatic API call. The interface 
+ * {@link javax.enterprise.inject.spi.BeanManager} provides operations 
+ * for obtaining contextual references for beans, along with many other 
+ * operations of use to portable extensions.</p>
+ * 
+ * <h3>Container lifecycle events</h3>
+ * 
+ * <p>During the application initialization process, the container fires 
+ * a series of {@linkplain javax.enterprise.event events}, allowing 
+ * portable extensions to integrate with the container initialization 
+ * process. Observer methods of these events must belong to
+ * {@linkplain javax.enterprise.inject.spi.Extension extensions} declared 
+ * in <tt>META-INF/services</tt>.</p>
+ * 
+ * <p>Lifecycle events include
+ * {@link javax.enterprise.inject.spi.BeforeBeanDiscovery},
+ * {@link javax.enterprise.inject.spi.AfterBeanDiscovery},
+ * {@link javax.enterprise.inject.spi.AfterDeploymentValidation} and
+ * {@link javax.enterprise.inject.spi.BeforeShutdown}.</p>
+ * 
  * <h3>Interfaces representing enabled beans</h3>
  * 
  * <p>The interfaces 
@@ -24,25 +47,31 @@
  * a bean, interceptor, decorator or observer method.</p>
  * 
  * <p>An instance of <tt>Bean</tt> exists for every  
- * {@linkplain javax.enterprise.inject enabled bean}. An application 
- * or portable extension may add support for new kinds of beans by 
- * implementing <tt>Bean</tt> and 
+ * {@linkplain javax.enterprise.inject enabled bean}. A portable extension 
+ * may add support for new kinds of beans by implementing <tt>Bean</tt> and 
  * {@linkplain javax.enterprise.inject.spi.AfterBeanDiscovery#addBean(Bean) 
- * registering beans} with the container.</p>
+ * registering beans} with the container. An instance of 
+ * <tt>ObserverMethod</tt> exists for every 
+ * {@linkplain javax.enterprise.event observer method} of every 
+ * enabled bean. A portable extension may add observers by implementing 
+ * <tt>ObserverMethod</tt> and 
+ * {@linkplain javax.enterprise.inject.spi.AfterBeanDiscovery#addObserverMethod(ObserverMethod) 
+ * registering an instance} with the container.</p>
  * 
- * <h3>The <tt>BeanManager</tt> object</h3>
+ * <p>A portable extension may be notified of the existence of an
+ * enabled bean or observer method by observing the container
+ * lifecycle event type {@link javax.enterprise.inject.spi.ProcessBean}
+ * or one of its {@linkplain javax.enterprise.inject.spi.ProcessBean subtypes},
+ * or of the existence of an observer method of an enabled bean by 
+ * observing the event type
+ * {@link javax.enterprise.inject.spi.ProcessObserverMethod}.</p>
  * 
- * <p>Portable extensions sometimes interact directly with the container 
- * via programmatic API call. The interface 
- * {@link javax.enterprise.inject.spi.BeanManager} provides operations 
- * for obtaining contextual references for beans, along with many other 
- * operations of use to portable extensions.</p>
- * 
  * <h3>Alternate metadata sources</h3>
  * 
  * <p>A portable extension may provide an alternative metadata 
- * source, such as configuration by XML. 
- * {@link javax.enterprise.inject.spi.Annotated}
+ * source, such as configuration by XML.</p>
+ * 
+ * <p>{@link javax.enterprise.inject.spi.Annotated}
  * and its subtypes allow a portable extension to specify 
  * metadata that overrides the annotations that exist on a 
  * bean class. The portable extension is responsible for 
@@ -52,15 +81,33 @@
  * element types and annotations, instead of directly calling the 
  * Java Reflection API.</p>
  * 
- * <h3>Container lifecycle events</h3>
+ * <p>A portable extension provides its metadata to the 
+ * container by observing the event 
+ * {@link javax.enterprise.inject.spi.ProcessAnnotatedType} and
+ * calling 
+ * {@link javax.enterprise.inject.spi.ProcessAnnotatedType#setAnnotatedType(AnnotatedType)}.</p>
  * 
- * <p>During the application initialization process, the container fires 
- * a series of {@linkplain javax.enterprise.event events}, allowing 
- * portable extensions to integrate with the container initialization 
- * process. Observer methods of these events must belong to
- * {@linkplain javax.enterprise.inject.spi.Extension extensions} declared 
- * in <tt>META-INF/services</tt>.</p>
+ * <h3><tt>Producer</tt> and <tt>InjectionTarget</tt></h3>
  * 
+ * <pr>The interfaces {@link javax.enterprise.inject.spi.Producer} and
+ * {@link javax.enterprise.inject.spi.InjectionTarget} abstract the 
+ * basic lifecycle of (contextual or non-contextual) container managed 
+ * objects, including instantiation and destruction, dependency injection 
+ * and lifecycle callbacks.</p>
+ * 
+ * <p>An instance of {@link javax.enterprise.inject.spi.InjectionTarget} 
+ * may be obtained using 
+ * {@link javax.enterprise.inject.spi.BeanManager#createInjectionTarget(AnnotatedType)},
+ * allowing a portable extension to request these container services for
+ * objects under the control of the portable extension.</p>
+ * 
+ * <p>Furthermore, a portable extension may replace the implementation
+ * of {@link javax.enterprise.inject.spi.InjectionTarget} or
+ * {@link javax.enterprise.inject.spi.Producer} used by the container
+ * with its own implementation by observing the events
+ * {@link javax.enterprise.inject.spi.ProcessInjectionTarget} or
+ * {@link javax.enterprise.inject.spi.ProcessProducer}.</p>
+ * 
  * @see javax.enterprise.inject
  * @see javax.enterprise.context.spi
  */

