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

weld-commits at lists.jboss.org weld-commits at lists.jboss.org
Thu Oct 29 00:34:31 EDT 2009 

Author: gavin.king at 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

More information about the weld-commits mailing list