SeamFramework.orgCommunity Documentation

第38章 Seam on IBM's Websphere

38.1. Websphere environment and deployment information
38.1.1. Installation versions and tips
38.1.2. Required custom properties
38.2. jee5/booking サンプル
38.2.1. 構成ファイルの変更
38.2.2. jee5/booking サンプルのビルド
38.2.3. Websphere へのアプリケーションのデプロイ
38.3. jpa booking サンプル
38.3.1. jpa サンプルのビルド
38.3.2. jpa サンプルのデプロイ
38.3.3. Whats different for Websphere 6.1
38.4. Deploying an application created using seam-gen on Websphere 6.1.0.13
38.4.1. seam-gen セットアップの実行
38.4.2. Websphere へのデプロイに必要な変更点

Websphere 6.1.x is IBM's application server offering. The latest release is 6.1.0.19 which does not have EJB3 or JEE5 support. There is a recently released (Nov 07) EJB3 feature pack which provides some support for EJB3 and JPA. Currently there is no true JEE5 offering from IBM. This causes some issues with Seam integration with applications that use EJB3.

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 JPA example application.

38.1. Websphere environment and deployment information

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.

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

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 management tool.

It is highly recommended to patch Websphere by latest fix pack, at the time of this writing it is 6.1.0.19

A note about restarting the server

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 modifying a property or deploying an application try to restart the server.

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 : Setting web container custom properties

  • prependSlashToResource = "true" — 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 java.net.MalformedURLException will be thrown. With this property set you will still see warnings, but the resources will be retrieved as expected.

    Detailed can be found at:

    SRVE0238E: Resource paths must have a leading slash

  • com.ibm.ws.webcontainer.invokefilterscompatibility = "true" — This solves an issue with Websphere where it throws a FileNotFoundException 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.

    Detailed can be found at:

    PK33090; 6.1: A filter that serves a file does not pop-up an alert message

38.2. jee5/booking サンプル

jee5/booking サンプルは、(JBoss AS 上で動作する) ホテル予約サンプルに基づいています。そのままで GlassFish 上で動作するように設計されていますが、以下の手順で Websphere 上でも動作させることができます。このサンプルは $SEAM_DIST/examples/jee5/booking にあります。

As stated before the EJB3 feature pack does not provide a full jee5 implementation. This means that there are some tricks to getting an application deployed and functioning.

雛形のサンプルに対して必要となる構成ファイルの変更点は以下の通りです。

resources/WEB-INF/components.xml

We need to change the way that we look up EJBs for Websphere. 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/WEB-INF/web.xml

This is the first place that we notice an unexpected change because this is not full jee5 implementation.

Websphere does not support Servlet 2.5, it requires Servlet 2.4. For this change we need to adjust the top of the web.xml file to look like the following:


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

                  

Next, we have to make some changes to the EJB references in the web.xml. 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 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-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.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-home

></local-home>

    <local

>org.jboss.seam.transaction.LocalEjbSynchronizations</local>

  </ejb-local-ref

>

The important change is that there is an empty local-home element for each EJB. This tells Websphere to make the correct bindings between the web module and the EJB3 beans. The ejb-link element is simply not used.

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>

web.xml の中で上記の設定を行わなければ、以下のエラーが発生します。

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 Websphere. To do this change the jta-data-source element:




<jta-data-source

>DefaultDatasource</jta-data-source>

Hibernate プロパティを設定する必要があります。まず最初に GlassFish プロパティをコメントアウトします。次に以下のプロパティを追加修正する必要があります。




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

                  

resources/GlassfishDerbyDialect.class

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

cp ../../jpa/resources-websphere61/WEB-INF/classes/GlassfishDerbyDialect.class
   ./resources

This class will be put into the jboss-seam-jee5.jar file using changes to the build.xml discussed later.

resources/import.sql

Derby DB とダイアレクトのいずれも ID カラムの生成をサポートしないので、JPA サンプルからこのファイルをコピーしなければなりません。ファイルは、ID カラムの違い以外は同一です。 以下のコマンドを使用してコピーしてください 

cp ../../jpa/resources-websphere61/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 Websphere. This section will cover what changes are needed to the build.xml.

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. The primary change is the addition of the GlassfishDerbyDialect.class: 




   <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

>

Next we need to add the library dependencies discussed above. For this add the following to bottom of the ear.lib.extras fileset entry: 




   <!--<include name="lib/log4j.jar" />-->

   <include name="lib/el-api.jar" />

   <include name="lib/el-ri.jar" />

   <include name="lib/jsf-api.jar" />

   <include name="lib/jsf-impl.jar" />

   <include name="lib/jboss-seam.jar" />

</fileset

>

We also need to add richfaces-api.jar, jsf-impl.jar and el-ri.jar into WEB-INF/lib of the war file. Add the following fileset after ear.lib.extras fileset.




    <fileset id="war.lib.extras" dir="${seam.dir}"

> 

       <include name="lib/richfaces-api.jar" />

       <include name="lib/jsf-impl.jar" />

       <include name="lib/el-ri.jar" /> 

    </fileset

>

A note about copying JSF and EL jars

There is a class loading issue with WebSphere, which causes the jars from ear lib directory to not be available when the web module is initialized.

最後に残された作業は、 ant archive タスクを実行することです。アプリケーションは、jee5/booking/dist ディレクトリにビルドされます。

必要なものはすべて所定の位置に揃いました。残されたことはデプロイすることです - あとわずか数ステップの手順です。

デプロイには、WebSphere の管理コンソールを使用します。従来どおり従われなければならない手順とヒントがあります。

The steps below are for the Websphere version stated above, yours may be slightly different.

  1. Log in to the administration console 

    https://localhost:9043/ibm/console

  2. Access the Enterprise Application menu option under the Applications top menu.

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

  4. アプリケーションのインストールが完了しましたが、実行の前にいくつかの調整をする必要があります。

  5. アプリケーションを開始するために Enterprise Applications (エンタープライズアプリケーション) テーブルに戻って、リストの中からサンプルのアプリケーションを選択してください。テーブルの先頭で Start ボタンを選択してください。

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

A note about Websphere Stateful bean timeouts

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.

38.3. jpa booking サンプル

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 require EJB3 support to run.

サンプルには、Websphere も含めた多くのコンテナ用の構成とビルドスクリプトが既に用意されています。

最初に行うことは、サンプルのビルトとデプロイです。そのあとに必要な設定変更を行います。

Building it only requires running the correct ant command: 

ant websphere61

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

これは jee5 サンプルの 項38.2.3. 「Websphere へのアプリケーションのデプロイ」 と類似していますが、多くの手順は必要ありません。

  • Enterprise Applications (エンタープライズアプリケーション) テーブルから Install (インストール) ボタンを選択してください。

    • アプリケーションのインストール準備

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

      • Context root テキストボックスに jboss-seam-jpaを入力してください。

      • Next ボタンを選択してください。

    • Next ボタンを選択して、3 ページ先まで進んでください。そこまで変更は必要ありません。

    • Summary (要約) ページ

      • お望みなら設定を確認して、Finish (完了) ボタンを選択してアプリケーションのインストールを完了してください。インストールが完了して Save (保存) リンクを選択すると Enterprise Applications (エンタープライズアプリケーション)テーブルに戻ります。

  • 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 for Seam Booking.

  • 最後にアプリケーションを開始するには、Enterprise Applications (エンタープライズアプリケーション) テーブルでアプリケーションを選択して Start (開始) ボタンをクリックしてください。

  • http://localhost:9080/jboss-seam-jpa/index.html からアプリケーションにアクセスできます。

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

38.4. Deploying an application created using seam-gen on Websphere 6.1.0.13

seam-gen は、開発者が素早くアプリケーションを準備して動作させるのにとても役に立つツールで、独自の機能を追加するための雛形を用意します。seam-gen はそのままで JBoss AS で動作するように構成されたアプリケーションを生成します。以下の手順では、Websphere 上で動作させるために必要なステップを示します。項38.2. 「jee5/booking サンプル 」 で述べたように、EJB3 アプリケーションを動作させるには変更が必要です。このセクションでは、その正確な手順を示します。

第一ステップは、雛形となるプロジェクトを生成できるように seam-gen をセットアップすることです。以下に実行したように、設定すべき項目がいくつかあります。特に、データソースと Hibernate の設定値は、プロジェクトを生成する環境に合わせて設定します。

./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_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.3.GA/server/default/lib
     [echo] Type 'seam create-project' to create the new project

BUILD SUCCESSFUL
Total time: 3 minutes 5 seconds

プロジェクトを作成するためには、$ ./seam new-project と入力してください。そして cd /home/jbalunas/workspace/websphere_example と入力して新しく作成されたディレクトリへ移動してください。

生成されたプロジェクトに変更を行う必要があります。

resources/META-INF/persistence-dev.xml

  • jta-data-source を DefaultDatasource に修正してください。組み込みの Websphere DB を使用します。

  • 以下のプロパティを追加修正してください。項38.2. 「jee5/booking サンプル 」 に詳細が説明されています。 

    

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

  • EntityManagerFactory を定義する JBoss AS 固有のメソッドを取り除いてください。 

    
<property 
    
 name="jboss.entity.manager.factory.jndi.name" 
    
 value="java:/websphere_exampleEntityManagerFactory">

  • prod プロファイルを使用して Websphere にデプロイしたければ、persistence-prod.xml も同様に修正する必要があります。

resources/GlassfishDerbyDialect.class

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

cp $SEAM/examples/jpa/resources-websphere61/WEB-INF/classes/GlassfishDerbyDialect.class
   ./resources

resources/META-INF/jboss-app.xml

JBoss AS にはデプロイしないのでこのファイルを削除できます (JBoss AS では jboss-app.xml を使用して、クラスローディングの分離を有効にします)

resources/*-ds.xml

JBoss AS にはデプロイしないのでこのファイルを削除できます (これらのファイルは、JBoss AS ではデータソースを定義していますが、Websphere ではデフォルトのデータソースを使用しています)

resources/WEB-INF/components.xml

  • コンテナ管理トランザクション統合を有効にします - <transaction:ejb-transaction /> コンポーネントと、その名前空間宣言 xmlns:transaction="http://jboss.com/products/seam/transaction" を追記してください

  • jndi-pattern を java:comp/env/websphere_example/#{ejbName} に修正します

  • このサンプルでは、managed-persistence-context は必要ではないので、そのエントリは削除します。

    

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

Websphere does not support Servlet 2.5, it required Servlet 2.4. For this change we need to adjust the top of the web.xml file to look like the following:




<?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">

                  

As with the jee5/booking example we need to add EJB references to the web.xml. These references require the empty local-home 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-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

>

既存の Authenticator Seam POJO コンポーネントを利用して、EJB3 を作成します。 

  1. 

    @Name("authenticator")

    @Stateless

    public class AuthenticatorAction implements Authenticator {
    

    @Local

    public interface Authenticator { 

      public boolean authenticate(); 

    }

  2. すでに web.xml ファイルには EJB 参照を追加したので、次に進めます。

このアプリケーションは、jee5/booking サンプルと同様の変更が必要となります。