[webbeans-commits] Webbeans SVN: r2431 - ri/trunk/spi/src/main/java/org/jboss/webbeans/bootstrap/spi and 2 other directories.

Author: pete.muir(a)jboss.org Date: 2009-04-16 08:33:10 -0400 (Thu, 16 Apr 2009) New Revision: 2431 Modified: doc/trunk/reference/en-US/ri-spi.xml ri/trunk/spi/src/main/java/org/jboss/webbeans/bootstrap/spi/WebBeanDiscovery.java ri/trunk/spi/src/main/java/org/jboss/webbeans/ejb/spi/EjbDescriptor.java ri/trunk/spi/src/main/java/org/jboss/webbeans/ejb/spi/EjbServices.java ri/trunk/spi/src/main/java/org/jboss/webbeans/messaging/spi/JmsServices.java Log: SPI docs update Modified: doc/trunk/reference/en-US/ri-spi.xml =================================================================== --- doc/trunk/reference/en-US/ri-spi.xml 2009-04-16 12:12:33 UTC (rev 2430) +++ doc/trunk/reference/en-US/ri-spi.xml 2009-04-16 12:33:10 UTC (rev 2431) @@ -1,30 +1,21 @@ <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]> <appendix id="ri-spi"> - <title>Integrating the Web Beans RI into other environments</title> + <title>Integrating Web Beans into other environments</title> <para> - Currently the Web Beans RI only runs in JBoss AS 5; integrating the RI + Currently Web Beans only runs in JBoss AS 5; integrating the RI into other EE environments (for example another application server like Glassfish), into a servlet container (like Tomcat), or with an Embedded EJB3.1 implementation is fairly easy. In this Appendix we will briefly discuss the steps needed. </para> - <note> - <para> - It should be possible to run Web Beans in an SE environment, but - you'll to do more work, adding your own contexts and lifecycle. The - Web Beans RI currently doesn't expose lifecycle extension points, so - you would have to code directly against Web Beans RI classes. - </para> - </note> - <section> - <title>The Web Beans RI SPI</title> + <title>The Web Beans SPI</title> <para> - The Web Beans SPI is located in <literal>webbeans-spi</literal> + The Web Beans SPI is located in the <literal>webbeans-spi</literal> module, and packaged as <literal>webbeans-spi.jar</literal>. Some SPIs are optional, if you need to override the default behavior, others are required. @@ -32,31 +23,32 @@ <para> All interfaces in the SPI support the decorator pattern and provide a - <literal>Forwarding</literal> class. + <literal>Forwarding</literal> class located in the + <literal>helpers</literal> sub package. Additional, commonly used, + utility classes, and standard implementations are also located in the + <literal>helpers</literal> sub package. </para> <section> <title>Web Bean Discovery</title> - <programlisting role="JAVA"><![CDATA[public interface WebBeanDiscovery { - /** - * Gets list of all classes in classpath archives with web-beans.xml files + <programlisting role="JAVA"><![CDATA[/** + * Gets list of all classes in classpath archives with META-INF/beans.xml (or + * for WARs WEB-INF/beans.xml) files * * @return An iterable over the classes */ public Iterable<Class<?>> discoverWebBeanClasses(); /** - * Gets a list of all web-beans.xml files in the app classpath + * Gets a list of all deployment descriptors in the app classpath * - * @return An iterable over the web-beans.xml files + * @return An iterable over the beans.xml files */ - public Iterable<URL> discoverWebBeansXml(); - -}]]></programlisting> + public Iterable<URL> discoverWebBeansXml();]]></programlisting> <para> - The discovery of Web Bean classes and <literal>web-bean.xml</literal> + The discovery of Web Bean classes and <literal>beans.xml</literal> files is self-explanatory (the algorithm is described in Section 11.1 of the JSR-299 specification, and isn't repeated here). </para> @@ -66,26 +58,24 @@ <section> <title>EJB services</title> + <note> + <para> + Web Beans will run without an EJB container; in this case you + don't need to implement the EJB SPI. + </para> + </note> + <para> - The Web Beans RI also delegates EJB3 bean discovery to the container + Web Beans also delegates EJB3 bean discovery to the container so that it doesn't have to scan for EJB3 annotations or parse <literal>ejb-jar.xml</literal>. For each EJB in the application an EJBDescriptor should be discovered: </para> - <programlisting role="JAVA"><![CDATA[public interface EjbServices + <programlisting role="JAVA"><![CDATA[public interface EjbDescriptor<T> { /** - * Gets a descriptor for each EJB in the application - * - * @return The bean class to descriptor map - */ - public Iterable<EjbDescriptor<?>> discoverEjbs();]]></programlisting> - - <programlisting role="JAVA"><![CDATA[public interface EjbDescriptor<T> { - - /** * Gets the EJB type * * @return The EJB Bean class @@ -146,10 +136,7 @@ * * @return The name */ - public String getEjbName(); - - -}]]></programlisting> + public String getEjbName();]]></programlisting> <para> The <literal>EjbDescriptor</literal> is fairly self-explanatory, @@ -161,25 +148,26 @@ </para> <para> - The resolution of <literal>@EJB</literal> and - <literal>@Resource</literal> is delegated to the container. You must - provide an implementation of + The resolution of <literal>@EJB</literal> (for injection into simple + beans), the resolution of local EJBs (for backing session beans) and + remote EJBs (for injection as a Java EE resource) is delegated to + the container. You must provide an implementation of <literal>org.jboss.webbeans.ejb.spi.EjbServices</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. + provides these operations. For resolving the <literal>@EJB</literal> + injection point, Web Beans will provide the + <literal>InjectionPoint</literal>; for resolving local EJBs, the + <literal>EjbDescriptor</literal> will be provided, and for remote + EJBs the <literal>jndiName</literal>, <literal>mappedName</literal>, + or <literal>ejbLink</literal> will be provided. </para> -<!-- <para>--> -<!-- JSR-299 also requires that when the <literal>Bean.destroy()</literal>--> -<!-- is called on a session bean that the container removes the stateful--> -<!-- session bean. As there is no specified way of doing this, the--> -<!-- <literal>EjbResolver.removeEjb()</literal> method is used by Web --> -<!-- Beans to request the EJB container remove a stateful session bean.--> -<!-- Web Beans assumes that the EJB container will invoke any--> -<!-- <literal>@PreDestroy</literal> lifecycle callbacks.--> -<!-- </para>--> + <para> + When resolving local EJBs (used to back session beans) a wrapper + (<literal>SessionObjectReference</literal>) around the EJB reference + is returned. This wrapper allows Web Beans to request a reference + that implements the given business interface, and, in the case of + SFSBs, request the removal of the EJB from the container. + </para> </section> @@ -187,24 +175,39 @@ <title>JPA services</title> <para> - Just as resolution of <literal>@EJB</literal> is delegated to the - container, so is resolution of - <literal>@PersistenceContext</literal>. + Just as EJB resolution is delegated to the container, resolution of + <literal>@PersistenceContext</literal> for injection into simple + beans (with the <literal>InjectionPoint</literal> provided), + and resolution of persistence contexts and persistence units (with + the <literal>unitName</literal> provided) for injection as a Java EE + resource is delegated to the container. </para> <para> - OPEN ISSUE: Web Beans also requires the container to provide a list - of entities in the deployment, so that they aren't discovered as - simple beans. + To allow JPA integration, the <literal>JpaServices</literal> + interface should be implemented. </para> + + <para> + Web Beans also needs to know what entities are in a deployment (so + that they aren't managed by Web Beans). An implementation that + detects entities through <literal>@Entity</literal> and + <literal>orm.xml</literal> is provided by default. If you want to + provide support for a entities defined by a JPA provider (such as + Hibernate's <literal>.hbm.xml</literal> you can wrap or replace the + default implementation. + </para> + + <programlisting><![CDATA[EntityDiscovery delegate = bootstrap.getServices().get(EntityDiscovery.class);]]></programlisting> + </section> <section> <title>Transaction Services</title> <para> - The Web Beans RI must delegate JTA activities to the container. - The SPI provides a couple hooks to easily achieve this with the + Web Beans must delegate JTA activities to the container. The SPI + provides a couple hooks to easily achieve this with the <literal>TransactionServices</literal> interface. </para> @@ -237,44 +240,98 @@ public boolean isTransactionActive(); }]]></programlisting> - <para> - The enumeration <literal>Status</literal> is a convenience for implementors - to be able to keep track of whether a synchronization is supposed to notify - an observer only when the transaction is successful, or after a failure, or - regardless of the status of the transaction. - </para> + <para> + The enumeration <literal>Status</literal> is a convenience for + implementors to be able to keep track of whether a synchronization + is supposed to notify an observer only when the transaction is + successful, or after a failure, or regardless of the status of the + transaction. + </para> - <para> - Any <literal>javax.transaction.Synchronization</literal> implementation - may be passed to the <literal>registerSynchronization()</literal> method - and the SPI implementation should immediately register the synchronization - with the JTA transaction manager used for the EJBs. - </para> + <para> + Any <literal>javax.transaction.Synchronization</literal> + implementation may be passed to the + <literal>registerSynchronization()</literal> method and the SPI + implementation should immediately register the synchronization with + the JTA transaction manager used for the EJBs. + </para> - <para> - To make it easier to determine whether or not a transaction is currently - active for the requesting thread, the <literal>isTransactionActive()</literal> - method can be used. The SPI implementation should query the same - JTA transaction manager used for the EJBs. - </para> - </section> + <para> + To make it easier to determine whether or not a transaction is + currently active for the requesting thread, the + <literal>isTransactionActive()</literal> method can be used. The SPI + implementation should query the same JTA transaction manager used + for the EJBs. + </para> + </section> + + <section> + <title>JMS services</title> + + <para> + A number of JMS operations are not container specific, and so should + be provided via the SPI <literal>JmsServices</literal>. + JMS does not specify how to obtain a + <literal>ConnectionFactory</literal> so the SPI provides a method + which should be used to look up a factory. Web Beans also delegates + <literal>Destination</literal> lookup to the container via the SPI. + </para> + </section> + + <section> + <title>Resource Services</title> + + <para> + The resolution of <literal>@Resource</literal> (for injection into simple + beans) and the resolution of resources (for injection as a Java EE + resource) is delegated to the container. You must provide an + implementation of <literal>ResourceServices</literal> which + provides these operations. For resolving the + <literal>@Resource</literal> injection, Web Beans will provide the + <literal>InjectionPoint</literal>; and for Java EE resources, the + <literal>jndiName</literal> or <literal>mappedName</literal> will be + provided. + </para> + </section> + + <section> + <title>Web Services</title> + + <para> + The resolution of web service references (for injection as a Java EE + resource) is delegated to the container. You must provide an + implementation of <literal>WebServices</literal> whichprovides this + operation. For resolving the Java EE resource, the + <literal>jndiName</literal> or <literal>mappedName</literal> will be + provided. + </para> + </section> + + <section> + <title>The bean store</title> + + <para> + Web Beans uses a map like structure to store bean instances - + <literal>org.jboss.webbeans.context.api.BeanStore</literal>. You may + find + <literal>org.jboss.webbeans.context.api.helpers.ConcurrentHashMapBeanStore</literal> + useful. + </para> + </section> - <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. + be implemented to provide an application scoped storage. </para> - </section> + </section> - <section> + <section> <title>Bootstrap and shutdown</title> <para> The <literal>org.jboss.webbeans.bootstrap.api.Bootstrap</literal> @@ -294,7 +351,10 @@ </para> <para> - The bootstrap supports multiple environments. Different environments + The bootstrap supports multiple environments. An environment is + defined by an implementation of the <literal>Environment</literal> + interface. A number of standard envrionments are built in as the + enumeration <literal>Environments</literal>. Different environments require different services to be present (for example servlet doesn't require transaction, EJB or JPA services). By default an EE environment is assumed, but you can adjust the environment by @@ -302,6 +362,13 @@ </para> <para> + Web Beans uses a generic-typed service registry to allow services to + be registered. All services implement the <literal>Service</literal> + interface. The service registry allows services to be added and + retrieved. + </para> + + <para> To initialize the bootstrap you call <literal>Bootstrap.initialize()</literal>. Before calling <literal>initialize()</literal>, you must register any services @@ -322,8 +389,9 @@ <para> To shutdown the container you call - <literal>Bootstrap.shutdown()</literal>. This allows the container - to perform any cleanup operations needed. + <literal>Bootstrap.shutdown()</literal> or + <literal>webBeansManager.shutdown()</literal>. This allows the + container to perform any cleanup operations needed. </para> </section> @@ -332,45 +400,30 @@ <title>JNDI</title> <para> - The Web Beans RI implements JNDI binding and lookup according to - 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.resources.spi.NamingContext</literal>: + Web Beans delegates all JNDI operations to the container through the + SPI. </para> - <programlisting role="JAVA"><![CDATA[public interface NamingContext extends Serializable { - - /** - * Typed JNDI lookup - * - * @param <T> The type - * @param name The JNDI name - * @param expectedType The expected type - * @return The object - */ - public <T> T lookup(String name, Class<? extends T> expectedType); + <note> + <para> + A number of the SPI interface require JNDI lookup, and the class + <literal>AbstractResourceServices</literal> provides JNDI/Java EE + spec compliant lookup methods. + </para> + </note> + - /** - * Binds an item to JNDI - * - * @param name The key to bind under - * @param value The item to bind - */ - public void bind(String name, Object value); - -}]]></programlisting> - </section> <section> <title>Resource loading</title> <para> - The Web Beans RI needs to load classes and resources from the - classpath at various times. By default, they are loaded from the - same classloader that was used to load the RI, however this may not - be correct for some environments. If this is case, you can implement + Web Beans needs to load classes and resources from the classpath at + various times. By default, they are loaded from the Thread Context + ClassLoader if available, if not the same classloader that was used + to load Web Beans, however this may not be correct for some + environments. If this is case, you can implement <literal>org.jboss.webbeans.spi.ResourceLoader</literal>: </para> @@ -456,7 +509,7 @@ </varlistentry> <varlistentry> <term> - Servlet listener and filters + Servlet </term> <listitem> <para> @@ -467,6 +520,24 @@ configuration, for each Web Beans application which uses Servlet. </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + JSF + </term> + <listitem> + + <para> + If you are integrating the Web Beans into a JSF + environment you must register + <literal>org.jboss.webbeans.jsf.WebBeansPhaseListener</literal> + as a phase listener, and + <literal>org.jboss.webbeans.el.WebBeansELREsolver</literal> as + an EL resolver, either automatically, or through user + configuration, for each Web Beans application which uses + JSF. + </para> <para> If you are integrating the Web Beans into a JSF environment @@ -477,6 +548,12 @@ JSF. This filter can be registered for all Servlet deployment safely. </para> + + <note> + <para> + Web Beans only supports JSF 1.2 and above. + </para> + </note> </listitem> </varlistentry> <varlistentry> Modified: ri/trunk/spi/src/main/java/org/jboss/webbeans/bootstrap/spi/WebBeanDiscovery.java =================================================================== --- ri/trunk/spi/src/main/java/org/jboss/webbeans/bootstrap/spi/WebBeanDiscovery.java 2009-04-16 12:12:33 UTC (rev 2430) +++ ri/trunk/spi/src/main/java/org/jboss/webbeans/bootstrap/spi/WebBeanDiscovery.java 2009-04-16 12:33:10 UTC (rev 2431) @@ -22,27 +22,27 @@ import org.jboss.webbeans.bootstrap.api.Service; /** - * A container should implement this interface to allow the Web Beans RI to - * discover the Web Beans to deploy + * A container should implement this interface to allow Web Beans to + * discover the beans to deploy * * @author Pete Muir * */ public interface WebBeanDiscovery extends Service { - public static final String PROPERTY_NAME = WebBeanDiscovery.class.getName(); /** - * Gets list of all classes in classpath archives with web-beans.xml files + * Gets list of all classes in classpath archives with META-INF/beans.xml (or + * for WARs WEB-INF/beans.xml) files * * @return An iterable over the classes */ public Iterable<Class<?>> discoverWebBeanClasses(); /** - * Gets a list of all web-beans.xml files in the app classpath + * Gets a list of all deployment descriptors in the app classpath * - * @return An iterable over the web-beans.xml files + * @return An iterable over the beans.xml files */ public Iterable<URL> discoverWebBeansXml(); Modified: ri/trunk/spi/src/main/java/org/jboss/webbeans/ejb/spi/EjbDescriptor.java =================================================================== --- ri/trunk/spi/src/main/java/org/jboss/webbeans/ejb/spi/EjbDescriptor.java 2009-04-16 12:12:33 UTC (rev 2430) +++ ri/trunk/spi/src/main/java/org/jboss/webbeans/ejb/spi/EjbDescriptor.java 2009-04-16 12:33:10 UTC (rev 2431) @@ -25,7 +25,7 @@ * * @author Pete Muir * - * @param <T> + * @param <T> the bean type */ public interface EjbDescriptor<T> { Modified: ri/trunk/spi/src/main/java/org/jboss/webbeans/ejb/spi/EjbServices.java =================================================================== --- ri/trunk/spi/src/main/java/org/jboss/webbeans/ejb/spi/EjbServices.java 2009-04-16 12:12:33 UTC (rev 2430) +++ ri/trunk/spi/src/main/java/org/jboss/webbeans/ejb/spi/EjbServices.java 2009-04-16 12:33:10 UTC (rev 2431) @@ -23,7 +23,7 @@ import org.jboss.webbeans.ejb.api.SessionObjectReference; /** - * A container should implement this interface to allow the Web Beans RI to + * A container should implement this interface to allow Web Beans to * resolve EJB and discover EJBs * * @author Pete Muir Modified: ri/trunk/spi/src/main/java/org/jboss/webbeans/messaging/spi/JmsServices.java =================================================================== --- ri/trunk/spi/src/main/java/org/jboss/webbeans/messaging/spi/JmsServices.java 2009-04-16 12:12:33 UTC (rev 2430) +++ ri/trunk/spi/src/main/java/org/jboss/webbeans/messaging/spi/JmsServices.java 2009-04-16 12:33:10 UTC (rev 2431) @@ -28,8 +28,18 @@ */ public <T extends Destination> T resolveDestination(String jndiName, String mappedName); + /** + * Get a QueueConnectionFactory + * + * @return the queue connection factory + */ public QueueConnectionFactory getQueueConnectionFactory(); + /** + * Get a TopicConnectionFactory + * + * @return + */ public TopicConnectionFactory getTopicConnectionFactory(); } \ No newline at end of file