7:37 p.m.
Author: pete.muir(a)jboss.org
Date: 2008-12-20 13:37:13 -0500 (Sat, 20 Dec 2008)
New Revision: 628
Added:
doc/trunk/reference/en/modules/ri-spi.xml
Modified:
doc/trunk/reference/en/master.xml
Log:
Add an appendix on integrating the RI into other environments
Modified: doc/trunk/reference/en/master.xml
===================================================================
--- doc/trunk/reference/en/master.xml 2008-12-20 18:36:27 UTC (rev 627)
+++ doc/trunk/reference/en/master.xml 2008-12-20 18:37:13 UTC (rev 628)
@@ -53,6 +53,7 @@
</part>
<xi:include href="modules/next.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="modules/ri-spi.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</book>
Added: doc/trunk/reference/en/modules/ri-spi.xml
===================================================================
--- doc/trunk/reference/en/modules/ri-spi.xml (rev 0)
+++ doc/trunk/reference/en/modules/ri-spi.xml 2008-12-20 18:37:13 UTC (rev 628)
@@ -0,0 +1,212 @@
+<!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>
+
+ <para>
+ Currently the Web Beans RI 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>
+
+ <para>
+ The Web Beans SPI is located in <literal>webbeans-ri-spi</literal>
+ module, and packaged as <literal>webbeans-ri-spi.jar</literal>.
+ </para>
+
+ <para>
+ Currently, the only SPI to implement is the bootstrap spi:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[public interface
WebBeanDiscovery {
+ /**
+ * Gets list of all classes in classpath archives with web-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
+ *
+ * @return An iterable over the web-beans.xml files
+ */
+ public Iterable<URL> discoverWebBeansXml();
+
+ /**
+ * Gets a descriptor for each EJB in the application
+ *
+ * @return The bean class to descriptor map
+ */
+ public Iterable<EjbDescriptor<?>> discoverEjbs();
+
+}]]></programlisting>
+
+ <para>
+ The discovery of Web Bean classes and
<literal>web-bean.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>
+
+ <para>
+ The Web Beans RI 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
EjbDescriptor<T> {
+
+ /**
+ * Gets the EJB type
+ *
+ * @return The EJB Bean class
+ */
+ public Class<T> getType();
+
+ /**
+ * Gets the local business interfaces of the EJB
+ *
+ * @return An iterator over the local business interfaces
+ */
+ public Iterable<BusinessInterfaceDescriptor<?>>
getLocalBusinessInterfaces();
+
+ /**
+ * Gets the remote business interfaces of the EJB
+ *
+ * @return An iterator over the remote business interfaces
+ */
+ public Iterable<BusinessInterfaceDescriptor<?>>
getRemoteBusinessInterfaces();
+
+ /**
+ * Get the remove methods of the EJB
+ *
+ * @return An iterator over the remove methods
+ */
+ public Iterable<MethodDescriptor> getRemoveMethods();
+
+ /**
+ * Indicates if the bean is stateless
+ *
+ * @return True if stateless, false otherwise
+ */
+ public boolean isStateless();
+
+ /**
+ * Indicates if the bean is a EJB 3.1 Singleton
+ *
+ * @return True if the bean is a singleton, false otherwise
+ */
+ public boolean isSingleton();
+
+ /**
+ * Indicates if the EJB is stateful
+ *
+ * @return True if the bean is stateful, false otherwise
+ */
+ public boolean isStateful();
+
+ /**
+ * Indicates if the EJB is and MDB
+ *
+ * @return True if the bean is an MDB, false otherwise
+ */
+ public boolean isMessageDriven();
+
+ /**
+ * Gets the EJB name
+ *
+ * @return The name
+ */
+ public String getEjbName();
+
+ /**
+ * @return The JNDI string which can be used to lookup a proxy which
+ * implements all local business interfaces
+ *
+ */
+ public String getLocalJndiName();
+
+}]]></programlisting>
+
+ <para>
+ The contract described the JavaDoc is enough to implement
+ an EJBDescriptor. In addition to these two interfaces, there is
+ <literal>BusinessInterfaceDescriptor</literal> which represents a
local
+ business interface (encapsulating the interface class and jndi name), and
+ <literal>MethodDescriptor</literal> which encapsulates the method
name
+ and parameter types (allowing it to be invoked on any instance of the
+ EJB, proxy or otherwise).
+ </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.webBeanDiscovery</literal> with
the
+ fully qualified class name as the value. For example:
+ </para>
+
+
<programlisting>org.jboss.webbeans.bootstrap.webBeanDiscovery=org.jboss.webbeans.integration.jbossas.WebBeanDiscoveryImpl</programlisting>
+
+ <para>
+ The property can either be specified as a system property, or in a
+ properties file <literal>META-INF/web-beans-ri.properties</literal>.
+ </para>
+
+ </section>
+
+ <section>
+ <title>The contract with the container</title>
+
+ <para>
+ There are a number of requirements that the Web Beans RI places on the
+ container for correct functioning that fall outside implementation of
+ APIs
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ Classloader isolation
+ </term>
+ <listitem>
+ <para>
+ If you are integrating the Web Beans into an environment that
+ supports deployment of applications, you must enable,
+ automatically, or through user configuation, classloader
+ isolation for each Web Beans application
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ The <literal>webbeans-ri.jar</literal>
+ </term>
+ <listitem>
+ <para>
+ If you are integrating the Web Beans into an environment that
+ supports deployment of applications, you must insert the
+ <literal>webbeans-ri.jar</literal> into the applications
+ isolated classloader. It cannot be loaded from a shared
+ classloader.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+</appendix>
\ No newline at end of file
Property changes on: doc/trunk/reference/en/modules/ri-spi.xml
___________________________________________________________________
Name: svn:mime-type
+ text/plain