Author: jbalunas(a)redhat.com Date: 2008-01-29 11:17:05 -0500 (Tue, 29 Jan 2008) New Revision: 7288 Modified: branches/Seam_2_0/doc/reference/en/modules/websphere.xml Log: added seam-gen section to chapter Modified: branches/Seam_2_0/doc/reference/en/modules/websphere.xml =================================================================== --- branches/Seam_2_0/doc/reference/en/modules/websphere.xml 2008-01-29 15:35:53 UTC (rev 7287) +++ branches/Seam_2_0/doc/reference/en/modules/websphere.xml 2008-01-29 16:17:05 UTC (rev 7288) @@ -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> @@ -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> + &lt;transaction:ejb-transaction /&gt; + </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[ +@Name("authenticator") @Stateless public class + AuthenticatorAction implements Authenticator {]]></programlisting> + + + <programlisting><![CDATA[ +@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> &lt;target name="war" + depends="compile" description="Build the distribution + .war file"&gt; </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>&lt;fileset dir="${basedir}"&gt;</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>