[webbeans-commits] Webbeans SVN: r1730 - doc/trunk/reference/en-US.

Author: pete.muir(a)jboss.org Date: 2009-02-26 16:21:49 -0500 (Thu, 26 Feb 2009) New Revision: 1730 Modified: doc/trunk/reference/en-US/ri-spi.xml Log: Update for new Bootstrap api Modified: doc/trunk/reference/en-US/ri-spi.xml =================================================================== --- doc/trunk/reference/en-US/ri-spi.xml 2009-02-26 21:19:44 UTC (rev 1729) +++ doc/trunk/reference/en-US/ri-spi.xml 2009-02-26 21:21:49 UTC (rev 1730) @@ -29,15 +29,6 @@ SPIs are optional, if you need to override the default behavior, others are required. </para> - - <para> - You can specify the implementation of an SPI either as a system - property, or in a properties file - <literal>META-INF/web-beans-ri.properties</literal>. All property names - are the fully qualified class name of the implemented interface; all - property values are the fully qualified class name of the - implementation class. - </para> <para> All interfaces in the SPI support the decorator pattern and provide a @@ -70,28 +61,6 @@ of the JSR-299 specification, and isn't repeated here). </para> - <para> - The Web Beans RI can be told to load your implementation of - <literal>WebBeanDiscovery</literal> using the property - <literal>org.jboss.webbeans.bootstrap.spi.WebBeanDiscovery</literal> with the - fully qualified class name as the value. For example: - </para> - - <programlisting>org.jboss.webbeans.bootstrap.spi.WebBeanDiscovery= \ - org.jboss.webbeans.integration.jbossas.WebBeanDiscoveryImpl</programlisting> - - <para> - If the Web Beans RI is being used in a servlet container, it - expects a constructor of the form: - </para> - - <programlisting><![CDATA[public WebBeanDiscoveryImpl(ServletContext servletContext) {}]]></programlisting> - - <para> - The servlet context can be used to allow your implementation of - <literal>WebBeanDiscovery</literal> to interact with the container. - </para> - </section> <section> @@ -193,32 +162,93 @@ local business interface (encapsulating the interface class and jndi name used to look up an instance of the EJB). </para> - - <para> - The Web Beans RI can be told to load your implementation of - <literal>EjbDiscovery</literal> using the property - <literal>org.jboss.webbeans.bootstrap.spi.EjbDiscovery</literal> with the - fully qualified class name as the value. For example: - </para> - - <programlisting>org.jboss.webbeans.bootstrap.spi.EjbDiscovery= \ - org.jboss.webbeans.integration.jbossas.EjbDiscoveryImpl</programlisting> - - <para> - If the Web Beans RI is being used in a servlet container, it - expects a constructor of the form: - </para> - - <programlisting><![CDATA[public EjbDiscoveryImpl(ServletContext servletContext) {}]]></programlisting> - - <para> - The servlet context can be used to allow your implementation of - <literal>EjbDiscovery</literal> to interact with the container. - </para> </section> <section> + <title><literal>@EJB</literal>, <literal>@PersistenceContext</literal> and <literal>@Resource</literal> resolution</title> + + <para> + The resolution of <literal>@EJB</literal>, + <literal>@PersistenceContext</literal> and + <literal>@Resource</literal> is delegated to the container. You must + provide an implementation of + <literal>org.jboss.webbeans.ejb.spi.EjbResolver</literal> which + provides these operations. Web Beans passes in the + <literal>javax.inject.manager.InjectionPoint</literal> the + resolution is for, as well as the <literal>NamingContext</literal> + in use for each resolution request. + </para> + + </section> + + <section> + <title>The application context</title> + + <para> + Web Beans expects the Application Server or other container to + provide the storage for each application's context. The + <literal>org.jboss.webbeans.context.api.BeanStore</literal> should + be implemented to provide an application scoped storage. You may + find + <literal>org.jboss.webbeans.context.api.helpers.ConcurrentHashMapBeanStore</literal> + useful. + </para> + + </section> + + <section> + <title>Bootstrap and shutdown</title> + <para> + The <literal>org.jboss.webbeans.bootstrap.api.Bootstrap</literal> + interface defines the bootstrap for Web Beans. To boot Web Beans, + you must obtain an instance of + <literal>org.jboss.webbeans.bootstrap.WebBeansBootstrap</literal> + (which implements <literal>Boostrap</literal>), tell it about the + SPIs in use, and then request the container start. + </para> + + <para> + The bootstrap is split into phases, bootstrap initialization and + bootstrap. Initialization will create a manager, and add the + standard (specification defined) contexts. Bootstrap will discover + EJBs, classes and XML; add beans defined using annotations; add + beans defined using XML; and validate all beans. + </para> + + <para> + To initialize the bootstrap you call + <literal>Bootstrap.initialize()</literal>. Before calling + <literal>initialize()</literal> you must have called + <literal>Bootstrap.setEjbResolver()</literal>. If you are not using + the built in <literal>DefaultNamingContext</literal> or the built in + <literal>DefaultResourceLoader</literal> you must set these before + calling <literal>initialize()</literal>. + </para> + + <para> + Having called <literal>initialize()</literal>, the + <literal>Manager</literal> can be obtained by calling + <literal>Bootstrap.getManager()</literal>. + </para> + + <para> + To boot the container you call <literal>Bootstrap.boot()</literal>. + Before calling <literal>boot()</literal> you must have called + <literal>Bootstrap.setWebBeanDiscovery()</literal>, + <literal>Bootstrap.setEjbDiscovery()</literal> and + <literal>Bootstrap.setApplicationContext()</literal>. + </para> + + <para> + To shutdown the container you call + <literal>Bootstrap.shutdown()</literal>. This allows the container + to perform any cleanup operations needed. + </para> + + </section> + + <section> <title>JNDI</title> <para> @@ -226,7 +256,7 @@ standards, however you may want to alter the binding and lookup (for example in an environment where JNDI isn't available). To do this, implement - <literal>org.jboss.webbeans.spi.resources.NamingContext</literal>: + <literal>org.jboss.webbeans.resources.spi.NamingContext</literal>: </para> <programlisting role="JAVA"><![CDATA[public interface NamingContext extends Serializable { @@ -251,24 +281,6 @@ }]]></programlisting> - <para> - and tell the RI to use it: - </para> - - <programlisting>org.jboss.webbeans.resources.spi.NamingContext=com.acme.MyNamingContext</programlisting> - - <para> - If the Web Beans RI is being used in a servlet container, it - expects a constructor of the form: - </para> - - <programlisting><![CDATA[public MyNamingContext(ServletContext servletContext) {}]]></programlisting> - - <para> - The servlet context can be used to allow your implementation of - <literal>NamingContext</literal> to interact with the container. - </para> - </section> <section> @@ -312,24 +324,6 @@ } ]]></programlisting> - <para> - and tell the RI to use it: - </para> - - <programlisting>org.jboss.webbeans.resources.spi.ResourceLoader=com.acme.ResourceLoader</programlisting> - - <para> - If the Web Beans RI is being used in a servlet container, it - expects a constructor of the form: - </para> - - <programlisting><![CDATA[public MyResourceLoader(ServletContext servletContext) {}]]></programlisting> - - <para> - The servlet context can be used to allow your implementation of - <literal>ResourceLoader</literal> to interact with the container. - </para> - </section> </section>