[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>
+                           &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[
+ 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> &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>




More information about the seam-commits mailing list