[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Gavin King
gavin.king at jboss.com
Fri Jun 15 12:29:07 EDT 2007
User: gavin
Date: 07/06/15 12:29:07
Modified: doc/reference/en/modules configuration.xml
Log:
update config to latest simplifications
Revision Changes Path
1.50 +110 -342 jboss-seam/doc/reference/en/modules/configuration.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: configuration.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/configuration.xml,v
retrieving revision 1.49
retrieving revision 1.50
diff -u -b -r1.49 -r1.50
--- configuration.xml 15 Jun 2007 07:36:20 -0000 1.49
+++ configuration.xml 15 Jun 2007 16:29:07 -0000 1.50
@@ -18,33 +18,38 @@
<sect2>
<title>Integrating Seam with JSF and your servlet container</title>
+
<para>
- Seam requires the following entry in your <literal>web.xml</literal>
- file:
+ Of course, you need a faces servlet!
</para>
- <programlisting><![CDATA[<listener>
- <listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
-</listener>]]></programlisting>
+ <programlisting><![CDATA[<servlet>
+ <servlet-name>Faces Servlet</servlet-name>
+ <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
+ <load-on-startup>1</load-on-startup>
+</servlet>
+
+<servlet-mapping>
+ <servlet-name>Faces Servlet</servlet-name>
+ <url-pattern>*.seam</url-pattern>
+</servlet-mapping>]]></programlisting>
<para>
- This listener is responsible for bootstrapping Seam, and for destroying
- session and application contexts.
+ (You can adjust the URL pattern to suit your taste.)
</para>
<para>
- To integrate with the JSF request lifecycle, we also need a JSF
- <literal>PhaseListener</literal> registered in in the
- <literal>faces-config.xml</literal> file:
+ In addition, Seam requires the following entry in your <literal>web.xml</literal>
+ file:
</para>
- <programlisting><![CDATA[<lifecycle>
- <phase-listener>org.jboss.seam.jsf.SeamPhaseListener</phase-listener>
-</lifecycle>]]></programlisting>
+ <programlisting><![CDATA[<listener>
+ <listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
+</listener>]]></programlisting>
<para>
- The actual listener class here varies depending upon how you want to
- manage transaction demarcation (more on this below).
+ This listener is responsible for bootstrapping Seam, and for destroying
+ session and application contexts.
</para>
<para>
@@ -62,6 +67,29 @@
</sect2>
<sect2>
+ <title>Using facelets</title>
+
+ <para>
+ If you want follow our advice and use facelets instead of JSP,
+ add the following lines to <literal>faces-config.xml</literal>:
+ </para>
+
+ <programlisting><![CDATA[<application>
+ <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
+</application>]]></programlisting>
+
+ <para>
+ And the following lines to <literal>web.xml</literal>:
+ </para>
+
+ <programlisting><![CDATA[<context-param>
+ <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
+ <param-value>.xhtml</param-value>
+</context-param>]]></programlisting>
+
+ </sect2>
+
+ <sect2>
<title>Seam Resource Servlet</title>
<para>
@@ -253,10 +281,11 @@
<sect3>
<title>Ajax4jsf</title>
+
<para>
- If Ajax4jsf is used in your project, Seam will install the Ajax4jsf filter for you, making sure
- to install it before all other built-in filters. You don't need to install the
- Ajax4jsf filter in <literal>web.xml</literal> yourself.
+ If Ajax4jsf is used in your project, Seam will install the Ajax4jsf filter for you,
+ making sure to install it before all other built-in filters. You don't need to install
+ the Ajax4jsf filter in <literal>web.xml</literal> yourself.
</para>
<para>
@@ -356,8 +385,8 @@
<para>
Seam can install your filters for you, allowing you to specify <emphasis>where</emphasis>
in the chain your filter is placed (the servlet specification doesn't provide a well defined order
- if you specify your filters in a <literal>web.xml</literal>). Just add the <literal>@Filter</literal> annotation
- to your Seam component (which must implement <literal>javax.servlet.Filter</literal>):
+ if you specify your filters in a <literal>web.xml</literal>). Just add the <literal>@Filter</literal>
+ annotation to your Seam component (which must implement <literal>javax.servlet.Filter</literal>):
</para>
<programlisting><![CDATA[@Startup
@@ -367,12 +396,13 @@
@Filter(within="org.jboss.seam.web.ajax4jsfFilter")
public class MultipartFilter extends AbstractFilter {]]></programlisting>
-
<para>
Adding the <literal>@Startup</literal> annotation means thar the component is available during
- Seam startup; bijection isn't available here (<literal>@Intercept(NEVER)</literal>); and the filter should be
- further down the chain than the Ajax4jsf filter (<literal>@Filter(within="org.jboss.seam.web.ajax4jsfFilter")</literal>).
+ Seam startup; bijection isn't available here (<literal>@Intercept(NEVER)</literal>); and the
+ filter should be further down the chain than the Ajax4jsf filter
+ (<literal>@Filter(within="org.jboss.seam.web.ajax4jsfFilter")</literal>).
</para>
+
</sect3>
</sect2>
@@ -385,8 +415,7 @@
to add the following interceptor configuration in <literal>ejb-jar.xml</literal>:
</para>
-<programlisting><![CDATA[
-<interceptors>
+<programlisting><![CDATA[<interceptors>
<interceptor>
<interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
</interceptor>
@@ -397,7 +426,7 @@
<ejb-name>*</ejb-name>
<interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
</interceptor-binding>
- </assembly-descriptor>
+</assembly-descriptor>
]]></programlisting>
<para>
@@ -440,29 +469,6 @@
</sect2>
<sect2>
- <title>Using facelets</title>
-
- <para>
- If you want follow our advice and use facelets instead of JSP,
- add the following lines to <literal>faces-config.xml</literal>:
- </para>
-
- <programlisting><![CDATA[<application>
- <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
-</application>]]></programlisting>
-
- <para>
- And the following lines to <literal>web.xml</literal>:
- </para>
-
- <programlisting><![CDATA[<context-param>
- <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
- <param-value>.xhtml</param-value>
-</context-param>]]></programlisting>
-
- </sect2>
-
- <sect2>
<title>Don't forget!</title>
<para>
@@ -524,6 +530,7 @@
<programlisting><![CDATA[my-application.ear/
jboss-seam.jar
jboss-el.jar
+ jboss-el-api.jar
META-INF/
MANIFEST.MF
application.xml
@@ -557,8 +564,8 @@
<para>
You must include <literal>jboss-seam.jar</literal>, <literal>jboss-el.jar</literal> and
- <literal>el-ri.jar</literal> in the EAR classpath. Make sure you reference all of these
- JARs from <literal>application.xml</literal>.
+ <literal>jboss-el-api.jar</literal> in the EAR classpath. Make sure you reference all of
+ these JARs from <literal>application.xml</literal>.
</para>
<para>
@@ -603,179 +610,6 @@
</sect1>
<sect1>
- <title>Configuring Seam in Java SE, with the JBoss Embeddable EJB3 container</title>
-
- <para>
- The JBoss Embeddable EJB3 container lets you run EJB3 components outside the context
- of the Java EE 5 application server. This is especially, but not only, useful for testing.
- </para>
-
- <para>
- The Seam booking example application includes a TestNG integration test suite that runs on
- the Embeddable EJB3 container.
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/testng.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="../shared/images/testng.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para>
- The booking example application may even be deployed to Tomcat.
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/e-ejb3.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="../shared/images/e-ejb3.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <sect2>
- <title>Installing the Embeddable EJB3 container</title>
-
- <para>
- Seam ships with a build of the Embeddable EJB3 container in the <literal>embedded-ejb</literal>
- directory. To use the Embeddable EJB3 container with Seam, add the
- <literal>embedded-ejb/conf</literal> directory, and all jars in the <literal>lib</literal>
- and <literal>embedded-ejb/lib</literal> directories to your classpath. Then, add the
- following line to <literal>components.xml</literal>:
- </para>
-
- <programlisting><![CDATA[<core:ejb />]]></programlisting>
-
- <para>
- This setting installs the built-in component named <literal>org.jboss.seam.core.ejb</literal>.
- This component is responsible for bootstrapping the EJB container when Seam is started,
- and shutting it down when the web application is undeployed.
- </para>
-
- </sect2>
-
- <sect2>
- <title>Configuring a datasource with the Embeddable EJB3 container</title>
-
- <para>
- You should refer to the Embeddable EJB3 container documentation for more information about
- configuring the container. You'll probably at least need to set up your own datasource.
- Embeddable EJB3 is implemented using the JBoss Microcontainer, so it's very easy to add
- new services to the minimal set of services provided by default. For example, I can add a
- new datasource by putting this <literal>jboss-beans.xml</literal> file in my classpath:
- </para>
-
- <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-
-<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:jboss:bean-deployer bean-deployer_1_0.xsd"
- xmlns="urn:jboss:bean-deployer">
-
- <bean name="bookingDatasourceBootstrap"
- class="org.jboss.resource.adapter.jdbc.local.LocalTxDataSource">
- <property name="driverClass">org.hsqldb.jdbcDriver</property>
- <property name="connectionURL">jdbc:hsqldb:.</property>
- <property name="userName">sa</property>
- <property name="jndiName">java:/bookingDatasource</property>
- <property name="minSize">0</property>
- <property name="maxSize">10</property>
- <property name="blockingTimeout">1000</property>
- <property name="idleTimeout">100000</property>
- <property name="transactionManager">
- <inject bean="TransactionManager"/>
- </property>
- <property name="cachedConnectionManager">
- <inject bean="CachedConnectionManager"/>
- </property>
- <property name="initialContextProperties">
- <inject bean="InitialContextProperties"/>
- </property>
- </bean>
-
- <bean name="bookingDatasource" class="java.lang.Object">
- <constructor factoryMethod="getDatasource">
- <factory bean="bookingDatasourceBootstrap"/>
- </constructor>
- </bean>
-
-</deployment>]]></programlisting>
-
- </sect2>
-
- <sect2>
- <title>Packaging</title>
-
- <para>
- The archive structure of a WAR-based deployment on an servlet engine like Tomcat
- will look something like this:
- </para>
-
- <programlisting><![CDATA[my-application.war/
- META-INF/
- MANIFEST.MF
- WEB-INF/
- web.xml
- components.xml
- faces-config.xml
- lib/
- jboss-seam.jar
- jboss-seam-ui.jar
- jboss-el.jar
- jsf-facelets.jar
- jsf-api.jar
- jsf-impl.jar
- jboss-ejb3.jar
- jboss-jca.jar
- jboss-j2ee.jar
- ...
- mc-conf.jar/
- ejb3-interceptors-aop.xml
- embedded-jboss-beans.xml
- default.persistence.properties
- jndi.properties
- login-config.xml
- security-beans.xml
- log4j.xml
- my-application.jar/
- META-INF/
- MANIFEST.MF
- persistence.xml
- jboss-beans.xml
- log4j.xml
- seam.properties
- org/
- jboss/
- myapplication/
- User.class
- Login.class
- LoginBean.class
- Register.class
- RegisterBean.class
- ...
- login.jsp
- register.jsp
- ...]]></programlisting>
-
- <para>
- The <literal>mc-conf.jar</literal> just contains the standard
- JBoss Microcontainer configuration files for Embeddable EJB3.
- You won't usually need to edit these files yourself.
- </para>
-
- <para>
- Most of the Seam example applications may be deployed to Tomcat by running
- <literal>ant deploy.tomcat</literal>.
- </para>
-
- </sect2>
-
- </sect1>
-
- <sect1>
<title>Configuring Seam in J2EE</title>
<para>
@@ -799,10 +633,9 @@
<para>
Seam JavaBean components do not provide declarative transaction demarcation like session
beans do. You <emphasis>could</emphasis> manage your transactions manually using the
- JTA <literal>UserTransaction</literal> (you could even implement your own declarative
- transaction management in a Seam interceptor). But most applications will use Seam managed
- transactions when using Hibernate with JavaBeans. Follow the instructions in the
- persistence chapter to install <literal>TransactionalSeamPhaseListener</literal>.
+ JTA <literal>UserTransaction</literal> or declaratively using Seam's
+ <literal>@Transactional</literal> annotation. But most applications will just use Seam
+ managed transactions when using Hibernate with JavaBeans.
</para>
<para>
@@ -864,11 +697,12 @@
lib/
jboss-seam.jar
jboss-seam-ui.jar
- el-api.jar
- el-ri.jar
+ jboss-el-api.jar
+ jboss-el.jar
jsf-facelets.jar
hibernate3.jar
hibernate-annotations.jar
+ hibernate-validator.jar
...
my-application.jar/
META-INF/
@@ -886,120 +720,65 @@
register.jsp
...]]></programlisting>
-
<para>
- If we want to deploy Hibernate in a non-J2EE environment like Tomcat or TestNG, we
- need to do a little bit more work.
+ If we want to deploy Hibernate in a non-EE environment like Tomcat or TestNG,
+ we need to do a little bit more work.
</para>
</sect2>
</sect1>
<sect1>
- <title>Configuring Seam in Java SE, with the JBoss Microcontainer</title>
+ <title>Configuring Seam in Java SE, with the JBoss Embedded</title>
+
<para>
- The Seam support for Hibernate and JPA requires JTA and a JCA datasource. If you are
- running in a non-EE environment like Tomcat or TestNG you can run these services,
- and Hibernate itself, in the JBoss Microcontainer.
+ JBoss Embedded lets you run EJB3 components outside the context of the Java EE 5
+ application server. This is especially, but not only, useful for testing.
</para>
<para>
- You can even deploy the Hibernate and JPA versions of the booking example in Tomcat.
+ The Seam booking example application includes a TestNG integration test suite that
+ runs on JBoss Embedded via <literal>SeamTest</literal>.
</para>
<mediaobject>
<imageobject role="fo">
- <imagedata fileref="images/hibernate-mc.png" align="center"/>
+ <imagedata fileref="images/testng.png" align="center"/>
</imageobject>
<imageobject role="html">
- <imagedata fileref="../shared/images/hibernate-mc.png" align="center"/>
+ <imagedata fileref="../shared/images/testng.png" align="center"/>
</imageobject>
</mediaobject>
<para>
- Seam ships with an example Microcontainer configuration in
- <literal>microcontainer/conf/jboss-beans.xml</literal> that provides all the things you
- need to run Seam with Hibernate in any non-EE environment. Just add the
- <literal>microcontainer/conf</literal> directory, and all jars in the <literal>lib</literal>
- and <literal>microcontainer/lib</literal> directories to your classpath. Refer to
- the documentation for the JBoss Microcontainer for more information.
- </para>
-
- <sect2>
- <title>Using Hibernate and the JBoss Microcontainer</title>
-
- <para>
- The built-in Seam component named <literal>org.jboss.seam.core.microcontainer</literal>
- bootstraps the microcontainer. As before, we probably want to use a Seam managed session.
+ The booking example application may even be deployed to Tomcat.
</para>
- <programlisting><![CDATA[<core:microcontainer/>
-
-<core:managed-hibernate-session name="bookingDatabase" auto-create="true"
- session-factory-jndi-name="java:/bookingSessionFactory"/>]]></programlisting>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/e-ejb3.png" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../shared/images/e-ejb3.png" align="center"/>
+ </imageobject>
+ </mediaobject>
- <para>
- Where <literal>java:/bookingSessionFactory</literal> is the name of the Hibernate session
- factory specified in <literal>hibernate.cfg.xml</literal>.
- </para>
+ <sect2>
+ <title>Installing JBoss Embedded</title>
<para>
- You'll need to provide a <literal>jboss-beans.xml</literal> file that installs JNDI,
- JTA, your JCA datasource and Hibernate into the microcontainer:
+ Please follow the instructions in the JBoss Embedded documentation to
+ install JBoss Embedded in Tomcat.
</para>
- <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-
-<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:jboss:bean-deployer bean-deployer_1_0.xsd"
- xmlns="urn:jboss:bean-deployer">
-
- <bean name="Naming" class="org.jnp.server.SingletonNamingServer"/>
-
- <bean name="TransactionManagerFactory"
- class="org.jboss.seam.microcontainer.TransactionManagerFactory"/>
- <bean name="TransactionManager" class="java.lang.Object">
- <constructor factoryMethod="getTransactionManager">
- <factory bean="TransactionManagerFactory"/>
- </constructor>
- </bean>
-
- <bean name="bookingDatasourceFactory"
- class="org.jboss.seam.microcontainer.DataSourceFactory">
- <property name="driverClass">org.hsqldb.jdbcDriver</property>
- <property name="connectionUrl">jdbc:hsqldb:.</property>
- <property name="userName">sa</property>
- <property name="jndiName">java:/hibernateDatasource</property>
- <property name="minSize">0</property>
- <property name="maxSize">10</property>
- <property name="blockingTimeout">1000</property>
- <property name="idleTimeout">100000</property>
- <property name="transactionManager"><inject bean="TransactionManager"/></property>
- </bean>
- <bean name="bookingDatasource" class="java.lang.Object">
- <constructor factoryMethod="getDataSource">
- <factory bean="bookingDatasourceFactory"/>
- </constructor>
- </bean>
-
- <bean name="bookingSessionFactoryFactory"
- class="org.jboss.seam.microcontainer.HibernateFactory"/>
- <bean name="bookingSessionFactory" class="java.lang.Object">
- <constructor factoryMethod="getSessionFactory">
- <factory bean="bookingSessionFactoryFactory"/>
- </constructor>
- <depends>bookingDatasource</depends>
- </bean>
-
-</deployment>]]></programlisting>
-
</sect2>
<sect2>
<title>Packaging</title>
<para>
- The WAR could have the following structure:
+ The archive structure of a WAR-based deployment on an servlet engine like Tomcat
+ will look something like this:
</para>
<programlisting><![CDATA[my-application.war/
@@ -1012,36 +791,35 @@
lib/
jboss-seam.jar
jboss-seam-ui.jar
+ jboss-el-api.jar
jboss-el.jar
jsf-facelets.jar
- hibernate3.jar
- ...
- jboss-microcontainer.jar
- jboss-jca.jar
- ...
jsf-api.jar
jsf-impl.jar
- mc-conf.jar/
- jndi.properties
- log4j.xml
+ ...
my-application.jar/
META-INF/
MANIFEST.MF
- jboss-beans.xml
+ persistence.xml
seam.properties
- hibernate.cfg.xml
- log4j.xml
org/
jboss/
myapplication/
User.class
Login.class
+ LoginBean.class
Register.class
+ RegisterBean.class
...
login.jsp
register.jsp
...]]></programlisting>
+ <para>
+ Most of the Seam example applications may be deployed to Tomcat by running
+ <literal>ant deploy.tomcat</literal>.
+ </para>
+
</sect2>
</sect1>
@@ -1112,6 +890,7 @@
<programlisting><![CDATA[my-application.ear/
jboss-seam.jar
jboss-el.jar
+ jboss-el-api.jar
jbpm-3.1.jar
META-INF/
MANIFEST.MF
@@ -1170,17 +949,6 @@
JBoss Portal.
</para>
- <para>
- In addition, you'll need to use a portlet-specific phase listener
- instead of <literal>SeamPhaseListener</literal> or
- <literal>TransactionalSeamPhaseListener</literal>.
- The <literal>SeamPortletPhaseListener</literal> and
- <literal>TransactionalSeamPortletPhaseListener</literal>
- are adapted to the portlet lifecycle. I would like to offer my
- sincerest apologies for the name of that last class. I really
- couldn't think of anything better. Sorry.
- </para>
-
</sect1>
<sect1>
More information about the jboss-cvs-commits
mailing list