1. 最初に、アプリケーションのパッケージと依存関係を確認します。詳細は、 「クラスローディングの変更によるアプリケーション依存関係の更新」を参照してください。
2. アプリケーションがロギングを行う場合、正しいモジュールの依存関係を指定する必要があります。詳細は、 「ロギング依存関係の編集」を参照してください。
3. モジュラークラスローディングの変更により、EAR または WAR のパッケージ構造を変更する必要がある場合があります。詳細は、 「EAR および WAR パッケージの編集」を参照してください。

手順3.1 モジュールの依存関係の理解

1. 暗黙的な依存関係を理解する

   サーバー内のデプロイヤーは、javax.api や sun.jdk などの一般的に使用されるモジュール依存関係を暗黙的かつ自動的に追加します。これにより、ランタイム時にデプロイメントに対してクラスを可視化でき、開発者が依存関係を明示的に追加する作業が軽減されます。暗黙的な依存関係がいつどのように追加されるかについては、https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/ にある JBoss EAP 6 向け『開発ガイド』の章「クラスローディングとモジュール」に記載されている「暗黙的なモジュール依存関係」の説明を参照してください。

2. 明示的な依存関係を理解する

   その他のクラスに対してはモジュールを明示的に指定する必要があります。明示的に指定しないと、不明な依存関係が原因でデプロイメントエラーやランタイムエラーが発生します。依存関係が不明な場合は、サーバーログに ClassNotFoundExceptions トレースまたは NoClassDefFoundErrors トレースが記録されます。複数のモジュールが同じ JAR をロードしたり、異なるモジュールによってロードされるクラスを拡張するクラスを 1 つのモジュールがロードしたりする場合は、サーバーログに ClassCastExceptions トレースが記録されます。依存関係を明示的に指定するには、MANIFEST.MF を変更するか、JBoss 固有のデプロイメント記述子ファイル jboss-deployment-structure.xml を作成します。モジュール依存関係の詳細は、https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/ にある JBoss EAP 6 向け『開発ガイド』の章「クラスローディングとモジュール」に記載されている「クラスローディングとモジュールの概要」を参照してください。

手順3.2 ResourceBundle プロパティーの場所変更

1. WAR アーカイブをデプロイする場合、これらのプロパティーを WAR の WEB-INF/classes/ フォルダーでパッケージ化する必要があります。
2. これらのプロパティーを EAR のすべてのコンポーネントに対してアクセス可能にするには、JAR のルートでパッケージ化し、EAR の lib/ フォルダーに置く必要があります。

手順3.3 カスタムモジュールの作成

1. module/ ディレクトリー構造を作成し、ファイルを追加します。
   1. EAP_HOME/module ディレクトリー下にディレクトリー構造を作成し、ファイルや JAR が含まれるようにします。例は次のとおりです。

      $ cd EAP_HOME/modules/ 
      $ mkdir -p myorg-conf/main/properties

   2. 作成した EAP_HOME/modules/myorg-conf/main/properties/ ディレクトリーにプロパティーファイルを移動します。
   3. 次の XML が含まれる module.xml ファイルを EAP_HOME/modules/myorg-conf/main/ ディレクトリーに作成します。

      <module xmlns="urn:jboss:module:1.1" name="myorg-conf">
          <resources>
              <resource-root path="properties"/>
          </resources>
      </module>

2. サーバー設定ファイルの ee サブシステムを編集します。JBoss CLI を使用するか、手作業でファイルを編集します。
   • 次の手順に従って JBoss CLI を使用し、サーバー設定ファイルを編集します。
     1. サーバーを起動し、管理 CLI へ接続します。
        • Linux の場合は、コマンドラインで以下を入力します。

           EAP_HOME/bin/jboss-cli.sh --connect

        • Windows の場合は、コマンドラインで以下を入力します。

          C:\>EAP_HOME\bin\jboss-cli.bat --connect

        次の応答が表示されるはずです。

        Connected to standalone controller at localhost:9999

     2. ee サブシステムに myorg-conf <global-modules> 要素を作成するには、コマンドラインで以下を入力します。

        /subsystem=ee:write-attribute(name=global-modules, value=[{"name"=>"myorg-conf","slot"=>"main"}])

        次の結果が表示されるはずです。

        {"outcome" => "success"}

   • サーバー設定ファイルを手作業で編集する場合は、次の手順に従ってください。
     1. サーバーを停止し、テキストエディターでサーバー設定ファイルを開きます。スタンドアロンサーバーを実行している場合は、EAP_HOME/standalone/configuration/standalone.xml ファイルになります。管理対象ドメインを実行している場合は、EAP_HOME/domain/configuration/domain.xml ファイルになります。
     2. ee サブシステムを見つけ、myorg-conf のグローバルモジュールを追加します。以下は、myorg-conf 要素が含まれるように編集された ee サブシステム要素の例になります。

        例3.1 myorg-conf element

        <subsystem xmlns="urn:jboss:domain:ee:1.0" >            
            <global-modules>
                <module name="myorg-conf" slot="main" />            
            </global-modules>
        </subsystem>

3. my.properties という名前のファイルを正しいモジュールの場所にコピーした場合は、以下のようなコードを使用してプロパティーファイルをロードできるようになります。

   例3.2 プロパティーファイルのロード

   Thread.currentThread().getContextClassLoader().getResource("my.properties");

手順3.4 アプリケーションロギングコードの更新

1. 「サードパーティーロギングフレームワークのアプリケーションコードの更新」
2. 「新しい JBoss ロギングフレームワークを使用したコードの変更」

手順3.5 log4j.properties または log4j.xml ファイルを使用するよう JBoss EAP 6 を設定する

1. 次の内容が含まれる jboss-deployment-structure.xml を作成します。

   <jboss-deployment-structure>
       <deployment>
           <!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
           <exclusions>
               <module name="org.apache.log4j" />
           </exclusions>
       </deployment>
   </jboss-deployment-structure>
   

2. jboss-deployment-structure.xml ファイルは、WAR をデプロイする場合は META-INF/ または WEB-INF/ ディレクトリーに置き、EAR をデプロイする場合は META-INF/ ディレクトリーに置きます。デプロイメントに依存する子デプロイメントが含まれる場合は、各サブデプロイメントのモジュールも除外する必要があります。
3. log4j.properties または log4j.xml ファイルが、EAR の lib/ ディレクトリーまたは WAR デプロイメントの WEB-INF/classes/ ディレクトリーに含まれるようにします。このファイルを WAR の lib/ ディレクトリーに置きたい場合は、jboss-deployment-structure.xml ファイルに <resource-root> パスを指定する必要があります。

   <jboss-deployment-structure>
       <deployment>
           <!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
           <exclusions>
               <module name="org.apache.log4j" />
           </exclusions>
           <resources>
               <resource-root path="lib" />
           </resources>
       </deployment>
   </jboss-deployment-structure>
   

4. 以下の引数を用いて JBoss EAP 6 サーバーを起動し、アプリケーションをデプロイするときに ClassCastException がコンソールに表示されないようにします。

   -Dorg.jboss.as.logging.per-deployment=false

5. アプリケーションをデプロイします。

手順3.6 JBoss EAP 6.3 またはそれ以降のバージョンでのロギング依存関係の設定

1. 以下の引数を用いて JBoss EAP 6 サーバーを起動し、アプリケーションをデプロイするときに ClassCastException がコンソールに表示されないようにします。

   -Dorg.jboss.as.logging.per-deployment=false

2. ターミナルを開き、管理 CLI へ接続します。
   • Linux の場合は、コマンドラインで以下を入力します。

     $ EAP_HOME/bin/jboss-cli.sh --connect
     

   • Windows の場合は、コマンドラインで以下を入力します。

     C:\>EAP_HOME\bin\jboss-cli.bat --connect
     

3. ロギングサブシステムの add-logging-api-dependencies 属性を編集します。
   この属性は、コンテナが暗黙的なロギング API の依存関係を追加するかどうかを制御します。

   • デフォルトの true に設定すると、暗黙的なロギング API の依存関係がすべて追加されます。
   • false に設定すると、依存関係はデプロイメントへ追加されません。
   サードパーティーロギングフレームワークの依存関係を除外するには、以下のコマンドを使用してこの属性を false に設定する必要があります。

   /subsystem=logging:write-attribute(name=add-logging-api-dependencies, value=false)

   このコマンドは、<add-logging-api-dependencies> 要素を standalone.xml 設定ファイルの logging サブシステムに追加します。

   <subsystem xmlns="urn:jboss:domain:logging:1.4">
       <add-logging-api-dependencies value="false"/>
       ....
   </subsystem>
   

4. アプリケーションをデプロイします。

手順3.7 JBoss ロギングフレームワークを使用するようコードおよび依存関係を変更する

1. インポートとロギングコードの変更

   新しい JBoss ロギングフレームワークを使用するコードの例は以下のとおりです。

   import org.jboss.logging.Level;
   import org.jboss.logging.Logger;
   
   private static final Logger logger = Logger.getLogger(MyClass.class.toString());
   
   if(logger.isTraceEnabled()) {
       logger.tracef("Starting...", subsystem);
   }
   

2. ロギング依存関係の追加

   JBoss ロギングクラスが含まれる JAR は org.jboss.logging という名前のモジュールにあります。MANIFEST-MF ファイルは次のようになるはずです。

   Manifest-Version: 1.0
   Dependencies: org.jboss.logging
   

   モジュール依存関係の検索方法に関する詳細については、「クラスローディングの変更によるアプリケーション依存関係の更新」と「移行の問題のデバッグと解決」を参照してください。

手順3.8 アーカイブパッケージの編集

1. WAR のパッケージ化

   WAR は単一のモジュールで、WAR のすべてのクラスは同じクラスローダーでロードされます。そのため WEB-INF/lib/ ディレクトリーにパッケージされるクラスは、WEB-INF/classes ディレクトリーのクラスと同様に処理されます。

2. EAR のパッケージ化

   EAR は複数のモジュールによって構成されます。EAR/lib/ ディレクトリーは単一のモジュールで、EAR 内の各 WAR や EJB jar サブデプロイメントは個別のモジュールになります。依存関係が明示的に定義された場合を除き、クラスは EAR 内の他のモジュールにあるクラスへアクセスできません。サブデプロイメントは常に親モジュール上で自動的な依存関係を持ち、親モジュールは EAR/lib/ ディレクトリーのクラスへのアクセスを許可します。しかし、サブデプロイメントはお互いのアクセスを許可するため常に自動的な依存関係を持っているわけではありません。この挙動は次のように ee サブシステム設定の <ear-subdeployments-isolated> 要素を設定すると制御できます。

   <subsystem xmlns="urn:jboss:domain:ee:1.0" >            
     <ear-subdeployments-isolated>false</ear-subdeployments-isolated>
   </subsystem>

   デフォルトでは false に設定され、EAR 内の他のサブデプロイメントに属するクラスがサブデプロイメントに対して可視化されます。
   クラスローディングの詳細については、https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/ にある JBoss EAP 6 向け『開発ガイド』の章「クラスローディングとモジュール」を参照してください。

1. アプリケーションがデータソースを使用する場合は、 「DataSource 設定の更新」を参照してください。
2. アプリケーションが JPA を使用し、現在 Hibernate JAR をバンドルする場合は、 「Hibernate または JPA 用のデータソースの設定」を参照し、移行のオプションについて確認してください。
3. アプリケーションがリソースアダプターを使用する場合は、 「リソースアダプター設定の更新」を参照してください。
4. 「アプリケーションセキュリティーの変更設定」 を参照し、基本的なセキュリティーの設定変更方法について確認してください。

手順3.9 JDBC ドライバーのインストールと設定

1. JDBC ドライバーをインストールします。

   1. JDBC ドライバーをデプロイメントとしてインストールします。

      これはドライバーのインストールに推奨される方法です。JDBC ドライバーがデプロイメントとしてインストールされると、普通の JAR としてデプロイされます。JBoss EAP 6 インスタンスがスタンドアロンサーバーとして実行されている場合は、 JDBC 4.0 対応の JAR を EAP_HOME/standalone/deployments/ ディレクトリーへコピーします。管理対象ドメインの場合は、管理コンソールまたは管理 CLI を使用して JAR をサーバーグループにデプロイする必要があります。
      スタンドアロンサーバーにデプロイメントとしてインストールされた MySQL JDBC ドライバーの例は次のとおりです。

      $cp mysql-connector-java-5.1.15.jar EAP_HOME/standalone/deployments/

      JDBC 4.0 対応のドライバーは自動的に認識され、名前とバージョンによってシステムへインストールされます。JDBC 4.0 対応の JAR にはドライバーのクラス名を指定する META-INF/services/java.sql.Driver という名前のテキストファイルが含まれてます。ドライバーが 4.0 対応でない場合は、次の方法の 1 つを用いてデプロイ可能にすることができます。

      • java.sql.Driver ファイルを作成し、META-INF/services/ パス下の JAR に追加します。このファイルには、次のようなドライバークラス名が含まれていなければなりません。

        com.mysql.jdbc.Driver

      • java.sql.Driver ファイルをデプロイメントディレクトリーに作成します。スタンドアロンサーバーとして実行されている JBoss EAP 6 のインスタンスの場合、このファイルを EAP_HOME/standalone/deployments/META-INF/services/java.sql.Driver に置く必要があります。サーバーが管理ドメインで実行されている場合は、管理コンソールまたは管理 CLI を使用してファイルをデプロイする必要があります。
      この方法の利点は次のとおりです。

      • モジュールを定義する必要がないため、これが最も簡単な方法です。
      • サーバーが管理対象ドメインで実行されている場合は、この方法を使用するデプロイメントがドメイン内のすべてのサーバーに自動的に伝播されます。つまり、管理者はドライバー JAR を手動で配布する必要がありません。

      この方法の欠点は次のとおりです。

      • JDBC ドライバーが複数の JAR (たとえば、ドライバー JAR および依存ライセンス JAR またはローカリゼーション JAR) から構成される場合、ドライバーをデプロイメントとしてインストールすることはできません。JDBC ドライバーは、コアモジュールとしてインストールする必要があります。
      • ドライバーが JDBC 4.0 対応でない場合は、ドライバークラス名を含むファイルを作成し、JAR にインポートするか、deployments/ ディレクトリーにオーバーレイする必要があります。

   2. JDBC ドライバーをコアモジュールとしてインストールします。

      JDBC ドライバーをコアモジュールとしてインストールするには、EAP_HOME/modules/ ディレクトリー下にファイルパス構造を作成する必要があります。この構造には、JDBC ドライバー JAR、任意の追加ベンダーライセンスまたはローカリゼーション JAR、およびモジュールを定義する module.xml ファイルが含まれます。

      • MySQL JDBC ドライバーをコアモジュールとしてインストールします。

        1. ディレクトリー構造 EAP_HOME/modules/com/mysql/main/ を作成します。
        2. main/ サブディレクトリーで、MySQL JDBC ドライバーに対する以下のモジュール定義を含む module.xml ファイルを作成します。

           <?xml version="1.0" encoding="UTF-8"?>
           <module xmlns="urn:jboss:module:1.0" name="com.mysql">
           <resources>
               <resource-root path="mysql-connector-java-5.1.15.jar"/>
           </resources>
           <dependencies>
               <module name="javax.api"/>
           </dependencies>
           </module>
           
           

           モジュール名 "com.mysql" はこのモジュールのディレクトリー構造と一致します。<dependencies> 要素は、このモジュールの他のモジュールへの依存関係を指定するために使用されます。この場合、全 JDBC データソースの場合と同様に、javax.api という名前の他のモジュールによって定義される Java JDBC API に依存します。このモジュールは modules/system/layers/base/javax/api/main/ ディレクトリーに存在します。

           注記

           module.xml ファイルの最初に空白文字が存在しないようにしてください。空白文字が存在すると、このドライバーに対して 「New missing/unsatisfied dependencies」エラーが発生します。
        3. MySQL JDBC ドライバー JAR を EAP_HOME/modules/com/mysql/main/ ディレクトリーへコピーします。

           $ cp mysql-connector-java-5.1.15.jar EAP_HOME/modules/com/mysql/main/

      • IBM DB2 JDBC ドライバーとライセンス JAR をコアモジュールとしてインストールします。

        この例は、 JDBC ドライバー JAR 以外に JAR が必要なドライバーをデプロイする方法を示すためにのみ提供されています。
        1. ディレクトリー構造 EAP_HOME/modules/com/ibm/db2/main/ を作成します。
        2. main/ サブディレクトリーで、IBM DB2 JDBC ドライバーとライセンスに対する以下のモジュール定義を含む module.xml ファイルを作成します。

           <?xml version="1.0" encoding="UTF-8"?>
           <module xmlns="urn:jboss:module:1.1" name="com.ibm.db2">
             <resources>
               <resource-root path="db2jcc.jar"/>
               <resource-root path="db2jcc_license_cisuz.jar"/>
             </resources>
             <dependencies>
               <module name="javax.api"/>
               <module name="javax.transaction.api"/>
             </dependencies>
           </module>
           

           注記

           module.xml ファイルの最初に空白文字が存在しないようにしてください。空白文字が存在すると、このドライバーに対して 「New missing/unsatisfied dependencies」エラーが発生します。
        3. JDBC ドライバーおよびライセンス JAR を EAP_HOME/modules/com/ibm/db2/main/ ディレクトリーにコピーします。

           $ cp db2jcc.jar EAP_HOME/modules/com/ibm/db2/main/
           $ cp db2jcc_license_cisuz.jar EAP_HOME/modules/com/ibm/db2/main/

      この方法の利点は次のとおりです。

      • これは、JDBC ドライバーが複数の JAR から構成される場合に有効な唯一の方法です。
      • この方法では、JDBC 4.0 対応でないドライバーは、ドライバー JAR を変更したり、ファイルオーバーレイを作成したりせずにインストールできます。

      この方法の欠点は次のとおりです。

      • モジュールのセットアップはより困難になります。
      • モジュールは、管理対象ドメインで実行されている各サーバーに手動でコピーする必要があります。

2. データソースを設定します。

   1. データソースドライバーを追加します。

      <driver> 要素を同じファイルの <drivers> 要素に追加します。以前 *-ds.xml ファイルに定義されたデータソース情報と同じ情報が一部含まれます。
      最初にドライバー JAR が JDBC 4.0 対応であるか判断します。JDBC 4.0 対応の JAR にはドライバークラス名を指定する META-INF/services/java.sql.Driver ファイルが含まれています。サーバーはこのファイルを使用して JAR のドライバークラス名を探します。JDBC 4.0 対応の ドライバーの JAR にはすでに <driver-class> 要素が指定されているため、この要素は必要ありません。JDBC 4.0 対応 MySQL ドライバーのドライバー要素の例は次のとおりです。

      <driver name="mysql-connector-java-5.1.15.jar" module="com.mysql"/>
      

      JDBC 4.0 対応でないドライバーには、ドライバークラスを指定する <driver-class> 属性が必要です。これは、ドライバークラス名を指定する META-INF/services/java.sql.Driver ファイルが存在しないためです。JDBC 4.0 対応でないドライバーのドライバー要素の例は、次のとおりです。

      <driver name="mysql-connector-java-5.1.15.jar" module="com.mysql">
      <driver-class>com.mysql.jdbc.Driver</driver-class></driver>
      

   2. データソースを作成します。

      standalone.xml ファイルの <datasources> セクションに <datasource> 要素を作成します。このファイルには、以前に *-ds.xml ファイルに定義されたデータソース情報とほとんど同じ情報が含まれています。

      重要

      サーバーの再起動後も変更が維持されるようにするには、サーバーを停止してからサーバー設定ファイルを編集する必要があります。
      standalone.xml ファイルの MySQL データソース要素の例は次のとおりです。

      <datasource jndi-name="java:/YourDatasourceName" pool-name="YourDatasourceName">
        <connection-url>jdbc:mysql://localhost:3306/YourApplicationURL</connection-url>
        <driver>mysql-connector-java-5.1.15.jar</driver>
        <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
        <pool>
          <min-pool-size>100</min-pool-size>
          <max-pool-size>200</max-pool-size>
        </pool>
        <security>
          <user-name>USERID</user-name>
          <password>PASSWORD</password>
        </security>
        <statement>
          <prepared-statement-cache-size>100</prepared-statement-cache-size>
          <share-prepared-statements/>
        </statement>
      </datasource>
      

3. アプリケーションコードで JNDI 参照を更新します。

   定義した新しい JNDI 標準データソース名を使用するには、アプリケーションソースコードの古い JNDI ルックアップ名を置き換える必要があります。詳細は、 「JNDI 名前空間の新ルールに準拠するようアプリケーションを変更」を参照してください。
   新しい JNDI 名を使用するには、データソースにアクセスする既存の @Resource アノテーションも置き換える必要があります。例は次のとおりです。

   @Resource(name = "java:/YourDatasourceName").
   

手順3.10 Hibernate バンドルの削除

1. アプリケーションライブラリーフォルダーより Hibernate JAR を削除します。
2. persistence.xml ファイルの <hibernate.transaction.manager_lookup_class> 要素は必要がないため、削除またはコメントアウトします。

手順3.11 他の承認チェックの無効化

• 他の承認チェックを無効にし、既存の PicketLink デプロイメントを継続して使用するには、以下の方法の 1 つを使用します。

  • システム全体のプロパティーの設定

    サーバーレベルで他の承認チェックを無効にするには、org.jboss.ws.cxf.disableHandlerAuthChecks システムプロパティーの値を true に設定します。この方法は、アプリケーションサーバーに対して作成されたすべてのデプロイメントに影響します。
    システムプロパティーの設定方法は、JBoss EAP 『管理および設定ガイド』の「管理 CLI を使用したシステムプロパティーの設定」を参照してください。

  • デプロイメントの Web サービス記述子ファイルでのプロパティーの作成

    デプロイメントレベルで他の承認チェックを無効にするには、jboss-webservices.xml ファイルで org.jboss.ws.cxf.disableHandlerAuthChecks プロパティーの値を true に設定します。この方法は、特定のデプロイメントのみに影響します。
    1. 他の承認チェックを無効にしたいデプロイメントの META-INF/ ディレクトリーで jboss-webservices.xml ファイルを作成します。
    2. 以下の内容を追加します。

       <?xml version="1.1" encoding="UTF-8"?>
       <webservices xmlns="http://www.jboss.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         version="1.2" xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee">
         <property>
           <name>org.jboss.ws.cxf.disableHandlerAuthChecks</name>
           <value>true</value>
         </property>
       </webservices>

手順3.12 JNDI ルックアップの変更

1. 「移植可能な EJB JNDI 名」を確認する
2. 「JNDI 名前空間のルールの確認」
3. 「JNDI 名前空間の新ルールに準拠するようアプリケーションを変更」