[webbeans-commits] Webbeans SVN: r2248 - doc/trunk/reference/en-US.
webbeans-commits at lists.jboss.org
webbeans-commits at lists.jboss.org
Sat Mar 28 12:41:24 EDT 2009
Author: pete.muir at 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</ulink>,
- 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</ulink>,
+ 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</ulink>,
- and unzip it. For example
- </para>
-
- <programlisting><![CDATA[$ cd ~/
+ <para>
+ Next, download Web Beans from
+ <ulink url="http://seamframework.org/Download">seamframework.org</ulink>,
+ 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.org</ulink>,
+ 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</ulink>,
+ 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>
More information about the weld-commits
mailing list