Author: gavin.king(a)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 */