SeamFramework.orgCommunity Documentation

Chapter 40. Seam on IBM's Websphere AS

40.1. Websphere AS environment and deployment information
40.1.1. Installation versions
40.2. The jee5/booking example
40.2.1. Configuration file changes
40.2.2. Building the jee5/booking example
40.2.3. Deploying the application to Websphere
40.3. The jpa booking example
40.3.1. Building the jpa example
40.3.2. Deploying the jpa example
40.3.3. What's different for Websphere AS V7
40.4. Deploying an application created using seam-gen on Websphere V7
40.4.1. Running seam-gen Setup
40.4.2. Changes needed for deployment to Websphere

Websphere AS V7 is IBM's application server offering. This release is fully Java EE 5 certified.

First we will go over some basic information about the Websphere AS environment that we used for these examples. We will go over the details of those steps with the JEE5 booking example. We will also deploy the JPA example application.

40.1. Websphere AS environment and deployment information

Websphere AS 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.

All of the examples and information in this chapter are based on the version V7 of Websphere AS at the time of this writing.

After installing Websphere AS, create server profile with Profile Management Tool, if you didn't create profile in installation process.

40.2.  The jee5/booking example

The jee5/booking 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 $SEAM_DIST/examples/jee5/booking directory.

Below are the configuration file changes that are need to the base example.

resources/WEB-INF/components.xml

We need to change the way that we look up EJBs for WAS. We need to remove the /local from the end of the jndi-pattern attribute. It should look like this: 




<core:init jndi-pattern="java:comp/env/jboss-seam-jee5/#{ejbName}" debug="true"/>

                  
resources/META-INF/ejb-jar.xml

We need to replace the /local string from ejb-ref-name. See at the following final code:




   <enterprise-beans>

      <!-- EJB reference required when one Seam EJB component references another Seam EJB component using @In -->

      <!-- Not required if you inject using @EJB, but then you lose state management and client-side interceptors (e.g., security) -->

      <session>

         <ejb-name>RegisterAction</ejb-name>

         <ejb-local-ref>

            <ejb-ref-name>jboss-seam-jee5/AuthenticatorAction</ejb-ref-name>

            <ejb-ref-type>Session</ejb-ref-type>

            <local>org.jboss.seam.example.booking.Authenticator</local>

         </ejb-local-ref>

      </session>

   </enterprise-beans>
resources/WEB-INF/web.xml

We have to make some changes to the EJB references in the web.xml. These changes are what will allow WAS to bind automatically the EJB3 references in the web module to the the actual EJB3 beans in the EAR module. Replace all of the /local strings in ejb-local-refs when the values below.




  <!-- JEE5 EJB3 names -->

  <ejb-local-ref>

    <ejb-ref-name>jboss-seam-jee5/AuthenticatorAction</ejb-ref-name>

    <ejb-ref-type>Session</ejb-ref-type>

    <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>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>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>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>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>org.jboss.seam.example.booking.HotelSearching</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>org.jboss.seam.transaction.LocalEjbSynchronizations</local>

  </ejb-local-ref>

Note also that EjbSynchronizations is a built-in Seam EJB and not part of the Hotel Booking example. This means that if your application's components.xml specifies transaction:ejb-transaction, then you must include:




  <ejb-local-ref>

    <ejb-ref-name>myapp/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>

in your web.xml. If you don't include it, you'll get the following error:

Name comp/env/myapp/EjbSynchronizations not found in context java:
resources/META-INF/persistence.xml

For this example we will be using the default datasource that comes with WAS. To do this change the jta-data-source element:




<jta-data-source>DefaultDatasource</jta-data-source>

                  

Then we need to adjust some of the hibernate properties. First comment out the Glassfish properties. Next you need to add/change the properties:




<!--<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"/>

                  

src/GlassfishDerbyDialect.java

You will need to get the GlassfishDerbyDialect.java and copy it into the /src directory. The java class exists in the JPA example source directory and can be copied using the command below assuming you are in jee5/booking directory:

cp ../../jpa/src/GlassfishDerbyDialect.java
   ./src

This class will be put into the jboss-seam-jee5.jar file.

resources/import.sql

This file must also be copied from the JPA example because either the Derby DB or the dialect does not support changes to the ID column. The files are identical except for the column difference. Use the following command to make the copy 

cp ../../jpa/resources-websphere7/import.sql ./resources

In order to get the changes we have made into our application we need to make some changes to the build.xml. There are also some additional jars that are required by our application in order to work with WAS. This section will cover what changes are needed to the build.xml.

We remove the log4j.jar so that all of the log output from our application will be added to the WAS log. Additional steps are required to fully configure log4j and those are outside of the scope of this document.

Add the following entry to the bottom of the build.xml file. This overrides the default fileset that is used to populate the jboss-seam-jee5.jar. : 




   <fileset id="jar.resources" dir="${resources.dir}">

      <include name="import.sql" />

      <include name="seam.properties" />

      <include name="META-INF/persistence.xml" />

      <include name="META-INF/ejb-jar.xml" />

   </fileset>

Now all that is left is to execute the ant archive task and the built application will be in the jee5/booking/dist directory.

So now we have everything we need in place. All that is left is to deploy it - just a few steps more.

For this we will use Websphere's administration console. As before there are some tricks and tips that must be followed.

The steps below are for the WAS version stated above. The ports are default values, if you changed them substitute your values.

  1. Log in to the administration console 

    https://localhost:9043/admin

    or 

    http://localhost:9060/admin

  2. Access the Websphere enterprise applications menu option under the Applications --> Application Type left side menu.

  3. At the top of the Enterprise Applications table select Install. Below are installation wizard pages and what needs to done on each:

  4. Now that we have our application installed we need to make some adjustments to it before we can start it:

  5. To start the application return to the Enterprise Applications table and select our application in the list. Then choose the Start button at the top of the table.

  6. You can now access the application at http://localhost:9080/seam-jee5-booking/index.html .

40.3.  The jpa booking example

Thankfully getting the jpa example to work is much easier than the jee5 example. This is the Hotel Booking example implemented in Seam POJOs and using Hibernate JPA with JPA transactions. It does not use EJB3.

The example already has a breakout of configurations and build scripts for many of the common containers including Websphere.

First thing we are going to do is build and deploy that example. Then we'll go over some key changes that we needed.

Building it only requires running the correct ant command: 

ant websphere7

This will create container specific distribution and exploded archive directories with the websphere7 label.

This is similar to the jee5 example at Section 40.2.3, “Deploying the application to Websphere”, but without so many steps.

  • From the Enterprise Applications table select the Install button.

    • Preparing for the application installation

      • Browse to the examples/jpa/dist-websphere7/jboss-seam-jpa.war file using the file upload widget.

      • Select the Fast Path button.

      • Select the Next button.

    • Select the Next button for the next three pages, no changes are needed.

    • Map context roots for Web modules

      • In the Context root text box enter jboss-seam-jpa.

      • Select the Next button.

    • Summary page

      • Review the settings if you wish and select the Finish button to install the application. When installation finished select the Save link and you will be returned to the Enterprise Applications table.

  • As with the jee5 example there are some class loader changes needed before we start the application. Follow the instructions at installation adjustments for jee5 example but exchange jboss-seam-jpa_war for Seam Booking.

  • Finally start the application by selecting it in the Enterprise Applications table and clicking the Start button.

  • You can now access the application at the http://localhost:9080/jboss-seam-jpa/index.html.

The differences between the JPA examples that deploys to JBoss 4.2 and Websphere AS V7 are mostly expected; library and configuration file changes.

40.4. Deploying an application created using seam-gen on Websphere V7

seam-gen 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 seam-gen 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 Section 40.2, “ The jee5/booking example ” there are some tricky changes needed to get an EJB3 application running. This section will take you through the exact steps.

The first step is setting up seam-gen 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.

./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.3.GA] 
[C:/Program Files/jboss-4.2.3.GA]
/home/jbalunas/jboss/jboss-4.2.3.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 [org.jboss.seam.
tutorial.websphere.action] [org.jboss.seam.tutorial.websphere.action]
org.jboss.seam.tutorial.websphere.action 
    [input] Enter the Java package name for your entity beans [org.jboss.seam.
tutorial.websphere.model] [org.jboss.seam.tutorial.websphere.model]
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 [/tmp/seam/lib/hsqldb.jar] 
[/tmp/seam/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_2/jboss-seam-2_2/seam-gen/build.properties
     [echo] Installing JDBC driver jar to JBoss server
     [copy] Copying 1 file to /home/jbalunas/jboss/jboss-4.2.3.GA/server/default/lib
     [echo] Type 'seam create-project' to create the new project

BUILD SUCCESSFUL
Total time: 3 minutes 5 seconds

Type ./seam new-project to create your project and cd /home/jbalunas/workspace/websphere_example to the newly created structure.

We now need to make some changes to the generated project.

resources/META-INF/persistence-dev.xml
src/GlassfishDerbyDialect.java

As with other examples we need to include this java class for DB support. It can be copied from the jpa example into the websphere_example/src directory. 

cp $SEAM/examples/jpa/src/GlassfishDerbyDialect.java
   ./src

resources/META-INF/jboss-app.xml

You can delete this file as we aren't deploying to JBoss AS ( jboss-app.xml is used to enable classloading isolation in JBoss AS)

resources/*-ds.xml

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)

resources/WEB-INF/components.xml

  • Enable container managed transaction integration - add the <transaction:ejb-transaction /> component, and it's namespace declaration xmlns:transaction="http://jboss.com/products/seam/transaction"

  • Alter the jndi-pattern to java:comp/env/websphere_example/#{ejbName}

  • We do not need managed-persistence-context for this example and so can delete its entry.

    

    
<persistence:managed-persistence-context name="entityManager"
    
             auto-create="true"
    
             persistence-unit-jndi-name="java:/websphere_exampleEntityManagerFactory"/> 
resources/WEB-INF/web.xml

As with the jee5/booking example we need to add EJB references to the web.xml. These references require replacing /local string in ejb-ref-name to flag them for Websphere to perform the proper binding.


  

  <ejb-local-ref>

    <ejb-ref-name>websphere_example/AuthenticatorAction</ejb-ref-name>

    <ejb-ref-type>Session</ejb-ref-type>

    <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>org.jboss.seam.transaction.LocalEjbSynchronizations</local>

  </ejb-local-ref>

We want to take the existing Authenticator Seam POJO component and create an EJB3 out of it.

  1. Change the generated Authenticator class

    

    @Name("authenticator") @Stateless public class

                AuthenticatorAction implements Authenticator {
    

    @Local public interface Authenticator { 

      public boolean authenticate(); 

    }

  2. We've already added its reference to the web.xml file so are good to go.

This application has similar requirements as the jee5/booking example.