[seam-commits] Seam SVN: r7270 - branches/Seam_2_0/doc/reference/en/modules.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Mon Jan 28 17:08:23 EST 2008
Author: jbalunas at redhat.com
Date: 2008-01-28 17:08:22 -0500 (Mon, 28 Jan 2008)
New Revision: 7270
Added:
branches/Seam_2_0/doc/reference/en/modules/websphere.xml
Log:
initial implementation of websphere chapter
Added: branches/Seam_2_0/doc/reference/en/modules/websphere.xml
===================================================================
--- branches/Seam_2_0/doc/reference/en/modules/websphere.xml (rev 0)
+++ branches/Seam_2_0/doc/reference/en/modules/websphere.xml 2008-01-28 22:08:22 UTC (rev 7270)
@@ -0,0 +1,946 @@
+<chapter id="websphere">
+ <title>Seam on IBM's Websphere</title>
+
+ <para>Websphere 6.1.x is IBM's application server offering. The latest
+ release is 6.1.0.13 which does not have <literal>EJB3</literal> or
+ <literal>JEE5</literal> support. There is a recently released (Nov 07)
+ <literal>EJB3</literal> feature pack which provides some support for
+ <literal>EJB3</literal> and <literal>JPA</literal>. Currently there
+ is no true <literal>JEE5</literal> offering from IBM. This causes some
+ issues with Seam integration with applications that use EJB3.</para>
+
+ <para>First we will go over some basic information about the Websphere
+ environment that we used for these examples. After a good deal of research
+ and work we were able to get EJB3 applications to function correctly. We will
+ go over the details of those steps with the jee5 example. We will also deploy
+ the the JPA example application. </para>
+
+ <section>
+ <title>Websphere environment and deployment information</title>
+
+ <para>Websphere is a commercial product and so we will not discuss the
+ details of its installation other than to say follow the directions
+ provided by your particular installation type and license. This
+ section will detail the exact server versions used, installation tips,
+ and some custom properties that are needed for all of the
+ examples.</para>
+
+ <section>
+ <title>Installation versions and tips</title>
+ <para>All of the examples and information in this chapter are based on
+ the the latest version of Websphere at the time of this writing.
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+ url="http://www.ibm.com/developerworks/websphere/zones/was/">
+ Websphere Application Server 6.1.0.13</ulink></para>
+ </listitem>
+ <listitem>
+ <para><ulink
+ url="http://www-1.ibm.com/support/docview.wss?rs=180&uid=swg21287579">
+ Feature Pack for EJB 3.0 for Websphere Application Server
+ V6.1 (3.0.6.1.0.13)</ulink></para>
+ </listitem>
+ </itemizedlist> </para>
+
+ <para>The EJB3 feature pack that we installed came with the 6.1.0.13
+ patch version of Websphere. Installing the feature pack does not
+ ensure that your server will have the proper environment for EJB3
+ applications. Be sure that as part of the installation of the feature
+ pack you follow the instructions to create a new server
+ 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>
+ </section>
+
+ <section>
+ <title>Required custom properties</title>
+ <para>There are a couple of Websphere custom properties that are required
+ for Seam integration. These properties are not needed specifically
+ for seam, but work around some issues with Websphere. These are
+ set following the instructions here : <ulink
+ url="http://www-1.ibm.com/support/docview.wss?rss=180&uid=swg21284395">
+ Setting web container custom properties</ulink></para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>prependSlashToResource = "true"</literal>
+ — This solves a fairly common issue with Websphere
+ where applications are not using a leading "/" when
+ attempting to access resources. If this is not set then a
+ <literal>java.net.MalformedURLException</literal>
+ will be thrown. With this property set you will still see
+ warnings, but the resources will be retrieved as expected.
+ <note>
+ <title>Detailed can be found at:</title>
+ <para><ulink
+ url="http://www-1.ibm.com/support/docview.wss?uid=swg21190234">
+ SRVE0238E: Resource paths must have a leading
+ slash</ulink></para> </note> </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>com.ibm.ws.webcontainer.invokefilterscompatibility
+ = "true"</literal> — This solves an issue with
+ Websphere where it throws a
+ <literal>FileNotFoundException</literal> when a web
+ application attempts to access a file resource that does not
+ actually exist on disk. This is a common practice in modern web
+ applications where filters or servlets are used to process
+ resource requests like these. This issue manifests itself as
+ failures to retrieve JavaScript, CSS, images, etc... when
+ requesting a web page. <note>
+ <title>Detailed can be found at:</title>
+ <para><ulink
+ url="http://www-1.ibm.com/support/docview.wss?uid=swg24014758">
+ PK33090; 6.1: A filter that serves a file does not pop-up an
+ alert message</ulink></para> </note></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ <section id="jee5-websphere-section">
+ <title> The <literal>jee5/booking</literal> example </title>
+
+ <para> The <literal>jee5/booking</literal> example is based on the Hotel
+ Booking example (which runs on JBoss AS). Out of the box it is designed
+ to run on Glassfish, but with the steps below it can be deployed to
+ Websphere. It is located in the
+ <literal>$SEAM_DIST/examples/jee5/booking</literal> directory.
+ </para>
+
+ <para>As stated before the <literal>EJB3</literal> feature pack does not
+ provide a full <literal>jee5</literal> implementation. This means
+ that there are some tricks to getting an application deployed and
+ functioning. </para>
+
+ <section>
+ <title>Configuration file changes</title>
+
+ <para>Below are the configuration file changes that are need to the base
+ example.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>resources/WEB-INF/components.xml</literal>
+ </term>
+ <listitem>
+ <para>We need to change the way that we look up EJBs for
+ Websphere. We need to remove the
+ <literal>/local</literal> from the end of the
+ <literal>jndi-pattern</literal> attribute. It should
+ look like this: </para>
+
+
+ <programlisting><![CDATA[
+<core:init jndi-pattern="java:comp/env/jboss-seam-jee5/#{ejbName}" debug="true"/>
+ ]]></programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <literal>resources/WEB-INF/web.xml</literal>
+ </term>
+ <listitem>
+ <para>This is the first place that we notice an unexpected
+ change because this is not full <literal>jee5</literal>
+ implementation. </para>
+ <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>Next you 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
+ module. Replace all of the
+ <literal>ejb-local-refs</literal> when the values
+ below.</para>
+
+
+ <programlisting><![CDATA[
+ <!-- JEE5 EJB3 names -->
+ <ejb-local-ref>
+ <ejb-ref-name>jboss-seam-jee5/AuthenticatorAction</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <local-home></local-home>
+ <local>org.jboss.seam.example.booking.Authenticator</local>
+ </ejb-local-ref>
+
+ <ejb-local-ref>
+ <ejb-ref-name>jboss-seam-jee5/BookingListAction</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <local-home></local-home>
+ <local>org.jboss.seam.example.booking.BookingList</local>
+ </ejb-local-ref>
+
+ <ejb-local-ref>
+ <ejb-ref-name>jboss-seam-jee5/RegisterAction</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <local-home></local-home>
+ <local>org.jboss.seam.example.booking.Register</local>
+ </ejb-local-ref>
+
+ <ejb-local-ref>
+ <ejb-ref-name>jboss-seam-jee5/ChangePasswordAction</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <local-home></local-home>
+ <local>org.jboss.seam.example.booking.ChangePassword</local>
+ </ejb-local-ref>
+
+ <ejb-local-ref>
+ <ejb-ref-name>jboss-seam-jee5/HotelBookingAction</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <local-home></local-home>
+ <local>org.jboss.seam.example.booking.HotelBooking</local>
+ </ejb-local-ref>
+
+ <ejb-local-ref>
+ <ejb-ref-name>jboss-seam-jee5/HotelSearchingAction</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <local-home></local-home>
+ <local>org.jboss.seam.example.booking.HotelSAll of the examples and informaearching</local>
+ </ejb-local-ref>
+
+ <ejb-local-ref>
+ <ejb-ref-name>jboss-seam-jee5/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>
+ <para>The important changes are that there is an empty
+ <literal>local-home</literal> element for each EJB.
+ This is the signal to Websphere so that it will make the
+ correct bindings behind the scenes between the web module
+ and the EJB3 beans. The <literal>ejb-link</literal>
+ element is simply not used. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>resources/META-INF/persistence.xml</literal>
+ </term>
+ <listitem>
+ <para>For this example we will be using the default
+ datasource that comes with Websphere. To do this change the
+ <literal>jta-data-source</literal> element like below.</para>
+ <programlisting><![CDATA[
+<jta-data-source>DefaultDatasource</jta-data-source>
+ ]]></programlisting>
+ <para>Then we need to adjust some of the hibernate
+ properties. First comment out the Glassfish properties.
+ Next you need to add/change the properties below. </para>
+
+
+ <programlisting><![CDATA[
+<!--<property name="hibernate.transaction.flush_before_completion" value="true"/>-->
+<property name="hibernate.cache.provider_class"
+ value="org.hibernate.cache.HashtableCacheProvider"/>
+<property name="hibernate.dialect" value="GlassfishDerbyDialect"/>
+<property name="hibernate.transaction.manager_lookup_class"
+ value="org.hibernate.transaction.WebSphereExtendedJTATransactionLookup"/>
+ ]]></programlisting>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>hibernate.transaction.manager_lookup_class</literal>
+ — Standard hibernate transaction
+ manager property for Websphere 6.X</para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>hibernate.transaction.flush_before_completion</literal>
+ — This is commented out because we want
+ the container to manage the transactions. Also
+ if this is set to <literal>true</literal> an
+ exception will be thrown by Websphere when the
+ EJBContext is looked up.
+
+
+ <programlisting><![CDATA[
+com.ibm.wsspi.injectionengine.InjectionException:
+ EJBContext may only be looked up by or injected into an EJB
+ ]]></programlisting></para>
+ </listitem>
+ <listitem>
+ <para><literal>hibernate.dialect</literal>
+ — From WAS 6.1.0.9 on the embedded DB was
+ switched to the same Derby DB in
+ Glassfish.</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>resources/GlassfishDerbyDialect.class</literal>
+ </term>
+ <listitem>
+ <para>You will need to get the
+ <literal>GlassfishDerbyDialect.class</literal> and
+ copy it into the <literal>/resources</literal>
+ directory. The class exists in the JPA example and can be
+ copied using the command below assuming you are in
+ <literal>jee5/booking</literal> directory:</para>
+
+
+ <programlisting><![CDATA[
+cp ../../jpa/resources-websphere61/WEB-INF/classes/GlassfishDerbyDialect.class
+ ./resources]]></programlisting>
+ <para>This class will be put into the
+ <literal>jboss-seam-jee5.jar</literal> file using
+ changes to the build.xml discussed later. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <literal>resources/import.sql</literal>
+ </term>
+ <listitem>
+ <para>This file must also be copied from the JPA example
+ because either the Derby DB or the dialect does not support
+ changes to the <literal>ID</literal> column. The files
+ are identical except for the column difference. Use the
+ following command to make the copy
+
+
+ <programlisting><![CDATA[
+cp ../../jpa/resources-websphere61/import.sql ./resources]]></programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </section>
+
+ <section>
+ <title>Building the <literal>jee5/booking</literal>
+ example</title>
+
+ <para>In order to get the changes we have made into our application we
+ need to make some changes to the <literal>build.xml</literal>.
+ There are also some additional jars that are required by our
+ application in order to work with Websphere. This section will cover
+ what changes are needed to the <literal>build.xml</literal>.</para>
+
+ <section>
+ <title>New libraries dependencies</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>JSF libraries — Websphere 6.1 comes with
+ their own version of JSF 1.1 (Seam requires JSF 1.2). So
+ we must add these jars to our application.
+ <itemizedlist>
+ <listitem>
+ <para><literal>jsf-api.jar</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>jsf-impl.jar</literal>
+ </para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para>Since Websphere is not a fully compliant
+ <literal>JEE5</literal> implementation we need to
+ add these expression language libraries as well:
+ <itemizedlist>
+ <listitem>
+ <para><literal>el-api.jar</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>el-ri.jar</literal>
+ </para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para><literal>jboss-seam.jar</literal> — for
+ some reason when deploying the application through
+ the Websphere administration console it can not find
+ the <literal>jboss-seam.jar</literal> at the base
+ of the EAR archive. This means that we need to add it to
+ the <literal>/lib</literal> of the EAR.</para>
+ </listitem>
+ <listitem>
+ <para>Then finally by removing the
+ <literal>log4j.jar</literal> all of the log output
+ from our application will be added to the Websphere
+ logging. Addition steps are required to fully
+ configure log4j and those are outside of the scope of
+ this document.</para>
+ </listitem>
+ </itemizedlist> </para>
+
+ </section>
+
+ <section>
+ <title>Updating the <literal>build.xml</literal> file</title>
+
+ <para>Add the following entry to the bottom of the
+ <literal>build.xml</literal> file. This overrides the
+ default fileset that is used to populate the
+ <literal>jboss-seam-jee5.jar</literal>. The primary change
+ is the addition of the
+ <literal>GlassfishDerbyDialect.class</literal>.
+
+
+ <programlisting><![CDATA[
+ <fileset id="jar.resources" dir="${resources.dir}">
+ <include name="import.sql" />
+ <include name="seam.properties" />
+ <include name="GlassfishDerbyDialect.class" />
+ <include name="META-INF/persistence.xml" />
+ <include name="META-INF/ejb-jar.xml" />
+ </fileset>]]></programlisting>
+ </para>
+
+ <para>Next we need to add the library dependencies discussed above.
+ For this add the following to bottom of the
+ <literal>ear.lib.extras</literal> fileset entry.
+
+
+ <programlisting><![CDATA[
+ <!--<include name="lib/log4j.jar" />-->
+ <include name="lib/el-api.jar" />
+ <include name="examples/jpa/lib/el-ri.jar" />
+ <include name="lib/jsf-api.jar" />
+ <include name="lib/jsf-impl.jar" />
+ <include name="lib/jboss-seam.jar" />
+</fileset>]]></programlisting>
+ </para>
+
+ <para>Now all that is left is to execute the <literal>ant
+ archive</literal> task and your application files should be in
+ the <literal>jee5/booking/dist</literal> directory.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="jee5-websphere-deploy">
+ <title>Deploying the application to Websphere</title>
+
+ <para>So now we have everything we need in place. All that is left is to
+ deploy it - just a few steps more ;) </para>
+ <para> For that we will use Websphere's administration console. As
+ before there are some tricks and tips that must be followed.</para>
+
+ <para>The steps below are for the Websphere version stated above, yours
+ may be slightly different.
+ <orderedlist>
+ <listitem>
+ <para>Log in to the administration console
+
+
+ <programlisting><![CDATA[
+https://localhost:9043/ibm/console]]></programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Access the <literal>Enterprise
+ Application</literal> menu option under the
+ <literal>Applications</literal> top menu. </para>
+ </listitem>
+ <listitem>
+ <para>At the top of the <literal>Enterprise
+ Application</literal> table select
+ <literal>Install</literal>. Below are installation
+ wizard pages and what needs to done on each.
+ <itemizedlist>
+ <listitem>
+ <para><literal>Preparing for the application
+ installation</literal>
+ <itemizedlist>
+ <listitem>
+ <para>Browse to the
+ <literal>examples/jee5/booking/dist/jboss-seam-jee5.ear</literal>
+ file using the file upload widget.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Select the
+ <literal>Next</literal>
+ button.</para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para><literal>Select installation
+ options</literal>
+ <itemizedlist>
+ <listitem>
+ <para>Select the <literal>Deploy
+ enterprise beans</literal>
+ check box. This is needed unless you
+ used a Websphere tool to package the
+ application. </para>
+ </listitem>
+ <listitem>
+ <para>Select the
+ <literal>Next</literal>
+ button.</para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para><literal>Map modules to
+ servers</literal>
+ <itemizedlist>
+ <listitem>
+ <para>No changes needed here as we only
+ have one server. Select the
+ <literal>Next</literal>
+ button.</para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para><literal>Map EJB references to
+ beans</literal> This page will list all of the
+ beans that we entered in the web.xml.
+ <itemizedlist>
+ <listitem>
+ <para>Make sure that <literal>Allow
+ EJB reference targets to resolve
+ automatically</literal> check box
+ is selected. This will tell
+ Websphere to bind our EJB3 beans to
+ the EJB references in the web
+ module.</para>
+ </listitem>
+ <listitem>
+ <para>Select the
+ <literal>Next</literal>
+ button.</para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para><literal>Map virtual hosts for Web
+ modules</literal>
+ <itemizedlist>
+ <listitem>
+ <para>No changes needed here. Select
+ the <literal>Next</literal>
+ button.</para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para><literal>Summary</literal>
+ <itemizedlist>
+ <listitem>
+ <para>No changes needed here. Select
+ the <literal>Finish</literal>
+ button.</para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para><literal>Installation</literal>
+ <itemizedlist>
+ <listitem>
+ <para>Now you will see it installing and
+ deploying your
+ application.</para>
+ </listitem>
+ <listitem>
+ <para>When if finishes select the
+ <literal>Save</literal> link and
+ you will be returned to the
+ <literal>Enterprise
+ Applications</literal>
+ table.</para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem id="websphere-app-adj-after-install" xreflabel="installation adjustments for jee5 example">
+ <para>Now that we have our application installed we need to
+ make some adjustments to it before we can start it.
+ <itemizedlist>
+ <listitem>
+ <para>Starting from the <literal>Enterprise
+ Applications</literal> table select the
+ <literal>Seam Booking</literal>
+ link.</para>
+ </listitem>
+ <listitem>
+ <para>Select the <literal>Manage
+ Modules</literal> link.</para>
+ </listitem>
+ <listitem>
+ <para>Select the
+ <literal>jboss-seam-jee5.war</literal>
+ link.</para>
+ </listitem>
+ <listitem>
+ <para>Change the <literal>Class loader
+ order</literal> combo box to say
+ <literal>Classes loaded with application
+ class loader first</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Select <literal>Apply</literal> and then
+ <literal>Save</literal> options.</para>
+ </listitem>
+ <listitem>
+ <para>Return the <literal>Seam
+ Booking</literal> page.</para>
+ </listitem>
+ <listitem>
+ <para>On this page select the <literal>Class
+ loading and update detection</literal>
+ link.</para>
+ </listitem>
+ <listitem>
+ <para>Select the radio button for
+ <literal>Classes loaded with application
+ class loader first</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Even though we are not enabling class reload
+ you must also enter a valid number in the
+ <literal>Polling interval for updated
+ files</literal> text area (zero works
+ fine).</para>
+ </listitem>
+ <listitem>
+ <para>Select <literal>Apply</literal> and then
+ <literal>Save</literal> options.</para>
+ </listitem>
+ <listitem>
+ <para>You should verify that the change you just
+ made has stuck. We had problems with the last
+ class loader change not taking effect - even
+ after a restart. If the change did not take you
+ will need to do it manually following these
+ directions
+ <itemizedlist>
+ <listitem>
+ <para> Open the following file in a text
+ editor of your choice:
+
+
+ <programlisting><![CDATA[
+$WebSphereInstall/$yourServerName/profiles/$yourProfileName/config/cells/
+ $yourCellName/applications/Seam Booking.ear/deployments/
+ Seam Booking/deployment.xml]]></programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para> Modify the following line so that
+ <literal>PARENT_FIRST</literal>
+ is now
+ <literal>PARENT_LAST</literal>:
+
+
+ <programlisting><![CDATA[
+<classloader xmi:id="Classloader_#######" mode="PARENT_FIRST"/>]]></programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para> Save the file and now when go to the
+ <literal>Class loading and update
+ detection</literal> page you
+ should see <literal>Classes loaded
+ with application class loader
+ first</literal> selected. </para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para>To start the application return to the
+ <literal>Enterprise Applications</literal> table and
+ select our application in the list. Then choose the
+ <literal>Start</literal> button at the top of the
+ table.</para>
+ </listitem>
+ <listitem>
+ <para>You can now access the application at
+ <literal>http://localhost:9080/seam-jee5/</literal>
+ .</para>
+ </listitem>
+ </orderedlist>
+ <note>
+ <title>A note about Websphere Stateful bean timeouts</title>
+ <para>The default timeout period for a Websphere 6.1 Stateful
+ EJB is 10 minutes. This means that you may see some EJB timeout
+ exceptions after some idle time. It is possible to adjust the
+ timeout of the Stateful EJBs on an individual basis, but
+ that is beyond the scope of this document. See the Websphere
+ documentation for details.
+ </para>
+ </note>
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title> The <literal>jpa</literal> booking example </title>
+ <para>Thankfully getting the <literal>jpa</literal> example to work is
+ much easier than the <literal>jee5</literal> example. This is the
+ Hotel Booking example implemented in Seam POJOs and using Hibernate JPA
+ with JPA transactions. It does not require EJB3 support to
+ run.</para>
+
+ <para> The example already has a breakout of configurations and build
+ scripts for many of the common containers including Websphere.</para>
+
+ <para>First thing we are going to do is build and deploy that example. Then
+ we'll go over some key changes that we needed.</para>
+
+ <section>
+ <title>Building the <literal>jpa</literal> example</title>
+ <para> Building it only requires running the correct ant command:
+ <programlisting>ant websphere61</programlisting>
+ This will create container specific distribution and exploded
+ archive directories with the <literal>websphere61</literal> label.</para>
+ </section>
+ <section>
+ <title>Deploying the <literal>jpa</literal> example</title>
+ <para>This is similar to the <literal>jee5</literal> example at
+ <xref linkend="jee5-websphere-deploy"/>, but without so many steps.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>From the <literal>Enterprise Applications</literal> table
+ select the <literal>Install</literal> button.
+ <itemizedlist>
+ <listitem>
+ <para><literal>Preparing for the application
+ installation</literal>
+ <itemizedlist>
+ <listitem>
+ <para>Browse to the
+ <literal>examples/jpa/dist-websphere61/jboss-seam-jpa.war</literal>
+ file using the file upload widget.
+ </para>
+ </listitem>
+ <listitem>
+ <para>In the <literal>Context root</literal> text box
+ enter <literal>jboss-seam-jpa</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Select the <literal>Next</literal> button.
+ </para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para>Select the <literal>Next</literal> button for the next
+ three pages, no changes are needed.
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>Summary</literal> page
+ <itemizedlist>
+ <listitem>
+ <para>Review the settings if you wish and select
+ the <literal>Finish</literal> button to install
+ the application. When installation finished select the <literal>
+ Save</literal> link and you will be returned to the
+ <literal>Enterprise Applications</literal> table.
+ </para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>As with the <literal>jee5</literal> example there are some
+ class loader changes needed before we start the application.
+ Follow the instructions at <xref linkend="websphere-app-adj-after-install"/>
+ but exchange <literal>jboss-seam-jpa</literal> for <literal>Seam Booking</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Finally start the application by selecting it in the
+ <literal>Enterprise Applications</literal> table and clicking
+ the <literal>Start</literal> button.
+ </para>
+ </listitem>
+ <listitem>
+ <para>You can now access the application at the
+ <literal>http://localhost:9080/jboss-seam-jpa/index.html</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Whats different for Websphere 6.1</title>
+ <para>The differences between the JPA examples that deploys to JBoss
+ 4.2 and Websphere 6.1 are mostly expected; library and
+ configuration file changes. </para>
+ <itemizedlist>
+ <listitem>
+ <para>Configuration file changes
+ <itemizedlist>
+ <listitem>
+ <para><literal>WEB-INF/web.xml</literal>
+ — the only significant change is that
+ Websphere 6.1 only support <literal>Servlet
+ 2.4</literal> so the top of this file was changed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>META-INF/persistence.xml</literal>
+ — the main changes here are for the
+ datasource JNDI path, switching to the Websphere
+ 6.1 transaction manager look up class, and
+ changing the hibernate dialect to be
+ <literal>GlassfishDerbyDialect</literal>
+ .</para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>WEB-INF/classes/GlassfishDerbyDialect.class
+ </literal> — this class is needed for the
+ hibernate dialect change to
+ <literal>GlassfishDerbyDialect</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>import.sql</literal> —
+ either for the dialect or Derby DB the
+ <literal>ID</literal> column can not be
+ populated by this file and was removed.
+ </para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para>Changes for dependent libraries</para>
+ <para><literal>WEB-INF/lib</literal> — The Websphere
+ version requires several library packages because they are
+ not included as they are with JBoss AS. These are primarily for
+ hibernate, JSF-RI support and their dependencies. Below are
+ listed only the additional jars needed above and beyond the JBoss
+ <literal>JPA</literal> example.
+ <itemizedlist>
+ <listitem>
+ <para> To use Hibernate as your JPA provider you need
+ the following jars:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <literal>hibernate.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <literal>hibernate-annotations.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <literal>hibernate-commons-annotations.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <literal>hibernate-entitymanager.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <literal>hibernate-validator.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <literal>commons-collections.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <literal>jboss-archive-browsing.jar</literal>
+ </simpara>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para>Seam requires JSF 1.2 and these are the jars needed
+ for that. Websphere 6.1 ships with its own implementation
+ of JSF 1.1.
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <literal>jsf-api.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <literal>jsf-impl.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara> <literal>el-ri.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara> <literal>el-api.jar</literal>
+ </simpara>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ <listitem>
+ <para>Various third party jars that Websphere needs:
+ <itemizedlist>
+ <listitem>
+ <simpara> <literal>antlr.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara> <literal>cglib.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara> <literal>asm.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara> <literal>dom4j.jar</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <literal>javassist.jar</literal>
+ </simpara>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ </itemizedlist> </para>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+
+
+ </section>
+
+</chapter>
More information about the seam-commits
mailing list