Author: gavin.king(a)jboss.com Date: 2009-10-29 00:34:29 -0400 (Thu, 29 Oct 2009) New Revision: 4378 Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/BeanManager.java api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Extension.java api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/package-info.java Log: Done with the preamble, etc. Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/BeanManager.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/BeanManager.java 2009-10-29 04:02:56 UTC (rev 4377) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/BeanManager.java 2009-10-29 04:34:29 UTC (rev 4378) @@ -32,36 +32,24 @@ import javax.enterprise.inject.UnsatisfiedResolutionException; /** - * <p> - * This interface provides operations for obtaining contextual references for - * beans, along with many other operations of use to portable extensions. - * Occasionally it is necessary to use this programmatic API to fully utilize - * portable extensions in the Contexts and Dependency Injection for the Java EE - * platform standard. - * </p> - * <p> - * The container provides a built-in bean with bean type BeanManager, scope - * {@literal @}{@link javax.enterprise.context.Dependent} and qualifier - * {@literal @}{@link javax.enterprise.inject.Default}. The built-in - * implementation is a {@linkplain PassivationCapable passivation capable} - * dependency. Thus, any bean may obtain an instance of BeanManager by injecting - * it: - * </p> + * <p>Allows a portable extension to interact directly with the container. + * Provides operations for obtaining contextual references for beans, along + * with many other operations of use to portable extensions.</p> * + * <p>Any bean may obtain an instance of <tt>BeanManager</tt> by injecting + * it:</p> + * * <pre> - * &#064;Inject - * BeanManager manager; + * &#064;Inject BeanManager manager; * </pre> - * <p> - * Java EE components may also obtain an instance of BeanManager from + * + * <p>Java EE components may obtain an instance of <tt>BeanManager</tt> from * {@linkplain javax.naming JNDI} by looking up the name {@code - * java:comp/BeanManager}. - * </p> - * <p> - * Any operation of BeanManager may be called at any time during the execution - * of the application. - * </p> + * java:comp/BeanManager}.</p> * + * <p>Any operation of <tt>BeanManager</tt> may be called at any time during + * the execution of the application.</p> + * * @author Gavin King * @author Pete Muir * @author Clint Popetz Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Extension.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Extension.java 2009-10-29 04:02:56 UTC (rev 4377) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Extension.java 2009-10-29 04:34:29 UTC (rev 4378) @@ -18,7 +18,24 @@ package javax.enterprise.inject.spi; /** + * <p>Service interface implemented by service providers that + * observe container lifecycle events. Service providers must + * be declared in <tt>META-INF/services</tt></p> * + * <p>The container instantiates a single instance of each + * service provider at the beginning of the application + * initialization process and maintains a reference to it until + * the application shuts down.</p> + * + * <p>Service providers may have observer methods, which may + * observe container initialization events and obtain an injected + * {@link javax.enterprise.inject.spi.BeanManager}.<p> + * + * <p>Service providers are made available for injection as beans + * with the qualifier {@link javax.context.Default &#064;Default}.</p> + * + * + * @author Gavin King * @author Pete Muir * */ 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 04:02:56 UTC (rev 4377) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/package-info.java 2009-10-29 04:34:29 UTC (rev 4378) @@ -1,6 +1,43 @@ /** * <p>The portable extension integration SPI.</p> * + * <p>A portable extension may integrate with the container by:</p> + * + * <ul> + * <li>Providing its own beans, interceptors and decorators to the + * container</li> + * <li>Injecting dependencies into its own objects using the + * dependency injection service</li> + * <li>Providing a context implementation for a custom scope</li> + * <li>Augmenting or overriding the annotation-based metadata with + * metadata from some other source</li> + * </ul> + * + * <h3>Interfaces representing enabled beans</h3> + * + * <p>The interfaces + * {@link javax.enterprise.inject.spi.Bean}, + * {@link javax.enterprise.inject.spi.Decorator}, + * {@link javax.enterprise.inject.spi.Interceptor} and + * {@link javax.enterprise.inject.spi.ObserverMethod} + * define everything the container needs to manage instances of + * 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.spi.AfterBeanDiscovery#addBean(Bean) + * registering beans} with the container.</p> + * + * <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>Alternate metadata sources</h3> * * <p>A portable extension may provide an alternative metadata @@ -15,5 +52,14 @@ * element types and annotations, instead of directly calling the * Java Reflection API.</p> * + * <h3>Container lifecycle events</h3> + * + * <p>During the application initialization process, the container fires + * a series of events, allowing portable extensions to integrate with the + * container initialization process. Observers of these events must be + * service providers of the service + * {@link javax.enterprise.inject.spi.Extension} declared in + * <tt>META-INF/services</tt>.</p> + * */ package javax.enterprise.inject.spi; \ No newline at end of file