Author: pete.muir(a)jboss.org Date: 2009-03-28 12:41:24 -0400 (Sat, 28 Mar 2009) New Revision: 2248 Added: doc/trunk/reference/en-US/environments.xml doc/trunk/reference/en-US/extensions.xml doc/trunk/reference/en-US/part5.xml Modified: doc/trunk/reference/en-US/Author_Group.xml doc/trunk/reference/en-US/master.xml doc/trunk/reference/en-US/ri.xml Log: Improve docs for WB Modified: doc/trunk/reference/en-US/Author_Group.xml =================================================================== --- doc/trunk/reference/en-US/Author_Group.xml 2009-03-28 15:32:35 UTC (rev 2247) +++ doc/trunk/reference/en-US/Author_Group.xml 2009-03-28 16:41:24 UTC (rev 2248) @@ -18,6 +18,10 @@ <orgname>Red Hat Middleware LLC</orgname> </affiliation> </author> + <author> + <firstname>David</firstname> + <surname>Allen</surname> + </author> <othercredit> <firstname>Nicola</firstname> <surname>Benaglia</surname> Added: doc/trunk/reference/en-US/environments.xml =================================================================== --- doc/trunk/reference/en-US/environments.xml (rev 0) +++ doc/trunk/reference/en-US/environments.xml 2009-03-28 16:41:24 UTC (rev 2248) @@ -0,0 +1,168 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]> + +<chapter id="environments"> + <title>Application Servers and environments supported by Web Beans</title> + + <section> + <title>Using Web Beans with JBoss AS</title> + + <para> + No special configuration of your application, beyond adding either + <literal>META-INF/beans.xml</literal> or + <literal>WEB-INF/beans.xml</literal> is needed. + </para> + + <para> + If you are using JBoss AS 5.0.1.GA then you'll need to install Web + Beans as an extra. First we need to tell Web Beans where JBoss is located. Edit + <literal>jboss-as/build.properties</literal> and set the + <literal>jboss.home</literal> property. For example: + </para> + + <programlisting>jboss.home=/Applications/jboss-5.0.1.GA</programlisting> + + <para> + Now we can install Web Beans: + </para> + + <programlisting>$ cd webbeans-$VERSION/jboss-as +$ ant update</programlisting> + + <note> + <para> + A new deployer, + <literal>webbeans.deployer</literal> is added to JBoss AS. This adds supports for + JSR-299 deployments to JBoss AS, and allows Web Beans to query the + EJB3 container and discover which EJBs are installed in your + application. + </para> + </note> + + <para> + Web Beans is built into all releases of JBoss AS from 5.1 onwards. + </para> + + </section> + + <section> + <title>Glassfish</title> + + <para>TODO</para> + </section> + + <section> + <title>Tomcat</title> + + <para>Web Beans can be used in Tomcat 6.0.</para> + + <note> + <para> + Web Beans doesn't support deploying session beans, injection using + <literal>@EJB</literal>, <literal>@Resource</literal>, or + <literal>@PersistenceContext</literal> or using transactional events + on Tomcat. + </para> + </note> + + <para> + Web Beans should be used as a web application library in Tomcat. You + should place <literal>webbeans-tomcat.jar</literal> in + <literal>WEB-INF/lib</literal>. <literal>webbeans-tomcat.jar</literal> + is an "uber-jar" provided for your convenience. Instead, you could use + it's component jars: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>jsr299-api.jar</literal> + </para> + </listitem> + <listitem> + <para> + <literal>webbeans-api.jar</literal> + </para> + </listitem> + <listitem> + <para> + <literal>webbeans-spi.jar</literal> + </para> + </listitem> + <listitem> + <para> + <literal>webbeans-core.jar</literal> + </para> + </listitem> + <listitem> + <para> + <literal>webbeans-logging.jar</literal> + </para> + </listitem> + <listitem> + <para> + <literal>webbeans-tomcat-int.jar</literal> + </para> + </listitem> + <listitem> + <para> + <literal>javassist.jar</literal> + </para> + </listitem> + <listitem> + <para> + <literal>dom4j.jar</literal> + </para> + </listitem> + </itemizedlist> + + <para> + You also need to explicitly specify the Tomcat servlet listener (used to + boot Web Beans, and control it's interaction with requests) in + <literal>web.xml</literal>: + </para> + + <programlisting><![CDATA[<listener> + <listener-class>org.jboss.webbeans.environment.tomcat.Listener</listener-class> +</listener>]]></programlisting> + + <para> + Tomcat has a read-only JNDI, so Web Beans can't automatically bind the + Manager. To bind the Manager into JNDI, you should add the following to + your <literal>META-INF/context.xml</literal>: + </para> + + <programlisting><![CDATA[<Resource name="app/Manager" + auth="Container" + type="javax.inject.manager.Manager" + factory="org.jboss.webbeans.resources.ManagerObjectFactory"/> +]]></programlisting> + + <para> + and make it available to your deployment by adding this to + <literal>web.xml</literal>: + </para> + + <programlisting><![CDATA[<resource-env-ref> + <resource-env-ref-name> + app/Manager + </resource-env-ref-name> + <resource-env-ref-type> + javax.inject.manager.Manager + </resource-env-ref-type> +</resource-env-ref>]]></programlisting> + + <para> + Tomcat doesn't only allows you to bind entries to + <literal>java:comp/env</literal>, so the Manager will be available at + <literal>java:comp/env/app/Manager</literal> + </para> + + </section> + + <section> + <title>Java SE</title> + + <para>TODO</para> + </section> + +</chapter> \ No newline at end of file Property changes on: doc/trunk/reference/en-US/environments.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Added: doc/trunk/reference/en-US/extensions.xml =================================================================== --- doc/trunk/reference/en-US/extensions.xml (rev 0) +++ doc/trunk/reference/en-US/extensions.xml 2009-03-28 16:41:24 UTC (rev 2248) @@ -0,0 +1,29 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]> + +<chapter id="extensions"> + <title>JSR-299 extensions available as part of Web Beans</title> + + <important> + <para> + These modules are usable on any JSR-299 implementation, not just Web + Beans! + </para> + </important> + + + <section> + <title>Web Beans Logger</title> + + <para> + TODO + </para> + + </section> + + <section> + <title>XSD Generator for JSR-299 XML deployment descriptors</title> + + <para>TODO</para> + </section> + +</chapter> \ No newline at end of file Property changes on: doc/trunk/reference/en-US/extensions.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Modified: doc/trunk/reference/en-US/master.xml =================================================================== --- doc/trunk/reference/en-US/master.xml 2009-03-28 15:32:35 UTC (rev 2247) +++ doc/trunk/reference/en-US/master.xml 2009-03-28 16:41:24 UTC (rev 2248) @@ -69,8 +69,20 @@ <xi:include href="extend.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </part> + + <xi:include href="next.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <part> + <title>Web Beans Reference</title> + + <xi:include href="part5.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="environments.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="extensions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + </part> - <xi:include href="next.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="ri-spi.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </book> Added: doc/trunk/reference/en-US/part5.xml =================================================================== --- doc/trunk/reference/en-US/part5.xml (rev 0) +++ doc/trunk/reference/en-US/part5.xml 2009-03-28 16:41:24 UTC (rev 2248) @@ -0,0 +1,23 @@ +<!DOCTYPE partintro PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]> + +<partintro> + + <para> + Web Beans is the reference implementation of JSR-299, and is used by JBoss + AS and Glassfish to provide JSR-299 services for Java Enterprise Edition + applications. Web Beans also goes beyond the environments and APIs defined + by the JSR-299 specification and provides support for a number of other + environments (such as a servlet container such as Tomcat, or Java SE) and + additional APIs and modules (such as logging, XSD generation for the + JSR-299 XML deployment descriptors). + </para> + + <para> + If you want to get started quickly using Web Beans with JBoss AS or Tomcat + and experiment with one of the examples, take a look at <xref linkend="ri"/>. + Otherwise read on for a exhaustive discussion of using Web Beans in all + the environments and application servers it supports, as well the Web Beans + extensions. + </para> + +</partintro> \ No newline at end of file Property changes on: doc/trunk/reference/en-US/part5.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Modified: doc/trunk/reference/en-US/ri.xml =================================================================== --- doc/trunk/reference/en-US/ri.xml 2009-03-28 15:32:35 UTC (rev 2247) +++ doc/trunk/reference/en-US/ri.xml 2009-03-28 16:41:24 UTC (rev 2248) @@ -1,172 +1,265 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]> <chapter id="ri"> - <title>The Web Beans Reference Implementation</title> + <title>Web Beans, the Reference Implementation of JSR-299</title> <para> - The Web Beans Reference Implementation is being developed at + The Web Beans is being developed at <ulink url="http://seamframework.org/WebBeans">the Seam project</ulink>. You can download the latest developer release of Web Beans from the <ulink url="http://seamframework.org/Download">the downloads page</ulink>. </para> <para> - The Web Beans RI comes with a two deployable example applications: + Web Beans comes with a two deployable example applications: <literal>webbeans-numberguess</literal>, a war example, containing only simple beans, and <literal>webbeans-translator</literal> an ear example, - containing enterprise beans. To run the examples you'll need the following: + containing enterprise beans. There are also two variations on the + numberguess example, the tomcat example (suitable for deployment to + Tomcat) and the jsf2 example, which you can use if you are running JSF2. + To run the examples you'll need the following: </para> <itemizedlist> <listitem> - <para>the latest release of the Web Beans RI,</para> + <para>the latest release of Web Beans,</para> </listitem> <listitem> - <para>JBoss AS 5.0.1.GA, and</para> + <para>JBoss AS 5.0.1.GA, or</para> </listitem> <listitem> + <para>Apache Tomcat 6.0.x, and</para> + </listitem> + <listitem> <para>Ant 1.7.0.</para> </listitem> </itemizedlist> - <para> - Currently, the Web Beans RI only runs on JBoss Application Server 5. - You'll need to download JBoss AS 5.0.1.GA from - <ulink url="http://www.jboss.org/jbossas/downloads/">jboss.org</...;, - and unzip it. For example: - </para> + <section> + <title>Using JBoss AS 5</title> - <programlisting><![CDATA[$ cd /Applications + <para> + You'll need to download JBoss AS 5.0.1.GA from + <ulink url="http://www.jboss.org/jbossas/downloads/">jboss.org</...;, + and unzip it. For example: + </para> + + <programlisting><![CDATA[$ cd /Applications $ unzip ~/jboss-5.0.1.GA.zip]]></programlisting> - <para> - Next, download the Web Beans RI from - <ulink url="http://seamframework.org/Download">seamframework.org<...;, - and unzip it. For example - </para> - - <programlisting><![CDATA[$ cd ~/ + <para> + Next, download Web Beans from + <ulink url="http://seamframework.org/Download">seamframework.org<...;, + and unzip it. For example + </para> + + <programlisting><![CDATA[$ cd ~/ $ unzip ~/webbeans-$VERSION.zip]]></programlisting> - <para> - Next, we need to tell Web Beans where JBoss is located. Edit - <literal>jboss-as/build.properties</literal> and set the - <literal>jboss.home</literal> property. For example: - </para> - - <programlisting>jboss.home=/Applications/jboss-5.0.1.GA</programlisting> - - <note> <para> - A new deployer, - <literal>webbeans.deployer</literal> is added to JBoss AS. This adds supports for - Web Bean archives to JBoss AS, and allows the Web Beans RI to query the - EJB3 container and discover which EJBs are installed in your - application. + Next, we need to tell Web Beans where JBoss is located. Edit + <literal>jboss-as/build.properties</literal> and set the + <literal>jboss.home</literal> property. For example: </para> + <programlisting>jboss.home=/Applications/jboss-5.0.1.GA</programlisting> + <para> - Web Beans is bundled with JBoss AS 5.1 and above. + To install Web Beans, you'll need Ant 1.7.0 installed, and the + <literal>ANT_HOME</literal> environment variable set. For example: </para> - </note> - - <para> - To install Web Beans, you'll need Ant 1.7.0 installed, and the - <literal>ANT_HOME</literal> environment variable set. For example: - </para> - - <programlisting>$ unzip apache-ant-1.7.0.zip + + <programlisting>$ unzip apache-ant-1.7.0.zip $ export ANT_HOME=~/apache-ant-1.7.0</programlisting> - <para> - Then, you can install the update. The update script will use Maven to - download Web Beans automatically. - </para> - - <programlisting>$ cd webbeans-$VERSION/jboss-as + <para> + Then, you can install the update. The update script will use Maven to + download Web Beans automatically. + </para> + + <programlisting>$ cd webbeans-$VERSION/jboss-as $ ant update</programlisting> - <para> - Now, you're ready to deploy your first example! - </para> + <para> + Now, you're ready to deploy your first example! + </para> + + <tip> + <para> + The build scripts for the examples offer a number of targets for + JBoss AS, these are: + </para> + <itemizedlist> + <listitem> + <para> + <literal>ant restart</literal> - deploy the example in exploded + format + </para> + </listitem> + <listitem> + <para> + <literal>ant explode</literal> - update an exploded example, without + restarting the deployment + </para> + </listitem> + <listitem> + <para> + <literal>ant deploy</literal> - deploy the example in compressed jar format + </para> + </listitem> + <listitem> + <para> + <literal>ant undeploy</literal> - remove the example from the server + </para> + </listitem> + <listitem> + <para> + <literal>ant clean</literal> - clean the example + </para> + </listitem> + </itemizedlist> + </tip> - <tip> <para> - The build scripts for the examples offer a number of targets, these - are: + To deploy the numberguess example: </para> - <itemizedlist> - <listitem> - <para> - <literal>ant restart</literal> - deploy the example in exploded - format - </para> - </listitem> - <listitem> - <para> - <literal>ant explode</literal> - update an exploded example, without - restarting the deployment - </para> - </listitem> - <listitem> - <para> - <literal>ant deploy</literal> - deploy the example in compressed jar format - </para> - </listitem> - <listitem> - <para> - <literal>ant undeploy</literal> - remove the example from the server - </para> - </listitem> - <listitem> - <para> - <literal>ant clean</literal> - clean the example - </para> - </listitem> - </itemizedlist> - </tip> - - <para> - To deploy the numberguess example: - </para> - - <programlisting>$ cd examples/numberguess + + <programlisting>$ cd examples/numberguess ant deploy</programlisting> - <para> - Start JBoss AS: - </para> + <para> + Start JBoss AS: + </para> + + <programlisting>$ /Application/jboss-5.0.0.GA/bin/run.sh</programlisting> + + <tip> + <para> + If you use Windows, use the <literal>run.bat</literal>script. + </para> + </tip> - <programlisting>$ /Application/jboss-5.0.0.GA/bin/run.sh</programlisting> + <para> + Wait for the application to deploy, and enjoy hours of fun at + <ulink url="http://localhost:8080/webbeans-numberguess" />! + </para> + + <para> + Web Beans includes a second simple example that will translate your text + into Latin. The numberguess example is a war example, and uses only simple + beans; the translator example is an ear example, and includes enterprise + beans, packaged in an EJB module. To try it out: + </para> - <tip> + <programlisting>$ cd examples/translator +ant deploy</programlisting> + <para> - If you use Windows, use the <literal>run.bat</literal>script. + Wait for the application to deploy, and visit + <ulink url="http://localhost:8080/webbeans-translator" />! </para> - </tip> + + </section> + + <section> + <title>Using Apache Tomcat 6.0</title> + + <para> + You'll need to download Tomcat 6.0.18 or later from + <ulink url="http://tomcat.apache.org/download-60.cgi">tomcat.apache...;, + and unzip it. For example: + </para> + + <programlisting><![CDATA[$ cd /Applications +$ unzip ~/apache-tomcat-6.0.18.zip]]></programlisting> - <para> - Wait for the application to deploy, and enjoy hours of fun at - <ulink url="http://localhost:8080/webbeans-numberguess" />! - </para> + <para> + Next, download Web Beans from + <ulink url="http://seamframework.org/Download">seamframework.org<...;, + and unzip it. For example + </para> + + <programlisting><![CDATA[$ cd ~/ +$ unzip ~/webbeans-$VERSION.zip]]></programlisting> + + <para> + Next, we need to tell Web Beans where Tomcat is located. Edit + <literal>jboss-as/build.properties</literal> and set the + <literal>tomcat.home</literal> property. For example: + </para> + + <programlisting>tomcat.home=/Applications/apache-tomcat-6.0.18</programlisting> + + <tip> + <para> + The build scripts for the examples offer a number of targets for + Tomcat, these are: + </para> + <itemizedlist> + <listitem> + <para> + <literal>ant tomcat.restart</literal> - deploy the example in exploded + format + </para> + </listitem> + <listitem> + <para> + <literal>ant tomcat.explode</literal> - update an exploded example, without + restarting the deployment + </para> + </listitem> + <listitem> + <para> + <literal>ant tomcat.deploy</literal> - deploy the example in compressed jar format + </para> + </listitem> + <listitem> + <para> + <literal>ant tomcat.undeploy</literal> - remove the example from the server + </para> + </listitem> + <listitem> + <para> + <literal>ant tomcat.clean</literal> - clean the example + </para> + </listitem> + </itemizedlist> + </tip> + + <para> + To deploy the numberguess example for tomcat: + </para> - <para> - The Web Beans RI includes a second simple example that will translate your text - into Latin. The numberguess example is a war example, and uses only simple - beans; the translator example is an ear example, and includes enterprise - beans, packaged in an EJB module. To try it out: - </para> + <programlisting>$ cd examples/tomcat +ant tomcat.deploy</programlisting> - <programlisting>$ cd examples/translator -ant deploy</programlisting> + <para> + Start Tomcat: + </para> + + <programlisting>$ /Applications/apache-tomcat-6.0.18/bin/startup.sh</programlisting> + + <tip> + <para> + If you use Windows, use the <literal>startup.bat</literal>script. + </para> + </tip> + + <para> + Wait for the application to deploy, and enjoy hours of fun at + <ulink url="http://localhost:8080/webbeans-numberguess" />! + </para> - <para> - Wait for the application to deploy, and visit - <ulink url="http://localhost:8080/webbeans-translator" />! - </para> + </section> <section> + <title>Using GlassFish</title> + + <para>TODO</para> + </section> + + <section> <title>The numberguess example</title> <para> @@ -278,8 +371,8 @@ <note> <para> - Whilst this demo is a JSF demo, you can use the Web Beans RI with - any Servlet based web framework. + Whilst this demo is a JSF demo, you can use Web Beans with any + Servlet based web framework. </para> </note> @@ -549,6 +642,37 @@ } }]]></programlisting> + + <section> + <title>The numberguess example for Tomcat</title> + + <para> + The numberguess for Tomcat differs in a couple of ways. Firstly, + Web Beans should be deployed as a Web Application library in + <literal>WEB-INF/lib</literal>. For your convenience we provide a + single jar suitable for running Web Beans on Tomcat + <literal>webbeans-tomcat.jar</literal>. + </para> + + <tip> + <para> + Of course, you must also include JSF and EL, as well common + annotations (<literal>jsr250-api.jar</literal>) which a JEE server + includes by default. + </para> + </tip> + + <para> + Secondly, we need to explicitly specify the Tomcat servlet listener + (used to boot Web Beans, and control it's interaction with requests) + in <literal>web.xml</literal>: + </para> + + <programlisting><![CDATA[<listener> + <listener-class>org.jboss.webbeans.environment.tomcat.Listener</listener-class> +</listener>]]></programlisting> + + </section> </section> <section>