[seam-commits] Seam SVN: r7289 - trunk/doc/reference/en/modules.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Tue Jan 29 11:25:14 EST 2008
Author: jbalunas at redhat.com
Date: 2008-01-29 11:25:13 -0500 (Tue, 29 Jan 2008)
New Revision: 7289
Modified:
trunk/doc/reference/en/modules/websphere.xml
Log:
updated with seam-gen section
Modified: trunk/doc/reference/en/modules/websphere.xml
===================================================================
--- trunk/doc/reference/en/modules/websphere.xml 2008-01-29 16:17:05 UTC (rev 7288)
+++ trunk/doc/reference/en/modules/websphere.xml 2008-01-29 16:25:13 UTC (rev 7289)
@@ -51,6 +51,13 @@
profile with the EJB3 feature pack enabled, or augment one of your
existing ones. This can also be done after the installation
by running the profile managment tool.</para>
+ <note>
+ <title>A note about restarting the server</title>
+ <para>There are times that restarting the server will be required after
+ deploying or changes the examples in this chapter. Its does not seem
+ like every change requires a restart. If you get errors or exceptions
+ after modifing a property or deploying an application try to restart
+ the server. </para> </note>
</section>
<section>
@@ -161,7 +168,7 @@
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
]]></programlisting>
- <para>Next, er have to make some changes to the EJB references
+ <para>Next, we have to make some changes to the EJB references
in the <literal>web.xml</literal>. These changes are
what will allow Websphere to bind the EJB2 references in
the web module to the the actual EJB3 beans in the EAR
@@ -940,4 +947,564 @@
</section>
+ <section>
+ <title>Deploying an application created using
+ <literal>seam-gen</literal> on Websphere 6.1.0.13</title>
+
+ <para><literal>seam-gen</literal> is a very useful tool for developers
+ to quickly get an application up and running, and provides a foundation
+ to add your own functionality. Out of box <literal>seam-gen</literal>
+ will produce applications configured to run on JBoss AS. These
+ instructions will show the steps needed to get it to run on Websphere.
+ As stated above in <xref linkend="jee5-websphere-section"/> there
+ are some tricky changes needed to get an EJB3 application running. This
+ section will take you through the exact steps.</para>
+
+ <para>The first step is setting up <literal>seam-gen</literal> to
+ construct the base project. There are several choices made below,
+ specifically the datasource and hibernate values that we will adjust
+ once the project is created.</para>
+
+
+ <programlisting><![CDATA[
+./seam setup
+Buildfile: build.xml
+
+init:
+
+setup:
+ [echo] Welcome to seam-gen :-)
+ [input] Enter your Java project workspace (the directory that contains your Seam projects) [C:/Projects] [C:/Projects]
+/home/jbalunas/workspace
+ [input] Enter your JBoss home directory [C:/Program Files/jboss-4.2.2.GA] [C:/Program Files/jboss-4.2.2.GA]
+/home/jbalunas/jboss/jboss-4.2.2.GA
+ [input] Enter the project name [myproject] [myproject]
+websphere_example
+ [echo] Accepted project name as: websphere_example
+ [input] Do you want to use ICEFaces instead of RichFaces [n] (y, [n], )
+
+ [input] skipping input as property icefaces.home.new has already been set.
+ [input] Select a RichFaces skin [blueSky] ([blueSky], classic, ruby, wine, deepMarine, emeraldTown, sakura, DEFAULT)
+
+ [input] Is this project deployed as an EAR (with EJB components) or a WAR (with no EJB support) [ear] ([ear], war, )
+
+ [input] Enter the Java package name for your session beans [com.mydomain.websphere_example] [com.mydomain.websphere_example]
+org.jboss.seam.tutorial.websphere.action
+ [input] Enter the Java package name for your entity beans [org.jboss.seam.tutorial.websphere.action] [org.jboss.seam.tutorial.websphere.action]
+org.jboss.seam.tutorial.websphere.model
+ [input] Enter the Java package name for your test cases [org.jboss.seam.tutorial.websphere.action.test] [org.jboss.seam.tutorial.websphere.action.test]
+org.jboss.seam.tutorial.websphere.test
+ [input] What kind of database are you using? [hsql] ([hsql], mysql, oracle, postgres, mssql, db2, sybase, enterprisedb, h2)
+
+ [input] Enter the Hibernate dialect for your database [org.hibernate.dialect.HSQLDialect] [org.hibernate.dialect.HSQLDialect]
+
+ [input] Enter the filesystem path to the JDBC driver jar [lib/hsqldb.jar] [lib/hsqldb.jar]
+
+ [input] Enter JDBC driver class for your database [org.hsqldb.jdbcDriver] [org.hsqldb.jdbcDriver]
+
+ [input] Enter the JDBC URL for your database [jdbc:hsqldb:.] [jdbc:hsqldb:.]
+
+ [input] Enter database username [sa] [sa]
+
+ [input] Enter database password [] []
+
+ [input] Enter the database schema name (it is OK to leave this blank) [] []
+
+ [input] Enter the database catalog name (it is OK to leave this blank) [] []
+
+ [input] Are you working with tables that already exist in the database? [n] (y, [n], )
+
+ [input] Do you want to drop and recreate the database tables and data in import.sql each time you deploy? [n] (y, [n], )
+
+[propertyfile] Creating new property file: /rhdev/projects/jboss-seam/svn-seam_2_0/jboss-seam-2_0/seam-gen/build.properties
+ [echo] Installing JDBC driver jar to JBoss server
+ [copy] Copying 1 file to /home/jbalunas/jboss/jboss-4.2.2.GA/server/default/lib
+ [echo] Type 'seam create-project' to create the new project
+
+BUILD SUCCESSFUL
+Total time: 3 minutes 5 seconds]]></programlisting>
+
+ <para> Type <literal>./seam new-project</literal> to create your
+ project and <literal>cd
+ /home/jbalunas/workspace/websphere_example</literal> to the
+ newly created structure. </para>
+
+ </section>
+ <section>
+ <title>Changes needed for deployment to Websphere</title>
+ <para>We now need to make some changes to the generated project.</para>
+ <section>
+ <title>Configuration file changes</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>resources/META-INF/persistence-dev.xml</literal>
+ </term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para> Alter the
+ <literal>jta-data-source</literal> to be
+ <literal>DefaultDatasource</literal>. We are
+ going to be using the integrated Websphere
+ DB.</para>
+ </listitem>
+ <listitem>
+ <para> Add or change the properties below.
+ These are described in detail at <xref
+ linkend="jee5-websphere-section"/>:
+ </para>
+
+ <programlisting><![CDATA[
+<property name="hibernate.dialect" value="GlassfishDerbyDialect"/>
+<property name="hibernate.hbm2ddl.auto" value="update"/>
+<property name="hibernate.show_sql" value="true"/>
+<property name="hibernate.format_sql" value="true"/>
+<property name="hibernate.cache.provider_class"
+ value="org.hibernate.cache.HashtableCacheProvider"/>
+<property name="hibernate.transaction.manager_lookup_class"
+ value="org.hibernate.transaction.WebSphereExtendedJTATransactionLookup"/>]]></programlisting>
+ </listitem>
+ <listitem>
+ <para> Remove the JBoss AS specific method of exposing
+ the EntityManagerFactory: </para>
+
+ <programlisting><![CDATA[<property
+ name="jboss.entity.manager.factory.jndi.name"
+ value="java:/websphere_exampleEntityManagerFactory">]]></programlisting>
+ </listitem>
+ <listitem>
+ <para> You'll need to alter
+ <literal>persistence-prod.xml</literal> as
+ well if you want to deploy to Websphere using the
+ prod profile. </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>resources/GlassfishDerbyDialect.class</literal>
+ </term>
+ <listitem>
+ <para>As with other examples we need to include this class for
+ DB support. It can be copied from the
+ <literal>jpa</literal> example into the
+ <literal>websphere_example/resources</literal>
+ directory.
+
+ <programlisting><![CDATA[
+cp $SEAM/examples/jpa/resources-websphere61/WEB-INF/classes/GlassfishDerbyDialect.class
+ ./resources]]></programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>resources/META-INF/jboss-app.xml</literal>
+ </term>
+ <listitem>
+ <para> You can delete this file as we aren't deploying to JBoss
+ AS ( <literal>jboss-app.xml</literal> is used to enable
+ classloading isolation in JBoss AS) </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <literal>resources/*-ds.xml</literal>
+ </term>
+ <listitem>
+ <para> You can delete these file as we aren't deploying to
+ JBoss AS (these files define datasources in JBoss AS, we
+ are using Websphere's default datasource) </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>resources/WEB-INF/components.xml</literal>
+ </term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para> Enable container managed transaction
+ integration - add the <literal>
+ <transaction:ejb-transaction />
+ </literal> component, and it's namespace
+ declaration <literal>
+ xmlns:transaction="http://jboss.com/products/seam/transaction"
+ </literal> </para>
+ </listitem>
+ <listitem>
+ <para> Alter the <literal>jndi-pattern</literal>
+ to <literal>
+ java:comp/env/websphere_example/#{ejbName}
+ </literal> </para>
+ </listitem>
+ <listitem>
+ <para>We do not need
+ <literal>managed-persistence-context</literal>
+ for this example and so can delete its
+ entry.</para>
+
+
+ <programlisting><![CDATA[
+<persistence:managed-persistence-context name="entityManager"
+ auto-create="true"
+ persistence-unit-jndi-name="java:/websphere_exampleEntityManagerFactory"/> ]]></programlisting>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <literal>resources/WEB-INF/web.xml</literal>
+ </term>
+ <listitem>
+ <para> Websphere does not support <literal>Servlet
+ 2.5</literal>, it required <literal>Servlet
+ 2.4</literal>. For this change we need to adjust the top of
+ the <literal>web.xml</literal> file to look like the
+ following:</para>
+
+ <programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<web-app version="2.4"
+ xmlns="http://java.sun.com/xml/ns/j2ee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
+ http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
+ ]]></programlisting>
+
+ <para>As with the <literal>jee5/booking</literal>
+ example we need to add EJB references to the web.xml. These
+ references require the empty
+ <literal>local-home</literal> to flag them for
+ Websphere to perform the proper binding.</para>
+
+
+ <programlisting><![CDATA[
+ <ejb-local-ref>
+ <ejb-ref-name>websphere_example/AuthenticatorAction</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <local-home></local-home>
+ <local>org.jboss.seam.tutorial.websphere.action.Authenticator</local>
+ </ejb-local-ref>
+
+ <ejb-local-ref>
+ <ejb-ref-name>websphere_example/EjbSynchronizations</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <local-home></local-home>
+ <local>org.jboss.seam.transaction.LocalEjbSynchronizations</local>
+ </ejb-local-ref>]]></programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section>
+ <title>Creating the <literal>AuthenticatorAction</literal>
+ EJB</title>
+ <para> We want to take the existing <literal>Authenticator</literal>
+ Seam POJO component and create an EJB3 out of it. </para>
+ <orderedlist>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para> Rename the class to
+ <literal>AuthenticatorAction</literal> </para>
+ </listitem>
+ <listitem>
+ <para> Add the <literal>@Stateless</literal>
+ annotation to the new
+ <literal>AuthenticatorAction</literal> class.
+ </para>
+ </listitem>
+ <listitem>
+ <para> Create an interface called
+ <literal>Authenticator</literal> which
+ <literal>AuthenticatorAction</literal>
+ implements (EJB3 requires session beans to have a
+ local interface). Annotate the interface with
+ <literal>@Local</literal> , and add a single method
+ with same signature as the
+ <literal>authenticate</literal> in
+ <literal>AuthenticatorAction</literal> . </para>
+ </listitem>
+ </itemizedlist>
+
+
+ <programlisting><![CDATA[
+ at Name("authenticator") @Stateless public class
+ AuthenticatorAction implements Authenticator {]]></programlisting>
+
+
+ <programlisting><![CDATA[
+ at Local public interface Authenticator {
+ public boolean authenticate();
+}]]></programlisting>
+ </listitem>
+ <listitem>
+ <para>We've already added its reference to the
+ <literal>web.xml</literal> file so are good to go. </para>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section>
+ <title>Extra jar dependencies and other changes to the
+ <literal>build.xml</literal></title>
+ <para> This application has similar requirements as the
+ <literal>jee5/booking</literal> example. </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Change the default target to
+ <literal>archive</literal> (we aren't going to cover
+ automatic deployment to Websphere).
+
+
+ <programlisting><![CDATA[
+<project name="websphere_example" default="archive" basedir=".">]]></programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Websphere looks for the drools
+ <literal>/security.drl</literal> file in the root of the
+ <literal>war</literal> file instead of the root of the
+ <literal>websphere_example.jar</literal> so we need
+ to have the <literal>build.xml</literal> move it to the
+ correct location at build time. The following must be added at
+ the top of the <literal> <target name="war"
+ depends="compile" description="Build the distribution
+ .war file"> </literal> target.
+
+ <programlisting><![CDATA[
+<copy todir="${war.dir}">
+ <fileset dir="${basedir}/resources" >
+ <include name="*.drl" />
+ </fileset>
+</copy>]]></programlisting></para>
+ </listitem>
+ <listitem>
+ <para>We need to ge the
+ <literal>GlassfishDerbyDialect.class</literal> into
+ our application jar. To do that find the
+ <literal>jar</literal> task and modify the top of it so that
+ it looks like this:
+
+
+ <programlisting><![CDATA[
+<target name="jar" depends="compile,copyclasses"
+ description="Build the distribution .jar file">
+ <copy todir="${jar.dir}">
+ <fileset dir="${basedir}/resources">
+ <include name="seam.properties" />
+ <include name="*.drl" />
+ <include name="GlassfishDerbyDialect.class" />
+ </fileset>
+ </copy>
+...]]></programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Next we need to get the
+ <literal>jboss-seam.jar</literal> into the base of the
+ <literal>EAR</literal> file. For deployment Websphere
+ requires this jar to be in both the <literal>/lib</literal>
+ directory and at the base of the <literal>EAR</literal>. You
+ must add the following to the <literal>archive</literal>
+ task: </para>
+
+
+ <programlisting><![CDATA[
+<fileset dir="${lib.dir}">
+ <include name="jboss-seam.jar" />
+</fileset>]]></programlisting>
+ <para>So that the whole <literal>archive</literal> task looks
+ like:</para>
+
+
+ <programlisting><![CDATA[
+<target name="archive" depends="jar,war,ear"
+ description="Package the archives">
+ <jar jarfile="${dist.dir}/${project.name}.jar" basedir="${jar.dir}"/>
+ <jar jarfile="${dist.dir}/${project.name}.war" basedir="${war.dir}"/>
+ <jar jarfile="${dist.dir}/${project.name}.ear">
+ <fileset dir="${ear.dir}"/>
+ <fileset dir="${dist.dir}">
+ <include name="${project.name}.jar"/>
+ <include name="${project.name}.war"/>
+ </fileset>
+ <fileset dir="${lib.dir}">
+ <include name="jboss-seam.jar" />
+ </fileset>
+ </jar>
+</target>]]></programlisting>
+ </listitem>
+ <listitem>
+ <para>Now we need to get extra jars into the
+ <literal>build.xml</literal>. Look for the
+ <literal><fileset dir="${basedir}"></literal> section
+ of the task below. Add the new includes at the bottom of
+ the fileset.
+ </para>
+
+
+ <programlisting><![CDATA[
+<target name="ear" description="Build the EAR">
+ <copy todir="${ear.dir}">
+ <fileset dir="${basedir}/resources">
+ <include name="*jpdl.xml" />
+ <include name="*hibernate.cfg.xml" />
+ <include name="jbpm.cfg.xml" />
+ </fileset>
+ <fileset dir="${lib.dir}">
+ <include name="jboss-seam.jar" />
+ </fileset>
+ <fileset dir="${basedir}">
+ <include name="lib/jbpm*.jar" />
+ <include name="lib/jboss-el.jar" />
+ <include name="lib/drools-*.jar"/>
+ <include name="lib/core.jar"/>
+ <include name="lib/janino*.jar"/>
+ <include name="lib/antlr-*.jar"/>
+ <include name="lib/mvel*.jar"/>
+ <include name="lib/richfaces-api*.jar" />
+ </fileset>
+ </copy>
+ <copy todir="${ear.dir}/META-INF">
+ <fileset dir="${basedir}/resources/META-INF">
+ <include name="application.xml" />
+ <include name="jboss-app.xml" />
+ </fileset>
+ </copy>
+</target>]]></programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>Hibernate dependencies</para>
+ <programlisting><![CDATA[
+ <!-- Hibernate and deps -->
+ <include name="lib/hibernate.jar"/>
+ <include name="lib/hibernate-commons-annotations.jar"/>
+ <include name="lib/hibernate-annotations.jar"/>
+ <include name="lib/hibernate-entitymanager.jar"/>
+ <include name="lib/hibernate-validator.jar"/>
+ <include name="lib/jboss-common-core.jar" />]]></programlisting>
+ </listitem>
+ <listitem>
+ <para>JSF dependencies. You will need to copy the
+ <literal>el-ri.jar</literal> from the
+ <literal>$SEAM/examples/jpa/lib</literal> directory.</para>
+ <programlisting><![CDATA[
+ <!-- jsf libs -->
+ <include name="lib/jsf-api.jar" />
+ <include name="lib/jsf-impl.jar" />
+ <include name="lib/el-api.jar" />
+ <include name="lib/el-ri.jar"/>]]></programlisting>
+ </listitem>
+ <listitem>
+ <para> Third party dependencies. You will need to copy the
+ <literal>jboss-archive-browsing.jar</literal> from the
+ <literal>$SEAM/examples/jpa/lib</literal> directory into the
+ the projects <literal>/lib</literal> directory. You will
+ also need to acquire the <literal>concurrent.jar</literal>
+ and place it in the same directory. You can get this from
+ any jboss distribution or just search for it.</para>
+ <programlisting><![CDATA[
+ <!-- 3rd party and supporting jars -->
+ <!--<include name="lib/log4j.jar" />-->
+ <include name="lib/javassist.jar"/>
+ <include name="lib/dom4j.jar" />
+ <include name="lib/jboss-archive-browsing.jar" />
+ <include name="lib/concurrent.jar" />
+ <include name="lib/cglib.jar"/>
+ <include name="lib/asm.jar"/>
+ <include name="lib/antlr.jar" />
+ <include name="lib/commons-logging.jar" />
+ <include name="lib/commons-collections.jar" />]]></programlisting>
+ </listitem>
+ <listitem>
+ <para><literal>jboss-seam.jar</literal> - this is needed in
+ both the <literal>ear</literal> base and
+ <literal>/lib</literal>
+ directory.</para>
+ <programlisting><![CDATA[
+ <!-- seam jar -->
+ <include name="lib/jboss-seam.jar" />]]></programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>You should end up with something like:</para>
+ <programlisting><![CDATA[
+<fileset dir="${basedir}">
+ <include name="lib/jbpm*.jar" />
+ <include name="lib/jboss-el.jar" />
+ <include name="lib/drools-*.jar"/>
+ <include name="lib/core.jar"/>
+ <include name="lib/janino*.jar"/>
+ <include name="lib/antlr-*.jar"/>
+ <include name="lib/mvel*.jar"/>
+ <include name="lib/richfaces-api*.jar" />
+
+ <!-- Hibernate and deps -->
+ <include name="lib/hibernate.jar"/>
+ <include name="lib/hibernate-commons-annotations.jar"/>
+ <include name="lib/hibernate-annotations.jar"/>
+ <include name="lib/hibernate-entitymanager.jar"/>
+ <include name="lib/hibernate-validator.jar"/>
+ <include name="lib/jboss-common-core.jar" />
+
+ <!-- jsf libs -->
+ <include name="lib/jsf-api.jar" />
+ <include name="lib/jsf-impl.jar" />
+ <include name="lib/el-api.jar" />
+ <include name="lib/el-ri.jar"/>
+
+ <!-- 3rd party and supporting jars -->
+ <!--<include name="lib/log4j.jar" />-->
+ <include name="lib/javassist.jar"/>
+ <include name="lib/dom4j.jar" />
+ <include name="lib/jboss-archive-browsing.jar" />
+ <include name="lib/concurrent.jar" />
+ <include name="lib/cglib.jar"/>
+ <include name="lib/asm.jar"/>
+ <include name="lib/antlr.jar" />
+ <include name="lib/commons-logging.jar" />
+ <include name="lib/commons-collections.jar" />
+
+ <!-- seam jar -->
+ <include name="lib/jboss-seam.jar" />
+
+</fileset>]]></programlisting>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+ <section>
+ <title> Building and deploying the seam-gen'd application to Websphere
+ </title>
+
+
+ <itemizedlist>
+ <listitem>
+ <para> Build your application by calling
+ <literal>ant</literal> in the base directory of your
+ project (ex.
+ <literal>/home/jbalunas/workspace/websphere_example</literal>
+ ). The target of the build will be
+ <literal>dist/websphere_example.ear</literal> . </para>
+ </listitem>
+
+ <listitem>
+ <para>To deploy the application follow the instructions here :
+ <xref linkend="jee5-websphere-deploy"/> but use references to
+ this project <literal>websphere_example</literal> instead of
+ <literal>jboss-seam-jee5</literal>.</para>
+ </listitem>
+ <listitem>
+ <para> Checkout the app at:
+ <literal>http://localhost:9080/websphere_example/index.html</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+ </section>
+
</chapter>
More information about the seam-commits
mailing list