Cosminexus アプリケーションサーバ V8

機能解説 基本・開発編(コンテナ共通機能)

解説書

3020-3-U07-60

目　　次

前書き

変更内容

はじめに

1.　アプリケーションサーバの機能

1.1　機能の分類

1.1.1　アプリケーションの実行基盤としての機能

1.1.2　アプリケーションの実行基盤を運用・保守するための機能

1.1.3　機能とマニュアルの対応

1.2　システムの目的と機能の対応

1.2.1　ネーミング管理の機能

1.2.2　リソース接続とトランザクション管理の機能

1.2.3　OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）の機能

1.2.4　アプリケーションサーバで使用するJPAの機能

1.2.5　Cosminexus JPAプロバイダの機能

1.2.6　Cosminexus JMSプロバイダの機能

1.2.7　JavaMailの機能

1.2.8　セキュリティ管理の機能

1.2.9　アプリケーションの属性管理

1.2.10　アノテーションの機能

1.2.11　J2EEアプリケーションの形式とデプロイの機能

1.2.12　コンテナ拡張ライブラリの機能

1.3　このマニュアルに記載している機能の説明

1.3.1　分類の意味

1.3.2　分類を示す表の例

1.4　アプリケーションサーバ 08-70での主な機能変更

2.　ネーミング管理

2.1　この章の構成

2.2　ネーミング管理の概要

2.2.1　ネーミング管理の機能

2.2.2　ネーミングサービス

2.3　JNDI名前空間へのオブジェクトのバインドとルックアップ

2.3.1　ルックアップで使用する名称の種類

2.3.2　EJBのリファレンスが自動的にバインドされる名称

2.3.3　JNDI名前空間のマッピングとルックアップ

2.3.4　JNDI名前空間の確認方法

2.3.5　cosminexus.xmlでの定義

2.3.6　実行環境での設定

2.4　Enterprise BeanまたはJ2EEリソースへの別名付与（ユーザ指定名前空間機能）

2.4.1　別名を付けられる対象

2.4.2　別名の付与規則

2.4.3　別名が登録または削除されるタイミング

2.4.4　クライアントからの検索

2.4.5　Enterprise Beanの別名の設定

2.4.6　J2EEリソースの別名の設定

2.4.7　実行環境での設定

2.4.8　ユーザ指定名前空間機能を使用する場合の注意事項

2.5　ラウンドロビンポリシーによるCORBAネーミングサービスの検索

2.5.1　ラウンドロビン検索の範囲

2.5.2　ラウンドロビン検索の動作

2.5.3　ラウンドロビン検索をするために必要な設定

2.5.4　ラウンドロビン検索機能を使用する場合の推奨する設定

2.5.5　ラウンドロビン検索をする場合の注意事項

2.6　ネーミング管理機能でのキャッシング

2.6.1　キャッシングの流れ

2.6.2　ネーミングで使用したキャッシュのクリア

2.6.3　キャッシング機能を使用するための設定

2.6.4　ネーミングでのキャッシングの注意事項

2.7　ネーミングサービスの障害検知

2.7.1　ネーミングサービスの障害検知機能とは

2.7.2　ラウンドロビン検索機能との併用

2.7.3　ネーミングサービスの障害検知機能の挙動

2.7.4　実行環境の設定（障害検知機能を使用する場合）

2.7.5　ネーミングサービスの障害検知機能の注意事項

2.8　CORBAネーミングサービスの切り替え

2.9　EJBホームオブジェクトリファレンスの再利用（EJBホームオブジェクトへの再接続機能）

2.9.1　実行環境での設定（J2EEサーバの設定）

2.9.2　EJBホームオブジェクトリファレンスを再利用する場合の注意事項

3.　リソース接続とトランザクション管理

3.1　この章の構成

3.2　リソース接続とトランザクション管理の概要

3.3　リソース接続

3.3.1　リソースへの接続方法

3.3.2　リソースアダプタの種類

3.3.3　リソースアダプタの使用方法

3.3.4　リソースアダプタの機能

3.3.5　リソースアダプタ以外の機能

3.3.6　リソースに接続するための実装

3.3.7　リソースアダプタの設定方法

3.3.8　リソースアダプタの設定の流れ（J2EEリソースアダプタとしてデプロイして使用する場合）

3.3.9　リソースアダプタの設定の流れ（J2EEアプリケーションに含めて使用する場合）

3.3.10　リソースアダプタの設定の流れ（Inboundで使用する場合）

3.3.11　リソースアダプタの設定の流れ（コネクションプールのクラスタ化をする場合）

3.3.12　リソースアダプタ以外を使用する接続の設定

3.3.13　リソースアダプタについての注意事項

3.4　トランザクション管理

3.4.1　リソース接続でのトランザクション管理の方法

3.4.2　ローカルトランザクションとグローバルトランザクション

3.4.3　リソースごとに使用できるトランザクションの種類

3.4.4　トランザクションサービスで提供する機能

3.4.5　システム例外発生時のトランザクションの動作

3.4.6　トランザクションマネージャの取得

3.4.7　コンテナ管理のトランザクション（CMT）を使用する場合の処理概要と留意点

3.4.8　UserTransactionインタフェースを使用する場合の処理概要と留意点

3.4.9　リソースアダプタ固有のトランザクション管理インタフェースを使用する場合の処理概要と留意点

3.4.10　トランザクションを使用しない場合の処理概要と留意点

3.4.11　JTAによるトランザクション実装時の注意事項

3.4.12　実行環境での設定

3.5　リソースへのサインオン方式

3.6　データベースへの接続

3.6.1　DB Connectorによる接続の概要

3.6.2　使用できるJ2EEコンポーネントおよび機能

3.6.3　接続できるデータベース

3.6.4　DB Connector（RARファイル）の種類

3.6.5　HiRDBと接続する場合の前提条件と注意事項

3.6.6　Oracleと接続する場合の前提条件と注意事項

3.6.7　SQL Serverと接続する場合の前提条件と注意事項

3.6.8　XDM/RD E2と接続する場合の前提条件と注意事項

3.6.9　実行環境での設定（リソースアダプタでの設定）

3.7　データベース上のキューとの接続

3.7.1　DB Connector for Cosminexus RMとCosminexus RMによる接続の概要

3.7.2　DB Connector for Cosminexus RMとCosminexus RMによる接続の特徴

3.7.3　使用できる機能

3.7.4　接続できるデータベース

3.7.5　DB Connector for Cosminexus RM（RARファイル）の種類

3.7.6　HiRDBのキューに接続する場合の前提条件

3.7.7　Oracleのキューに接続する場合の前提条件

3.7.8　データベース上のキューに接続するための設定

3.8　OpenTP1とのOutboundでの接続（SPPまたはTP1/Message Queue）

3.8.1　uCosminexus TP1 Connectorによる接続

3.8.2　TP1/Message Queue - Accessによる接続

3.8.3　OpenTP1とOutboundで接続するための設定

3.9　OpenTP1とのInboundでの接続

3.10　Cosminexus JMSプロバイダとの接続

3.11　SMTPサーバとの接続

3.12　JavaBeansリソースの利用

3.12.1　JavaBeansリソースの機能

3.12.2　JavaBeansリソースの開始処理の流れ

3.12.3　JavaBeansリソースの実装

3.12.4　JavaBeansリソースの設定

3.12.5　JavaBeansリソースの入れ替え

3.13　そのほかのリソースとの接続

3.13.1　そのほかのリソースとの接続に使用するリソースアダプタ

3.13.2　そのほかのリソースとの接続で使用できる機能

3.14　パフォーマンスチューニングのための機能

3.14.1　コネクションプーリング

3.14.2　コネクションプーリングで使用できる機能

3.14.3　コネクションシェアリング・アソシエーション

3.14.4　ステートメントプーリング

3.14.5　ライトトランザクション

3.14.6　インプロセストランザクションサービス

3.14.7　DataSourceオブジェクトのキャッシング

3.14.8　DB Connectorのコンテナ管理でのサインオンの最適化

3.14.9　cosminexus.xmlでの定義

3.14.10　実行環境での設定

3.15　フォールトトレランスのための機能

3.15.1　コネクションの障害検知

3.15.2　コネクション枯渇時のコネクション取得待ち

3.15.3　コネクションの取得リトライ

3.15.4　コネクションプールの情報表示

3.15.5　コネクションプールのクリア

3.15.6　コネクションの自動クローズ

3.15.7　コネクションスイーパ

3.15.8　トランザクションタイムアウトとステートメントキャンセル

3.15.9　トランザクションリカバリ

3.15.10　障害調査用SQLの出力

3.15.11　オブジェクトの自動クローズ

3.15.12　cosminexus.xmlでの定義

3.15.13　実行環境での設定

3.16　そのほかのリソースアダプタの機能（Connector 1.5仕様に準拠するリソースアダプタの場合）

3.16.1　リソースアダプタのライフサイクル管理

3.16.2　リソースアダプタのワーク管理

3.16.3　メッセージインフロー

3.16.4　トランザクションインフロー

3.16.5　管理対象オブジェクトのルックアップ

3.16.6　コネクション定義の複数指定

3.16.7　アプリケーションサーバ独自のConnector 1.5 API仕様

3.16.8　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定

3.16.9　属性ファイルの指定例

3.16.10　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の注意事項

3.17　コネクションプールのクラスタ化機能

3.17.1　クラスタコネクションプールの概要

3.17.2　使用するリソースアダプタ

3.17.3　クラスタコネクションプールの動作

3.17.4　手動によるコネクションプールの停止・開始の流れ

3.17.5　Oracle RACを使用したOracleへの接続

3.17.6　コネクションプールをクラスタ化するために必要な設定

3.18　リソースへの接続テスト

3.19　ファイアウォール環境での運用のための機能

3.19.1　トランザクションリカバリ用通信ポート

3.19.2　スマートエージェントが使用する通信ポート

3.19.3　ファイアウォール環境での運用のための設定

3.20　EJBクライアントアプリケーションでトランザクションを開始する場合の注意事項

3.20.1　アプリケーション開発時の注意事項

3.20.2　システム構築時の注意事項

3.20.3　システム運用時の注意事項

4.　OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）

4.1　この章の構成

4.2　TP1インバウンド連携機能の概要

4.3　TP1インバウンド連携機能の前提条件

4.4　OpenTP1の機能との対応

4.4.1　クライアントでサポートするOpenTP1の機能

4.4.2　OpenTP1のサーバの機能との対応

4.5　コネクション管理機能

4.5.1　コネクション管理機能の概要

4.5.2　コネクション接続要求の受信

4.5.3　電文の受信

4.5.4　コネクション接続要求の送信

4.5.5　電文の送信

4.5.6　一時クローズ処理によるコネクション数の調整

4.5.7　コネクション接続要求または電文送信失敗時のリトライ

4.6　RPC通信機能

4.6.1　RPC通信機能の概要

4.6.2　RPC要求の受信と組み立て

4.6.3　RPC要求のチェック

4.6.4　RPC応答の生成から送信まで

4.6.5　最大同時RPC要求受け付け数および受信タイムアウト

4.7　スケジュール機能

4.7.1　スケジュール機能の概要

4.7.2　スケジュールキューの制御

4.7.3　Message-driven Bean（サービス）の同時実行数の制御

4.7.4　サービス実行のタイムアウト

4.8　トランザクション連携機能

4.8.1　トランザクション連携機能の概要

4.8.2　グローバルトランザクションの範囲

4.8.3　グローバルトランザクションへのMessage-driven Bean（サービス）の参加条件

4.8.4　トランザクショナルRPCの受信と応答

4.8.5　同期点処理

4.8.6　同期点処理の最適化

4.8.7　トランザクション連携機能の設定

4.8.8　トランザクション障害発生時の対処

4.9　Message-driven Bean（サービス）の実装

4.9.1　Message-driven Bean（サービス）の実装の準備

4.9.2　クラスパスの設定

4.9.3　リスナインタフェースの実装

4.9.4　onMessageメソッドでの業務ロジックの実装

4.9.5　ejb-jar.xmlの定義

4.9.6　cosminexus.xmlの定義

4.9.7　Message-driven Bean（サービス）の開始

4.10　OpenTP1のアプリケーションプログラムの作成

4.11　アプリケーションサーバの実行環境での設定

4.11.1　J2EEサーバの設定

4.11.2　リソースアダプタの設定

4.12　OpenTP1での設定

4.12.1　ユーザサービスネットワーク定義によるスケジューラダイレクトの設定

4.12.2　性能解析トレースの設定

4.12.3　トランザクションの設定

4.13　OpenTP1とアプリケーションサーバ間のタイムアウトの設定

4.13.1　RPC要求受信およびRPC応答送信時のタイムアウト

4.13.2　トランザクションに関するタイムアウト

4.14　TP1インバウンドアダプタとMessage-driven Bean（サービス）の開始と終了

4.14.1　TP1インバウンドアダプタの開始と終了

4.14.2　Message-driven Bean（サービス）の開始と終了

4.15　性能解析トレース情報の引き継ぎ

4.15.1　性能解析情報を引き継ぐための準備

4.15.2　性能解析情報の対応

4.15.3　トランザクション連携機能を使用しない場合の性能解析トレース情報の引き継ぎ

4.15.4　トランザクション連携機能を使用する場合の性能解析トレース情報の引き継ぎ

4.16　TP1インバウンドアダプタで発生するRPCエラー応答

5.　アプリケーションサーバでのJPAの利用

5.1　この章の構成

5.2　JPAの特長

5.2.1　JPAを使用したアプリケーションの利点

5.2.2　エンティティクラスとは

5.2.3　JPAプロバイダとは

5.3　アプリケーションサーバで使用できるJPAの機能

5.3.1　使用できるJPAプロバイダ

5.3.2　使用できるコンポーネント

5.3.3　サポートするアプリケーションの形式

5.3.4　サポートするクラスローダ構成

5.3.5　使用できるリソースアダプタ

5.4　EntityManagerとは

5.4.1　EntityManagerで提供するメソッド

5.4.2　EntityManagerの種類

5.4.3　トランザクションの制御とEntityManager

5.4.4　永続化ユニットとは

5.5　永続化コンテキストとは

5.5.1　EntityManagerと永続化コンテキスト

5.5.2　コンテナ管理のEntityManagerを使用する場合の永続化コンテキスト

5.5.3　アプリケーション管理のEntityManagerを使用する場合の永続化コンテキスト

5.6　コンテナ管理のEntityManagerを取得する方法

5.6.1　アプリケーションにEntityManagerをインジェクトする方法

5.6.2　アプリケーションからEntityManagerをルックアップする方法

5.6.3　DDによる@PersistenceContext定義のオーバーライド

5.7　アプリケーション管理のEntityManagerを取得する方法

5.7.1　アプリケーションにEntityManagerFactoryをインジェクトする方法

5.7.2　アプリケーションからEntityManagerFactoryをルックアップする方法

5.7.3　DDによる@PersistenceUnit定義のオーバーライド

5.8　persistence.xmlでの定義

5.8.1　<persistence-unit>タグに指定する属性

5.8.2　<persistence-unit>タグ下に指定するタグ

5.9　persistence.xmlの配置

5.10　JPAのインタフェース

5.10.1　javax.persistence.EntityManagerインタフェース

5.10.2　javax.persistence.EntityManagerFactoryインタフェース

5.11　アプリケーション設定時の注意事項

5.11.1　エンティティクラス配置時の注意

5.11.2　永続化ユニット名の参照スコープ

5.11.3　アプリケーションのデプロイ時にチェックされる項目

5.11.4　アプリケーションサーバでJPAを使用するときの注意事項

5.11.5　CosminexusのJPA機能を使用しないときの注意事項

6.　Cosminexus JPAプロバイダ

6.1　この章の構成

6.2　Cosminexus JPAプロバイダとは

6.2.1　Cosminexus JPAプロバイダでの処理

6.2.2　Cosminexus JPAプロバイダが提供する機能

6.2.3　Cosminexus JPAプロバイダを使用するための前提条件

6.2.4　DB Connectorのコネクション数の見積もり

6.3　エンティティを使用したデータベースの更新

6.4　EntityManagerによるエンティティの操作

6.4.1　エンティティの状態遷移

6.4.2　エンティティに対するpersist操作

6.4.3　エンティティに対するremove操作

6.4.4　データベースからのエンティティの取得

6.4.5　データベースとの同期

6.4.6　永続化コンテキストからのエンティティの切り離しとmerge操作

6.4.7　managed状態のエンティティ

6.5　データベースとJavaオブジェクトとのマッピング情報の定義

6.6　エンティティのリレーションシップ

6.6.1　リレーションシップの種類

6.6.2　リレーションシップのアノテーション

6.6.3　リレーションシップの方向

6.6.4　デフォルトマッピング（双方向のリレーションシップ）

6.6.5　デフォルトマッピング（単方向のリレーションシップ）

6.7　エンティティオブジェクトのキャッシュ機能

6.7.1　キャッシュ機能の処理

6.7.2　キャッシュの参照形態とキャッシュタイプ

6.7.3　キャッシュ機能の有効範囲

6.7.4　キャッシュ機能を使用するときの注意事項

6.8　プライマリキー値の自動採番

6.9　クエリ言語によるデータベース操作

6.10　楽観的ロック

6.10.1　楽観的ロックの処理

6.10.2　楽観的ロックに失敗した場合の例外処理

6.10.3　楽観的ロックを使用する際の注意事項

6.11　JPQLでの悲観的ロック

6.12　エンティティクラスの作成

6.12.1　エンティティクラスとデータベースの対応の定義

6.12.2　エンティティクラスの作成要件

6.12.3　エンティティクラスのフィールドに対するアクセス方法の指定

6.12.4　アクセサメソッドの作成

6.12.5　エンティティの永続化フィールドおよび永続プロパティの型

6.12.6　エンティティでのプライマリキーの指定

6.12.7　永続化フィールドおよび永続化プロパティのデフォルトマッピング規則

6.13　エンティティクラスの継承方法

6.13.1　継承クラスの種類

6.13.2　継承マッピング戦略

6.14　EntityManagerおよびEntityManagerFactoryの使用方法

6.14.1　EntityManagerでのエンティティのライフサイクル管理

6.14.2　EntityManagerおよびEntityManagerFactoryの設定方法

6.14.3　EntityManagerのAPIに関する注意事項

6.15　コールバックメソッドの指定方法

6.15.1　コールバックメソッドの指定個所

6.15.2　コールバックメソッドの実装

6.15.3　コールバックメソッドの呼び出し順序

6.16　クエリ言語を利用したデータベースの参照および更新方法

6.16.1　JPQLでのデータベースの参照および更新方法

6.16.2　ネイティブクエリでのデータベースの参照および更新方法

6.16.3　クエリ結果件数の範囲指定

6.16.4　フラッシュモードの指定

6.16.5　クエリヒントの指定

6.16.6　クエリの実行時の注意事項

6.17　JPQLの記述方法

6.17.1　JPQLの構文

6.17.2　SELECT文

6.17.3　SELECT節

6.17.4　FROM節

6.17.5　WHERE節

6.17.6　GROUP BY節およびHAVING節

6.17.7　ORDER BY節

6.17.8　バルクUPDATE文およびバルクDELETE文

6.17.9　JPQL使用時の注意事項

6.17.10　クエリ使用時に発生する例外

6.18　persistence.xmlの定義

6.19　実行環境での設定

7.　Cosminexus JMSプロバイダ

7.1　この章の構成

7.2　Cosminexus JMSプロバイダの概要

7.2.1　Cosminexus JMSプロバイダとは

7.2.2　Cosminexus JMSプロバイダのアプリケーションサーバ内での位置づけ

7.2.3　Cosminexus JMSプロバイダの機能の概要

7.3　CJMSPリソースアダプタとCJMSPブローカーの配置

7.3.1　一つのCJMSPリソースアダプタに対して一つのCJMSPブローカーを配置する構成

7.3.2　複数のCJMSPリソースアダプタに対して一つのCJMSPブローカーを配置する構成

7.4　メッセージングモデルの種類

7.4.1　PTPメッセージングモデル

7.4.2　Pub/Subメッセージングモデル

7.5　メッセージの構成

7.6　メッセージセレクターによる受信メッセージの選択

7.7　メッセージ配信の高信頼性確保の仕組み

7.7.1　メッセージ配信時に発生するトラブルの種類と信頼性を確保する方法

7.7.2　トランザクションの利用

7.7.3　メッセージの流量制御

7.8　CJMSPブローカーの機能

7.8.1　コネクションサービス

7.8.2　送信先の管理とルーティングサービス

7.8.3　CJMSPブローカーの性能監視

7.8.4　管理情報およびメッセージの永続化サービス

7.9　CJMSPリソースアダプタの機能

7.10　Message-driven Beanの呼び出し

7.10.1　Message-driven Beanによるメッセージ処理の特徴

7.10.2　Message-driven Beanを呼び出す流れ

7.10.3　Message-driven Beanで必要な設定

7.10.4　トランザクションコンテキストの設定

7.11　アプリケーション実装時の制限事項

7.12　DDでの定義

7.13　実行環境の構築の流れ

7.14　CJMSPブローカーの設定

7.14.1　CJMSPブローカーの共通プロパティと管理コマンドのプロパティの設定

7.14.2　CJMSPブローカーの作成

7.14.3　CJMSPブローカーの個別プロパティの設定

7.14.4　CJMSPブローカーの起動

7.14.5　送信先の作成

7.15　CJMSPリソースアダプタの設定

7.16　J2EEアプリケーションの設定

7.17　Cosminexus JMSプロバイダを使用する場合のシステムの開始と停止

7.17.1　システムの開始手順

7.17.2　システムの停止手順

7.17.3　CJMSPブローカーの状態の確認

7.18　障害対応用の情報の確認

7.19　Cosminexus JMSプロバイダ使用時の注意事項

8.　JavaMailの利用

8.1　この章の構成

8.2　セッションプロパティ

8.2.1　SMTPサーバに接続するためのセッションプロパティ

8.2.2　POP3サーバに接続するためのセッションプロパティ

8.3　JavaMailを利用する場合の注意事項

9.　セキュリティ管理

9.1　この章の構成

9.2　SSL使用による認証情報とデータの暗号化

9.2.1　Webサーバの認証機能

9.2.2　通信路のセキュリティレベルの要請

9.2.3　SSLで使用された証明書情報の取得

9.2.4　DDでの定義

9.2.5　Hitachi Web ServerのSSLの設定

9.2.6　Hitachi Web ServerのSSLの設定（Webリダイレクタ環境の場合）

9.2.7　Microsoft IISの設定（Webリダイレクタ環境の場合）

9.2.8　実行環境での設定

9.3　ロールに基づくWebコンテナのユーザ認証

9.3.1　ロールに基づくWebコンテナのユーザ認証の機能

9.3.2　DDでの定義

9.3.3　実行環境での設定（J2EEアプリケーションの設定）

9.3.4　認証機能を併用するときの注意

9.4　SecurityManagerによるWebコンテナの実行時の保護

9.5　セキュリティアイデンティティを使用した認証

9.5.1　セキュリティアイデンティティの機能

9.5.2　セキュリティアイデンティティを使用した認証の設定

10.　アプリケーションの属性管理

10.1　この章の構成

10.2　属性の管理

10.3　cosminexus.xmlを含むアプリケーション

10.3.1　cosminexus.xmlとは

10.3.2　cosminexus.xmlを含むアプリケーションを使用する利点

10.3.3　cosminexus.xmlを含むアプリケーションの作成

10.3.4　cosminexus.xmlの作成

10.3.5　cosminexus.xmlの作成例

10.3.6　cosminexus.xmlを含むアプリケーションの運用

10.3.7　cosminexus.xmlを含まないアプリケーションから移行する手順

10.4　DDの省略

10.4.1　アプリケーションサーバで実行できるアプリケーションの構成

10.4.2　application.xmlの有無による機能の違い

10.4.3　application.xmlがある場合のモジュールの決定規則

10.4.4　application.xmlがない場合のモジュールの決定規則

10.4.5　web.xmlを省略したWebアプリケーションに対する操作

10.4.6　DDを省略した場合に設定される表示名

10.4.7　application.xmlを省略した場合にapplication.xmlが作成される操作

10.4.8　application.xmlを省略した場合にJ2EEアプリケーションにリソースを追加するときの注意

11.　アノテーションの使用

11.1　この章の構成

11.2　アノテーションの指定

11.2.1　アノテーションを使用するメリットと指定できるアノテーション

11.2.2　アノテーションを宣言したライブラリJARのクラスの使用

11.2.3　アノテーションを指定する場合のEnterprise Beanの実装

11.3　ロード対象のクラスとロード時に必要なクラスパス

11.4　DIの使用

11.4.1　@Resourceアノテーションで指定できるリソースのタイプ

11.4.2　@Resourceアノテーションを使用したリソースの参照解決

11.4.3　DI失敗時の動作

11.4.4　注意事項

11.5　アノテーションの参照抑止

11.5.1　アノテーション参照抑止機能の目的と適用範囲

11.5.2　アノテーションを参照するタイミング

11.5.3　DDでの定義（モジュール単位の設定）

11.5.4　実行環境での設定（J2EEサーバ単位の設定）

11.5.5　アノテーション参照抑止機能の設定変更

11.6　アノテーションで定義した内容の更新

11.6.1　アノテーションの更新

11.6.2　DDによるアノテーションの上書き

11.6.3　サーバ管理コマンドを使用した定義の参照と更新

11.7　アノテーション使用時の注意事項

12.　J2EEアプリケーションの形式とデプロイ

12.1　この章の構成

12.2　実行できるJ2EEアプリケーションの形式

12.3　アーカイブ形式のJ2EEアプリケーション

12.4　展開ディレクトリ形式のJ2EEアプリケーション

12.4.1　展開ディレクトリ形式の概要

12.4.2　アプリケーションディレクトリの構成

12.4.3　展開ディレクトリ形式のJ2EEアプリケーションを使用するための設定（セキュリティの設定変更）

12.4.4　展開ディレクトリ形式を使用する場合の注意事項

12.5　J2EEアプリケーションのデプロイとアンデプロイ

12.5.1　アーカイブ形式のJ2EEアプリケーションのデプロイとアンデプロイ

12.5.2　展開ディレクトリ形式のJ2EEアプリケーションのデプロイとアンデプロイ

12.5.3　EARファイル／ZIPファイルの展開ディレクトリ形式でのデプロイ

12.5.4　J2EEアプリケーションへのプロパティの設定

12.6　J2EEアプリケーションの入れ替え

12.7　J2EEアプリケーションのリデプロイ

12.7.1　リデプロイによるJ2EEアプリケーションの入れ替え

12.7.2　J2EEアプリケーションの状態と入れ替え

12.7.3　リデプロイによるJ2EEアプリケーションの入れ替えの注意事項

12.8　J2EEアプリケーションの更新検知とリロード

12.8.1　J2EEアプリケーションのリロード方法

12.8.2　リロードの適用範囲

12.8.3　リロード時のクラスローダの構成

12.8.4　エラー発生時の動作

12.8.5　更新検知の対象となるファイル

12.8.6　J2EEアプリケーションの更新検知インターバル

12.8.7　J2EEアプリケーションの構成ファイル更新用インターバル

12.8.8　Webアプリケーションのリロード

12.8.9　JSPのリロード

12.8.10　ほかの機能との関係

12.8.11　コマンドによるJ2EEアプリケーションのリロード

12.8.12　J2EEアプリケーションの更新検知とリロードの設定

12.8.13　リロードの注意事項および制限事項

13.　コンテナ拡張ライブラリ

13.1　この章の構成

13.2　コンテナ拡張ライブラリの利用

13.3　コンテナ拡張ライブラリの機能

13.3.1　コンテナ拡張ライブラリ利用の検討

13.3.2　コンテナ拡張ライブラリの作成と利用の流れ

13.3.3　コンテナ拡張ライブラリの機能を使用するための設定

13.4　サーバ起動・停止フック機能

13.4.1　サーバ起動・停止フック処理の呼び出し順序

13.4.2　サーバ起動・停止フック機能の実装方法

13.4.3　サーバ起動・停止フック機能利用時のクラスパスの指定

13.5　スマートエージェント経由でのCORBAオブジェクトの呼び出し

13.5.1　CORBAオブジェクト呼び出し処理の実装時の注意事項

13.5.2　CORBAオブジェクト呼び出し処理のパッケージ化の注意事項

13.6　コンテナ拡張ライブラリおよびサーバ起動・停止フック機能利用時の制限事項

14.　アプリケーション実装時の注意事項

14.1　スレッドローカル変数使用時の注意事項

付録

付録A　文字コード

付録A.1　アプリケーションで扱う文字コード

付録A.2　ブラウザとアプリケーション間の文字コード変換

付録A.3　データベースとアプリケーション間の文字コード変換

付録B　クラスローダの構成

付録B.1　デフォルトのクラスローダ構成

付録B.2　ローカル呼び出し最適化時のクラスローダ構成

付録B.3　下位互換用のクラスローダ構成

付録B.4　クラスローダに設定されるクラスパス

付録C　JPAプロバイダとEJBコンテナ間の規約

付録C.1　ランタイムに関する規約

付録C.2　デプロイメントに関する規約

付録D　JPQLのBNF

付録E　Cosminexus JMSプロバイダのユースケース

付録E.1　すべてのユースケースに共通の前提条件

付録E.2　前提とするプロセスモデル

付録E.3　Cosminexus JMSプロバイダを使用する場合の環境構築

付録E.4　Cosminexus JMSプロバイダを使用するアプリケーションの追加

付録E.5　Cosminexus JMSプロバイダを使用するアプリケーションの削除

付録E.6　Cosminexus JMSプロバイダサービスの開始（初回起動時）

付録E.7　Cosminexus JMSプロバイダサービスの開始（稼働中システムの再起動時）

付録E.8　CJMSPリソースアダプタとCJMSPブローカーの状態確認

付録E.9　メッセージ配信状況の確認と滞留時の対処（CJMSPブローカーを一時停止する方法）

付録E.10　メッセージ配信状況の確認と滞留時の対処（アプリケーションを停止する方法）

付録E.11　Cosminexus JMSプロバイダサービスの終了

付録E.12　送信先の圧縮

付録E.13　送信先サイズの変更

付録E.14　永続化サブスクライバーの削除

付録E.15　CJMSPブローカーの状態監視

付録E.16　CJMSPブローカーの詳細情報確認

付録E.17　送信先の状態確認

付録E.18　永続化サブスクライバーの状態確認

付録E.19　CJMSPリソースアダプタに問題が発生した場合の解析

付録E.20　CJMSPブローカーが障害によって停止したときの解析

付録E.21　Cosminexus JMSプロバイダサービス無応答時の解析

付録E.22　CJMSPリソースアダプタに問題が発生した場合の回復

付録E.23　CJMSPブローカーが障害によって停止したときの回復

付録E.24　Cosminexus JMSプロバイダサービス無応答時の回復

付録E.25　Cosminexus JMSプロバイダサービスインスタンスの削除

付録F　各バージョンでの主な機能変更

付録F.1　08-53での主な機能変更

付録F.2　08-50での主な機能変更

付録F.3　08-00での主な機能変更

付録G　このマニュアルの参考情報

付録G.1　関連マニュアル

付録G.2　マニュアル体系の変更について

付録G.3　このマニュアルでの表記

付録G.4　英略語

付録G.5　KB（キロバイト）などの単位表記について

付録H　用語解説

索引

[他社商品名称に関する表示]

All Rights Reserved. Copyright (C) 2008, 2011, Hitachi, Ltd.

前書き

■ 対象製品

●適用OS：Windows Server 2003，Windows Server 2003 R2，Windows Server 2003（x64）※¹，Windows Server 2003 R2（x64）※¹，Windows Server 2008 x86，Windows Server 2008 x64※¹，Windows Server 2008 R2※¹

P-2443-7B84　 uCosminexus Application Server Standard-R　 08-70
P-2443-7D84　 uCosminexus Application Server Standard　 08-70
P-2443-7K84　 uCosminexus Application Server Enterprise　 08-70
P-2443-7M84　 uCosminexus Web Redirector　 08-70
P-2443-7S84　 uCosminexus Service Platform　 08-70※2

●適用OS：Windows Server 2003，Windows Server 2003 R2，Windows Vista，Windows XP，Windows 7（32bit），Windows 7（x64）※¹

P-2443-7E84　 uCosminexus Developer Standard　 08-70
P-2443-7F84　 uCosminexus Developer Professional　 08-70
P-2443-7T84　 uCosminexus Service Architect　 08-70※2

●適用OS：Windows Server 2003，Windows Server 2003 R2，Windows Server 2003（x64）※¹，Windows Server 2003 R2（x64）※¹，Windows Server 2008 x86，Windows Server 2008 x64※¹，Windows Server 2008 R2※¹，Windows Vista，Windows XP，Windows 7（32bit），Windows 7（x64）※¹

P-2443-7H84　 uCosminexus Client　 08-70

●適用OS：Windows Server 2003（x64），Windows Server 2003 R2（x64），Windows Server 2008 x64，Windows Server 2008 R2

P-2943-7B84　 uCosminexus Application Server Standard-R　 08-70
P-2943-7D84　 uCosminexus Application Server Standard　 08-70
P-2943-7K84　 uCosminexus Application Server Enterprise　 08-70
P-2943-7S84　 uCosminexus Service Platform　 08-70※2

●適用OS：AIX 5L V5.3，AIX V6.1，AIX V7.1

P-1M43-7D81　 uCosminexus Application Server Standard　 08-70※2
P-1M43-7K81　 uCosminexus Application Server Enterprise　 08-70※2
P-1M43-7S81　 uCosminexus Service Platform　 08-70※2

●適用OS：HP-UX 11i V2（IPF），HP-UX 11i V3（IPF）

P-1J43-7D81　 uCosminexus Application Server Standard　 08-70
P-1J43-7K81　 uCosminexus Application Server Enterprise　 08-70
P-1J43-7S81　 uCosminexus Service Platform　 08-70※2

●適用OS：Red Hat Enterprise Linux AS 4（x86），Red Hat Enterprise Linux ES 4（x86），Red Hat Enterprise Linux AS 4（AMD64 & Intel EM64T），Red Hat Enterprise Linux ES 4（AMD64 & Intel EM64T），Red Hat Enterprise Linux 5 Advanced Platform（x86），Red Hat Enterprise Linux 5（x86），Red Hat Enterprise Linux 5 Advanced Platform（AMD/Intel 64），Red Hat Enterprise Linux 5（AMD/Intel 64），Red Hat Enterprise Linux Server 6（32-bit x86），Red Hat Enterprise Linux Server 6（64-bit x86_64）

P-9S43-7B81　 uCosminexus Application Server Standard-R　 08-70※2
P-9S43-7D81　 uCosminexus Application Server Standard　 08-70※2
P-9S43-7K81　 uCosminexus Application Server Enterprise　 08-70※2
P-9S43-7M81　 uCosminexus Web Redirector　 08-70※2
P-9S43-7S81　 uCosminexus Service Platform　 08-70※2

注※1　WOW64（Windows On Windows 64）環境だけで使用できます。
注※2　この製品については，サポート時期をご確認ください。
これらのプログラムプロダクトのほかにもこのマニュアルをご利用になれる場合があります。詳細は「リリースノート」でご確認ください。
本製品では日立トレース共通ライブラリをインストールします。

■ 輸出時の注意

本製品を輸出される場合には，外国為替および外国貿易法ならびに米国の輸出管理関連法規などの規制をご確認の上，必要な手続きをお取りください。
なお，ご不明な場合は，弊社担当営業にお問い合わせください。

■ 商標類

Active Directoryは，米国Microsoft Corporationの，米国およびその他の国における登録商標または商標です。
AIXは，米国およびその他の国におけるInternational Business Machines Corporationの商標です。
AIX 5Lは，米国およびその他の国におけるInternational Business Machines Corporationの商標です。
AMDは，Advanced Micro Devices, Inc.の商標です。
AX2000は，A10 Networks, Inc.の商品名称です。
Borlandのブランド名および製品名はすべて，米国Borland Software Corporationの米国およびその他の国における商標または登録商標です。
CORBAは，Object Management Groupが提唱する分散処理環境アーキテクチャの名称です。
HP-UXは，Hewlett-Packard Companyのオペレーティングシステムの名称です。
IIOPは，OMG仕様によるORB(Object Request Broker)間通信のネットワークプロトコルの名称です。
Internet Explorerは，米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
Itaniumは，アメリカ合衆国およびその他の国におけるIntel Corporationの商標です。
J2EEは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Javaは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
JavaScriptは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
JDBCは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
JDKは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
JSPは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Linuxは，Linus Torvalds氏の日本およびその他の国における登録商標または商標です。
Microsoftは，米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
Microsoft Internet Information Servicesは，米国Microsoft Corporationの商品名称です。
MyEclipseは，米国Genuitec社の商品名称です。
OMG，CORBA，IIOP，UML，Unified Modeling Language，MDA，Model　Driven　Architectureは，Object Management Group, Inc.の米国及びその他の国における登録商標または商標です。
ORACLEは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Oracle及びOracle 10gは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Oracle及びOracle9iは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Oracle及びOracle Database 10gは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Oracle及びOracle Database 11gは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Red Hatは，米国およびその他の国でRed Hat, Inc. の登録商標もしくは商標です。
Solarisは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
すべてのSPARC商標は，米国SPARC International, Inc. のライセンスを受けて使用している同社の米国およびその他の国における商標または登録商標です。SPARC商標がついた製品は，米国Sun Microsystems, Inc. が開発したアーキテクチャに基づくものです。
SQL Serverは，米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
Sunは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Sun Microsystemsは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
UNIXは，The Open Groupの米国ならびに他の国における登録商標です。
Windowsは，米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
Windows Serverは，米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
Windows Vistaは，米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
X/Openは，The Open Groupの英国ならびに他の国における登録商標です。
Eclipseは，開発ツールプロバイダのオープンコミュニティであるEclipse Foundation, Inc.により構築された開発ツール統合のためのオープンプラットフォームです。
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

■ マイクロソフト製品の表記について

このマニュアルでは，マイクロソフト製品の名称を次のように表記しています。

製品名 | 表記
Microsoft(R) Active Directory(R) | Active Directory
Microsoft(R) Internet Information Services 6.0 | Microsoft IIS 6.0 | Microsoft IIS
Microsoft(R) Internet Information Services 7.0 | Microsoft IIS 7.0
Microsoft(R) Internet Information Services 7.5 | Microsoft IIS 7.5
Microsoft(R) SQL Server 2000 | SQL Server 2000 | SQL Server
Microsoft(R) SQL Server 2005 | SQL Server 2005
Microsoft(R) SQL Server 2008 | SQL Server 2008
Microsoft(R) SQL Server 2000 Driver for JDBC | SQL Server 2000 Driver for JDBC | SQL ServerのJDBCドライバ
Microsoft(R) SQL Server 2005 JDBC Driver | SQL Server 2005 JDBC Driver
Microsoft(R) SQL Server JDBC Driver 2.0 | SQL Server JDBC Driver
Microsoft(R) SQL Server JDBC Driver 3.0
Microsoft(R) Windows(R) 7 Enterprise（32bit） | Windows 7（32bit） | Windows 7 | Windows
Microsoft(R) Windows(R) 7 Professional（32bit）
Microsoft(R) Windows(R) 7 Ultimate（32bit）
Microsoft(R) Windows(R) 7 Enterprise（x64） | Windows 7（x64）
Microsoft(R) Windows(R) 7 Professional（x64）
Microsoft(R) Windows(R) 7 Ultimate（x64）
Microsoft(R) Windows Server(R) 2003，Enterprise Edition 日本語版 | Windows Server 2003 Enterprise Edition | Windows Server 2003
Microsoft(R) Windows Server(R) 2003，Standard Edition 日本語版 | Windows Server 2003 Standard Edition
Microsoft(R) Windows Server(R) 2003 R2，Enterprise Edition 日本語版 | Windows Server 2003 R2 Enterprise Edition | Windows Server 2003 R2
Microsoft(R) Windows Server(R) 2003 R2，Standard Edition 日本語版 | Windows Server 2003 R2 Standard Edition
Microsoft(R) Windows Server(R) 2003，Enterprise x64 Edition 日本語版 | Windows Server 2003 Enterprise x64 Edition | Windows Server 2003（x64）
Microsoft(R) Windows Server(R) 2003，Standard x64 Edition 日本語版 | Windows Server 2003 Standard x64 Edition
Microsoft(R) Windows Server(R) 2003 R2，Enterprise x64 Edition 日本語版 | Windows Server 2003 R2 Enterprise x64 Edition | Windows Server 2003 R2（x64）
Microsoft(R) Windows Server(R) 2003 R2，Standard x64 Edition 日本語版 | Windows Server 2003 R2 Standard x64 Edition
Microsoft(R) Windows Server(R) 2008 Enterprise 32-bit 日本語版 | Windows Server 2008 x86
Microsoft(R) Windows Server(R) 2008 Standard 32-bit 日本語版
Microsoft(R) Windows Server(R) 2008 Enterprise 日本語版 | Windows Server 2008 x64
Microsoft(R) Windows Server(R) 2008 Standard 日本語版
Microsoft(R) Windows Server(R) 2008 R2 Enterprise 日本語版 | Windows Server 2008 R2
Microsoft(R) Windows Server(R) 2008 R2 Standard 日本語版
Microsoft(R) Windows Vista(R) Business | Windows Vista Business | Windows Vista
Microsoft(R) Windows Vista(R) Enterprise | Windows Vista Enterprise
Microsoft(R) Windows Vista(R) Ultimate | Windows Vista Ultimate
Microsoft(R) Windows(R) XP Professional Operating System | Windows XP
Windows(R) Internet Explorer(R) | Internet Explorer

■ 発行

2011年 7月 3020-3-U07-60

■ 著作権

All Rights Reserved. Copyright (C) 2008, 2011, Hitachi, Ltd.

変更内容

変更内容（3020-3-U07-60）uCosminexus Application Server Enterprise 08-70，uCosminexus Application Server Standard 08-70，uCosminexus Application Server Standard-R 08-70，uCosminexus Client 08-70，uCosminexus Developer Professional 08-70，uCosminexus Developer Standard 08-70，uCosminexus Service Architect 08-70，uCosminexus Service Platform 08-70，uCosminexus Web Redirector 08-70

追加・変更内容
変更個所

アプリケーションサーバ 08-70での主な機能変更についての説明を追加した。また，アプリケーションサーバ 08-53での主な機能変更についての説明を付録F.1に移動した。
1.4，付録F.1

Enterprise BeanおよびJ2EEリソースの別名に指定できる文字に，ハイフン（-）を追加した。
2.4.2

TP1インバウンド連携機能を呼び出せるOpenTP1のプログラムにMHP（メッセージ処理プログラム）を追加した。
3.9，4.2，4.4.1，4.12.3

Connector 1.5仕様に準拠したリソースアダプタの場合に，InboundでTransacted Deliveryを使用できるようにした。
3.13.2，3.16.3，3.16.7，3.16.10

ステートメントプーリング機能で，ステートメントを再利用する際に初期化する内容を設定できるようにした。
3.14.4，3.14.10

ejb-jar.xmlにインターセプタの定義およびアプリケーション例外の定義を指定できるようにした。
10.2，11.5.1，11.6.2，11.7

DDによるアノテーションの上書きに関する説明を追加した。
11.6.2，11.6.3

server.policyファイルに統合ユーザ管理機能のパーミッションに関する説明を追加した。
12.4.3

次の製品の適用OSにAIX，HP-UX（IPF）を追加した。

uCosminexus Application Server Enterprise

uCosminexus Application Server Standard

uCosminexus Service Platform

－

次の製品の適用OSにRed Hat Enterprise Linux Server 6（32-bit x86），Red Hat Enterprise Linux Server 6（64-bit x86_64）を追加した。

uCosminexus Application Server Enterprise

uCosminexus Application Server Standard

uCosminexus Application Server Standard-R

uCosminexus Service Platform

uCosminexus Web Redirector

－

単なる誤字・脱字などはお断りなく訂正しました。

変更内容（3020-3-U07-40）uCosminexus Application Server Enterprise 08-53，uCosminexus Application Server Standard 08-53，uCosminexus Application Server Standard-R 08-53，uCosminexus Client 08-53，uCosminexus Developer Professional 08-53，uCosminexus Developer Standard 08-53，uCosminexus Service Architect 08-53，uCosminexus Service Platform 08-53，uCosminexus Web Redirector 08-53

追加・変更内容

機能の分類とマニュアルの対応の説明に，次の機能を追加した。

JavaMailの利用

トランザクションインフローの機能を追加した。

OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）に次の機能を追加した。

コネクション管理機能

トランザクション連携機能

JavaMailで，POP3サーバによるメールの受信機能をサポートした。

アプリケーションサーバ 08-53での主な機能変更についての説明を追加した。また，アプリケーションサーバ 08-50での主な機能変更についての説明を付録F.1に移動した。

SQL Server 2008に対応した。これに伴い，使用できるJDBCドライバにSQL Server JDBC Driver 2.0，およびSQL Server JDBC Driver 3.0を追加した。

HiRDB Version 9に対応した。

TP1インバウンド連携機能を使用してOpenTP1と接続する場合に，トランザクション属性にRequiredを指定できるようにした。

Microsoft IIS 7.0およびMicrosoft IIS 7.5に対応した。

対象製品としてuCosminexus Application Server Standard-Rを追加した。

次の製品の適用OSからAIX，HP-UX，Linux（IPF）を削除した。

uCosminexus Application Server Standard

uCosminexus Application Server Enterprise

uCosminexus Service Platform

変更内容（3020-3-U07-20）uCosminexus Application Server Enterprise 08-50，uCosminexus Application Server Standard 08-50，uCosminexus Client 08-50，uCosminexus Developer Professional 08-50，uCosminexus Developer Standard 08-50，uCosminexus Service Architect 08-50，uCosminexus Service Platform 08-50，uCosminexus Web Redirector 08-50

追加・変更内容

機能の分類とマニュアルの対応の説明に，次の機能を追加した。

OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）

Cosminexus JMSプロバイダ

スレッドの非同期並行処理

ホスト単位管理モデルを対象にした系切り替えシステム（クラスタソフトウェアとの連携）

JP1 Version 9に対応した。また，JP1 Version 7は非サポートとなったため削除した。

OpenTP1からアプリケーションサーバを呼び出す機能（TP1インバウンド連携機能）を追加した。

Cosminexus JMSプロバイダの機能を追加した。

アプリケーションサーバ 08-50での主な機能変更についての説明を追加した。また，アプリケーションサーバ 08-00での主な機能変更についての説明を付録F.1に移動した。

リロード機能で更新できるアノテーションに@WebServiceProviderを追加した。

アプリケーション実装時の注意事項の説明を追加した。

次の製品の適用OSにWindows Server 2008 R2を追加した。

uCosminexus Application Server Standard

uCosminexus Application Server Enterprise

uCosminexus Web Redirector

uCosminexus Service Platform

uCosminexus Client

次の製品の適用OSにWindows 7を追加した。

uCosminexus Developer Standard

uCosminexus Developer Professional

uCosminexus Service Architect

uCosminexus Client

はじめに

このマニュアルは，Cosminexus（コズミネクサス）のアプリケーションサーバの機能について説明したものです。このマニュアルでは，アプリケーションサーバが提供するWebコンテナおよびEJBコンテナから共通で使用できる機能について説明します。また，アプリケーションサーバがほかのリソースと接続する場合に使用できる機能についても説明しています。

アプリケーションサーバでは，次に示すプログラムプロダクトを使用してシステムを構築，運用します。

uCosminexus Application Server Enterprise

uCosminexus Application Server Standard

uCosminexus Application Server Standard-R

uCosminexus Client

uCosminexus Developer Professional

uCosminexus Developer Standard

uCosminexus Service Architect

uCosminexus Service Platform

uCosminexus Web Redirector

このマニュアルでは，これらのプログラムプロダクトの構成ソフトウェアのうち，次に示す構成ソフトウェアについて説明しています。

Cosminexus Component Container

Cosminexus Component Container - Client

Cosminexus Component Container - Redirector

Cosminexus Component Transaction Monitor

Cosminexus Developer's Kit for Java

Cosminexus Performance Tracer

Cosminexus TPBroker

対象読者

このマニュアルは，アプリケーションサーバのシステムを設計，構築または運用する方，およびアプリケーションサーバで動作するアプリケーションを開発する方を対象としています。

次の内容を理解されていることを前提としています。

システムを設計，構築または運用する方

Windowsまたはご使用のUNIXのシステム構築および運用に関する知識

Java EEに関する知識

SQLおよびリレーショナルデータベースに関する基本的な知識

CORBAに関する基本的な知識

アプリケーションを開発する方

Windowsの基本操作に関する知識

Javaによるプログラム開発に関する基本的な知識

使用するIDE（Eclipse）に関する基本的な知識

ご利用の製品ごとの用語の読み替えについて

ご利用の製品によっては，マニュアルで使用している用語を，ご利用の製品名に読み替える必要があります。

次の表に従って，マニュアルで使用している用語をご利用の製品名に読み替えてください。

ご利用の製品名 | マニュアルで使用している用語
uCosminexus Application Server Standard-R | Application Server
uCosminexus Developer Professional※1 | Application ServerおよびApplication Server Enterprise
uCosminexus Developer Standard※1，※2 | Application Server
uCosminexus Service Architect※1 | Application ServerおよびApplication Server Enterprise
uCosminexus Service Platform

注※1　テスト環境で使用している場合にだけ読み替えが必要です。

注※2　uCosminexus Developer StandardとApplication Serverには一部機能差があります。機能差については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション開発ガイド」の「付録D　Developer Standard使用時の注意事項」を参照してください。

図中で使用している記号

このマニュアルの図中で使用している記号について次に示します。

文法で使用している記号

このマニュアルの文法で使用している記号について次に示します。

記号
意　味

　｜
横に並べられた複数の項目に対する項目間の区切りを示し，「または」を意味します。
（例）　A｜B
　AまたはBを指定することを示します。

［　］
この記号で囲まれている項目は省略してもよいことを示します。複数の項目が横に並べて記述されている場合には，すべてを省略するか，記号｛ ｝と同じくどれか一つを選択します。
（例１）　［A］
　「何も指定しない」か「Aを指定する」ことを示します。
（例２）　［B｜C］
　「何も指定しない」か「BまたはCを指定する」ことを示します。

<　>
この記号で囲まれている項目は，該当する要素やファイルなどを指定したり，該当する要素が表示されたりすることを示します。
（例１）　<プロパティ>
　プロパティを記述します。またはプロパティが表示されます。
（例２）　<ファイル名>
　ファイル名を指定します。

CUIおよびGUIの説明で使用している記号

このマニュアルのCUIおよびGUIの説明で使用している記号について次に示します。

記号
意味

　｜
横に並べられた複数の項目に対する項目間の区切りを示し，「または」を意味します。
（例）　A｜B
　AまたはBを指定することを示します。

{ 　 }
この記号で囲まれている複数の項目のうちから一つを選択することを示します。項目が横に並べられ，記号｜で区切られている場合は，そのうちの一つを選択します。
（例）　｛A｜B｜C｝
　A，BまたはCのどれかを指定することを示します。

［　］
この記号で囲まれている項目は画面名または画面に表示されている項目であることを表します。

<　>
<　>内の名称がユーザの環境によって異なることを表します。

1.　アプリケーションサーバの機能

この章では，アプリケーションサーバの機能の分類と目的，および機能とマニュアルの対応について説明します。また，このバージョンで変更した機能についても説明しています。

＜この章の構成＞

1.1　機能の分類

1.2　システムの目的と機能の対応

1.3　このマニュアルに記載している機能の説明

1.4　アプリケーションサーバ 08-70での主な機能変更

1.1　機能の分類

アプリケーションサーバは，Java EE 5に準拠したJ2EEサーバを中心としたアプリケーションの実行環境を構築したり，実行環境上で動作するアプリケーションを開発したりするための製品です。Java EEの標準仕様に準拠した機能や，アプリケーションサーバで独自に拡張された機能など，多様な機能を使用できます。目的や用途に応じた機能を選択して使用することで，信頼性の高いシステムや，処理性能に優れたシステムを構築・運用できます。

アプリケーションサーバの機能は，大きく分けて，次の二つに分類できます。

アプリケーションの実行基盤としての機能

アプリケーションの実行基盤を運用・保守するための機能

二つの分類は，機能の位置づけや用途によって，さらに詳細に分類できます。アプリケーションサーバのマニュアルは，機能の分類に合わせて提供しています。

アプリケーションサーバの機能の分類と対応するマニュアル（機能解説）の体系について，次の図に示します。

図1-1　アプリケーションサーバの機能の分類と対応するマニュアル（機能解説）の体系

ここでは，機能の分類について，マニュアルとの対応と合わせて説明します。

＜この節の構成＞

1.1.1　アプリケーションの実行基盤としての機能

1.1.2　アプリケーションの実行基盤を運用・保守するための機能

1.1.3　機能とマニュアルの対応

1.1.1　アプリケーションの実行基盤としての機能

アプリケーションとして実装されたオンライン業務やバッチ業務を実行する基盤となる機能です。システムの用途や求められる要件に応じて，使用する機能を選択します。

アプリケーションの実行基盤としての機能を使用するかどうかは，システム構築やアプリケーション開発よりも前に検討する必要があります。

アプリケーションの実行基盤としての機能について，分類ごとに説明します。

＜この項の構成＞

(1)　Java EEに準拠したアプリケーションを動作させるための基本的な機能（基本・開発機能）

(2)　信頼性や性能などを向上させるために拡張されたアプリケーションサーバ独自の機能（拡張機能）

(1)　Java EEに準拠したアプリケーションを動作させるための基本的な機能（基本・開発機能）

Java EEに準拠したアプリケーション（J2EEアプリケーション）を動作させるための基本的な機能が該当します。主にJ2EEサーバの機能が該当します。

アプリケーションサーバでは，Java EE 5に準拠したJ2EEサーバを提供しています。J2EEサーバでは，標準仕様に準拠した機能のほか，アプリケーションサーバ独自の機能も提供しています。

基本・開発機能は，機能を使用するJ2EEアプリケーションの形態に応じて，さらに三つに分類できます。アプリケーションサーバの機能解説のマニュアルは，この分類に応じて分冊されています。

それぞれの分類の概要を説明します。

Webアプリケーションを実行するための機能（Webコンテナ）
Webアプリケーションの実行基盤であるWebコンテナの機能，およびWebコンテナとWebサーバが連携して実現する機能が該当します。

Enterprise Beanを実行するための機能（EJBコンテナ）
Enterprise Beanの実行基盤であるEJBコンテナの機能が該当します。また，Enterprise Beanを呼び出すEJBクライアントの機能も該当します。

WebアプリケーションとEnterprise Beanの両方で使用する機能（コンテナ共通機能）
Webコンテナ上で動作するWebアプリケーションおよびEJBコンテナ上で動作するEnterprise Beanの両方で使用できる機能が該当します。

(2)　信頼性や性能などを向上させるために拡張されたアプリケーションサーバ独自の機能（拡張機能）

アプリケーションサーバで独自に拡張された機能が該当します。バッチサーバ，CTM，データベースなど，J2EEサーバ以外のプロセスを使用して実現する機能も含まれます。

アプリケーションサーバでは，システムの信頼性を高め，安定稼働を実現するための多様な機能が拡張されています。また，J2EEアプリケーション以外のアプリケーション（バッチアプリケーション）をJavaの環境で動作させる機能も拡張しています。

1.1.2　アプリケーションの実行基盤を運用・保守するための機能

アプリケーションの実行基盤を効率良く運用したり，保守したりするための機能です。システムの運用開始後に，必要に応じて使用します。ただし，機能によっては，あらかじめ設定やアプリケーションの実装が必要なものがあります。

アプリケーションの実行基盤を運用・保守するための機能について，分類ごとに説明します。

＜この項の構成＞

(1)　システムの起動・停止など日常的な運用をするための機能（運用機能）

(2)　システムの利用状況を監視するための機能（監視機能）

(3)　ほかの製品と連携して運用するための機能（連携機能）

(4)　トラブル発生時などに対処するための機能（保守機能）

(5)　旧バージョンの製品から移行するための機能（移行機能）

(6)　旧バージョンの製品との互換のための機能（互換機能）

(1)　システムの起動・停止など日常的な運用をするための機能（運用機能）

システムの起動や停止，アプリケーションの開始や停止，入れ替えなどの，日常運用で使用する機能が該当します。

(2)　システムの利用状況を監視するための機能（監視機能）

システムの稼働状態や，リソースの枯渇状態などを監視するための機能が該当します。また，システムの操作履歴など，監査で使用する情報を出力する機能も該当します。

(3)　ほかの製品と連携して運用するための機能（連携機能）

JP1やクラスタソフトウェアなど，ほかの製品と連携して実現する機能が該当します。

(4)　トラブル発生時などに対処するための機能（保守機能）

トラブルシューティングのための機能が該当します。トラブルシューティング時に参照する情報を出力するための機能も含みます。

(5)　旧バージョンの製品から移行するための機能（移行機能）

旧バージョンのアプリケーションサーバから新しいバージョンのアプリケーションサーバに移行するための機能が該当します。

(6)　旧バージョンの製品との互換のための機能（互換機能）

旧バージョンのアプリケーションサーバとの互換用の機能が該当します。なお，互換機能については，「1.1.1　アプリケーションの実行基盤としての機能」に該当する機能などの推奨機能に移行することをお勧めします。

1.1.3　機能とマニュアルの対応

アプリケーションサーバの機能解説のマニュアルは，機能の分類に合わせて分冊されています。

機能の分類と，それぞれの機能について説明しているマニュアルとの対応を次の表に示します。

表1-1　機能の分類とマニュアルの対応

分類 | 機能 | 参照先マニュアル※1
基本・開発機能 | Webコンテナ | 基本・開発編(Webコンテナ)
Webサーバ連携
インプロセスHTTPサーバ
サーブレットおよびJSPの実装
EJBコンテナ | 基本・開発編(EJBコンテナ)
EJBクライアント
Enterprise Bean実装時の注意事項
ネーミング管理 | 基本・開発編(コンテナ共通機能)※2
リソース接続とトランザクション管理
OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）
アプリケーションサーバでのJPAの利用
Cosminexus JPAプロバイダ
Cosminexus JMSプロバイダ
JavaMailの利用
セキュリティ管理
アプリケーションの属性管理
アノテーションの使用
J2EEアプリケーションの形式とデプロイ
コンテナ拡張ライブラリ
拡張機能 | バッチサーバによるアプリケーションの実行 | 拡張編
CTMによるリクエストのスケジューリングと負荷分散
バッチアプリケーションのスケジューリング
J2EEサーバ間のセッション情報の引き継ぎ（セッションフェイルオーバ機能）
明示管理ヒープ機能を使用したフルガーベージコレクションの抑止
クライアント性能の測定と分析
統合ユーザ管理
複数の構築済み実行環境の切り替え
アプリケーションのユーザログ出力
スレッドの非同期並行処理
運用機能 | システムの起動と停止 | 運用／監視／連携編
J2EEアプリケーションの運用
監視機能 | 稼働情報の監視（稼働情報収集機能）
リソースの枯渇監視
監査ログ出力機能
データベース監査証跡連携機能
運用管理コマンドによる稼働情報の出力
Managementイベントの通知とManagementアクションによる処理の自動実行
CTMの稼働統計情報の収集
コンソールログの出力
連携機能 | JP1と連携したシステムの運用
システムの構成定義および管理（JP1/IM-CMとの連携）
システムの集中監視（JP1/IMとの連携）
ジョブによるシステムの自動運転（JP1/AJSとの連携）
シナリオによるシステムの自動運転（JP1/AJS2 - SOとの連携）
監査ログの収集および一元管理（JP1/NETM/Auditとの連携）
クラスタソフトウェアとの連携
1:1系切り替えシステム（クラスタソフトウェアとの連携）
相互系切り替えシステム（クラスタソフトウェアとの連携）
N:1リカバリシステム（クラスタソフトウェアとの連携）
ホスト単位管理モデルを対象にした系切り替えシステム（クラスタソフトウェアとの連携）
保守機能 | トラブルシューティング関連機能 | 保守／移行／互換編
性能解析トレースを使用したシステムの性能解析
日立固有のJavaVMの機能
移行機能 | 旧バージョンのアプリケーションサーバからの移行
推奨機能への移行
互換機能 | 旧バージョンとの互換用機能（ベーシックモード）
旧バージョンとの互換用機能（サーブレットエンジンモード）
Cosminexus DABroker Libraryを使用したデータベース接続

注※1　マニュアル名称の「Cosminexus アプリケーションサーバ 機能解説」を省略しています。

注※2　このマニュアルです。

1.2　システムの目的と機能の対応

アプリケーションサーバでは，構築・運用するシステムの目的に合わせて，適用する機能を選択する必要があります。

この節では，WebコンテナおよびEJBコンテナが共通で使用できる機能について，どのようなシステムの場合に使用するとよいかを示します。機能ごとに，次の項目への対応を示しています。

信頼性
高い信頼が求められるシステムの場合に使用するとよい機能です。
アベイラビリティ（安定稼働性）およびフォールトトレランス（耐障害性）を高める機能や，ユーザ認証などのセキュリティを高めるための機能が該当します。

性能
性能を重視したシステムの場合に使用するとよい機能です。
システムのパフォーマンスチューニングで使用する機能などが該当します。

運用・保守
効率の良い運用・保守をしたい場合に使用するとよい機能です。

拡張性
システム規模の拡大・縮小および構成の変更への柔軟な対応が必要な場合に使用するとよい機能です。

そのほか
そのほかの個別の目的に対応するための機能です。

また，WebコンテナおよびEJBコンテナが共通で使用できる機能には，Java EE標準機能とアプリケーションサーバが独自に拡張した機能があります。機能を選択するときには，必要に応じて，Java EE標準への準拠についても確認してください。

＜この節の構成＞

1.2.1　ネーミング管理の機能

1.2.2　リソース接続とトランザクション管理の機能

1.2.3　OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）の機能

1.2.4　アプリケーションサーバで使用するJPAの機能

1.2.5　Cosminexus JPAプロバイダの機能

1.2.6　Cosminexus JMSプロバイダの機能

1.2.7　JavaMailの機能

1.2.8　セキュリティ管理の機能

1.2.9　アプリケーションの属性管理

1.2.10　アノテーションの機能

1.2.11　J2EEアプリケーションの形式とデプロイの機能

1.2.12　コンテナ拡張ライブラリの機能

1.2.1　ネーミング管理の機能

ネーミング管理の機能を次の表に示します。システムの目的に合った機能を選択してください。機能の詳細については，参照先を確認してください。

表1-2　ネーミング管理の機能とシステムの目的の対応

機能
システムの目的
Java EE標準への準拠
参照先

信頼性
性能
運用・
保守
拡張性
そのほか
標準
拡張

JNDI名前空間へのオブジェクトのバインドとルックアップ
－
－
－
○
－
○
○
2.3

Enterprise BeanまたはJ2EEリソースへの別名付与（ユーザ指定名前空間機能）
－
－
－
○
－
－
○
2.4

ラウンドロビンポリシーによるCORBAネーミングサービスの検索
－
－
－
○
－
－
○
2.5

ネーミング管理機能でのキャッシング
－
○
－
－
－
－
○
2.6

ネーミングサービスの障害検知
○
－
－
－
－
－
○
2.7

CORBAネーミングサービスの切り替え
－
－
－
○
－
－
○
2.8

EJBホームオブジェクトリファレンスの再利用（EJBホームオブジェクトへの再接続機能）
－
－
－
○
－
○
○
2.9

（凡例）　○：対応する　　－：対応しない

注　「Java EE標準への準拠」の「標準」と「拡張」の両方に○が付いている機能は，Java EE標準の機能にアプリケーションサーバ独自の機能が拡張されていることを示します。「拡張」だけに○が付いている機能はアプリケーションサーバ独自の機能であることを示します。

1.2.2　リソース接続とトランザクション管理の機能

リソース接続とトランザクション管理の機能を次の表に示します。システムの目的に合った機能を選択してください。機能の詳細については，参照先を確認してください。

表1-3　リソース接続とトランザクション管理の機能とシステムの目的の対応

機能名
システムの目的
Java EE標準への準拠
参照先

信頼性
性能
運用・
保守
拡張性
そのほか
標準
拡張

コネクションプーリング
－
○
－
－
－
○
○
3.14.1

コネクションプーリングで使用できる機能
－
○
－
－
－
－
○
3.14.2

コネクションシェアリング・アソシエーション
－
○
－
－
－
○
－
3.14.3

ステートメントプーリング
－
○
－
－
－
－
○
3.14.4

ライトトランザクション
－
○
－
－
－
－
○
3.14.5

インプロセストランザクションサービス
－
○
－
－
－
○
－
3.14.6

DataSourceオブジェクトのキャッシング
－
○
－
－
－
－
○
3.14.7

DB Connectorのコンテナ管理でのサインオンの最適化
－
○
－
－
－
－
○
3.14.8

コネクションの障害検知
○
－
－
－
－
○※1
○※1
3.15.1

コネクション枯渇時のコネクション取得待ち
○
－
－
－
－
－
○
3.15.2

コネクションの取得リトライ
○
－
－
－
－
－
○
3.15.3

コネクションプールの情報表示
○
－
－
－
－
－
○
3.15.4

コネクションプールのクリア
○
－
－
－
－
－
○
3.15.5

コネクションの自動クローズ
○
－
－
－
－
○
－
3.15.6

コネクションスイーパ
○
－
－
－
－
－
○
3.15.7

トランザクションタイムアウトとステートメントキャンセル
○
－
－
－
－
○
－
3.15.8

トランザクションリカバリ
○
－
－
－
－
○
－
3.15.9

障害調査用SQLの出力
－
－
○
－
－
－
○
3.15.10

オブジェクトの自動クローズ
○
－
－
－
－
○
－
3.15.11

リソースアダプタのライフサイクル管理※2
－
－
－
－
－
○
－
3.16.1

リソースアダプタのワーク管理※2
－
－
－
－
－
○
－
3.16.2

メッセージインフロー※2
－
－
－
－
－
○
－
3.16.3

トランザクションインフロー※3
－
－
－
－
－
○
－
3.16.4

管理対象オブジェクトのルックアップ※2
－
－
－
－
－
○
－
3.16.5

コネクション定義の複数指定※2
－
－
－
－
－
○
－
3.16.6

コネクションプールのクラスタ化機能
（コネクションプールの一時停止・再開・状態表示）
○
－
－
－
－
－
○
3.17

リソースへの接続テスト
－
－
○
－
－
－
○
3.18

ファイアウォール環境での運用のための機能
－
－
○
－
－
－
○
3.19

（凡例）　○：対応する　　－：対応しない

注　「Java EE標準への準拠」の「標準」と「拡張」の両方に○が付いている機能は，Java EE標準の機能にアプリケーションサーバ独自の機能が拡張されていることを示します。「拡張」だけに○が付いている機能はアプリケーションサーバ独自の機能であることを示します。

注※1　Connector 1.0の場合は「拡張」です。Connector 1.5の場合は「Java EE標準」です。

注※2　Connector 1.5仕様に準拠したリソースアダプタを使用する場合だけ使用できる機能です。

注※3　Connector 1.5仕様に準拠したリソースアダプタのうち，TP1インバウンドアダプタを使用する場合だけ使用できる機能です。

1.2.3　OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）の機能

OpenTP1からアプリケーションサーバを呼び出す際のTP1インバウンド連携機能を次の表に示します。システムの目的に合った機能を選択してください。機能の詳細については，参照先を確認してください。

表1-4　 OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）とシステムの目的の対応

機能名
システムの目的
Java EE標準への準拠
参照先

信頼性
性能
運用・
保守
拡張性
そのほか
標準
拡張

コネクション管理機能
－
－
○
－
○
－
○
4.5

RPC通信機能
－
－
○
－
○
－
○
4.6

スケジュール機能
－
－
○
－
○
－
○
4.7

トランザクション連携機能
－
－
○
－
○
－
○
4.8

（凡例）　○：対応する　　－：対応しない

1.2.4　アプリケーションサーバで使用するJPAの機能

アプリケーションサーバで使用するJPAの機能を次の表に示します。システムの目的に合った機能を選択してください。機能の詳細については，参照先を確認してください。

表1-5　アプリケーションサーバで使用するJPAの機能とシステムの目的の対応

機能名
システムの目的
Java EE標準への準拠
参照先

信頼性
性能
運用・
保守
拡張性
そのほか
標準
拡張

JPA
○
－
○
－
－
○
○
5章

（凡例）　○：対応する　　－：対応しない

注　「Java EE標準への準拠」の「標準」と「拡張」の両方に○が付いている機能は，Java EE標準の機能にアプリケーションサーバ独自の機能が拡張されていることを示します。

1.2.5　Cosminexus JPAプロバイダの機能

Cosminexus JPAプロバイダの機能を次の表に示します。システムの目的に合った機能を選択してください。機能の詳細については，参照先を確認してください。

表1-6　Cosminexus JPAプロバイダの機能とシステムの目的の対応

機能名
システムの目的
Java EE標準への準拠
参照先

信頼性
性能
運用・
保守
拡張性
そのほか
標準
拡張

エンティティを使用したデータベースの更新
○
○
－
－
－
○
○
6.3

EntityManagerによるエンティティの操作
－
－
－
－
○
○
○
6.4

データベースとJavaオブジェクトとのマッピング情報の定義
－
－
－
－
○
○
○
6.5

エンティティのリレーションシップ
－
○
－
－
－
○
○
6.6

エンティティオブジェクトのキャッシュ機能
－
○
－
－
－
－
○
6.7

プライマリキー値の自動採番
－
－
－
－
○
○
○
6.8

クエリ言語によるデータベース操作
－
－
○
－
－
○
○
6.9

楽観的ロック
○
－
－
－
－
○
○
6.10

JPQLでの悲観的ロック
○
－
－
－
－
－
○
6.11

（凡例）　○：対応する　　－：対応しない

注　「Java EE標準への準拠」の「標準」と「拡張」の両方に○が付いている機能は，Java EE標準の機能にアプリケーションサーバ独自の機能が拡張されていることを示します。「拡張」だけに○が付いている機能はアプリケーションサーバ独自の機能であることを示します。

1.2.6　Cosminexus JMSプロバイダの機能

Cosminexus JMSプロバイダの機能を次の表に示します。システムの目的に合った機能を選択してください。機能の詳細については，参照先を確認してください。

表1-7　Cosminexus JMSプロバイダの機能とシステムの目的の対応

機能名
システムの目的
Java EE標準への準拠
参照先

信頼性
性能
運用・
保守
拡張性
そのほか
標準
拡張

JMS仕様に準拠したメッセージの送受信
－
－
－
－
○
－
－
7.4
7.5
7.6

メッセージ配信の高信頼性確保の仕組み
○
－
－
－
－
－
－
7.7

CJMSPブローカーの機能
－
－
○
－
－
－
－
7.8

CJMSPリソースアダプタの機能
－
－
－
－
○
－
－
7.9

Message-driven Beanの呼び出し
－
－
－
－
○
－
－
7.10

（凡例）　○：対応する　　－：対応しない

1.2.7　JavaMailの機能

JavaMailの機能を次の表に示します。システムの目的に合った機能を選択してください。機能の詳細については，参照先を確認してください。

表1-8　JavaMailの機能とシステムの目的の対応

機能名
システムの目的
Java EE標準への準拠
参照先

信頼性
性能
運用・
保守
拡張性
そのほか
標準
拡張

JavaMail
－
－
－
－
○
－
－
8章

（凡例）　○：対応する　　－：対応しない

1.2.8　セキュリティ管理の機能

セキュリティ管理の機能を次の表に示します。システムの目的に合った機能を選択してください。機能の詳細については，参照先を確認してください。

表1-9　セキュリティ管理の機能とシステムの目的の対応

機能名
システムの目的
Java EE標準への準拠
参照先

信頼性
性能
運用・
保守
拡張性
そのほか
標準
拡張

SSL使用による認証情報とデータの暗号化
○
－
－
－
－
○
○
9.2

ロールに基づくWebコンテナのユーザ認証
○
－
－
－
－
○
○
9.3

SecurityManagerによるWebコンテナの実行時の保護
○
－
－
－
－
○
○
9.4

セキュリティアイデンティティを使用した認証
○
－
－
－
－
－
○
9.5

（凡例）　○：対応する　　－：対応しない

注　「Java EE標準への準拠」の「標準」と「拡張」の両方に○が付いている機能は，Java EE標準の機能にアプリケーションサーバ独自の機能が拡張されていることを示します。「拡張」だけに○が付いている機能はアプリケーションサーバ独自の機能であることを示します。

1.2.9　アプリケーションの属性管理

アプリケーションの属性管理の機能を次の表に示します。システムの目的に合った機能を選択してください。機能の詳細については，参照先を確認してください。

表1-10　アプリケーションの属性管理の機能とシステムの目的の対応

機能名
システムの目的
Java EE標準への準拠
参照先

信頼性
性能
運用・
保守
拡張性
そのほか
標準
拡張

cosminexus.xmlを含むアプリケーション
－
－
－
○
－
－
○
10.3

DDの省略
－
－
－
○
－
○
○
10.4

（凡例）　○：対応する　　－：対応しない

注　「Java EE標準への準拠」の「標準」と「拡張」の両方に○が付いている機能は，Java EE標準の機能にアプリケーションサーバ独自の機能が拡張されていることを示します。「拡張」だけに○が付いている機能はアプリケーションサーバ独自の機能であることを示します。

1.2.10　アノテーションの機能

アノテーションの機能を次の表に示します。システムの目的に合った機能を選択してください。機能の詳細については，参照先を確認してください。

表1-11　アノテーションの機能とシステムの目的の対応

機能名
システムの目的
Java EE標準への準拠
参照先

信頼性
性能
運用・
保守
拡張性
そのほか
標準
拡張

アノテーション
－
－
－
○
－
○
○
11章

（凡例）　○：対応する　　－：対応しない

注　「Java EE標準への準拠」の「標準」と「拡張」の両方に○が付いている機能は，Java EE標準の機能にアプリケーションサーバ独自の機能が拡張されていることを示します。

1.2.11　J2EEアプリケーションの形式とデプロイの機能

J2EEアプリケーションの形式とデプロイの機能を次の表に示します。システムの目的に合った機能を選択してください。機能の詳細については，参照先を確認してください。

表1-12　J2EEアプリケーションの形式とデプロイの機能とシステムの目的の対応

機能名
システムの目的
Java EE標準への準拠
参照先

信頼性
性能
運用・
保守
拡張性
そのほか
標準
拡張

J2EEアプリケーションのデプロイとアンデプロイ
－
－
－
－
－
○
○
12.5

J2EEアプリケーションの入れ替え
－
－
－
－
－
○
－
12.6

J2EEアプリケーションのリデプロイ
－
－
○
－
－
－
○
12.7

J2EEアプリケーションの更新検知とリロード
－
－
○
－
－
－
○
12.8

（凡例）　○：対応する　　－：対応しない

注　「Java EE標準への準拠」の「標準」と「拡張」の両方に○が付いている機能は，Java EE標準の機能にアプリケーションサーバ独自の機能が拡張されていることを示します。「拡張」だけに○が付いている機能はアプリケーションサーバ独自の機能であることを示します。

1.2.12　コンテナ拡張ライブラリの機能

コンテナ拡張ライブラリの機能を次の表に示します。システムの目的に合った機能を選択してください。機能の詳細については，参照先を確認してください。

表1-13　コンテナ拡張ライブラリの機能とシステムの目的の対応

機能名
システムの目的
Java EE標準への準拠
参照先

信頼性
性能
運用・
保守
拡張性
そのほか
標準
拡張

コンテナ拡張ライブラリ機能
－
－
－
○
－
－
○
13.3

サーバ起動・停止フック機能
－
－
－
○
－
－
○
13.4

スマートエージェント経由でのCORBAオブジェクトの呼び出し
－
－
－
○
－
－
○
13.5

（凡例）　○：対応する　　－：対応しない

注　「拡張」だけに○が付いている機能はアプリケーションサーバ独自の機能であることを示します。

1.3　このマニュアルに記載している機能の説明

ここでは，このマニュアルで機能を説明するときの分類の意味と，分類を示す表の例について説明します。

＜この節の構成＞

1.3.1　分類の意味

1.3.2　分類を示す表の例

1.3.1　分類の意味

このマニュアルでは，各機能について，次の五つに分類して説明しています。マニュアルを参照する目的によって，必要な個所を選択して読むことができます。

解説
機能の解説です。機能の目的，特長，仕組みなどについて説明しています。機能の概要について知りたい場合にお読みください。

実装
コーディングの方法やDDの記載方法などについて説明しています。アプリケーションを開発する場合にお読みください。

設定
システム構築時に必要となるプロパティなどの設定方法について説明しています。システムを構築する場合にお読みください。

運用
運用方法の説明です。運用時の手順や使用するコマンドの実行例などについて説明しています。システムを運用する場合にお読みください。

注意事項
機能を使用するときの全般的な注意事項について説明しています。注意事項の説明は必ずお読みください。

1.3.2　分類を示す表の例

機能説明の分類については，表で説明しています。表のタイトルは，「この章の構成」または「この節の構成」となっています。

次に，機能説明の分類を示す表の例を示します。

機能説明の分類を示す表の例

表X-1　この章の構成（○○機能）

分類 | タイトル | 参照先
解説 | ○○機能とは | X.1
実装 | アプリケーションの実装 | X.2
DDおよびcosminexus.xml※での定義 | X.3
設定 | 実行環境での設定 | X.4
運用 | ○○機能を使用した運用 | X.5
注意事項 | ○○機能使用時の注意事項 | X.6

注※　cosminexus.xmlについては，「10.　アプリケーションの属性管理」を参照してください。

ポイント

cosminexus.xmlを含まないアプリケーションのプロパティ設定

cosminexus.xmlを含まないアプリケーションでは，実行環境へのインポート後にプロパティを設定，または変更します。設定済みのプロパティも実行環境で変更できます。

実行環境でのアプリケーションの設定は，サーバ管理コマンドおよび属性ファイルで実施します。サーバ管理コマンドおよび属性ファイルでのアプリケーションの設定については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「3.3.2　J2EEアプリケーションのプロパティの設定手順」を参照してください。

属性ファイルで指定するタグは，DDまたはcosminexus.xmlと対応しています。DDまたはcosminexus.xmlと属性ファイルのタグの対応については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「2.2　Cosminexusアプリケーション属性ファイル（cosminexus.xml）で指定する各属性の詳細」を参照してください。

なお，各属性ファイルで設定するプロパティは，アプリケーション統合属性ファイルでも設定できます。

1.4　アプリケーションサーバ 08-70での主な機能変更

この節では，アプリケーションサーバ 08-70での主な機能の変更について，変更目的ごとに説明します。

説明内容は次のとおりです。

アプリケーションサーバ 08-70で変更になった主な機能と，その概要を説明しています。機能の詳細については参照先の記述を確認してください。「参照先マニュアル」および「参照個所」には，その機能についての主な記載個所を記載しています。

「参照先マニュアル」に示したマニュアル名の「Cosminexus アプリケーションサーバ V8」は省略しています。

＜この節の構成＞

(1)　導入・構築の容易性強化

(2)　標準機能・既存機能への対応

(3)　信頼性の維持・向上

(4)　運用性の維持・向上

(5)　そのほかの目的

(1)　導入・構築の容易性強化

導入・構築の容易性強化を目的として変更した項目を次の表に示します。

表1-14　導入・構築の容易性強化を目的とした変更

項目
変更の概要
参照先マニュアル
参照個所

運用管理ポータル改善
運用管理ポータルの画面で，リソースアダプタの属性を定義するプロパティ（Connector属性ファイルの設定内容）の設定，および接続テストができるようになりました。また，運用管理ポータルの画面で，J2EEアプリケーション（earファイルおよびzipファイル）をManagement Serverにアップロードできるようになりました。
ファーストステップガイド
3.4.1

運用管理ポータル操作ガイド
－

page/tagディレクティブのimport属性暗黙インポート機能の追加
page/tagディレクティブのimport属性暗黙インポート機能を使用できるようになりました。
機能解説 基本・開発編(Webコンテナ)
2.3.7

仮想化環境でのJP1製品に対する環境設定の自動化対応
仮想サーバへのアプリケーションサーバ構築時に，仮想サーバに対するJP1製品の環境設定を，フックスクリプトで自動的に設定できるようになりました。
仮想化システム構築・運用ガイド
7.7.2

統合ユーザ管理機能の改善
ユーザ情報リポジトリでデータベースを使用する場合に，データベース製品のJDBCドライバを使用して，データベースに接続できるようになりました。Cosminexus DABroker LibraryのJDBCドライバによるデータベース接続はサポート外になりました。
簡易構築定義ファイルおよび運用管理ポータルの画面で，統合ユーザ管理機能に関する設定ができるようになりました。
また，Active Directoryの場合，DNで日本語などの2バイト文字に対応しました。
機能解説 拡張編
10章

運用管理ポータル操作ガイド
3.5，10.9.1

リファレンス 定義編(サーバ定義)
14.3

Hitachi Web Server設定項目の拡充
簡易構築定義ファイルおよび運用管理ポータルの画面で，Hitachi Web Serverの動作環境を定義するディレクティブ（httpsd.conf（Hitachi Web Server定義ファイル）の設定内容）を直接設定できるようになりました。
システム構築・運用ガイド
8.4.3

運用管理ポータル操作ガイド
10.10.1

リファレンス 定義編(サーバ定義)
4.13

（凡例）－：マニュアル全体を参照する

(2)　標準機能・既存機能への対応

標準機能・既存機能への対応を目的として変更した項目を次の表に示します。

表1-15　標準機能・既存機能への対応を目的とした変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
ejb-jar.xmlの指定項目の追加 | ejb-jar.xmlに，クラスレベルインターセプタおよびメソッドレベルインターセプタを指定できるようになりました。 | 機能解説 基本・開発編(EJBコンテナ) | 2.15
パラレルコピーガーベージコレクションへの対応 | パラレルコピーガーベージコレクションを選択できるようになりました。 | リファレンス 定義編(サーバ定義) | 19.5
Connector 1.5仕様に準拠したInboundリソースアダプタのグローバルトランザクションへの対応 | Connector 1.5仕様に準拠したリソースアダプタでTransacted Deliveryを使用できるようにしました。これによって，Message-driven Beanを呼び出すEISがグローバルトランザクションに参加できるようになりました。 | このマニュアル | 3.16.3
TP1インバウンドアダプタのMHPへの対応 | TP1インバウンドアダプタを使用してアプリケーションサーバを呼び出すOpenTP1のクライアントとして，MHPを使用できるようになりました。 | このマニュアル | 4章
cjrarupdateコマンドのFTPインバウンドアダプタへの対応 | cjrarupdateコマンドでバージョンアップできるリソースアダプタにFTPインバウンドアダプタを追加しました。 | リファレンス コマンド編 | 2.2

(3)　信頼性の維持・向上

信頼性の維持・向上を目的として変更した項目を次の表に示します。

表1-16　信頼性の維持・向上を目的とした変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
データベースセッションフェイルオーバ機能の改善 | 性能を重視するシステムで，グローバルセッション情報を格納したデータベースのロックを取得しないモードを選択できるようになりました。また，データベースを更新しない，参照専用のリクエストを定義できるようになりました。 | 機能解説 拡張編 | 6章
OutOfMemoryハンドリング機能の対象となる処理の拡大 | OutOfMemoryハンドリング機能の対象となる処理を追加しました。 | 機能解説 保守／移行／互換編 | 2.5.6
リファレンス 定義編(サーバ定義) | 19.2
HTTPセッションで利用するExplicitヒープの省メモリ化機能の追加 | HTTPセッションで利用するExplicitヒープのメモリ使用量を抑止する機能を追加しました。 | 機能解説 拡張編 | 8.9

(4)　運用性の維持・向上

運用性の維持・向上を目的として変更した項目を次の表に示します。

表1-17　運用性の維持・向上を目的とした変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
仮想化環境でのJP1製品を使用したユーザ認証への対応（クラウド運用対応） | JP1連携時に，JP1製品の認証サーバを利用して，仮想サーバマネージャを使用するユーザを管理・認証できるようになりました。 | 仮想化システム構築・運用ガイド | 1.2.2，3章，4章，5章，6章，7.8

(5)　そのほかの目的

そのほかの目的で変更した項目を次の表に示します。

表1-18　そのほかの目的による変更

項目
変更の概要
参照先マニュアル
参照個所

負荷分散機へのAPI（RESTアーキテクチャ）を使用した直接接続の対応
負荷分散機への接続方法として，API（RESTアーキテクチャ）を使用した直接接続に対応しました。
また，使用できる負荷分散機の種類にACOS（AX2500）が追加になりました。
システム構築・運用ガイド
4.3.1

仮想化システム構築・運用ガイド
2.1

リファレンス 定義編(サーバ定義)
4.5

snapshotログ収集時のタイムアウトへの対応と収集対象の改善
snapshotログの収集が指定した時間で終了（タイムアウト）できるようになりました。一次送付資料として収集される内容が変更になりました。
機能解説 保守／移行／互換編
付録A

2.　ネーミング管理

この章では，ネーミング管理の機能について説明します。ネーミング管理は，J2EEサービスで提供されている機能の一つです。ネーミング管理機能を使用して，Enterprise Bean参照またはリソース参照のための名前解決を実現します。

＜この章の構成＞

2.1　この章の構成

2.2　ネーミング管理の概要

2.3　JNDI名前空間へのオブジェクトのバインドとルックアップ

2.4　Enterprise BeanまたはJ2EEリソースへの別名付与（ユーザ指定名前空間機能）

2.5　ラウンドロビンポリシーによるCORBAネーミングサービスの検索

2.6　ネーミング管理機能でのキャッシング

2.7　ネーミングサービスの障害検知

2.8　CORBAネーミングサービスの切り替え

2.9　EJBホームオブジェクトリファレンスの再利用（EJBホームオブジェクトへの再接続機能）

2.1　この章の構成

ネーミング管理は，J2EEサービスで提供されている機能の一つです。J2EEサービスは，J2EEコンテナの部品機能として利用される機能です。

ネーミング管理の機能と参照先を次の表に示します。

表2-1　ネーミング管理の機能と参照先

機能 | 参照先
ネーミング管理の概要 | 2.2
JNDI名前空間へのオブジェクトのバインドとルックアップ※ | 2.3
Enterprise BeanまたはJ2EEリソースへの別名付与（ユーザ指定名前空間機能） | 2.4
ラウンドロビンポリシーによるCORBAネーミングサービスの検索 | 2.5
ネーミング管理機能でのキャッシング | 2.6
ネーミングサービスの障害検知 | 2.7
CORBAネーミングサービスの切り替え | 2.8
EJBホームオブジェクトリファレンスの再利用（EJBホームオブジェクトへの再接続機能） | 2.9

注※　ルックアップには何種類かの方法があります。ルックアップ名称および方法については，「2.3.1　ルックアップで使用する名称の種類」を参照してください。

2.2　ネーミング管理の概要

この節では，ネーミング管理の機能，およびネーミング管理で使用するネーミングサービスについて説明します。

＜この節の構成＞

2.2.1　ネーミング管理の機能

2.2.2　ネーミングサービス

2.2.1　ネーミング管理の機能

ネーミング管理では，オブジェクト（Enterprise Beanに対応するEJBホームオブジェクト，ビジネスインタフェースのリファレンスおよびJ2EEリソース）の名前と格納場所を管理しています。ネーミング管理の機能を使用することで，EJBクライアントは，呼び出すEnterprise Beanまたはリソースの格納場所を知らなくても，名前から必要なオブジェクトを利用できるようになります。

また，Connector 1.5仕様に準拠したリソースアダプタを使用する場合，管理対象オブジェクトもネーミング管理で管理されています。管理対象オブジェクトは，J2EEアプリケーションの中からメッセージの送信および同期受信をするときに使用するオブジェクトです。管理対象オブジェクトについては，「3.16.5　管理対象オブジェクトのルックアップ」を参照してください。

ネーミング管理機能のJNDIでは，CORBAオブジェクトリファレンス以外のオブジェクト（RMI-IIOPのリモートオブジェクトやJDBCデータソースなどのオブジェクト）を次のように扱います。

CORBAオブジェクトリファレンス以外の登録は，対象のオブジェクトをCORBAオブジェクトに変換し，CORBAオブジェクトリファレンスをCORBAネーミングサービスへ登録することで実現しています。

CORBAオブジェクト以外のオブジェクトの検索は，CORBAオブジェクトリファレンスを検索し，CORBAオブジェクトから逆変換して元のオブジェクトを取得することで実現しています。

なお，アプリケーションサーバで提供するネーミング管理の機能には，J2EEで規定された機能にアプリケーションサーバ独自の機能を拡張したものと，アプリケーションサーバ独自の機能として提供しているものがあります。アプリケーションサーバ独自の機能かどうかについては，「1.　アプリケーションサーバの機能」を参照してください。

アプリケーションサーバが提供するネーミング管理の機能と対象になるオブジェクトの関係を次の表に示します。

表2-2　アプリケーションサーバが提供するネーミング管理の機能と対象になるオブジェクトの関係

機能 | Enterprise Bean | J2EEリソース
EJBホームオブジェクト | ビジネスインタフェース
JNDI名前空間へのオブジェクトのバインドとルックアップ | ○ | ○ | 　○※
Enterprise BeanまたはJ2EEリソースへの別名付与（ユーザ指定名前空間機能） | ○ | ○ | ○
ラウンドロビンポリシーによるCORBAネーミングサービスの検索 | ○ | ○ | ×
ネーミング管理機能でのオブジェクトのキャッシング | ○ | × | ×
CORBAネーミングサービスの切り替え | ○ | × | ×

（凡例）○：使用できる　×：使用できない

注※　自動的にバインドされる名称でのルックアップはできません。

注意

Webアプリケーションでカスタムエラーページを設定している場合，設定されたエラーページからJNDIを利用できません。

2.2.2　ネーミングサービス

ネーミング管理機能を使用する場合，オブジェクトの名前と格納場所は，ネーミングサービスによって管理されます。

アプリケーションサーバでは，ネーミング管理の機能として，CORBAネーミングサービスを利用したJNDIをサポートしています。オブジェクトの登録，削除，または検索などのJNDIのインタフェースが呼び出されたときに，対応するCORBAネーミングサービスのインタフェースを呼び出します。したがって，ネーミング管理機能を利用するためには，CORBAネーミングサービスへの接続情報としてプロトコル，ホスト名，およびポート番号を設定する必要があります。

参考

CORBAネーミングサービスはJ2EEサーバのインプロセスで起動できます。インプロセスで起動することで，個別の起動・終了が不要になり，運用性が向上します。

2.3　JNDI名前空間へのオブジェクトのバインドとルックアップ

ルックアップの対象になるオブジェクトは，JNDI名前空間の名前と関連づけて管理されます。

J2EEサーバ内で実行するアプリケーションでは，利用したいリソースマネジャや呼び出したいEnterprise Beanなどのオブジェクトを参照するために，JNDIの名前空間で検索（ルックアップ）を実行します。

この節では，ルックアップに使用する名称の種類，バインドされる名称の規則，およびルックアップの仕組みについて説明します。また，JNDI名前空間の確認方法についても説明します。

この節の構成を次の表に示します。

表2-3　この節の構成（JNDI名前空間へのオブジェクトのバインドとルックアップ）

分類 | タイトル | 参照先
解説 | ルックアップで使用する名称の種類 | 2.3.1
EJBのリファレンスが自動的にバインドされる名称 | 2.3.2
JNDI名前空間のマッピングとルックアップ | 2.3.3
JNDI名前空間の確認方法 | 2.3.4
実装 | cosminexus.xmlでの定義 | 2.3.5
設定 | 実行環境での設定 | 2.3.6

注　「運用」について，この機能固有の説明はありません。

＜この節の構成＞

2.3.1　ルックアップで使用する名称の種類

2.3.2　EJBのリファレンスが自動的にバインドされる名称

2.3.3　JNDI名前空間のマッピングとルックアップ

2.3.4　JNDI名前空間の確認方法

2.3.5　cosminexus.xmlでの定義

2.3.6　実行環境での設定

2.3.1　ルックアップで使用する名称の種類

アプリケーションサーバでは，次に示す3種類の名称を使用したルックアップができます。

自動的にバインドされる名称でのルックアップ
Enterprise Beanをルックアップするときに使用できます。

java:comp/envでのルックアップ
Enterprise BeanまたはJ2EEリソースをルックアップするときに使用できます。

ユーザ指定名前空間機能を利用して付与した名称でのルックアップ
Enterprise BeanまたはJ2EEリソースをルックアップするときに使用できます。

EJBクライアントの形態ごとに，利用できるルックアップ方法，および推奨するルックアップ方法を次の表に示します。

表2-4　ルックアップ方法の種類

EJBクライアントの形態 | ルックアップの方法
自動的にバインドされる名称でのルックアップ | java:comp/envを使用した名称でのルックアップ | ユーザ指定名前空間機能を利用して付与した別名でのルックアップ
EJBクライアントアプリケーション | ◎ | × | ○
JSP，サーブレット | ○ | ◎ | ○
EJB | ○ | ◎ | ○

（凡例）　◎：利用を推奨する　○：利用できる　×：利用できない

それぞれのルックアップ名称とその名称を使用したルックアップ方法について説明します。

＜この項の構成＞

(1)　自動的にバインドされる名称でのルックアップ

(2)　java:comp/envを使用した名称でのルックアップ

(3)　ユーザ指定名前空間機能を利用して付与した別名でのルックアップ

(1)　自動的にバインドされる名称でのルックアップ

アプリケーションサーバでのJ2EEアプリケーションのデプロイ時に，オブジェクトリファレンスに自動的に付与される名称を指定してルックアップする方法です。

J2EEアプリケーションのデプロイ時に，Enterprise Beanに対応するEJBホームオブジェクトリファレンス，およびビジネスインタフェースのリファレンスは，自動的にJNDIの名前にバインドされます。バインドされる名称には，J2EEアプリケーションのサーバ名やアプリケーション名が付与されるので，名前空間の衝突を回避できます。

自動的にバインドされる名称については，「2.3.2　EJBのリファレンスが自動的にバインドされる名称」を参照してください。

(2)　java:comp/envを使用した名称でのルックアップ

Java EEで定義されているjava:comp/envを使用して，ルックアップで指定した名称の名前解決をする方法です。java:comp/envは，Java EEで定義されている，名前空間のコンテキストルートです。なお，java:comp/envで指定する参照名と，実際の名称間のリンクの対応は，DDによって定義します。これによって，デプロイ時に参照名と実際の名称間のリンクを解決します。

(3)　ユーザ指定名前空間機能を利用して付与した別名でのルックアップ

アプリケーションサーバの機能で，Enterprise BeanまたはJ2EEリソースに別名を定義する方法です。ユーザ指定名前空間機能といいます。

Enterprise Beanの場合，JNDIの名前へのバインドと合わせて，EJBホームオブジェクトリファレンスまたはビジネスインタフェースのリファレンスの別名を登録できます。また，J2EEリソース（リソースアダプタ，メールコンフィグレーション，JavaBeansリソース）に対しても，別名を登録できます。

別名を登録することで，ユーザが指定した任意の名称でEnterprise BeanおよびJ2EEリソースをルックアップできるようになります。

参考

Java EEの仕様では，java:comp/envを使用した名称でのルックアップが推奨されています。

Enterprise BeanまたはJ2EEリソースへの別名付与の詳細については，「2.4　Enterprise BeanまたはJ2EEリソースへの別名付与（ユーザ指定名前空間機能）」を参照してください。

2.3.2　EJBのリファレンスが自動的にバインドされる名称

J2EEアプリケーションをデプロイすると，EJBホームオブジェクトリファレンスおよびビジネスインタフェースのリファレンスは，決められた名称で自動的にJNDIの名前にバインドされます。ルックアップ時には，バインドされた名前を使用します。

ここでは，EJBホームオブジェクトリファレンスおよびビジネスインタフェースのリファレンスが自動的にバインドされる名称について説明します。

なお，JNDI名前空間のマッピングの仕組みと使い方については，「2.3.3　JNDI名前空間のマッピングとルックアップ」で説明します。

＜この項の構成＞

(1)　EJBホームオブジェクトリファレンスが自動的にバインドされる名称

(2)　ビジネスインタフェースのリファレンスが自動的にバインドされる名称

(3)　テストモードで実行されているEnterprise Beanのルックアップをする場合の名称の指定方法

(1)　EJBホームオブジェクトリファレンスが自動的にバインドされる名称

J2EEアプリケーションを開始（デプロイ）したとき，Enterprise BeanのEJBホームオブジェクトリファレンスは，次に示す名称で，JNDIの名前にバインドされます。

HITACHI_EJB/SERVERS/<サーバ名称>/EJB/<J2EE APP名称>/<Enterprise Bean名称>

<サーバ名称>

J2EEサーバのサーバ名称

<J2EE APP名称>

J2EEアプリケーションのルックアップ名称

<Enterprise Bean名称>

Enterprise Beanのルックアップ名称

J2EEアプリケーション間のEnterprise Beanの呼び出しや，EJBクライアントアプリケーションからのEnterprise Beanの呼び出しのとき，クライアントはバインドされたJNDIの名前でEJBホームオブジェクトリファレンスをルックアップします。

次に示す図では，下記の条件でJ2EEアプリケーションを開始したとき，"CartHome"インタフェースを実装したEJBホームオブジェクトが生成され，そのリファレンスがJNDIの名前"HITACHI_EJB/SERVERS/MyServer/EJB/CartApp/CartEB"にバインドされることを示しています。

条件

Enterprise Bean："CartBean"

リモートインタフェースの名称："Cart"

ホームインタフェース："CartHome"

サーバ名称："MyServer"

J2EEアプリケーションのルックアップ名称："CartApp"

Enterprise Beanのルックアップ名称："CartEB"

図2-1　EJBホームオブジェクトリファレンスのJNDI名前空間へのバインド

次に，自動的にバインドされる名称を利用してEJBホームオブジェクトのリファレンスをルックアップする場合のルックアップとオブジェクトの取得の流れを示します。

図2-2　自動的にバインドされる名称を利用したルックアップとオブジェクトの取得の流れ

(2)　ビジネスインタフェースのリファレンスが自動的にバインドされる名称

J2EEアプリケーションを開始（デプロイ）したとき，ビジネスインタフェースのリファレンスは，次に示す名称でJNDIの名前にバインドされます。

HITACHI_EJB/SERVERS/<サーバ名称>/EJBBI/<J2EE APP名称>/<Enterprise Bean名称>

<サーバ名称>

J2EEサーバのサーバ名称

<J2EE APP名称>

J2EEアプリケーションのルックアップ名称

<Enterprise Bean名称>

Enterprise Beanのルックアップ名称

J2EEアプリケーション間のEnterprise Beanの呼び出しや，EJBクライアントアプリケーションからのEnterprise Beanの呼び出しのとき，クライアントはバインドされたJNDIの名前でビジネスインタフェースのリファレンスをルックアップします。

(3)　テストモードで実行されているEnterprise Beanのルックアップをする場合の名称の指定方法

J2EEアプリケーション外からテストモードで実行されているEnterprise Beanをルックアップする場合，テストモード用の名前空間を意識してルックアップする必要があります。通常モードで実行されるEnterprise Beanを「HITACHI_EJB/」で始まる文字列でルックアップするのに対して，同じEnterprise Beanがテストモードで実行される場合は「$HITACHI_TEST/HITACHI_EJB/」で始まる文字列でルックアップします。

テストモードでのアプリケーションの動作については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 運用／監視／連携編」の「5.7　J2EEアプリケーションのテスト機能」を参照してください。

2.3.3　JNDI名前空間のマッピングとルックアップ

ここでは，JNDI名前空間のマッピングの仕組みと，ルックアップでの指定する名称とJNDI名前空間およびDDの関係について説明します。

＜この項の構成＞

(1)　Enterprise Beanを参照する仕組みと使い方（ejb-ref）

(2)　リソースを参照する仕組みと使い方（resource-ref）

(1)　Enterprise Beanを参照する仕組みと使い方（ejb-ref）

J2EEサーバ内で実行するアプリケーションでは，Enterprise Beanを呼び出すために，Enterprise Bean参照の名前解決が必要です。正確には，Enterprise Beanに対応するEJBホームインタフェース，EJBローカルホームインタフェース，ビジネスインタフェースなどの名前解決をします。

EJBホームインタフェース，またはビジネスインタフェースの名前解決をするためには，次の2種類の作業が必要です。

参照側アプリケーションの作成時の作業
アプリケーションの作成時に参照用の名称を決め，Enterprise Beanやサーブレットなどのプログラム内でのlookupの引数に，その参照用の名称を指定します。また，java:comp/envを使用する場合は，DDの<ejb-ref>に，決めた参照用の名称を記載します。

参照側アプリケーションのデプロイ時の作業
作成したアプリケーションをJ2EEサーバ上にデプロイするときに，Enterprise Beanをカスタマイズして，参照用の名称と実際の名称をlinked-toで結び付けます。
この操作は，サーバ管理コマンドを使用して実行できます。

マッピングの仕組みは，参照側のアプリケーションと参照先のアプリケーションが同じJ2EEアプリケーションか，別のJ2EEアプリケーションかによって異なります。次に，EJBホームインタフェースの名前解決の例として，別のJ2EEアプリケーションのEnterprise Beanを参照する場合と，同じJ2EEアプリケーション内のEnterprise Beanを参照する場合の例を示します。

(a)　別のJ2EEアプリケーションのEnterprise Beanを参照する場合

J2EEアプリケーションから別のJ2EEアプリケーションに含まれるEnterprise Beanを参照する例を，次の図に示します。

図2-3　J2EEアプリケーションから別のJ2EEアプリケーションに含まれるEnterprise Beanを参照する例

java:comp/envを使用する場合，参照側のプログラムのlookupに指定するjava:comp/env下の参照名と実際にJNDI名前空間に登録されているlookup名は，デフォルトで対応づけられます（linked-to）。なお，lookup名をJNDI名前空間に登録されている名称と異なる名称にする場合は，サーバ管理コマンドでカスタマイズする必要があります。図の場合は，PetShopEBをejb/PetShopBeanとして呼び出すようにカスタマイズします。

ユーザ指定名前空間機能を使用する場合，参照側のプログラムのlookupに別名を指定できます。<ejb-ref>の定義は不要です。

(b)　同じJ2EEアプリケーション内のEnterprise Beanを参照する場合

J2EEアプリケーションから同じJ2EEアプリケーションに含まれるEnterprise Beanを参照する例を，次の図に示します。

図2-4　同じJ2EEアプリケーションに含まれるEnterprise Beanを参照する例

同じアプリケーション内のEnterprise Beanを呼び出す場合は，lookup名による参照の解決ではなく，<ejb-ref-name>とejb-nameを結び付けて解決します（linked-to）。なお，同一のJ2EEアプリケーションの場合，参照に必要な情報はアプリケーション開発時に判明しているので，DDの<ejb-link>タグに直接ejb-nameを書き込んでおくこともできます。

(2)　リソースを参照する仕組みと使い方（resource-ref）

J2EEサーバ内で実行するアプリケーションでリソースアダプタを利用する場合，lookupによるリソース参照の名前解決が必要です。正確には，リソースマネジャへのコネクションを作成するファクトリの名前解決をします。

リソースマネジャへのコネクションを作成するファクトリの名前解決をするためには，次の2種類の作業が必要です。

参照側アプリケーションの作成時の作業
アプリケーションの作成時に参照用の名称を決め，Enterprise Beanやサーブレットなどのプログラム内でのlookupの引数に，その参照用の名称を指定します。また，DDの<resource-ref>に，決めた参照用の名称を記載します。

参照側アプリケーションのデプロイ時の作業
作成したアプリケーションをJ2EEサーバ上にデプロイするときに，リソースをカスタマイズして，参照用の名称とJ2EEサーバ上に登録済みのリソースをlinked-toで結び付けます。
この操作は，サーバ管理コマンドを使用して実行できます。

次にDB Connector経由でデータベースにアクセスする場合の例を示します。

図2-5　DB Connector経由でデータベースにアクセスする場合の例

この例では，リソースの参照名称とリソースの表示名称を結び付けています。

2.3.4　JNDI名前空間の確認方法

コマンドを使用して，CORBAネーミングサービスで認識されている名称を表示して確認できます。なお，J2EEリソースの別名やEJBローカルホームオブジェクトリファレンスの登録情報は確認できません。使用するコマンドは，nsutilコマンドです。nsutilコマンドの使用方法，使用条件などについては，マニュアル「Borland(R) Enterprise Server VisiBroker(R) デベロッパーズガイド」を参照してください。

JNDI名前空間の「HITACHI_EJB/SERVERS/MyServer/EJB」の下位の一覧を表示する場合の表示例を次に示します。

# nsutil -VBJprop ORBInitRef=NameService=corbaname::localhost:900 list HITACHI_EJB/SERVERS/MyServer/EJB
Bindings in HITACHI_EJB/SERVERS/MyServer/EJB
Context: App1
Context: App2
Context: App3

2.3.5　cosminexus.xmlでの定義

ネーミング管理の機能の定義は，cosminexus.xmlの<ejb-jar>タグ内に指定します。cosminexus.xmlでのネーミング管理のための定義について次の表に示します。

表2-5　cosminexus.xmlでのネーミング管理の機能の定義

指定するタグ
設定内容

<session>－<lookup-name>タグ
<entity>－<lookup-name>タグ
ルックアップ名称を指定します。

2.3.6　実行環境での設定

ネーミング管理機能を使用する場合，J2EEサーバの設定，サーバ管理コマンドのカスタマイズ，J2EEアプリケーションの設定が必要です。

＜この項の構成＞

(1)　J2EEサーバの設定

(2)　サーバ管理コマンドのカスタマイズ

(3)　J2EEアプリケーションの設定

(1)　J2EEサーバの設定

J2EEサーバの設定は，簡易構築定義ファイルで実施します。ネーミング管理機能の定義は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。簡易構築定義ファイルでのネーミング管理機能の定義について次の表に示します。

表2-6　簡易構築定義ファイルでのネーミング管理の機能の定義

項目 | 指定するパラメタ | 設定内容
基本設定 | ejbserver.naming.host※ | CORBAネーミングサービスのホスト名を指定します。
ejbserver.naming.port※ | CORBAネーミングサービスのポート番号を指定します。
ejbserver.naming.startupMode | CORBAネーミングサービスの起動モードを指定します。
ネーミングサービスの通信タイムアウト | ejbserver.jndi.request.timeout | ネーミングサービスとの通信タイムアウト時間を指定します。

注※　デフォルトの設定では，J2EEサーバはホスト名「localhost」，ポート番号「900」のCORBAネーミングサービスをインプロセスで自動起動して使用します。設定を変更したい場合に変更してください。

(2)　サーバ管理コマンドのカスタマイズ

サーバ管理コマンドの動作設定をカスタマイズできます。ここでは，サーバ管理コマンドが使用するCORBAネーミングサービスの設定について説明します。

ネーミング管理の機能を使用するためのサーバ管理コマンドのカスタマイズは，usrconf.properties（サーバ管理コマンド用システムプロパティファイル）で設定します。設定内容を次に示します。なお，キーの詳細，およびここで説明していないキーについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「5.　サーバ管理コマンドで使用するファイル」を参照してください。

表2-7　ネーミング管理機能を使用するためのサーバ管理コマンドのカスタマイズ

項目 | 指定するキー | 設定内容
CORBAネーミングサービスが動作するホスト名 | ejbserver.naming.host | サーバ管理コマンドが使用するCORBAネーミングサービスが動作するホストを指定します。
CORBAネーミングサービスのポート番号 | ejbserver.naming.port | サーバ管理コマンドが使用するCORBAネーミングサービスのポート番号を指定します。
CORBAネーミングサービスへのアクセスプロトコル | ejbserver.naming.protocol | サーバ管理コマンドが使用するCORBAネーミングサービスへのアクセスプロトコルを指定します。

(3)　J2EEアプリケーションの設定

実行環境でのJ2EEアプリケーションの設定は，サーバ管理コマンドおよび属性ファイルで実施します。ネーミング管理の機能の定義には，Session Bean属性ファイルまたはEntity Bean属性ファイルを使用します。

これらの属性ファイルで指定するタグは，cosminexus.xmlと対応しています。cosminexus.xmlでの定義については，「2.3.5　cosminexus.xmlでの定義」を参照してください。

2.4　Enterprise BeanまたはJ2EEリソースへの別名付与（ユーザ指定名前空間機能）

Enterprise BeanまたはJ2EEリソースに対して，ユーザが別の名称を付けてJNDI名前空間に登録する機能を，ユーザ指定名前空間機能といいます。この機能によって，Enterprise BeanまたはJ2EEリソースを，設定した任意の名称でルックアップできるようになります。

なお，別名を付与するためには，サーバ管理コマンドの動作設定のカスタマイズが必要です。設定方法については，「2.4.7　実行環境での設定」を参照してください。

注意

Java EEの仕様では，java:comp/envを利用した名称でのルックアップが推奨されています。

この節の構成を次の表に示します。

表2-8　この節の構成（ユーザ指定名前空間機能）

分類 | タイトル | 参照先
解説 | 別名を付けられる対象 | 2.4.1
別名の付与規則 | 2.4.2
別名が登録または削除されるタイミング | 2.4.3
クライアントからの検索 | 2.4.4
実装 | Enterprise Beanの別名の設定 | 2.4.5
J2EEリソースの別名の設定 | 2.4.6
設定 | 実行環境での設定 | 2.4.7
注意事項 | ユーザ指定名前空間機能を使用する場合の注意事項 | 2.4.8

注　「運用」について，この機能固有の説明はありません。

＜この節の構成＞

2.4.1　別名を付けられる対象

2.4.2　別名の付与規則

2.4.3　別名が登録または削除されるタイミング

2.4.4　クライアントからの検索

2.4.5　Enterprise Beanの別名の設定

2.4.6　J2EEリソースの別名の設定

2.4.7　実行環境での設定

2.4.8　ユーザ指定名前空間機能を使用する場合の注意事項

2.4.1　別名を付けられる対象

ここでは，別名を付けられる対象について説明します。

別名は，Enterprise BeanまたはJ2EEリソースに付けられます。

＜この項の構成＞

(1)　Enterprise Beanに対する別名

(2)　J2EEリソースに対する別名

(1)　Enterprise Beanに対する別名

別名を付けられるのは，次のインタフェースを持つEnterprise Beanです。

リモートホームインタフェース

ローカルホームインタフェース

リモートビジネスインタフェース

ローカルビジネスインタフェース

なお，以降，リモートホームインタフェースとリモートビジネスインタフェースをあわせて，リモートインタフェースといいます。また，ローカルホームインタフェースとローカルビジネスインタフェースをあわせてローカルインタフェースといいます。

参考

リモートインタフェースとローカルインタフェースの別名は，異なる属性として設定します。詳細は，「2.4.5　Enterprise Beanの別名の設定」を参照してください。

(2)　J2EEリソースに対する別名

別名を付与できるのは，次の表に示すJ2EEリソースです。

表2-9　別名を付与できるJ2EEリソース

J2EEリソースの種別 | 別名付与の可否
リソースアダプタ | DB Connector | ○※1
DB Connector for Cosminexus RM | ○
Cosminexus RM | ○※2
uCosminexus TP1 Connector | ○
TP1/Message Queue - Access | ○※2
そのほかのリソースアダプタ | ○※3
メールコンフィグレーション | ○
JavaBeansリソース | ○

（凡例）　○：別名を付けられる

注※1　コネクションプールのクラスタ化機能を使用する場合，メンバリソースアダプタには別名を付けられません。

注※2　属性ファイルの<resource-env-ref>に指定するjavax.jms.ConnectionFactoryオブジェクトに別名を付けられます。<resource-env-ref>に指定するjavax.jms.Destinationオブジェクトには別名を付けられません。

注※3　Connector 1.5仕様に準拠するリソースアダプタの場合，管理対象オブジェクトに別名は付与できません。

2.4.2　別名の付与規則

ここでは，Enterprise BeanおよびJ2EEリソースに別名を設定する場合の付与規則について説明します。

＜この項の構成＞

(1)　指定できる名称

(2)　別名の重複

(1)　指定できる名称

別名に指定できる文字，および指定する場合の制約について説明します。

(a)　別名に指定できる文字

別名には，次の文字を使用した名称を指定できます。

英数字（A～Z，a～z，0～9）

アンダースコア（_）

スラント（/）

ピリオド（.）

ハイフン（-）

ただし，スラントは，区切り文字として使用する場合だけ，名前に使用できます。

(b)　別名を指定するときの制約

次に示す名前は，別名として指定できません。指定した場合，J2EEアプリケーションまたはJ2EEリソースを開始できません。

名前の先頭または名前の末尾に，スラント（/）またはピリオド（.）を指定した名前。

スラント（/）だけ，またはピリオド（.）だけの名前。

スラント（/）が連続している名前。

スラント（/）とピリオド（.）が連続している名前。

「HITACHI_EJB」で始まる名前（大文字・小文字を区別する）。

文字列長が255バイトよりも長い名前。

このほか，J2EEリソースの場合，同じ名称が指定されたときには，あとから指定されている定義が有効になります。

(2)　別名の重複

Enterprise BeanおよびJ2EEリソースに別名を付ける場合の別名の重複可否を次の表に示します。

表2-10　Enterprise BeanおよびJ2EEリソースの別名の重複可否

別名を付ける対象 | リモートインタフェースを持つEnterprise Bean | ローカルインタフェースを持つEnterprise Bean | J2EEアプリケーションに含まれるリソースアダプタ | J2EEリソース※1
リモートインタフェースを持つEnterprise Bean | × | ○※2 | × | ×
ローカルインタフェースを持つEnterprise Bean | ○※2 | △ | △ | ×
J2EEアプリケーションに含まれるリソースアダプタ | × | △ | △ | ×
J2EEリソース※1 | × | × | × | ×

（凡例）

○：重複できる

△：J2EEアプリケーションが異なる場合は重複できる

×：重複できない

注※1　J2EEアプリケーションに含まれるリソースアダプタを除きます。

注※2　ローカル呼び出し最適化機能を使用するかどうかに関係なく重複できます。

なお，重複できない組み合わせの場合，名称が完全に一致していなくても指定できないことがあります。

例を使用して説明します。

例

ネーミング管理機能では，CORBAネーミングサービスに登録されるオブジェクトを名前で管理しています。オブジェクトに付与された名前は「/」を階層構造の区切りとして解析し，ツリー構造で管理されます。ツリーのなかで，子ノードを持つノードでは，そのノードの下に新しくオブジェクトを登録できます。

次の図の，ノードA，B，C，Fは子ノードを持つノードです。このため，これらのノードの下には新しくオブジェクトを登録できます。

図2-6　名称が完全に一致していなくても指定できない例

この状態で，別名「A/B/D」がすでに使用されている場合は，別名「A/B/I」を指定できます。

しかし，D，E，G，Hのようなノードには，新しくオブジェクトを登録することはできません。このため，別名「A/B/D/I」を指定することはできません。

重複できない別名を指定した場合，別名を指定した対象ごとに，次のタイミングでエラーが発生します。

Enterprise Beanの場合は，J2EEアプリケーションの開始に失敗します。

メールコンフィグレーション以外のJ2EEリソースの場合は，リソースの開始に失敗します。

メールコンフィグレーションの場合は，属性設定時にエラーが発生します。

2.4.3　別名が登録または削除されるタイミング

ここでは，Enterprise BeanまたはJ2EEリソースに対する別名の設定方法，別名が登録されるタイミング，および別名が削除されるタイミングについて説明します。

＜この項の構成＞

(1)　Enterprise Beanの別名が登録または削除されるタイミング

(2)　J2EEリソースの別名が登録または削除されるタイミング

(1)　Enterprise Beanの別名が登録または削除されるタイミング

Enterprise Beanのオブジェクトに指定した別名が名前空間に登録されるのは，J2EEアプリケーションを開始した時，またはJ2EEサーバを起動した時です。

Enterprise Beanのオブジェクトに指定した別名が名前空間から削除されるのは，J2EEアプリケーションを停止した時，またはJ2EEサーバを停止した時です。

参考

ログレベルを「Warning」にしている場合，別名が登録または削除されたことをメッセージログで確認できます。

別名登録時：KDJE47605-Iが出力されます。

別名削除時：KDJE47606-Iが出力されます。

ただし，デフォルトのログレベルの設定では，これらのメッセージは出力されません。ログレベルの設定については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「3.3.6　J2EEサーバのログ取得の設定」を参照してください。

(2)　J2EEリソースの別名が登録または削除されるタイミング

J2EEリソースの別名が名前空間に登録されるのは，J2EEリソースを開始した時です。

J2EEリソースの別名が名前空間から削除されるのは，J2EEリソースを停止した時です。

参考

別名が登録または削除されたことは，メッセージログで確認できます。

別名登録時：KDJE47602-Iが出力されます。

別名削除時：KDJE47603-Iが出力されます。

2.4.4　クライアントからの検索

ここでは，別名を付けたEnterprise BeanまたはJ2EEリソースをクライアントから検索する方法について説明します。

＜この項の構成＞

(1)　クライアントのソースと検索先オブジェクトの設定の関係

(2)　Enterprise Beanの検索

(3)　J2EEリソースの検索

(1)　クライアントのソースと検索先オブジェクトの設定の関係

別名を付けたEnterprise BeanまたはJ2EEリソースを検索する場合のクライアントのソースでの指定方法と，検索先オブジェクトでの設定方法について説明します。

クライアントのソースには，ルックアップする名称として，検索先のオブジェクトの別名を指定します。検索先のオブジェクトには，アノテーションまたは属性ファイルを使用して，対応する別名を設定します。

検索元のソースの記述と，検索先オブジェクトの設定の関係を次の図に示します。

図2-7　クライアントのソースと検索先オブジェクトの設定の関係

(2)　Enterprise Beanの検索

別名を使用してEnterprise Beanを検索する場合の，クライアントのコーディング例を次に示します。この例では，「MyCart」という別名を設定したEJBホームオブジェクトを検索します。

 ：
javax.naming.Context ctx = new javax.naming.InitialContext();
Object obj = ctx.lookup("MyCart");
SampleHome home =
(SampleHome)javax.rmi.PortableRemoteObject.narrow(obj, SampleHome.class);
Sample mybean = home.create();   //リモートオブジェクトの生成
String name = mybean.ping();     //ビジネスメソッドの実行
 ：

EJBホームオブジェクト取得後の操作は，別名を使用しないで取得したEJBホームオブジェクトに対する操作と同じです。

EJBホームオブジェクトのリファレンスをルックアップする場合の，ルックアップおよびオブジェクト取得の流れを次の図に示します。

図2-8　EJBホームオブジェクトのリファレンスのルックアップとオブジェクト取得の流れ

ポイント

J2EEアプリケーション外からテストモードで実行されているEnterprise Beanをルックアップする場合，テストモード用の名前空間を意識してルックアップする必要があります。この図の例では，通常モードで実行されるEnterprise Beanを「MyCart」でルックアップするのに対して，同じEnterprise Beanがテストモードで実行される場合は，「$HITACHI_TEST/MyCart」でルックアップします。

テストモードでのアプリケーションの動作については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 運用／監視／連携編」の「5.7　J2EEアプリケーションのテスト機能」を参照してください。

(3)　J2EEリソースの検索

別名を使用してJ2EEリソースを検索する場合の，クライアントのコーディング例を次に示します。この例では，「jdbc/DBOpt」という別名を設定したJ2EEリソースを検索します。

Context initCtx = new InitialContext();
DataSource ds = (DataSource) initCtx.lookup("jdbc/DBOpt");

なお，J2EEリソースのオブジェクト取得後の操作は，別名を使用しないで取得したオブジェクトに対する操作と同じです。

注意

EJBクライアントアプリケーションからは，J2EEリソースを検索できません。検索した場合は，javax.naming.NameNotFoundException例外が発生します。

2.4.5　Enterprise Beanの別名の設定

ここでは，Enterprise Beanに別名を設定する方法について説明します。

Enterprise Beanの別名は，次の2種類の方法で設定できます。

cosminexus.xmlで設定する方法

アノテーションで指定する方法

それぞれの方法について説明します。

なお，この機能を使用する場合は，サーバ管理コマンドのusrconf.propertiesで別名を使用するかどうかを指定しておく必要があります。設定方法については，「2.4.7　実行環境での設定」を参照してください。

＜この項の構成＞

(1)　cosminexus.xmlで設定する方法

(2)　アノテーションで指定する方法

(3)　サーバ管理コマンドとアノテーションの両方で別名を設定した場合

(1)　cosminexus.xmlで設定する方法

Enterprise Beanの別名を設定するには，cosminexus.xmlの<ejb-jar>タグ内に指定します。cosminexus.xmlでのEnterprise Beanの別名の設定について次の表に示します。

表2-11　cosminexus.xmlでのEnterprise Beanの別名を設定

項目 | 指定するタグ | 設定内容
リモートインタフェース | <session>－<optional-name>タグ | Session Beanのリモートインタフェースの別名を指定します。
<entity>－<optional-name>タグ | Entity Beanのリモートインタフェースの別名を指定します。
ローカルインタフェース | <session>－<local-optional-name>タグ | Session Beanのローカルインタフェースの別名を指定します。
<entity>－<local-optional-name>タグ | Entity Beanのローカルインタフェースの別名を指定します。

指定するタグの詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「2.2　Cosminexusアプリケーション属性ファイル（cosminexus.xml）で指定する各属性の詳細」を参照してください。

参考

Enterprise Beanの別名は，アノテーションで設定することもできます。アノテーションによって別名が設定されている場合に，サーバ管理コマンドで異なる別名を設定すると，サーバ管理コマンドで設定した値が有効になります。

詳細は，「(3) サーバ管理コマンドとアノテーションの両方で別名を設定した場合」を参照してください。

(2)　アノテーションで指定する方法

@Statelessまたは@StatefulのmappedName属性で指定します。

アノテーションで別名を指定する場合のコーディング例を次に示します。この例は，@StatelessのmappedName属性にStateless Session Beanの別名「MyFoo」を設定する場合の例です。

@Stateless(mappedName="MyFoo")
public class FooEB implements FooIF {
   ...
}

public interface FooIF {
...
}

@Stateless，@StatefulのmappedName属性に指定した別名は，Session Bean属性ファイルの<hitachi-session-bean-property><mapped-name>タグに設定されます。

(3)　サーバ管理コマンドとアノテーションの両方で別名を設定した場合

@Stateless，@StatefulのmappedName属性を指定して別名を指定している場合に，cosminexus.xmlで<optional-name>タグまたは<local-optional-name>タグに別名を設定したときには，<optional-name>タグおよび<local-optional-name>タグの指定が有効になります。

サーバ管理コマンドとアノテーションの両方で別名を指定した場合に有効になるタグについて，次の表に示します。

表2-12　サーバ管理コマンドとアノテーションの両方で別名を指定した場合に有効になるタグ

別名の設定対象 | @Stateless，@StatefulのmappedName属性だけを指定 | <optional-name>タグ，<local-optional-name>タグだけを指定 | @Stateless，@StatefulのmappedName属性および<optional-name>タグ，<local-optional-name>タグの両方を指定した場合
リモートインタフェース | <mapped-name>タグ※ | <optional-name>タグ | <optional-name>タグ
ローカルインタフェース | <mapped-name>タグ※ | <local-optional-name>タグ | <local-optional-name>タグ

注※　@Stateless，@StatefulのmappedName属性に指定した値が設定されるタグです。

2.4.6　J2EEリソースの別名の設定

ここでは，J2EEリソースに別名を設定する方法について説明します。

J2EEリソースの別名は，cosminexus.xmlで設定できます。

なお，この機能を使用する場合は，サーバ管理コマンドのusrconf.propertiesで別名を使用するかどうかを指定しておく必要があります。設定方法については，「2.4.7　実行環境での設定」を参照してください。

J2EEリソースの別名を設定するには，cosminexus.xmlの<rar>タグ内に指定します。cosminexus.xmlでのJ2EEリソースの別名の設定について次の表に示します。

表2-13　cosminexus.xmlでのJ2EEリソースの別名を設定

項目 | 指定するタグ | 設定内容
リソースアダプタ | <resource-external-property>－<optional-name>タグ | リソースアダプタの別名を指定します。

注　メールコンフィグレーションおよびJavaBeansリソースの別名は，属性ファイルを使用して設定します。設定方法については，「2.4.7　実行環境での設定」を参照してください。

指定するタグの詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「2.2　Cosminexusアプリケーション属性ファイル（cosminexus.xml）で指定する各属性の詳細」を参照してください。

2.4.7　実行環境での設定

ユーザ指定名前空間機能を使用するためには，サーバ管理コマンドのカスタマイズ，J2EEアプリケーションの設定が必要です。

＜この項の構成＞

(1)　サーバ管理コマンドのカスタマイズ

(2)　J2EEアプリケーションの設定

(1)　サーバ管理コマンドのカスタマイズ

サーバ管理コマンドの動作設定をカスタマイズできます。ここでは，サーバ管理コマンドが使用するユーザ指定名前空間機能の設定について説明します。

サーバ管理コマンドのカスタマイズは，usrconf.properties（サーバ管理コマンド用システムプロパティファイル）で設定します。設定内容を次に示します。

表2-14　ユーザ指定名前空間機能を使用するためのサーバ管理コマンドのカスタマイズ

項目
指定するキー
設定内容

EJBホームオブジェクトリファレンスの別名付与（ユーザ指定名前空間機能）
ejbserver.cui.optionalname.enabled
EJBホームオブジェクトの別名を指定するかどうかを指定します。
また，EJBホームオブジェクトに別名を付与するためには，このキーの指定に加えて，EJBホームオブジェクトの別名※を指定する必要があります。

J2EEリソースの別名付与（ユーザ指定名前空間機能）
ejbserver.cui.optionalname.enabled
J2EEリソースの別名を指定するかどうかを指定します。
J2EEリソースに別名を付与するためには，このキーの指定に加えて，J2EEリソースの別名※を指定する必要があります。

注※　サーバ管理コマンドを使用してJ2EEアプリケーションのプロパティを定義するときに別名を指定します。JNDI名前空間に登録される名称の参照と変更については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「9.13　JNDI名前空間に登録される名称の参照と変更」を参照してください。

(2)　J2EEアプリケーションの設定

実行環境でのJ2EEアプリケーションの設定は，サーバ管理コマンドおよび属性ファイルで実施します。Enterprise Beanの別名の設定とJ2EEリソースの設定に分けて説明します。なお，ここで説明するタグは，cosminexus.xmlと対応しています。cosminexus.xmlでの定義については，「2.4.5　Enterprise Beanの別名の設定」または「2.4.6　J2EEリソースの別名の設定」を参照してください。

(a)　Enterprise Beanの別名の設定

Enterprise Beanに別名を付与するための設定には，Session Bean属性ファイルまたはEntity Bean属性ファイルを使用します。インタフェースの種別によってタグ名が異なります。インタフェースの種別ごとに使用する属性ファイルとタグを次に示します。

リモートインタフェースの別名
Session Beanの場合はSession Bean属性ファイル，Entity Beanの場合はEntity Bean属性ファイルの<optional-name>タグに指定します。

ローカルインタフェースの別名
Session Beanの場合はSession Bean属性ファイル，Entity Beanの場合はEntity Bean属性ファイルの<local-optional-name>タグに指定します。

属性ファイルでの別名の指定例を次に示します。この例は，SessionBean属性ファイルを使用して，Stateful Session Beanに別名を設定する場合の例です。

<hitachi-session-bean-property>
 <display-name>MyAdder</display-name>
 <session-type>Stateful</session-type>
 <transaction-type>Container</transaction-type>
 <runtime>
   <lookup-name>MyAdder</lookup-name>
   <optional-name>user/Adder</optional-name>
   <local-optional-name>user/localAdder</local-optional-name>
   <maximum-sessions>0</maximum-sessions>
   <stateful>
     <maximum-active-sessions>0</maximum-active-sessions>
     <inactivity-timeout>0</inactivity-timeout>
     <removal-timeout>0</removal-timeout>

この例の場合は，リモートインタフェースの別名として「user/Adder」，ローカルインタフェースの別名として「user/localAdder」が設定されます。

(b)　J2EEリソースの別名の設定

J2EEリソースに別名を付与するための設定は，DB Connector，メールコンフィグレーション，またはJavaBeansリソースの属性として設定します。設定に使用するコマンドおよび属性ファイルは，リソースの種別ごとに異なります。リソースの種別と別名を設定するコマンドおよび属性ファイルを次の表に示します。

表2-15　リソースの種別と別名を設定するコマンドおよび属性ファイル

リソースの種別 | コマンド | 属性ファイル | 指定するタグ
リソースアダプタ | cjsetrarpropコマンド | Connector属性ファイル | <resource-external-property>－<optional-name>タグ
メールコンフィグレーション | cjsetrespropコマンド | メール属性ファイル
JavaBeansリソース | cjsetjbpropコマンド | JavaBeansリソース属性ファイル | <resource-env-external-property>－<optional-name>タグ

注　メールコンフィグレーションおよびJavaBeansリソースについては，cosminexus.xmlでは設定できません。属性ファイルで設定してください。

属性ファイルでの別名の指定例を次に示します。この例は，Connector属性ファイルを使用して，リソースアダプタに別名を設定する場合の例です。

<hitachi-connector-property>
 <description></description>
 <display-name>DB_Connector_for_Oracle</display-name>
 <icon />
 <vendor-name>Hitachi, Ltd.</vendor-name>
 :
 <connector-runtime>
   <resource-external-property>
   <description></description>
   <optional-name>jdbc/TestDB1</optional-name>
   <res-auth>Container</res-auth>
   <res-sharing-scope>Shareable</res-sharing-scope>
   </resource-external-property>
 </connector-runtime>
</hitachi-connector-property>

この例の場合は，DB Connectorの別名として「jdbc/TestDB1」が設定されます。

2.4.8　ユーザ指定名前空間機能を使用する場合の注意事項

ここでは，ユーザ指定名前空間機能を使用する場合の注意事項について説明します。

＜この項の構成＞

(1)　別名を使用した検索を実行する場合の注意

(2)　ネーミングサービスについての注意

(3)　J2EEリソースの別名を指定する場合の注意

(4)　テストモードを使用する場合の注意

(1)　別名を使用した検索を実行する場合の注意

ローカルインタフェースを持つEnterprise Beanは，J2EEアプリケーション外から検索できません。

ローカルインタフェースを持つEnterprise Beanの別名に対して，ネーミングコンテキスト単位の検索はできません。

リモートインタフェースを持つEnterprise Beanとローカルインタフェースを持つEnterprise Beanには，同じ別名を設定できます。ただし，この場合に重複している別名をルックアップすると，必ずローカルインタフェースを持つEnterprise Beanがルックアップされます。

(2)　ネーミングサービスについての注意

複数のJ2EEサーバで，一つのCORBAネーミングサービスを共用している場合，ユーザ指定名前空間機能は使用できません。

J2EEサーバとCORBAネーミングサービスは同じタイミングで起動・停止するようにしてください。
J2EEサーバまたはCORBAネーミングサービスのどちらか一方がダウンした場合は，J2EEサーバとCORBAネーミングサービスを共に再起動してください。

CORBAネーミングサービスを共有する場合，ユーザ指定名前空間機能で指定する別名として「Cosminexus」は使用できません。

(3)　J2EEリソースの別名を指定する場合の注意

別名を登録したJ2EEリソースを停止，削除，または属性変更（JavaMailセッションの場合）する場合は，J2EEサーバ上で開始されているすべてのJ2EEアプリケーションを先に停止してください。

J2EEリソースのユーザ指定名前空間機能を使用する場合，J2EEアプリケーションで生成するInitialContextで指定しているプロバイダURL（java.naming.provider.url）のホスト名と，J2EEサーバ側のサーバ定義に指定するejbserver.naming.hostキーの値は同じ文字列にしてください。なお，次の条件に当てはまる場合は，J2EEアプリケーションで生成しているInitialContextに対して，プロバイダURLを指定する必要はありません。

J2EEサーバ用ユーザプロパティファイルのejbserver.naming.hostキーに「localhost」（デフォルト値）を指定する。

同一J2EEサーバ上のネーミングサービスへ接続する。

ejbserver.naming.hostキーに「localhost」を指定していて，J2EEアプリケーションで生成しているInitialContextのプロバイダURLを指定する場合は，プロバイダURLのホスト名に次のAPIで取得できる値を指定してください。java.net.InetAddress.getLocalHost().getHostName();

J2EEリソースのユーザ指定名前空間機能では，別名の中に"/"文字を含めた場合も，ネーミングコンテキスト単位で検索できません。ルックアップ名称として使用できる文字列は，指定した別名だけです。
別名として "jdbc/TestDB"を付与してデプロイおよび開始しているJ2EEリソース（DB Connector）の場合に，使用できるJNDIのルックアップ名称と使用できないルックアップ名の例を次に示します。

使用できるルックアップ名の例

DataSource ds = (DataSource) initCtx.lookup("jdbc/TestDB");

使用できないルックアップ名の例

Context ctx = (Context) initCtx.lookup("jdbc");

(4)　テストモードを使用する場合の注意

テストモードを使用している場合，1.と2.で示すオブジェクトの別名に，同じ名前を付けることができます。

テストモードで動作しているJ2EEアプリケーションに含まれる，リモートインタフェースを持つEnterprise Bean

通常モードで動作しているJ2EEアプリケーションに含まれる，リモートインタフェースを持つEnterprise Bean，またはJ2EEリソース

ただし，これらのオブジェクトに重複した別名を付けている場合に，どちらかのJ2EEアプリケーションの動作モードを変更して開始しようとすると，エラーが発生します。

エラーが発生する例を次の図に示します。

図2-9　J2EEアプリケーションの動作モードを変更した場合にエラーが発生する例

動作モードを変更した場合にJ2EEアプリケーションを起動できなかったときは，重複しない別名に変更してください。

2.5　ラウンドロビンポリシーによるCORBAネーミングサービスの検索

複数のCORBAネーミングサービスに登録されている同一名称（別名）のEJBホームオブジェクトまたはビジネスインタフェースのリファレンスを，ラウンドロビンポリシーに従ってルックアップできます。これを，ラウンドロビン検索といいます。

JNDIの名前空間から該当する名前でEJBホームオブジェクトまたはビジネスインタフェースのリファレンスをラウンドロビン検索した場合，クライアントアプリケーションは複数のCORBAネーミングサービス上に存在するEJBホームオブジェクトまたはビジネスインタフェースのリファレンスから，ラウンドロビンのポリシーで選択されたEJBホームオブジェクトまたはビジネスインタフェースのリファレンスを取得できます。これによって，J2EEサーバをクラスタ構成で開始して，負荷を分散できます。また，EJBクライアントからは，クラスタ構成を意識しないで，J2EEサーバのEnterprise Beanを呼び出すことができます。

この節の構成を次の表に示します。

表2-16　この節の構成（ラウンドロビンポリシーによるCORBAネーミングサービスの検索）

分類 | タイトル | 参照先
解説 | ラウンドロビン検索の範囲 | 2.5.1
ラウンドロビン検索の動作 | 2.5.2
設定 | ラウンドロビン検索をするために必要な設定 | 2.5.3
ラウンドロビン検索機能を使用する場合の推奨する設定 | 2.5.4
注意事項 | ラウンドロビン検索をする場合の注意事項 | 2.5.5

注　「実装」および「運用」について，この機能固有の説明はありません。

ポイント

ラウンドロビン検索をする場合，検索対象となるEJBホームオブジェクトまたはビジネスインタフェースのリファレンスは同じ名称でCORBAネーミングサービスに登録されている必要があります。このため，ユーザ指定名前空間機能を使用して，それぞれのEJBホームオブジェクトまたはビジネスインタフェースのリファレンスに同じ名称を指定してください。

＜この節の構成＞

2.5.1　ラウンドロビン検索の範囲

2.5.2　ラウンドロビン検索の動作

2.5.3　ラウンドロビン検索をするために必要な設定

2.5.4　ラウンドロビン検索機能を使用する場合の推奨する設定

2.5.5　ラウンドロビン検索をする場合の注意事項

2.5.1　ラウンドロビン検索の範囲

JNDIによるラウンドロビン検索の対象範囲は，論理ネーミングサービス内のグループとなります。

論理ネーミングサービスは一つ以上のグループで構成されます。1グループにつき一つ以上のCORBAネーミングサービスを含みます。論理ネーミングサービスの構成を次の図に示します。

図2-10　論理ネーミングサービスの構成

複数のグループで，グループのメンバに同一のCORBAネーミングサービスを指定できます。

2.5.2　ラウンドロビン検索の動作

クライアントプログラムからのラウンドロビン検索時の動作について次に示す図で説明します。

なお，図中の各CORBAネーミングサービスには，ラウンドロビン検索の対象となるEJBホームオブジェクトが「MyBean」という名前で登録されていると仮定します。検索対象となる複数のEJBホームオブジェクトには，ユーザ指定名前空間機能によって，同一の名称が設定されています。

図2-11　ラウンドロビン検索時の動作

上記の図について説明します。

クライアントアプリケーションは，検索対象の論理ネーミングサービスのグループ名を引数にして，ラウンドロビン用のInitialContextインスタンスを生成します。

クライアントアプリケーションは，生成したラウンドロビン用のInitialContextインスタンスに，「MyBean」という名前を指定して検索を要求します。

ラウンドロビン検索機能は，ラウンドロビンポリシーで検索対象のグループに属するCORBAネーミングサービスの検索先を決定します。

検索に成功すると，クライアントアプリケーションに結果を返します。
なお，検索に失敗した場合は，グループに属する別のCORBAネーミングサービスを検索します。

クライアントアプリケーションは，検索されたEJBホームオブジェクトにアクセスします。

2.5.3　ラウンドロビン検索をするために必要な設定

ラウンドロビン検索をするために必要な設定とグループ名の命名規則などについて説明します。

ラウンドロビン検索をする場合，次の設定が必要です。

ラウンドロビン検索の対象になる論理ネーミングサービスのグループ

各グループに属するCORBAネーミングサービスのルート位置

InitialContextFactoryの実装を委譲しているクラス

ラウンドロビン検索機能を使用するためには，システムプロパティに設定します。なお，InitialContextFactoryの実装を委譲しているクラスについては，システムプロパティの設定に加えて，各アプリケーションのInitialContext生成時に引数で指定することもできます。また，InitialContext生成時の引数では，システムプロパティに指定した論理ネーミングサービスのグループのうち，特定のネーミングサービスを選択して指定することもできます。

なお，システムプロパティだけで設定している場合は，特定のグループを指定したラウンドロビン検索はできません。論理ネーミングサービス上にある全グループのネーミングサービスが検索の対象となります。

ここでは，それぞれの設定方法の概要について説明します。

＜この項の構成＞

(1)　システムプロパティの設定によるグループとグループに属するCORBAネーミングサービスのルート位置の特定

(2)　J2EEサーバで動作するJ2EEアプリケーション（Enterprise Beanまたはサーブレット），またはWebコンテナサーバで動作するWebアプリケーション（サーブレット）の場合

(3)　J2EEサーバ，Webコンテナサーバ以外で動作するEJBクライアントアプリケーションの場合

(4)　InitialContext生成時の引数指定による検索対象グループの選択

(5)　グループ名の命名規則

(6)　プロパティでの設定内容

(7)　コマンドによって指定の要否が異なるプロパティ（EJBクライアントアプリケーションの場合）

(1)　システムプロパティの設定によるグループとグループに属するCORBAネーミングサービスのルート位置の特定

ラウンドロビン検索を実行する場合，システムプロパティに，ラウンドロビン検索の対象になる論理ネーミングサービスのグループと，グループに属するネーミングサービスのルート位置を指定します。また，InitialContextFactoryの実装を委譲しているクラスとして，java.naming.factory.initial=com.hitachi.software.ejb.jndi.GroupContextFactoryを指定する必要があります。

システムプロパティは，ラウンドロビン検索機能を利用するアプリケーションの種類ごとに，次の個所に設定方法が異なります。

(2)　J2EEサーバで動作するJ2EEアプリケーション（Enterprise Beanまたはサーブレット），またはWebコンテナサーバで動作するWebアプリケーション（サーブレット）の場合

J2EEサーバまたはWebコンテナサーバのプロパティをカスタマイズして設定します。設定は，簡易構築定義ファイルの，J2EEサーバ用のユーザプロパティに設定します。

ラウンドロビン検索をするための定義は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。簡易構築定義ファイルでのラウンドロビン検索をするための定義について次の表に示します。

表2-17　簡易構築定義ファイルでのラウンドロビン検索をするための定義

指定するパラメタ | 設定内容
ejbserver.jndi.namingservice.group.list | CORBAネーミングサービスのグループを指定します。
ejbserver.jndi.namingservice.group.<Specify group name>.providerurls | 各グループに属する，CORBAネーミングサービスのルート位置を指定します。
java.naming.factory.initial | InitialContextFactoryの実装をデレゲートしているクラスを指定します。

なお，ラウンドロビン検索は，ユーザ指定名前空間機能を使用していることが前提になります。ユーザ指定名前空間機能を使用する場合，サーバ管理コマンドの動作設定のカスタマイズと，J2EEアプリケーションのプロパティの定義が必要です。設定方法については，「2.4.7　実行環境での設定」および「2.4.5　Enterprise Beanの別名の設定」を参照してください。

(3)　J2EEサーバ，Webコンテナサーバ以外で動作するEJBクライアントアプリケーションの場合

次のどちらかの方法で設定します。

EJBクライアントアプリケーション起動時にプロパティとして設定する。

System.setPropertyメソッドを使用してアプリケーション内で設定する。

なお，EJBクライアントアプリケーションのプロパティの設定方法は，EJBクライアントアプリケーションの開始に使用するコマンドによって，EJBクライアントアプリケーションのプロパティの設定方法が異なります。EJBクライアントアプリケーションのプロパティの設定方法および指定例を説明します。

(a)　EJBクライアントアプリケーションのプロパティの設定方法

プロパティの設定方法は，cjclstartapコマンドを使用する場合とvbjコマンドを使用する場合で異なります。

cjclstartapコマンドの場合
cjclstartapコマンドを使用する場合は，EJBクライアントアプリケーションのプロパティファイル（usrconf.properties）でプロパティを設定します。なお，指定できるプロパティについては，「(2)　J2EEサーバで動作するJ2EEアプリケーション（Enterprise Beanまたはサーブレット），またはWebコンテナサーバで動作するWebアプリケーション（サーブレット）の場合」を参照してください。

vbjコマンドの場合
vbjコマンドを使用する場合は，バッチファイル/シェルスクリプトファイル，またはコマンドの引数で，プロパティを設定します。

(b)　プロパティの指定例

指定例を次に示します。この例は，プロパティをusrconf.propertiesで指定する場合の指定例です。なお，それぞれのキーの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「3.3　usrconf.properties（バッチサーバ用ユーザプロパティファイル）」またはマニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「15.3　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

# 論理ネーミングサービスの構成を定義
ejbserver.jndi.namingservice.group.list=g1;g2;g3
ejbserver.jndi.namingservice.group.g1.providerurls=corbaname::hostA:900;corbaname::hostB:900
ejbserver.jndi.namingservice.group.g2.providerurls=corbaname::hostD:700;corbaname::hostE:700
ejbserver.jndi.namingservice.group.g3.providerurls=corbaname::hostF:800;corbaname::hostG:800
# InitialContextFactoryの実装を委譲するクラスを指定
java.naming.factory.initial=com.hitachi.software.ejb.jndi.GroupContextFactory
　　：

指定例の中のejbserver.jndi.namingservice.group.listキー，ejbserver.jndi.namingservice.group.<Specify group name>.providerurlsキー，およびjava.naming.factory.initialキーには，それぞれ次の内容を指定します。

ejbserver.jndi.namingservice.group.listキー

ラウンドロビン検索をする場合に，検索対象になる論理ネーミングサービスのグループを定義します。指定する各グループ名は，論理ネーミング内で一意に識別できる名称にします。

ejbserver.jndi.namingservice.group.<Specify group name>.providerurlsキー

各グループに属するネーミングサービスのルート位置をプロバイダURLで指定します。<Specify group name>には，ejbserver.jndi.namingservice.group.list内に指定したグループ名を指定します。

java.naming.factory.initialキー

InitialContextFactoryの実装を委譲しているクラスを指定します。

java.naming.factory.initialキーに，"com.hitachi.software.ejb.jndi.GroupContextFactory"を指定した場合，ラウンドロビン検索が実施されます。指定しなかった場合，J2EEサーバがネーミングサービスとして利用するCORBAネーミングサービスが検索の対象になります。

なお，「(4)　InitialContext生成時の引数指定による検索対象グループの選択」に示す方法でInitialContext生成時の引数にjava.naming.factory.initialキーを設定する場合，システムプロパティでこのキーに値を指定する必要はありません。

(4)　InitialContext生成時の引数指定による検索対象グループの選択

ラウンドロビン検索を実行する設定になっている場合に，クライアントアプリケーション内でInitialContext生成時の引数に特定のグループを指定することによって，ラウンドロビン対象でのルックアップ対象になるグループを選択できます。なお，InitialContext生成時の引数の指定は任意です。

指定例を次に示します。

　　　　　：
Hashtable env = new Hashtable();
env.put("ejbserver.jndi.namingservice.groupname", "g1");
env.put("java.naming.factory.initial",
                "com.hitachi.software.ejb.jndi.GroupContextFactory");
InitialContext ic = new InitialContext(env);
　　　　　：

指定例の中のejbserver.jndi.namingservice.groupnameキーおよびjava.naming.factory.initialキーには，それぞれ次の内容を指定します。

ejbserver.jndi.namingservice.groupnameキー

検索対象となるグループ名を「gl」部分に指定します。グループ名は，システムプロパティ（usrconf.propertiesのejbserver.jndi.namingservice.group.listキー）で，すでに定義されているものを指定してください。なお，ejbserver.jndi.namingservice.groupnameキーにデフォルト値はありません。指定しなかった場合，システムプロパティで設定した，すべてのグループを検索の対象とします。

java.naming.factory.initialキー

InitialContextFactoryの実装を委譲しているクラスを指定します。java.naming.factory.initialキーに，"com.hitachi.software.ejb.jndi.GroupContextFactory"を指定した場合，ラウンドロビン検索が実施されます。システムプロパティのjava.naming.factory.initialキーの指定を省略した場合に，引数でこのキーの指定を省略すると，ejbserver.jndi.namingservice.groupnameキーで指定したグループの検索は実施されないで，J2EEサーバがネーミングサービスとして利用するCORBAネーミングサービスが検索の対象になります。

(5)　グループ名の命名規則

グループ名に使用できる文字を次に示します。

英数字（A～Z，a～z，0～9）

アンダースコア（_）

なお，グループ名は，論理ネーミングサービス内で一意となる名称にしてください。

(6)　プロパティでの設定内容

EJBクライアントアプリケーションのプロパティは，JavaアプリケーションからEnterprise Beanを呼び出す場合に使用されます。また，WebコンテナサーバからEnterprise Beanを呼び出す場合は，Enterprise Beanを呼び出す場合に必要なプロパティをカスタマイズする必要があります。J2EEアプリケーションの内容に応じて，必要なプロパティを設定してください。設定できるプロパティについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」を参照してください。

プロパティで設定できる内容の一例

EJBクライアントアプリケーションのログの設定
ejbserver.client.logで始まるキーやejbserver.loggerで始まるキーなどで，システムが出力するシステムログと，EJBクライアントアプリケーションが出力するユーザログの出力先やログレベルなどを変更できます。詳細については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 拡張編」の「2.5.2　実行環境での設定（バッチサーバの設定）」を参照してください。

EJBクライアントアプリケーションのトランザクションの設定
ejbserver.client.transactionで始まるキーで，EJBクライアントアプリケーションでトランザクションを使用するかどうか，トランザクションサービスが使用するクライアント名などを指定できます。なお，uCosminexus Clientを使用してEJBクライアント環境を構築する場合は，EJBクライアントアプリケーションのトランザクションは使用できません。詳細については，「3.20　EJBクライアントアプリケーションでトランザクションを開始する場合の注意事項」を参照してください。

EJBのリモートインタフェースでの通信障害発生時のEJBクライアントの動作
ejbserver.container.rebindpolicyキーに，EJBクライアント側でのコネクションの再接続動作とリクエストの再送動作を指定できます。

EJBクライアントアプリケーションからラウンドロビン検索を実行する設定
ejbserver.jndi.namingservice.group.listキー，ejbserver.jndi.namingservice.group.<Specify group name>.providerurlsキーおよびjava.naming.factory.initialキーに，CORBAネーミングサービスのグループ，各グループに属するCORBAネーミングサービスのルート位置，およびInitialContextFactoryの実装をデレゲートしているクラスを指定できます。なお，ラウンドロビン検索は，J2EEサーバのサーバ管理コマンドのカスタマイズでユーザ指定名前空間機能を使用する設定をしている場合に有効になります。

EJBクライアントアプリケーションからCTMへのリクエストの優先度の設定
ejbserver.client.ctm.RequestPriorityキーに，EJBクライアントアプリケーションからCTMに送信するリクエストの優先度を設定できます。

(7)　コマンドによって指定の要否が異なるプロパティ（EJBクライアントアプリケーションの場合）

ここでは，EJBクライアントアプリケーションのコマンド（vbjコマンド）によって指定の要否が異なるプロパティについて説明します。EJBクライアントアプリケーションのコマンドによって指定の要否が異なるプロパティのキーを次の表に示します。

表2-18　EJBクライアントアプリケーションのコマンドによって指定の要否が異なるプロパティのキー

プロパティのキー | 種別 | コマンド
cjclstartap | vbj
org.omg.CORBA.ORBClass | 固定 | － | －
org.omg.CORBA.ORBSingletonClass | 固定 | － | －
javax.rmi.CORBA.UtilClass | 固定 | － | ○
javax.rmi.CORBA.StubClass | 固定 | － | －
javax.rmi.CORBA.PortableRemoteObjectClass | 固定 | － | ○
java.endorsed.dirs | 可変 | － | －

（凡例）

固定：該当するキーに対する値は固定で，指定する必要がある

可変：システムの実行環境に従って値を指定する必要がある

○：コマンドにキーを指定する必要がある

－：コマンドにキーを指定する必要がない

2.5.4　ラウンドロビン検索機能を使用する場合の推奨する設定

ラウンドロビン検索機能を使用するときには，ネーミングサービスの障害検知機能をあわせて使用することを推奨します。

ネーミングサービスの障害検知機能と組み合わせた設定例については，「2.7.4　実行環境の設定（障害検知機能を使用する場合）」を参照してください。

2.5.5　ラウンドロビン検索をする場合の注意事項

ここでは，ラウンドロビン検索をする場合の注意事項について説明します。

ラウンドロビン検索用に取得したコンテキストでは，lookupメソッドだけをサポートしています。javax.naming.Contextで定義されているほかのAPIは使用できません。

別名を使用したラウンドロビン検索を実行すると，次の順序でEnterprise Beanが検索されます。

検索を実行したJ2EEサーバの名前空間から，ローカルインタフェースを持つEnterprise Beanが検索されます。

1.で見つからなかった場合は，ラウンドロビン検索によってリモートインタフェースを持つEnterprise Beanが検索されます。

InitialContextFactoryの処理を委譲しているクラスごとの検索可否を次の表に示します。

表2-19　InitialContextFactoryの処理を委譲しているクラスごとの検索可否

検索対象
GroupContextFactory
InsContextFactory

リモートインタフェースを持つEnterprise Bean
○※
○

リモートインタフェースを持つEnterprise Bean
（別名による検索）
○
○

ローカルインタフェースを持つEnterprise Bean
○※
○

ローカルインタフェースを持つEnterprise Bean
（別名による検索）
○
○

J2EEリソース
○※
○

J2EEリソース
（別名による検索）
×
○

（凡例）　○：検索できる　×：検索できない

注※　java:comp/envでのルックアップの場合，ラウンドロビン検索はしません。ルックアップを実行した自身のJ2EEサーバだけから検索されます。

InitialContextFactoryの実装を委譲しているクラスは，次の方法で指定します。両方指定した場合は引数で指定した方が有効になります。

usrconf.propertiesのjava.naming.factory.initialキーに指定する。

InitialContextを生成するときの引数(Hashtable)で，java.naming.factory.initialキーに指定する。

2.6　ネーミング管理機能でのキャッシング

J2EEサービスのネーミング管理機能には，キャッシング機能があります。キャッシング機能とは，JNDIを介してEJBホームオブジェクトリファレンスを検索した場合に，該当オブジェクトをキャッシュに一時的に保存し，以降，同一のオブジェクトを検索するときには，キャッシュに保存されたオブジェクトを返す機能です。

この節では，キャッシングの流れ，およびキャッシュ領域のクリアについて説明します。

なお，ネーミング管理機能でのキャッシングをするための設定は，J2EEサーバ，WebコンテナサーバまたはEJBクライアントアプリケーションのプロパティとして設定します。

この節の構成を次の表に示します。

表2-20　この節の構成（ネーミング管理機能でのキャッシング）

分類 | タイトル | 参照先
解説 | キャッシングの流れ | 2.6.1
ネーミングで使用したキャッシュのクリア | 2.6.2
設定 | キャッシング機能を使用するための設定 | 2.6.3
注意事項 | ネーミングでのキャッシングの注意事項 | 2.6.4

注　「実装」および「運用」について，この機能固有の説明はありません。

＜この節の構成＞

2.6.1　キャッシングの流れ

2.6.2　ネーミングで使用したキャッシュのクリア

2.6.3　キャッシング機能を使用するための設定

2.6.4　ネーミングでのキャッシングの注意事項

2.6.1　キャッシングの流れ

次の図に示すような流れで，ネーミングはキャッシングされます。

図2-12　ネーミングのキャッシングの流れ

キャッシングの流れを説明します。この流れでは，同じJ2EEサーバ上の二つのJ2EEアプリケーションから，同じ名前「Count」でEJBホームオブジェクトのリファレンスをルックアップします。1.～5.がJ2EEアプリケーション1から実行される処理，6.～9.がJ2EEアプリケーション2から実行される処理です。

J2EEアプリケーション1が，JNDIのjavax.naming.InitialContextクラスのインスタンスを生成します。

J2EEアプリケーション1が，javax.naming.InitialContextクラスのインスタンスに対して，EJBホームオブジェクトリファレンスの検索（ルックアップ）を要求します。このとき，名前に「Count」を指定します。

要求を受けたネーミング管理機能が，CORBAネーミングサービスの名前空間からEJBホームオブジェクトリファレンスを検索します。

ネーミング管理機能は，検索結果として，EJBホームオブジェクトのリファレンスを取得します。

ネーミング管理機能が，取得したEJBホームオブジェクトのリファレンスをキャッシュに保存します。

同じプロセス上にあるJ2EEアプリケーション2が，JNDIのjavax.naming.InitialContextクラスのインスタンスを生成します。

J2EEアプリケーション2が，javax.naming.InitialContextクラスのインスタンスに対して，EJBホームオブジェクトリファレンスの検索（ルックアップ）を要求します。このとき，名前に，2.で指定した名前と同じ名前「Count」を指定します。

要求を受けたネーミング管理機能が，キャッシュから，EJBホームオブジェクトリファレンスを検索します。

ネーミング管理機能が，検索結果として，キャッシュからEJBホームオブジェクトのリファレンスを取得します。

2.6.2　ネーミングで使用したキャッシュのクリア

ネーミングで使用しているキャッシュは，クリアできます。ただし，クリアするキャッシュサイズは設定できません。ここでは，キャッシュクリアが行われるタイミングと，クリアされる範囲について説明します。

＜この項の構成＞

(1)　キャッシュクリアのタイミング

(2)　キャッシュクリアの範囲

(1)　キャッシュクリアのタイミング

キャッシュの内容は次のどちらかのタイミングでクリアされます。

JNDIおよびRMI-IIOPのAPIで例外が発生した場合，キャッシュのクリアを強制的に実施します。

システムプロパティに指定した値の間隔でキャッシュをクリアします（デフォルト値は0秒で，キャッシュはクリアされません）。

(2)　キャッシュクリアの範囲

ネーミングサービスでのキャッシュクリアの範囲について説明します。

キャッシュクリアの範囲は2とおりあります。

キャッシュ領域をすべてクリアします。

無効なキャッシュ領域だけをクリアします。

1.の場合，キャッシュの全領域をクリアします。一方，2.の場合は，定期的に，キャッシュに保存されたオブジェクトが有効かどうかを確認し，無効なオブジェクトだけをキャッシュからクリアします。また，2.の場合，キャッシュクリアと同じタイミングで，一度検索を行ったCORBAネーミングサービスの状態を監視します。これによって，一度検索されたCORBAネーミングサービスの場合，CORBAネーミングサービスがダウンしたあとは，該当するCORBAネーミングサービスの検索を実施しません。また，CORBAネーミングサービスが再起動すると，該当するCORBAネーミングサービスの検索を自動的に開始します。

参考

EJBホームオブジェクトの再接続機能を使用している場合，J2EEサーバを再起動したあとでも，キャッシュは無効になりません。

このため，無効なキャッシュ領域だけをクリアする指定をしているときでも，CORBAネーミングサービスのEJBホームオブジェクトのオブジェクトリファレンスは，キャッシュ領域から削除されません。

EJBホームオブジェクトのリファレンスの検索（ルックアップ）で，削除されなかったキャッシュ上のオブジェクトリファレンスがそのまま使用できます。

2.6.3　キャッシング機能を使用するための設定

キャッシング機能を使用するための設定について説明します。J2EEアプリケーションの場合とEJBクライアントアプリケーションの場合で設定個所が異なります。

＜この項の構成＞

(1)　J2EEアプリケーションでキャッシング機能を使用する場合

(2)　EJBクライアントアプリケーションでキャッシング機能を使用する場合

(1)　J2EEアプリケーションでキャッシング機能を使用する場合

J2EEアプリケーションでキャッシング機能を使用するための定義は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。簡易構築定義ファイルでのキャッシング機能を使用するための定義について次の表に示します。

表2-21　キャッシング機能を使用するための定義

指定するパラメタ | 設定内容
ejbserver.jndi.cache | ネーミングでのキャッシングを有効にするかどうかを指定します。
ejbserver.jndi.cache.interval | ネーミングでのキャッシングをする場合，キャッシュをクリアする間隔（単位：秒）を指定します。
ejbserver.jndi.cache.interval.clear.option | インターバル経過後のネーミングでのキャッシュ領域に対する動作（キャッシュクリアの範囲）を決定します。

キャッシュを定期的にクリアするときの設定例（物理ティアの定義の場合）を次に示します。

（例）

<configuration>
 <logical-server-type>j2ee-server</logical-server-type>
 <param>
   <param-name>ejbserver.jndi.cache</param-name>
   <param-value>on</param-value>
 </param>
 <param>
   <param-name>ejbserver.jndi.cache.interval</param-name>
   <param-value>60</param-value>
 </param>
 <param>
   <param-name>ejbserver.jndi.cache.interval.clear.option</param-name>
   <param-value>check</param-value>
 </param>
 ：
</configuration>

(2)　EJBクライアントアプリケーションでキャッシング機能を使用する場合

EJBクライアントアプリケーション起動時にプロパティとして設定します。

EJBクライアントアプリケーションのプロパティの設定方法は，EJBクライアントアプリケーションの開始に使用するコマンドによって，EJBクライアントアプリケーションのプロパティの設定方法が異なります。

cjclstartapコマンドの場合
cjclstartapコマンドを使用する場合は，EJBクライアントアプリケーションのプロパティファイル（usrconf.properties）で，プロパティを設定します。

vbjコマンドの場合
vbjコマンドを使用する場合は，バッチファイル/シェルスクリプトファイル，またはコマンドの引数で，プロパティを設定します。

キャッシュを定期的にクリアするときの設定例を次に示します。

EJBクライアントのシステムプロパティ設定例

 ：
# キャッシュの設定
ejbserver.jndi.cache=on
ejbserver.jndi.cache.interval=60
ejbserver.jndi.cache.interval.clear.option=check

2.6.4　ネーミングでのキャッシングの注意事項

ネーミングのキャッシングに関する注意事項について説明します。

アプリケーションでEJBホームオブジェクトリファレンスやJDBCデータソースをキャッシングしている場合，ネーミングでのキャッシングを無効にすることを推奨します。

キャッシュを定期的にクリアするには，簡易構築定義ファイルで設定します。論理J2EEサーバ（j2ee-server）の<configuration>タグ内に，次のパラメタで設定します。

ejbserver.jndi.cache.interval.clear.option

キャッシュをクリアする範囲を指定します。

ejbserver.jndi.cache

キャッシュを実行するかどうかを指定します。ここでは「ON」を設定してください。

ejbserver.jndi.cache.interval

キャッシュのクリア間隔を指定します。

論理J2EEサーバ（j2ee-server）の<configuration>タグ内で，プロパティ「ejbserver.jndi.cache.interval.clear.option」に「check」を設定している場合，CORBAネーミングサービスの監視は，プロパティ「ejbserver.jndi.cache.interval」に指定したキャッシュクリアのタイミングだけで行われます。CORBAネーミングサービスの再起動後，CORBAネーミングサービスの回復を検知するためには，最大で，プロパティ「ejbserver.jndi.cache.interval」に設定した時間が必要です。

キャッシング機能を使用している場合，キャッシュにEJBホームオブジェクトのオブジェクトリファレンスが保存された状態で，EJBホームオブジェクトが保存されているJ2EEサーバがダウンするか，またはJ2EEアプリケーションの再デプロイが実行されると，キャッシュに保存されているEJBホームオブジェクトのオブジェクトリファレンスは無効な情報となります。この状態でEJBホームオブジェクトの検索要求（lookup）を受けると，キャッシュ上の無効なオブジェクトリファレンスが検索要求元に返却されます。このオブジェクトリファレンスに対して，javax.rmi.PortableRemoteObject.narrow()メソッド，またはcreateメソッドなどのメソッドを実行すると，CORBA例外（org.omg.CORBA.OBJECT_NOT_EXISTなど）が発生する場合があります。なお，CORBA例外が発生した場合，キャッシュ情報はすべて削除されます。次回の検索要求（lookup）ではCORBAネーミングサービスへ接続して有効な情報が取得されます。

CTMを使用している場合に，指定した値の間隔で無効なキャッシュ領域だけをクリアするとき，J2EEサーバやJ2EEアプリケーションが停止していても，グローバルCORBAネーミングサービスのEJBホームオブジェクトのオブジェクトリファレンスはキャッシュ領域からクリアされません。EJBホームオブジェクトの検索要求（lookup）を受けると，クリアされなかったキャッシュ上のオブジェクトリファレンスが検索要求元に返却されます。J2EEアプリケーションが再度開始されていた場合は，キャッシュしたオブジェクトリファレンスはそのまま使用できます。J2EEアプリケーションが再度開始されていない場合は，返却されたオブジェクトリファレンスに対して，createメソッドなどのメソッドを実行すると，CORBA例外（org.omg.CORBA.NO_IMPLEMENT）などが発生します。
なお，CORBA例外が発生した場合，キャッシュ情報はすべて削除されます。J2EEアプリケーションが再開始している場合は，次回の検索要求（lookup）でグローバルCORBAネーミングサービスに接続して有効な情報が取得されます。

2.7　ネーミングサービスの障害検知

ネーミングサービスの障害検知は，キャッシング機能のオプションとして使用します。

ネーミングサービスの障害検知機能を使用すると，ネーミングサービスの障害が発生した場合に，EJBクライアントが，より早くエラーを検知できます。

この節では，ネーミングサービスの障害検知機能の概要，およびネーミングサービスの障害検知機能と併用して使用することを推奨する機能について説明します。

この節の構成を次に示します。

表2-22　この節の構成（ネーミング管理の障害検知）

分類 | タイトル | 参照先
解説 | ネーミング管理の障害検知機能とは | 2.7.1
ラウンドロビン検索機能との併用 | 2.7.2
ネーミング管理の障害検知機能の挙動 | 2.7.3
設定 | 実行環境の設定（障害検知機能を使用する場合） | 2.7.4
注意事項 | ネーミング管理の障害検知機能の注意事項 | 2.7.5

注　「実装」および「運用」について，この機能固有の説明はありません。

＜この節の構成＞

2.7.1　ネーミングサービスの障害検知機能とは

2.7.2　ラウンドロビン検索機能との併用

2.7.3　ネーミングサービスの障害検知機能の挙動

2.7.4　実行環境の設定（障害検知機能を使用する場合）

2.7.5　ネーミングサービスの障害検知機能の注意事項

2.7.1　ネーミングサービスの障害検知機能とは

ネーミングサービスの障害検知機能を使用すると，ネーミングサービスが停止したり，アプリケーションサーバなどでマシンの障害やネットワーク障害が発生したりした場合，J2EEサーバが障害を検知します。

ネーミングサービスの障害検知機能では，J2EEサーバがネーミングサービスの機能の状態を監視し，通信ができないと判断したネーミングサービスの機能を使用することを抑止できます。そのため，EJBクライアントではむだな通信をしないで済みます。

ネーミングサービスの障害検知機能を使用した場合の処理の流れを次の図に示します。

図2-13　ネーミングサービスの障害検知機能を使用した場合の処理の流れ

ネーミングサービスの障害検知機能を使用しない場合，名前をルックアップするときには必ずネーミングサービスに通信します。このため，通信できないでエラーになるまでに時間が掛かることがあります。一方，ネーミングサービスの障害検知機能を使用している場合，障害が発生しているネーミングサービスに対する通信はしないで，エラーを検知できます。このため，時間が掛かりません。

2.7.2　ラウンドロビン検索機能との併用

ラウンドロビン検索機能とネーミングサービスの障害検知機能を併用すると，一つの系で障害が発生したときに，障害が発生した系を容易に切り離しできます。

次に，ラウンドロビン検索機能とネーミングサービスの障害検知機能を併用した場合の通信について図で説明します。

図2-14　ラウンドロビン検索機能とネーミングサービスの障害検知機能を併用した場合の通信

名前をルックアップした場合に特定のネーミングサービスに障害が発生していることを検知した場合，ラウンドロビン検索機能によって，通信可能なネーミングサービスへの通信に切り替えられます。

2.7.3　ネーミングサービスの障害検知機能の挙動

ネーミングサービスの障害検知機能の挙動について説明します。

＜この項の構成＞

(1)　閉塞のタイミング

(2)　閉塞した場合の挙動

(3)　ネーミングサービスの閉塞解除のタイミング

(1)　閉塞のタイミング

ネーミングサービスの障害検知では，次のタイミングでネーミングサービスの状態を確認し，応答がなかった場合に閉塞します。

sweepインターバル時間経過のタイミングに応答がなかった場合

RMI/IIOP通信エラーなどを契機にキャッシュの領域がすべてクリアされたあとや，キャッシュがない状態で，次の操作を最初に実行した時にネーミングサービスの応答がなかった場合

InitilalContextを生成した時

lookupをした時

キャッシュをすべてクリアしたあとのネーミングサービスに対する操作の挙動について表で説明します。

表2-23　キャッシュをすべてクリアしたあとのネーミングサービスに対する操作の挙動

ネーミング管理の機能での操作
ラウンドロビン検索を使用している場合
ラウンドロビン検索を使用していない場合

InitialContextを生成したとき
EJBクライアントプロセス起動後の初回InitialContext生成時に，ネーミングサービスの稼働確認で応答がない場合は，閉塞される。
初回以外の場合は，閉塞されない。
生死確認をして，ネーミングサービスからの応答が検知できない場合，閉塞される。

lookupしたとき
lookupの発行時に通信しようとしているネーミングサービスに対してだけ，状態確認をする。
応答が検知できない場合は，閉塞される。例えば三つのネーミングサービスでラウンドロビン検索をしている場合には，ダウンしたネーミングサービスが閉塞されるのは最大で3回目のlookup時になる。
生死確認をして，ネーミングサービスからの応答が検知できない場合，閉塞される。

ネーミングサービスの障害検知機能では，閉塞されると同時にKDJE47111-Iメッセージをログに出力します。メッセージが出力されたあとに，稼働中のネーミングサービスの機能に対する通信はすべて抑止されて，javax.naming.NamingExceptionをスローされます。

(2)　閉塞した場合の挙動

ネーミングサービスの障害検知機能によって閉塞されたネーミングサービスに対して，EJBクライアントからInitialContextの生成，またはlookupした場合のネーミングサービスの挙動について説明します。

閉塞したネーミングサービスに対する操作について，ラウンドロビン検索機能を使用しているか，使用していないかに分けて表で示します。

表2-24　閉塞したネーミングサービスに対する操作

EJBクライアントからの操作
ラウンドロビン検索を使用している場合
ラウンドロビン検索を使用していない場合

InitialContextを生成したとき
ラウンドロビン用のInitialContextを返す。
常に通信を抑止する。
EJBクライアントにjavax.naming.NamingExceptionを返す。

lookupしたとき
ラウンドロビングループに登録されている，別のネーミングサービスからオブジェクトを検索して返す。
常に通信を抑止する。
EJBクライアントにjavax.naming.NamingExceptionを返す。

(3)　ネーミングサービスの閉塞解除のタイミング

閉塞を解除するタイミングについて説明します。次に示すタイミングでネーミングサービスの状態確認をして，ネーミングサービスからの応答が検知できたときに閉塞を解除します。

sweepインターバル時間経過のタイミング

閉塞を解除すると同時に，KDJE47110-Iメッセージをログに出力します。メッセージが出力されたあとは，稼働中のネーミングサービスに対する通信は抑止されません。

2.7.4　実行環境の設定（障害検知機能を使用する場合）

ネーミングサービスの障害検知機能は，キャッシング機能のオプションです。このため，キャッシング機能の設定が前提となります。ネーミングサービスのキャッシング機能の設定については，「2.6.3　キャッシング機能を使用するための設定」を参照してください。

ネーミングサービスの障害検知機能を使用する場合は，次の表に示す値を設定してください。

表2-25　ネーミングサービスの障害検知機能を使用する場合の設定

指定するパラメタ | 値
ejbserver.jndi.cache | on
ejbserver.jndi.cache.interval | 1～2,147,483,647
ejbserver.jndi.cache.interval.clear.option | check

EJBクライアントのシステムプロパティの設定例を次に示します。この例は，usrconf.propertiesに設定した場合の例です。また，この例では，ラウンドロビン検索機能もあわせて設定しています。

EJBクライアントのシステムプロパティ設定例

 ：
# キャッシュの設定
ejbserver.jndi.cache=on
ejbserver.jndi.cache.interval=60
ejbserver.jndi.cache.interval.clear.option=check

# 論理ネーミングサービスの構成を定義
ejbserver.jndi.namingservice.group.list=g1;g2;g3
ejbserver.jndi.namingservice.group.g1.providerurls= corbaname::hostA:900;corbaname::hostB:900;corbaname::hostC:900
ejbserver.jndi.namingservice.group.g2.providerurls=
　　　　　　　　　　　　　corbaname::hostD:700;corbaname::hostE:700
ejbserver.jndi.namingservice.group.g3.providerurls=
 corbaname::hostF:800;corbaname::hostG:800;corbaname::hostH:800
 ：

2.7.5　ネーミングサービスの障害検知機能の注意事項

ネーミングサービスの障害検知機能の注意事項について説明します。

＜この項の構成＞

(1)　閉塞解除のタイミングについて

(2)　07-60までとの挙動の違い

(3)　ネーミング管理の機能の生死確認

(1)　閉塞解除のタイミングについて

ネーミングサービスの障害検知機能を使用しない場合，障害が発生したネーミングサービスへのクライアントアプリケーションからの検索は，ネーミングサービスおよびJ2EEサーバが再起動した直後から成功します。

しかし，ネーミングサービスの障害検知機能を使用している場合，sweepインターバルのタイミングでしか閉塞の解除ができません。ネーミング管理機能では，ネーミングサービスが停止したあと，sweepインターバルが経過しないと実際のネーミングサービスに接続しません。つまり，ネーミングサービスの機能が回復したあとから検索に成功するまでに最大sweepインターバル時間を必要とします。ネーミングサービスの障害検知機能を使用する場合，sweepインターバルの設定時間（ejbserver.jndi.cache.intervalプロパティの値）に，短い時間（推奨値は60）を設定することを推奨します。

(2)　07-60までとの挙動の違い

アプリケーションサーバのバージョンが07-60までと08-00以降では，閉塞するタイミングが異なります。08-00以降では，sweepインターバル時間経過タイミングに加えて，クライアントアプリケーションから検索した場合に稼働状態の確認を実施します。

(3)　ネーミング管理の機能の生死確認

ネーミングサービスの障害検知機能を使って稼働状態の確認を実施した場合に，一時的なネットワーク障害やサーバ側が高負荷な状態であるときに，ネーミングサービスが停止したと判断されることがあります。

2.8　CORBAネーミングサービスの切り替え

ネーミング管理機能では，JNDIを介して分散オブジェクトを検索するときに，JNDIが接続するCORBAネーミングサービスの切り替えができます。切り替えは，InitialContextクラスのインスタンスに対して，プリフィックス「corbaname:」を付与した名前をlookupメソッドの引数に渡すことで実現できます。

CORBAネーミングサービスの切り替えの流れを次の図に示します。

図2-15　CORBAネーミングサービスの切り替えの流れ

ネーミングサービスの切り替えの流れを説明します。この流れでは，J2EEアプリケーションから，プリフィックス「corbaname:」を付与したルックアップを2回実行します。プリフィックスの後ろに指定したホスト名に応じて，接続するCORBAネーミングサービスが切り替えられます。

J2EEアプリケーションが，JNDIのjavax.naming.InitialContextクラスのインスタンスを生成します。

J2EEアプリケーションが，javax.naming.InitialContextクラスのインスタンスに対して，オブジェクトの検索（ルックアップ）を要求します。このとき，プリフィックス「corbaname:」を付与した名前「corbaname::MyHost:900#Count1」を指定します。

要求を受けたネーミング管理機能から「MyHost:900」のCORBAネーミングサービスへの接続が実行されます。接続後，ルックアップで指定した名前のEJBホームのオブジェクトリファレンス「Count1」が検索されます。

J2EEアプリケーションから，InitialContextクラスのインスタンスに対して，オブジェクトの検索（ルックアップ）を要求します。このとき，プリフィックス「corbaname:」を付与した名前「corbaname::MyHost:901#Count2」を指定します。

要求を受けたネーミング管理機能から「MyHost:901」のCORBAネーミングサービスへの接続が実行されます。接続後，ルックアップで指定した名前のEJBホームのオブジェクトリファレンス「Count2」が検索されます。

CORBAネーミングサービスの切り替えは，サーバ管理コマンドを使用した，Enterprise Beanリファレンスの解決で実行します。操作については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「9.　J2EEアプリケーションのプロパティ設定」を参照してください。

なお，CORBAネーミングサービスがローカルホスト上で動作する場合，ネーミングサービスのホスト名に関する設定では，"localhost"の文字列ではなく，マシン名またはIPアドレスを指定してください。

ネーミングサービスのホスト名の設定は，J2EEサーバのプロパティをカスタマイズして設定します。設定方法については，「2.3.6　実行環境での設定」を参照してください。

2.9　EJBホームオブジェクトリファレンスの再利用（EJBホームオブジェクトへの再接続機能）

EJBホームオブジェクトへの再接続機能とは，J2EEサーバの障害などのあとで，J2EEサーバを再起動した場合やJ2EEアプリケーションを再開始した場合に，EJBクライアントアプリケーションが取得したEJBホームオブジェクトを再利用できる機能です。J2EEサーバの再起動後やJ2EEアプリケーションの再開始後に，EJBクライアントアプリケーションが取得したEJBホームオブジェクトを，再ルックアップしないでそのまま利用できます。

Session Bean（Stateless Session BeanまたはStateful Session Bean）のEJBホームオブジェクトのリファレンスに利用できます。

この節の構成を次の表に示します。

表2-26　この節の構成（EJBホームオブジェクトへの再接続機能）

分類 | タイトル | 参照先
設定 | 実行環境での設定（J2EEサーバの設定） | 2.9.1
注意事項 | EJBホームオブジェクトリファレンスを再利用する場合の注意事項 | 2.9.2

注　「解説」，「実装」，および「運用」について，この機能固有の説明はありません。

＜この節の構成＞

2.9.1　実行環境での設定（J2EEサーバの設定）

2.9.2　EJBホームオブジェクトリファレンスを再利用する場合の注意事項

2.9.1　実行環境での設定（J2EEサーバの設定）

EJBホームオブジェクトへの再接続機能を使用する場合，J2EEサーバの設定が必要です。J2EEサーバの設定は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。

簡易構築定義ファイルでのEJBホームオブジェクトへの再接続機能の定義について次の表に示します。

表2-27　簡易構築定義ファイルでのEJBホームオブジェクトへの再接続機能の定義

指定するパラメタ | 設定内容
ejbserver.container.ejbhome.sessionbean.reconnect.enabled | EJBホームオブジェクトへの再接続機能を有効にするかどうかを指定します。

簡易構築定義ファイルおよび指定するパラメタの詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「4.6　簡易構築定義ファイル」を参照してください。

2.9.2　EJBホームオブジェクトリファレンスを再利用する場合の注意事項

EJBホームオブジェクトへの再接続機能を使用する場合の注意事項を次に示します。

J2EEサーバの再起動やJ2EEアプリケーションの再開始の際に，J2EEアプリケーションを変更しないでください。J2EEアプリケーションを変更すると，EJBホームオブジェクトのリファレンスは再利用できません。

J2EEサーバの通信ポートを固定してください。また，J2EEサーバを再起動するときに，固定した値を変更しないでください。
定義方法については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.14.1　通信ポートの固定」，およびマニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.14.2　IPアドレスの固定」を参照してください。

Javaアプリケーション用ユーザプロパティファイルのリモートインタフェースでの通信障害発生時のEJBクライアントの動作（ejbserver.container.rebindpolicyキー）の値に，「VB_TRANSPARENT」を指定してください。
定義方法については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.13　EJBのリモートインタフェースの呼び出し」を参照してください。

EJB呼び出しで通信障害が発生した場合，通信障害発生時のEJBクライアントの動作（ejbserver.container.rebindpolicyキー）の値に「VB_TRANSPARENT」を指定していると，コネクションが再接続され，リクエストが再送されます。
そのため，EJBホームオブジェクトへの再接続機能は参照系のシステムでの使用を推奨します。

3.　リソース接続とトランザクション管理

この章では，アプリケーションサーバが接続できるリソースと，リソースへの接続について説明します。また，リソース接続でのトランザクション管理についても説明します。

＜この章の構成＞

3.1　この章の構成

3.2　リソース接続とトランザクション管理の概要

3.3　リソース接続

3.4　トランザクション管理

3.5　リソースへのサインオン方式

3.6　データベースへの接続

3.7　データベース上のキューとの接続

3.8　OpenTP1とのOutboundでの接続（SPPまたはTP1/Message Queue）

3.9　OpenTP1とのInboundでの接続

3.10　Cosminexus JMSプロバイダとの接続

3.11　SMTPサーバとの接続

3.12　JavaBeansリソースの利用

3.13　そのほかのリソースとの接続

3.14　パフォーマンスチューニングのための機能

3.15　フォールトトレランスのための機能

3.16　そのほかのリソースアダプタの機能（Connector 1.5仕様に準拠するリソースアダプタの場合）

3.17　コネクションプールのクラスタ化機能

3.18　リソースへの接続テスト

3.19　ファイアウォール環境での運用のための機能

3.20　EJBクライアントアプリケーションでトランザクションを開始する場合の注意事項

3.1　この章の構成

リソース接続とトランザクション管理の機能と参照先を次の表に示します。

表3-1　リソース接続とトランザクション管理の機能と参照先

機能 | 参照先
リソース接続とトランザクション管理の概要 | 3.2
リソース接続 | 3.3
トランザクション管理 | 3.4
リソースへのサインオン方式 | 3.5
データベースへの接続 | 3.6
データベース上のキューとの接続 | 3.7
OpenTP1とのOutboundでの接続（SPPまたはTP1/Message Queue） | 3.8
OpenTP1とのInboundでの接続 | 3.9
Cosminexus JMSプロバイダとの接続 | 3.10
SMTPサーバとの接続 | 3.11
JavaBeansリソースの利用 | 3.12
そのほかのリソースとの接続 | 3.13
パフォーマンスチューニングのための機能 | 3.14
フォールトトレランスのための機能 | 3.15
そのほかのリソースアダプタの機能（Connector 1.5仕様に準拠するリソースアダプタの場合） | 3.16
コネクションプールのクラスタ化機能 | 3.17
リソースへの接続テスト | 3.18
ファイアウォール環境での運用のための機能 | 3.19
EJBクライアントアプリケーションでトランザクションを開始する場合の注意事項 | 3.20

3.2　リソース接続とトランザクション管理の概要

J2EEサーバ上のJ2EEアプリケーションに含まれるEJB，サーブレット，JSPなどのJ2EEコンポーネントからは，データベースやOpenTP1などのリソースに接続できます。データベースやOpenTP1などのリソースに接続する場合は，リソースアダプタを使用します。アプリケーションサーバでは，Connector 1.0仕様またはConnector 1.5仕様に準拠したリソースアダプタを使用できます。SMTPサーバやJavaBeansリソースなどのリソースに，リソースアダプタを使用しないで接続する機能も提供しています。

また，アプリケーションサーバでは，リソースに効率的かつ信頼性の高い方法でアクセスするために，コネクションプーリングやトランザクション管理の機能を提供しています。コネクションプーリングを使用すると，リソースに対するコネクションをプーリングして，効率的にコネクションを使用できます。また，障害が発生したコネクションを適切にコネクションプールから取り除きます。また，トランザクション管理の機能を使用すると，トランザクションマネージャが，EJBのメソッドごとに指定するトランザクション属性やJTAインタフェース（UserTransaction）による指示に基づいて，リソースアクセスのトランザクションを適切に制御します。複数のリソースに対してトランザクション管理をする場合には，グローバルトランザクションを使用します。グローバルトランザクションを使用すると，2フェーズコミットプロトコルによってトランザクションが管理されるため，リソース間で更新の整合性が確保されます。

コネクションプーリング，およびトランザクション管理の機能を使用したリソースへの接続の例を次の図に示します。

図3-1　コネクションプーリングおよびトランザクション管理の機能を使用したリソースへの接続の例

3.3　リソース接続

この節では，リソースの種類ごとの接続方法と，接続に使用するリソースアダプタの種類について説明します。

また，リソースアダプタを使用する場合の説明として，リソースアダプタの使用方法，機能および注意事項についても説明します。

この節の構成を次の表に示します。

表3-2　この節の構成（リソース接続）

分類 | タイトル | 参照先
解説 | リソースへの接続方法 | 3.3.1
リソースアダプタの種類 | 3.3.2
リソースアダプタの使用方法 | 3.3.3
リソースアダプタの機能 | 3.3.4
リソースアダプタ以外の機能 | 3.3.5
実装 | リソースに接続するための実装 | 3.3.6
設定 | リソースアダプタの設定方法 | 3.3.7
リソースアダプタの設定の流れ（J2EEリソースアダプタとしてデプロイして使用する場合） | 3.3.8
リソースアダプタの設定の流れ（J2EEアプリケーションに含めて使用する場合） | 3.3.9
リソースアダプタの設定の流れ（Inboundで使用する場合） | 3.3.10
リソースアダプタの設定の流れ（コネクションプールのクラスタ化をする場合） | 3.3.11
リソースアダプタ以外を使用する接続の設定 | 3.3.12
注意事項 | リソースアダプタについての注意事項 | 3.3.13

注　「運用」について，この機能固有の説明はありません。

＜この節の構成＞

3.3.1　リソースへの接続方法

3.3.2　リソースアダプタの種類

3.3.3　リソースアダプタの使用方法

3.3.4　リソースアダプタの機能

3.3.5　リソースアダプタ以外の機能

3.3.6　リソースに接続するための実装

3.3.7　リソースアダプタの設定方法

3.3.8　リソースアダプタの設定の流れ（J2EEリソースアダプタとしてデプロイして使用する場合）

3.3.9　リソースアダプタの設定の流れ（J2EEアプリケーションに含めて使用する場合）

3.3.10　リソースアダプタの設定の流れ（Inboundで使用する場合）

3.3.11　リソースアダプタの設定の流れ（コネクションプールのクラスタ化をする場合）

3.3.12　リソースアダプタ以外を使用する接続の設定

3.3.13　リソースアダプタについての注意事項

3.3.1　リソースへの接続方法

アプリケーションサーバでは，リソースの種類によって，接続にリソースアダプタを使用するものと，リソースアダプタを使用しないものがあります。それぞれのリソースへの接続方法の概要を，リソースの種類ごとに説明します。

＜この項の構成＞

(1)　接続にリソースアダプタを使用するリソース

(2)　接続にリソースアダプタを使用しないリソース

(1)　接続にリソースアダプタを使用するリソース

接続にリソースアダプタを使用するリソースを次に示します。

データベース

データベースと接続できます。データベースと接続するためには，リソースアダプタとしてDB Connectorを使用します。

DB Connectorで接続できるのは，次のデータベースです。

HiRDB

Oracle

SQL Server※

XDM/RD E2

注※　SQL Serverと接続できるのはWindowsの場合だけです。

データベースとの接続については，「3.6.1　DB Connectorによる接続の概要」を参照してください。

データベース上のキュー

Cosminexus RMで使用するデータベース上のキューと接続できます。データベース上のキューと接続するためには，リソースアダプタとしてDB Connector for Cosminexus RMおよびCosminexus RMを使用します。

DB Connector for Cosminexus RMおよびCosminexus RMで接続できるのは，次のデータベースです。

HiRDB

Oracle

データベース上のキューとの接続については，「3.7.1　DB Connector for Cosminexus RMとCosminexus RMによる接続の概要」を参照してください。

OpenTP1

OpenTP1のSPP，TP1/Message QueueとOutboundで接続できます。OpenTP1のSPPとOutboundで接続するには，リソースアダプタとしてuCosminexus TP1 Connectorを使用します。TP1/Message Queueと接続するには，リソースアダプタとしてTP1/Message Queue - Accessを使用します。

また，OpenTP1のSUPからアプリケーションサーバにInboundで接続することもできます。OpenTP1のSUPからInboundで接続するには，リソースアダプタとしてTP1インバウンドアダプタを使用します。

OpenTP1との接続の詳細については，接続に使用するリソースアダプタごとに説明しています。参照先を次の表に示します。

表3-3　OpenTP1との接続の詳細説明の参照先

接続方法 | 参照先
uCosminexus TP1 Connectorを使用した接続 | 「3.8.1　uCosminexus TP1 Connectorによる接続」
TP1/Message Queue - Accessを使用した接続 | 「3.8.2　TP1/Message Queue - Accessによる接続」
TP1インバウンドアダプタを使用した接続 | 「4.　OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）」

CJMSPブローカー

Cosminexus JMSプロバイダの機能を使用する場合，CJMSPブローカーと接続できます。CJMSPブローカーと接続するためには，リソースアダプタとしてCJMSPリソースアダプタを使用します。

CJMSPリソースアダプタを使用したCJMSPブローカーとの接続については，「7.　Cosminexus JMSプロバイダ」を参照してください。

そのほかのリソース

リソースの種類に関係なく，Connector 1.0仕様またはConnector 1.5仕様に準拠したリソースアダプタで接続できるリソースに接続できます。

使用できるリソースアダプタについては，「3.13　そのほかのリソースとの接続」を参照してください。また，Connector 1.5仕様に準拠したリソースアダプタを使用する場合に，アプリケーションサーバで使用できる機能については，「3.16　そのほかのリソースアダプタの機能（Connector 1.5仕様に準拠するリソースアダプタの場合）」を参照してください。

(2)　接続にリソースアダプタを使用しないリソース

接続にリソースアダプタを使用しないリソースについて次に示します。

SMTPサーバ

SMTPサーバと接続できます。SMTPサーバとの接続については，「3.11　SMTPサーバとの接続」を参照してください。

JavaBeans

リソースとしてJavaBeansリソースを利用できます。JavaBeansリソースの利用については，「3.12　JavaBeansリソースの利用」を参照してください。

3.3.2　リソースアダプタの種類

アプリケーションサーバでは，Connector 1.0仕様またはConnector 1.5仕様に準拠したリソースアダプタを使用できます。

ここでは，それぞれの仕様に準拠したリソースアダプタについて説明します。また，リソースアダプタのDDのスキーマの違いについても説明します。

＜この項の構成＞

(1)　Connector 1.0仕様に準拠したリソースアダプタ

(2)　Connector 1.5仕様に準拠したリソースアダプタ

(3)　Connector 1.0仕様とConnector 1.5仕様のリソースアダプタのスキーマの違い

(4)　リソースアダプタごとのRARファイルの種類

(1)　Connector 1.0仕様に準拠したリソースアダプタ

アプリケーションサーバを含む日立の製品では，Connector 1.0仕様に準拠したリソースアダプタを提供しています。

アプリケーションサーバでは，次のリソースアダプタを使用できます。

DB Connector

DB Connector for Cosminexus RMおよびCosminexus RM

uCosminexus TP1 Connector

TP1/Message Queue - Access

これらのリソースアダプタでは，Connector 1.0仕様に対応する機能が使用できます。

なお，DB ConnectorおよびDB Connector for Cosminexus RMでは，Connector 1.0仕様に対応する機能に加えて，アプリケーションサーバで追加された機能を使用できます。使用できる機能については，「3.3.4　リソースアダプタの機能」を参照してください。

ポイント

アプリケーションサーバでは，これらのリソースアダプタ以外にも，標準仕様のConnector 1.0仕様に準拠したリソースアダプタを使用できます。ただし，標準仕様のConnector 1.0仕様に準拠したリソースアダプタを使用する場合，DD（ra.xml）の次のタグの設定内容は無視されます。

<security-permission>
セキュリティの設定にはserver.policyファイルを使用してください。

<authentication-mechanism>
設定内容に関係なく，BasicPasswordが適用されます。

(2)　Connector 1.5仕様に準拠したリソースアダプタ

アプリケーションサーバでは，Connector 1.5仕様に準拠したリソースアダプタを使用できます。アプリケーションサーバで使用できるのは，Connector 1.5仕様の規約のうち，次の規約に対応した機能です。

Lifecycle Management

Work Management

メッセージインフロー

トランザクションインフロー

アプリケーションサーバでは，次のリソースアダプタを提供しています。

TP1インバウンドアダプタ

CJMSPリソースアダプタ

使用できる機能については，「3.3.4　リソースアダプタの機能」を参照してください。

また，Connector 1.5仕様に準拠したリソースアダプタについては，「3.13.1　そのほかのリソースとの接続に使用するリソースアダプタ」を参照してください。

(3)　Connector 1.0仕様とConnector 1.5仕様のリソースアダプタのスキーマの違い

Connector 1.0仕様に準拠したリソースアダプタと，Connector 1.5仕様に準拠したリソースアダプタの，DDのスキーマの違いについて説明します。リソースアダプタのDDは，ra.xmlです。

Connector 1.0仕様のスキーマからConnector 1.5仕様のスキーマに対する主な変更点を次の表に示します。ここで示す以外の変更点については，Connector 1.5仕様を参照してください。

表3-4　Connector 1.0仕様のスキーマからConnector 1.5仕様のスキーマに対する主な変更点

Connector 1.5仕様で変更になった内容
Connector 1.5仕様のDDの内容

javax.resource.spi.ResourceAdapterインタフェースの実装クラスの指定
<connector>-<resourceadapter>-<resourceadapter-class>タグ
<connector>-<resourceadapter>-<config-property>タグ

Outboundリソースアダプタの指定
<connector>-<resourceadapter>-<outbound-resourceadapter>タグ

Inboundリソースアダプタの指定
<connector>-<resourceadapter>-<inbound-resourceadapter>タグ

adminobjectの指定
<connector>-<resourceadapter>-<adminobject>タグ

Connector 1.5仕様で変更になった内容の概要を説明します。

javax.resource.spi.ResourceAdapterインタフェースの実装クラスの指定

javax.resource.spi.ResourceAdapterインタフェースの実装クラスと，そのコンフィグレーションプロパティを指定する要素が追加されました。javax.resource.spi.ResourceAdapterインタフェースの追加に伴って実現できる機能については，「3.16.1　リソースアダプタのライフサイクル管理」および「3.16.2　リソースアダプタのワーク管理」を参照してください。

Outboundリソースアダプタの指定

Outboundのリソースアダプタを明示的に定義するための要素が追加されました。

なお，Outboundリソースアダプタでは，一つのDD内にコネクション定義を複数指定できます。コネクション定義の複数指定については，「3.16.6　コネクション定義の複数指定」を参照してください。

Inboundリソースアダプタの指定

Inboundのリソースアダプタを明示的に定義するための要素が追加されました。

adminobjectの指定

管理対象オブジェクトについての情報を指定する要素が追加されました。

(4)　リソースアダプタごとのRARファイルの種類

プロパティを定義するリソースアダプタは，接続するリソースや使用するトランザクションの種類などによって異なります。ここでは，次の場合に使用するリソースアダプタについて説明します。

DB Connectorを使用する場合

DB Connector for Cosminexus RMとCosminexus RMを使用する場合

ほかのリソースアダプタを使用する場合

(a)　DB Connectorを使用する場合

DB Connectorは，接続するデータベースの種類や使用するトランザクションの種類によって，ファイルが異なります。DB Connectorの種類を次の表に示します。

表3-5　DB Connectorの種類

RARファイル名 | 説明
DBConnector_HiRDB_Type4_CP.rar | HiRDB Type4 JDBC Driverを使用して，ローカルトランザクションまたはトランザクション管理なしで，HiRDB，XDM/RD E2に接続する場合に選択します。
DBConnector_HiRDB_Type4_XA.rar | HiRDB Type4 JDBC Driverを使用して，グローバルトランザクションで，HiRDBに接続する場合に選択します。
DBConnector_Oracle_CP.rar | Oracle JDBC Thin Driverを使用して，ローカルトランザクションまたはトランザクション管理なしで，Oracleに接続する場合に選択します。
DBConnector_Oracle_XA.rar | Oracle JDBC Thin Driverを使用して，グローバルトランザクションで，Oracleに接続する場合に選択します。
DBConnector_SQLServer_CP.rar | SQL Server 2000 Driver for JDBCを使用して，ローカルトランザクションまたはトランザクション管理なしで，SQL Server 2000（Windowsの場合だけ）に接続する場合に選択します。
DBConnector_SQLServer2005_CP.rar | SQL Server 2005 JDBC Driverを使用して，ローカルトランザクションまたはトランザクション管理なしで，SQL Server 2005（Windowsの場合だけ）に接続する場合に選択します。
SQL Server JDBC Driverを使用して，ローカルトランザクションまたはトランザクション管理なしで，SQL Server 2008（Windowsの場合だけ）に接続する場合に選択します。
DBConnector_CP_ClusterPool_Root.rar | コネクションプールのクラスタ化機能のルートリソースアダプタです。ルートリソースアダプタに属するメンバリソースアダプタが，ローカルトランザクションまたはトランザクション管理なしで，Oracleに接続する場合に選択します。
DBConnector_Oracle_CP_ClusterPool_Member.rar | コネクションプールのクラスタ化機能のメンバリソースアダプタです。Oracle JDBC Thin Driverを使用して，ローカルトランザクションまたはトランザクション管理なしで，Oracleに接続する場合に選択します。なお，J2EEアプリケーションのリソースリファレンスに設定して使用できません。

注　新規に，DB ConnectorのRARファイルを使用する場合，アプリケーションサーバで提供するConnector属性ファイルのテンプレートファイルを使用して，プロパティを定義できます。Connector属性ファイルのテンプレートファイルは，すべてのDB ConnectorのRARファイルに対して提供しています。提供しているテンプレートファイルについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1.14　Connector属性ファイルのテンプレートファイル」を参照してください。

(b)　DB Connector for Cosminexus RMとCosminexus RMを使用する場合

Cosminexus RMと連携してデータベースに接続する場合には，Cosminexus RM連携用のリソースアダプタ（DB Connector for Cosminexus RM）と，Cosminexus RMで提供するリソースアダプタの両方をインポートする必要があります。Cosminexus RMで提供するリソースアダプタについては，マニュアル「Cosminexus Reliable Messaging」を参照してください。

DB Connector for Cosminexus RMは，使用するトランザクションの種類や接続するデータベースの種類によって，ファイルが異なります。DB Connector for Cosminexus RMの種類を次の表に示します。

表3-6　DB Connector for Cosminexus RMの種類

RARファイル名 | 説明
DBConnector_HiRDB_Type4_CP_Cosminexus_RM.rar | HiRDB Type4 JDBC Driverを使用して，ローカルトランザクションまたはトランザクション管理なしで，HiRDBに接続する場合に選択します。
DBConnector_HiRDB_Type4_XA_Cosminexus_RM.rar | HiRDB Type4 JDBC Driverを使用して，グローバルトランザクションで，HiRDBに接続する場合に選択します。
DBConnector_Oracle_CP_Cosminexus_RM.rar | Oracle JDBC Thin Driverを使用して，ローカルトランザクションまたはトランザクション管理なしで，Oracleに接続する場合に選択します。
DBConnector_Oracle_XA_Cosminexus_RM.rar | Oracle JDBC Thin Driverを使用して，グローバルトランザクションで，Oracleに接続する場合に選択します。

注　新規に，DB Connector for Cosminexus RMのRARファイルを使用する場合，アプリケーションサーバで提供するConnector属性ファイルのテンプレートファイルを使用して，プロパティを定義できます。Connector属性ファイルのテンプレートファイルは，すべてのDB ConnectorのRARファイルに対して提供しています。提供しているテンプレートファイルについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1.14　Connector属性ファイルのテンプレートファイル」を参照してください。

ポイント

DB Connector for Cosminexus RMとCosminexus RMを使用して同一トランザクション内でJDBCとJMSのアクセスを行う場合に，同じ物理コネクションを共有することで，ローカルトランザクションの適用，グローバルトランザクションの1相コミット決着ができます。1相コミット決着のための条件を次に示します。

DB Connector for Cosminexus RMとCosminexus RMで使用するデータベースシステムが同一であり，かつサインオン方式とセキュリティ情報（ユーザ名，パスワード）が同一である。

リソースアダプタを使用するJ2EEアプリケーションの属性ファイル（Session Bean属性ファイル，Entity Bean属性ファイルなど）で<res-sharing-scope>タグに「Shareable」を指定している。

(c)　ほかのリソースアダプタを使用する場合

OpenTP1のSPPとOutboundで接続する場合には，uCosminexus TP1 ConnectorおよびTP1/Client/Jの提供するリソースアダプタを使用します。詳細については，uCosminexus TP1 Connectorのドキュメント，およびマニュアル「OpenTP1 クライアント使用の手引 TP1/Client/J編」を参照してください。

OpenTP1のSUPからInboundで接続する場合には，TP1インバウンドアダプタを使用します。詳細については，「4.　OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）」を参照してください。

また，Cosminexus JMSプロバイダを使用する場合，CJMSPブローカーと接続するために，CJMSPリソースアダプタを使用します。詳細については，「7.　Cosminexus JMSプロバイダ」を参照してください。

なお，新規にTP1インバウンドアダプタまたはCJMSPリソースアダプタのRARファイルを使用する場合，アプリケーションサーバで提供するテンプレートファイルを使用して，プロパティを定義できます。詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1.14　Connector属性ファイルのテンプレートファイル」を参照してください。

TP1/Message Queueと接続する場合には，TP1/Message Queue - Accessの提供するリソースアダプタを使用します。詳細については，マニュアル「OpenTP1 Version 7 メッセージキューイングアクセス機能 TP1/Message Queue - Access 使用の手引」を参照してください。

また，アプリケーションサーバでは，Connector 1.0仕様またはConnector 1.5仕様に準拠したリソースアダプタを使用して，任意のリソースに接続できます。これらのリソースアダプタを使用する場合は，リソースアダプタのドキュメントを参照してください。

3.3.3　リソースアダプタの使用方法

ここでは，リソースアダプタの使用方法について説明します。リソースアダプタを使用してリソースと接続する方法には，次の2種類があります。

J2EEリソースアダプタとしてデプロイして使用する方法

J2EEアプリケーションに含めて使用する方法

ここでは，それぞれの方法について説明します。

＜この項の構成＞

(1)　J2EEリソースアダプタとしてデプロイして使用する

(2)　J2EEアプリケーションに含めて使用する

(3)　使用方法ごとに使用できるリソースアダプタ

(1)　J2EEリソースアダプタとしてデプロイして使用する

J2EEサーバにインポートしたリソースアダプタを，共有スタンドアロンモジュールとしてデプロイします。そのJ2EEサーバ上で動作するすべてのJ2EEアプリケーションで使用できるようになります。J2EEサーバ上に配置されたリソースアダプタをJ2EEリソースアダプタといいます。

(2)　J2EEアプリケーションに含めて使用する

リソースアダプタをJ2EEアプリケーションに含めて使用します。同じJ2EEアプリケーションに含まれるEJBやWARから，リソースアダプタを使用できます。リソースアダプタをJ2EEアプリケーションに含めて使用する手順については，「3.3.9　リソースアダプタの設定の流れ（J2EEアプリケーションに含めて使用する場合）」を参照してください。

なお，J2EEアプリケーションに含めることができるリソースアダプタには，制限があります。詳細については，「(3)　使用方法ごとに使用できるリソースアダプタ」を参照してください。

(3)　使用方法ごとに使用できるリソースアダプタ

リソースアダプタは，Application Serverのバージョンに適したリソースアダプタに統一する必要があります。また，アプリケーションサーバでは，Connector 1.0仕様，およびConnector 1.5仕様に準拠したリソースアダプタをデプロイして使用できます。ただし，J2EEアプリケーションに含めて使用する場合，次のリソースアダプタは使用できません。

XATransactionに設定したリソースアダプタ

ネイティブライブラリを含むリソースアダプタ

起動順序の制御が必要なリソースアダプタ

アプリケーションサーバ独自の機能を使用しているリソースアダプタ

アプリケーションサーバが提供するリソースアダプタの使用方法を次の表に示します。

表3-7　アプリケーションサーバが提供するリソースアダプタの使用方法

リソースアダプタ | 使用方法
リソースアダプタをJ2EEリソースアダプタとしてデプロイして使用する | リソースアダプタをJ2EEアプリケーションに含めて使用する
DB Connector | NoTransactionまたはLocalTransactionに設定 | ○ | ○
XATransactionに設定 | ○ | －
クラスタ構成 | ルートリソースアダプタ | ○ | －
メンバリソースアダプタ | ○ | －
uCosminexus TP1 Connector | NoTransactionまたはLocalTransactionに設定 | ○ | ○
XATransactionに設定 | ○ | －
TP1/Message Queue - Access | ○ | －
Cosminexus RM | Cosminexus RM（データベースなし） | ○ | －
Cosminexus RM（データベースあり） | ○ | －
DB Connector for Cosminexus RM | ○ | －
TP1インバウンドアダプタ※ | ○ | －
CJMSPリソースアダプタ | ○ | －

（凡例）　○：使用できる　－：該当しない

注※　TP1インバウンドアダプタは，次の製品だけで使用できます。

uCosminexus Application Server Enterprise

uCosminexus Developer Professional

uCosminexus Service Platform

uCosminexus Service Architect

使用できないリソースアダプタに対して次の操作をすると，エラーメッセージが出力されて，操作に失敗します。

J2EEアプリケーションに含めてインポートする

J2EEアプリケーションに含めて接続テストまたは開始する

3.3.4　リソースアダプタの機能

ここでは，次のリソースアダプタの機能について説明します。

DB Connector

コネクションプールのクラスタ化で使用するDB Connector（ルートリソースアダプタおよびメンバリソースアダプタ）

DB Connector for Cosminexus RM

TP1インバウンドアダプタ

CJMSPリソースアダプタ

そのほかのConnector 1.5仕様に準拠したリソースアダプタ

なお，これ以外のリソースアダプタの機能については，使用するリソースアダプタのドキュメントを参照してください。

使用できる機能をリソースアダプタの種類ごとに次の表に示します。それぞれの機能の詳細については，参照先の説明を参照してください。

表3-8　リソースアダプタの種類ごとの使用できる機能

機能 | リソースアダプタの種類 | 参照先
DB Connector | ルートリソースアダプタ | メンバリソースアダプタ | DB Connector for Cosminexus RM | TP1インバウンドアダプタ | CJMSPリソースアダプタ | そのほかのConnector 1.5仕様に準拠したリソースアダプタ※1
コネクションプーリング | ○ | × | ◎ | ○ | － | ○ | ○ | 3.14.1
コネクションプールのウォーミングアップ | ○ | × | ○ | ○ | － | ○ | ○ | 3.14.2
コネクション数調節機能 | ○ | × | ○ | ○ | － | ○ | ○
コネクションシェアリング・アソシエーション | ○ | × | ○ | ○ | － | × | ○ | 3.14.3
ステートメントプーリング | ○ | × | ○ | ○ | － | × | ○ | 3.14.4
DataSourceオブジェクトのキャッシング | ○ | ○ | × | ○ | － | × | × | 3.14.7
DB Connectorのコンテナ管理でのサインオンの最適化 | ○ | × | ○ | ○ | － | × | × | 3.14.8
コネクションの障害検知 | ○ | × | ◎ | ○ | － | × | ○ | 3.15.1
コネクション枯渇時のコネクション取得待ち | ○ | × | ◎ | ○ | － | ○ | ○ | 3.15.2
コネクションの取得リトライ | ○ | × | × | ○ | － | ○ | ○ | 3.15.3
コネクションプールの情報表示 | ○ | × | ○ | ○ | － | ○ | × | 3.15.4
コネクションプールのクリア | ○ | × | ○ | ○ | － | ○ | ○ | 3.15.5
コネクションの自動クローズ | ○ | × | ○ | ○ | － | × | ○ | 3.15.6
コネクションスイーパ | ○ | × | ○ | ○ | － | ○ | ○ | 3.15.7
ステートメントキャンセル | ○ | × | ○ | ○ | － | × | ○ | 3.15.8
障害調査用SQLの出力 | ◎ | × | ◎ | ◎ | － | × | × | 3.15.10
オブジェクトの自動クローズ | ○ | × | ○ | ○ | － | × | × | 3.15.11
リソースアダプタのライフサイクル管理 | × | × | × | × | ○ | ○ | ○ | 3.16.1
リソースアダプタのワーク管理 | × | × | × | × | ○ | ○ | ○ | 3.16.2
メッセージインフロー | × | × | × | × | ○ | ○ | ○ | 3.16.3
トランザクションインフロー | × | × | × | × | ○ | × | × | 3.16.4
管理対象オブジェクトのルックアップ | × | × | × | × | － | ○ | ○ | 3.16.5
コネクション定義の複数指定 | × | × | × | × | － | ○ | ○ | 3.16.6
コネクションプールの一時停止 | × | × | ○ | × | － | × | × | 3.17.3
コネクションプールの再開 | × | × | ○ | × | － | × | ×
コネクションプールの状態表示 | ○ | × | ○ | ○ | － | × | ○
リソースへの接続テスト | ○ | ○ | ○ | ○ | － | ○ | ○ | 3.18
J2EEリソースへの別名付与 | ○ | ○ | × | ○ | － | ○ | ○ | 2.4
コネクションIDのPRFトレース | ○ | ○ | ○ | ○ | － | － | － | ※2

（凡例）　◎：必ず有効になる　○：使用できる　×：使用できない　－：該当しない

注※1　この表で示しているのはアプリケーションサーバが提供する機能が使用できるかどうかです。リソースアダプタが提供する機能については，使用するリソースアダプタのドキュメントを参照してください。

注※2　マニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「4.6　性能解析トレース」を参照してください。

3.3.5　リソースアダプタ以外の機能

ここでは，リソースアダプタ以外で実現される機能について説明します。ここで説明する機能は，リソースアダプタの種類に関係なく使用できます。

リソースアダプタ以外で実現される機能を，次の表に示します。それぞれの機能の詳細については，参照先の説明を参照してください。

表3-9　リソースアダプタ以外の機能

機能 | 参照先
ライトトランザクション | 3.14.5
インプロセストランザクションサービス | 3.14.6
トランザクションタイムアウトとステートメントキャンセル | 3.15.8
トランザクションリカバリ | 3.15.9

3.3.6　リソースに接続するための実装

アプリケーションからリソースに接続するには，Enterprise Beanやサーブレットでリソースへの参照を取得する必要があります。リソースへの参照を取得する方法として，ルックアップを使用する方法とDI（Dependency Injection）を使用する方法があります。

＜この項の構成＞

(1)　ルックアップを使用してリソースへの参照を取得する方法

(2)　DIを使用してリソースへの参照を取得する方法

(3)　リソースへの接続を実装する場合の注意事項

(1)　ルックアップを使用してリソースへの参照を取得する方法

ルックアップを使用する場合，次の手順でアプリケーションからリソースに接続します。

リソースに接続するコネクションを取得するためのファクトリクラスを，JNDIを使用してルックアップします。
ルックアップする名前は，Enterprise BeanやサーブレットのDDで指定します。該当するタグは<resource-ref>タグ中の<res-ref-name>タグです。

コネクションのファクトリクラスを使用して，コネクションを取得します。

取得したコネクションを使用して，リソースに接続します。

使用済みのコネクションをクローズします。

コネクションプーリングを使用している場合は，手順2.でプーリングされているコネクションが取得され，手順4.でコネクションがプールに返却されます。ユーザプログラムでコネクションプーリングを意識したコーディングは必要ありません。

(2)　DIを使用してリソースへの参照を取得する方法

DIを使用してリソースへの参照を取得する場合，DDの定義は不要となります。DIの概要およびDI使用時の注意事項については，「11.4　DIの使用」を参照してください。

(3)　リソースへの接続を実装する場合の注意事項

ユーザプログラムでリソースへのコネクションを取得した場合，使用後には必ずクローズしてください。具体的には，例外などが発生した場合にも必ずクローズするように，finally節でコネクションをクローズしてください。

なお，finalizeメソッドが呼ばれるタイミングはJavaVMのガーベージコレクションのタイミングに依存するので，finalizeメソッドでコネクションをクローズする設計にはしないでください。ユーザプログラムでコネクションが正しくクローズされない場合，取得できるコネクションの最大数に達してしまい，それ以上のコネクションが取得できなくなるおそれがあります。

3.3.7　リソースアダプタの設定方法

リソースアダプタの設定方法には，次の二つの方法があります。

J2EEリソースアダプタとしてデプロイして設定する方法
リソースアダプタを，直接J2EEサーバにデプロイして設定する方法です。

J2EEアプリケーションに含めて設定する方法
J2EEアプリケーションに含めて使用するリソースアダプタに対して設定する方法です。

参考

リソースアダプタがDB Connector，TP1インバウンドアダプタ，またはCJMSPリソースアダプタの場合，アプリケーションサーバが提供するConnector属性ファイルのテンプレートファイルを使用できます。テンプレートファイルを使用すると，リソースアダプタをインポートする前に，Connector属性ファイルを編集しておくことができます。このため，編集対象のConnector属性ファイルをサーバ管理コマンド（cjgetrarpropコマンドまたはcjgetrespropコマンド）で取得する操作が不要になります。

Connector属性ファイルのテンプレートファイルの格納先，およびテンプレートファイル使用時の注意事項については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1.14　Connector属性ファイルのテンプレートファイル」を参照してください。

注意

旧バージョンのアプリケーションサーバで使用していたリソースアダプタを使用する場合，リソースアダプタの移行処理が必要です。リソースの移行方法については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「12.1.8　リソースアダプタの移行コマンドの実行」を参照してください。

3.3.8　リソースアダプタの設定の流れ（J2EEリソースアダプタとしてデプロイして使用する場合）

ここでは，リソースアダプタをJ2EEリソースアダプタとしてデプロイして使用する場合の，次の流れについて説明します。

リソースアダプタの新規設定の流れ

リソースアダプタの設定変更の流れ

リソースアダプタの入れ替えの流れ

リソースアダプタの設定には，サーバ管理コマンドを使用します。

＜この項の構成＞

(1)　リソースアダプタの新規設定の流れ

(2)　リソースアダプタの設定変更の流れ

(3)　リソースアダプタの入れ替えの流れ

(1)　リソースアダプタの新規設定の流れ

データベースやほかのリソースに接続する場合のリソースアダプタの新規設定の流れを次の図に示します。

図3-2　リソースアダプタの新規設定の流れ

図中の1.～4.について説明します。

サーバ管理コマンドを使用してリソースアダプタをインポートします。
cjimportresコマンドを使用して，リソースアダプタをインポートします。
DB Connectorを使用してデータベースに接続する場合と，ほかのリソースアダプタを使用してOpenTP1などの各種リソースに接続する場合では，インポートするRARファイルが異なります。インポートするリソースアダプタについては，「3.3.2　リソースアダプタの種類」を参照してください。

サーバ管理コマンドを使用してリソースアダプタをデプロイします。
cjdeployrarコマンドを使用して，リソースアダプタをデプロイします。
リソースアダプタは，デプロイするとJ2EEリソースアダプタとして使用できます。J2EEリソースアダプタとは，J2EEサーバに共有スタンドアロンモジュールとして配備したリソースアダプタのことです。サーバ管理コマンドでインポートしたリソースアダプタをデプロイすると，そのJ2EEサーバ上で動作するすべてのJ2EEアプリケーションから使用できるようになります。

サーバ管理コマンドを使用してリソースアダプタのプロパティを定義します。
cjgetrarpropコマンドでConnector属性ファイルを取得し，ファイル編集後に，cjsetrarpropコマンドで編集内容を反映させます。
使用する機能ごとに設定するリソースアダプタのプロパティについては，それぞれ次の個所を参照してください。

リソース接続とトランザクション管理機能を使用するための設定
「3.4.12　実行環境での設定」

パフォーマンスチューニングのための機能
「3.14.10　実行環境での設定」

フォールトトレランスのための機能
「3.15.13　実行環境での設定」

J2EEリソースの別名の設定
「2.4.6　J2EEリソースの別名の設定」

サーバ管理コマンドを使用してリソースアダプタの接続テストを実施します。
cjtestresコマンドを使用して，リソースアダプタの接続テストを実施します。リソースごとの接続テストでの検証内容については，「3.18　リソースへの接続テスト」を参照してください。

注意

DB Connector for Cosminexus RMとCosminexus RMを使用してデータベースに接続する場合の接続テストには次のような順序があります。

DB Connector for Cosminexus RMを開始します。

Cosminexus RMの接続テストを実施します。

Cosminexus RMを開始します。

DB Connector for Cosminexus RMの接続テストを実施します。

DB Connector for Cosminexus RMの場合の，J2EEリソースアダプタの接続テストについては，マニュアル「Cosminexus Reliable Messaging」の「2.7　DB Connector for Cosminexus RMの機能」を参照してください。

サーバ管理コマンドでの操作については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「3.　サーバ管理コマンドの基本操作」を参照してください。また，コマンドについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「2.4　J2EEサーバで使用するリソース操作コマンド」を参照してください。属性ファイルについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.　リソースの設定で使用する属性ファイル」を参照してください。

注意

リソースアダプタを使用する場合，J2EEアプリケーションからリソースアダプタへのリファレンスを解決しておく必要があります。リソースアダプタを使用しているJ2EEアプリケーションのプロパティを定義するときに，J2EEアプリケーションからリソースアダプタへのリファレンスを解決しておいてください。

参考

次のような場合，リソースアダプタをエクスポート・インポートすることで，効率良くリソースアダプタを設定できます。

開発環境で設定したリソースアダプタをエクスポートして，運用環境にインポートして使用する場合

運用環境ですでに動いているリソースアダプタをエクスポートして，増設したJ2EEサーバにインポートして使用する場合

エクスポートとインポートはcjexportrarとcjimportresで実行します。

なお，アプリケーションサーバのバージョンやプラットフォームが異なるホスト間では，リソースアダプタをエクスポート・インポートして使用することはできません。リソースアダプタをエクスポートするホストと，アプリケーションサーバのバージョンやプラットフォームが異なるホストでリソースアダプタを設定する場合は，リソースアダプタを新規に設定してください。

(2)　リソースアダプタの設定変更の流れ

デプロイ済みのリソースアダプタの設定を変更する場合の流れについて説明します。設定変更の流れを次の図に示します。

図3-3　リソースアダプタの設定変更の流れ

図中の1.～2.について説明します。

サーバ管理コマンドを使用して，リソースアダプタを停止します。
cjstoprarコマンドを使用してリソースアダプタを停止します。なお，リソースアダプタを停止する前に，そのリソースアダプタを使用しているJ2EEアプリケーションをすべて停止してください。

サーバ管理コマンドを使用してリソースアダプタのプロパティを定義します。
リソースアダプタはデプロイ済みであるため，cjgetrarpropコマンドを使用して属性ファイルを取得し，ファイル編集後に，cjsetrarpropコマンドで編集内容を反映させます。

(3)　リソースアダプタの入れ替えの流れ

リソースアダプタを入れ替える場合の流れについて説明します。リソースアダプタの入れ替えの流れを次の図に示します。

図3-4　リソースアダプタの入れ替えの流れ

図中の1.～3.について説明します。

J2EEサーバを停止します。
cjstopsvコマンドを使用してJ2EEサーバを停止します。

リソースアダプタを入れ替えます。
cjrarupdateコマンドを使用して，リソースアダプタを入れ替えます。

J2EEサーバを起動します。
cjstartsvコマンドを使用してJ2EEサーバを起動します。

cjrarupdateコマンドを使用しないでリソースアダプタを入れ替えることもできます。cjrarupdateコマンドを使用しないでリソースアダプタを入れ替えるときの流れを次の図に示します。

図3-5　リソースアダプタの入れ替えの流れ（cjrarupdateコマンドを使用しない場合）

図中の1.～7.について説明します。

サーバ管理コマンドを使用して，リソースアダプタを停止します。
cjstoprarコマンドを使用して入れ替えるリソースアダプタを停止します。なお，リソースアダプタを停止する前に，そのリソースアダプタを使用しているJ2EEアプリケーションをすべて停止してください。

J2EEサーバを再起動します。
cjstopsvコマンドを使用してJ2EEサーバを停止し，cjstartsvコマンドを使用してJ2EEサーバを起動します。

サーバ管理コマンドを使用して，リソースアダプタのプロパティ定義を退避します。
リソースアダプタのプロパティ定義を引き継ぐ場合は，cjgetrarpropコマンド，またはcjgetrespropコマンドを使用して，リソースアダプタのConnector属性ファイルを取得します。

サーバ管理コマンドを使用してリソースアダプタをアンデプロイします。
cjundeployrarコマンドを使用して，入れ替えるリソースアダプタをアンデプロイします。

サーバ管理コマンドを使用してリソースアダプタを削除します。
cjdeleteresコマンドを使用して，入れ替えるリソースアダプタを削除します。

サーバ管理コマンドを使用してリソースアダプタを設定します。
「(1)　リソースアダプタの新規設定の流れ」に従って，リソースアダプタを設定します。リソースアダプタのプロパティ定義を引き継ぐ場合は，3.で取得したConnector属性ファイルを使用します。

サーバ管理コマンドを使用して，リソースアダプタを開始します。
cjstartrarコマンドを使用してリソースアダプタを開始します。なお，リソースアダプタを開始したあとに，リソースアダプタを使用するJ2EEアプリケーションを開始してください。

3.3.9　リソースアダプタの設定の流れ（J2EEアプリケーションに含めて使用する場合）

リソースアダプタの設定には，サーバ管理コマンドを使用します。ここでは，リソースアダプタをJ2EEアプリケーションに含めて使用する場合のリソースアダプタの設定の流れについて説明します。

なお，リソースアダプタをアプリケーションに含めて使用する場合のリソースアダプタの設定方法には，次の二つの方法があります。

リソースアダプタを含めたJ2EEアプリケーションをJ2EEサーバにインポートする方法

J2EEサーバにインポート済みのJ2EEアプリケーションにリソースアダプタを追加する方法

ここでは，それぞれの方法について説明します。

なお，J2EEアプリケーションに含められるリソースアダプタには，制限があります。J2EEアプリケーションに含められるリソースアダプタについては，「3.3.3　リソースアダプタの使用方法」を参照してください。

＜この項の構成＞

(1)　リソースアダプタを含めたJ2EEアプリケーションをJ2EEサーバにインポートする方法

(2)　インポート済みのJ2EEアプリケーションにリソースアダプタを追加する方法

(1)　リソースアダプタを含めたJ2EEアプリケーションをJ2EEサーバにインポートする方法

リソースアダプタのRARファイルを含めてJ2EEアプリケーションを作成して，そのEARファイルをJ2EEサーバにインポートする方法です。この方法の概要を次の図に示します。

図3-6　リソースアダプタを含めたJ2EEアプリケーションをJ2EEサーバにインポートする方法の概要

リソースアダプタを含めたJ2EEアプリケーションをJ2EEサーバにインポートする流れを次の図に示します。

図3-7　リソースアダプタを含めたJ2EEアプリケーションをJ2EEサーバにインポートする流れ

図中の1.～4.について説明します。

サーバ管理コマンドを使用してリソースアダプタのRARファイルをJ2EEアプリケーションのEARファイルに追加します。
cjaddappコマンドを使用して，リソースアダプタのRARファイルをJ2EEアプリケーションのEARファイルに追加します。
EARファイルに含められるリソースアダプタには，制限があります。EARファイルに含められるリソースアダプタについては，「3.3.3　リソースアダプタの使用方法」を参照してください。

サーバ管理コマンドを使用してJ2EEアプリケーションをインポートします。
cjimportappコマンドを使用して，J2EEアプリケーションをインポートします。

サーバ管理コマンドを使用してリソースアダプタのプロパティを定義します。
cjgetapppropコマンドでConnector属性ファイルを取得し，ファイル編集後に，cjsetapppropコマンドで編集内容を反映させます。
使用する機能ごとに設定するリソースアダプタのプロパティについては，それぞれ次の個所を参照してください。

リソース接続とトランザクション管理機能を使用するための設定
「3.4.12　実行環境での設定」

パフォーマンスチューニングのための機能
「3.14.10　実行環境での設定」

フォールトトレランスのための機能
「3.15.13　実行環境での設定」

J2EEリソースの別名の設定
「2.4.6　J2EEリソースの別名の設定」

サーバ管理コマンドを使用してリソースアダプタの接続テストを実施します。
cjtestresコマンドを使用して，リソースアダプタの接続テストを実施します。リソースごとの接続テストでの検証内容については，「3.18　リソースへの接続テスト」を参照してください。

(2)　インポート済みのJ2EEアプリケーションにリソースアダプタを追加する方法

リソースアダプタ（RARファイル）をJ2EEサーバにインポートしてから，同じJ2EEサーバにインポート済みのJ2EEアプリケーションにリソースアダプタを追加する方法です。この方法の概要を次の図に示します。

図3-8　インポート済みのJ2EEアプリケーションにリソースアダプタを追加する方法の概要

インポート済みのJ2EEアプリケーションにリソースアダプタを追加する流れを次の図に示します。

図3-9　インポート済みのJ2EEアプリケーションにリソースアダプタを追加する流れ

図中の1.～5.について説明します。

サーバ管理コマンドを使用してJ2EEアプリケーションをインポートします。
cjimportappコマンドを使用して，J2EEアプリケーションをインポートします。

サーバ管理コマンドを使用してリソースアダプタをインポートします。
cjimportresコマンドを使用して，リソースアダプタをインポートします。

サーバ管理コマンドを使用してリソースアダプタをJ2EEアプリケーションに追加します。
cjaddappコマンドを使用して，リソースアダプタをJ2EEアプリケーションに追加します。

サーバ管理コマンドを使用してリソースアダプタのプロパティを定義します。
cjgetapppropコマンドでConnector属性ファイルを取得し，ファイル編集後に，cjsetapppropコマンドで編集内容を反映させます。
使用する機能ごとに設定するリソースアダプタのプロパティについては，それぞれ次の個所を参照してください。

リソース接続とトランザクション管理機能を使用するための設定
「3.4.12　実行環境での設定」

パフォーマンスチューニングのための機能
「3.14.10　実行環境での設定」

フォールトトレランスのための機能
「3.15.13　実行環境での設定」

J2EEリソースの別名の設定
「2.4.6　J2EEリソースの別名の設定」

サーバ管理コマンドを使用してリソースアダプタの接続テストを実施します。
cjtestresコマンドを使用して，リソースアダプタの接続テストを実施します。リソースごとの接続テストでの検証内容については，「3.18　リソースへの接続テスト」を参照してください。

3.3.10　リソースアダプタの設定の流れ（Inboundで使用する場合）

ここでは，メッセージインフローを実行する場合のリソースアダプタとJ2EEアプリケーションの設定の流れについて説明します。設定の流れは，リソースアダプタをJ2EEサーバに直接デプロイして使用するか，J2EEアプリケーションに含めて使用するかによって異なります。

＜この項の構成＞

(1)　リソースアダプタをJ2EEサーバに直接デプロイして使用する場合

(2)　リソースアダプタをJ2EEアプリケーションに含めて使用する場合

(1)　リソースアダプタをJ2EEサーバに直接デプロイして使用する場合

リソースアダプタをJ2EEサーバに直接デプロイして使用する場合の設定の流れを次の図に示します。

図3-10　リソースアダプタをJ2EEサーバに直接デプロイして使用する場合の設定の流れ

図中の1.～5.について説明します。ここでは，サーバ管理コマンドによる操作を示します。

Connector 1.5仕様に準拠したリソースアダプタをインポートします。
cjimportresコマンドに-type rarを指定して実行します。

リソースアダプタをデプロイします。
cjdeployrarコマンドを実行します。

リソースアダプタのプロパティを定義します。
cjgetrarpropコマンドでConnector属性ファイルを取得します。ファイル編集後に，cjsetrarpropコマンドで編集内容を反映させます。
ここでは，管理対象オブジェクトを設定します。設定内容については，「3.16.8(2) 管理対象オブジェクトの設定」を参照してください。

Message-driven Beanを含むJ2EEアプリケーションをインポートします。
cjimportappコマンドを使用します。

J2EEアプリケーションのプロパティを定義します。
cjgetapppropコマンドに-type allを指定して実行し，アプリケーション統合属性ファイルを取得します。ファイル編集後に，cjsetapppropコマンドに-type allを指定して実行し，編集内容を反映させます。
ここでは，次の項目を設定します。

Message-driven Beanとリソースアダプタの対応づけ
設定内容については「3.16.8(3) Message-driven Beanとリソースアダプタの対応づけの設定」を参照してください。

Message-driven Beanが使用するインタフェース
設定内容については「3.16.8(4) Message-driven Beanが使用するインタフェースの設定」を参照してください。

ActivationSpecの設定
設定内容については「3.16.8(5) ActivationSpecの設定」を参照してください。

(2)　リソースアダプタをJ2EEアプリケーションに含めて使用する場合

リソースアダプタをJ2EEアプリケーションに含めて使用する場合の設定の流れを次の図に示します。

図3-11　リソースアダプタをJ2EEアプリケーションに含めて使用する場合の設定の流れ

図中の1.～2.について説明します。なお，ここでは，サーバ管理コマンドによる操作を示します。

Message-driven Beanを含むJ2EEアプリケーションをインポートします。
cjimportappコマンドを使用します。

J2EEアプリケーションのプロパティを定義します。
cjgetapppropコマンドに-type allを指定して実行し，アプリケーション統合属性ファイルを取得します。ファイル編集後に，cjsetapppropコマンドに-type allを指定して実行し，編集内容を反映させます。
ここでは，次の項目を設定します。

管理対象オブジェクトの情報
設定内容については「3.16.8(2) 管理対象オブジェクトの設定」を参照してください。

Message-driven Beanとリソースアダプタの対応づけ
設定内容については「3.16.8(3) Message-driven Beanとリソースアダプタの対応づけの設定」を参照してください。

Message-driven Beanが使用するインタフェース
設定内容については「3.16.8(4) Message-driven Beanが使用するインタフェースの設定」を参照してください。

ActivationSpecの設定
設定内容については「3.16.8(5) ActivationSpecの設定」を参照してください。

3.3.11　リソースアダプタの設定の流れ（コネクションプールのクラスタ化をする場合）

コネクションプールをクラスタ化している場合の，データベースに接続するときのリソースアダプタの設定の流れを次の図に示します。

図3-12　コネクションプールのクラスタ化でのリソースアダプタの設定の流れ

図中の1.～10.について説明します。

サーバ管理コマンドを使用してメンバリソースアダプタをインポートします。
cjimportresコマンドを使用して，メンバリソースアダプタをインポートします。
インポートするリソースアダプタについては，「3.3.2　リソースアダプタの種類」を参照してください。

サーバ管理コマンドを使用してメンバリソースアダプタをデプロイします。
cjdeployrarコマンドを使用して，メンバリソースアダプタをデプロイします。

サーバ管理コマンドを使用してメンバリソースアダプタのプロパティを定義します。
cjgetrarpropコマンドでConnector属性ファイルを取得し，ファイル編集後に，cjsetrarpropコマンドで編集内容を反映させます。
メンバリソースアダプタとルートリソースアダプタのプロパティ定義では設定できる項目が異なります。メンバリソースアダプタおよびルートリソースアダプタで設定できるプロパティ定義の項目については，「3.17　コネクションプールのクラスタ化機能」を参照してください。
使用する機能ごとに設定するリソースアダプタのプロパティについては，それぞれ次の個所を参照してください。

リソース接続とトランザクション管理機能を使用するための設定
「3.4.12　実行環境での設定」

パフォーマンスチューニングのための機能
「3.14.10　実行環境での設定」

フォールトトレランスのための機能
「3.15.13　実行環境での設定」

J2EEリソースの別名の設定
「2.4.6　J2EEリソースの別名の設定」

サーバ管理コマンドを使用してメンバリソースアダプタの接続テストを実施します。
cjtestresコマンドを使用して，メンバリソースアダプタの接続テストを実施します。
メンバリソースアダプタの接続テストでの検証内容については，「3.18　リソースへの接続テスト」を参照してください。
また，1.～4.までの流れを，メンバリソースアダプタの数だけ繰り返します。

サーバ管理コマンドを使用してメンバリソースアダプタを開始します。
ルートリソースアダプタの接続テストを実施する場合には，あらかじめメンバリソースアダプタを開始しておいてください。cjstartrarコマンドを使用して，メンバリソースアダプタを開始します。

サーバ管理コマンドを使用してルートリソースアダプタをインポートします。
cjimportresコマンドを使用して，ルートリソースアダプタをインポートします。
インポートするリソースアダプタについては，「3.3.2　リソースアダプタの種類」を参照してください。

サーバ管理コマンドを使用してルートリソースアダプタをデプロイします。
cjdeployrarコマンドを使用してルートリソースアダプタをデプロイします。

サーバ管理コマンドを使用してルートリソースアダプタのプロパティを定義します。
cjgetrarpropコマンドでConnector属性ファイルを取得し，ファイル編集後に，cjsetrarpropコマンドで編集内容を反映させます。

サーバ管理コマンドを使用してルートリソースアダプタの接続テストを実施します。
cjtestresコマンドを使用して，ルートリソースアダプタの接続テストを実施します。
ルートリソースアダプタの接続テストでの検証内容については，「3.18　リソースへの接続テスト」を参照してください。

サーバ管理コマンドを使用してメンバリソースアダプタを停止します。
ルートリソースアダプタの接続テストを実施した場合には，メンバリソースアダプタを停止してください。cjstoprarコマンドを使用して，メンバリソースアダプタを停止します。

サーバ管理コマンドでの操作については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「3.　サーバ管理コマンドの基本操作」を参照してください。また，コマンドについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「2.4　J2EEサーバで使用するリソース操作コマンド」を参照してください。属性ファイルについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.　リソースの設定で使用する属性ファイル」を参照してください。

注意

コネクションプールをクラスタ化する場合，J2EEアプリケーションからルートリソースアダプタへのリファレンスを解決しておく必要があります。ルートリソースアダプタを使用しているJ2EEアプリケーションのプロパティを定義するときに，J2EEアプリケーションからルートリソースアダプタへのリファレンスを解決しておいてください。

3.3.12　リソースアダプタ以外を使用する接続の設定

リソースアダプタ以外の，JavaBeansリソースやJavaMailを使用する場合の設定については，それぞれ次の個所を参照してください。

JavaBeansリソースを使用する場合
「3.12.4　JavaBeansリソースの設定」を参照してください。

JavaMailを使用する場合
メールコンフィグレーションはSMTPサーバとの接続だけで使用します。
メールの受信にはPOP3サーバを利用します。IMAPサーバは利用できません。
詳細は「3.11　SMTPサーバとの接続」を参照してください。

3.3.13　リソースアダプタについての注意事項

ここでは，リソースアダプタについての注意事項を説明します。

デプロイ方法によって使用できない機能

リソースアダプタをJ2EEアプリケーションに含めて使用する場合，J2EEアプリケーションに含めたリソースが更新されても，次の機能は有効になりません。

J2EEアプリケーションの更新検知

J2EEアプリケーションのリロード

詳細は，「12.8.13　リロードの注意事項および制限事項」を参照してください。

リソースアダプタの表示名についての注意事項

J2EEアプリケーション内のEJBやWARは，J2EEリソースアダプタとしてデプロイするリソースアダプタ，およびJ2EEアプリケーションに含めて使用するリソースアダプタを同時に使用できます。ただし，一つのJ2EEサーバで同じ表示名のリソースアダプタを二つ以上使用することはできません。一つのJ2EEサーバに同じ表示名のリソースアダプタを二つ以上使用しようとすると，エラーメッセージが出力されて，リソースアダプタの開始に失敗します。リソースアダプタの開始に失敗する手順の例を次に示します。

例1.

「Rar1」という表示名のリソースアダプタをJ2EEサーバにデプロイする。

「Rar1」という表示名のリソースアダプタを含めたJ2EEアプリケーションをインポートする。

例2.

「Rar2」という表示名のリソースアダプタをJ2EEサーバにデプロイする。

「Rar2」という表示名のリソースアダプタを，インポート済みのJ2EEアプリケーションに追加する。

例3.

「Rar3」という表示名のリソースアダプタを含めたJ2EEアプリケーションをインポートする。

「Rar3」という表示名のリソースアダプタをJ2EEサーバにデプロイする。

リソースアダプタのオプショナル名についての注意事項

同じオプショナル名で複数のリソースアダプタをデプロイしている場合，エラーメッセージが出力されて，リソースアダプタの開始に失敗します。

3.4　トランザクション管理

この節では，トランザクション管理の概要について説明します。

リソース接続時のトランザクションを管理する方法には，アプリケーションサーバで管理する方法と，ユーザが直接管理する方法があります。

アプリケーションサーバでトランザクションを管理する場合，アプリケーションサーバのトランザクションマネージャを使用してトランザクションを管理できます。

この節の構成を次の表に示します。

表3-10　この節の構成（トランザクション管理）

分類 | タイトル | 参照先
解説 | リソース接続でのトランザクション管理の方法 | 3.4.1
ローカルトランザクションとグローバルトランザクション | 3.4.2
リソースごとに使用できるトランザクションの種類 | 3.4.3
トランザクションサービスで提供する機能 | 3.4.4
システム例外発生時のトランザクションの動作 | 3.4.5
トランザクションマネージャの取得 | 3.4.6
実装※ | コンテナ管理のトランザクション（CMT）を使用する場合の処理概要と留意点 | 3.4.7
UserTransactionインタフェースを使用する場合の処理概要と留意点 | 3.4.8
リソースアダプタ固有のトランザクション管理インタフェースを使用する場合の処理概要と留意点 | 3.4.9
トランザクションを使用しない場合の処理概要と留意点 | 3.4.10
JTAによるトランザクション実装時の注意事項 | 3.4.11
設定 | 実行環境での設定 | 3.4.12

注　「運用」について，この機能固有の説明はありません。

注※　EJBクライアントでのトランザクションの実装方法については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「3.5　EJBクライアントアプリケーションでのトランザクションの実装」を参照してください。

ポイント

リソースのうち，SMTPサーバおよびJavaBeansリソースについては，トランザクション管理の対象外です。

参考

EJBクライアントアプリケーションでもトランザクションを開始できます。EJBクライアントアプリケーションでトランザクションを開始する場合の注意事項については，「3.20　EJBクライアントアプリケーションでトランザクションを開始する場合の注意事項」を参照してください。

＜この節の構成＞

3.4.1　リソース接続でのトランザクション管理の方法

3.4.2　ローカルトランザクションとグローバルトランザクション

3.4.3　リソースごとに使用できるトランザクションの種類

3.4.4　トランザクションサービスで提供する機能

3.4.5　システム例外発生時のトランザクションの動作

3.4.6　トランザクションマネージャの取得

3.4.7　コンテナ管理のトランザクション（CMT）を使用する場合の処理概要と留意点

3.4.8　UserTransactionインタフェースを使用する場合の処理概要と留意点

3.4.9　リソースアダプタ固有のトランザクション管理インタフェースを使用する場合の処理概要と留意点

3.4.10　トランザクションを使用しない場合の処理概要と留意点

3.4.11　JTAによるトランザクション実装時の注意事項

3.4.12　実行環境での設定

3.4.1　リソース接続でのトランザクション管理の方法

リソース接続でのトランザクションの管理方法には，アプリケーションサーバが管理する方法と，アプリケーションサーバが管理しない方法（ユーザが直接管理する方法）があります。ここでは，それぞれのトランザクションの管理方法について説明します。

＜この項の構成＞

(1)　アプリケーションサーバが管理するトランザクション

(2)　ユーザが直接管理するトランザクション（アプリケーションサーバが管理しないトランザクション）

(1)　アプリケーションサーバが管理するトランザクション

アプリケーションサーバのトランザクションマネージャ経由でトランザクションを管理する方法です。ユーザは，javax.transaction.UserTransactionインタフェースのAPIを操作するか，EJBメソッドのCMT属性を設定することで，トランザクションを管理します。

UserTransactionインタフェースによる管理
サーブレット，JSP，またはEJB（BMT）から，javax.transaction.UserTransactionインタフェースのAPIを発行することで，トランザクションを管理できます。BMTの詳細については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.7.2　BMT」を参照してください。

EJBのCMT属性による管理
EJB（CMT）のメソッド単位で指定するトランザクション属性によって，トランザクションを管理できます。CMTの詳細については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.7.3　CMT」を参照してください。

アプリケーションサーバがトランザクションを管理する場合，トランザクションの種類としてローカルトランザクションまたはグローバルトランザクションを選択できます。アプリケーションサーバが管理するトランザクションの種類については，「3.4.2　ローカルトランザクションとグローバルトランザクション」を参照してください。

(2)　ユーザが直接管理するトランザクション（アプリケーションサーバが管理しないトランザクション）

リソース固有のAPIによって，ユーザが直接トランザクションを管理する方法です。例えば，データベースにJDBCインタフェースで接続する場合，java.sql.ConnectionインタフェースのsetAutoCommit()，commit()，rollback()などのAPIをユーザが直接操作します。

3.4.2　ローカルトランザクションとグローバルトランザクション

アプリケーションサーバが管理するトランザクションを使用する場合，アプリケーションサーバのトランザクションマネージャと，リソースを管理するリソースマネジャ（DBMSなど）が連携して，トランザクションを管理します。この場合，トランザクションの種類として，ローカルトランザクションとグローバルトランザクションのどちらかを選択します。

ローカルトランザクションと，グローバルトランザクションについて説明します。

＜この項の構成＞

(1)　ローカルトランザクション

(2)　グローバルトランザクション

(3)　ライトトランザクション機能とトランザクションの管理方法の関係

(1)　ローカルトランザクション

トランザクション管理を行うリソースが一つだけの場合に，ローカルトランザクションを使用します。ローカルトランザクションを使用する場合，トランザクションの決着はリソースマネジャが行います。

(2)　グローバルトランザクション

トランザクション管理を行うリソースが複数ある場合に，グローバルトランザクションを使用します。グローバルトランザクションを使用する場合，トランザクションマネージャが複数のリソースのトランザクションを調整し，整合性が崩れないように決着します。トランザクションの決着には，2フェーズコミットプロトコルが使用されます。なお，グローバルトランザクション使用時には，インプロセストランザクションサービスを使用します。インプロセストランザクションサービスについては，「3.14.6　インプロセストランザクションサービス」を参照してください。

グローバルトランザクションには比較的高い処理コストが掛かりますので，トランザクション管理を行うリソースが一つだけの場合には，ローカルトランザクションを使用することをお勧めします。

なお，デフォルトではライトトランザクション機能※が有効になっているため，グローバルトランザクションを使用することはできません。グローバルトランザクションを使用するには，ライトトランザクション機能を無効にする必要があります。

注※

ライトトランザクションの詳細については，「3.14.5　ライトトランザクション」を参照してください。

(3)　ライトトランザクション機能とトランザクションの管理方法の関係

ライトトランザクション機能とは，ローカルトランザクションに，最適化された環境を提供する機能です。

トランザクションの管理方法とライトトランザクションの対応を次の表に示します。

表3-11　トランザクションの管理方法とライトトランザクションの対応

トランザクションの管理方法 | ライトトランザクション有効 | ライトトランザクション無効
アプリケーションサーバが管理するトランザクション | ローカルトランザクション | ○ | ○
グローバルトランザクション | × | ○
アプリケーションサーバが管理しないトランザクション | ○ | ○

（凡例）　○：使用できる　　×：使用できない

ライトトランザクション機能については，「3.14.5　ライトトランザクション」を参照してください。

3.4.3　リソースごとに使用できるトランザクションの種類

ここでは，次に示すリソースごとに使用できるトランザクションの種類について説明します。

データベース（接続方法：DB Connector）

データベース上のキュー（接続方法：DB Connector for Cosminexus RMとCosminexus RM）

OpenTP1（Outboundでの接続）（接続方法：uCosminexus TP1 ConnectorまたはTP1/Message Queue - Access）

OpenTP1（Inboundでの接続）（接続方法：TP1インバウンドアダプタ）

CJMSPブローカー（接続方法：CJMSPリソースアダプタ）

そのほかのリソース（接続方法：Connector 1.5仕様に準拠したリソースアダプタ）

それぞれのリソースで使用できるトランザクションの種類は，次の項目の設定内容によって決まります。

リソースアダプタ単位で設定するトランザクションサポートレベル

次に示す3種類のトランザクションサポートレベルごとに，使用できるトランザクションの種類が異なります。

NoTransaction
リソースをトランザクション管理しません。

LocalTransaction
リソースをローカルトランザクションでトランザクション管理します。

XATransaction
リソースをグローバルトランザクションでトランザクション管理します。

なお，トランザクションサポートレベルの設定は，リソースアダプタのプロパティとして設定します。リソースアダプタの設定については，「3.4.12　実行環境での設定」を参照してください。

ライトトランザクション機能の有効／無効

ライトトランザクション機能を有効にしているか無効にしているかによって，使用できるトランザクションの種類が異なります。

＜この項の構成＞

(1)　データベース接続の場合

(2)　データベース上のキューとの接続の場合

(3)　OpenTP1接続の場合（Outboundでの接続）

(4)　OpenTP1接続の場合（Inboundでの接続）

(5)　CJMSPブローカー接続の場合

(6)　そのほかのリソースの場合

(1)　データベース接続の場合

接続方法，トランザクションサポートレベルの対応で決定される，トランザクションの種類を次の表に示します。

表3-12　使用できるトランザクションの種類（データベース接続の場合）

接続方法
トランザクションサポートレベル
ライトトランザクション機能

有効
無効

DB Connector（DBConnector_HiRDB_Type4_CP.rar）
（DBConnector_DABJ_CP.rar）
（DBConnector_Oracle_CP.rar）
（DBConnector_SQLServer_CP.rar）
（DBConnector_SQLServer2005_CP.rar）
（DBConnector_CP_ClusterPool_Root.rar）
（DBConnector_Oracle_CP_ClusterPool_Member.rar）
NoTransaction
なし
なし

LocalTransaction
ローカル
ローカル

DB Connector（DBConnector_HiRDB_Type4_XA.rar）
（DBConnector_DABJ_XA.rar）
（DBConnector_Oracle_XA.rar）
XATransaction
－
グローバル

（凡例）

グローバル：グローバルトランザクション

ローカル：ローカルトランザクション

なし：トランザクション管理なし

－：指定できない

(2)　データベース上のキューとの接続の場合

接続方法，トランザクションサポートレベルの対応で決定される，トランザクションの種類を次の表に示します。

表3-13　使用できるトランザクションの種類（データベース上のキューとの接続の場合）

接続方法
トランザクションサポートレベル
ライトトランザクション機能

有効
無効

DB Connector for Cosminexus RMとCosminexus RM
（DBConnector_HiRDB_Type4_CP_Cosminexus_RM.rar）
（DBConnector_DABJ_CP_Cosminexus_RM.rar）
（DBConnector_Oracle_CP_Cosminexus_RM.rar）
NoTransaction
なし
なし

LocalTransaction
ローカル
ローカル

DB Connector for Cosminexus RMとCosminexus RM
（DBConnector_HiRDB_Type4_XA_Cosminexus_RM.rar）
（DBConnector_DABJ_XA_Cosminexus_RM.rar）
（DBConnector_Oracle_XA_Cosminexus_RM.rar）
XATransaction
－
グローバル

（凡例）

グローバル：グローバルトランザクション

ローカル：ローカルトランザクション

なし：トランザクション管理なし

－：指定できない

(3)　OpenTP1接続の場合（Outboundでの接続）

接続方法，トランザクションサポートレベルの対応で決定される，トランザクションの種類を次の表に示します。

表3-14　使用できるトランザクションの種類（OpenTP1接続の場合（Outboundでの接続））

接続方法 | トランザクションサポートレベル | ライトトランザクション機能
有効 | 無効
uCosminexus TP1 Connector | NoTransaction | なし | なし
LocalTransaction | ローカル | ローカル
XATransaction | － | グローバル
TP1/Message Queue - Access | NoTransaction | なし | なし
LocalTransaction | ローカル | ローカル
XATransaction | － | グローバル

（凡例）

グローバル：グローバルトランザクション

ローカル：ローカルトランザクション

なし：トランザクション管理なし

－：指定できない

(4)　OpenTP1接続の場合（Inboundでの接続）

TP1インバウンドアダプタで使用できるトランザクションの種類については，「3.13.2　そのほかのリソースとの接続で使用できる機能」を参照してください。

(5)　CJMSPブローカー接続の場合

接続方法，トランザクションサポートレベルの対応で決定される，トランザクションの種類を次の表に示します。

表3-15　使用できるトランザクションの種類（CJMSPブローカー接続の場合）

接続方法 | トランザクションサポートレベル | ライトトランザクション機能
有効 | 無効
CJMSPリソースアダプタ | NoTransaction | なし | なし
LocalTransaction | ローカル | ローカル
XATransaction | － | －

（凡例）

ローカル：ローカルトランザクション

なし：トランザクション管理なし

－：指定できない

(6)　そのほかのリソースの場合

Connector 1.5仕様に準拠したリソースアダプタで使用できるトランザクションの種類については，「3.13.2　そのほかのリソースとの接続で使用できる機能」を参照してください。

3.4.4　トランザクションサービスで提供する機能

トランザクションサービスでは，次に示す機能を提供します。なお，アプリケーションサーバでは，トランザクションサービスはJ2EEサーバのインプロセスで起動します。

グローバルトランザクションの開始，コミット決着，ロールバック決着の制御
2フェーズコミットプロトコルによってトランザクション処理を制御します。2フェーズコミットプロトコルとは，同期点での処理をプリペア処理（資源のアップデート準備）とコミット処理（資源のアップデート処理）という2段階に分ける方法です。2フェーズコミットプロトコルでは，DBMSなどの複数のリソースオブジェクトに対して同期を取り，コミットまたはロールバックができます。また，2フェーズコミットプロトコルではトランザクション処理中に障害が発生した場合でも，すべてのリソースオブジェクトを矛盾なく自動的にロールバックできます。

トランザクションコンテキストの伝播（RMI-IIOPによるEnterprise Bean呼び出し）
グローバルトランザクションの状態を表すトランザクションコンテキストを管理します。例えば，サーブレット/JSPなどのクライアントがリモートのEnterprise Beanのメソッドを呼び出したとき，クライアント側のトランザクションコンテキストをサーバ側のEnterprise Beanに伝達します。

ステータスファイルを使用したトランザクション情報の管理と障害発生後のJ2EEサーバの再起動によるシステム回復
システム障害でJ2EEサーバが停止したときに実行中だったアプリケーションプログラムのトランザクション処理を回復して，ロールバックまたはコミットします。トランザクションをロールバックするか，コミットするかは，トランザクション処理がどこまで進んでいたかで決まります。トランザクション処理が，2フェーズコミットのうち，1フェーズ目の完了前まで進んでいる場合には，グローバルトランザクションをロールバックします。2フェーズコミットのうちの1フェーズ目が完了している場合には，ルートトランザクションブランチでの決定に従って，グローバルトランザクションをロールバック，またはコミットします。

ステータスファイルの二重化
ステータスファイルの二重化の機能を使用した場合，一方のステータスファイルが配置されているディスクで障害が発生すると，他方のステータスファイルでトランザクション回復処理が実行されます※。ただし，この機能を利用すると，二重にディスクアクセスするため，オンライン処理の応答時間は遅くなります。

注※

オンライン処理は継続できません。

リソースマネジャでのヒューリスティック決着時のエラー通知
データベースなどのリソースマネジャでのヒューリスティック決着を検知したとき，メッセージによってエラーを通知します。

3.4.5　システム例外発生時のトランザクションの動作

EJB呼び出し時に，呼び出し先でシステム例外が発生したときの呼び出し元のトランザクションの挙動は，J2EEサーバの起動モードやシステム定義によって次のように変わります。

＜この項の構成＞

(1)　呼び出し元のトランザクションを呼び出し先が引き継ぐ場合（呼び出し先のトランザクション属性がCMTのRequired，Supports，Mandatoryの場合）

(2)　呼び出し元のトランザクションを呼び出し先が引き継がない場合（呼び出し先のトランザクション属性がBMT，またはCMTのNotSupported，RequiresNew，Neverの場合）

(1)　呼び出し元のトランザクションを呼び出し先が引き継ぐ場合（呼び出し先のトランザクション属性がCMTのRequired，Supports，Mandatoryの場合）

呼び出し先でシステム例外が戻ってきた場合，トランザクションはコンテナによってロールバックされます。この動作は，EJB仕様で規定されています。

(2)　呼び出し元のトランザクションを呼び出し先が引き継がない場合（呼び出し先のトランザクション属性がBMT，またはCMTのNotSupported，RequiresNew，Neverの場合）

呼び出し元，呼び出し先のトランザクションは，それぞれ次のように動作します。

呼び出し元のトランザクション

EJBのリモートインタフェースでのリモート呼び出し時
ライトトランザクションが無効の場合：
トランザクションはOTSによってロールバックにマークされます。
ライトトランザクションが有効の場合：
トランザクションはロールバックにマークされません。

EJBのリモートインタフェースでのローカル呼び出しの最適化時
usrconf.propertiesのejbserver.distributedtx.rollbackClientTxOnSystemExceptionキーの値によって動作が異なります。
trueの場合：
トランザクションはロールバックにマークされます。
falseの場合：
トランザクションはロールバックにマークされません。

EJBのローカルインタフェース呼び出し時
トランザクションはロールバックにマークされます。

呼び出し先のトランザクション

トランザクションはコンテナによってロールバックされます。この動作は，EJB仕様で規定されています。

なお，ローカル呼び出しの最適化については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.13.1　EJBのリモートインタフェースでのローカル呼び出しの最適化」を参照してください。

3.4.6　トランザクションマネージャの取得

トランザクションマネージャ（javax.transaction.TransactionManagerまたはjavax.transaction.Transaction）は，トランザクションを管理するためのAPIを提供します。トランザクションマネージャのAPIを使用するフレームワークを使用する場合は，JNDIを使用してトランザクションマネージャを取得できます。トランザクションマネージャを取得するには，「java:comp/TransactionManager」の名前でルックアップします。

アプリケーションサーバがサポートするトランザクションマネージャのAPI，およびSynchronizationを使用する場合の注意について説明します。

＜この項の構成＞

(1)　サポートするAPI

(2)　トランザクションマネージャを使用する場合の注意事項

(3)　Synchronizationを使用する場合の注意事項

(1)　サポートするAPI

アプリケーションサーバがサポートするトランザクションマネージャのAPIを次の表に示します。

表3-16　アプリケーションサーバがサポートするトランザクションマネージャのAPI

インタフェース | メソッド | 使用可否
javax.transaction.TransactionManager | begin | ○
commit | ○
getStatus | ○
getTransaction | ○
resume | ○
rollback | ○
setRollbackOnly | ○
setTransactionTimeout | ○
suspend | ○
javax.transaction.Transaction | commit | ○
delistResource | －
enlistResource | －
getStatus | ○
registerSynchronization | ○
rollback | ○
setRollbackOnly | ○

（凡例）　○：使用できる　－：使用できない

注　使用できないメソッドを使用しようとすると，javax.transaction.SystemExceptionがスローされます。

(2)　トランザクションマネージャを使用する場合の注意事項

ルックアップで取得したトランザクションマネージャを使用する場合，トランザクション管理に含める処理（データベースのコネクションの取得，使用，解放など）は，トランザクションの開始後から決着前，または開始後から中断前および再開後から決着前の範囲内で実装してください。トランザクションの開始前や決着後，中断中に実装された処理はトランザクション管理に含まれません。

(3)　Synchronizationを使用する場合の注意事項

トランザクション（javax.transaction.Transaction）のregisterSynchronizationメソッドで登録するSynchronization（javax.transaction.Synchronization）のbeforeCompletionメソッド，およびafterCompletionメソッドでは，J2EEサーバが提供するサービスを使用できません。使用できないサービスの例を次に示します。

リソースアクセス

UserTransactionまたはCMTによるトランザクション操作

EJBアクセス

JNDIアクセス

これらのサービスのうちリソースアクセスを行った場合，リソースアクセスでトランザクションマネージャが管理するトランザクションの一部として管理されないため，不整合が発生することがあります。リソースアクセスをする場合は，フレームワークの責任で，フレームワークがリソースに対して直接トランザクションを制御するようにしてください。

上記のような注意事項があるため，ユーザプログラムでSynchronizationを利用することは推奨しません。ユーザプログラムからトランザクション決着のタイミングを利用したい場合には，EJBのjavax.ejb.SessionSynchronizationを使用してください。

3.4.7　コンテナ管理のトランザクション（CMT）を使用する場合の処理概要と留意点

コンテナ管理のトランザクションを使用すれば，Enterprise Beanのビジネスメソッドが呼ばれる直前に自動的にトランザクションを開始し，ビジネスメソッドの処理が終了した直後に自動的にトランザクションをコミットできます。ユーザプログラムのコーディングとしてトランザクション管理処理をまったく記述する必要がなく，容易にリソースへのアクセスのトランザクションを管理できます。

コンテナ管理のトランザクションを使用する場合のシーケンスを示します。

図3-13　コンテナ管理のトランザクション使用時のシーケンス

コンテナ管理のトランザクションを使用する場合，次の点に留意して実装してください。

コンテナ管理のトランザクションを使用する場合，Enterprise Beanのメソッドごとにトランザクション属性を指定できます。指定できるのは，Required，RequiresNew，Mandatory，Supports，NotSupported，Neverのどれかです。トランザクションを使用する場合，DDの<transaction-type>タグにContainerを指定し，メソッドごとのトランザクション属性は<trans-attribute>タグに指定します。また，DDを使用しないで，アノテーションで定義することもできます。トランザクション属性の詳細については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.7.3　CMT」を参照してください。アノテーションについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス API編」の「2.　アプリケーションサーバが対応しているアノテーションおよびDependency Injection」を参照してください。

トランザクションを開始したあとのビジネスメソッドの中でリソースにアクセスした場合には，そのリソースアクセスは自動的にトランザクション管理がされます。

トランザクション開始後に複数のリソースへアクセスする場合は，グローバルトランザクションに対応したリソースアダプタを使用し，リソースアダプタのトランザクションサポートレベルをXATransactionに設定する必要があります。

コンテナ管理のトランザクションを使用する場合，ユーザプログラムのコーディングとしてトランザクション管理のための処理を記述する必要はありません。

コンテナ管理のトランザクションはEnterprise Beanで使用できます。サーブレットおよびJSPでは使用できません。

3.4.8　UserTransactionインタフェースを使用する場合の処理概要と留意点

UserTransactionインタフェースを使用すれば，ユーザプログラムからトランザクションマネージャに対して，トランザクションの開始，決着の指示を出すことができます。ユーザプログラムで，トランザクションの細かい制御をしたい場合には，この方法を使用します。

ユーザプログラムからトランザクションマネージャに対して，トランザクションの開始，決着を指示する手順を示します。

UserTransactionオブジェクトを取得します。
UserTransactionオブジェクトを取得するには，次の方法があります。

ネーミングサービスからJNDIを使用して"java:comp/UserTransaction"をルックアップする方法

EJBContextインタフェースのgetUserTransactionメソッドを呼び出して取得する方法

DIを使用して取得する方法

UserTransactionオブジェクトのbeginメソッドを呼び出して，トランザクションを開始します。

リソースにアクセスします。

UserTransactionオブジェクトのcommitメソッドまたはrollbackメソッドを呼び出して，トランザクションを決着します。

UserTransactionインタフェースを使用する場合のシーケンスを示します。

図3-14　UserTransactionインタフェース使用時のシーケンス

UserTransactionインタフェースを使用する場合，次の点に留意して実装してください。

UserTransactionインタフェースを使用する場合，DDの<transaction-type>タグにBeanを指定します。また，DDを使用しないで，アノテーションで定義することもできます。アノテーションについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス API編」の「2.　アプリケーションサーバが対応しているアノテーションおよびDependency Injection」を参照してください。

トランザクションを開始後にリソースにアクセスした場合には，そのリソースアクセスは自動的にトランザクション管理されます。

トランザクション開始後に複数のリソースへアクセスする場合は，グローバルトランザクションに対応したリソースアダプタを使用し，リソースアダプタのトランザクションサポートレベルをXATransactionに設定する必要があります。

Enterprise Bean，サーブレット，およびJSPで使用できます。

UserTransactionインタフェースを使用して，ユーザプログラムで開始したトランザクションは，例外などが発生した場合にも，ユーザプログラムでcommitまたはrollbackを発行して決着させる必要があります。決着させなかった場合，リソースのロックが解放されない，または次のトランザクションが開始できないなどの問題が発生するおそれがあります。

3.4.9　リソースアダプタ固有のトランザクション管理インタフェースを使用する場合の処理概要と留意点

リソースアダプタ固有のインタフェースを使用して，ユーザプログラムが直接リソースのトランザクションを制御することもできます。例えば，DB Connectorであれば，ConnectionインタフェースのsetAutoCommitメソッド，commitメソッド，およびrollbackメソッドを使用して，ユーザプログラムが直接リソースのトランザクションを制御できます。

リソースアダプタ固有のトランザクション管理インタフェースを使用する場合のシーケンスを示します。

図3-15　リソースアダプタ固有のトランザクション管理インタフェース使用時のシーケンス

リソースアダプタ固有のトランザクション管理インタフェースを使用する場合，次の点に留意して実装してください。

トランザクションマネージャが提供するトランザクションタイムアウトなどの機能は使用できません。

複数のリソースへのアクセスをトランザクション管理することはできません。

3.4.10　トランザクションを使用しない場合の処理概要と留意点

リソースへのアクセスをトランザクション管理しないこともできます。リソースに対して参照しかしない場合などには，トランザクション管理のコストを削減するために，この方法を使用できます。

トランザクションを使用しない場合のシーケンスを示します。

図3-16　トランザクション未使用時のシーケンス

トランザクションを使用しない場合，次の点に留意して実装してください。

Enterprise BeanのDDの<transaction-type>タグにContainerを指定して，<trans-attribute>タグにNotSupported，Neverのどちらかを指定すれば，トランザクションは使用されません。また，DDを使用しないで，アノテーションで定義することもできます。トランザクション属性の詳細については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.7.3　CMT」を参照してください。アノテーションについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス API編」の「2.　アプリケーションサーバが対応しているアノテーションおよびDependency Injection」を参照してください。

Enterprise BeanのDDの<transaction-type>タグにBeanを指定して，UserTransactionオブジェクトのbeginメソッドを呼び出さなければ，トランザクションは使用されません。また，DDを使用しないで，アノテーションで定義することもできます。アノテーションについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス API編」の「2.　アプリケーションサーバが対応しているアノテーションおよびDependency Injection」を参照してください。

サーブレットおよびJSPでUserTransactionオブジェクトのbeginメソッドを呼び出さなければ，トランザクションは使用されません。

特定のリソースアダプタへのアクセスだけをトランザクションで管理しないこともできます。これを実現するには，トランザクションで管理しないリソースアダプタのトランザクションサポートレベルをNoTransactionに設定します。トランザクションサポートレベルをNoTransactionに設定したリソースアダプタでは，トランザクション開始後にリソースにアクセスしてもトランザクション管理の対象とはなりません。

3.4.11　JTAによるトランザクション実装時の注意事項

JTAを使用してトランザクションを実装したプログラムの処理の内容，および動作を次の表に示します。

表3-17　JTAの動作

処理の内容
動作

EJB呼び出しで，java.rmi.RemoteExceptionまたはjava.rmi.RemoteExceptionを継承した例外が発生した場合

CORBAのシステム例外が発生した場合

クライアント側のトランザクションをロールバックにマークするかしないかは，プロパティ（ejbserver.distributedtx.rollbackClientTxOnSystemException）の設定で変わります。プロパティの設定値とその動作については，「3.4.5　システム例外発生時のトランザクションの動作」を参照してください。

トランザクションタイムアウト発生後に，javax.transaction.UserTransaction.commitメソッドを呼び出した場合
javax.transaction.RollbackException例外が発生します。ただし，トランザクションタイムアウトが発生したあと，2回以上UserTransaction.commitメソッドを呼び出すと，2回目以降はjava.lang.IllegalStateException例外が発生します。

トランザクションタイムアウト発生後にjavax.transaction.UserTransaction.rollbackメソッドを呼び出した場合
例外は発生しません。

トランザクションタイムアウト後のjavax.transaction.UserTransaction.getStatusメソッドの戻り値
javax.transaction.Status.STATUS_ROLLEDBACKが返されます。ただし，UserTransaction.commitメソッド，またはUserTransaction.rollbackメソッドを呼び出したあとは，javax.transaction.Status.STATUS_NO_TRANSACTIONが返されます。

javax.ejb.SessionSynchronizationを実装したEJBのbeforeCompletionメソッド，またはafterCompletionメソッドからのEJB呼び出し
例外が発生することなく，呼び出すことができます。

3.4.12　実行環境での設定

リソース接続とトランザクション管理機能を使用する場合，J2EEサーバ，およびリソースアダプタの設定が必要です。

＜この項の構成＞

(1)　J2EEサーバの設定

(2)　リソースアダプタの設定

(1)　J2EEサーバの設定

J2EEサーバの設定は，簡易構築定義ファイルで実施します。リソース接続とトランザクション管理の機能の定義は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。簡易構築定義ファイルでの設定を次の表に示します。なお，トランザクション管理では，トランザクションのタイムアウトも指定できます。トランザクションのタイムアウトについては，「3.15.8　トランザクションタイムアウトとステートメントキャンセル」を参照してください。

表3-18　簡易構築定義ファイルでのリソース接続とトランザクション管理の機能を使用するための定義

項目
指定するパラメタ
設定内容

トランザクションの種類
ejbserver.distributedtx.XATransaction.enabled
ライトトランザクションを使用するか，グローバルトランザクションを使用するかどうかを指定します。デフォルトの設定では，ライトトランザクションが有効になっています。

システム例外発生時のクライアントトランザクションの動作
ejbserver.distributedtx.rollbackClientTxOnSystemException
システム例外が発生したときにクライアントトランザクションをロールバックにマークするかどうかを指定します。

ステータスファイルの格納ディレクトリ

ejbserver.distributedtx.ots.status.directory1

ejbserver.distributedtx.ots.status.directory2

インプロセストランザクションサービスのステータスファイルとステータスファイルのバックアップを格納するディレクトリとして指定します。

注意

インプロセストランザクションサービスのステータスファイルとステータスファイルのバックアップを格納するディレクトリの指定について

インプロセストランザクションサービスでは，トランザクションの整合性を保証するため，ホスト名またはIPアドレスをJ2EEサーバの識別情報としてステータスファイル内に取り込みます。このため，J2EEサーバのコンフィグレーション定義でvbroker.se.iiop_tp.hostパラメタを設定していて値を変更する場合，またはvbroker.se.iiop_tp.hostパラメタを設定しないでJ2EEサーバを起動するマシンのIPアドレスを変更する場合は，次の手順に従ってください。

J2EEサーバ上でトランザクションが存在しない状態で，J2EEサーバを停止してください。

IPアドレス，またはvbroker.se.iiop_tp.hostパラメタの設定を変更してください。

ejbserver.distributedtx.ots.status.directory1パラメタで指定したディレクトリを削除してください。

J2EEサーバを起動してください。

(2)　リソースアダプタの設定

実行環境でのリソースアダプタの設定は，サーバ管理コマンドおよび属性ファイルを使用します。トランザクション管理のための機能の定義には，Connector属性ファイルの<resourceadapter>タグに指定します。設定内容について，次の表に示します。

表3-19　Connector属性ファイルでのトランザクション管理のための機能の定義

項目
指定するタグ
設定内容

トランザクションサポートレベル
<outbound-resourceadapter>－<transaction-support>タグ
トランザクションサポートレベルを設定します。
トランザクション管理なし（NoTransaction），ローカルトランザクション（LocalTransaction），またはグローバルトランザクション（XATransaction）を指定します。

3.5　リソースへのサインオン方式

リソースへのサインオンの方式として，次のどちらかの方式を選択できます。

コンテナ管理サインオン
アプリケーションサーバで自動的にサインオンする方式です。この方式を使用する場合，リソースアダプタごとにユーザ名とパスワードを設定しておけば，コネクション取得時に，アプリケーションサーバによって自動的にユーザ名とパスワードがリソースに伝達されます。
コンテナ管理サインオンを使用するには，Enterprise BeanやサーブレットのDDの，<resource-ref>タグ中の<res-auth>タグに，Containerを指定してください。

コンポーネント管理サインオン
ユーザプログラムでリソースにサインオンする方式です。この方式を使用する場合，コネクションを取得するときのユーザ名とパスワードをユーザプログラムで指定します。

（例）DB Connectorの場合

DataSourceクラスのgetConnectionを呼び出すときに，引数でユーザ名とパスワードを指定します。

コンポーネント管理サインオンを使用するには，Enterprise BeanやサーブレットのDDの<resource-ref>タグ中の<res-auth>タグに，Applicationを指定してください。

コネクションプーリングを使用する場合は，コネクションを効率良く再利用できるコンテナ管理サインオンの使用をお勧めします。

なお，セットアップウィザードを使用して構築したシステムの場合，ejbserver.connectionpool.applicationAuthentication.disabledにtrueが指定されているため，アプリケーション認証が使えません。

3.6　データベースへの接続

この節では，DB Connectorを使用してデータベースと接続する機能について説明します。

この節の構成を次の表に示します。

表3-20　この節の構成（データベースへの接続）

分類 | タイトル | 参照先
解説 | DB Connectorによる接続の概要 | 3.6.1
使用できるJ2EEコンポーネントおよび機能 | 3.6.2
接続できるデータベース | 3.6.3
DB Connector（RARファイル）の種類 | 3.6.4
HiRDBと接続する場合の前提条件と注意事項 | 3.6.5
Oracleと接続する場合の前提条件と注意事項 | 3.6.6
SQL Serverと接続する場合の前提条件と注意事項 | 3.6.7
XDM/RD E2と接続する場合の前提条件と注意事項 | 3.6.8
設定 | 実行環境での設定（リソースアダプタでの設定） | 3.6.9

注　「実装」および「運用」について，この機能固有の説明はありません。

DB Connectorを使用して接続できるデータベースには，HiRDB，Oracle，SQL Server，XDM/RD E2があります。データベースと接続する場合，接続先のデータベースの種類によって，データベースの接続方法，使用できるJDBCドライバなどが異なります。ここでは，データベース接続の前提条件と，使用できる機能について説明します。

＜この節の構成＞

3.6.1　DB Connectorによる接続の概要

3.6.2　使用できるJ2EEコンポーネントおよび機能

3.6.3　接続できるデータベース

3.6.4　DB Connector（RARファイル）の種類

3.6.5　HiRDBと接続する場合の前提条件と注意事項

3.6.6　Oracleと接続する場合の前提条件と注意事項

3.6.7　SQL Serverと接続する場合の前提条件と注意事項

3.6.8　XDM/RD E2と接続する場合の前提条件と注意事項

3.6.9　実行環境での設定（リソースアダプタでの設定）

3.6.1　DB Connectorによる接続の概要

データベースと接続する場合，リソースアダプタとしてDB Connectorを使用できます。DB Connectorは，JDBCを利用したデータベースアクセスをするためのリソースアダプタです。DB Connectorは，J2EEアプリケーションからコネクションファクトリ（javax.sql.DataSourceクラス）をルックアップして使用します。

DB Connectorによる接続の概要を次の図に示します。

図3-17　DB Connectorによる接続の概要

DB Connectorでのデータベース接続では，JDBCドライバに，HiRDB Type4 JDBC Driver，Oracle JDBC Thin Driver，またはSQL ServerのJDBCドライバを使用します。

DB Connectorの設定の詳細については，「3.6.9　実行環境での設定（リソースアダプタでの設定）」，およびマニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「4.2　データベースと接続するための設定」を参照してください。

また，データベース上のキューと接続する場合の接続方法については，「3.7　データベース上のキューとの接続」を参照してください。

注意

リソースアダプタを使用する場合，J2EEアプリケーションからリソースアダプタへのリファレンスを解決しておく必要があります。リソースアダプタを使用しているJ2EEアプリケーションをカスタマイズするときに，J2EEアプリケーションからリソースアダプタへのリファレンスを解決しておいてください。

3.6.2　使用できるJ2EEコンポーネントおよび機能

ここでは，データベース接続で使用できる機能について説明します。

データベース接続で使用できるJ2EEコンポーネントおよび機能を，データベースごとに次の表に示します。

表3-21　使用できるJ2EEコンポーネントおよび機能

項目 | HiRDB | Oracle | SQL Server | XDM/RD E2
Oracle9i | Oracle10g | Oracle11g
J2EEコンポーネント | Servlet/JSP | ○ | ○ | ○ | ○ | ○ | ○
Stateless Session Bean | ○ | ○ | ○ | ○ | ○ | ○
Stateful Session Bean | ○ | ○ | ○ | ○ | ○ | ○
Entity Bean（BMP） | ○ | ○ | ○ | ○ | ○ | ×
Entity Bean（CMP1.1） | ○ | × | × | × | × | ×
Entity Bean（CMP2.0） | ○※1 | × | × | × | × | ×
Message-driven Bean（onMessageメソッドからのデータベースアクセス） | ○ | ○ | ○ | ○ | ○ | ○
使用できる機能 | コネクションプーリング | ○ | ○ | ○ | ○ | ○ | ○
コネクションプールのウォーミングアップ | ○ | ○ | ○ | ○ | ○ | ○
コネクションプールの情報表示（cjlistpoolコマンド） | ○ | ○ | ○ | ○ | ○ | ○
コネクションプールのクリア（cjclearpoolコマンド） | ○ | ○ | ○ | ○ | ○ | ○
リソースへの接続テスト | ○ | ○ | ○ | ○ | ○ | ○
コネクションの障害検知 | ○ | ○ | ○ | ○ | △※2 | ○
ステートメントプーリング | ○※3 | ○ | ○ | ○ | ○ | ○※3
ステートメントキャンセル | ○ | △※4 | △※4 | △※4 | ○ | ○
ステートメントsetQueryTimeoutメソッド | ○ | △※5 | △※5 | △※5 | ○※6 | ×
コネクションIDのPRFトレース出力 | ○ | ○ | ○ | ○ | × | ○
障害調査用SQLの出力 | ○ | ○ | ○ | ○ | ○ | ○
コネクションプールのクラスタ化 | × | × | ○※7 | ○※7 | × | ×

（凡例）○：使用できる　　×：使用できない　　△：一部制限あり

注※1　CMP2.0の機能である，CMR機能は利用できません。

注※2　DB ConnectorのselectMethodプロパティをdirectに設定した場合は使用できません。

注※3　HiRDB自動再接続機能とステートメントプーリング機能の併用はできません。

注※4　Oracle9i，Oracle10gまたはOracle11gでOracle JDBC Thin Driverを使用して接続する場合は，接続形式がMTS接続のときに使用できます。専用接続では使用できません。

注※5　Oracle JDBC Thin Driverを使用する場合，MTS接続は有効に働きますが，専用接続には制限があります。詳細はオラクルのサポートサービスにお問い合わせください。

注※6　ステートメントsetQueryTimeoutメソッドは，SQL Server 2005またはSQL Server 2008の場合だけ使用できます。SQL Server 2000の場合は使用できません。

注※7　RAC機能を使用している場合で，Oracle JDBC Thin Driverを使用して接続するときに使用できます。

3.6.3　接続できるデータベース

ここでは，DB Connectorを使用して接続できるデータベースについて説明します。

＜この項の構成＞

(1)　接続できるデータベースの種類

(2)　データベースとJDBCドライバの対応

(3)　DB ConnectorがサポートするJDBC仕様

(1)　接続できるデータベースの種類

DB Connectorを利用して接続できるデータベースには，HiRDB，Oracle，SQL Server，XDM/RD E2があります。なお，SQL ServerおよびXDM/RD E2ではグローバルトランザクションは使用できません。

(2)　データベースとJDBCドライバの対応

DB Connectorを使用してデータベースに接続するためには，データベースに対応するJDBCドライバが必要です。接続先のデータベースと使用できるJDBCドライバの対応について次の表に示します。

表3-22　接続先のデータベースと使用できるJDBCドライバ（データベース接続の場合）

データベース | JDBCドライバ
HiRDB Type4 JDBC Driver | Oracle JDBC Thin Driver | SQL ServerのJDBCドライバ
HiRDB Version 8 | ◎ | × | ×
HiRDB Version 9 | ◎ | × | ×
Oracle | × | ◎ | ×
SQL Server | × | × | ○
XDM/RD E2 | ○ | × | ×

（凡例）

◎：使用できる。かつ使用を推奨する。

○：使用できる。

×：使用できない。

(3)　DB ConnectorがサポートするJDBC仕様

接続に使用するJDBCドライバとDB ConnectorがサポートするJDBC仕様を次の表に示します。ただし，接続に使用するJDBCドライバが，JDBC仕様で規定された機能をサポートしていない場合は，DB Connectorでその機能を使用できません。

表3-23　接続に使用するJDBCドライバとDB ConnectorがサポートするJDBC仕様

接続に使用するJDBCドライバ | DB ConnectorがサポートするJDBC仕様
HiRDB Type4 JDBC Driver | JDBC 2.0
Oracle JDBC Thin Driver | JDBC 3.0
SQL ServerのJDBCドライバ | JDBC 2.0

ポイント

Oracle JDBC Thin Driverは，JDBC 3.0の仕様で規定された範囲の機能をサポートしています。Oracleパッケージのクラスおよびインタフェースを使用したOracle拡張機能は使用できません。

また，アプリケーションサーバでOracle JDBC Thin Driverを使用してデータベースと接続する場合，Oracle JDBC Thin Driverの拡張機能である，文キャッシュおよび接続キャッシュ機能を利用することはできません。アプリケーションサーバで提供するステートメントプーリング，またはコネクションプーリングを使用してください。ステートメントプーリングまたはコネクションプーリングについては，「3.14　パフォーマンスチューニングのための機能」を参照してください。

3.6.4　DB Connector（RARファイル）の種類

DB Connectorを使用してデータベースに接続する場合，使用するJDBCドライバに対応したRARファイルを使用します。RARファイルは，サーバ管理コマンドを使用して操作します。サーバ管理コマンドを使用してRARファイルを操作する方法については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」を参照してください。

JDBCドライバの種類と対応するRARファイルについて次の表に示します。

表3-24　JDBCドライバとRARファイルの対応

JDBCドライバ | RARファイル | 説明
HiRDB Type4 JDBC Driver | DBConnector_HiRDB_Type4_CP.rar | トランザクション管理をしない場合，またはローカルトランザクションを使用する場合に使用します。
DBConnector_HiRDB_Type4_XA.rar※ | グローバルトランザクションを使用する場合に使用します。
Oracle JDBC Thin Driver | DBConnector_Oracle_CP.rar | トランザクション管理をしない場合，またはローカルトランザクションを使用する場合に使用します。
DBConnector_Oracle_XA.rar※ | グローバルトランザクションを使用する場合に使用します。
DBConnector_CP_ClusterPool_Root.rar | コネクションプールのクラスタ化機能でルートリソースアダプタを使用する場合に使用します。
DBConnector_Oracle_CP_ClusterPool_Member.rar | コネクションプールのクラスタ化機能でメンバリソースアダプタを使用する場合に使用します。
SQL ServerのJDBCドライバ | DBConnector_SQLServer_CP.rar | SQL Server 2000への接続に使用するRARファイルです。トランザクション管理をしない場合，またはローカルトランザクションを使用する場合に使用します。
DBConnector_SQLServer2005_CP.rar | SQL Server 2005またはSQL Server 2008への接続に使用するRARファイルです。トランザクション管理をしない場合，またはローカルトランザクションを使用する場合に使用します。

注※　ライトトランザクション機能は有効にできません。

3.6.5　HiRDBと接続する場合の前提条件と注意事項

ここでは，HiRDBと接続する場合の前提条件と注意事項について説明します。HiRDBのバージョンによって，使用できるJDBCドライバが異なります。

＜この項の構成＞

(1)　HiRDB Version 8の場合の前提条件

(2)　HiRDB Version 9の場合の前提条件

(3)　HiRDBと接続するときの注意事項

(1)　HiRDB Version 8の場合の前提条件

HiRDB Version 8の場合の前提条件について示します。

使用できるJDBCドライバ
使用できるJDBCドライバはHiRDB Type4 JDBC Driverとなります。

接続方法
次のどちらかのRARファイルを使用します。

DBConnector_HiRDB_Type4_CP.rar

DBConnector_HiRDB_Type4_XA.rar

RARファイルの種類に応じて，指定できるトランザクションサポートレベルが異なります。また，ライトトランザクションを使用できるかどうかも異なります。
RARファイルごとに指定できるトランザクションサポートレベルを次の表に示します。

表3-25　RARファイルごとに使用できるトランザクションサポートレベル（HiRDB Version 8）

使用するDB Connector
（RARファイル）
トランザクションサポートレベル
ライトトランザクション

有効
無効

DBConnector_HiRDB_Type4_CP.rar
NoTransaction
LocalTransaction
○
○

DBConnector_HiRDB_Type4_XA.rar
XATransaction
－
○

（凡例）　○：使用できる　　－：該当しない

(2)　HiRDB Version 9の場合の前提条件

HiRDB Version 9の場合の前提条件について示します。

使用できるJDBCドライバ
使用できるJDBCドライバはHiRDB Type4 JDBC Driverとなります。

接続方法
次のどれかのRARファイルを使用します。

DBConnector_HiRDB_Type4_CP.rar

DBConnector_HiRDB_Type4_XA.rar

RARファイルの種類に応じて，指定できるトランザクションサポートレベルが異なります。また，ライトトランザクションを使用できるかどうかも異なります。
RARファイルごとに指定できるトランザクションサポートレベルを次の表に示します。

表3-26　RARファイルごとに使用できるトランザクションサポートレベル（HiRDB Version 9）

使用するDB Connector
（RARファイル）
トランザクションサポートレベル
ライトトランザクション

有効
無効

DBConnector_HiRDB_Type4_CP.rar
NoTransaction
LocalTransaction
○
○

DBConnector_HiRDB_Type4_XA.rar
XATransaction
－
○

（凡例）　○：使用できる　　－：該当しない

(3)　HiRDBと接続するときの注意事項

HiRDBと接続する場合の注意を次に示します。

HiRDBの自動再接続機能を使用すると，データベースネットワーク障害などでHiRDBサーバとの接続が切断された場合に，コネクションが自動的に再接続されます。ただし，トランザクション中に接続が切断されると，SQLException例外が発生します。J2EEアプリケーションでSQLException例外を受け取ったときには，処理を続行しないでください。続けてDBMSにアクセスするとデータの不整合などの問題が発生するおそれがあります。

コネクションプール機能とステートメントプーリング機能を有効にして，Statement.cancel()を使用すると，SQLException例外が発生することがあります。この場合，コネクションプール機能，またはステートメントプーリング機能のどちらかを無効にすることをお勧めします。

HiRDBのバージョンが07-01以前で，トランザクションサポートレベルにXATrasactionを使用する場合，トランザクション外でコネクションを使用してデータベースにアクセスすると，コネクションが二つ使用されます。
HiRDBのバージョンが07-02以降で，J2EEアプリケーションが次の条件をすべて満たす場合は，コネクションが二つ使用され，HiRDBへの接続が同時に利用しているユーザ数の2倍になります。HiRDBのシステム共通定義のpd_max_usersオペランドに，同時に利用しているユーザ数の2倍の値を指定してください。pd_max_usersオペランドについては，マニュアル「HiRDB システム定義」を参照してください。

トランザクションサポートレベルがXATrasactionのDB Connectorを使用する。

アプリケーションサーバが管理するトランザクション内でコネクション※を使ってデータベースにアクセスする。

2.のトランザクションが決着する前に，トランザクション外でコネクション※を使ってデータベースにアクセスする。
注※　このコネクションは1.のDB Connectorから取得したコネクションで，かつ同一コネクションです。

HiRDBのバージョンが07-01以前で，ステートメントプーリング機能を有効にした場合，アプリケーションサーバが管理するトランザクションで使用するときだけ，ステートメントプーリング機能が使用できます。これ以外の場合はエラーが発生します。
HiRDBのバージョンが07-02以降で，J2EEアプリケーションが次の条件をすべて満たす場合は，エラーが発生します。

トランザクションサポートレベルがXATrasactionのDB Connectorを使用する。

アプリケーションサーバが管理するトランザクション内でコネクション※を使ってデータベースにアクセスする。

2.のトランザクションが決着する前に，トランザクション外でコネクション※を使ってデータベースにアクセスする。
注※　このコネクションは1.のDB Connectorから取得したコネクションで，かつ同一コネクションです。

コネクションの障害検知機能が有効な場合，コネクションが正常のときにも障害であると誤診することがあります。その結果，不要なコネクションの破棄および生成が行われ，性能に影響が出ます。トランザクションサポートレベルがXATransactionのDB Connectorを使用してHiRDBに接続する場合はコネクションの障害検知機能を使用しないでください。障害が発生した場合は，cjclearpoolコマンドを実行してください。HiRDBのバージョンが07-02以降の場合は，コネクションの障害検知機能を使用できます。

次の条件をすべて満たす場合，同一コネクションを複数の異なるグローバルトランザクションに同時に参加させることはできません。トランザクションごとに使用するコネクションを分けてください。

トランザクションサポートレベルがXATrasactionのDB Connectorを使用する。

アプリケーションサーバが管理するトランザクション内でコネクション※を使ってデータベースにアクセスする。

2.のトランザクションが決着する前に，トランザクション外でコネクション※を使ってデータベースにアクセスする。
注※　このコネクションは1.のDB Connectorから取得したコネクションで，かつ同一コネクションです。

HiRDBのコネクション自動再接続機能およびステートメントプール機能を有効にすると，自動再接続機能によってコネクションが再接続されたあとのSQL実行でメッセージ「KFPA11901-E」を含んだSQLException例外が発生することがあります。トランザクションサポートレベルがLocalTransaction，またはNoTransactionのDB Connectorでステートメントプール機能を有効にしてHiRDBに接続する場合は，HiRDBのコネクション自動再接続機能は使用しないでください。障害が発生した場合は，コネクションの障害検知機能，またはcjclearpoolコマンドを実行してください。

3.6.6　Oracleと接続する場合の前提条件と注意事項

ここでは，Oracleと接続する場合の前提条件と注意事項について説明します。

＜この項の構成＞

(1)　Oracle9iの場合の前提条件

(2)　Oracle10gの場合の前提条件

(3)　Oracle11gの場合の前提条件

(4)　Oracleと接続する場合の注意事項

(5)　Oracle RACを使用したOracleへの接続方法

(1)　Oracle9iの場合の前提条件

Oracle9iの場合の前提条件について示します。

使用できるJDBCドライバ
使用できるJDBCドライバはOracle JDBC Thin Driverとなります。

接続方法
次のどちらかのRARファイルを使用します。

DBConnector_Oracle_CP.rar

DBConnector_Oracle_XA.rar

RARファイルの種類に応じて，指定できるトランザクションサポートレベルが異なります。また，ライトトランザクションを使用できるかどうかも異なります。
RARファイルごとに指定できるトランザクションサポートレベルを次の表に示します。

表3-27　RARファイルごとに使用できるトランザクションサポートレベル（Oracle9i）

使用するDB Connector
（RARファイル）
トランザクションサポートレベル
ライトトランザクション

有効
無効

DBConnector_Oracle_CP.rar
NoTransaction
LocalTransaction
○
○

DBConnector_Oracle_XA.rar
XATransaction
－
○

（凡例）　○：使用できる　　－：該当しない

(2)　Oracle10gの場合の前提条件

Oracle10gの場合の前提条件について示します。

使用できるJDBCドライバ
使用できるJDBCドライバはOracle JDBC Thin Driverとなります。

接続方法
次のどれかのRARファイルを使用します。

DBConnector_Oracle_CP.rar

DBConnector_Oracle_XA.rar

DBConnector_CP_ClusterPool_Root.rar

DBConnector_Oracle_CP_ClusterPool_Member.rar

RARファイルの種類に応じて，指定できるトランザクションサポートレベルが異なります。また，ライトトランザクションを使用できるかどうかも異なります。
RARファイルごとに指定できるトランザクションサポートレベルを次の表に示します。

表3-28　RARファイルごとに使用できるトランザクションサポートレベル（Oracle10g）

使用するDB Connector
（RARファイル）
トランザクションサポートレベル
ライトトランザクション

有効
無効

DBConnector_Oracle_CP.rar
NoTransaction
LocalTransaction
○
○

DBConnector_Oracle_XA.rar
XATransaction
－
○

DBConnector_CP_ClusterPool_Root.rar
DBConnector_Oracle_CP_ClusterPool_Member.rar
NoTransaction
LocalTransaction
○
○

（凡例）　○：使用できる　　－：該当しない

(3)　Oracle11gの場合の前提条件

Oracle11gの場合の前提条件について示します。

使用できるJDBCドライバ
使用できるJDBCドライバはOracle JDBC Thin Driverとなります。

接続方法
次のどれかのRARファイルを使用します。

DBConnector_Oracle_CP.rar

DBConnector_Oracle_XA.rar

DBConnector_CP_ClusterPool_Root.rar

DBConnector_Oracle_CP_ClusterPool_Member.rar

RARファイルの種類に応じて，指定できるトランザクションサポートレベルが異なります。また，ライトトランザクションを使用できるかどうかも異なります。
RARファイルごとに指定できるトランザクションサポートレベルを次の表に示します。

表3-29　RARファイルごとに使用できるトランザクションサポートレベル（Oracle11g）

使用するDB Connector
（RARファイル）
トランザクションサポートレベル
ライトトランザクション

有効
無効

DBConnector_Oracle_CP.rar
NoTransaction
LocalTransaction
○
○

DBConnector_Oracle_XA.rar
XATransaction
－
○

DBConnector_CP_ClusterPool_Root.rar
DBConnector_Oracle_CP_ClusterPool_Member.rar
NoTransaction
LocalTransaction
○
○

（凡例）　○：使用できる　　－：該当しない

(4)　Oracleと接続する場合の注意事項

ここでは，Oracleに接続する場合の使用時の注意について説明します。

(a)　使用できるJ2EEコンポーネントの違い

Oracle JDBC Thin DriverでOracleに接続する場合に使用できるJ2EEコンポーネントを次に示します。

サーブレット/JSP

Stateless Session Bean

Stateful Session Bean

Entity Bean（BMP）

Entity Bean（CMP2.0）

Message-driven Bean

(b)　型マッピング

Oracle JDBC Thin Driverを使用する場合のJavaの型とOracleのSQL型のマッピングを次の表に示します。

表3-30　Javaの型とOracleのSQL型のマッピング（Oracle JDBC Thin Driver）

メソッド | OracleのSQL型
CHAR | VARCHAR2 | NUMBER | DATE | TIMESTAMP | CLOB | LONG | BLOB | RAW | LONGRAW
set/getByte | ○ | ○ | ○ | － | － | － | ○ | － | － | －
set/getShort | ○ | ○ | ○ | － | － | － | ○ | － | － | －
set/getInt | ○ | ○ | ○ | － | － | － | ○ | － | － | －
set/getLong | ○ | ○ | ○ | － | － | － | ○ | － | － | －
set/getFloat | ○ | ○ | ○ | － | － | － | ○ | － | － | －
set/getDouble | ○ | ○ | ○ | － | － | － | ○ | － | － | －
set/getBigDecimal | ○ | ○ | ○ | － | － | － | ○ | － | － | －
set/getBoolean | ○ | ○ | ○ | － | － | － | ○ | － | － | －
set/getString | ○ | ○ | ○ | ○ | － | － | ○ | － | ○ | ○
set/getBytes | － | － | － | － | － | － | － | － | ○ | ○
set/getDate | ○ | ○ | － | ○ | － | － | ○ | － | － | －
set/getTime | ○ | ○ | － | ○ | － | － | ○ | － | － | －
set/getTimestamp | ○ | ○ | － | ○ | － | － | ○ | － | － | －
set/getClob | － | － | － | － | － | ○ | － | － | － | －
set/getBlob | － | － | － | － | － | － | － | ○ | － | －
set/getObject | ○ | ○ | ○ | ○ | － | ○ | ○ | ○ | ○ | ○

（凡例）

○：java.sql.PreparedStatement#setXXXおよびjava.sql.ResultSet#getXXXなどでマッピングできる

－：マッピングできない

注　この表は，Oracle9iのマッピングです。詳細やOracle10gおよびOracle11gについては，Oracleのマニュアルを参照してください。

(c)　日本語文字コード変換の相違点とOracle JDBC Thin Driverでの文字化けを回避するための設定

JDBCドライバでは，データをデータベースに格納するとき，およびデータベースからデータを取り出すときに，Unicodeとデータベース格納コードとの間で適宜，文字コードを変換します。ここでは，Oracle JDBC Thin Driverを使用する場合に文字コード変換が実施される場所を次の図に示します。

図3-18　Oracle JDBC Thin Driverを使用する場合に文字コード変換が実施される場所

図中の場所ごとに実行される文字コード変換について，次の表に示します。

表3-31　Oracle JDBC Thin Driverを使用する場合に文字コード変換が実施される場所

場所 | 実施される内容
1 | ネットワーク，ファイルなどの外部データをJ2EEサーバで読み込む時に，外部データコードからUnicodeに変換されます。
2 | J2EEサーバで読み込んだデータをOracleサーバに格納する時に，UnicodeからUTF-8に変換されます。J2EEサーバ上のJDBCドライバ部分で実施されるコード変換です。
3 | Oracleサーバのコンバータによって，UTF-8からデータベース格納コードへの変換が実施されます。Oracleサーバ上で実施されるコード変換です。
4 | Oracleサーバのコンバータによって，データベース格納コードからUTF-8への変換が実施されます。
5 | OracleサーバからJ2EEサーバが格納したデータを取得する時に，UTF-8からUnicodeに変換されます。
6 | J2EEサーバで取得したデータをネットワークやファイルなどに書き出す時に，Unicodeから外部データコードに変換されます。

Oracle JDBC Thin Driverを使用する場合，JavaVMとOracleサーバのコンバータがサポートしているマッピング規則の相違から，文字化けが発生することがあります。文字化けは，外部データの文字コードとデータベース格納コードの組み合わせや，文字コード変換を行うコンバータの組み合わせによって発生します。

文字化けを回避するためには，外部データの文字コードと，データベース格納コードを，次に示す組み合わせで使用してください。

外部データの文字コードがシフトJIS（CP932）の場合
データベース格納コードに「AL32UTF8」または「JA16SJISTILDE」を指定してください。なお，データベース格納コードに「JA16SJIS」を指定した場合，「～」の文字で文字化けが発生しますのでご注意ください。

外部データの文字コードがSJISの場合
データベース格納コードに「AL32UTF8」を指定してください。なお，データベース格納コードに「JA16SJIS」を指定した場合，「￠」「￡」「￢」「∥」「－」で文字化けが発生しますのでご注意ください。

外部データの文字コードがEUCの場合
データベース格納コードに「AL32UTF8」を指定してください。なお，データベース格納コードに「JA16EUC」を指定した場合，「￠」「￡」「￢」で文字化けが発生しますのでご注意ください。

(d)　データソースの設定

Oracleに対してXA接続でアクセスする場合，データソースの設定では，次の規則でXA Open Stringを指定する必要があります。

指定する文字列は，Oracleのマニュアルに記載されている規則に従って指定してください。キーワードなどの区切り文字が不正な場合は，Oracleライブラリ内でアプリケーションエラーが発生する場合がありますのでご注意ください。

指定する文字列には必ず，「Threads=true」を指定してください。「Threads=true」が指定されていない場合は，Oracleライブラリ内でアプリケーションエラーが発生，またはSQL実行時にエラーが発生することがありますのでご注意ください。

(5)　Oracle RACを使用したOracleへの接続方法

Oracle RACを使用したOracleへの接続方法は，Oracleのバージョン，または負荷分散に使用する機能によって異なります。Oracleのバージョン，負荷分散に使用する機能および使用するRARファイルの対応を次の表に示します。

表3-32　Oracleのバージョン，使用する機能および使用するRARファイルの対応

Oracleのバージョン
負荷分散に使用する機能
DB ConnectorのRARファイル名

Oarcle10g

Oracle11g

アプリケーションサーバの機能（コネクションプールのクラスタ化機能）
DBConnector_CP_ClusterPool_Root.rar
DBConnector_Oracle_CP_ClusterPool_Member.rar

Oracle9i

Oarcle10g

Oracle11g

Oracleの機能
DBConnector_Oracle_CP.rar
DBConnector_Oracle_CP_Cosminexus_RM.rar

3.6.7　SQL Serverと接続する場合の前提条件と注意事項

ここでは，SQL Serverと接続する場合の前提条件と注意事項について説明します。

＜この項の構成＞

(1)　SQL Serverの場合の前提条件

(2)　SQL Serverと接続する場合の注意事項

(1)　SQL Serverの場合の前提条件

SQL Serverの場合の前提条件について示します。

使用できるJDBCドライバ
使用できるJDBCドライバはSQL ServerのJDBCドライバとなります。

接続方法
DBConnector_SQLServer_CP.rarまたはDBConnector_SQLServer2005_CP.rarを使用します。使用するRARファイルは，接続するSQL Serverによって異なります。
RARファイルごとに指定できるトランザクションサポートレベルを次の表に示します。

表3-33　RARファイルごとに使用できるトランザクションサポートレベル（SQL Server）

使用するDB Connector
（RARファイル）
トランザクションサポートレベル
ライトトランザクション

有効
無効

DBConnector_SQLServer_CP.rar
DBConnector_SQLServer2005_CP.rar
NoTransaction
LocalTransaction
○
○

（凡例）　○：使用できる

なお，SQL Serverと接続できるのはWindowsの場合だけです。

(2)　SQL Serverと接続する場合の注意事項

ここでは，SQL Serverと接続する場合のシステムでの文字コード変換に関する注意事項とDB Connector設定時の注意事項について説明します。

(a)　システムでの文字コード変換時の注意

SQL Server接続時，データベースに日本語文字コードを含むデータを格納する場合，システムでの文字コード変換について考慮する必要があります。ここでは，システムでの文字コード変換の概要と，文字化けを回避するために設定時に注意することについて説明します。

Javaでは日本語文字コードはUnicodeで表現されます。SQL Serverを使用する場合，Webクライアントとアプリケーションサーバ間，およびアプリケーションサーバとSQL Server間の処理で文字コード変換が実施されます。

SQL Serverを使用する場合の文字コード変換の概要を次の図に示します。

図3-19　SQL Serverを使用する場合の文字コード変換の概要

図中の1.～4.について説明します。

アプリケーションサーバがWebクライアントからデータを受信する時に，外部文字コードからUnicodeに変換されます。

アプリケーションサーバがデータをSQL Serverに格納する時に，Unicodeからデータベース格納文字コードに変換されます。

SQL Serverに格納されたデータをアプリケーションサーバが取得する時に，データベース格納文字コードからUnicodeに変換されます。

アプリケーションサーバがデータをWebクライアントに送信する時に，Unicodeから外部文字コードに変換されます。

SQL Serverを使用する場合，外部文字コードとデータベース格納文字コードの組み合わせや，文字コード変換を実施する場合に使用されるコンバータの種類によっては，文字化けなどの問題が発生することがあります。このような文字化けを回避するためには，文字コードの設定に注意する必要があります。

SQL Serverでは次の表に示す文字データ型をサポートしています。SQL Serverを使用する場合，Unicodeデータ型を使用することによって，文字コード変換時に発生する文字化けを防ぐことができます。

表3-34　SQL Serverでサポートする文字データ型

カテゴリ | 文字データ型
Unicodeデータ型 | nchar，nvarchar，ntext
非Unicode文字データ型 | char，varchar，text

次に，SQL Serverでのデータベース格納文字コードとして，Unicodeデータ型を使用する場合と，非Unicodeデータ型を使用する場合の文字コード変換について説明します。

Unicodeデータ型を使用する場合

DB ConnectorのプロパティのsendStringParametersAsUnicodeキーにtrue（デフォルト値）を設定している場合，文字化けは発生しません。falseを設定した場合，外部文字コードにShift_JIS，EUC-JP，ISO-2022-JP，またはUTF-8を使用すると文字化けが発生することがあります。

非Unicode文字データ型を使用する場合

外部文字コードの設定によって，文字化けが発生することがあります。

外部文字コードにWindows-31Jを使用する場合
文字化けは発生しません。

外部文字コードにShift_JIS，EUC-JP，またはISO-2022-JPを使用する場合
次に示す文字などで文字化けが発生します。

外部文字コードにUTF-8を使用する場合
次に示す文字などで文字化けが発生します。

(b)　DB ConnectorのselectMethodプロパティ設定時の注意

DB ConnectorのselectMethodプロパティ（<config-property-name>の項目名）の値に「direct」を設定した場合の注意事項を次の表に示します。

表3-35　 DB ConnectorのselectMethodプロパティ設定時の注意事項

条件
注意事項

コネクションの障害検知機能が有効
コネクションに障害が発生していても正常であると誤診することがあります。その結果，ユーザアプリケーションプログラムに障害が発生したコネクションを返すことがあるので，コネクションの障害検知機能を使用しないでください。障害が発生したら，cjclearpoolコマンドを実行してください。

Statement，PreparedStatement，CallableStatementを複数同時に生成
SQL ServerのJDBCドライバによって，同時に生成したステートメントごとにSQL Server 2000への接続が生成されます。
また，ステートメントプーリング機能を使用する場合には，プールされているステートメントごとに接続が生成され，メモリを多く消費するので注意してください。

3.6.8　XDM/RD E2と接続する場合の前提条件と注意事項

ここでは，XDM/RD E2と接続する場合の前提条件と注意事項について説明します。

使用できるJDBCドライバ
使用できるJDBCドライバはHiRDB Type4 JDBC Driverとなります。

接続方法
DBConnector_HiRDB_Type4_CP.rarを使用します。
RARファイルごとに指定できるトランザクションサポートレベルを次の表に示します。

表3-36　RARファイルごとに使用できるトランザクションサポートレベル（XDM/RD E2）

使用するDB Connector
（RARファイル）
トランザクションサポートレベル
ライトトランザクション

有効
無効

DBConnector_HiRDB_Type4_CP.rar
NoTransaction
LocalTransaction
○
○

（凡例）　○：使用できる

3.6.9　実行環境での設定（リソースアダプタでの設定）

データベースに接続するための機能を使用する場合，属性ファイルの設定が必要です。

実行環境でのリソースアダプタの設定は，サーバ管理コマンドおよび属性ファイルを使用します。データベースに接続するための機能の定義には，Connector属性ファイルを使用します。

ここでは，使用する機能に関係なく，データベースに接続するために共通のDB Connectorの設定について説明します。

データベースコネクション確立までの待ち時間
<config-property>タグのloginTimeoutで，データベースコネクション確立までのJ2EEアプリケーションの待ち時間を指定します。

なお，データベースに接続するための設定については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「4.2　データベースと接続するための設定」を参照してください。

3.7　データベース上のキューとの接続

この節では，DB Connector for Cosminexus RMとCosminexus RMを使用してデータベース上のキューと接続する機能について説明します。

この節の構成を次の表に示します。

表3-37　この節の構成（データベース上のキューとの接続）

分類 | タイトル | 参照先
解説 | DB Connector for Cosminexus RMとCosminexus RMによる接続の概要 | 3.7.1
DB Connector for Cosminexus RMとCosminexus RMによる接続の特徴 | 3.7.2
使用できる機能 | 3.7.3
接続できるデータベース | 3.7.4
DB Connector for Cosminexus RM（RARファイル）の種類 | 3.7.5
HiRDBのキューに接続する場合の前提条件 | 3.7.6
Oracleのキューに接続する場合の前提条件 | 3.7.7
設定 | データベース上のキューに接続するための設定 | 3.7.8

注　「実装」および「運用」について，この機能固有の説明はありません。

データベース上のキューと接続するためには，リソースアダプタとしてDB Connector for Cosminexus RMとCosminexus RMを使用します。

Cosminexus RMの詳細については，マニュアル「Cosminexus Reliable Messaging」を参照してください。また，接続できるデータベースについては，「3.6　データベースへの接続」を参照してください。

＜この節の構成＞

3.7.1　DB Connector for Cosminexus RMとCosminexus RMによる接続の概要

3.7.2　DB Connector for Cosminexus RMとCosminexus RMによる接続の特徴

3.7.3　使用できる機能

3.7.4　接続できるデータベース

3.7.5　DB Connector for Cosminexus RM（RARファイル）の種類

3.7.6　HiRDBのキューに接続する場合の前提条件

3.7.7　Oracleのキューに接続する場合の前提条件

3.7.8　データベース上のキューに接続するための設定

3.7.1　DB Connector for Cosminexus RMとCosminexus RMによる接続の概要

DB Connector for Cosminexus RMは，Cosminexus RMと連携して，JMSインタフェースを使用してデータベースと接続するためのリソースアダプタです。

Cosminexus RMと連携することによって，サーブレット，JSP，Enterprise Bean（Session Bean，Entity Bean，Message-driven Bean）から，JMSインタフェースを使用してデータベース上のキューにアクセスできます。また，JDBCインタフェースを使用して，データベース上のテーブルにもアクセスできます。

JMSインタフェースとJDBCインタフェースを使用して同じデータベースにアクセスするとき，グローバルトランザクションを1フェーズコミットで処理できます。これによって，処理性能が向上します。また，JMSインタフェースとJDBCインタフェースによるデータベース接続に使用する物理コネクションを共通できるため，リソースを有効活用できるようになります。

DB Connector for Cosminexus RMとCosminexus RMによる接続の概要を次の図に示します。

図3-20　DB Connector for Cosminexus RMとCosminexus RMによる接続の概要

DB Connector for Cosminexus RMとCosminexus RMによるデータベース接続では，JDBCドライバに，HiRDB Type4 JDBC DriverまたはOracle JDBC Thin Driverを使用します。

DB Connector for Cosminexus RMの設定の詳細については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「14.1　リソースアダプタの設定の概要」，およびマニュアル「Cosminexus Reliable Messaging」の「2.7　DB Connector for Cosminexus RMの機能」を参照してください。

3.7.2　DB Connector for Cosminexus RMとCosminexus RMによる接続の特徴

ここでは，DB Connector for Cosminexus RMとCosminexus RMによる接続の特徴について説明します。

＜この項の構成＞

(1)　DB Connector for Cosminexus RMおよびCosminexus RMによる処理の概要

(2)　DB Connector for Cosminexus RMとCosminexus RMによるデータベース接続の構成

(1)　DB Connector for Cosminexus RMおよびCosminexus RMによる処理の概要

DB Connector for Cosminexus RMを使用してCosminexus RMと連携することによって，データベース上のキューに対するJMSインタフェースによるメッセージの送受信や，メッセージによって起動されるMessage-driven Beanの呼び出しなどができます。

DB Connector for Cosminexus RMとCosminexus RMによってデータベースに接続する場合，JMSインタフェースとJDBCインタフェースによるアクセスで使用する物理コネクションを共有することによって次のことが実現できるため，処理性能が向上します。

ローカルトランザクションの適用

グローバルトランザクションの1フェーズコミット

サーブレット，JSP，または，Enterprise Beanから，JMSインタフェースとJDBCインタフェースを使用して，データベースにアクセスするときのDB Connector for Cosminexus RMおよびCosminexus RMの処理の概要を次の図に示します。

図3-21　DB Connector for Cosminexus RMおよびCosminexus RMの処理の概要

JMSインタフェースによるアクセスはCosminexus RMを経由して，JDBCインタフェースによるアクセスはDB Connector for Cosminexus RMを経由して，データベースにアクセスします。なお，Cosminexus RMでは，キューをデータベース上に構築するため，内部的にJDBCインタフェースによるデータベースへのアクセスを使用します。そのため，JDBCドライバを経由してデータベースにアクセスします。

また，DB Connector for Cosminexus RMでは，Cosminexus RMを経由して，Cosminexus RMと物理コネクションを共有してデータベースにアクセスします。これらのリソースアダプタでは，Cosminexus RM用のコネクションプールを利用してコネクションを取得します。これによって，物理コネクションの共有を実現しています。

(2)　DB Connector for Cosminexus RMとCosminexus RMによるデータベース接続の構成

DB Connector for Cosminexus RMとCosminexus RMを使用して接続する場合のリソースの構成パターンについて説明します。ここでは，次に示す場合のリソースの構成について説明します。

JMSインタフェースだけを使用する場合

JMSインタフェースとJDBCインタフェースで同一データベースにアクセスする場合

JMSインタフェースとJDBCインタフェースで異なるデータベースにアクセスする場合

Message-driven Beanを使用する場合

なお，JMSインタフェースとJDBCインタフェースで同一データベースにアクセスする場合と，Message-driven Beanを使用する場合は，コネクションの共有ができます。ただし，コネクションを共有するためには，次に示す前提条件を満たしている必要があります。

コネクション共有の前提条件

ユーザプログラムで，同一トランザクション内でJMSインタフェースによるデータベース上のキューへのアクセスと，JDBCインタフェースによるテーブルへのアクセスを実施する。

Cosminexus RMによってキューを構築するデータベースと，テーブルにアクセスするデータベースが同じである。

JMSインタフェースよるデータベース上のキューへのアクセスと，JDBCインタフェースによるデータベース上のテーブルへのアクセスで使用するセキュリティ情報（ユーザ名，パスワード）と，サインオンの方式が同じである。

DB Connector for Cosminexus RMとCosminexus RMへのリファレンスを設定しているJ2EEアプリケーションで，DDの<res-sharing-scope>タグの値に「Shareable」が設定されている。

注意

JDBCインタフェースだけを使用してデータベースにアクセスする場合，リソースアダプタとしてDB Connectorを使用してください。

コネクション共有の前提条件を満たさない場合，DB Connector for Cosminexus RMとCosminexus RMによってJMSインタフェースとJDBCインタフェースの両方を使用したデータベースへのアクセスはしないでください。この場合，「(c)　JMSインタフェースとJDBCインタフェースで異なるデータベースにアクセスする場合」に示す構成にして，テーブルへのアクセスにはDB Connectorを使用してください。

(a)　JMSインタフェースだけを使用する場合

ユーザプログラムでデータベース上のキューに対してだけアクセスする場合，次の図に示す構成で使用します。

図3-22　JMSインタフェースだけを使用する場合の構成

(b)　JMSインタフェースとJDBCインタフェースで同一データベースにアクセスする場合

ユーザプログラムでJMSインタフェースとJDBCインタフェースを使用してデータベースにアクセスする場合，コネクション共有の前提条件を満たしているときは，2種類のインタフェースで同一のデータベースにアクセスできます。このとき，次の図に示す構成で使用します。

この構成にすることによって，コネクションの共有によるトランザクション処理性能の向上とリソースの有効利用を実現できます。

図3-23　JMSインタフェースとJDBCインタフェースでアクセスするデータベースが同じ場合の構成

(c)　JMSインタフェースとJDBCインタフェースで異なるデータベースにアクセスする場合

ユーザプログラムでJMSインタフェースとJDBCインタフェースを使用してデータベースにアクセスする場合，コネクション共有の前提条件を満たしていないときは，インタフェースごとに，異なるデータベースにアクセスする構成にする必要があります。このとき，次の図に示す構成で使用します。

図3-24　JMSインタフェースとJDBCインタフェースでアクセスするデータベースが異なる場合の構成

データベース上のキューへのアクセスには，DB Connector for Cosminexus RMとCosminexus RMを使用します。また，データベース上のテーブルへのアクセスには，DB Connectorを別途用意して使用する必要があります。

(d)　Message-driven Beanを使用する場合

Message-driven Beanを使用する場合，次の図に示す構成で使用します。コネクションの共有条件を満たす場合には，DB Connector for Cosminexus RMのJDBCインタフェースを使用して，Message-driven BeanとJDBCインタフェースでコネクションを共有することができます。

なお，Message-driven Beanを使用する場合，関連づけるリソースアダプタがCosminexus RM 01-01以降のときは，グローバルトランザクションおよびローカルトランザクションを使用できます。Cosminexus RM 01-00のリソースアダプタを使用する場合は，グローバルトランザクションを使用する必要があります。このとき，ローカルトランザクションを使用することはできませんが，コネクション共有の前提条件を満たしていれば，グローバルトランザクションは1フェーズで決着されます。

図3-25　Message-driven Beanを使用する場合の構成

3.7.3　使用できる機能

DB Connector for Cosminexus RMとCosminexus RMによる接続で使用できる機能の詳細については，マニュアル「Cosminexus Reliable Messaging」の「2.7　DB Connector for Cosminexus RMの機能」を参照してください。

なお，JDBCインタフェースを使用してデータベースに接続する場合，DB Connectorを使用して接続する場合と同じ機能を利用できます。利用できる機能の詳細については，「3.3.4　リソースアダプタの機能」を参照してください。

3.7.4　接続できるデータベース

ここでは，DB Connector for Cosminexus RMとCosminexus RMを使用して接続できるデータベースについて説明します。

＜この項の構成＞

(1)　接続できるデータベースの種類

(2)　データベースとJDBCドライバの対応

(3)　注意事項

(1)　接続できるデータベースの種類

DB Connector for Cosminexus RMとCosminexus RMを使用して接続できるデータベースには，HiRDB，およびOracleがあります。なお，SQL Server，およびXDM/RD E2には接続できません。

(2)　データベースとJDBCドライバの対応

DB Connector for Cosminexus RMとCosminexus RMを使用してデータベースに接続するためには，データベースに対応するJDBCドライバが必要です。

接続先のデータベースと使用できるJDBCドライバについて次の表に示します。

表3-38　接続先のデータベースと使用できるJDBCドライバ（データベース上のキューとの接続の場合）

データベース | JDBCドライバ
HiRDB Type4 JDBC Driver | Oracle JDBC Thin Driver
HiRDB Version 8 | ○ | ×
HiRDB Version 9 | ○ | ×
Oracle | × | ○

（凡例）　○：使用できる　　×：使用できない

(3)　注意事項

DB Connector for Cosminexus RMとCosminexus RMを使用してデータベースに接続する場合の注意事項を次に示します。

DB Connector for Cosminexus RMが提供するJDBCコネクション（java.sql.Connection. Connection）では，JDBC固有のトランザクション制御はできません。JDBC固有のトランザクション制御を行った場合，setAutoCommit(boolean)メソッドの引数falseでの呼び出しのときと，releaseSavepoint(SavePoint)メソッド，rollback(Savepoint)メソッド，setSavepoint()メソッド，およびsetSavepoint(String)メソッドの呼び出しのときに例外が発生します。JDBC固有のトランザクション制御を行う場合は，DB Connectorを使用してください。

DB Connector for Cosminexus RMの場合，性能解析トレースの取得ポイントおよびイベントIDがDB Connectorの場合と一部異なります。
JDBCコネクション（java.sql.Connection. Connection）に関しては，1回のアクセスでDB Connector for Cosminexus RMのJDBCコネクションと，DB ConnectorでのJDBCコネクションの二つのトレース取得ポイントで性能解析トレースが出力されます。
また，JDBCコネクションの生成物（java.sql.Statementなど）は，DB Connectorと同様のトレース取得ポイントで性能解析トレースが出力されます。java.sql.DataSourceは，DB Connector for Cosminexus RM用のトレース取得ポイントでだけ性能解析トレースが出力されます。

DB Connector for Cosminexus RMでは，稼働情報監視をした場合，DB Connector for Cosminexus RMのリソースアダプタの次の項目について，正しい値が出力されません。DB Connector for Cosminexus RM はコネクションをCosminexus RM経由で取得するため，連携するリソースアダプタの監視稼働情報はCosminexus RM側に累積され出力されます。

トランザクションサポートレベル

プール現在値（総数）

使用中のコネクション数

未使用のコネクション数

ManagedConnectionFactoryのcreateManagedConnection()メソッドの実行回数

ManagedConnectionのgetConnection()メソッドの実行回数

ManagedConnectionのcleanup()メソッドの実行回数

ManagedConnectionのdestroy()メソッドの実行回数

ConnectionManagerのallocateConnection()メソッドの実行時間

ManagedConnectionFactoryのcreateManagedConnection()メソッドの実行時間

ConnectionManagerのallocateConnection()メソッドの失敗回数

ManagedConnectionでFATALエラーが発生した回数

DB Connector for Cosminexus RMは，連携するCosminexus RM側のコネクションプールを共有します。そのため，DB Connector for Cosminexus RMには，コネクションプールの各機能の設定をする必要はありません。

リソースアダプタを使用する場合，J2EEアプリケーションからリソースアダプタへのリファレンスを解決しておく必要があります。リソースアダプタを使用しているJ2EEアプリケーションをカスタマイズするときに，J2EEアプリケーションからリソースアダプタへのリファレンスを解決しておいてください。

3.7.5　DB Connector for Cosminexus RM（RARファイル）の種類

DB Connector for Cosminexus RMを使用してデータベースに接続する場合，使用するJDBCドライバに応じたRARファイルを使用します。RARファイルは，サーバ管理コマンドを使用して操作します。サーバ管理コマンドを使用してRARファイルを操作する方法については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」を参照してください。

JDBCドライバの種類と対応するRARファイルについて次の表に示します。

表3-39　JDBCドライバとRARファイルの対応

JDBCドライバ | RARファイル | 説明
HiRDB Type4 JDBC Driver | DBConnector_HiRDB_Type4_CP_Cosminexus_RM.rar | トランザクション管理をしない場合，またはローカルトランザクションを使用する場合に使用します。
DBConnector_HiRDB_Type4_XA_Cosminexus_RM.rar※ | グローバルトランザクションを使用する場合に使用します。
Oracle JDBC Thin Driver | DBConnector_Oracle_CP_Cosminexus_RM.rar | トランザクション管理をしない場合，またはローカルトランザクションを使用する場合に使用します。
DBConnector_Oracle_XA_Cosminexus_RM.rar※ | グローバルトランザクションを使用する場合に使用します。

注※　ライトトランザクション機能は有効にできません。

3.7.6　HiRDBのキューに接続する場合の前提条件

ここでは，HiRDBのキューに接続する場合の前提条件について説明します。

＜この項の構成＞

(1)　HiRDB Version 8の場合の前提条件

(2)　HiRDB Version 9の場合の前提条件

(1)　HiRDB Version 8の場合の前提条件

HiRDB Version 8の場合の前提条件について示します。

使用できるJDBCドライバ
使用できるJDBCドライバはHiRDB Type4 JDBC Driverとなります。

接続方法
次のどちらかのRARファイルを使用します。

DBConnector_HiRDB_Type4_CP_Cosminexus_RM.rar

DBConnector_HiRDB_Type4_XA_Cosminexus_RM.rar

RARファイルの種類に応じて，指定できるトランザクションサポートレベルが異なります。また，ライトトランザクションを使用できるかどうかも異なります。
RARファイルごとに指定できるトランザクションサポートレベルを次の表に示します。

表3-40　RARファイルごとに使用できるトランザクションサポートレベル（HiRDB Version 8）

使用するDB Connector for Cosminexus RM
（RARファイル）
トランザクションサポートレベル
ライトトランザクション

有効
無効

DBConnector_HiRDB_Type4_CP_Cosminexus_RM.rar
NoTransaction
LocalTransaction
○
○

DBConnector_HiRDB_Type4_XA_Cosminexus_RM.rar
XATransaction
－
○

（凡例）　○：使用できる　　－：該当しない

(2)　HiRDB Version 9の場合の前提条件

HiRDB Version 9の場合の前提条件について示します。

使用できるJDBCドライバ
使用できるJDBCドライバはHiRDB Type4 JDBC Driverとなります。

接続方法
次のどちらかのRARファイルを使用します。

DBConnector_HiRDB_Type4_CP_Cosminexus_RM.rar

DBConnector_HiRDB_Type4_XA_Cosminexus_RM.rar

RARファイルの種類に応じて，指定できるトランザクションサポートレベルが異なります。また，ライトトランザクションを使用できるかどうかも異なります。
RARファイルごとに指定できるトランザクションサポートレベルを次の表に示します。

表3-41　RARファイルごとに使用できるトランザクションサポートレベル（HiRDB Version 9）

使用するDB Connector for Cosminexus RM
（RARファイル）
トランザクションサポートレベル
ライトトランザクション

有効
無効

DBConnector_HiRDB_Type4_CP_Cosminexus_RM.rar
NoTransaction
LocalTransaction
○
○

DBConnector_HiRDB_Type4_XA_Cosminexus_RM.rar
XATransaction
－
○

（凡例）　○：使用できる　　－：該当しない

3.7.7　Oracleのキューに接続する場合の前提条件

ここでは，Oracleのキューに接続する場合の前提条件について説明します。

＜この項の構成＞

(1)　Oracle9iの場合の前提条件

(2)　Oracle10gおよびOracle11gの場合の前提条件

(1)　Oracle9iの場合の前提条件

Oracle9iの場合の前提条件について示します。

使用できるJDBCドライバ
使用できるJDBCドライバはOracle JDBC Thin Driverとなります。

接続方法
DBConnector_Oracle_CP_Cosminexus_RM.rarまたはDBConnector_Oracle_XA_Cosminexus_RM.rarを使用します。
RARファイルの種類に応じて，指定できるトランザクションサポートレベルが異なります。また，ライトトランザクションを使用できるかどうかも異なります。
RARファイルごとに指定できるトランザクションサポートレベルを次の表に示します。

表3-42　RARファイルごとに使用できるトランザクションサポートレベル（Oracle9i）

使用するDB Connector for Cosminexus RM
（RARファイル）
トランザクションサポートレベル
ライトトランザクション

有効
無効

DBConnector_Oracle_CP_Cosminexus_RM.rar
NoTransaction
LocalTransaction
○
○

DBConnector_Oracle_XA_Cosminexus_RM.rar
XATransaction
－
○

（凡例）　○：使用できる　　－：該当しない

(2)　Oracle10gおよびOracle11gの場合の前提条件

Oracle10gおよびOracle11gで使用できるJDBCドライバおよび接続方法は，Oracle9iの場合と同じです。「(1)　Oracle9iの場合の前提条件」を参照してください。

3.7.8　データベース上のキューに接続するための設定

データベース上のキューに接続するための設定については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「14.1　リソースアダプタの設定の概要」およびマニュアル「Cosminexus Reliable Messaging」の「2.7　DB Connector for Cosminexus RMの機能」を参照してください。

3.8　OpenTP1とのOutboundでの接続（SPPまたはTP1/Message Queue）

この節では，OpenTP1（SPPまたはTP1/Message Queue）とOutboundで接続する機能について説明します。

この節の構成を次の表に示します。

表3-43　この節の構成（OpenTP1とのOutboundでの接続（SPPまたはTP1/Message Queue））

分類 | タイトル | 参照先
解説 | uCosminexus TP1 Connectorによる接続 | 3.8.1
TP1/Message Queue - Accessによる接続 | 3.8.2
設定 | OpenTP1とOutboundで接続するための設定 | 3.8.3

注　「実装」および「運用」について，この機能固有の説明はありません。

アプリケーションサーバでは，OpenTP1 SPPまたはTP1/Message Queueと接続できます。OpenTP1との接続には，次のリソースアダプタを使用します。

OpenTP1 SPPとの接続の場合，uCosminexus TP1 Connectorを使用します。

TP1/Message Queueとの接続の場合，TP1/Message Queue - Accessを使用します。

ここでは，OpenTP1との接続について説明します。

＜この節の構成＞

3.8.1　uCosminexus TP1 Connectorによる接続

3.8.2　TP1/Message Queue - Accessによる接続

3.8.3　OpenTP1とOutboundで接続するための設定

3.8.1　uCosminexus TP1 Connectorによる接続

J2EEサーバとOpenTP1 SPPの接続には，リソースアダプタとしてuCosminexus TP1 ConnectorとTP1/Client/Jを組み合わせて利用します。

OpenTP1との連携について次の図に示します。

図3-26　uCosminexus TP1 Connectorを利用したOpenTP1との連携

uCosminexus TP1 Connectorは，TP1/Client/JのRPCを使用してOpenTP1と接続し，OpenTP1のSPPにアクセスします。これによって，J2EEサーバでは，OpenTP1のSPPと連携することができます。

注意

リソースアダプタを使用する場合，J2EEアプリケーションからリソースアダプタへのリファレンスを解決しておく必要があります。リソースアダプタを使用しているJ2EEアプリケーションをカスタマイズするときに，J2EEアプリケーションからリソースアダプタへのリファレンスを解決しておいてください。

uCosminexus TP1 Connectorの設定項目の詳細については，uCosminexus TP1 Connectorのドキュメントを参照してください。TP1/Client/Jの設定項目の詳細については，マニュアル「OpenTP1 クライアント使用の手引 TP1/Client/J編」を参照してください。

また，サーバ管理コマンドを使用したリソースアダプタの設定方法については，uCosminexus TP1 Connectorのドキュメント，マニュアル「OpenTP1 クライアント使用の手引 TP1/Client/J編」，およびマニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「4.4　そのほかのリソースと接続するための設定」を参照してください。

3.8.2　TP1/Message Queue - Accessによる接続

アプリケーションサーバとTP1/Message Queueの接続には，リソースアダプタとしてTP1/Message Queue - Accessを利用します。

TP1/Message Queue - Accessを利用したTP1/Message Queueとの連携について次の図に示します。

図3-27　TP1/Message Queue - Accessを利用したTP1/Message Queueとの連携

TP1/Message Queue - Accessでは，JMSインタフェースを提供しています。このJMSインタフェースを利用して，J2EEサーバはTP1/Message Queueと接続します。

注意

リソースアダプタを使用する場合，J2EEアプリケーションからリソースアダプタへのリファレンスを解決しておく必要があります。リソースアダプタを使用しているJ2EEアプリケーションをカスタマイズするときに，J2EEアプリケーションからリソースアダプタへのリファレンスを解決しておいてください。

TP1/Message Queue - Accessの設定項目の詳細については，マニュアル「OpenTP1 Version 7 メッセージキューイングアクセス機能 TP1/Message Queue - Access 使用の手引」を参照してください。

また，サーバ管理コマンドを使用したリソースアダプタの設定方法については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「4.4　そのほかのリソースと接続するための設定」を参照してください。

3.8.3　OpenTP1とOutboundで接続するための設定

uCosminexus TP1 Connectorによって接続する場合の設定については，uCosminexus TP1 Connectorのドキュメント，マニュアル「OpenTP1 クライアント使用の手引 TP1/Client/J編」，およびマニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「4.4　そのほかのリソースと接続するための設定」を参照してください。

TP1/Message Queue - Accessによって接続する場合の設定については，マニュアル「OpenTP1 Version 7 メッセージキューイングアクセス機能 TP1/Message Queue - Access 使用の手引」，およびマニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「4.4　そのほかのリソースと接続するための設定」を参照してください。

3.9　OpenTP1とのInboundでの接続

OpenTP1を使用したレガシーシステム上のSUPから，アプリケーションサーバのJ2EEサーバ上で動作している業務プログラムを呼び出す場合，OpenTP1とJ2EEサーバの接続には，リソースアダプタとしてTP1インバウンドアダプタを使用します。

TP1インバウンドアダプタは，Connector 1.5仕様に準拠したリソースアダプタです。また，次の機能を備えています。

OpenTP1のスケジュールサービスの代替機能

OpenTP1とRPC通信を実行するための機能

これらの機能を使用することで，OpenTP1のSUPからは，OpenTP1のSPPを呼び出す場合と同様の手順でJ2EEサーバ上の業務プログラムを呼び出せます。

TP1インバウンドアダプタを使用したOpenTP1との接続の詳細については，「4.　OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）」を参照してください。

注意

TP1インバウンド連携機能はSUP，SPPおよびMHPからの呼び出しが可能ですが，このマニュアルでは，SUPからの呼び出しを例に説明します。

3.10　Cosminexus JMSプロバイダとの接続

アプリケーションサーバが提供するJMSプロバイダの機能を使用する場合，メッセージの送信先の管理にCJMSPブローカーというプロセスを使用します。J2EEサーバとCJMSPブローカーとの接続には，CJMSPリソースアダプタを使用します。

CJMSPリソースアダプタを使用することで，PTPメッセージングモデルまたはPub/Subメッセージングモデルでのメッセージの送受信を実現できます。

CJMSPリソースアダプタを使用したOpenTP1との接続の詳細については，「7.　Cosminexus JMSプロバイダ」を参照してください。

3.11　SMTPサーバとの接続

J2EEアプリケーションは，JavaMailを使用して，SMTPサーバにメールを送信できます。

SMTPサーバとの接続の設定については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「6.3　メールコンフィグレーションの設定」を参照してください。

3.12　JavaBeansリソースの利用

この節では，JavaBeansリソースの利用について説明します。

この節の構成を次の表に示します。

表3-44　この節の構成（JavaBeansリソースの利用）

分類 | タイトル | 参照先
解説 | JavaBeansリソースの機能 | 3.12.1
JavaBeansリソースの開始処理の流れ | 3.12.2
実装 | JavaBeansリソースの実装 | 3.12.3
設定 | JavaBeansリソースの設定 | 3.12.4
JavaBeansリソースの入れ替え | 3.12.5

注　「運用」について，この機能固有の説明はありません。

＜この節の構成＞

3.12.1　JavaBeansリソースの機能

3.12.2　JavaBeansリソースの開始処理の流れ

3.12.3　JavaBeansリソースの実装

3.12.4　JavaBeansリソースの設定

3.12.5　JavaBeansリソースの入れ替え

3.12.1　JavaBeansリソースの機能

JavaBeansリソースでは，J2EEアプリケーションを稼働させるための設定値などを一括して保持，管理できます。J2EEアプリケーションからJNDIを使用してJavaBeansリソースをルックアップすることで，設定値を取得できます。

3.12.2　JavaBeansリソースの開始処理の流れ

J2EEサーバで，複数のJavaBeansリソースを開始状態にできます。サーバ管理コマンドを使用した場合の，JavaBeansリソースの開始処理の流れを次の図に示します。

図3-28　JavaBeansリソースの開始処理の流れ

JavaBeansリソースをインポートして，開始する。
サーバ管理コマンドを使用して，J2EEサーバにJavaBeansリソースをインポートして開始します。

ネーミングサービスにJavaBeansリソースのリファレンスを登録する。
JavaBeansリソースの開始時に，ネーミングサービスのJ2EEリソース用の名前空間にJavaBeansリソースのリファレンスを登録します。

J2EEアプリケーションからネーミングサービスにルックアップする。
JavaBeansリソースを利用するJ2EEアプリケーションから，ネーミングサービスにルックアップを行います。ルックアップ処理の延長でJavaBeansリソースのsetメソッドが呼ばれて，JavaBeansリソース属性ファイルに指定したプロパティ値が設定されます。

取得したリファレンスを使用して，JavaBeansリソースのgetメソッドを呼び出す。
ルックアップして取得したリファレンスを使用して，JavaBeansリソースのgetメソッドの呼び出しを行い，setメソッドで設定した値をgetメソッドで取得します。

JavaBeansリソースの実装クラスは，単独のクラスで構成される場合はクラスファイルの形式で，JavaBeansリソースのクラスと関連クラスのように複数のクラスで構成される場合はJARファイルの形式で利用できます。

3.12.3　JavaBeansリソースの実装

JavaBeansリソースの実装手順を，例を用いて説明します。

＜この項の構成＞

(1)　インポート時の設定

(2)　JavaBeansリソースの実装クラスの作成

(3)　アプリケーションの設定

(4)　アプリケーションの開始と終了

(1)　インポート時の設定

サーバ管理コマンド（cjimportjbコマンド）でJavaBeansリソースをインポートするときに必要な設定と注意事項を示します。

(a)　JavaBeansリソース属性ファイルの設定

JavaBeansリソース属性ファイルは，次に示す点に留意して作成してください。

<res-type>タグおよび<class-name>タグには，JavaBeansリソースのクラス名，実装クラス名を指定します。<res-type>タグおよび<class-name>タグで同じ値を設定する場合は<res-type>タグは省略できます。

<property-name>タグには，setメソッドおよびgetメソッドのメソッド名称を指定します。

<property-type>タグには，setメソッドの引数の型を指定します。
<property-type>タグの値と実際の該当setメソッドの引数型と合わない場合はlookup時にエラーになります。

<property-value>タグには，setメソッドの引数に渡す値を指定します。

JavaBeansリソース属性ファイルの設定例を示します。

<!DOCTYPE hitachi-javabeans-resource-property PUBLIC '-//Hitachi, Ltd.//DTD JavaBeans Resource Property 7.0//EN'
'http://localhost/hitachi-javabeans-resource-property_7_0.dtd'>

<hitachi-javabeans-resource-property>
 <description></description>
 <display-name>JavaBean_resource</display-name>
   <class-name>com.mycompany.mypackage.MyJavaBean</class-name>
   <runtime>
     <property>
       <property-name>UserName</property-name>
       <property-type>java.lang.String</property-type>
       <property-value>Hitachi</property-value>
     </property>
     <property>
       <property-name>UserID</property-name>
       <property-type>java.lang.String</property-type>
       <property-value>01234567</property-value>
     </property>
   </runtime>
</hitachi-javabeans-resource-property>

JavaBeansリソース属性ファイルのテンプレートファイル（jb_template.xml）は，次のディレクトリに格納されています。

<Cosminexusのインストールディレクトリ>¥CC¥admin¥templates

(b)　-dオプションの使い方

インポート時に-dオプションを使用することで，アーカイブを作成しないで，ディレクトリ構成のままインポートできます。-dで指定するディレクトリは，インポートするディレクトリの最上位を指定します。

インポートするときの-dオプションの指定例を次に示します。この指定例では，パッケージ名がcom.mycompany.mypackageのMyJavaBeanクラスをインポートします。

-dで指定するディレクトリ¥
 └ com¥
    └ mycompany
       └ mypackage
            └ MyJavaBean.class

-dオプションは指定されたディレクトリ下に存在するものをすべてインポートするので，不要なファイルはディレクトリ内に含めないでください。

複数のJavaBeansリソースをインポートする場合の注意

インポート済みのJavaBeansリソースと同じ実装クラス名のJavaBeansリソースはインポートできません。先にインポートしたJavaBeansリソースを削除してからインポートするか，実装クラス名を変更し，作成し直してからインポートしてください。

(2)　JavaBeansリソースの実装クラスの作成

JavaBeansで管理するデータ（プロパティ）を操作するメソッドを宣言します。データを登録する場合，setメソッド（set＋プロパティ名）を設定します。データを参照する場合，getメソッド（get＋プロパティ名）を設定します。

次に，JavaBeansリソースを登録，参照するクラスの実装例を示します。

package com.mycompany.mypackage;
public class MyJavaBean {
   private String username;
   private String userid;

   public void setUserName(String user_name) {
       this.username = user_name;
   }
   public void setUserID(String user_id) {
       this.userid = user_id;
   }
   public String getUserName() {
       return this.username;
   }
   public int getUserID() {
       return this.userid;
   }
}

(3)　アプリケーションの設定

JavaBeansリソースを利用するときに，アプリケーション側で必要な実装および定義について説明します。

(a)　lookupの実装（JavaBeansリソース）

JavaBeansリソースを，ルックアップまたはDIを使用して取得します。ここでは，"java:comp/env"形式でルックアップする方法を示します。

Context initCtx = new InitialContext();
MyJavaBean jb = (MyJavaBean) initCtx.lookup("java:comp/env/bean/myJB");

JavaBeansリソースをルックアップできる範囲は，ほかのリソース同様に，同じJ2EEサーバプロセス内のアプリケーションです。

(b)　DDの定義内容（JavaBeansリソース）

ルックアップを使用してJavaBeansリソースを取得する場合，ルックアップする名前や実装クラス名の情報をDD（ejb-jar.xmlまたはweb.xml）に定義します。設定するタグを次に示します。

<resource-env-ref-name>タグに，ルックアップで"java:comp/env"形式に指定する値を指定します。

<resource-env-ref-type>タグに，JavaBeansリソースの実装クラス名を指定します。

また，作成したアプリケーションをJ2EEサーバ上にデプロイするときに，ルックアップでの参照用の名称と実際の名称をlinked-toで結び付けます。この操作をするには，サーバ管理コマンド（cjsetapppropコマンド）を使用します。

cjgetapppropで該当アプリケーションの属性ファイルを取得します。

<resource-env-ref>タグに<linked-to>タグを追加して，利用するJavaBeansリソースの表示名を指定します。

cjsetapppropで該当アプリケーションの属性ファイルを設定します。

次に，cjsetapppropで渡す属性ファイルの<resource-env-ref>タグの例を示します。

<resource-env-ref>
 <resource-env-ref-name>bean/myJB</resource-env-ref-name>
 <resource-env-ref-type>com.mycompany.mypackage.MyJavaBean</resource-env-ref-type>
 <linked-to>JavaBean_resource</linked-to>
</resource-env-ref>

(4)　アプリケーションの開始と終了

JavaBeansリソースを利用するアプリケーションの開始，終了は，サーバ管理コマンドまたはManagement Serverで操作します。アプリケーションの開始方法については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「10.2.1　J2EEアプリケーションの開始」を参照してください。アプリケーションの終了方法については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「10.2.2　J2EEアプリケーションの停止」を参照してください。

アプリケーションサーバでは，JavaBeansリソースのサンプルプログラムを提供します。サンプルプログラムの概要および実行方法については，マニュアル「Cosminexus アプリケーションサーバ システム構築・運用ガイド」の「付録F.6　JavaBeansリソースのサンプルプログラム」を参照してください。

3.12.4　JavaBeansリソースの設定

ここでは，JavaBeansリソースの設定について説明します。

サーバ管理コマンドを使用してJavaBeansリソースのプロパティを設定し，JavaBeansリソースをインポートします。

JavaBeansリソースの設定には，サーバ管理コマンドを使用します。

ここでは，JavaBeansリソースの新規設定の流れ，設定変更の流れ，および入れ替えの流れについて説明します。

＜この項の構成＞

(1)　JavaBeansリソースの新規設定の流れ

(2)　JavaBeansリソースの設定変更の流れ

(3)　JavaBeansリソースの入れ替えの流れ

(4)　JavaBeansリソースのプロパティ定義で設定できること

(1)　JavaBeansリソースの新規設定の流れ

JavaBeansリソースの新規設定の流れを次の図に示します。

図3-29　JavaBeansリソースの新規設定の流れ

図中の1.～2.について説明します。

JavaBeansリソース属性ファイルを作成し，JavaBeansリソースのプロパティを定義します。
JavaBeansリソース属性ファイルのテンプレートを使用してJavaBeansリソース属性ファイルを作成して，JavaBeansリソースのプロパティを定義してください。JavaBeansリソース属性ファイルのテンプレートは次のディレクトリに格納されています。

Windowsの場合
<Cosminexusインストールディレクトリ>¥CC¥admin¥templates¥jb_template.xml

UNIXの場合
/opt/Cosminexus/CC/admin/templates/jb_template.xml

JavaBeansリソースのプロパティ定義で設定できる内容については，「(4)　JavaBeansリソースのプロパティ定義で設定できること」を参照してください。

サーバ管理コマンドを使用して，JavaBeansリソースをインポートします。
1.で設定したJavaBeansリソース属性ファイルと，JavaBeansリソースを含むJARファイルのパスを引数に指定し，cjimportjbコマンドを使用して，JavaBeansリソースをインポートします。

サーバ管理コマンドでの操作については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「3.　サーバ管理コマンドの基本操作」を参照してください。また，コマンドについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「2.4　J2EEサーバで使用するリソース操作コマンド」を参照してください。属性ファイルについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.2　JavaBeansリソース属性ファイル」を参照してください。

参考

JavaBeansリソースを複数インポートする場合，インポート済みのJavaBeansリソースと同じ実装クラス名のJavaBeansリソースはインポートできません。先にインポートしたJavaBeansリソースを削除してからインポートするか，または実装クラス名を変更して再作成したあとでインポートしてください。
また，JavaBeansリソースの実装クラス以外にほかのクラスファイルを使用している場合，ほかのクラスファイルに関してはチェックされません。

インポート時にcjimportjbコマンドに-dオプションを使用すると，アーカイブを生成しないで，ディレクトリ構成のままインポートできます。ディレクトリは，インポートしたいディレクトリの最上位を指定します。
なお，指定したディレクトリがディレクトリ構成でない場合は，指定したディレクトリ直下のファイルをすべてインポートします。
指定したディレクトリ下にあるすべてのファイルをインポートするため，不要なファイルをディレクトリに含めないでください。

注意

JavaBeansリソースを使用する場合，J2EEアプリケーションからJavaBeansリソースへのリファレンスを解決しておく必要があります。JavaBeansリソースを使用しているJ2EEアプリケーションのプロパティを定義するときに，J2EEアプリケーションからJavaBeansリソースへのリファレンスを解決しておいてください。

(2)　JavaBeansリソースの設定変更の流れ

JavaBeansリソースの設定変更の流れを次の図に示します。

図3-30　JavaBeansリソースの設定変更の流れ

図中の1.～2.について説明します。

サーバ管理コマンドを使用して，JavaBeansリソースを停止します。
cjstopjbコマンドを使用してJavaBeansリソースを停止します。なお，JavaBeansリソースを停止する前に，そのJavaBeansリソースを使用しているJ2EEアプリケーションをすべて停止してください。

サーバ管理コマンドを使用して，JavaBeansリソースのプロパティを定義します。
cjgetjbpropコマンドを使用してJavaBeansリソース属性ファイルを取得し，ファイル編集後に，cjsetjbpropコマンドで編集内容を反映させます。
JavaBeansリソースのプロパティ定義で設定できる内容については，「(4)　JavaBeansリソースのプロパティ定義で設定できること」を参照してください。

(3)　JavaBeansリソースの入れ替えの流れ

JavaBeansリソースの入れ替えの流れを次の図に示します。

図3-31　JavaBeansリソースの入れ替えの流れ

図中の1.～4.について説明します。

サーバ管理コマンドを使用して，JavaBeansリソースを停止します。
cjstopjbコマンドを使用して入れ替えるJavaBeansリソースを停止します。なお，JavaBeansリソースを停止する前に，そのJavaBeansリソースを使用しているJ2EEアプリケーションをすべて停止してください。

J2EEサーバを再起動します。
cjstopsvコマンドを使用してJ2EEサーバを停止し，cjstartsvコマンドを使用してJ2EEサーバを再起動します。

サーバ管理コマンドを使用して，JavaBeansリソースを削除します。
cjdeletejbコマンドを使用して，入れ替えるJavaBeansリソースを削除します。

サーバ管理コマンドを使用してJavaBeansリソースをインポートします。
cjimportjbコマンドを使用して，新しいJavaBeansリソースをインポートします。

(4)　JavaBeansリソースのプロパティ定義で設定できること

JavaBeansリソースのプロパティを新規に設定する場合は，JavaBeansリソース属性ファイルのテンプレートを使用してJavaBeansリソース属性ファイルを作成して，プロパティを定義します。また，設定変更の場合は，サーバ管理コマンドでJavaBeansリソース属性ファイルを取得して，プロパティを定義します。cjgetjbpropコマンドでJavaBeansリソース属性ファイルを取得して，ファイル編集後に，cjsetjbpropコマンドで編集内容を反映させてください。

JavaBeansリソースのプロパティ定義で設定できる主な内容を次の表に示します。

表3-45　JavaBeansリソースのプロパティ定義で設定できる主な内容

分類
項目
設定内容

実行時プロパティ
リソースのタイプ
<res-type>タグにJavaBeansリソースのクラス名を指定します。

プロパティ情報
<property>タグ下の次のタグに設定します。

<property-name>タグにJavaBeansリソースのsetメソッド，getメソッドのメソッド名を指定します。

<property-type>タグにJavaBeansリソースのsetメソッドの引数の型を指定します。

<property-value>タグにJavaBeansリソースのsetメソッドの引数に渡す値を指定します。

別名情報
別名
JavaBeansリソースに別名を付与する場合，<resource-env-external-property>－<optional-name>タグにJavaBeansリソースの別名を指定します。
別名の設定については，「2.4.6　J2EEリソースの別名の設定」を参照してください。

参考

DD（ra.xml）の<resource-ref>タグで指定していた<res-auth>属性と，<res-sharing-scope>属性は，JavaBeansリソース属性ファイルの<resource-env-external-property>タグには指定できません。

3.12.5　JavaBeansリソースの入れ替え

ここでは，JavaBeansリソースを入れ替える手順について説明します。JavaBeansリソースは，J2EEアプリケーションおよびJavaBeansリソースを停止して，J2EEサーバを再起動してから入れ替えます。JavaBeansリソースの入れ替えには，サーバ管理コマンドを使用します。

手順を次に示します。

入れ替えるJavaBeansリソースを使用しているJ2EEアプリケーションを停止します。
J2EEアプリケーションを停止するには，cjstopappコマンドを実行します。cjstopappコマンドの実行形式と実行例を次に示します。

実行形式

cjstopapp <J2EEサーバ名> -name <J2EEアプリケーション名>

実行例

cjstopapp MyServer -name App1

入れ替えるJavaBeansリソースを停止します。
JavaBeansリソースを停止するには，cjstopjbコマンドを実行します。cjstopjbコマンドの実行形式と実行例を次に示します。

実行形式

cjstopjb <サーバ名称> -resname <JavaBeansリソース表示名>

実行例

cjstopjb MyServer -resname javabeansname

J2EEサーバを再起動します。
いったん開始したJavaBeansリソースを削除するには，J2EEサーバを再起動する必要があります。J2EEサーバを停止するには，cjstopsvコマンドを実行します。cjstopsvコマンドの実行形式と実行例を次に示します。

実行形式

cjstopsv <J2EEサーバ名>

実行例

cjstopsv MyServer

J2EEサーバを停止したあと，もう一度開始します。J2EEサーバを開始するには，cjstartsvコマンドを実行します。cjstartsvコマンドの実行形式と実行例を次に示します。

実行形式

cjstartsv <J2EEサーバ名>

実行例

cjstartsv MyServer

入れ替えるJavaBeansリソースを削除します。
JavaBeansリソースを削除するには，cjdeletejbコマンドを実行します。cjdeletejbコマンドの実行形式と実行例を次に示します。

実行形式

cjdeletejb <サーバ名称> -resname <JavaBeansリソース表示名>

実行例

cjdeletejb MyServer -resname MyJavaBeans

入れ替え後のJavaBeansリソースをインポートします。
JavaBeansリソースをインポートするには，cjimportjbコマンドを実行します。cjimportjbコマンドの実行形式と実行例を次に示します。

実行形式

cjimportjb <サーバ名称> -f <JARファイルパス> -c <JavaBeansリソース属性ファイルパス>

実行例

cjimportjb MyServer -f Myjavabeans.jar -c Myjavabeansprop.xml

JavaBeansリソースを開始します。
JavaBeansリソースを開始するには，cjstartjbコマンドを実行します。cjstartjbコマンドの実行形式と実行例を次に示します。

実行形式

cjstartjb <サーバ名称> -resname <JavaBeansリソース表示名>

実行例

cjstartjb MyServer -resname javabeansname

J2EEアプリケーションを開始します。
J2EEアプリケーションを開始するには，cjstartappコマンドを実行します。cjstartappコマンドの実行形式と実行例を次に示します。

実行形式

cjstartapp <J2EEサーバ名> -name <J2EEアプリケーション名>

実行例

cjstartapp MyServer -name App1

3.13　そのほかのリソースとの接続

ここでは，これまでの節で説明したリソース以外のリソースとの接続について説明します。

＜この節の構成＞

3.13.1　そのほかのリソースとの接続に使用するリソースアダプタ

3.13.2　そのほかのリソースとの接続で使用できる機能

3.13.1　そのほかのリソースとの接続に使用するリソースアダプタ

アプリケーションサーバでは，Connector 1.0仕様またはConnector 1.5仕様に準拠したリソースアダプタを使用して，任意のリソースに接続できます。

Connector 1.5仕様では，J2EEサーバとリソースアダプタ間の通信モデルとして，次の2種類のモデルが決められています。アプリケーションサーバでは，これらの通信モデルに対応したリソースアダプタを使用できます。

Outbound
J2EEサーバからリソースアダプタにアクセスする通信モデルです。

Inbound
リソースアダプタからJ2EEサーバにアクセスする通信モデルです。

アプリケーションサーバでは，Connector 1.5仕様の次の規約に対応しています。

Lifecycle Management
リソースアダプタの開始処理または終了処理を管理するための規約です。

Work Management
リソースアダプタがスレッドを扱うための規約です。

メッセージインフロー
EISからのメッセージを受信して，リソースアダプタからMessage-driven Beanを使用するための規約です。

トランザクションインフロー
メッセージインフローで，トランザクションを扱うための規約です。

これらの規約に基づいたアプリケーションサーバの機能については，「3.16.1　リソースアダプタのライフサイクル管理」，「3.16.2　リソースアダプタのワーク管理」，「3.16.3　メッセージインフロー」および「3.16.4　トランザクションインフロー」を参照してください。

また，既存の次の規約に対してConnector1.5仕様で追加された機能についても，アプリケーションサーバで対応しています。

Connection Management
不正コネクションを検知できます。
不正コネクションを検知する機能については，「3.15.1　コネクションの障害検知」を参照してください。

Common Client Interface
メッセージインフローに関連したAPIを使用できます。このAPIに対してアプリケーションサーバで独自に規定した仕様については，「3.16.7　アプリケーションサーバ独自のConnector 1.5 API仕様」を参照してください。

3.13.2　そのほかのリソースとの接続で使用できる機能

Connector 1.5で規定された機能のうち，アプリケーションサーバで使用できる機能について説明します。使用できる機能は，Outboundの場合とInboundの場合で異なります。なお，Connector 1.5仕様に準拠したリソースアダプタで使用できるアプリケーションサーバの機能については，「3.3.4　リソースアダプタの機能」を参照してください。

＜この項の構成＞

(1)　Outboundで使用できる機能

(2)　Inboundで使用できる機能

(3)　リソースアダプタの利用方法とトランザクションレベルの対応

(1)　Outboundで使用できる機能

Outboundでは，次の機能が使用できます。

ローカルトランザクションおよびグローバルトランザクションによるトランザクション管理

メッセージキューの使用

(2)　Inboundで使用できる機能

Inboundでは，Non-Transacted Delivery（EISがトランザクションに参加しないメッセージ配信）およびTransacted Delivery（EISがアプリケーションサーバのグローバルトランザクションに参加するメッセージ配信）を使用できます。

参考

トランザクションインフロー（Message-driven Beanの呼び出しがEISのトランザクションに参加するメッセージ配信）は，TP1インバウンド連携機能でだけ対応しています。

(3)　リソースアダプタの利用方法とトランザクションレベルの対応

リソースアダプタをOutboundで使用する場合に指定できるトランザクションレベルを次の表に示します。

表3-46　Outboundで使用する場合に指定できるトランザクションレベル

利用する通信モデル
トランザクションの管理方法
トランザクション属性
トランザクションサポートレベル

NoTransaction
LocalTransaction
XATransaction※

Outbound
CMT
Required
RequiresNew
Supports
NotSupported
Mandatory
Never
○
○
○

BMT
－
○
○
○

（凡例）

○：使用できる　－：該当しない

注※　リソースアダプタをJ2EEアプリケーションに含める場合は，XATransactionは使用できません。

ポイント

リソースアダプタをInboundで使用する場合に指定できるトランザクション属性を次の表に示します。

表3-47　Inboundで使用する場合に指定できるトランザクション属性

利用する通信モデル | トランザクションの管理方法 | トランザクション属性
Inbound | CMT | Required※
NotSupported
BMT | －

（凡例）

－：該当しない

注※　CJMSPリソースアダプタまたはFTPインバウンドアダプタの場合は指定できません。

3.14　パフォーマンスチューニングのための機能

この節では，パフォーマンスチューニングのための機能について説明します。

この節の構成を次の表に示します。

表3-48　この節の構成（パフォーマンスチューニングのための機能）

分類 | タイトル | 参照先
解説 | コネクションプーリング | 3.14.1
コネクションプーリングで使用できる機能 | 3.14.2
コネクションシェアリング・アソシエーション | 3.14.3
ステートメントプーリング | 3.14.4
ライトトランザクション | 3.14.5
インプロセストランザクションサービス | 3.14.6
DataSourceオブジェクトのキャッシング | 3.14.7
DB Connectorのコンテナ管理でのサインオンの最適化 | 3.14.8
実装 | cosminexus.xmlでの定義 | 3.14.9
設定 | 実行環境での設定 | 3.14.10

注　「運用」について，この機能固有の説明はありません。

＜この節の構成＞

3.14.1　コネクションプーリング

3.14.2　コネクションプーリングで使用できる機能

3.14.3　コネクションシェアリング・アソシエーション

3.14.4　ステートメントプーリング

3.14.5　ライトトランザクション

3.14.6　インプロセストランザクションサービス

3.14.7　DataSourceオブジェクトのキャッシング

3.14.8　DB Connectorのコンテナ管理でのサインオンの最適化

3.14.9　cosminexus.xmlでの定義

3.14.10　実行環境での設定

3.14.1　コネクションプーリング

サーブレット，JSP，EJBなどのJ2EEコンポーネントからのリソースアクセス量に応じて，リソースコネクション（JDBCコネクション，およびリソースアダプタのコネクション）をプーリングする機能です。コネクションをプーリングすることによって，ユーザアプリケーションからのリソース接続要求を高速に処理します。

＜この項の構成＞

(1)　前提条件

(2)　コネクションプールの生成および初期化

(3)　コネクションプールの終了処理

(4)　例外が発生したコネクションの破棄

(5)　コネクションプール利用上の注意事項

(6)　コネクションプーリングの動作

(1)　前提条件

コネクションプーリング機能は，リソースの種類，接続方法の組み合わせによって，使用できる場合とできない場合があります。コネクションプーリング機能の使用について次の表に示します。

表3-49　コネクションプーリング機能の利用可否

リソースの種類 | 接続方法 | 利用可否
データベース | DB Connector | ○
データベース上のキュー | DB Connector for Cosminexus RMとCosminexus RM | ○
OpenTP1 | uCosminexus TP1 Connector | ○
TP1/Message Queue - Access | ○
SMTPサーバ | メールコンフィグレーション | ×
JavaBeansリソース | － | ×
そのほかのリソース | Connector 1.0仕様またはConnector 1.5仕様に準拠したリソースアダプタ | ○

（凡例）　○：使用できる　×：使用できない　－：該当しない

(2)　コネクションプールの生成および初期化

コネクションプールが生成・初期化されるタイミングは，リソースのスタート処理時です。コネクションプールのウォーミングアップ機能を有効にした場合，この時点でコネクションを生成します。コネクションプールのウォーミングアップ機能を無効にした場合，リソースのスタート時にコネクションは生成されず，最初のコネクション取得要求の発生時にコネクションを生成します。

コネクションプールの生成単位は次のとおりです。

Connector 1.0仕様に対応したリソースアダプタを使用する場合，リソース単位に一つのコネクションプールが生成されます。

Connector 1.5仕様に対応したリソースアダプタを使用する場合，コネクション定義ごとに一つのコネクションプールが生成されます。

(3)　コネクションプールの終了処理

リソースのアンデプロイ時やJ2EEサーバの終了時は，コネクションプール内のすべてのコネクションを削除し，コネクションプール自体も削除します。なお，コネクションプールの終了処理では，コネクションに関するトランザクションなどがすべて決着済みのものとして処理します。

(4)　例外が発生したコネクションの破棄

データベース障害などが発生すると，コネクションプールに格納しているコネクションは使えなくなるため，コネクションプールから速やかに破棄する必要があります。

アプリケーションサーバは，コネクション，またはStatementのようなコネクションからの生成物に対する処理で例外が発生すると，コネクションクローズ時に該当コネクションをコネクションプールから破棄します。ただし，ローカルトランザクションの決着処理が正常終了した場合には，コネクションが正常であると判断するため破棄しません。

コネクションが正常に維持している状態で，コネクションやコネクションからの生成物で例外が発生すると，グローバルトランザクションを使用している場合には，トランザクションの決着処理が正常終了してもアプリケーションサーバはコネクションをコネクションプールに戻さないで破棄します。そのため余分なコネクション生成が発生して性能に影響を与えることがあります。

(5)　コネクションプール利用上の注意事項

コネクションプールを利用する場合の注意事項について説明します。

データベースサーバ側から強制的に切断する機能（タイムアウトなど）を利用しないでください。

コネクションプールで管理するコネクションは，取得時に使用した認証情報（ユーザ名，パスワードなど）を保持するため，サインオンの形態によっては注意が必要です。

コンテナ管理でのサインオンの場合

一つのコネクションプールに対して，コネクション取得要求時に使用する認証情報は常に一つとなるため，特に注意は必要ありません。

コンポーネント管理でのサインオンの場合

複数のユーザ名とパスワードの組み合わせを利用する場合に注意が必要です。コネクションプールはリソースごとに一つであるため，一つのリソースに対して複数のユーザが利用する場合，複数のユーザで一つのコネクションプールを共有することになります。この場合，一人のユーザが，コネクションプールの最大値に設定した数までコネクションを利用できないことがあります。

また，コネクションプール内の未使用コネクションの中に，認証情報が一致するコネクションがない場合，プール内のコネクション総数によって，次のように動作します。

コネクション総数が，指定したコネクションプールの最大値に達している場合，未使用状態のコネクションを破棄して，新規にコネクションを生成します。

コネクション総数が，指定したコネクションプールの最大値に達していない場合，新規にコネクションを生成します。

(6)　コネクションプーリングの動作

リソースアダプタのコネクションプーリングの動作を次の表に示します。

表3-50　コネクションプールの状態と動作

ユーザアプリケーションプログラム処理
コネクションプールの状態
コネクションプールの動作

コネクションの取得要求
プール内に未使用状態のコネクションがある
未使用状態のコネクションの一つが選択され，ユーザアプリケーションプログラムに渡されます。選択されたコネクションは，プール内で使用中状態になります。

プール内に未使用状態のコネクションがなく，プール内のコネクションの総数が「MaxPoolSize」の値未満
新規にコネクションを確立します。確立したコネクションはユーザアプリケーションに渡され，コネクションはプール内で使用中状態となります。

プール内に未使用状態のコネクションがなく，プール内のコネクションの総数が「MaxPoolSize」の値に達している
ユーザアプリケーションプログラムに例外が通知され，コネクションの取得は失敗します。再取得するためには，「Retry Count」と「Retry Interval」を設定します。

プール内に取得要求に一致するコネクションがない
プール内のコネクションの総数によって次の処理が実施されます。

プール内のコネクションの数が「MaxPoolSize」の値未満の場合
新規にコネクションを確立し，ユーザアプリケーションに引き渡されます。

プール内のコネクションの数が「MaxPoolSize」の値に達している場合
使用されていないコネクションのうち，最初にプーリングされたコネクションが破棄されたあと，新しいコネクションが作成されて，ユーザアプリケーションに引き渡されます。

コネクションを解放
解放したコネクションに異常がなく，再利用できる
このコネクションはプール内で未使用状態に戻ります。

解放したコネクションが再利用できない
このコネクションは破棄されます。

－
コネクションプールのウォーミングアップ機能を使用
リソースアダプタの開始時またはリソースアダプタを開始済みの状態でのサーバ起動時に，「MinPoolSize」の値までコネクションが生成されてプールされます。
コネクションプールのウォーミングアップ機能を使用するためには，「Warmup」を設定します。

コネクション枯渇時のコネクション取得待ち
コネクションプールにコネクションが最大数プールされていて利用できるコネクションがプールにない状態（コネクション枯渇）のときに，コネクションの取得要求を待ち状態にできます。
待ち状態になっているコネクション取得要求は，コネクションが解放されるとすぐにコネクションを取得できます。
コネクション枯渇時のコネクション取得待ちは，「RequestQueueEnable」「RequestQueueTimeout」で設定します。

（凡例）　－：該当なし

なお，コネクションプールのウォーミングアップ機能を使用する場合は，次の表に示す注意事項があります。

表3-51　コネクションプールのウォーミングアップ機能を使用する場合の注意事項

条件
注意事項

コンテナ認証用の認証情報（ユーザ名，パスワードなど）の設定※
コンポーネント管理でのサインオンで，複数のユーザ名とパスワードの組み合わせで利用する場合に注意が必要です。コネクションプールはリソースごとに一つであるため，一つのリソースに対して複数のユーザが利用する場合，複数のユーザで一つのコネクションプールを共有することになります。この場合，一人のユーザが，コネクションプールの最大値に設定した数までコネクションを利用できないことがあります。
コンテナ管理でのサインオンの場合は，一つのコネクションプールに対して，コネクション取得要求時に使用する認証情報は常に一つとなるため，特に注意は必要ありません。

「MinPoolSize」の設定
次のような場合，MinPoolSizeに指定した値よりもプールされているコネクションが少なくなることがあります。

コネクションスイーパによってコネクション解放処理が実行されたとき

cjclearpool（コネクションプール内のコネクション削除）コマンドを実行したとき

コネクションに障害が発生したとき

リソースの開始時にMinPoolSize分のコネクションが生成されるため，コネクションプールのウォーミングアップ機能を使用しない場合に比べてサーバの起動またはリソースアダプタの開始に時間が掛かります。
また，このときに「bufSizeに指定した値 × 生成したコネクション数分のメモリ」をJavaヒープ領域に確保します。
MinPoolSizeに必要以上に大きな値を設定してウォーミングアップ機能を使用すると，メモリを確保したときにJavaヒープを使い切り，OutOfMemoryErrorが発生するおそれがあります。
このため，MinPoolSizeの値は，使用するリソースマネジャの最大同時接続数以下に設定してください。

注※　コネクションプールで管理するコネクションは，ウォーミングアップ機能の動作時に使用したコンテナ認証用の認証情報（ユーザ名，パスワードなど）を保持します。

3.14.2　コネクションプーリングで使用できる機能

コネクションプーリング機能を使用すると，さらに次に示す機能も使用できます。

＜この項の構成＞

(1)　コネクションプールのウォーミングアップ

(2)　コネクション数調節機能

(3)　コネクションスイーパの動作

(1)　コネクションプールのウォーミングアップ

コネクションプールのウォーミングアップとは，サーバ起動時またはリソースアダプタのスタート時に実行されるリソースのスタート処理で，あらかじめ，コネクションを，コネクションプールの設定で定義した最小値までプーリングする機能です。これによって，コネクションプールの使用を開始した直後の，コネクション要求のレスポンスを向上できます。

コネクションプールのウォーミングアップは，リソースアダプタの属性（プロパティ）として設定します。リソースアダプタのプロパティ定義で設定できることについては，「3.14.10　実行環境での設定」を参照してください。

(2)　コネクション数調節機能

コネクション数調節機能とは，コネクションプール内の不要なコネクションを指定したコネクションプールの最小値から最大値の範囲で段階的に減少させる機能です。この機能を有効にすると，実際の稼働実績に適した数までプール内のコネクション数を徐々に減らせるため，指定したコネクションプールの最小値を超えた場合のコネクション生成コストの削減やリソース資源の節約ができます。

また，コネクション数の調節時のコネクション削除処理に対して，応答時間にタイムアウトを設定できます。サーバ障害やネットワーク障害が発生してリソースからの応答が返らない場合，コネクション削除処理に対しても応答が返らなくなることがあります。このように，リソースから応答が返らない場合でも，タイムアウトを設定することでコネクション削除処理を終了し，処理を継続できます。

コネクション数調節機能の動作

コネクション数調節機能を使用すると，プール内のコネクション数は，前回コネクション数を調節したときから今回コネクション数を調節するまでの間に同時に使用されたコネクションの最大数で調節されます。コネクション数の調節時に，プール内コネクション数が同時に使用されたコネクションの最大数より多い場合は，コネクションの削除処理が動作します。例えば，現在，プール内にあるコネクション数が8の場合で，前回のコネクション数調整から今回のコネクション数調節までの間に同時に使用されたコネクションの最大数が5のときは，プール内のコネクション数が3多いため，コネクションプールから3コネクションが削除され，調節後のコネクション数は5となります。

なお，コネクション数調節機能は一定間隔で動作します。

コネクション数調節機能の設定については，「3.14.10　実行環境での設定」を参照してください。

コネクション削除処理のタイムアウト

コネクション数調節機能のコネクション削除処理に対して，その応答時間にタイムアウトを設定できます。なお，コネクション削除処理のタイムアウト時間は簡易構築定義ファイルのJ2EEサーバで指定するキーに，任意の時間を指定できます（デフォルト値は5秒）。

ただし，コネクションプールの最大数が無制限の場合，コネクション削除処理のタイムアウトは無効になります。

また，コネクション削除処理のタイムアウトにはコネクション管理スレッドを使用するため，コネクション削除処理のタイムアウトを設定すると，設定しない場合に比べて多くのメモリを消費します。設定する場合は，必要なメモリ使用量を適切に見積もってください。

コネクション管理スレッドについては，「3.15.1　コネクションの障害検知」を参照してください。

(3)　コネクションスイーパの動作

一定間隔でコネクションプール内の未使用コネクションを破棄するための，コネクションスイーパ機能は，次のように動作します。

前回のコネクションスイーパの動作が終了してから「SweeperInterval」の値の経過後，コネクションスイーパが動作します。

コネクションスイーパは，プール内の未使用状態のコネクションを監視します。
最後に利用した時点からの経過時間が「ConnectionTimeout」の値以上の未使用状態コネクションを破棄します。未使用状態コネクションで，最後に利用した時点からの経過時間が「ConnectionTimeout」の値未満のコネクションについては，何もしません。

3.14.3　コネクションシェアリング・アソシエーション

コネクションシェアリングとコネクションアソシエーションは，コネクション共有機能です。コネクション共有機能を利用することで，リソースを効率的に使用し，パフォーマンスを向上できます。必要に応じて，コネクションアソシエーション機能を有効にしてください。

ローカルトランザクションでトランザクション管理を行っている場合，一つのリソースコネクションだけでデータベースなどのリソースにアクセスする必要があります。コネクション共有機能を使用するとユーザアプリケーションで意識することなく，一つのリソースコネクションだけでリソースアクセスができます。

グローバルトランザクションの場合も同様に，一つのリソースコネクションしかトランザクションに参加しない場合は，1フェーズコミットに最適化されるため，トランザクションの決着コストを下げることができます。

＜この項の構成＞

(1)　物理コネクションと論理コネクション

(2)　コネクションシェアリング

(3)　コネクションアソシエーション

(1)　物理コネクションと論理コネクション

物理コネクションとは，接続先リソースのコネクションを指します。通常，サーブレットやEnterprise BeanなどのJ2EEコンポーネントが直接操作することはなく，コンテナが操作します。例えば，リソースアダプタの場合はManagedConnection（javax.resource.spi.ManagedConnection）です。

論理コネクションとは，サーブレットやEnterprise BeanなどのJ2EEコンポーネントが直接操作するコネクションを指します。例えば，リソースアダプタの場合はjavax.resource.cci.Connectionやリソースアダプタが独自に提供するコネクションです。

物理コネクションと論理コネクションの関係は，一般的に，物理コネクションから論理コネクションを生成するという関係になります。物理コネクションはコネクションプールで管理され，コネクションプールが物理コネクションの取得およびクローズを行います。

サーブレットやEnterprise BeanなどのJ2EEコンポーネントからのコネクション取得要求に対しては，コネクションプールが物理コネクションから論理コネクションを生成して返却します。コネクション解放要求に対しては，論理コネクションだけをクローズし，物理コネクションはクローズしないでプール管理します。

(2)　コネクションシェアリング

コネクションアソシエーション機能が有効でない場合，アプリケーションサーバが管理するトランザクション内でコネクションシェアリングが行われます。トランザクション内コネクションシェアリングは，リソースコネクションを最も効率的に使用します。トランザクション内のコネクションシェアリングについて次の図に示します。

図3-32　論理コネクションと物理コネクションの関係（トランザクション内コネクションシェアリング）

コネクションアソシエーション機能が有効な場合，およびアプリケーションサーバが管理するトランザクションの外でのコネクションシェアリングは，サーブレットやEnterprise BeanなどのJ2EEコンポーネントインスタンス内でコネクションシェアリングが行われます。コンポーネント内のコネクションシェアリングについて，次の図に示します。

図3-33　論理コネクションと物理コネクションの関係（コンポーネント内コネクションシェアリング）

(a)　コネクションシェアリングの条件

コネクションシェアリングをするためには，次の条件をすべて満たす必要があります。

同一のJ2EEサーバ内であること

同一のリソースであること

サインオンの方法とセキュリティ情報（ユーザ名とパスワード）が同じであること

標準DDの<res-sharing-scope>にShareableが指定されていること

同一のアプリケーションサーバが管理するトランザクション内であること※

注※

アプリケーションサーバが管理するトランザクションの外でもコネクションシェアリングを行うことができます。

アプリケーションサーバが管理するトランザクションの外でコネクションシェアリングを有効にする場合は，J2EEサーバのプロパティをカスタマイズして設定します。J2EEサーバの動作設定のカスタマイズについては，「3.14.10　実行環境での設定」を参照してください。

なお，リソースアダプタのトランザクションサポートレベルにNoTransactionを指定した場合は，コネクションシェアリングは行われません。

なお，コネクションシェアリングの定義については，「3.14.9　cosminexus.xmlでの定義」を参照してください。

(b)　コネクションシェアリングの定義

コネクションを共有するかどうかは，サーブレットやEnterprise Beanの標準DDまたはcosminexus.xmlの<res-sharing-scope>タグで指定します。リソース参照ごとに指定できます。コネクションの共有はデフォルトで有効になっています。無効にする場合は，<res-sharing-scope>にUnshareableを指定します。

J2EEアプリケーションの設定については，「3.14.9　cosminexus.xmlでの定義」を参照してください。

(c)　注意事項

java.sql.Connectionを，複数のトランザクション間で再利用することはできません。

java.sql.Connectionをトランザクション内で利用する場合には，トランザクションごとに，javax.sql.DataSourceからgetConnection()メソッドを使用してコネクションを取得してください。

なお，java.sql.Connectionは，トランザクション内とトランザクション外との間でも再利用することはできません。

(3)　コネクションアソシエーション

トランザクション範囲を超えた永続性を持つコネクションを使用する場合，トランザクション内コネクションシェアリングを使用できません。その場合は，コネクションアソシエーション機能を有効にしてください。

コネクションアソシエーションは，論理コネクションと物理コネクションの関係を切り替えて，一つのリソースコネクションによるリソースアクセスを実現します。

図3-34　論理コネクションと物理コネクションの関係（コネクションアソシエーション）

図3-35　論理コネクションと物理コネクションの関係（コネクションアソシエーションとコネクションシェアリングの併用時）

(a)　コネクションアソシエーションの条件

コネクションアソシエーションをするためには，次の条件のすべてを満たす必要があります。

コネクションアソシエーション機能が有効であること

同一のJ2EEサーバ内であること

同一のリソースであること

サインオンの方法とセキュリティ情報（ユーザ名とパスワード）が同じであること

標準DDの<res-sharing-scope>にShareableが指定されていること※

同一のアプリケーションサーバが管理するトランザクション内であること

注※

usrconf.propertiesのejbserver.connectionpool.association.enabledDespiteUnshareableSettingキーに「true」を設定すると標準DDの<res-sharing-scope>にUnshareableが指定されていてもコネクションアソシエーションを行います。

このプロパティは下位互換性のためだけに提供されています。

(b)　コネクションアソシエーションの定義

コネクションアソシエーションはデフォルトで無効になっています。

コネクションアソシエーションを有効にするための設定は，J2EEサーバのプロパティをカスタマイズして設定します。J2EEサーバの動作設定のカスタマイズについては，「3.14.10　実行環境での設定」を参照してください。

(c)　注意事項

java.sql.Connectionからの生成物（例：java.sql.Statement）をトランザクションの範囲を超えて使用することはできません。

3.14.4　ステートメントプーリング

DB Connectorを使用した場合，JDBCのAPIであるjava.sql.PreparedStatementとjava.sql.CallableStatementの再利用を行うプーリング機能を使用できます。ステートメントプーリング機能によって，PreparedStatementとCallableStatementを使用した場合のパフォーマンス向上が図れます。なお，PreparedStatementとCallableStatementのプールサイズは，DB Connectorの設定で指定します。ステートメントプーリングを使用する際のプールサイズ設定の指針については，マニュアル「Cosminexus アプリケーションサーバ システム設計ガイド」の「8.5.2　ステートメントプーリングを使用する」を参照してください。また，DB Connectorのプロパティ定義については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「4.2.2　DB Connectorのプロパティ定義」を参照してください。

ステートメントプーリング機能では，ステートメントを再利用する際にステートメントを初期化します。初期化する内容はJ2EEサーバのプロパティをカスタマイズして設定します。ステートメントプーリング機能の設定については，「3.14.10　実行環境での設定」を参照してください。

ステートメントプーリング機能を利用するには，コネクションプーリング機能を使用する必要があります。また，トランザクションサポートレベルにグローバルトランザクションを指定した場合，HiRDBのバージョンによっては利用できないことがあります。

注意

HiRDB Type4 JDBC Driverを使用する場合，PreparedStatement，CallableStatementのプールサイズに制限があります。指定できるプールサイズについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1.10　DB Connectorに設定する<config-property>タグに指定できるプロパティ」を参照してください。

＜この項の構成＞

(1)　前提条件

(2)　ステートメントプーリングの動作

(3)　ステートメントプーリング機能を使用する場合の注意事項

(1)　前提条件

トランザクションサポートレベル，コネクションプーリング使用の有無，使用するデータベースの種類との対応による，ステートメントプーリング利用について次の表に示します。

表3-52　ステートメントプーリングの利用

トランザクションサポートレベル | コネクションプーリングを使用する | コネクションプーリングを使用しない
HiRDB※1 | Oracle | SQL Server | XDM/RD E2 | HiRDB／Oracle／SQL Server
トランザクションなし（NoTransaction） | ○ | ○ | ○ | ○ | ×
ローカルトランザクション（LocalTransaction） | ○ | ○ | ○ | ○ | ×
グローバルトランザクション（XATransaction） | ○※2 | ○ | × | × | ×

（凡例）　○：利用できる　　×：利用できない

注※1　ステートメントプーリング機能を使用した状態で，定義SQLを実行しないでください。定義SQLを実行する場合，ステートメントプーリング機能は使用できません。また，定義SQLを実行する場合は，HiRDBのクライアント環境変数として「PDDDLDEAPRP=YES」を設定する必要があります。

注※2　JDBCのDatabaseMetaData#supportsStatementPooling()の戻り値がtrueの場合に，利用できます。

なお，XDM/RD E2を使用する場合はXDM/RD E2 11-03以降のバージョンとHiRDB Type4 JDBC Driver 08-02以降を使用するときにだけステートメントプーリング機能を使用できます。ステートメントプーリング機能の設定については，「3.14.10　実行環境での設定」を参照してください。

(2)　ステートメントプーリングの動作

リソースアダプタのコンフィグレーションプロパティで設定するステートメントプーリングの動作について説明します。

ステートメントプーリング機能の動作を，次の表に示します。

表3-53　ステートメントプールの状態と動作

ユーザアプリケーションプログラム処理 | ステートメントプールの状態 | ステートメントプールの動作
PreparedStatement，CallableStatementの生成を要求 | プール内に未使用状態のPreparedStatement，CallableStatementがある | プール内で未使用状態のPreparedStatement，CallableStatementの一つが選択され，ユーザアプリケーションプログラムに渡されます。選択されたPreparedStatement，CallableStatementは，プール内で使用中状態になります。
プール内に未使用状態のPreparedStatement，CallableStatementがなく，プール内のPreparedStatement，CallableStatementの総数が「PreparedStatementPoolSize」，「CallableStatementPoolSize」の値に満たない | 新規にPreparedStatement，CallableStatementを生成します。生成したPreparedStatement，CallableStatementはユーザアプリケーションに渡され，PreparedStatement，CallableStatementはプール内で使用中状態となります。
プール内に未使用状態のPreparedStatement，CallableStatementがなく，プール内のPreparedStatement，CallableStatementの総数が「PreparedStatementPoolSize」，「CallableStatementPoolSize」の値以上 | タイムスタンプが最も古い※PreparedStatement，CallableStatementをプールから削除したあと，新規にPreparedStatement，CallableStatementを生成します。生成したPreparedStatement，CallableStatementはユーザアプリケーションに渡され，PreparedStatement，CallableStatementはプール内で使用中状態となります。
PreparedStatement，CallableStatementを解放 | － | PreparedStatement，CallableStatementはプール内で未使用状態に戻ります。

（凡例）　－：該当なし

注※　プール内のPreparedStatement，CallableStatementのタイムスタンプが更新されるタイミングは，次のとおりです。

新規に生成したPreparedStatement，CallableStatementがプールに追加されるとき

プール内のPreparedStatement，CallableStatementが使用中状態になるとき

(3)　ステートメントプーリング機能を使用する場合の注意事項

ステートメントプーリング機能を使用する場合の注意事項を次の表に示します。

表3-54　ステートメントプーリング機能を使用する場合の注意事項

条件
注意事項

－

ステートメントプーリング機能を使用しない場合と比べて，プールされているPreparedStatement，CallableStatementの数だけメモリが消費されます。

ステートメントプールは，コネクションプール内のコネクションごとにあるため，プールされるPreparedStatement，CallableStatementの最大数は，「MaxPoolSize」×（「PreparedStatementPoolSize」＋「CallableStatementPoolSize」）となります。

－

ステートメントプーリング機能をコネクション数調節機能またはコネクション障害検知機能と併用した場合，コネクションプールから取り除かれた未使用コネクションは，コネクションプール内のコネクション数としてカウントされません。このため，プールされているPreparedStatement，CallableStatementの数がコネクションプールの最大値×PreparedStatementPoolSize，およびコネクションプールの最大値×CallableStatementPoolSizeを一時的に超える場合があります。

OracleまたはSQL Serverに接続

ステートメントプーリング機能と，コネクションの障害検知機能を併用する場合
コネクションの障害検知に使用されるPreparedStatementがコネクションごとに一つプーリングされます。そのため，PreparedStatementPoolSize，CallableStatementPoolSizeを決定する際には，コネクションの障害検知用のPreparedStatementもリソース数の見積もりに加えて，CallableStatementPoolSizeを最大ステートメント数未満に設定してください。※

ステートメントプーリング機能と，コネクションプールのウォーミングアップ機能を併用する場合
コネクションが生成されてプーリングされるときに，コネクションの障害検知に使用されるSQLで生成したPreparedStatementがコネクションごとに一つプーリングされます。

ステートメントプーリング機能と，リザルトセットの保持機能を併用する場合
Oracle接続でリザルトセットの保持機能を使用する場合，Connection.prepareStatement()メソッドまたはprepareCall()メソッドの引数にリザルトセットの保持機能を指定してください。Connection.setHoldability()メソッドでは，リザルトセットの保持機能は指定できません。

（凡例）　－：該当なし

注※

コネクションの障害検知機能を使用する場合には，CallableStatementPoolSizeを最大ステートメント数未満に設定してください。

コネクションの障害検知機能を使用すると，プーリングされているCallableStatementの数が最大ステートメント数に達したとき，コネクションの障害検知が実行されます。このとき，CallableStatementPoolSize=＜最大ステートメント数＞と設定していると，JDBCドライバの一つのコネクションで利用できるリソース数の最大値を超えるため，例外が発生します。例外が発生すると障害が発生したと判断されるので，そのコネクションはコネクションプールから削除され，同時にステートメントプールも破棄されます。つまり，ステートメントプーリング機能を使用する意味がなくなってしまいます。

3.14.5　ライトトランザクション

ライトトランザクションとは，ローカルトランザクションに最適化された環境を提供する機能です。これによって，良好なローカルトランザクション処理性能を得られます。ライトトランザクションは，ローカルトランザクションだけを使用する場合に適用できます。ライトトランザクション機能を有効にした場合，呼び出し先がBMTのときだけ，トランザクション中のEJBリモート呼び出しができます。

ライトトランザクション機能は，デフォルトでは有効となっています。ライトトランザクション機能を有効にした状態で，グローバルトランザクションを使用するとエラーになります。このため，グローバルトランザクションを使用する場合には，ライトトランザクション機能を無効にする必要があります。

ライトトランザクション機能を有効にするための設定は，J2EEサーバのプロパティをカスタマイズして設定します。J2EEサーバの動作設定のカスタマイズについては，「3.4.12　実行環境での設定」を参照してください。

3.14.6　インプロセストランザクションサービス

アプリケーションサーバでは，トランザクションサービスをJ2EEサーバのインプロセスで起動できます。インプロセスでトランザクションサービスを起動すると，トランザクション処理をJ2EEサーバのプロセス内で実行するように最適化されるので，パフォーマンスの高いシステムを実現できます。

インプロセストランザクションサービスは，CORBAで規定されたOTS1.3の仕様をサポートしています。

3.14.7　DataSourceオブジェクトのキャッシング

J2EEアプリケーションからデータベースにアクセスする場合，JNDIインタフェースを使用してjavax.sql.DataSource型のオブジェクト（以降，DataSourceオブジェクト）の検索を要求します。J2EEサーバのデフォルトの動作では，該当するDataSourceが登録されている場合に，DataSourceオブジェクトのインスタンスを生成してアプリケーションに返します。

このとき，DataSourceオブジェクトのキャッシングを使用すると，J2EEサーバは，登録されているDataSourceオブジェクトのインスタンスをキャッシングして，検索の要求に対して同じインスタンスを返します。DataSourceオブジェクトのキャッシングを使用すると，DataSourceオブジェクトの検索時間が短くなります。

DataSourceオブジェクトのキャッシングをするための設定は，J2EEサーバのプロパティをカスタマイズして設定します。J2EEサーバの動作設定のカスタマイズについては，「3.14.10　実行環境での設定」を参照してください。

＜この項の構成＞

(1)　前提条件

(2)　注意事項

(1)　前提条件

DataSourceオブジェクトのキャッシング機能は，Enterprise Beanのビジネスメソッド，およびサーブレット/JSPのサービスメソッド内でDataSourceをルックアップし，該当するインスタンスをメンバ変数などに保持しない場合に有効です。

ビジネスメソッドやサービスメソッド内でルックアップしたDataSourceオブジェクトをメンバ変数に保持し，ほかのメソッドでも利用する場合は有効ではありません。また，Enterprise BeanのejbCreateメソッドやサーブレット/JSPのinitメソッドなどの初期化メソッド内でルックアップしたDataSourceオブジェクトをメンバ変数に保持し，ビジネスメソッドやサービスメソッドで使用する場合も有効ではありません。

(2)　注意事項

DataSourceオブジェクトのキャッシング機能を使用する場合に，次に示すようなリソースアダプタを使用すると，動作時に属性ファイルの<resource-ref>の定義が有効にならないことがあります。

同一J2EEコンポーネントから同一リソースに対して複数の<resource-ref>タグを定義し，それぞれの<resource-ref>タグにある<res-sharing-scope>タグや<res-auth>タグに異なる値を指定した，リソースアダプタを使用する。

同一J2EEコンポーネントで複数の<resource-ref>タグを定義する場合は，別のリソース（デプロイ単位が別になるリソースアダプタ）を使用するようにしてください。

3.14.8　DB Connectorのコンテナ管理でのサインオンの最適化

DB Connectorでは，コンテナ管理のサインオンとコンポーネント管理のサインオンをサポートしています。

それぞれの方法の特徴を次に示します。

コンテナ管理でのサインオンの場合

コンテナ管理のサインオンを使用する場合，DB Connectorで設定するユーザ名とパスワードを使用して，データベースにアクセスします。

コンポーネント管理でのサインオンの場合

コンポーネント管理でのサインオンを使用する場合，コネクションファクトリのgetConnectionメソッドに渡されたユーザ名とパスワードを使用してデータベースにアクセスします。

なお，DBConnector_DABJ_XA.rarを使用する場合（グローバルトランザクションを使用する場合），XAOpen文字列に指定されたユーザ名とパスワードだけが有効となります。このため，getConnectionメソッドでユーザ名とパスワードを指定して利用する，コンポーネント管理でのサインオンはできません。

コンテナ管理のサインオンをするときに，サインオンの最適化機能を使用すると，コンテナ管理でのサインオン動作が最適化され，データベースとのコネクション取得のパフォーマンスが向上します。

DB Connectorのコンテナ管理でのサインオンの最適化をするための設定は，J2EEサーバのプロパティをカスタマイズして設定します。J2EEサーバの動作設定のカスタマイズについては，「3.14.10　実行環境での設定」を参照してください。

注意

コンテナ管理でのサインオンの最適化は，コンポーネント管理のサインオンをしない場合に使用してください。コンテナ管理でのサインオンの最適化をすると，コンポーネント管理でのサインオンは利用できなくなります。

コネクションプールのクラスタ化機能を利用する場合，一つのクラスタコネクションプール内で，コンテナ管理でのサインオンとコンポーネント管理でのサインオンを混在して使用できません。

3.14.9　cosminexus.xmlでの定義

パフォーマンスチューニングのための機能のうち，コネクションシェアリングの定義は，cosminexus.xmlの<rar>タグ内に指定します。cosminexus.xmlでのパフォーマンスチューニングのための機能の定義について次の表に示します。

表3-55　cosminexus.xmlでのパフォーマンスチューニングのための機能の定義

指定するタグ | 設定内容
<resource-external-property>－<res-sharing-scope>タグ | 取得したコネクションを共有するかどうかを設定します。

3.14.10　実行環境での設定

パフォーマンスチューニングのための機能を使用する場合，J2EEサーバの設定，リソースアダプタの設定，およびJ2EEアプリケーションの設定が必要です。

＜この項の構成＞

(1)　J2EEサーバの設定

(2)　リソースアダプタの設定

(3)　J2EEアプリケーションの設定

(1)　J2EEサーバの設定

J2EEサーバの設定は，簡易構築定義ファイルで実施します。パフォーマンスチューニングの定義は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。

簡易構築定義ファイルでのパフォーマンスチューニングのための機能の定義について，次の表に示します。

表3-56　簡易構築定義ファイルでのパフォーマンスチューニングのための機能の定義

項目 | 指定するパラメタ | 設定内容
アプリケーションサーバが管理するトランザクションの外でコネクションシェアリングの有効化 | ejbserver.connectionpool.sharingOutsideTransactionScope.enabled | アプリケーションサーバが管理するトランザクションの外で複数回コネクションの取得を行ったときの，コネクションシェアリングの動作を指定します。
コネクションアソシエーション | ejbserver.connectionpool.association.enabled | コネクションアソシエーション機能を使用するかどうかを指定します。
ejbserver.connectionpool.association.enabledDespiteUnshareableSetting | システムプロパティには，リソースの非共有を設定している場合※も，コネクションアソシエーション機能を使用するかどうかを指定します。
ステートメントプーリング機能のステートメントの初期化 | ejbserver.connector.statementpool.clear.backcompat | ステートメントプーリング機能でステートメントを再利用する際に初期化するステートメントの内容を指定します。
DataSourceオブジェクトのキャッシング | ejbserver.jndi.cache.reference | DataSourceオブジェクトのキャッシングを有効にするかどうかを指定します。
DB Connectorのコンテナ管理でのサインオンの最適化 | ejbserver.connectionpool.applicationAuthentication.disabled | コンテナ管理のサインオンの最適化機能を有効にするかどうかを指定します。

注※　WAR属性ファイル，Entity Bean属性ファイル，Session Bean属性ファイル，またはMessage-driven Bean属性ファイルの<res-sharing-scope>タグで，Unshareable（リソースを共有しない）を指定している場合のことです。

ライトトランザクションの設定については，「3.4.12　実行環境での設定」を参照してください。

なお，インプロセストランザクションサービスは，デフォルトの設定で使用される機能です。設定は不要です。

(2)　リソースアダプタの設定

実行環境でのリソースアダプタの設定は，サーバ管理コマンドおよび属性ファイルを使用します。パフォーマンスチューニングのための機能の定義には，Connector属性ファイルを使用します。

Connector属性ファイルでのパフォーマンスチューニングのための機能の定義について次の表に示します。

表3-57　Connector属性ファイルでのパフォーマンスチューニングのための機能の定義

分類
項目
指定するタグ
設定内容

コネクションプーリング
コネクションの最小値と最大値
<property>タグのMinPoolSizeとMaxPoolSize
コネクションプールにプールするコネクションの最小値と最大値を指定します。

コネクションプールのウォーミングアップ
<property>タグのWarmup
コネクションプールのウォーミングアップ機能を使用する指定をします。

コネクション管理スレッド
<property>タグのNetworkFailureTimeout
コネクション管理スレッドを使用する指定をします。
コネクション管理スレッドを使用する場合，コネクションの障害検知機能，およびコネクション数調節機能のタイムアウトを使用する設定になります。07-60以前のバージョンでは5秒で固定です。08-00以降のバージョンでは任意の時間を指定できます（デフォルト値は5秒）。

コネクション数調節機能
<property>タグのConnectionPoolAdjustmentInterval
コネクション数調節機能が動作する間隔を指定します。
なお，コネクション数調節機能にタイムアウトを設定する場合には，NetworkFailureTimeoutでコネクション管理スレッドの使用を有効にします。※1

ステートメントプーリング
PreparedStatementのプールサイズ※2
<config-property>タグのPreparedStatementPoolSize
PreparedStatementのプールサイズを指定します。

CallableStatementのプールサイズ※2
<config-property>タグのCallableStatementPoolSize
CallableStatementのプールサイズを指定します。

注※1　コネクションの障害検知機能のタイムアウトと同じキーです。このため，コネクションの障害検知機能でタイムアウトを使用する場合は，コネクション数調節機能でもタイムアウトを使用する設定となります。

注※2　XDM/RD E2 11-01以前のバージョンの場合，ステートメントプーリング機能を利用できないため，これらのプロパティには0を指定してください。

(3)　J2EEアプリケーションの設定

実行環境でのJ2EEアプリケーションの設定は，サーバ管理コマンドおよび属性ファイルで実施します。パフォーマンスチューニングのための機能の定義には，WAR属性ファイル，Session Bean属性ファイル，Entity Bean属性ファイルまたはMessage-driven Bean属性ファイルを使用します。

これらの属性ファイルで指定するタグは，cosminexus.xmlまたはDDと対応しています。なお，cosminexus.xmlでの定義については，「3.14.9　cosminexus.xmlでの定義」を参照してください。

3.15　フォールトトレランスのための機能

この節では，フォールトトレランスのための機能について説明します。

この節の構成を次の表に示します。

表3-58　この節の構成（フォールトトレランスのための機能）

分類 | タイトル | 参照先
解説 | コネクションの障害検知 | 3.15.1
コネクション枯渇時のコネクション取得待ち | 3.15.2
コネクションの取得リトライ | 3.15.3
コネクションプールの情報表示 | 3.15.4
コネクションプールのクリア | 3.15.5
コネクションの自動クローズ | 3.15.6
コネクションスイーパ | 3.15.7
トランザクションタイムアウトとステートメントキャンセル | 3.15.8
トランザクションリカバリ | 3.15.9
障害調査用SQLの出力 | 3.15.10
オブジェクトの自動クローズ | 3.15.11
実装 | cosminexus.xmlでの定義 | 3.15.12
設定 | 実行環境での設定 | 3.15.13

注　「運用」について，この機能固有の説明はありません。

＜この節の構成＞

3.15.1　コネクションの障害検知

3.15.2　コネクション枯渇時のコネクション取得待ち

3.15.3　コネクションの取得リトライ

3.15.4　コネクションプールの情報表示

3.15.5　コネクションプールのクリア

3.15.6　コネクションの自動クローズ

3.15.7　コネクションスイーパ

3.15.8　トランザクションタイムアウトとステートメントキャンセル

3.15.9　トランザクションリカバリ

3.15.10　障害調査用SQLの出力

3.15.11　オブジェクトの自動クローズ

3.15.12　cosminexus.xmlでの定義

3.15.13　実行環境での設定

3.15.1　コネクションの障害検知

コネクションプーリングを使用している場合，リソースダウン・ネットワーク障害などが発生すると，ユーザプログラムのコネクション取得要求に対し，障害が発生したコネクションを返すおそれがあります。コネクションの障害検知機能を使用すると，プーリングされているコネクションに障害が発生していないかをチェックし，障害が発生したコネクションをなるべく返さないようにできます。

コネクション障害検知機能は，コネクション取得リトライ機能と併用できます。この場合，ユーザプログラムのコネクション取得要求時にコネクション障害を検知すると，新しいコネクション取得のリトライを実施し，障害が復旧した時点でコネクションをユーザプログラムに返すことができます。

なお，新しいコネクションを作成して返すことは，コネクションの障害検知のタイミングを「コネクション取得要求時」に設定している場合だけ有効になります。

コネクションの障害検知のタイミングについては，「(2)　障害検知を実施するタイミング」を参照してください。

＜この項の構成＞

(1)　前提条件

(2)　障害検知を実施するタイミング

(3)　障害検知のタイムアウト

(4)　チェック時の動作

(5)　注意事項

(1)　前提条件

コネクションの障害検知機能の利用可否を次の表に示します。

表3-59　コネクションの障害検知機能の利用可否

リソース | 接続方法 | 利用可否
データベース | DB Connector | ○
データベース上のキュー | DB Connector for Cosminexus RMとCosminexus RM | ○
OpenTP1 | uCosminexus TP1 Connector | 　 ×※1
TP1/Message Queue - Access | 　 ×※1
SMTPサーバ | メールコンフィグレーション | ×
JavaBeansリソース | － | ×
そのほかのリソース | Connector 1.0仕様またはConnector 1.5仕様に準拠したリソースアダプタ | 　 △※2

（凡例）○：使用できる　×：使用できない　△：条件によって異なる　－：該当なし

注※1　アプリケーションサーバが提供するコネクションの障害検知機能は使用できませんが，uCosminexus TP1 ConnectorまたはTP1/Message Queue - Accessでは，コネクションの障害検知機能と同様の機能が提供されています。

注※2　Connector 1.5仕様に準拠したリソースアダプタを使用している場合に，リソースアダプタがValidatingManagedConnectionFactoryインタフェースのgetInvalidConnectionsメソッドを実装しているときに使用できます。

(2)　障害検知を実施するタイミング

コネクションの障害を検知するタイミングは，表に示したタイミングのどちらかを選択できます。

表3-60　コネクションの障害検知のタイミング

障害検知のタイミング | 内容
コネクション取得要求時 | コネクション取得時に，毎回，障害検知を実施します。この場合，コネクション取得要求のレスポンス性能が劣化しますが，障害が発生したコネクションを取得する確率は低くなります。コネクション取得要求の頻度が少ない場合や，障害が発生したコネクションの取得がほとんど許容されない場合に有用です。
一定間隔 | 一定時間の間隔で，障害検知を実施します。障害検知の間隔をある程度長くすることで，障害検知処理による性能劣化を少なくできます。ただし，障害が発生したコネクションを取得する確率は高くなります。コネクション取得要求の頻度が多い場合や，障害が発生したコネクションの取得がある程度許容される場合に有用です。

なお，デフォルトでは，コネクション取得要求時に障害検知を実施する設定となっています。コネクションの障害検知を実施しない設定もできます。

コネクション障害検知の有効・無効の切り替えや，検知するタイミングの設定は，リソースアダプタのプロパティとして設定します。リソースアダプタの設定については，「3.15.13　実行環境での設定」を参照してください。

(3)　障害検知のタイムアウト

コネクション障害検知に対する応答時間にタイムアウトを設定できます。

サーバ障害やネットワーク障害が発生してリソースからの応答が返らない場合，コネクション障害検知の実行に対しても応答が返らなくなることがあります。タイムアウトを設定することで，リソースからの応答が返らない場合も，コネクションのチェックを終了して，処理を継続できます。なお，障害検知のタイムアウト時間は簡易構築定義ファイルのJ2EEサーバで指定するキーに，任意の時間を指定できます（デフォルト値は5秒）。

コネクション障害検知のタイムアウトは，コネクション管理スレッドを使用して動作します。コネクション管理スレッドは，コネクションプールのコネクション数に応じてシステム内で作成されます。コネクション管理スレッドの数と，コネクションプールのコネクション数の最大値の関係を次に示します。

コネクション管理スレッド数 = コネクションプールのコネクション数の最大値×2

このため，コネクション障害検知にタイムアウトを設定すると，設定しない場合に比べて多くのメモリを消費します。必要なメモリ使用量を適切に見積もってください。

また，コネクションプールのコネクション数の最大値の設定が無制限の場合，メッセージが出力されて，コネクション障害検知のタイムアウトが無効になります。

なお，コネクション障害検知のタイムアウトを有効にする場合の注意事項の詳細については，「(5)　注意事項」を参照してください。

コネクション障害検知のタイムアウトの有効・無効は，リソースアダプタのプロパティをカスタマイズして設定します。リソースアダプタのプロパティの設定については，「3.15.13　実行環境での設定」を参照してください。

(4)　チェック時の動作

コネクション障害検知をコネクション取得要求時に実施する場合と，一定間隔で実施する場合の動作について説明します。

コネクション障害検知をコネクション取得要求時に実施する場合
コネクション障害検知をコネクション取得要求時に実施する場合の動作を次に示します。

コネクションプールから未使用コネクションが取得されます。

コネクションチェックメソッドによって，コネクションに障害が発生していないかどうかチェックされます。
コネクション障害検知のタイムアウトが無効な場合，このチェックはコネクション取得要求の延長で実施されます。
コネクション障害検知のタイムアウトが有効な場合，このチェックはコネクション管理スレッドで実施されます。サーバ障害やネットワーク障害などでチェックメソッドの応答がタイムアウト時間以内に返らないときは，コネクションに障害が発生していると判断されます。このとき，メッセージが出力されます。
なお，リソースアダプタにコネクションチェックメソッドが実装されていない場合，コネクションの状態はチェックされません。

コネクションに障害が発生している場合，チェックに使用したコネクションが破棄されて，新たに作成されたコネクションがユーザプログラムに返されます。
コネクションに障害が発生していない場合，チェックに使用したコネクションがユーザプログラムに返されます。

コネクション障害検知を一定間隔で実施する場合
コネクション障害検知を一定間隔で実施する場合の動作を次に示します。

コネクションプールから未使用コネクションが一つ取得されて，そのコネクションが有効であるかどうかがチェックされます。
ただし，未使用コネクションがプーリングされていない場合は，チェックされません。

コネクション障害検知のタイムアウトが無効な場合，コネクションチェックメソッドによって，コネクションに障害が発生していないかどうかのチェックが一定間隔で実施されます。
コネクション障害検知のタイムアウトが有効な場合，コネクション管理スレッドで，チェックが一定間隔で実施されます。サーバ障害やネットワーク障害などでチェックメソッドの応答がタイムアウト時間以内に返らないときは，コネクションに障害が発生していると判断されます。このとき，メッセージが出力されます。
なお，リソースアダプタにコネクションチェックメソッドが実装されていない場合，コネクションの状態はチェックされません。

コネクションに障害が発生している場合に，コネクション障害検知のタイムアウトが無効のときは，コネクションチェックに使用されたコネクションが破棄されて，コネクションプール内の使用中コネクションが再利用不可にマークされます。また，未使用コネクションが破棄されます。
コネクション障害検知のタイムアウトが有効のときは，コネクションチェックに使用したコネクションが破棄されて，コネクション管理スレッドによってコネクションプール内の使用中コネクションが再利用不可にマークされます。また，未使用コネクションが，コネクションプールから取り除かれて，破棄されます。
コネクションに障害が発生していない場合は，コネクションチェックに使用されたコネクションがコネクションプールに返却されます。

(5)　注意事項

パラレルサーバ構成のリソースを使用する場合の注意事項と，コネクション障害検知のタイムアウトを有効にした場合の注意事項について説明します。

(a)　パラレルサーバ構成のリソースを使用する場合の注意事項

コネクション障害検知を一定間隔で実施する場合，コネクションプール内のコネクションをサンプリングチェックするため，一部のサーバに障害が発生しても検知できないことがあります。

(b)　コネクション障害検知のタイムアウトを有効にした場合の注意事項

コネクション障害検知のタイムアウトを有効にした場合の注意事項を次に示します。

コネクション障害検知にタイムアウトを設定した場合，システム内で，コネクションプールのコネクション数に応じた障害検知用のスレッドが生成されます。このため，コネクション障害検知にタイムアウトを設定すると，設定しない場合に比べて多くのメモリを消費するので注意が必要です。
障害検知用のスレッドは，コネクションプールの最大コネクション数の2倍の数だけ作成されます。必要なメモリ使用量を適切に見積もってください。

サーバ障害やネットワーク障害などが繰り返し発生する場合にシステムの運用を続けると，コネクションチェックメソッドを実行中のコネクション管理スレッドが増え続け，システム側が用意したすべてのコネクション管理スレッドを使い切るおそれがあります。使用できるコネクション管理スレッドがない場合，メッセージが出力されて，コネクション取得要求がエラーとなります。

コネクション障害検知を実施する場合，コネクションプールから取り除いた未使用コネクションは，コネクションプール内のコネクション数としてカウントされません。そのため，コネクションプール内のコネクションとコネクションプールから取り除いた未使用コネクションの総数が，コネクションプールのコネクション数の最大値を一時的に超える場合があります。

3.15.2　コネクション枯渇時のコネクション取得待ち

コネクションがコネクションプールに指定した最大コネクション数までプールされていて，利用できるコネクションがプール中にない状態を，コネクション枯渇といいます。

コネクション枯渇状態のときには，コネクション取得要求を待ち状態にできます。待ち状態になっているコネクション取得要求は，コネクションが解放されるとすぐにコネクションを取得できます。これによって，コネクション枯渇時に，効率良くコネクションを取得できます。コネクション枯渇時の取得待ちについて，次の図で説明します。

図3-36　コネクション枯渇時のコネクション取得待ち

この図では，コネクションプールの最大数は2となっています。このため，四つのgetConnectionからコネクション取得要求があっても，二つまでしか処理できません。最初の二つのコネクションの取得要求については，コネクションプールにコネクションがあるため，コネクションの取得ができます。残りの二つについては，コネクション枯渇の状態になるため，コネクション取得待ちのキューに入り，コネクションが解放されるのを待ちます。

なお，コネクション取得待ちは，コネクションプールを利用している場合に設定できます。

コネクション取得待ちをする場合には，リソースアダプタのプロパティとして，次の二つの内容を設定する必要があります。

コネクション枯渇時にコネクションの取得待ちをするかどうか

コネクション取得待ちの最大時間

リソースアダプタの設定については，「3.15.13　実行環境での設定」を参照してください。

＜この項の構成＞

(1)　コネクション枯渇時の動作

(1)　コネクション枯渇時の動作

コネクション取得待ちを設定している場合，コネクション枯渇時のコネクション取得要求は待ち状態になります。

また，コネクション取得要求を再開するタイミングは，次のどちらかになります。

コネクションが解放されて，未使用コネクションができたとき

コネクションが破棄されて，コネクション数が最大数未満になったとき

なお，コネクション取得要求の再開後にエラーが発生した場合，コネクション取得のリトライ機能が有効になっているときは，リトライ処理が実施されます。

3.15.3　コネクションの取得リトライ

コネクション取得リトライは，使用できるコネクションがコネクションプールにない場合や，物理コネクションの確立に失敗した場合に，自動的にコネクションの取得をリトライする機能です。コネクション取得リトライ機能を使用することで，コネクション取得に失敗した場合に，ユーザプログラムでリトライをする必要がなくなります。

コネクション取得をリトライできる条件は次のとおりです。

コネクションの取得要求時に，コネクションプールに未使用状態のコネクションがない場合で，コネクションプールのコネクション総数がプーリングするコネクションの最大数に達しているとき

物理コネクションの確立に失敗した場合

なお，リトライしてもコネクションが取得できない場合は，アプリケーションプログラムに例外が通知され，コネクションの取得は失敗します。

コネクションプールが枯渇したときの動作は，「3.15.2　コネクション枯渇時のコネクション取得待ち」に従います。

コネクション取得リトライを実施する場合には，リソースアダプタのプロパティとして，次の二つの内容を設定する必要があります。

リトライの回数
リトライする回数を設定します。

リトライまでの間隔
次のリトライまでの間隔を秒単位で設定します。

なお，リトライの回数，およびリトライまでの間隔を大きくすると，コネクション取得処理が重なった場合に，待ちが発生するおそれがあります。

リソースアダプタの設定については，「3.15.13　実行環境での設定」を参照してください。

＜この項の構成＞

(1)　前提条件

(1)　前提条件

コネクション取得のリトライ機能を使用するための前提条件を次の表に示します。

表3-61　コネクション取得のリトライ機能の利用

リソース | 接続方法 | 利用可否
データベース | DB Connector | ○
データベース上のキュー | DB Connector for Cosminexus RMとCosminexus RM | ○
OpenTP1 | uCosminexus TP1 Connector | ○
TP1/Message Queue - Access | ○
SMTPサーバ | メールコンフィグレーション | ×
JavaBeansリソース | － | ×
そのほかのリソース | Connector 1.0仕様またはConnector 1.5仕様に準拠したリソースアダプタ | ○

（凡例）○：使用できる　×：使用できない　－：該当なし

3.15.4　コネクションプールの情報表示

コネクションプール内のコネクションの情報は，cjlistpoolコマンドを使用して表示できます。cjlistpoolコマンドは，コネクションプールのクラスタ化機能を使用した場合のメンバリソースアダプタに対しても実行できます。

コマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjlistpool（コネクションプールの一覧表示）」を参照してください。また，コネクションプールのクラスタ化機能については，「3.17　コネクションプールのクラスタ化機能」を参照してください。

メンバリソースアダプタのコネクション情報の表示例を次に示します。なお，コネクションプールが無効な場合は，コネクション情報は表示されません。

図3-37　メンバリソースアダプタのコネクション情報の表示例

3.15.5　コネクションプールのクリア

データベースサーバのダウンなどによって，コネクションが切断された場合，プールされているコネクションはコネクションプール内に残ってしまいます。これらのコネクションは，cjclearpoolコマンドによって削除できます。

なお，コマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjclearpool（コネクションプール内のコネクション削除）」を参照してください。

3.15.6　コネクションの自動クローズ

ユーザプログラムがオープンしたリソースのコネクションは，ユーザプログラムでクローズする必要があります。例外発生などの理由で，ユーザプログラムがコネクションをクローズすることができない場合，WebコンテナやEJBコンテナが自動的にコネクションをクローズする機能があります。

コネクション自動クローズ機能は，機能によって有効と無効を切り替えることができます。コネクションの自動クローズの方法と切り替えについて次の表に示します。

表3-62　コネクション自動クローズの方法と機能の切り替え

自動クローズの方法 | 有効と無効の切り替え | 備考
Webコンテナによるコネクション自動クローズ | ○※1，※2 | －
EJBコンテナによるコネクション自動クローズ | ×※1 | 常に有効になります。

（凡例）○：切り替えできる　×：切り替えできない　－：該当しない

注※1　対象リソースは，リソースアダプタのコネクションとなります。

注※2　Webコンテナによるコネクションの自動クローズ機能は，デフォルトでは有効となっています。無効にする場合は，J2EEサーバのプロパティをカスタマイズして設定します。J2EEサーバの動作設定のカスタマイズについては，「3.15.13　実行環境での設定」を参照してください。

＜この項の構成＞

(1)　Webコンテナによるコネクション自動クローズ

(2)　EJBコンテナによるコネクション自動クローズ

(3)　コネクション自動クローズが実行されたことを確認する方法

(4)　注意事項

(1)　Webコンテナによるコネクション自動クローズ

サーブレットやJSPのサービスメソッド内で，取得・オープンされたJDBCコネクションのうち，メソッドの実行完了時にクローズが実行されていないコネクションに対して，J2EEコンテナ側で自動的にコネクションをクローズします。これによって，オープンされたまま蓄積しているコネクションを自動でクローズできます。

なお，コネクションの自動クローズ機能は，サーブレット内部の別のメソッド，または外部のクラスでコネクションを取得・利用した場合にも有効です。

Webコンテナによるコネクション自動クローズは，サーブレットやJSPのserviceメソッドが完了したときに実行されます。

(2)　EJBコンテナによるコネクション自動クローズ

例外発生などの理由で，EJB内で取得したリソースのコネクションをユーザがクローズできない場合に，EJBコンテナが自動的にコネクションをクローズして解放する機能です。

EJBコンテナによるコネクションの自動クローズは，次のタイミングで実施されます。

EJBが破棄されるとき

Stateless Session Beanで，ビジネスメソッドがリターンするとき

Stateful Session Beanがパッシベイトされるとき

(3)　コネクション自動クローズが実行されたことを確認する方法

コネクション自動クローズが実行されたことは，メッセージログまたはPRFトレースで確認できます。

テスト実行時や障害調査時など，性能を考慮しなくてよい場合は，メッセージログによって確認することをお勧めします。実運用時に確認したい場合は，PRFトレースによって確認することをお勧めします。

(a)　メッセージログで確認する方法

ログレベルを「Warning」に設定してください。

コネクション自動クローズが実行された場合は，J2EEサーバのメッセージログにKDJE31010-Wが出力されます。

ログレベルの設定方法については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「3.3.6　J2EEサーバのログ取得の設定」を参照してください。

(b)　PRFトレースでの確認方法

JCAコンテナの機能レイヤのPRFトレース取得レベルを「詳細」に設定してください。

コネクション自動クローズが実行された場合は，PRFトレースファイルに次のイベントIDが出力されます。

0x8B84

0x8B85

PRFトレースの取得レベルの設定方法については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「3.3.6　J2EEサーバのログ取得の設定」を参照してください。また，機能レイヤごとのPRFトレース取得レベルの設定方法については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cprflevel（PRFトレース取得レベルの表示と変更）」またはマニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cprfstart（PRFデーモンの開始）」を参照してください。

(4)　注意事項

Servlet/JSPでユーザが生成したスレッド（ユーザスレッド）で取得したコネクションは，自動クローズされません。

3.15.7　コネクションスイーパ

コネクションスイーパは，一定間隔でコネクションプールを監視し，一定時間使用していない未使用コネクションを破棄する機能です。該当コネクションを最後に利用した時点からの経過時間が，指定された時間以上の場合に，コネクションを破棄します。

コネクションスイーパ機能は，デフォルトでは無効になっています。なお，コネクションスイーパ機能の設定は，リソースアダプタのプロパティとして設定します。リソースアダプタの設定については，「3.15.13　実行環境での設定」を参照してください。

3.15.8　トランザクションタイムアウトとステートメントキャンセル

トランザクションの開始時点からの経過時間を監視し，指定された時間が経過した時点でトランザクションをロールバックする機能です。監視期間は，トランザクションの開始時点から，トランザクションの決着時点までです。トランザクションタイムアウトが発生したあと，該当するトランザクションでのJTA，およびJDBCインタフェースへのアクセスは例外が通知されます。

トランザクションタイムアウト機能は，アプリケーションサーバが管理するトランザクションの場合に有効です。

なお，BMT，サーブレット，またはJSPの場合，トランザクションタイムアウトが発生したあと，該当するトランザクションに対してUserTransaction.commit/rollbackを発行すると，JTA，およびJDBCインタフェースにアクセスできるようになります。

＜この項の構成＞

(1)　トランザクションタイムアウトの設定単位

(2)　トランザクションタイムアウト発生時のステートメントキャンセル

(1)　トランザクションタイムアウトの設定単位

トランザクションタイムアウトの設定は，J2EEサーバ単位またはBean単位で設定できます。

(a)　J2EEサーバ単位での設定

J2EEサーバ単位の設定は，J2EEサーバのプロパティをカスタマイズして設定します。J2EEサーバの動作設定のカスタマイズについては，「3.15.13　実行環境での設定」を参照してください。

(b)　Bean単位での設定

Bean単位で設定するには，BMTの場合とCMTの場合で異なります。

BMTの場合
UserTransactionインタフェースを使用してトランザクションを管理する場合は，UserTransactionインタフェースのsetTransactionTimeoutメソッドを使用して，デフォルト値から変更できます。

CMTの場合
サーバ管理コマンドを使用して設定します。設定単位は，Bean単位，インタフェース単位，およびメソッド単位の三つから選択できます。
設定が有効になるメソッドは，次のどちらかです。

トランザクション属性が「Required」に設定され，EJBコンテナがトランザクションを開始するメソッド

トランザクション属性が「RequiresNew」に設定されたメソッド

クライアントから伝播するトランザクションで動作するSupports属性およびMandatory属性の場合，トランザクションを使用しないNotSupported属性およびNever属性の場合は，タイムアウトの設定は無効になります。なお，トランザクション属性については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.7.3　CMT」を参照してください。
なお，設定の優先順位は，次のとおりです。

メソッド単位での設定

インタフェース単位での設定

Bean単位での設定

J2EEサーバ単位での設定

Bean単位のトランザクションタイムアウトの設定は，J2EEアプリケーションに含まれるSession Bean，Entity BeanまたはMessage-driven Beanの属性（プロパティ）として設定します。J2EEアプリケーションの設定については，「3.15.13　実行環境での設定」を参照してください。

(2)　トランザクションタイムアウト発生時のステートメントキャンセル

実行中のSQL処理が返ってこない状態でトランザクションタイムアウトが発生すると，ステートメントがキャンセルされます。

ステートメントのキャンセルを有効にする場合，DB ConnectorのCancelStatementプロパティにtrueを設定する必要があります。リソースアダプタの設定については，「3.15.13　実行環境での設定」を参照してください。

3.15.9　トランザクションリカバリ

J2EEサーバやリソースマネジャの障害で，プリペア状態またはヒューリスティック完了状態となった2フェーズトランザクションを決着させる機能です。グローバルトランザクションを使用する場合に有効になります。

J2EEサーバを開始すると，インポートされているリソースに対して，無条件にトランザクションの全面回復処理を実行します。また，トランザクション実行中にリソースマネジャがダウンした場合にも，部分回復処理をします。

なお，トランザクションの状態は，インプロセストランザクションサービスを使用している場合，サーバ管理コマンドのcjlisttrnコマンドで表示できます。また，停止中のJ2EEサーバのステータスファイルに残っている，未決着トランザクション情報はcjlisttrnfileコマンドで表示できます。

ライトトランザクションが有効なときには，トランザクションリカバリ機能は使用できません。

注意

J2EEサーバ再起動によるトランザクションリカバリをしない場合，トランザクションの回復は各リソースの回復手順に従い，ユーザ責任で手動回復してください。

＜この項の構成＞

(1)　J2EEサーバ終了時の未決着トランザクションの確認とタイムアウトの設定

(2)　注意事項

(3)　トランザクション情報の確認手順

(1)　J2EEサーバ終了時の未決着トランザクションの確認とタイムアウトの設定

J2EEサーバを正常停止する時，J2EEサーバは未決着のトランザクションがないことを確認してから停止します。未決着のトランザクションがあるときは，それらが完了するまで無限に待ちます。また，そのトランザクションが決着するまでリソースを削除できません。

これに対して，システム開発時など，トランザクションを早急に解決する必要がない場合は，未決着トランザクションの確認時間にタイムアウトを設定できます。タイムアウトが発生した場合は，未決着のトランザクションの確認処理が完了していなくても，J2EEサーバの停止処理がされます。ただし，タイムアウトは，J2EEアプリケーション開発時などに設定してください。J2EEアプリケーション運用時には，トランザクションの信頼性を保証するために，タイムアウトを設定しないことをお勧めします。

タイムアウトの設定は，J2EEサーバのプロパティをカスタマイズして設定します。J2EEサーバの動作設定のカスタマイズについては，「3.15.13　実行環境での設定」を参照してください。

(2)　注意事項

トランザクションリカバリについての注意事項を説明します。

(a)　J2EEサーバ起動時にリソースアダプタの開始に失敗した場合の注意

J2EEサーバ起動時にXATransactionを利用するリソースアダプタの開始に失敗した場合，J2EEサーバはトランザクションリカバリを実行しないで，メッセージKDJE48605-Eを出力して強制停止します。この場合は，リソースアダプタの開始処理が失敗する原因を取り除いてから，J2EEサーバを再起動してください。これによって，プリペア状態またはヒューリスティック状態のトランザクションは決着されます。

(b)　J2EEサーバを再起動する時の注意

J2EEサーバが強制終了または異常終了したあと，リソースを削除するとリカバリできなくなります。このため，再起動時にリソースの構成を変更しないでください。

強制終了または異常終了前の受信ポートと同じポートで再起動する必要があります。このため，簡易構築定義ファイル内の<configuration>タグ内のパラメタ「ejbserver.distributedtx.recovery.port」の値を変更しないでください。なお，Management Serverを利用しないでシステムを構築する場合は，usrconf.propertiesのejbserver.distributedtx.recovery.portキーを変更しないでください。

(c)　トランザクションリカバリを実行するための権限

リカバリはリソース（XADataSourceなど）に設定したデフォルトユーザで実行します。リソースマネジャによっては，未決着トランザクションの走査に特別な権限や設定が必要になります。また，複数のユーザでサインオンする場合，デフォルトユーザにそのほかのユーザのトランザクションを決着できるリソースマネジャでの適正な権限を付与する必要があります。なお，詳細については，各リソースのマニュアルを参照してください。

Oracleでリカバリをする場合で，JDBCドライバにOracle JDBC Thin Driverを使用するときは，ユーザに次の権限が必要です。

SYS.DBA_PENDING_TRANSACTIONSへのSELECT権限

FORCE ANY TRANSACTION権限

SYS.DBMS_SYSTEMをEXECUTEする権限

Oracleを使用する場合の設定については，マニュアル「Cosminexus アプリケーションサーバ システム構築・運用ガイド」の「7.5.2　Oracleの設定（Oracle JDBC Thin Driverの場合）」を参照してください。

(d)　使用するコネクション数

トランザクションリカバリをする場合に使用するコネクション数に注意してください。

J2EEサーバでは，トランザクションサポートレベルがXATransactionの一つのリソースアダプタに対して，次のコネクションを確立します。

プーリング管理をするコネクション

リカバリ用のコネクション（一つ）

同一のリソースマネジャで必要となる最大コネクション数は，次の式で示す値になります。リソースマネジャにコネクション数の上限がある場合は，注意してください。

同一のリソースマネジャで必要となる最大コネクション数＝IR(1) + … + IR(N) + N

IR(i)

i番目のリソースアダプタのプール設定値の最大コネクション数。

1≦i≦Nです。

N

Connector 1.0仕様に準拠したリソースアダプタの場合は，同一のリソースマネジャに接続するリソースアダプタ数。

Connector 1.5仕様に準拠したリソースアダプタの場合は，同一のリソースマネジャに接続するリソースアダプタ内のコネクション定義数の総数。

対象になるのは，開始状態で，かつトランザクションサポートレベルがXATransactionのリソースアダプタです。

(3)　トランザクション情報の確認手順

ここでは，稼働中および停止中のJ2EEサーバのトランザクションの情報を確認する方法について説明します。稼働中のJ2EEサーバでのトランザクションの状態や，停止中のJ2EEサーバでの未決着のトランザクションの有無などの情報を確認できます。

(a)　稼働中のトランザクションの確認手順

J2EEサーバで稼働中のトランザクションの情報を確認できます。トランザクションの状態，グローバルトランザクションID，経過時間，ブランチの種類などの情報を確認できます。

稼働中のトランザクションの確認には，cjlisttrnコマンドを使用します。実行形式と実行例を次に示します。

実行形式

cjlisttrn [<サーバ名称>] -bqual

実行例

cjlisttrn MyServer -bqual

また，未決着のトランザクションの状態も確認できます。未決着のトランザクションについての情報を確認するときは，引数に「-pending」を指定します。未決着のトランザクションについての情報を確認する場合の実行形式と実行例を次に示します。

実行形式

cjlisttrn [<サーバ名称>] -pending -bqual

実行例

cjlisttrn MyServer -pending -bqual

cjlisttrnコマンド，および取得できる情報の詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjlisttrn（稼働中のJ2EEサーバのトランザクション情報の表示）」を参照してください。

(b)　停止中のトランザクションの確認手順

停止中のJ2EEサーバのトランザクションの情報を確認できます。トランザクションの状態，グローバルトランザクションID，経過時間，ブランチの種類等の情報を確認できます。また，未決着のトランザクションが残っているかどうかも確認できます。

停止中のトランザクションの確認には，cjlisttrnfileコマンドを使用します。実行形式と実行例を次に示します。

実行形式

cjlisttrnfile [<サーバ名称>] -bqual

実行例

cjlisttrnfile MyServer -bqual

J2EEサーバが停止中の状態で未決着のトランザクションが存在する場合は，必要に応じて次の処理を実行して，トランザクションを決着させてください。

J2EEサーバを再起動する（cjstartsvコマンド）

J2EEサーバをリカバリモードで起動する（cjstartrecoverコマンド）

cjlisttrnfileコマンド，および取得できる情報の詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjlisttrnfile（停止中のJ2EEサーバのトランザクション情報の表示）」を参照してください。

3.15.10　障害調査用SQLの出力

デッドロックやスローダウンなどの障害が発生した場合，発行したSQLが障害の要因となった可能性があります。そこで，発行したSQLをログに出力することによって，障害要因の解析が容易になります。ログに出力されるSQLの情報を障害調査用SQLと呼びます。

＜この項の構成＞

(1)　出力されるタイミング

(2)　出力先

(3)　出力内容

(4)　注意事項

(1)　出力されるタイミング

障害調査用SQLは，次のタイミングで出力されます。

トランザクションタイムアウト発生時

J2EEアプリケーションの強制停止実行時

メソッドキャンセルコマンド実行時

メソッドタイムアウト発生後のメソッドキャンセル実行時

(2)　出力先

障害調査用SQLは，リソースアダプタの稼働ログ，および性能解析トレースに出力されます。

リソースアダプタの稼働ログでは，KDJE50080-Wのメッセージに出力されます。詳細については，マニュアル「Cosminexus アプリケーションサーバ メッセージ 2」の「KDJE50080-W」を参照してください。

性能解析トレースでは，0x8C41のイベントIDに出力されます。詳細については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「7.　性能解析トレースのトレース取得ポイントとPRFトレース取得レベル」を参照してください。

(3)　出力内容

出力対象のコネクションでSQLを発行している場合，物理コネクションがSQLを保持しています。この物理コネクションが保持しているSQLが，障害調査用SQLとして出力されます。

SQLを保持する物理コネクション

障害調査用SQLが出力されるタイミングごとに，SQLを保持している物理コネクションを示します。

トランザクションタイムアウト発生時
トランザクションに参加しているコネクションに対応する物理コネクション。

J2EEアプリケーションを強制停止した時，メソッドキャンセルコマンド実行時，またはメソッドタイムアウト発生後のメソッドキャンセル実行時
トランザクション処理中の場合，トランザクションに参加しているコネクションに対応する物理コネクション。
トランザクションを使用していない場合，アプリケーション強制停止またはメソッドキャンセルを実行するインスタンスで使用中のコネクションに対応する物理コネクション。なお，クローズしたコネクションは，障害調査用SQL出力の対象外になります。

SQLを保持するAPI

ユーザアプリケーションで次のAPIが呼び出されたとき，引数で渡されたSQLを物理コネクションに保持します。保持するSQLは物理コネクションごとに一つです。APIが呼び出されるたびに，最新のSQLが上書きされます。SQLを保持するAPIを次の表に示します。

表3-63　SQLを保持するAPIの一覧

クラス | メソッド
java.sql.Connection | prepareCall(String sql)
prepareCall(String sql, int resultSetType, int resultSetConcurrency)
prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)
prepareStatement(String sql)
prepareStatement(String sql, int autoGeneratedKeys)
prepareStatement(String sql, int[] columnIndexes)
prepareStatement(String sql, int resultSetType, int resultSetConcurrency)
prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)
prepareStatement(String sql, String[] columnNames)
java.sql.Statement | addBatch(String sql)
execute(String sql)
execute(String sql, int autoGeneratedKeys)
execute(String sql, int[] columnIndexes)
execute(String sql, String[] columnNames)
executeBatch()※1
executeQuery(String sql)
executeUpdate(String sql)
executeUpdate(String sql, int autoGeneratedKeys)
executeUpdate(String sql, int[] columnIndexes)
executeUpdate(String sql, String[] columnNames)
java.sql.PreparedStatement | java.sql.Statementから継承した表示対象メソッド
addBatch()※2
execute()※2
executeQuery()※2
executeUpdate()※2
java.sql.CallableStatement | java.sql.PreparedStatementから継承した表示対象メソッド

注※1　executeBatch()メソッドを実行した場合は，最後にaddBatch(String sql)メソッド， addBatch()メソッドで加えられたSQLを物理コネクションに保持します。

注※2　addBatch()メソッド，execute()メソッド，executeQuery()メソッド，executeUpdate()メソッドを実行した場合，java.sql.ConnectionのprepareStatementメソッド，prepareCallメソッドの引数で与えられたSQLを物理コネクションに保持します。ただし，SQLのINパラメタプレースホルダー（"？"）は，置換しないで"？"のまま出力します。

(4)　注意事項

障害調査用SQLの出力機能についての注意事項を説明します。

DB Connectorを使用している場合，この機能は常に有効になります。DB Connector以外を使用している場合は無効になります。

リソースアダプタの稼働ログの障害調査用SQLログに出力されるメッセージが4キロバイトを超えた場合，4キロバイトまでのメッセージだけが出力されます。

コネクションシェアリング，コネクションアソシエーションによって共有されたコネクションは，物理コネクションが一つのため，障害調査用SQLログは一つだけ出力されます。

3.15.11　オブジェクトの自動クローズ

ユーザプログラムでオープンしたStatementオブジェクトなどは，ユーザプログラムでクローズする必要があります。ただし，クローズできなかった場合，DB Connectorは，ユーザハンドル（java.sql.Connection）から生成された，次のオブジェクトを自動的にクローズできます。

Statementオブジェクト

PreparedStatementオブジェクト

CallableStatementオブジェクト

各種ステートメントやDatabaseMetaDataから生成されたResultSetオブジェクト

3.15.12　cosminexus.xmlでの定義

フォールトトレランスのための機能のうち，CMTのトランザクションタイムアウトの定義は，cosminexus.xmlの<ejb-jar>タグ内に指定します。cosminexus.xmlでのフォールトトレランスのための機能の定義について次の表に示します。

表3-64　cosminexus.xmlでのフォールトトレランスのための機能の定義

指定するタグ
設定内容

<message>－<ejb-transaction-timeout>タグ
<entity>－<ejb-transaction-timeout>タグ
<session>－<ejb-transaction-timeout>タグ
CMTの場合のトランザクションをタイムアウトする時間を指定します。

3.15.13　実行環境での設定

ここでは，フォールトトレランスのための機能を使用する場合の設定について説明します。

なお，次に示す機能については事前に設定する必要はありません。

コネクションプールの情報表示

コネクションプールのクリア

障害調査用SQLの出力

オブジェクトの自動クローズ

＜この項の構成＞

(1)　J2EEサーバの設定

(2)　リソースアダプタの設定

(3)　J2EEアプリケーションの設定

(1)　J2EEサーバの設定

J2EEサーバの設定は，簡易構築定義ファイルで実施します。フォールトトレランスの定義は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。

簡易構築定義ファイルでのフォールトトレランスのための機能の定義について，次の表に示します。

表3-65　簡易構築定義ファイルでのフォールトトレランスのための機能の定義

分類 | プロパティ | 設定内容
コネクションの自動クローズ | ejbserver.webj2ee.connectionAutoClose.enabled | Webアプリケーションでコネクションを自動クローズするかどうかを指定します。
トランザクションタイムアウト（J2EEサーバ単位）※1 | ejbserver.jta.TransactionManager.defaultTimeOut | J2EEサーバ上で開始されるトランザクションのタイムアウトのデフォルト値を指定します。
トランザクションのリカバリ | ejbserver.distributedtx.recovery.port | グローバルトランザクションを使用する場合に，トランザクションのリカバリで使用する固定ポート番号を指定します。
未決着トランザクションの確認時間のタイムアウト※2 | ejbserver.distributedtx.recovery.completionCheckOnStopping.timeout | J2EEサーバ停止時に行われるトランザクション仕掛かり完了確認のタイムアウト時間を指定します。

注※1　CMTの場合，Enterprise Bean，インタフェース，メソッド単位の設定もできます。Enterprise Bean，インタフェース，メソッド単位に設定する場合には，J2EEアプリケーションの設定時にサーバ管理コマンドを使用して属性ファイルに設定します。J2EEアプリケーションの設定については，「3.15.12　cosminexus.xmlでの定義」を参照してください。

注※2　アプリケーション開発時にタイムアウトを設定してください。J2EEアプリケーション運用時には，トランザクションの信頼性を保証するために，タイムアウトを設定しないことをお勧めします。

(2)　リソースアダプタの設定

実行環境でのリソースアダプタの設定は，サーバ管理コマンドおよび属性ファイルを使用します。フォールトトレランスのための機能の定義には，Connector属性ファイルを使用します。

Connector属性ファイルでのフォールトトレランスのための機能の定義について次の表に示します。

表3-66　Connector属性ファイルでのフォールトトレランスのための機能の定義

項目
指定するパラメタ
設定内容

コネクションの障害検知
<property>タグのValidationTypeおよびValidationInterval
コネクションの障害を検知するタイミングおよび障害を検知する間隔を指定します。
なお，コネクションの障害検知にタイムアウトを設定する場合には，NetworkFailureTimeoutでコネクション管理スレッドの使用を有効にします。※

コネクション管理スレッド
<property>タグのNetworkFailureTimeout
コネクション管理スレッドを使用するかどうかを指定します。
コネクション管理スレッドを使用する場合，コネクションの障害検知機能，およびコネクション数調節機能のタイムアウトを使用する設定になります。07-60より前のバージョンでは5秒で固定です。08-00以降のバージョンでは任意の時間を指定できます（デフォルト値は5秒）。

コネクション枯渇時のコネクション取得待ち
<property>タグのRequestQueueEnable
コネクション枯渇時のコネクション取得待ちを有効にするかどうかを指定します。

<property>タグのRequestQueueTimeout
コネクション取得の待ち時間を指定します。

コネクションの取得リトライ
<property>タグのRetryCount
コネクション取得に失敗した場合のリトライ回数を指定します。

<property>タグのRetryInterval
コネクション取得に失敗した場合のリトライ間隔を指定します。

コネクションスイーパ
<property>タグのSweeperIntervalで
コネクションの自動破棄（コネクションスイーパ）が動作する間隔を指定し，

<property>タグのConnectionTimeout
コネクションの最終利用時刻からコネクションを自動破棄するかどうかを判定するまでの時間を指定します。

ステートメントキャンセル
<config-property>タグのCancelStatement
トランザクションタイムアウト発生時のステートメントキャンセルを有効にするかどうかを指定します。

注※　コネクションの障害検知機能とコネクション数調節機能のタイムアウトを同じキーで設定します。このため，コネクションの障害検知機能でタイムアウトを使用する場合は，コネクション数調節機能でもタイムアウトを使用する設定となります。

(3)　J2EEアプリケーションの設定

実行環境でのJ2EEアプリケーションの設定は，サーバ管理コマンドおよび属性ファイルで実施します。パフォーマンスチューニングのための機能の定義には，Session Bean属性ファイル，Entity Bean属性ファイルまたはMessage-driven Bean属性ファイルを使用します。

これらの属性ファイルで指定するタグは，cosminexus.xmlと対応しています。cosminexus.xmlでの定義については，「3.15.12　cosminexus.xmlでの定義」を参照してください。

3.16　そのほかのリソースアダプタの機能（Connector 1.5仕様に準拠するリソースアダプタの場合）

この節では，「3.14　パフォーマンスチューニングのための機能」，「3.15　フォールトトレランスのための機能」，および「3.17　コネクションプールのクラスタ化機能」で説明する機能以外のリソースアダプタの機能について説明します。

この節の構成を次の表に示します。

表3-67　この節の構成（そのほかのリソースアダプタの機能（Connector 1.5仕様に準拠するリソースアダプタの場合））

分類 | タイトル | 参照先
解説 | リソースアダプタのライフサイクル管理 | 3.16.1
リソースアダプタのワーク管理 | 3.16.2
メッセージインフロー | 3.16.3
トランザクションインフロー | 3.16.4
管理対象オブジェクトのルックアップ | 3.16.5
コネクション定義の複数指定 | 3.16.6
実装 | アプリケーションサーバ独自のConnector 1.5 API仕様 | 3.16.7
設定 | Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定 | 3.16.8
属性ファイルの指定例 | 3.16.9
注意事項 | Connector 1.5仕様に準拠したリソースアダプタを使用する場合の注意事項 | 3.16.10

注　「運用」について，この機能固有の説明はありません。

これらの機能は，Connector 1.5仕様に準拠したリソースアダプタで使用できます。アプリケーションサーバで使用できるConnector 1.5仕様に準拠したリソースアダプタについては，「3.3.2(2)　Connector 1.5仕様に準拠したリソースアダプタ」を参照してください。

参考

Connector 1.5仕様に準拠したリソースアダプタなど，「3.3.2(1)　Connector 1.0仕様に準拠したリソースアダプタ」で示したリソースアダプタ以外のリソースアダプタを使用する場合には，リソースアダプタの処理の入り口と出口で，トレースを出力することをお勧めします。出力したトレースは，障害が発生したときの要因を切り分けるために使用します。

＜この節の構成＞

3.16.1　リソースアダプタのライフサイクル管理

3.16.2　リソースアダプタのワーク管理

3.16.3　メッセージインフロー

3.16.4　トランザクションインフロー

3.16.5　管理対象オブジェクトのルックアップ

3.16.6　コネクション定義の複数指定

3.16.7　アプリケーションサーバ独自のConnector 1.5 API仕様

3.16.8　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定

3.16.9　属性ファイルの指定例

3.16.10　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の注意事項

3.16.1　リソースアダプタのライフサイクル管理

Connector 1.5仕様に準拠したリソースアダプタを利用する場合，J2EEサーバによってリソースアダプタのライフサイクルを管理できます。

リソースアダプタのライフサイクル管理とは，リソースアダプタの開始処理と停止処理を，J2EEサーバで管理する機能です。

＜この項の構成＞

(1)　前提条件

(2)　ライフサイクル管理に使用するクラス

(3)　ライフサイクル管理の制御

(4)　ライフサイクル管理機能を使用するときの注意

(1)　前提条件

リソースアダプタのライフサイクル管理は，リソースアダプタが次の条件を満たす場合に有効になります。

リソースアダプタに，「(2)　ライフサイクル管理に使用するクラス」で示すクラスが実装されている。

DD（ra.xml）の<connector>-<resourceadapter>-<resourceadapter-class>に，javax.resource.spi.ResourceAdapterインタフェースを実装したJavaBeansのクラス名を指定している。

なお，DDの<connector>-<resourceadapter>-<resourceadapter-class>の指定が省略されている場合，リソースアダプタのライフサイクル管理は実行されません。

(2)　ライフサイクル管理に使用するクラス

リソースアダプタのライフサイクル管理に使用するクラスについて説明します。使用するクラスには，リソースアダプタでの実装が必要なクラスと，J2EEサーバが提供するクラスがあります。

●リソースアダプタで実装が必要なクラス

リソースアダプタでは，次のクラスの実装が必要です。なお，これらのクラスはJavaBeanとして実装することが，Connector 1.5仕様で規定されています。

javax.resource.spi.ResourceAdapterインタフェースの実装クラス

javax.resource.spi.ManagedConnectionFactoryインタフェースの実装クラス

AdminObject（管理対象オブジェクト）の実装クラス

詳細な実装については，Connector 1.5仕様を参照してください。

●J2EEサーバが提供するクラス

J2EEサーバは，次のクラスを提供します。

javax.resource.spi.work.WorkManagerインタフェースの実装クラス
このクラスには，doWork(Work)メソッド，scheduleWork(Work)メソッド，startWork(Work)メソッドなどが実装されています。

javax.resource.spi.BootstrapContextインタフェースの実装クラス
このクラスには，createTimer()メソッド，getWorkManager()メソッド，およびgetXATerminator()メソッドが実装されています。
なお，アプリケーションサーバでは，BootstrapContextインタフェースのgetXATerminatorメソッドを呼び出した場合，nullが返却されるように実装されています。

(3)　ライフサイクル管理の制御

ここでは，ライフサイクル管理の対象になる，リソースアダプタの開始処理と停止処理の制御について説明します。

リソースアダプタの開始処理および停止処理は，次のタイミングで実行されます。

J2EEリソースアダプタを開始または停止したとき（cjstartrarコマンドまたはcjstoprarコマンドを実行したとき）

J2EEサーバを起動または停止したとき（cjstartsvコマンドまたはcjstopsvコマンドを実行したとき）

リソースアダプタを含むアプリケーションを開始または停止したとき（cjstartappコマンドまたはcjstopappコマンドを実行したとき）

●リソースアダプタの開始処理を実行した場合の制御

リソースアダプタの開始処理を実行した場合の制御の流れを次の図に示します。

図3-38　リソースアダプタの開始処理を実行した場合の制御の流れ

リソースアダプタの開始処理によって実行される制御について説明します。なお，項番は図中の数字と対応しています。

WorkManager（javax.resource.spi.work.WorkManagerインタフェースの実装クラス）が生成されます。

BootstrapContext（javax.resource.spi.BootstrapContextインタフェースの実装クラス）が生成されます。

ResourceAdapterJavaBean（javax.resource.spi.ResourceAdapterインタフェースの実装クラス）が生成されます。
ResourceAdapterJavaBeanとして生成される実装クラスは，リソースアダプタのDD（ra.xml）の<connector>-<resourceadapter>-<resourceadapter-class>に指定したクラスです。
このタグで指定したクラスのインスタンス化に失敗した場合，リソースアダプタの開始が失敗します※。このとき，KDJE48589-Eのメッセージが出力されます。

ResourceAdapterJavaBeanにプロパティが設定されます。
DD（ra.xml）の<connector>-<resourceadapter>-<config-property>に指定した値は，3.で生成されたResourceAdapterJavaBeanに設定されます。設定は，JavaBeanの仕様に従い，setterメソッドで実行されます。setterメソッドの呼び出しで例外が発生した場合は，KDJE48594-Wのメッセージが出力されます。ただし，処理は継続されます。

javax.resource.spi.ResourceAdapterインタフェースのstartメソッドが呼び出され，リソースアダプタが開始されます。
このメソッドの呼び出しによって例外がスローされた場合は，リソースアダプタの開始が失敗します※。このとき，KDJE48590-Eのメッセージが出力されます。

ResourceAdapterJavaBeanとManagedConnectionFactoryJavaBeanが関連づけられます（Outboundの場合）。
ライフサイクル管理機能を使用する場合，javax.resource.spi.ManagedConnectionFactoryインタフェースの実装クラスはjavax.resource.spi.ResourceAdapterAssociationインタフェースを実装しています。ResourceAdapterJavaBeanとManagedConnectionFactoryの関連づけは，javax.resource.spi.ResourceAdapterAssociationインタフェースのsetResourceAdapter(ResourceAdapter)メソッドで実行されます。
また，次の場合には，リソースアダプタの開始が失敗します※。このとき，KDJE48591-Eが出力されます。

ManagedConnectionFactoryJavaBeanがjavax.resource.spi.ResourceAdapterAssociationインタフェースを実装していなかった場合

setResourceAdapterメソッドの呼び出しに対して例外がスローされた場合

AdminObjectJavaBean（管理対象オブジェクト）が生成され，プロパティが設定されます。
AdminObjectJavaBeanとして生成される実装クラスは，リソースアダプタのDD（ra.xml）の<connector>-<resourceadapter>-<adminobject>-<adminobject-class>に指定したクラスです。このタグで指定したクラスのインスタンス化に失敗した場合，リソースアダプタの開始が失敗します※。このとき，KDJE48597-Eのメッセージが出力されます。
また，DD（ra.xml）の<connector>-<resourceadapter>-<adminobject>-<config-property>で指定した値が，AdminObjectJavaBeanに設定されます。設定は，JavaBeanの仕様に従い，setterメソッドで実行されます。AdminObjectJavaBeanのsetterメソッドの呼び出しで例外が発生した場合は，KDJE48598-Wのメッセージが出力されます。ただし，処理は継続されます。

注※

アプリケーションに含まれるリソースアダプタの場合，リソースアダプタの開始が失敗したときには，そのリソースアダプタを含むアプリケーションの開始処理も失敗します。

●リソースアダプタの停止処理を実行した場合の制御

リソースアダプタの停止処理を実行した場合の制御を次の図に示します。

図3-39　リソースアダプタの停止処理を実行した場合の制御

リソースアダプタの停止処理によって実行される制御について説明します。なお，項番は図中の数字と対応しています。

停止するリソースアダプタを参照しているEJB，サーブレット，Message-driven Beanがすべて停止していることが確認されます。
次の要素が使用されていないことが確認されます。

Inboundリソースアダプタ

コネクションファクトリ

管理対象オブジェクト

これらが使用されていた場合は，リソースアダプタの停止処理が中止されます。

AdminObjectJavaBean（管理対象オブジェクト）が破棄されます。

javax.resource.spi.ResourceAdapterインタフェースのstopメソッドが呼び出され，リソースアダプタが停止します。
このメソッドの呼び出しによって例外がスローされた場合は，KDJE48590-Eのメッセージが出力されて，リソースアダプタの停止処理が失敗します。

ResourceAdapterJavaBeanが破棄されます。

●リソースアダプタの状態遷移

リソースアダプタは，リソースアダプタの開始処理または停止処理が実行されたタイミングで，「開始状態」または「停止状態」に遷移します。

リソースアダプタの状態遷移を次の図に示します。

図3-40　リソースアダプタの状態遷移

(4)　ライフサイクル管理機能を使用するときの注意

ライフサイクル管理機能を使用する場合は，次の点に注意してください。

J2EEサーバにデプロイされているリソースアダプタが複数ある場合，開始および停止処理が実行される順序は不定です。また，アプリケーションに含まれるリソースアダプタが複数ある場合，開始および停止処理が実行される順序は不定です。実行順序に依存する処理がある場合，動作は保証されません。

アプリケーションに含まれるリソースアダプタの場合，アプリケーション内に含まれるEJBやServletの開始処理よりも前に，リソースアダプタの開始処理が実行されます。また，アプリケーション内に含まれるEJBやServletの停止処理よりもあとで，リソースアダプタの停止処理が実行されます。

ResourceAdapter.stopの処理では，次に示す処理を適切に実行してください。

BootstrapContext.createTimerで生成したTimerの破棄(Timer#cancel)

WorkManagerに登録したWorkオブジェクトへの終了指示(Work#release)

3.16.2　リソースアダプタのワーク管理

Connector 1.5仕様に準拠したリソースアダプタを使用する場合，リソースアダプタが使用するスレッドをJ2EEサーバによって管理できます。

リソースアダプタのワーク管理とは，リソースアダプタがマルチスレッドで動作する場合に，スレッドを適切に使用するための機能です。J2EEサーバは，スレッドをプールに管理しておき，必要なリソースアダプタに割り当てます。

注意

ワーク管理の対象になるWorkを実行するスレッドは，J2EEアプリケーションの実行時間監視の対象にはなりません。

J2EEアプリケーションの実行時間監視については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 運用／監視／連携編」の「5.3　J2EEアプリケーションの実行時間の監視とキャンセル」を参照してください。

＜この項の構成＞

(1)　前提条件

(2)　ワーク管理に使用するクラス

(3)　ワーク管理の流れ

(4)　スレッドプーリング

(5)　ワーク管理の開始処理と終了処理

(6)　ワーク管理機能を使用するときの注意

(1)　前提条件

リソースアダプタのワーク管理機能は，リソースアダプタのライフサイクルが管理されている場合に使用できます。リソースアダプタのライフサイクル管理については，「3.16.1　リソースアダプタのライフサイクル管理」を参照してください。

(2)　ワーク管理に使用するクラス

リソースアダプタのワークを管理する場合に使用するクラスについて説明します。使用するクラスには，リソースアダプタでの実装が必要なクラスと，J2EEサーバが提供するクラスがあります。なお，J2EEサーバが提供するクラスは，ライフサイクル管理で使用するクラスと同じです。「3.16.1(2)　ライフサイクル管理に使用するクラス」を参照してください。

●リソースアダプタで実装が必要なクラス

リソースアダプタでは，次のクラスの実装が必要です。

javax.resource.spi.work.Workインタフェースの実装クラス
このクラスのrunメソッドには，実行する処理を実装しておく必要があります。

なお，ワークの登録，ワークのスレッドへの割り当て，およびワークの終了のタイミングをリソースアダプタで管理したい場合は，javax.resource.spi.work.WorkListenerインタフェースの実装クラスも実装してください。

(3)　ワーク管理の流れ

ここでは，ワーク管理の処理の流れについて説明します。

ワーク管理の概要を次の図に示します。

図3-41　ワーク管理の概要

図で示した流れについて説明します。

Workの登録
リソースアダプタは，Work（javax.resource.spi.work.Workインタフェースの実装クラス）を生成して，WorkManagerに登録します。
このとき，WorkManagerのインスタンスは，BootstrapContext経由でリソースアダプタに渡されます。WorkManagerについては，「3.16.1　リソースアダプタのライフサイクル管理」を参照してください。
また，Workの登録と同時に，WorkManagerにWorkListener（javax.resource.spi.work.WorkListener）も登録すると，以降，Workの登録が完了したとき（1.が実行されたとき），Workにスレッドが割り当てられたとき（2.が実行されたとき），およびWorkの処理が完了したとき（3.が実行されたとき）に，それぞれイベント(javax.resource.spi.work.WorkEventインタフェースの実装クラス)を取得できます。

空きスレッドへのワークの割り当て
J2EEサーバは，WorkManagerに登録されたWorkに対して，空きスレッドを割り当てて，Workで実装されているrunメソッドを実行します。

Workの終了とスレッドの回収
J2EEサーバは，処理が完了したWorkに割り当てたスレッドを，スレッドプールに回収します。
回収されたスレッドは，スレッドプーリングでの設定に従って，プールに戻って待機状態になるか，解放されます。

なお，この流れの中で，javax.resource.spi.work.Workインタフェースまたはjavax.resource.spi.work.WorkListenerインタフェースのメソッドで例外が発生した場合は，それぞれKDJE48592-EまたはKDJE48593-Eのメッセージが出力されます。

WorkManagerに登録されたWorkの状態遷移を，次の図に示します。

図3-42　Workの状態遷移

なお，WorkManagerにWorkを登録する時に使用するメソッドによって，メソッドがリターンするタイミングが異なります。それぞれのメソッドがリターンするタイミングを次の表および図に示します。なお，リターンするタイミング以外，これらのメソッドの処理に違いはありません。

表3-68　メソッドがリターンするタイミング

メソッド | リターンするタイミング
scheduleWork | Workを登録して，すぐにリターンします。
startWork | Workにスレッドが割り当てられたタイミングでリターンします。
doWork | Workの処理が完了したタイミングでリターンします。

図3-43　scheduleWorkメソッドがリターンするタイミング

図3-44　startWorkメソッドがリターンするタイミング

図3-45　doWorkメソッドがリターンするタイミング

(4)　スレッドプーリング

スレッドプーリングは，ワークに割り当てるスレッドを，スレッドプールで管理する機能です。

●スレッドプーリングの設定

スレッドプーリングの設定は，リソースアダプタをJ2EEサーバにインポートしたあとで，Connector属性ファイルの<hitachi-connector-property>-<resourceadapter-runtime>-<property>タグに指定して，リソースアダプタごとのプロパティとして設定します。設定手順については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「5.4　リソースアダプタのプロパティ定義」を参照してください。

スレッドプールに設定できる値を次の表に示します。

表3-69　スレッドプールに設定できる値

設定できる値（プロパティ名）
説明

同時に実行される最大のスレッド数（MaxTPoolSize）
WorkManagerで同時に実行される最大のスレッド数を設定します。
Workが登録されたときに空きスレッドがない場合，WorkManagerで実行中のスレッドの数がこの値未満であれば，新規にスレッドが生成されて，Workに割り当てられます。
実行中のスレッドの数がこの値以上のときには，Workの受け付けは拒否されて，javax.resource.spi.work.WorkRejectedExceptionがスローされます。

スレッドプールの最小スレッド数（MinTPoolSize）
スレッドプールにプールする最小スレッド数を設定します。
WorkManagerにWorkがまったく登録されていない場合でも，この値分のスレッドは常にプールされます。
また，この値に0を指定した場合は，Workが登録されるまで，スレッドは生成されません。

Workが割り当たっていないスレッドが解放されるまでの最大生存期間［単位：秒］（TPoolKeepalive）
Workが割り当てられていないスレッドが，スレッドプールから解放されるまでの期間を秒単位で設定します。
空きスレッドになってからTPoolKeepalive秒経過してもWorkが割り当てられなかった場合，そのスレッドは解放されます。
ただし，スレッドプールに存在するスレッド数がMinTPoolSizeの値分しかない場合は，解放されません。

指定方法および指定できる値の詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1　Connector属性ファイル」を参照してください。

なお，ライフサイクル管理機能が有効でない場合（リソースアダプタのDD（ra.xml）に<resourceadapter-class>が指定されていない場合），スレッドプーリングを設定するプロパティの値は無視されます。

●ワーク管理で使用するスレッドのライフサイクル

ワーク管理機能で使用するスレッドのライフサイクルを次に図に示します。

スレッドのライフサイクルは，スレッドプールと実行中スレッドの状態によって異なります。

図3-46　スレッドのライフサイクル（スレッドプールに空きスレッドがなく，実行中のスレッド数がMaxTPoolSize未満の場合）

図3-47　スレッドのライフサイクル（スレッドプールに空きスレッドがある場合）

図3-48　スレッドのライフサイクル（スレッドプールに空きスレッドがなく，実行中のスレッド数がMaxTPoolSizeに達している場合）

スレッドが生成されるのは，リソースアダプタによってscheduleWorkメソッド，startWorkメソッドまたはdoWorkメソッドが呼び出された場合に，次の状態の両方に当てはまるときです。

スレッドプールに空きスレッドがない。

WorkManagerで実行中のスレッド数がMaxTPoolSize未満である。

スレッドは，Workの処理が完了するとスレッドプールで実行待ち状態になります。次のWorkが登録されると，再度実行状態になります。

スレッドプール内で，TPoolKeepaliveで指定した秒数が経過してもWorkが割り当てられなかった場合，スレッドは解放されます。ただし，そのスレッドを解放することでスレッドプール内のスレッド数がMinTPoolSize未満になる場合は，解放されません。

●Message-driven Beanのインスタンスプールとスレッドプーリングとの関係

リソースアダプタがWorkを使用してMessage-driven Beanを呼び出す場合の動作は，Message-driven Beanのインスタンスプールの最大数と，リソースアダプタのMaxTPoolSizeの関係によって異なります。

Message-driven Beanのインスタンスプールの最大数とリソースアダプタのMaxTPoolSizeの関係ごとの動作を次の表に示します。これは，一つのリソースアダプタから一つのMessage-driven Beanを呼び出す場合の動作です。

表3-70　リソースアダプタがWorkによってMessage-driven Beanを呼び出すときの動作

Message-driven Beanのインスタンスプールの最大数とリソースアダプタのMaxTPoolSizeの関係
動作

MaxTPoolSize>Message-driven Beanのインスタンスプールの最大数
Message-driven Beanのインスタンスプールの最大数に達するまで，WorkからMessage-driven Beanを実行できます。
Message-driven Beanのインスタンスプールの最大数を超える数のWorkは，Message-driven Beanのインスタンスの取得待ちの状態になります。

MaxTPoolSize=Message-driven Beanのインスタンスプールの最大数
Message-driven Beanのインスタンスプールの最大数に達するまで，WorkからMessage-driven Beanを実行できます。
Message-driven Beanのインスタンスプールの最大数を超える数のWorkに対しては，javax.resource.spi.work.WorkRejectedException例外がスローされます。インスタンスの取得待ちにはなりません。

MaxTPoolSize<Message-driven Beanのインスタンスプールの最大数
同時に使用できるMessage-driven Beanのインスタンス数は，MaxTPoolSizeの数になります。実行中のWorkの数がMaxTPoolSizeに達するまで，WorkからMessage-driven Beanを実行できます。
MaxTPoolSizeを超える数のWorkに対しては，javax.resource.spi.work.WorkRejectedException例外がスローされます。実行待ちにはなりません。

ポイント

ワーク管理機能のスレッドプーリングはリソースアダプタ単位に設定します。一方，Message-driven BeanのインスタンスプールはMessage-driven Bean単位に設定します。

リソースアダプタが複数のMessage-driven Beanを呼び出す場合，リソースアダプタのMaxTPoolSizeには，それぞれのMessage-driven Beanで必要なスレッド数を考慮して，合計した値を設定してください。

(5)　ワーク管理の開始処理と終了処理

ワーク管理の開始処理および終了処理は，ライフサイクル管理機能の開始処理および終了処理のタイミングで実行されます。

それぞれの処理で実行されることを次に示します。

●開始処理

ワーク管理の開始処理では，スレッドプーリングの設定に応じて，スレッドの生成が実行されます。MinTPoolSizeが1以上に設定されている場合は，MinTPoolSize分のスレッドが生成されて，空きスレッドとしてスレッドプールに格納されます。

●終了処理

終了処理で実行される内容は，正常終了の場合と，異常終了または強制終了の場合とで一部異なります。なお，異常終了とは，ResourceAdapterインタフェースのstopメソッド実行時に例外がスローされる場合のことです。また，強制終了とは，cjstopapp -forceコマンドまたはcjstopapp -cancelコマンド実行の延長で実行される終了処理のことです。

参考

cjstopsv -fコマンドを実行した場合は，リソースアダプタの終了処理が実行されないでJ2EEサーバが停止されます。このため，ここで説明する処理は実行されません。

J2EEサーバからResourceAdapterインタフェースのstopメソッドが呼び出され，リソースアダプタに対して，停止処理が指示されます。
また，この処理の延長でWorkのreleaseメソッドが呼び出されて，Workが解放されます。

リソースアダプタによって，新規のWorkの受け付けが停止されます。
1.の処理を実行したあとなので，通常，Workの登録要求はありません。Workの登録要求があった場合，例外として，javax.resource.spi.work.WorkRejectedExceptionがスローされます。

Workの処理完了が待機されます。
実行中のWorkのrunメソッドの実行がすべて完了するまで待機されます。

ポイント

Workから呼び出しているMessage-driven Beanに対してメソッドキャンセルが実行されると，Message-driven Beanは強制終了します。ただし，その場合，実行中のWorkの処理は停止されません。

WorkからMessage-driven Beanを呼び出している場合，リソースアダプタよりも先にMessage-driven Beanが終了します。Message-driven Bean停止後にWorkからMessage-driven Beanを呼び出したり，javax.resource.spi.endpoint.MessageEndpointFactoryのcreateEndpointメソッドを呼び出したりすると，例外がスローされます。
詳細は，「3.16.3　メッセージインフロー」を参照してください。

(6)　ワーク管理機能を使用するときの注意

WorkおよびWorkListenerのメソッド内では，J2EEサーバの機能として，メッセージインフロー規約に基づくMessage-driven Beanの呼び出しだけが使用できます。

WorkおよびWorkListenerのメソッドは，スレッドセーフにしてください。

WorkListenerのメソッドには，実行スレッドに依存した処理を実装しないでください。実行スレッドに依存した処理がある場合，動作は保証されません。

3.16.3　メッセージインフロー

メッセージインフローは，リソースアダプタとMessage-driven Bean間の規約です。Connector 1.5仕様のリソースアダプタは，EISなどのメッセージプロバイダからのメッセージを受け付けて，アプリケーションサーバ上のメッセージエンドポイント（Message-driven Bean）を動作させることができます。メッセージエンドポイントでは，メッセージプロバイダから送信されたメッセージを，非同期に処理します。

アプリケーションサーバでは，メッセージの配信方法として，次の2種類の方法を使用できます。

Non-Transacted Delivery

Transacted Delivery

これらは，呼び出し元のEISがトランザクションに参加するかどうかが異なります。

＜この項の構成＞

(1)　前提条件

(2)　メッセージインフローの制御の流れ（Non-Transacted Deliveryの場合）

(3)　メッセージインフローの制御の流れ（Transacted Deliveryの場合）

(4)　メッセージエンドポイントのデプロイとアンデプロイ

(1)　前提条件

メッセージインフローは，リソースアダプタおよびMessage-driven Beanが次の条件を満たす場合に有効になります。

メッセージインフローで呼び出されるMessage-driven Beanは，EJB 2.1以降に準拠している必要があります。
EJB 2.1以降では，Message-driven Beanはjavax.jms.MessageListenerだけではなく，任意のメッセージリスナを実装できます。メッセージリスナは，リソースアダプタとMessage-driven Bean間のメッセージ配送に使用するリスナです。リソースアダプタがサポートしているメッセージリスナをMessage-driven Beanに実装することで，汎用的なメッセージ受信を実現できます。
EJB 2.0のMessage-driven Beanでメッセージインフローを実行しようとした場合，アプリケーション開始時にエラーになり，開始に失敗します。この場合は，KDJE42088-Eのメッセージが出力されます。

メッセージインフローを実行する場合，リソースアダプタおよびMessage-driven Beanの属性として，次の設定が必要です。

管理対象オブジェクトに設定する情報（リソースアダプタ）

Message-driven Beanとリソースアダプタの対応づけ（Message-driven Beanおよびリソースアダプタ）

ActivationSpecに設定する情報（Message-driven Bean）

Message-driven Beanが使用するインタフェース（Message-driven Beanおよびリソースアダプタ）

メッセージインフローの処理を実行する場合のリソースアダプタとJ2EEアプリケーションの設定については，「3.16.8　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定」を参照してください。

また，Transacted Deliveryは，次の表に示す条件を満たす場合に有効になります。

表3-71　Transacted Deliveryが有効になる条件

J2EEサーバの設定 | Message-driven Beanの設定
トランザクション管理種別<transaction-type>がContainer | トランザクション管理種別<transaction-type>がBean
トランザクション属性<trans-attribute>がRequired | トランザクション属性<trans-attribute>がNotSupported
ejbserver.distributedtx.XATransaction.enabled | true | ○ | × | ×
false | △ | × | ×

（凡例）

○：メッセージを配信するEISをグローバルトランザクションに含めてトランザクションを開始する。

△：メッセージを配信するEISをトランザクションに含めないでローカルトランザクションを開始する。

×：トランザクションを開始しない。

また，Transacted Deliveryを使用する場合は，Connector 1.5仕様に準拠し，Transacted Deliveryに対応したリソースアダプタを使用する必要があります。設定の詳細については，ご使用のリソースアダプタのドキュメントを参照してください。

(2)　メッセージインフローの制御の流れ（Non-Transacted Deliveryの場合）

Non-Transacted Deliveryとは，メッセージを配信するEISがトランザクションに参加しないメッセージ配信です。

Non-Transacted Deliveryでメッセージインフローを使用する場合の制御の流れを次の図に示します。

図3-49　Non-Transacted Deliveryでメッセージインフローを使用する場合の制御の流れ

Non-Transacted Deliveryでメッセージインフローを使用した場合に実行される制御について説明します。なお，項番は図中の数字と対応しています。

アプリケーションの開始処理によって，リソースアダプタのActivationSpecJavaBeanにプロパティが設定されます。
Message-driven Beanの属性の<activation-config>に指定した内容が設定されます。

J2EEサーバからendpointActivationメソッドが呼び出されます。これによって，リソースアダプタにメッセージエンドポイントの開始が通知されます。

EISからメッセージが送信されます。

リソースアダプタからMessageEndpointFactoryに対して，createEndpointメッセージが呼び出されます。

MessageEndpointFactoryがエンドポイントのプロキシを生成します。

リソースアダプタからエンドポイントのプロキシに対して，onMessageメソッドなどのメッセージリスナのメソッドが呼び出されます。

エンドポイントのプロキシからMessage-driven Beanに対して，onMessageメソッドなどのメッセージリスナのメソッドが呼び出されます。

処理が完了したら，J2EEサーバからendpointDeactivationメソッドが呼び出されます。これによって，リソースアダプタにメッセージエンドポイントの停止が通知されます。

(3)　メッセージインフローの制御の流れ（Transacted Deliveryの場合）

Transacted Deliveryとは，メッセージを配信するEISがトランザクションに参加するメッセージ配信です。

Transacted Deliveryでメッセージインフローを使用する場合の制御の流れを次の図に示します。

図3-50　Transacted Deliveryでメッセージインフローを使用する場合の制御の流れ

Transacted Deliveryでメッセージインフローを使用した場合に実行される制御について説明します。なお，項番は図中の数字と対応しています。

アプリケーションの開始処理によって，リソースアダプタのActivationSpecJavaBeanにプロパティが設定されます。
Message-driven Beanの属性の<activation-config>に指定した内容が設定されます。

J2EEサーバからendpointActivationメソッドが呼び出されます。これによって，リソースアダプタにメッセージエンドポイントの開始が通知されます。

EISからメッセージが送信されます。

リソースアダプタからMessageEndpointFactoryに対して，createEndpointメッセージが呼び出されます。

MessageEndpointFactoryがエンドポイントのプロキシを生成します。

リソースアダプタからエンドポイントのプロキシに対して，onMessageメソッドなどのメッセージリスナのメソッドが呼び出されます。

呼び出されたエンドポイントのプロキシからトランザクションマネージャに対して，トランザクションの開始指示が呼び出されます。

トランザクションマネージャによってstartメソッドが呼び出され，トランザクションが開始されます。

エンドポイントのプロキシからMessage-driven Beanに対して，onMessageメソッドなどのメッセージリスナのメソッドが呼び出されます。

エンドポイントのプロキシからトランザクションマネージャに対して，トランザクションの決着が指示されます。

トランザクションマネージャによってprepareメソッド，commitメソッドなどのトランザクション決着メソッドが呼び出され，トランザクションが決着します。

処理が完了したら，J2EEサーバからendpointDeactivationメソッドが呼び出されます。これによって，リソースアダプタにメッセージエンドポイントの停止が通知されます。

(4)　メッセージエンドポイントのデプロイとアンデプロイ

ここでは，メッセージエンドポイントのデプロイとアンデプロイで実行される処理について説明します。

●メッセージエンドポイントのデプロイ

メッセージエンドポイントのデプロイ時に実行される処理について説明します。メッセージエンドポイントのデプロイは，リソースアダプタが開始済みの状態で，Message-driven Beanを含むアプリケーションを開始したときに実行されます。

メッセージエンドポイントのデプロイ時の処理を次の図に示します。

図3-51　メッセージエンドポイントのデプロイ時の処理

メッセージエンドポイントのデプロイで実行される処理について説明します。項番は図中の番号に対応しています。

リソースアダプタが開始済みの状態で，Message-driven Beanを含むJ2EEアプリケーションを開始します。

J2EEサーバが，MessageEndpointFactoryを生成します。
MessageEndpointFactoryは，J2EEサーバが提供するjavax.resource.spi.endpoint.MessageEndpointFactoryのインスタンスです。javax.resource.spi.endpoint.MessageEndpointFactoryはリソースアダプタにエンドポイントのインスタンスを提供するファクトリクラスです。

J2EEサーバが，ActivationSpecを生成します。
ActivationSpecは，Message-driven Bean（エンドポイント）の開始に必要な情報を設定するJavaBeanです。

J2EEサーバが，ActivationSpecのプロパティを設定します。
ActivationSpecのプロパティに設定する情報は，Message-driven Beanを含むアプリケーションの属性として設定した情報です。

J2EEサーバが，javax.resource.spi.ResourceAdapter#endpointActivation(MessageEndpointFactory, ActivationSpec)メソッドを呼び出します。
このとき，引数として，生成・設定したMessageEndpointFactoryとActivationSpecのインスタンスが指定されます。なお，endpointActivationメソッドの呼び出しで例外が発生した場合は，KDJE43174-Eのメッセージが出力され，アプリケーションの開始が中止されます。

リソースアダプタは，5.のメソッドが呼び出されると，メッセージプロバイダからのメッセージ受信に対する準備をします。

●メッセージエンドポイントのアンデプロイ

メッセージエンドポイントのアンデプロイ時に実行される処理について説明します。メッセージエンドポイントのアンデプロイは，Message-driven Beanを含むアプリケーションを停止したときに実行されます。

メッセージエンドポイントのアンデプロイ時の処理を次の図に示します。

図3-52　メッセージエンドポイントのアンデプロイ時の処理

メッセージエンドポイントのアンデプロイで実行される処理について説明します。項番は図中の番号に対応しています。

Message-driven Beanを含むJ2EEアプリケーションを停止します。

J2EEサーバが，javax.resource.spi.ResourceAdapter#endpointDeactivation(MessageEndpointFactory, ActivationSpec)を呼び出します。
このとき，引数として，デプロイ時に指定したMessageEndpointFactoryとActivationSpecと同じインスタンスが指定されます。なお，このメソッドの呼び出しで例外が発生した場合，メッセージKDJE43175-Wが出力されます。ただし，例外が発生した場合も，アプリケーションの停止処理は続行されます。

リソースアダプタは，2.のメソッドが呼び出されると，メッセージプロバイダからのメッセージ受信終了の処理をします。

●メッセージ配送をするときのリソースアダプタの処理

ここでは，メッセージ配送をするときのリソースアダプタの処理について説明します。

リソースアダプタからのメッセージエンドポイント（Message-driven Bean）の呼び出しは，メッセージエンドポイントのプロキシを使用して実行されます。このプロキシは，リソースアダプタからjavax.resource.spi.endpoint.MessageEndpointFactoryのcreateEndpointメソッドを呼び出すことで得られます。

注意

アプリケーションの停止後にMessageEndpointFactoryのメソッドを呼び出すと，javax.resource.spi.UnavailableException例外がスローされます。このとき，メッセージKDJE43177-Eが出力されます。また，メッセージエンドポイントのメソッドを呼び出した場合は，java.lang.IllegalStateException例外がスローされます。このとき，メッセージKDJE43177-Eが出力されます。

3.16.4　トランザクションインフロー

トランザクションインフローとは，アプリケーションサーバ上のメッセージエンドポイント（Message-driven Bean）をメッセージプロバイダのトランザクションに参加させる際のリソースアダプタとアプリケーションサーバ間の規約です。

メッセージエンドポイント（Message-driven Bean）は，メッセージプロバイダのトランザクション識別子に関連づけられトランザクションに参加します。

なお，トランザクションインフローは，TP1インバウンド連携機能でだけ使用できます。

トランザクションインフローの制御の流れを次に示します。

図3-53　トランザクションインフローの制御の流れ

図中の処理の流れについて説明します。なお，項番は図中の数字と対応しています。

EISからTP1インバウンドアダプタへメッセージが送信されます。

TP1インバウンドアダプタは，トランザクションマネージャへEISのトランザクション識別子を伝播します。

TP1インバウンドアダプタがMessage-driven Beanを実行します。

Message-driven Beanから，SQLを実行してDBを更新します。

Message-driven Bean実行後，TP1インバウンドアダプタからEISへ実行結果が送信されます。

実行結果を受けて，EISがTP1インバウンドアダプタへトランザクションの決着指示を送信します。

TP1インバウンドアダプタから，トランザクションマネージャへトランザクション決着指示が送信されます。

トランザクションが決着します。

3.16.5　管理対象オブジェクトのルックアップ

管理対象オブジェクト（AdminObject）をルックアップによって取得できます。管理対象オブジェクトは，J2EEアプリケーションの中からメッセージを送信したり，同期受信したりする場合に，メッセージの送信先の情報を得るために必要です。管理対象オブジェクトをルックアップするためには，リソースアダプタとJ2EEアプリケーションの設定が必要です。ここでは，設定の概要について説明します。

参考

管理対象オブジェクトの仕様は，リソースアダプタの仕様に依存します。詳細は，使用するリソースアダプタの仕様に従ってください。

＜この項の構成＞

(1)　ルックアップの対象にする管理対象オブジェクトの設定

(2)　J2EEアプリケーションの設定

(1)　ルックアップの対象にする管理対象オブジェクトの設定

ルックアップの対象にする管理対象オブジェクトの情報は，リソースアダプタのプロパティとして設定します。リソースアダプタのプロパティは，Connector属性ファイルで設定します。

管理対象オブジェクトをルックアップの対象にする場合は，<adminobject-name>タグに管理対象オブジェクト名を必ず指定してください。管理対象オブジェクト名は，管理対象オブジェクトがリソースアダプタごとに複数定義された場合に，管理対象オブジェクトを一意に識別するために使用されます。

設定項目については，「3.16.8　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定」を参照してください。

(2)　J2EEアプリケーションの設定

管理対象オブジェクトをルックアップするJ2EEアプリケーションの設定は，属性ファイルまたはアノテーションで設定できます。

(a)　属性ファイルを使用する場合

<resource-env-ref>タグ下の次の要素を設定します。

<resource-env-ref-name>タグ下にルックアップで使用する名称を指定します。<resource-env-ref-type>タグ下に参照する管理対象オブジェクトの型を指定します。<linked-adminobject>タグ下にリソースアダプタの管理対象オブジェクトの名前，リソースアダプタの表示名を指定します。

注意

EJB 2.1以降で管理対象オブジェクトを参照するための要素として規定されている<message-destination-ref>タグは，アプリケーションサーバでは使用できません。

設定については，「3.16.8　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定」を参照してください。

(b)　アノテーションを使用する場合

@ResourceのmappedName属性に，ルックアップする管理対象オブジェクト名を指定します。次の形式で指定します。リソースアダプタの表示名と管理対象オブジェクト名を区切る区切り文字には「!#」を使用します。

@Resource(mappedName="リソースアダプタの表示名!#管理対象オブジェクト名")

3.16.6　コネクション定義の複数指定

Connector 1.5仕様に準拠したリソースアダプタを使用する場合，一つのリソースアダプタに対して複数のコネクション定義を指定できます。コネクションプールやログ出力などについての設定は，コネクション定義ごとに設定できます。

リソースアダプタ内のコネクション定義の識別には，コネクション定義識別子を使用します。コネクション識別子は，DD内の<connectionfactory-interface>の指定値です。<connectionfactory-interface>の値は，リソースアダプタ内のコネクション定義ごとに一意の値を持っています。

なお，リソースアダプタに含まれるコネクション定義ごとのコネクション定義識別子については，次のサーバ管理コマンドに-outboundオプションを指定して実行すると確認できます。

cjlistappコマンド（アプリケーションに含まれるRARファイルの場合）
詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjlistapp（アプリケーションの一覧表示）」を参照してください。

cjlistresコマンド
詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjlistres（リソースの一覧表示）」を参照してください。

cjlistrarコマンド
詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjlistrar（リソースアダプタの一覧表示）」を参照してください。

ここでは，コネクション定義に指定できる要素と指定個所について説明します。また，コネクション定義を複数指定する場合に留意することについて説明します。

＜この項の構成＞

(1)　コネクション定義に指定できる要素と指定個所

(2)　コネクションプールを使用する場合の留意事項

(3)　トランザクションリカバリをする場合の留意事項

(4)　リソースへの接続テストをする場合の留意事項

(5)　稼働情報およびリソース枯渇監視情報を出力する場合の留意事項

(6)　リソースアダプタの稼働ログを出力する場合の留意事項

(1)　コネクション定義に指定できる要素と指定個所

ここでは，コネクション定義に指定できる要素と指定個所について説明します。

●DDでの指定個所とコネクション定義に指定できる要素

コネクション定義は，Connector 1.5仕様に対応したDDの，<connection-definition>下に指定します。<connection-definition>の下に指定する要素を次に示します。

<managedconnectionfactory-class>

<config-property>

<connectionfactory-interface>

<connectionfactory-impl-class>

<connection-interface>

<connection-impl-class>

●Connector属性ファイルの階層構造とコネクション定義の対応

DD（ra.xml）の階層構造の変更に合わせて，属性ファイルにもコネクション定義に対応する階層が追加されます。

J2EEサーバにインポート済みのリソースアダプタの場合，リソースアダプタのプロパティの変更には，Connector属性ファイルを使用します。Connector属性ファイルに定義した値は，サーバ管理コマンドを使用してJ2EEサーバ上のリソースアダプタに反映します。属性ファイルによるプロパティの設定手順については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「3.3　属性ファイルによるプロパティの設定」を参照してください。

なお，リソースアダプタの動作に関連するプロパティには，コネクション定義ごとに定義する項目と，リソースアダプタ全体に定義する項目があります。コネクション定義ごとに指定する項目については，Connector属性ファイルの<outbound-resourceadapter>-<connection-definition>下に指定します。リソースアダプタ全体に対して指定する項目については，<resourceadapter-runtime>-<property>下に指定します。

指定方法の詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1.1　Connector属性ファイルの指定内容」を参照してください。

●J2EEアプリケーションでのリンク解決の定義方法（<resource-ref>-<linked-to>，<cmp-map>-<datasource-name>またはmappedNameでの指定方法）

Connector 1.5仕様に準拠したリソースアダプタを参照するJ2EEアプリケーションでは，リンク解決のために，J2EEアプリケーションがどのコネクション定義を参照するかを定義する必要があります。

定義は，次のどれかの方法で指定します。

J2EEアプリケーションの属性ファイル（WAR属性ファイル，Session Bean属性ファイル，Entity Bean属性ファイルまたはMessageDrivenBean属性ファイル）の<resource-ref>-<linked-to>

J2EEアプリケーションの属性ファイル（Entity Bean属性ファイル）の<cmp-map>-<datasource-name>

アノテーション@ResourceのmappedName属性

注意

参照先のリソースがConnector 1.5仕様に準拠したリソースアダプタの場合は，必ずコネクション定義識別子を指定してください。指定を省略した場合，リンク解決に失敗します。また，参照先のリソースがConnector 1.0仕様に準拠したリソースアダプタの場合は，コネクション定義識別子を指定しないでください。指定した場合，リンク解決に失敗します。

コネクション定義識別子を含む参照先のリソースは，次の形式で指定します。

<リソースアダプタの表示名>!<コネクション定義識別子>

指定内容について説明します。

<リソースアダプタの表示名>

参照先のリソースアダプタのDD（ra.xml）の<connector>-<display-name>要素の値です。

<コネクション定義識別子>

参照先のリソースアダプタのDD（ra.xml）の<connector>-<resourceadapter>-<outbound-resourceadapter>-<connection-definition>-<connectionfactory-interface>要素の値です。

なお，リソースアダプタの表示名およびコネクション定義識別子は，次のサーバ管理コマンドでも確認できます。

cjlistappコマンド（アプリケーションに含まれるRARファイルの場合）

cjlistresコマンド

cjlistrarコマンド

(2)　コネクションプールを使用する場合の留意事項

複数のコネクション定義が指定されているリソースアダプタでは，コネクションプールをコネクション定義単位で管理できます。コネクションプールについての定義は，Connector属性ファイルの<outbound-resourceadapter>-<connection-definition>-<connector-runtime>-<property>下の要素で指定して設定してください。

次に，コネクションプールが複数になる場合の留意事項について説明します。

●コネクションプールを対象にしたコマンドの実行

コネクションプールを対象にしたサーバ管理コマンドを実行するときには，どのコネクションプールを対象にするかを指定する必要があります。

次のコマンドを実行する場合には，コネクション定義識別子の指定が必要です。コネクション定義識別子は，これらのコマンドのオプションで指定します。

cjclearpoolコマンド
詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjclearpool（コネクションプール内のコネクション削除）」を参照してください。

cjlistpoolコマンド
詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjlistpool（コネクションプールの一覧表示）」を参照してください。

参考

コネクションプールのクラスタ化で使用するコマンドについては，対象になりません。コネクションプールのクラスタ化で使用するコマンドは，アプリケーションサーバが提供しているリソースアダプタだけで実行できます。

●コネクションプールのウォーミングアップ処理

コネクションプールのウォーミングアップ処理は，コネクション定義ごとに実行されます。

コネクションプールのウォーミングアップ処理が実行される場合に，特定のコネクション定義に対応するコネクションプールのウォーミングアップに失敗しても，それ以外のコネクションプールに対するウォーミングアップ処理は継続されます。

(3)　トランザクションリカバリをする場合の留意事項

トランザクションリカバリは，コネクション定義ごとに実行されます。このため，コネクション定義を複数指定した場合，OTSにはコネクション定義ごとにリソースが登録されます。

(4)　リソースへの接続テストをする場合の留意事項

リソースアダプタの接続テストを実行する場合，特定のコネクション定義に対する接続テストでエラーが発生した場合も，処理は中止されません。すべてのコネクション定義に対して接続テストが実行されます。ただし，どれかのコネクション定義でエラーが発生した場合，コマンドの戻り値は異常終了を示す戻り値になります。

(5)　稼働情報およびリソース枯渇監視情報を出力する場合の留意事項

コネクション定義が複数指定されている場合，稼働情報およびリソース枯渇監視情報は次のように出力されます。

稼働情報（稼働情報ファイルに出力される情報）

一つ目のコネクション定義についての情報だけが出力されます。一つ目のコネクション定義とは，DD（ra.xml）で最初に定義されているコネクション定義です。

稼働情報（運用管理コマンドを使用して出力する情報）

出力できません。Connector 1.5仕様に準拠したリソースアダプタについての稼働情報を出力しようとした場合，出力内容は保証されません。

リソース枯渇監視情報

リソースアダプタに指定されているすべてのコネクション定義の情報が出力されます。

(6)　リソースアダプタの稼働ログを出力する場合の留意事項

Connector 1.5仕様に準拠したリソースアダプタの稼働ログを出力する場合，出力ファイルのファイル名は，次の形式になります。

<リソースアダプタの表示名>_<コネクション定義の並び順>_<ログファイルの通番>.log

<コネクション定義の並び順>は，DD（ra.xml）内で，対応する<connection-definition>が出現した順番（1，2，...）に対応します。

3.16.7　アプリケーションサーバ独自のConnector 1.5 API仕様

ここでは，Connector 1.5で仕様のインタフェースに対して，アプリケーションサーバ独自で規定した仕様について説明します。

＜この項の構成＞

(1)　javax.resource.spi.endpoint.MessageEndpointFactoryインタフェース

(2)　javax.resource.spi.endpoint.MessageEndpointインタフェース

(3)　メッセージリスナのメソッド

(1)　javax.resource.spi.endpoint.MessageEndpointFactoryインタフェース

アプリケーションサーバでは，二つのメソッドの仕様を規定しています。

(a)　createEndpointメソッド

形式

public MessageEndpoint createEndpoint(XAResource xaResource) throws UnavailableException

アプリケーションサーバ独自の仕様

EJBを含むJ2EEアプリケーションの停止処理を開始したあとでこのメソッドが呼び出された場合は，javax.resource.spi.UnavailableExceptionがスローされます。

このメソッドの中でMessage-driven Beanのインタスタンス取得処理が実行されます。Message-driven Beanのインスタンスプールの上限に達していた場合は，Message-driven Beanのインスタンスを取得できるか，J2EEアプリケーションが停止するまで，メソッドがリターンされません。

例外

アプリケーションサーバで規定した例外の動作について示します。

例外
例外が発生するタイミング

javax.resource.spi.UnavailableException

EJBを含むJ2EEアプリケーションの停止処理を開始したあとでこのメソッドが呼び出した場合

Message-driven Beanのインスタンスの取得に失敗した場合

(b)　isDeliveryTransactedメソッド

形式

public boolean isDeliveryTransacted(Method method) throws NoSuchMethodException

アプリケーションサーバ独自の仕様

ejbserver.distributedtx.XATransaction.enabled=trueが指定されていて，引数で渡されたメソッドのトランザクション属性にCMTのRequiredが指定されている場合に，trueを返します。

(2)　javax.resource.spi.endpoint.MessageEndpointインタフェース

アプリケーションサーバでは，三つのメソッドの仕様を規定しています。

(a)　beforeDeliveryメソッド

形式

public void beforeDelivery(Method method) throws NoSuchMethodException, ResourceException

アプリケーションサーバ独自の仕様

例外について規定しています。

例外

アプリケーションサーバで規定した例外の動作について示します。

例外
例外が発生するタイミング

java.lang.IllegalStateException

EJBを含むJ2EEアプリケーションの停止処理を開始したあとでメッセージリスナのメソッドを呼び出した場合

release()メソッドがすでに呼び出されている場合

javax.resource.spi.IllegalStateException

不正な順序で呼び出した場合（beforeDeliveryメソッド呼び出し後に再度beforeDeliveryメソッドを呼び出した場合。またはメッセージリスナのメソッドの呼び出し後にbeforeDeliveryメソッドを呼び出した場合）

javax.resource.spi.UnavailableException

予期しない例外が発生した場合

(b)　afterDeliveryメソッド

形式

public void afterDelivery() throws ResourceException

アプリケーションサーバ独自の仕様

例外について規定しています。

例外

アプリケーションサーバで規定した例外の動作について示します。

例外
例外が発生するタイミング

java.lang.IllegalStateException

EJBを含むJ2EEアプリケーションの停止処理を開始したあとでメッセージリスナのメソッドを呼び出した場合

release()メソッドがすでに呼び出されている場合

javax.resource.spi.IllegalStateException

不正な順序で呼び出した場合（Option B※のメッセージリスナのメソッド呼び出し後以外のタイミングでafterDelivery()を呼び出した場合）

javax.resource.spi.UnavailableException

予期しない例外が発生した場合

注※　Connector 1.5仕様に記述されているメッセージ配送オプションです。

(c)　releaseメソッド

形式

public void release()

アプリケーションサーバ独自の仕様

このメソッドを呼び出すと，エンドポイントに対応づけられたMessage-driven Beanのインスタンスが解放され，インスタンスプールに戻ります。

エンドポイントを使用し終わったら，必ずこのメソッドを呼び出して，Message-driven Beanをインスタンスプールに戻すように実装してください。

例外

アプリケーションサーバで規定した例外の動作について示します。

例外
例外が発生するタイミング

java.lang.IllegalStateException

EJBを含むJ2EEアプリケーションの停止処理を開始したあとでメッセージリスナのメソッドを呼び出した場合

release()メソッドがすでに呼び出されている場合

(3)　メッセージリスナのメソッド

インタフェースはメッセージリスナのインタフェースで定義されます。ここでは，アプリケーションサーバで規定した例外の動作について示します。

例外
例外が発生するタイミング

メッセージリスナのインタフェースに指定された例外

Message-driven Beanの実行時（システム例外が発生した時以外）

javax.ejb.EJBException

Message-driven Beanの実行時（システム例外が発生した時）

java.lang.IllegalStateException

EJBを含むJ2EEアプリケーションの停止処理を開始したあとでメッセージリスナのメソッドを呼び出した場合

release()メソッドがすでに呼び出されている場合

不正な順序で呼び出した場合（Option B※のメッセージ配送で，メッセージリスナのメソッドを呼び出したあと，続けてメッセージリスナのメソッドを呼び出した場合）

注※　Connector 1.5仕様に記述されているメッセージ配送オプションです。

3.16.8　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定

ここでは，Connector 1.5仕様に準拠したリソースアダプタを使用する場合のJ2EEアプリケーションとリソースアダプタの設定について説明します。

設定は，それぞれConnector属性ファイルとアプリケーション統合属性ファイル※に指定します。

注※

この項の説明は，すべてアプリケーション統合属性ファイルを使用する場合の説明です。cjgetapppropコマンドでMessage-driven Bean属性ファイルを取得した場合は，Message-driven Bean属性ファイルに指定できます。Message-driven Bean属性ファイルを使用する場合は，「アプリケーション統合属性ファイルの<hitachi-connector-property>タグ下」を「Message-driven Bean属性ファイル」に読み替えてください。

＜この項の構成＞

(1)　設定できる項目

(2)　管理対象オブジェクトの設定

(3)　Message-driven Beanとリソースアダプタの対応づけの設定

(4)　Message-driven Beanが使用するインタフェースの設定

(5)　ActivationSpecの設定

(1)　設定できる項目

Connector 1.5仕様に準拠したリソースアダプタを使用する場合に設定できる項目について説明します。

(a)　J2EEアプリケーションの設定

J2EEアプリケーションに設定できる内容を次の表に示します。

表3-72　J2EEアプリケーションの設定（Connector 1.5仕様に準拠するリソースアダプタを使用する場合）

機能
項目
対象
設定内容

管理対象オブジェクトのルックアップ
管理対象オブジェクトのルックアップで使用する情報
WAR，Session Bean，Entity Bean，Message-driven Bean
<resource-env-ref>タグ下の次のタグに設定します。

<resource-env-ref-name>タグに，ルックアップで使用する名前を指定します。

<resource-env-ref-type>タグに，管理対象オブジェクトの型を指定します。

<linked-adminobject>－<resourceadapter-name>タグに，管理対象オブジェクトが含まれるリソースアダプタの表示名を指定します。

<linked-adminobject>－<adminobject-name>タグに，管理対象オブジェクトのオブジェクト名を指定します。

メッセージインフロー※
リソースアダプタとの対応づけ
Message-driven Bean
<message-ref>－<connection-destination>タグ下の<resource-adapter>タグに，対応づけるリソースアダプタの表示名を指定します。

Message-driven Beanが使用するインタフェース
Message-driven Bean
<messaging-type>タグに，Message-driven Beanが実装するインタフェースを指定します。

ActivationSpecの設定
Message-driven Bean
<activation-config>－<activation-config-property>タグ下の<activation-config-property-name>タグおよび<activation-config-property-value>タグに，ActivationSpecに設定するプロパティを指定します。

注※　設定値の一部は，使用するリソースアダプタの設定値と合わせる必要があります。

(b)　リソースアダプタの設定

リソースアダプタのプロパティとして設定する項目のうち，Connector 1.5仕様に準拠したリソースアダプタで設定できる主な項目と，その項目の設定方法について説明します。なお，ここでは，Connector 1.5仕様に準拠したリソースアダプタ固有の内容を説明します。

Connector 1.5仕様に準拠したリソースアダプタのプロパティとして設定できる内容を次の表に示します。

表3-73　Connector 1.5仕様に準拠したリソースアダプタのプロパティ定義で設定できる内容

分類
項目
設定内容

管理対象オブジェクト
管理対象オブジェクト名※1
<adminobject>－<adminobject-name>タグ※2にルックアップで使用するオブジェクト名を指定します。管理対象オブジェクトをルックアップの対象にする場合は必ず指定してください。オブジェクト名には，連続したアンダースコア"__"を含めてはいけません。
なお，管理対象オブジェクトをルックアップする場合には，J2EEアプリケーションの設定も必要です。「(a)　J2EEアプリケーションの設定」を参照してください。

インタフェース
<adminobject>－<adminobject-interface>タグに使用するインタフェースを指定します。javax.jms.Queue，javax.jms.Topicなどを指定します。

実装クラスとプロパティ
<adminobject-class>タグに実装クラスを指定します。
<config-property>タグ下に管理対象オブジェクトのプロパティを設定します。

注※1　メッセージインフローで使用する管理対象オブジェクトの場合，指定する必要はありません。

注※2　DD（ra.xml）には存在しないタグです。

(2)　管理対象オブジェクトの設定

メッセージインフローで使用する管理対象オブジェクトの設定は，Connector属性ファイルに記述します。

管理対象オブジェクトに設定する内容は，リソースアダプタに依存します。使用するリソースアダプタのドキュメントを参照してください。

管理対象オブジェクトは，Message-driven Beanと対応づけて使用します。対応づけについては，「(5)　ActivationSpecの設定」を参照してください。

(3)　Message-driven Beanとリソースアダプタの対応づけの設定

Message-driven Beanとリソースアダプタの対応づけは，アプリケーション統合属性ファイルの<resource-adapter>タグに指定します。リソースアダプタの表示名を指定してください。

<resource-adapter>の階層を次に示します。

<hitachi-message-bean-property>
 <message-ref>
   <connection-destination>
     <resource-adapter>

これらのタグは，DD（ejb-jar.xml）には存在しない要素です。ただし，<hitachi-message-bean-property>はDDの<message-driven>に対応します。

リソースアダプタとの対応づけは，Message-driven Beanを含むJ2EEアプリケーションを開始したときに実行されます。なお，次の場合には，Message-driven Beanを含むJ2EEアプリケーションの開始が失敗します。この場合は，KDJE42359-Eのメッセージが出力されます。

<resource-adapter>タグにリソースアダプタの表示名が指定されていない場合

<resource-adapter>タグに指定した表示名のリソースアダプタが開始されていない場合

<resource-adapter>タグに指定した表示名のリソースアダプタが見つからない場合

Message-driven Beanは，管理対象オブジェクトとも対応づける必要があります。対応づけについては，「(5)　ActivationSpecの設定」を参照してください。

参考

アプリケーションサーバでは，<message-driven>－<message-destination-link>タグの情報は指定できません。

(4)　Message-driven Beanが使用するインタフェースの設定

Message-driven Beanが使用するインタフェースは，アプリケーション統合属性ファイルの<messaging-type>タグに記述します。Message-driven Beanが実装するインタフェース名を指定してください。

<messaging-type>の階層を次に示します。

<hitachi-message-bean-property>
 <messaging-type>

<hitachi-message-bean-property>はDD（ejb-jar.xml）の<message-driven>に対応します。

Message-driven Beanが使用するインタフェースには，リソースアダプタがサポートしているインタフェースを指定する必要があります。リソースアダプタがサポートするインタフェースは，リソースアダプタのDD（ra.xml）の<messagelistener-type>タグに指定されています。このタグに指定されている以外のインタフェースを指定した場合は，Message-driven Beanを含むJ2EEアプリケーションの起動が失敗します。この場合は，KDJE43167-Eのメッセージが出力されます。

リソースアダプタがサポートしているインタフェースは，サーバ管理コマンドの次のコマンドでも確認できます。これらのコマンドの引数に，-resnameおよび-inboundを指定して実行してください。

cjlistresコマンド
詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjlistres（リソースの一覧表示）」を参照してください。

cjlistrarコマンド
詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjlistrar（リソースアダプタの一覧表示）」を参照してください。

cjlistappコマンド
詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjlistapp（アプリケーションの一覧表示）」を参照してください。

なお，<messaging-type>タグの指定を省略した場合は，デフォルト値としてjavax.jms.MessageListenerインタフェースが使用されます。

参考

javax.jms.MessageListenerインタフェースは，EJB2.0まで固有のメッセージリスナインタフェースとして使用されていたインタフェースです。

(5)　ActivationSpecの設定

ActivationSpecとは，Message-driven Beanを活性化するために必要な設定を持つJavaBeansです。ActivationSpecには，リソースアダプタの設定に合わせて設定が必要なプロパティがあります。

(a)　ActivationSpecの設定の概要

ActivationSpecに設定する値は，アプリケーション統合属性ファイルの<activation-config>タグ下に記述します。プロパティ名とプロパティ値を指定してください。複数指定できます。

<activation-config>の階層を次に示します。

<hitachi-message-bean-property>
 <activation-config>
   <activation-config-property>
     <activation-config-property-name>
     <activation-config-property-value>

ActivationSpecについてのデフォルトの設定値は，リソースアダプタのDD（ra.xml）に設定できます。<resourceadapter>－<config-property>タグに設定した値が，デフォルト値として使用されます。デフォルト値を記載している場合にアプリケーション統合属性ファイルでActivationSpecの値を設定したときには，<hitachi-message-bean-property>タグ下で指定した値で上書きされます。

ActivationSpecのプロパティとして必ず設定しなくてはいけないプロパティについては，「(b)　設定が必要なプロパティ」で説明します。

(b)　設定が必要なプロパティ

ActivationSpecの設定では，リソースアダプタのDD（ra.xml）の<activationspec>－<required-config-property>タグに指定されているプロパティの値を設定する必要があります。設定が必要なプロパティは，サーバ管理コマンドの次のコマンドでも確認できます。これらのコマンドの引数に，-resnameおよび-listenertypeを指定して実行してください。

cjlistresコマンド

cjlistrarコマンド

cjlistappコマンド

このほか，ActivationSpecに設定できるプロパティはリソースアダプタに依存します。使用するリソースアダプタのドキュメントを参照してください。

(c)　JMSをサポートするメッセージリスナを使用する場合に設定が必要なプロパティ

JMSをサポートするメッセージリスナ（javax.jms.MessageListenerインタフェースを使用するメッセージリスナ）を使用する場合，ActivationSpecに次のプロパティが必要です。<activation-config>タグ下に指定してください。

destination

destinationType

なお，アプリケーションサーバでは，これらのプロパティが指定されているかどうかのチェックは実施されません。プロパティ設定が適切かどうかは，リソースアダプタが提供するActivationSpec#validateメソッドで確認してください。

参考

EJB 2.0で<message-driven>タグ下の要素として指定していた次の項目は，EJB 2.1以降では削除されています。

<message-selector>

<acknowledge-mode>

<message-driven-destination>－<subscription-durability>

Connector 1.5仕様では，これらの要素を<activation-config>下のプロパティとして指定できることが推奨されています。ただし，指定できるかどうかは使用するリソースアダプタに依存します。

JMSをサポートするメッセージリスナを使用する場合のActivationSpec仕様の詳細については，Connector 1.5仕様のドキュメントを参照してください。

(d)　ActivationSpecの生成・設定で発生するエラー

ActivationSpecを生成，設定するときに，次の表に示す状態になった場合，エラーが発生します。エラーが発生すると，J2EEアプリケーションの開始は失敗します。

エラーが発生する場合と出力されるメッセージを次の表に示します。

表3-74　エラーが発生する場合と出力されるメッセージの対応

エラーが発生する場合 | 出力されるメッセージ
ActivationSpecの実装クラスのインスタンス生成に失敗した場合 | KDJE43168-E
ActivationSpecに指定したクラスがjavax.resource.spi.ActivationSpecインタフェースを実装していなかった場合 | KDJE43172-E
<activation-config-property-name>タグに対応するプロパティのsetterメソッドが，ActivationSpecにない場合 | KDJE43169-E
ActivationSpecに各プロパティを設定したあとで，設定が適切であるかをチェックするメソッド(ActivationSpec#validateメソッド)の呼び出しで例外がスローされた場合 | KDJE43170-E
リソースアダプタのDD（ra.xml）で指定したプロパティ<required-config-property>タグに対応する設定項目が，アプリケーション統合属性ファイルの<activation-config>タグとして記述されていない場合 | KDJE43171-E
ActivationSpecのsetResourceAdapterメソッドで例外がスローされた場合※ | KDJE43173-E

注※　setResourceAdapterメソッドはjavax.resource.spi.ResourceAdapterAssociationインタフェースで定義するメソッドです。javax.resource.spi.ResourceAdapterAssociationインタフェースは，javax.resource.spi.ActivationSpecインタフェースのスーパーインタフェースです。

3.16.9　属性ファイルの指定例

ここでは，メッセージインフローを実行する場合の属性ファイルの指定方法について，例を使用して説明します。

Connector属性ファイルとアプリケーション統合属性ファイルでは，次の図に示す個所の設定を合わせる必要があります。

図3-54　Connector属性ファイルとアプリケーション統合属性ファイルで同じ値を指定する個所

それぞれの指定内容は次のとおりです。

aには，Message-driven Beanが使用するインタフェースを指定します。

bには，ActivationSpecと管理対象オブジェクトの対応づけを指定します。

cには，Message-driven Beanとリソースアダプタの対応づけを指定します。

以降，a～cに指定する内容を中心に説明します。

＜この項の構成＞

(1)　javax.jms.MessageListenerインタフェースを使用したMessage-driven Beanおよびリソースアダプタの場合

(2)　任意のメッセージリスナインタフェースを使用したMessage-driven Beanおよびリソースアダプタの場合

(1)　javax.jms.MessageListenerインタフェースを使用したMessage-driven Beanおよびリソースアダプタの場合

メッセージリスナのインタフェースとしてjavax.jms.MessageListenerインタフェースを使用する場合の属性ファイルの指定例を示します。

ここでは，次の図に示す構成を例にして説明します。JMSに対応した二つのMessage-driven Beanが，それぞれ別の管理オブジェクト（javax.jms.Queue）からメッセージを受信する例です。

図3-55　javax.jms.MessageListenerインタフェースを使用したMessage-driven Beanおよびリソースアダプタの構成例

アプリケーション統合属性ファイルの指定例を次に示します。

図3-56　アプリケーション統合属性ファイルの指定例（javax.jms.MessageListenerインタフェースを使用する場合）

図の説明：

図中の(3)～(5)は，「3.16.8　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定」での説明の項番と対応しています。また，a，b-1，b-2，cは，それぞれ次の設定を示します。

a：Message-driven Beanが使用するインタフェース

b-1，b-2：ActivationSpecと管理対象オブジェクトの対応づけ

c：Message-driven Beanとリソースアダプタの対応づけ

なお，a，b-1，b-2，cの設定値は，図3-56と対応しています。

Connector属性ファイルの指定例を次の図に示します。

図3-57　Connector属性ファイルの指定例（javax.jms.MessageListenerインタフェースを使用する場合）

図の説明：

図中の(2)～(4)は，「3.16.8　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定」での説明の項番と対応しています。また，a，b-1，b-2，cは，それぞれ次の設定を示します。

a：Message-driven Beanが使用するインタフェース

b-1，b-2：ActivationSpecと管理対象オブジェクトの対応づけ

c：Message-driven Beanとリソースアダプタの対応づけ

なお，a，b-1，b-2，cの設定値は，図3-57と対応しています。

(2)　任意のメッセージリスナインタフェースを使用したMessage-driven Beanおよびリソースアダプタの場合

メッセージリスナのインタフェースとして任意のインタフェースを使用する場合の属性ファイルの指定例を示します。

ここでは，次の図に示す構成を例にして説明します。

図3-58　任意のメッセージリスナインタフェースを使用したMessage-driven Beanおよびリソースアダプタの構成例

この例では，リソースアダプタが次に示す二つの独自のインタフェースに対応しています。

examples.Listener1は管理対象オブジェクトと独立して使用するメッセージリスナインタフェースです。

examples.Listener2は管理対象オブジェクトと関連づけて使用するメッセージリスナインタフェースです。

アプリケーション統合属性ファイルの指定例を次の図に示します。

図3-59　アプリケーション統合属性ファイルの指定例（任意のメッセージリスナインタフェースを使用する場合）

図の説明：

図中の(3)～(5)は，「3.16.8　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定」での説明の項番と対応しています。また，a-1，a-2，b，cは，それぞれ次の設定を示します。

a-1，a-2：Message-driven Beanが使用するインタフェース

b：ActivationSpecと管理対象オブジェクトの対応づけ

c：Message-driven Beanとリソースアダプタの対応づけ

なお，a-1，a-2，b，cの設定値は，図3-59と対応しています。

Connector属性ファイルの指定例を次の図に示します。

図3-60　Connector属性ファイルの指定例（任意のメッセージリスナインタフェースを使用する場合）

図の説明：

図中の(2)～(4)は，「3.16.8　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定」での説明の項番と対応しています。また，a-1，a-2，b，cは，それぞれ次の設定を示します。

a-1，a-2：Message-driven Beanが使用するインタフェース

b：ActivationSpecと管理対象オブジェクトの対応づけ

c：Message-driven Beanとリソースアダプタの対応づけ

なお，a-1，a-2，b，cの設定値は，図3-60と対応しています。

3.16.10　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の注意事項

Connector 1.5仕様に準拠したリソースアダプタを使用する場合の注意事項について説明します。注意事項はリソースアダプタの使用方法によって異なります。

＜この項の構成＞

(1)　J2EEリソースアダプタとしてデプロイして使用する場合（J2EEアプリケーションに含めないで使用する場合）

(2)　J2EEアプリケーションに含めて使用する場合

(1)　J2EEリソースアダプタとしてデプロイして使用する場合（J2EEアプリケーションに含めないで使用する場合）

管理対象オブジェクトをアノテーションで指定する場合は，コンテナ拡張ライブラリに管理対象オブジェクトのインタフェースを追加する必要があります。

コンテナ拡張ライブラリについては，「13.　コンテナ拡張ライブラリ」を参照してください。

(2)　J2EEアプリケーションに含めて使用する場合

リロード機能を使用する場合は，次のクラス（インタフェース）をコンテナ拡張ライブラリに追加する必要があります。

javax.resource.spi.ActivationSpecインタフェースの実装クラス

リソースアダプタがサポートするメッセージリスナのインタフェース

管理対象オブジェクトをアノテーションで指定する場合は，コンテナ拡張ライブラリに管理対象オブジェクトのインタフェースを追加する必要があります。

Inboundのリソースアダプタを使用した場合，グローバルトランザクションは使用できません。

コンテナ拡張ライブラリについては，「13.　コンテナ拡張ライブラリ」を参照してください。

3.17　コネクションプールのクラスタ化機能

この節では，コネクションプールのクラスタ化機能について説明します。

この節の構成を次の表に示します。

表3-75　この節の構成（コネクションプールのクラスタ化機能）

分類 | タイトル | 参照先
解説 | クラスタコネクションプールの概要 | 3.17.1
使用するリソースアダプタ | 3.17.2
クラスタコネクションプールの動作 | 3.17.3
手動によるコネクションプールの停止・開始の流れ | 3.17.4
設定 | Oracle RACを使用したOracleへの接続 | 3.17.5
コネクションプールをクラスタ化するために必要な設定 | 3.17.6

注　「実装」および「運用」について，この機能固有の説明はありません。

コネクションプールのクラスタ化機能は，データベースをクラスタ構成にしているシステムの場合に，最適な動作をするための機能です。コネクションプールのクラスタ化機能を使用することで，障害発生時やメンテナンス時の可用性の低下を防ぐことができます。コネクションプールのクラスタ化機能の使用時に，データベースノードに障害が発生した場合，およびデータベースノードのメンテナンスを行う場合の動作について説明します。

データベースノードに障害が発生した場合
OS，ハード，ソフト障害など，コネクションが取得できない状況になった場合，障害が発生しているデータベースノードに接続しているコネクションプールを自動で一時停止できます（自動一時停止機能）。J2EEアプリケーションからリソースアダプタにコネクションの取得要求が出された場合でも，一時停止されたコネクションプールにはコネクションの取得要求が出されないため，TCP/IPのタイムアウトまで処理が中断することはありません。これによって，J2EEアプリケーションは，ほかの正常なデータベースノードに接続しているコネクションプールからコネクションを取得し，業務を継続できます。
また，データベースノードの障害が回復した時に，自動でコネクションプールを再開できます（自動再開機能）。コネクションプールが再開されると，自動的に回復したデータベースノードから再びアクセスされるため，データベースノード回復時にcjclearpoolコマンドを実行して，コネクションプールを削除する必要はありません。

データベースノードのメンテナンスを行う場合
データベースノードのメンテナンスを行う場合，コマンドを使用して任意のタイミングでメンバコネクションプールを一時停止できます（手動一時停止機能）。これによって，そのデータベースノードを切り離して，メンテナンスを行えます。
また，メンテナンスが終了して再開する時に，コマンドを使用して任意のタイミングでコネクションプールを再開できます（手動再開機能）。

コネクションプールをクラスタ化する場合のコネクションプール（クラスタコネクションプール）の特徴，および機能について説明します。なお，Oracle RAC機能を使用してクラスタ化したOracleとの接続方法については，「3.17.5　Oracle RACを使用したOracleへの接続」を参照してください。

＜この節の構成＞

3.17.1　クラスタコネクションプールの概要

3.17.2　使用するリソースアダプタ

3.17.3　クラスタコネクションプールの動作

3.17.4　手動によるコネクションプールの停止・開始の流れ

3.17.5　Oracle RACを使用したOracleへの接続

3.17.6　コネクションプールをクラスタ化するために必要な設定

3.17.1　クラスタコネクションプールの概要

クラスタ化されたコネクションプールのことをクラスタコネクションプールといいます。ここでは，クラスタコネクションプールの構成，およびクラスタコネクションプールで使用できる機能について説明します。

＜この項の構成＞

(1)　クラスタコネクションプールの構成

(2)　前提条件

(3)　データベース接続で使用できるJ2EEコンポーネントおよび機能

(4)　使用できるリソース接続とトランザクション管理の機能

(1)　クラスタコネクションプールの構成

クラスタコネクションプールは，各データベースノードと接続するメンバリソースアダプタと，それら複数のメンバリソースアダプタを束ねるルートリソースアダプタで構成されています。ルートリソースアダプタとメンバリソースアダプタについて説明します。

ルートリソースアダプタ
クラスタ化したコネクションプール（クラスタコネクションプール）を使用するときに，J2EEアプリケーションからアクセスされるリソースアダプタです。ルートリソースアダプタは，メンバリソースアダプタを束ねる役割を持ちます。ルートリソースアダプタでは，ルートリソースアダプタに対する処理要求をメンバリソースアダプタに振り分けます。なお，ルートリソースアダプタは，コネクションプールを持ちません。

メンバリソースアダプタ
クラスタ化されている個々のデータベースノードに接続するリソースアダプタです。メンバリソースアダプタは，必ずルートリソースアダプタを経由してアクセスされます。メンバリソースアダプタのコネクションプールのことを，メンバコネクションプールといいます。

コネクションプールをクラスタ化しているときのコネクション取得時の処理の流れを次の図に示します。

図3-61　コネクション取得時の処理の流れ

J2EEアプリケーションは，ルートリソースアダプタに対しコネクション取得要求をする。

ルートリソースアダプタは，メンバコネクションプールを一つ選択し，コネクション取得要求を出す。

メンバコネクションプールからコネクションが選択され，J2EEアプリケーションに返す。

(2)　前提条件

コネクションプールのクラスタ化機能を利用できるデータベースは，Oracle10gまたはOracle11gでRAC機能を使用している場合だけです。使用できるJDBCドライバは，Oracle JDBC Thin Driverです。

(3)　データベース接続で使用できるJ2EEコンポーネントおよび機能

コネクションプールのクラスタ化機能を使用している場合に，データベース接続で使用できるJ2EEコンポーネントおよび機能を次の表に示します。

表3-76　データベース接続で使用できるJ2EEコンポーネントおよび機能（コネクションプールのクラスタ化機能）

項目 | Oracle10gまたはOracle11g（コネクションプールのクラスタ化機能を使用した場合）
J2EEコンポーネント | Servlet/JSP | ○
Stateless Session Bean | ○
Stateful Session Bean | ○
Entity Bean（BMP） | ○
Entity Bean（CMP1.1） | ×
Entity Bean（CMP2.0） | ×
Message-driven Bean | ×
使用できる機能 | コネクションプーリング | ○
コネクションプールのウォーミングアップ | ○
コネクションプールの情報表示（cjlistpoolコマンド） | ○
コネクションプールのクリア | ○
リソースへの接続テスト | ○
コネクションの障害検知 | ○
ステートメントプーリング | ○
ステートメントキャンセル | 　△※1
ステートメントsetQueryTimeoutメソッド | 　△※2
コネクションIDのPRFトレース出力 | ○
障害調査用SQLの出力 | ○

（凡例）○：使用できる　×：使用できない　△：一部制限あり

注※1　接続形式がMTS接続のときに使用できます。専用接続では使用できません。

注※2　MTS接続は有効に働きますが，専用接続には制限があります。詳細はオラクルのサポートサービスにお問い合わせください。

注意

リソースアダプタを使用する場合，J2EEアプリケーションからリソースアダプタへのリファレンスを解決しておく必要があります。リソースアダプタを使用しているJ2EEアプリケーションをカスタマイズするときに，J2EEアプリケーションからリソースアダプタへのリファレンスを解決しておいてください。

(4)　使用できるリソース接続とトランザクション管理の機能

ルートリソースアダプタ，およびメンバリソースアダプタで使用できる機能については，「3.3.4　リソースアダプタの機能」を参照してください。

3.17.2　使用するリソースアダプタ

ルートリソースアダプタおよびメンバリソースアダプタで実行できるコマンド，設定の概要，および注意事項について説明します。

＜この項の構成＞

(1)　実行できるコマンド

(2)　DB Connectorの設定

(3)　ルートリソースアダプタについての注意事項

(4)　メンバリソースアダプタについての注意事項

(1)　実行できるコマンド

ルートリソースアダプタおよびメンバリソースアダプタごとの，コマンドの実行可否を次の表に示します。なお，これ以外のコマンドについてはどちらのリソースアダプタでも実行できます。

表3-77　ルートリソースアダプタおよびメンバリソースアダプタのコマンドの実行可否

コマンド | リソースアダプタの種類
ルートリソースアダプタ | メンバリソースアダプタ
cjstartrar | ○ | ○
cjstoprar | ○ | ○
cjtestres | ○ | ○
cjlistrar | ○ | ○
cjclearpool | × | ○
cjlistpool | × | ○
cjsuspendpool | × | ○
cjresumepool | × | ○

（凡例）　○：実行できる　　×：実行できない

(2)　DB Connectorの設定

ルートリソースアダプタおよびメンバリソースアダプタのDB Connectorで設定する項目を次の表に示します。

表3-78　ルートリソースアダプタおよびメンバリソースアダプタのDB Connectorで設定する項目

設定項目 | リソースアダプタの種類
ルートリソースアダプタ | メンバリソースアダプタ
トランザクションサポートレベル | × | 　○※1
ログ取得の可否 | ○ | ○
データベース接続情報 | － | ○
DB Connector固有の設定（ステートメントプールなど） | － | ○
セキュリティ情報（ユーザ名，パスワード） | × | 　○※2
コネクションプールサイズ | × | ○
クラスタコネクションプール固有の設定 | ○ | －

（凡例）○：設定が必要　×：設定は不要　－：設定項目がない

注※1　一つのクラスタコネクションプールを構成するメンバリソースアダプタのトランザクションサポートレベルは，すべて同じにする必要があります。

注※2　一つのクラスタコネクションプールを構成するメンバリソースアダプタのユーザ名は，すべて同じにする必要があります。

DB Connectorの設定の詳細については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「4.2　データベースと接続するための設定」，またはマニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1　Connector属性ファイル」を参照してください。

(3)　ルートリソースアダプタについての注意事項

cjclearpoolコマンドは実行できません。実行した場合は，メッセージが出力され，コマンドが異常終了します。クラスタコネクションプール内のコネクションをcjclearpoolコマンドでクリアする場合は，メンバリソースアダプタに対してコマンドを実行してください。

cjlistpoolコマンドは実行できません。実行した場合は，メッセージが出力され，コマンドが異常終了します。クラスタコネクションプール内のコネクションプールの情報を表示する場合は，cjlistpoolコマンドの-resnameにメンバリソースアダプタの表示名を指定するか，-resallを指定して実行してください。

一つのクラスタコネクションプール内で，コンテナ管理でのサインオンとコンポーネント管理でのサインオンを混在して使用できません。コンポーネント管理でのサインオンを使用する場合は，ルートリソースアダプタに属するすべてのメンバリソースアダプタのユーザ名を空白にしてください。

ルートリソースアダプタは，ルートリソースアダプタに属するすべてのメンバリソースアダプタが開始状態の場合に開始できます。これ以外の場合に，ルートリソースアダプタを開始すると，コンソールまたは画面にエラーメッセージが出力され，リソースアダプタの開始に失敗します。

(4)　メンバリソースアダプタについての注意事項

メンバリソースアダプタでは，次の機能が前提となります。これらの機能は，デフォルトで有効となり，無効にすることはできません。

コネクションプーリング
コネクションプールの最大値に0より大きい値を設定してください。0以下の値を設定した場合，コネクションプールの最大値と最小値にデフォルト値が指定されたものとして動作します。

コネクション取得時のコネクションの障害検知
コネクション取得時のコネクションの障害検知およびコネクション障害検知のタイムアウトは，設定値に関係なく有効となります。

コネクション枯渇時のコネクション取得待ち
コネクション枯渇時のコネクション取得待ちは，設定値に関係なく有効となります。

loginTimeout
loginTimeoutのプロパティに0よりも大きい値を設定してください。0以下の値を設定した場合はデフォルト値が指定されたものとして動作します。

メンバリソースアダプタでは，次の機能を使用できません。これらの機能は，デフォルトで無効となり，有効にすることはできません。

コネクションの取得リトライ

J2EEリソースのユーザ指定名前空間

メンバコネクションプール内のコネクションは，すべて同じデータベースノードに接続している必要があるため，データベースで接続先を変更する機能は使用しないでください。次にその機能の例を挙げます。なお，各機能を無効にする設定については，オラクルのマニュアルを参照してください。

クライアント・ロード・バランシング機能

接続時フェイルオーバー機能

データベースサービス

リスナによる負荷分散機能

メンバリソースアダプタにアクセスするときは，必ずルートリソースアダプタを経由します。そのため，次の個所には設定できません。

J2EEアプリケーションのリソースリファレンス

CMP Entity Beanのマッピング定義

メンバリソースアダプタは，所属するルートリソースアダプタが停止状態の場合に停止できます。開始状態のときに，メンバリソースアダプタを停止すると，コンソールまたは画面にエラーメッセージが出力され，リソースアダプタの停止に失敗します。

メンバコネクションプールの閉塞および一時停止時，コネクションを破棄するために，コネクションプールから未使用コネクションを取り除きます。この際，コネクションの破棄が完了していない時点でコネクションプールが再開されると，コネクションプール内のコネクションとコネクションプールから取り除いた未使用コネクションの総数が，コネクションプールのコネクション数の最大値を一時的に超える場合があります。

3.17.3　クラスタコネクションプールの動作

コネクションプールをクラスタ化した場合に使用できる機能と動作について説明します。クラスタコネクションプールでは次の機能を実行できます。

コネクションプールの一時停止

コネクションプールの再開

また，コネクションプールの状態，およびコネクションの取得要求を受けたときの，コネクションプールの選択方式についても説明します。

＜この項の構成＞

(1)　コネクションプールの一時停止

(2)　コネクションプールの再開

(3)　コネクションプールの状態

(4)　コネクションプールの選択方式

(1)　コネクションプールの一時停止

メンバコネクションプールを閉塞および一時停止できます。一時停止を実行すると，メンバコネクションプールが閉塞し一時停止します。

J2EEアプリケーションがルートリソースアダプタにコネクション取得要求をした場合，閉塞または一時停止したメンバコネクションプールにはコネクション取得要求は出されません。

次の場合にメンバコネクションプールを一時停止してください。

データベースノードに障害が発生した場合

データベースノードのメンテナンスをする場合

なお，一時停止の方法には次の2とおりがあります。

自動一時停止

手動一時停止

参考

一時停止処理では，J2EEアプリケーションで使用し終わったコネクションを破棄し，コネクションプール内のすべてのコネクションを破棄してから，コネクションプールを一時停止します。ネットワーク障害やデータベースノード障害が発生した場合，ネットワークのタイムアウトまで待ってからコネクションを破棄するため，閉塞してから一時停止するまでに時間が掛かることがあります。

(a)　自動一時停止

データベースノードの障害時にメンバコネクションプールを自動で一時停止できます。障害を検知すると，メンバコネクションプールは自動的に閉塞状態になり，そのあと一時停止します。

コネクションの取得時に次の現象が発生した場合，データベースノードに障害が発生したと判断し，メンバコネクションプールが自動的に一時停止します。

コネクション取得時のコネクションの障害検知がタイムアウトした場合

物理コネクションの取得に失敗した場合

物理コネクションの取得がタイムアウトした場合

コネクション管理スレッドが枯渇した場合

この機能は，デフォルトで有効となっています。有効/無効の設定は，ルートリソースアダプタのプロパティとして設定します。リソースアダプタの設定については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「5.4　リソースアダプタのプロパティ定義」を参照してください。

(b)　手動一時停止

データベースノードのメンテナンスをする場合などに，cjsuspendpoolコマンドを実行することで，コネクションプールを手動で一時停止できます。手動一時停止は，メンバコネクションプールが開始状態，開始予約状態，自動一時停止状態，および自動一時停止予約状態の場合に実行できます。メンバコネクションプールが自動一時停止状態の場合にcjsuspendpoolコマンドを実行すると，手動一時停止状態になります。これによって，自動一時停止後に自動再開させない運用ができます。手動での一時停止手順については，「3.17.4(2)　コネクションプールの一時停止」を参照してください。コマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjsuspendpool（メンバコネクションプールの一時停止）」を参照してください。

注意

cjsuspendpoolコマンドで手動一時停止したコネクションプールは，自動で再開されません。手動で再開してください。

(2)　コネクションプールの再開

一時停止したメンバコネクションプールを再開できます。J2EEアプリケーションからルートリソースアダプタにコネクション取得要求をした時に，再開したメンバコネクションプールには再びコネクションの取得要求が出されるようになります。

なお，コネクションプールを再開するには，未使用のコネクション管理スレッドの個数が，コネクションプールのコネクション数の最大数以上必要です。

次の場合にコネクションプールを再開してください。

データベースノードの障害が回復した場合

データベースノードのメンテナンスが終了した場合

再開の方法には次の2とおりがあります。

自動再開

手動再開

参考

コネクションプールが停止されている場合に，未使用のコネクション管理スレッドの個数がコネクションプールのコネクション数の最大数になると，メッセージが出力されます。cjresumepoolコマンドの実行に失敗した場合は，出力されたメッセージを確認してから再度コマンドを実行してください。

コネクションプールのウォーミングアップ機能が有効な場合には，コネクションプールの設定で定義した最小値までコネクションをプールしてから，メンバコネクションプールを開始します。コネクションをプーリングしているときにコネクションの生成に失敗した場合は，メンバコネクションプールは一時停止状態に戻ります。また，コネクションプールのウォーミングアップ機能が無効な場合は，すぐに開始状態になります。

(a)　自動再開

自動一時停止したメンバコネクションプールを自動で再開できます。

自動一時停止したメンバコネクションプールでは，データベースノードの状態をチェックするために，一定間隔で物理コネクションの取得要求を出します。このとき，コネクションの取得に成功すると，データベースノードが回復したと判断し，自動的に再開処理が行われます。また，自動一時停止したメンバコネクションプールを自動再開させない運用にするには，自動一時停止後に手動一時停止してください。再開時には，手動再開してください。

なお，ルートリソースアダプタが停止状態の場合，自動再開処理は行われません。ただし，メンバコネクションプールが自動再開中状態の場合にルートリソースアダプタを停止したときは，実行中の自動再開処理が継続されます。

この機能は，デフォルトで有効となっています。有効/無効の切り替えや，データベースノードの状態をチェックする間隔の設定は，ルートリソースアダプタのプロパティとして設定します。リソースアダプタの設定については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「5.4　リソースアダプタのプロパティ定義」を参照してください。

(b)　手動再開

自動一時停止または手動一時停止したコネクションプールを手動で再開できます。手動再開するには，cjresumepoolコマンドを使用します。手動再開は，コネクションプールが次の状態の場合に実行できます。

自動一時停止状態

手動一時停止状態

自動一時停止予約状態

手動一時停止予約状態

手動での手動再開手順については，「3.17.4(3)　コネクションプールの再開」を参照してください。コマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjresumepool（メンバコネクションプールの再開始）」を参照してください。

(3)　コネクションプールの状態

コネクションプールの状態は，メンバコネクションプールの場合だけ存在するものです。なお，コネクションプールの状態は，J2EEサーバやリソースアダプタの再起動後も維持されます。

メンバコネクションプールの状態は次の方法で確認できます。手動一時停止または手動再開をする場合は，コマンドを実行する前にコネクションプールの状態を確認してください。

cjlistrarコマンド
cjlistrarコマンドは，デプロイされているすべてのリソースアダプタについて，リソースアダプタ名とリソースアダプタの状態を標準出力に出力します。-clusterpoolを指定した場合には，メンバコネクションプールの状態も表示できます。
コマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjlistrar（リソースアダプタの一覧表示）」を参照してください。

cjlistpoolコマンド
cjlistpoolコマンドは，コネクションプールの情報を表示するコマンドです。メンバリソースアダプタの場合は，メンバコネクションプールの状態も表示できます。メンバリソースアダプタのコネクション情報の表示例については，「3.15.4　コネクションプールの情報表示」を参照してください。
コマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjlistpool（コネクションプールの一覧表示）」を参照してください。

ここでは，メンバコネクションプールの状態について説明します。

メンバコネクションプールの状態は，J2EEサーバやメンバリソースアダプタを再起動しても維持されます。コネクションプールの状態を確認する方法については，「3.17.4(1)　コネクションプールの状態の確認」を参照してください。

なお，メンバリソースアダプタ以外のコネクションプールには状態はありません。

(a)　コネクションプールの状態遷移

メンバコネクションプールの状態遷移を次の図に示します。

図3-62　メンバコネクションプールの状態遷移（手動で一時停止を実行する場合）

図3-63　メンバコネクションプールの状態遷移（自動で一時停止が実行される場合）

なお，J2EEサーバの開始時にコネクションプールが再開中状態，または閉塞状態の場合，コネクションプールは一時停止状態に遷移します。

それぞれの状態の詳細について次の表に示します。

表3-79　メンバコネクションプールの状態

番号 | 状態 | 説明
1 | 開始状態 | コネクションプールが処理を受け付けている状態です。ルートリソースアダプタへのコネクション取得要求時には，開始状態のコネクションプールだけに処理が行われます。
2 | 開始予約状態 | コネクションプールが開始状態のときにリソースアダプタが停止された状態です。開始予約状態のコネクションプールは，リソースアダプタの開始時に開始状態になります。リソースアダプタをデプロイした直後は，この状態になります。
3 | 自動再開中状態 | 自動再開機能によって，コネクションプールが再開処理を行っている状態です。再開処理が成功すると開始状態になります。再開処理が失敗すると，自動一時停止状態に戻ります。自動再開中状態のコネクションプールには，ルートリソースアダプタへのコネクション取得要求時に処理が出されません。
4 | 手動再開中状態 | 自動一時停止状態，または手動一時停止状態のときにcjresumepoolコマンドを実行して，コネクションプールが再開処理を行っている状態です。再開処理が成功すると，開始状態になります。再開処理が失敗すると，コマンド実行前の状態に戻ります。手動再開中状態のコネクションプールには，ルートリソースアダプタへのコネクション取得要求時に処理が出されません。
5 | 自動閉塞状態 | 自動一時停止機能によって，コネクションプールが閉塞されて，一時停止処理を行っている状態です。一時停止処理が完了すると，自動一時停止状態になります。自動閉塞状態のコネクションプールには，ルートリソースアダプタへのコネクション取得要求時に処理が出されません。
6 | 手動閉塞状態 | cjsuspendpoolコマンドによって，コネクションプールが閉塞され，一時停止処理を行っている状態です。一時停止処理が完了すると，手動一時停止状態になります。手動閉塞状態のコネクションプールには，ルートリソースアダプタへのコネクション取得要求時に処理が出されません。
7 | 自動一時停止状態 | 自動一時停止機能によって，コネクションプールが一時停止された状態です。コネクションプール内にコネクションは存在しません。自動一時停止状態のコネクションプールには，ルートリソースアダプタへのコネクション取得要求時に処理が出されません。
8 | 手動一時停止状態 | cjsuspendpoolコマンドによって，コネクションプールが一時停止された状態です。コネクションプール内にコネクションは存在しません。手動一時停止状態のコネクションプールには，ルートリソースアダプタへのコネクション取得要求時に処理が出されません。
9 | 自動一時停止予約状態 | コネクションプールが自動一時停止状態のときにリソースアダプタを停止した状態です。自動一時停止予約状態のコネクションプールは，リソースアダプタの開始時に自動一時停止状態になります。なお，このとき，コネクションプールのウォーミングアップ機能は無効になります。
10 | 手動一時停止予約状態 | コネクションプールが手動一時停止状態のときにリソースアダプタを停止した状態です。手動一時停止予約状態のコネクションプールは，リソースアダプタの開始時に手動一時停止状態になります。なお，このとき，コネクションプールのウォーミングアップ機能は無効になります。

注　番号は，図3-62および図3-63中の番号を示します。

(b)　コネクションプールの状態によるコマンド実行の可否

コネクションプールの状態によって，実行できるコマンドと実行できないコマンドがあります。コネクションプールの状態ごとに，各コマンドの実行の可否を次に示します。

表3-80　コネクションプールの状態によるコマンド実行の可否

コマンド | コネクションプールの状態
開始 | 開始予約 | 自動再開中/手動再開中 | 自動閉塞/手動閉塞 | 自動一時停止 | 手動一時停止 | 自動一時停止予約 | 手動一時停止予約
cjstartrar | × | ○ | × | × | × | × | ○ | ○
cjstoprar | ○ | × | △※1 | △※2 | ○ | ○ | × | ×
cjclearpool | ○ | × | × | × | × | × | × | ×
cjlistrar | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○
cjsuspendpool | ○ | ○ | × | × | ○ | × | ○ | ×
cjresumepool | × | × | × | × | ○ | ○ | ○ | ○
cjstopsv(通常停止時) | ○ | ○ | △※1 | △※2 | ○ | ○ | ○ | ○
cjstopsv(強制停止時) | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○

（凡例）　○：実行できる　△：制限あり　×：実行できない

注※1　コマンドは受け付けられますが，開始または一時停止状態になってから処理が実行されます。

注※2　コマンドは受け付けられますが，一時停止状態になってから処理が実行されます。

(4)　コネクションプールの選択方式

J2EEアプリケーションがルートリソースアダプタにコネクションの取得要求を出した時に，メンバコネクションプールが一つ選択されます。このときメンバコネクションプールが選択される方式は，ラウンドロビン方式です。

選択対象のコネクションプールは，開始状態のメンバコネクションプールです。コネクションに空きがあるメンバコネクションプールが優先的に選択されます。

ただし，コネクション枯渇状態のメンバコネクションプールしかない場合は，コネクション取得要求が待ち状態になります。さらに，コネクション取得待ちのタイムアウトが発生すると，コネクションの取得に失敗します。また，コネクション取得要求が待ち状態の場合にコネクションプールが閉塞されたときは，コネクション取得要求が再開され，次の優先度のメンバコネクションプールからコネクションの取得を試みます。すべてのメンバコネクションプールからコネクションが取得できない場合には，コネクションの取得に失敗します。

なお，各メンバコネクションプールの最大サイズを設定する場合，次の指針に従って設定します。

メンバコネクションプールの最大サイズ（数）＝システムで許容される最大同時接続数÷データベースノードの数

3.17.4　手動によるコネクションプールの停止・開始の流れ

ここでは，クラスタコネクションプールの流れについて説明します。データベースに発生した障害に対応する場合や，データベースをメンテナンスする場合，一部のコネクションプールを手動で停止，再開始することで，システム全体を止めることなくデータベースをメンテナンスできます。一部のコネクションプールを手動で停止，再開始して，データベースをメンテナンスする作業は次の流れで行います。

コネクションプールの状態を確認する（3.17.4(1)参照）
サーバ管理コマンドを使用して実行します。

コネクションプールを一時停止する（3.17.4(2)参照）
サーバ管理コマンドを使用して実行します。

コネクションプールを再開する（3.17.4(3)参照）
サーバ管理コマンドを使用して実行します。

コネクションプールの状態を確認する（3.17.4(1)参照）
サーバ管理コマンドを使用して実行します。

＜この項の構成＞

(1)　コネクションプールの状態の確認

(2)　コネクションプールの一時停止

(3)　コネクションプールの再開

(1)　コネクションプールの状態の確認

クラスタ構成のデータベースをメンテナンスする前，およびメンテナンスしたあとに，コネクションプールの状態を確認します。

コネクションプールの状態の詳細については「3.17.3(3)　コネクションプールの状態」を参照してください。

コネクションプールの状態の確認は，cjlistrarコマンドで実行できます。

cjlistrarコマンドの実行形式と実行例を次に示します。

実行形式

cjlistrar <サーバ名> -clusterpool

実行例

cjlistrar MyServer -clusterpool

(2)　コネクションプールの一時停止

ここでは，コネクションプールを一時停止する手順について説明します。

コネクションプールの一時停止は，cjsuspendpoolコマンドで実行できます。cjsuspendpoolコマンドを実行すると，コネクションプールが閉塞されて一時停止状態になり，コネクション取得要求を受け付けなくなります。

cjsuspendpoolコマンドは，コネクションプールが次の状態の場合に実行できます。

開始

開始予約

自動一時停止

自動一時停止予約

コネクションプールの状態を確認する方法については，「(1)　コネクションプールの状態の確認」を参照してください。

cjsuspendpoolコマンドの実行形式と実行例を次に示します。

実行形式

cjsuspendpool ＜サーバ名＞ -resname ＜一時停止対象となるメンバリソースアダプタの表示名＞

実行例

cjsuspendpool MyServer -resname DB_Connector_for_Oracle_ClusterPool_Member

(3)　コネクションプールの再開

ここでは，コネクションプールを再開する手順について説明します。

コネクションプールの再開は，cjresumepoolコマンドで実行できます。cjresumepoolコマンドを実行すると，コネクションプールは手動再開中状態になり，再開処理が実行されます。再開処理が完了すると，コネクションプールは開始状態になり，コネクション取得要求を受け付けるようになります。

cjresumepoolコマンドは，コネクションプールが次の場合に実行できます。

使用されていないコネクション管理スレッドが，コネクションプールのコネクションの最大値以上ある

コネクションプールが，手動一時停止，手動一時停止予約，自動一時停止，または自動一時停止予約の状態である

コネクションプールの状態を確認する方法については，「(1)　コネクションプールの状態の確認」を参照してください。

cjresumepoolコマンドの実行形式と実行例を次に示します。

実行形式

cjresumepool ＜サーバ名＞ -resname ＜再開対象となるメンバリソースアダプタの表示名＞

実行例

cjresumepool MyServer -resname DB_Connector_for_Oracle_ClusterPool_Member

なお，cjresumepoolコマンドを実行したあと，コネクションプールの状態を確認して，再開処理が正しく実行されたかどうかを確認してください。コネクションプールの状態を確認する方法については，「(1)　コネクションプールの状態の確認」を参照してください。

3.17.5　Oracle RACを使用したOracleへの接続

Oracle RACを使用したOracleへの接続方法は，Oracleのバージョン，または負荷分散に使用する機能によって異なります。なお，接続できるトランザクションの種類はローカルトランザクションです。

Oracleのバージョン，負荷分散に使用する機能および使用するRARファイルの対応については，「3.6.6　Oracleと接続する場合の前提条件と注意事項」を参照してください。

負荷分散に使用する機能ごとに，Oracleへの接続方法について説明します。

＜この項の構成＞

(1)　アプリケーションサーバの機能を使用した接続

(2)　Oracleの機能を使用した接続

(1)　アプリケーションサーバの機能を使用した接続

アプリケーションサーバのコネクションプールのクラスタ化機能を使用して，Oracle RACに接続します。アプリケーションサーバがデータベースアクセスの負荷を分散します。コネクションプールのクラスタ化機能については，「3.17.1　クラスタコネクションプールの概要」を参照してください。

(a)　負荷分散処理の流れと設定

コネクションプールのクラスタ化機能を使用した場合の負荷分散処理の流れと設定を次の図に示します。

図3-64　コネクションプールのクラスタ化機能を使用した接続

この図では，3台構成のOracle RACシステムで，データベースノード1にはインスタンス1，データベースノード2にはインスタンス2，データベースノード3にはインスタンス3があります。データベースに接続するための設定を次に示します。

インスタンス1，2，3に対応したメンバリソースアダプタ用DB Connector M1，M2，M3を生成します。また，メンバリソースアダプタに振り分ける機能を持つルートリソースアダプタ用DB Connector Rも生成します。

J2EEアプリケーションはルートリソースアダプタ用DB Connector Rに関連づけます。

この設定によって，J2EEアプリケーション1，2からのデータベースアクセスはデータベースノード1，2，3に分散されます。

(b)　データベース障害発生時と回復時の動作

データベース障害が発生した場合，アプリケーションサーバが障害を検知します。障害が発生したデータベースに対応するメンバリソースアダプタが閉塞され，残っているインスタンスで処理が続行されます。

データベース障害が回復するとアプリケーションサーバは自動で閉塞を解除します。また，手動でも閉塞を解除できます。

(2)　Oracleの機能を使用した接続

DB ConnectorからOracle RACに接続し，Oracle RACの機能でデータベースアクセスの負荷を分散します。

(a)　負荷分散処理の流れと設定

Oracle RACの機能を使用した場合の負荷分散処理の流れと設定を次の図に示します。なお，この図はOracle10gの場合の図です。Oracle11gを使用している場合，図中の「サービスX」はありません。

図3-65　Oracle RACの機能を使用した接続

この図では，3台構成のOracle RACシステムで，データベースノード1にはインスタンス1，データベースノード2にはインスタンス2，データベースノード3にはインスタンス3があります。データベースに接続するための設定をOracle10gの場合とOracle11gの場合に分けて説明します。

Oracle10gの場合

OracleにサービスXを作成します。サービスとは，Oracle10gから導入された機能です。

サービスXでは，インスタンス1，2，3への接続を「優先」に設定します。なお，グローバルトランザクションは使用しないため，DTPは無効にします。

サービスXに対応したDB Connector Aを生成します。

DB Connector Aは，サービスXを使用するように設定します。

J2EEアプリケーション1，および2をDB Connector Aに関連づけます。

Oracle11gの場合

それぞれのインスタンスに分散して接続するDB Connector Aを生成します。

DB Connector Aは，グローバルデータベース名またはサービス名を使用するように設定します。

J2EEアプリケーション1，および2をDB Connector Aに関連づけます。

この設定によって，J2EEアプリケーション1，および2からのデータベースアクセスはデータベースノード1，2，3に分散されます。

(b)　データベース障害発生時と回復時の動作

データベース障害が発生した場合，Oracle RAC機能によって障害が発生したインスタンスが切り離され，残っているインスタンスで処理が続行されます。

アプリケーションサーバのコネクションプールを使用している場合，データベース回復時には次の操作を実行してください。コネクションプールがクリアされ，これ以降のアクセスが正常に分散されます。

cjclearpoolコマンドを実行する。

J2EEサーバを再起動する。

3.17.6　コネクションプールをクラスタ化するために必要な設定

コネクションプールをクラスタ化するためには，DB Connectorのプロパティ設定が必要になります。DB Connectorのプロパティ設定については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「4.3　データベースと接続するための設定（コネクションプールのクラスタ化の場合）」を参照してください。

3.18　リソースへの接続テスト

リソースアダプタのプロパティ設定後，設定した内容が正しいかどうか，検証することができます。これを接続テスト機能といいます。接続テストで検証される内容は，接続するリソースごとに異なります。リソースごとの接続テストでの検証内容を，次の表に示します。

なお，接続テストの実行手順や，リソースアダプタの設定については，「3.3.8　リソースアダプタの設定の流れ（J2EEリソースアダプタとしてデプロイして使用する場合）」，および「3.3.9　リソースアダプタの設定の流れ（J2EEアプリケーションに含めて使用する場合）」を参照してください。

表3-81　接続テストでの検証内容

リソースの種類
接続方法
接続テストでの検証内容

データベース
DB Connector

1.4モードであること

指定されたトランザクションサポートレベルが使用できること※1，※2

DB Connectorの設定が正しいこと

使用するJDBCドライバの設定が正しいこと

データベースとの接続を確立できること

SQL発行が成功すること

DB Connector（コネクションプールのクラスタ化機能を使用した場合のルートリソースアダプタ）

1.4モードであること

指定されたトランザクションサポートレベルが使用できること※1

DB Connectorの設定が正しいこと

ルートリソースアダプタの開始に必要な設定がされていること※3

DB Connector（コネクションプールのクラスタ化機能を使用した場合のメンバリソースアダプタ）

1.4モードであること

指定されたトランザクションサポートレベルが使用できること※1

DB Connectorの設定が正しいこと

Oracle JDBC Thin Driverの設定が正しいこと

データベースとの接続を確立できること

SQL発行が成功すること

メンバリソースアダプタの前提となる機能を使用していること※4

メンバリソースアダプタで使用できない機能を使用していないこと※4

データベース上のキュー
Cosminexus RM

1.4モードであること

指定されたトランザクションサポートレベルが使用できること※1

Cosminexus RMの設定が正しいこと

連携するDB Connector for Cosminexus RMが開始していること

連携するDB Connector for Cosminexus RMの設定が正しいこと

使用するデータベースとの接続を確立できること

DB Connector for Cosminexus RM

DB Connector for Cosminexus RMの設定が正しいこと

DB Connector for Cosminexus RMが開始していること

連携するCosminexus RMの設定が正しいこと

連携するCosminexus RMが開始していること

使用するJDBCドライバの設定が正しいこと

使用するデータベースとの接続を確立できること

SQL発行が成功すること

OpenTP1
TP1/Message Queue - Access

1.4モードであること

指定されたトランザクションサポートレベルが使用できること※1

TP1/Message Queue - Accessの設定が正しいこと

TP1/Message Queue - Accessが，TP1/Message Queueとの接続を確立できること

uCosminexus TP1 Connector

1.4モードであること

指定されたトランザクションサポートレベルが使用できること※1

uCosminexus TP1 Connectorの設定が正しいこと

TP1インバウンドアダプタ

Inboundでの通信のため，接続テストはできません。接続テストをしようとすると，KDJE48606-Eのメッセージが出力されます。

CJMSPブローカー
CJMSPリソースアダプタ

1.4モードであること

CJMSPブローカーとの接続を確立できること

SMTPサーバ
メールコンフィグレーション

SMTPサーバへの接続を確立できること

そのほか
日立製以外のリソースアダプタ

1.4モードであること

リソースへの接続を確立できること※5（javax.resource.spi.ManagedConnectionFactoryの実装クラスのcreateManagedConnectionメソッド呼び出しが成功することによって，リソースとの接続が確立できたものとします）。

Connector1.5に準拠したリソースアダプタの場合は，リソースアダプタを開始していないときに，開始と停止ができること（javax.resource.spi.ResourceAdapterの実装クラスのstartメソッドおよびstopメソッド呼出しが成功することによって，リソースアダプタを開始・停止できたものとします）。

注※1　リソースアダプタのトランザクションサポートレベルにグローバルトランザクション（XATransaction）が指定されている場合は，usrconf.propertiesのejbserver.distributedtx.XATransaction.enabledキーがtrueになっていれば使用できます。なお，トランザクションサポートレベルについては，「3.4.3　リソースごとに使用できるトランザクションの種類」を参照してください。

注※2　接続先のデータベースがXDM/RD E2のときは，グローバルトランザクション（XATransaction）は使用できません。トランザクションリカバリ用の物理コネクションの取得に失敗するため，DB Connectorの開始ができません。

注※3　ルートリソースアダプタの開始に必要な設定については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「4.3.3　ルートリソースアダプタ用DB Connectorの設定」を参照してください。

注※4　メンバリソースアダプタの前提となる機能，および使用できない機能については，「3.17.2　使用するリソースアダプタ」を参照してください。

注※5　Outboundの通信をする場合にリソースとの接続に必要なコネクション定義がないときは，メッセージKDJE48606-Eが出力されてテストに失敗します。

3.19　ファイアウォール環境での運用のための機能

ファイアウォールをシステムに組み込んで運用する場合，通信に使用するポートを固定し，固定したポートを使用した通信だけを許可する必要があります。

この節の構成を次の表に示します。

表3-82　この節の構成（ファイアウォール環境での運用のための機能）

分類 | タイトル | 参照先
解説 | トランザクションリカバリ用通信ポート | 3.19.1
スマートエージェントが使用する通信ポート | 3.19.2
設定 | ファイアウォール環境での運用のための設定 | 3.19.3

注　「実装」および「運用」について，この機能固有の説明はありません。

参考

コネクションスイーパによる通信性能低下の回避

ファイアウォールには，一定時間以上無通信のセッションを強制切断する機能を持つものがあります。ファイアウォールがアプリケーションサーバとデータベースサーバの間に配置されていて，コネクションプールが有効の場合には，しばらくの間使用されなかったコネクションがファイアウォールによって切断されることがあります。その後の切断されたコネクションの使用は，長時間の待ちが発生します。この現象は，ファイアウォールの無通信切断時間よりも早い時間で未使用コネクションを破棄するようにコネクションスイーパ機能を設定することで回避できます。

＜この節の構成＞

3.19.1　トランザクションリカバリ用通信ポート

3.19.2　スマートエージェントが使用する通信ポート

3.19.3　ファイアウォール環境での運用のための設定

3.19.1　トランザクションリカバリ用通信ポート

グローバルトランザクションを使用する場合，トランザクションリカバリ処理用の通信ポートを使用します。ファイアウォールをシステムに組み込んで運用する場合，ファイアウォールの構成によっては，このポートの通信を許可する必要があります。デフォルトではポート番号として20302が使用されますが，変更することもできます。

トランザクションリカバリ用通信ポートの設定は，J2EEサーバのプロパティをカスタマイズして設定します。J2EEサーバの動作設定のカスタマイズについては，「3.19.3　ファイアウォール環境での運用のための設定」を参照してください。

3.19.2　スマートエージェントが使用する通信ポート

TPBrokerのスマートエージェント（OSAgent）は通信ポートを使用します。ファイアウォールをシステムに組み込んで運用する場合，ファイアウォールの構成によっては，このポートを使用する通信を許可する必要があります。

スマートエージェントが使用する通信ポートの設定は，J2EEサーバのプロパティをカスタマイズして設定します。J2EEサーバの動作設定のカスタマイズについては，「3.19.3　ファイアウォール環境での運用のための設定」を参照してください。

なお，J2EEサーバのプロパティに設定した通信ポートは，環境変数OSAGENT_PORTにも指定する必要があります。J2EEサーバのプロパティと，環境変数OSAGENT_PORTには，必ず，同じ値を設定してください。

3.19.3　ファイアウォール環境での運用のための設定

ファイアウォール環境で運用する場合，J2EEサーバの設定が必要です。簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に，次の表に示す項目を設定します。

表3-83　簡易構築定義ファイルでのファイアウォール環境での運用のための設定

項目 | 設定するパラメタ | 設定内容
トランザクションのリカバリ | ejbserver.distributedtx.recovery.port | トランザクションのリカバリで使用する固定ポート番号を指定します。
スマートエージェントが使用する通信ポート | vbroker.agent.port | スマートエージェントが使用する通信ポートを指定します。

3.20　EJBクライアントアプリケーションでトランザクションを開始する場合の注意事項

この節では，EJBクライアントアプリケーションでトランザクションを開始する場合の注意事項について説明します。

ポイント

EJBクライアントアプリケーションでトランザクションを開始できるのは，EJBクライアントマシンにアプリケーションサーバをインストールしている場合です。uCosminexus ClientをインストールしたEJBクライアントマシンでは，EJBクライアントアプリケーションでトランザクションを開始することはできません。

EJBクライアントアプリケーションでトランザクションを開始した場合，グローバルトランザクションを使用してアプリケーションサーバ側のEJBを呼び出せます。このとき，トランザクションマネージャとトランザクションサービスは，EJBクライアントとアプリケーションサーバ間でトランザクションを伝播し，最終的に2フェーズコミットを実行します。

EJBクライアントアプリケーションで開始したトランザクション内では，アプリケーションサーバ上の複数のEJBを呼び出せます。アプリケーションサーバ側では，複数のリソースにアクセスできます。なお，EJBクライアントアプリケーションからリソースに直接アクセスすることはできません。

ここでは，EJBクライアントアプリケーションでトランザクションを開始する場合に注意することについて説明します。

＜この節の構成＞

3.20.1　アプリケーション開発時の注意事項

3.20.2　システム構築時の注意事項

3.20.3　システム運用時の注意事項

3.20.1　アプリケーション開発時の注意事項

EJBクライアントアプリケーションでトランザクションを開始する場合に，アプリケーション開発時に注意することを次に示します。EJBクライアントアプリケーションでのトランザクションの実装については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「3.5　EJBクライアントアプリケーションでのトランザクションの実装」を参照してください。

EJBクライアントアプリケーションでグローバルトランザクションを使用するには，EJBクライアントアプリケーション起動直後に，EJBクライアントアプリケーションで使用するサービスを初期化するための処理をユーザプログラムから呼び出す必要があります。この初期化処理を呼び出すことで，トランザクションマネージャとトランザクションサービスが初期化されます。初期化処理としては，EJBClientInitializerクラスのinitialize()メソッドを呼び出してください。

トランザクション処理中にEJBクライアントアプリケーションが異常終了した場合も，サービスを初期化するための処理をユーザプログラムで呼び出すことによって，トランザクションのリカバリ処理が開始できるようになります。なお，リカバリ処理はバックグラウンドで実行されるため，initialize()メソッドはリカバリ処理の完了を待たないでリターンします。EJBクライアントアプリケーションの再起動によってグローバルトランザクションのリカバリ処理が開始するように，EJBクライアントアプリケーションを設計してください。

EJBクライアントアプリケーションでトランザクションを開始している場合，必ずすべてのトランザクションを決着させてから，EJBクライアントアプリケーションが停止するように設計してください。トランザクションの決着処理を待たないでEJBクライアントアプリケーションが停止すると，未決着トランザクションがトランザクション内に残留するおそれがあります。この状態になると，アプリケーションサーバの正常停止やリソースアダプタの停止ができなくなったり，リソースのロックが解除されなくなったりする場合があります。

3.20.2　システム構築時の注意事項

ここでは，システム構築時に注意することと設定について説明します。

＜この項の構成＞

(1)　システム構築時の注意

(2)　EJBクライアントアプリケーションでトランザクションを使用するための設定

(3)　JARファイルの設定

(4)　プロパティの設定

(5)　注意事項

(1)　システム構築時の注意

EJBクライアントアプリケーションでトランザクションを開始する場合に，システム構築時に注意することを次に示します。EJBクライアントアプリケーションのトランザクションの設定については，「(2)　EJBクライアントアプリケーションでトランザクションを使用するための設定」を参照してください。

EJBクライアントアプリケーションでトランザクションを開始する場合，グローバルトランザクションを使用するために，アプリケーションサーバ側でライトトランザクション機能を無効に設定する必要があります（デフォルトでは有効になっています）。

呼び出されるEJBを，EJBコンテナで管理するトランザクション（CMT）でMandatory属性，Required属性，Supports属性などに指定すると，EJBクライアントアプリケーション側で開始したトランザクションの範囲内で実行されます。

(2)　EJBクライアントアプリケーションでトランザクションを使用するための設定

ここでは，EJBクライアントアプリケーションでトランザクションを使用するための設定について説明します。

注意

uCosminexus Clientを使用してEJBクライアント環境を構築する場合は，EJBクライアントアプリケーションのトランザクションは使用できません。

EJBクライアントアプリケーションでトランザクションを使用するためには，次の設定が必要です。

JARファイルの設定

プロパティの設定

UserTransactionの取得の設定

UserTransactionの取得の設定は，J2EEアプリケーション開発時の設定内容です。EJBクライアントアプリケーションでトランザクションを使用するために，EJBクライアントアプリケーションからUserTransaction（javax.transaction.UserTransaction）を取得するための設定が必要です。設定方法については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「3.5　EJBクライアントアプリケーションでのトランザクションの実装」を参照してください。

ここでは，EJBクライアントアプリケーションでトランザクションを使用するためのJARファイルとプロパティの設定について説明します。

(3)　JARファイルの設定

EJBクライアントアプリケーションでトランザクションを使用するために，次のJARファイルをクラスパスに設定します。

Windowsの場合

<Cosminexusのインストールディレクトリ>¥TPB¥lib¥tpotsinproc.jar

<Cosminexusのインストールディレクトリ>¥CC¥lib¥ejbserver.jar※

UNIXの場合

/opt/Cosminexus/TPB/lib/tpotsinproc.jar

/opt/Cosminexus/CC/lib/ejbserver.jar※

注※　クラスパスの設定で，ejbserver.jarはHiEJBClientStatic.jarよりも後ろに設定してください。

クラスパスへのJARファイルの設定については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「3.7.4　EJBクライアントアプリケーションのクラスパスへのJARファイルの設定」を参照してください。

(4)　プロパティの設定

EJBクライアントアプリケーションでトランザクションを使用するために設定が必要なキーについて説明します。プロパティの設定については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「3.3.5　EJBクライアントアプリケーションのプロパティの設定」を参照してください。各キーの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「15.3　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

EJBクライアントアプリケーションでトランザクションを使用するためには，次のキーを設定します。

(a)　必須のプロパティ

ejbserver.client.transaction.enabled
「true」を指定して，EJBクライアントアプリケーションでのトランザクションの使用を有効にします。

ejbserver.distributedtx.recovery.port
グローバルトランザクションを使用するとき，トランザクションリカバリで使用する固定ポート番号を指定します。EJBクライアントのプロセスごとに別のポート番号を指定してください。また，同一マシン上で動作するアプリケーションサーバのリカバリ用ポート番号とは別のポート番号を指定してください。

ejbserver.client.transaction.clientName
トランザクションサービスが使用するクライアント名を指定します。ここでは，EJBクライアントのプロセスごとに別の名前を指定してください。また，同一マシン上で動作するJ2EEサーバ名とは別の名前を指定してください。

ejbserver.distributedtx.ots.status.directory1
トランザクションサービスが使用するステータスファイルや，そのバックアップを配置するディレクトリを指定します。EJBクライアントのプロセスごとに別のディレクトリを指定してください。また，J2EEサーバに指定したステータスファイルのディレクトリとは別のディレクトリを指定してください。

(b)　任意のプロパティ

ejbserver.jta.TransactionManager.defaultTimeOut
トランザクションタイムアウトが発生するまでの時間を指定します。

ejbserver.distributedtx.ots.status.directory2
トランザクションサービスが使用するステータスファイルや，そのバックアップを配置する二つ目のディレクトリを指定します。EJBクライアントのプロセスごとに別のディレクトリを指定してください。また，J2EEサーバに指定したステータスファイルのディレクトリとは別のディレクトリを指定してください。

(5)　注意事項

EJBクライアントアプリケーションのトランザクションの設定での注意事項を次に示します。

グローバルトランザクションを使用するためには，アプリケーションサーバ側でライトトランザクション機能を無効にする必要があります。デフォルトの設定では，ライトトランザクション機能が有効になっています。J2EEサーバのusrconf.propertiesのejbserver.distributedtx.XATransaction.enabledキーで「true」を指定すると，ライトトランザクション機能が無効となり，グローバルトランザクションが利用できるようになります。

3.20.3　システム運用時の注意事項

EJBクライアントアプリケーションでトランザクションを開始した場合に，運用時に注意することを次に示します。

EJBクライアントアプリケーションの停止後に，アプリケーションサーバやリソースアダプタを停止できない場合は，未決着トランザクションがトランザクション内に残留しているおそれがあります。この場合，EJBクライアントアプリケーションを再起動して，グローバルトランザクションのリカバリ処理を実施してください。
なお，リカバリ処理は，EJBクライアントアプリケーション内で，再起動後にサービスの初期化処理を呼び出されることで実行されます。

トランザクション処理中に障害などの理由でEJBクライアントマシンがダウンした場合は，EJBクライアントアプリケーションを再起動して，グローバルトランザクションのリカバリ処理を実施する必要があります。

EJBクライアントアプリケーションで開始したトランザクションは，メソッドキャンセル機能を使用して強制決着させることはできません。

サービスの初期化処理で例外が発生した場合，EJBクライアントアプリケーションの実行時のシステムプロパティなどが正しく設定されていないおそれがあります。例外メッセージに従って対処してください。

EJBクライアントアプリケーションでトランザクションを開始した場合，JTAやOTSが出力する性能解析トレースにルートアプリケーション情報やクライアントアプリケーション情報が含まれません。リクエストをトレースする場合には，スレッドのハッシュコードやXIDの情報を使用してください。
また，トランザクションタイムアウトが発生した時に出力されるメッセージには，ルートアプリケーション情報の代わりに，トランザクションを開始したスレッドのハッシュコードが含まれています。この情報を使用してトレースすることもできます。

4.　OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）

この章では，OpenTP1システムで動作するSUPからアプリケーションサーバ上のJ2EEアプリケーションをInboundで呼び出す機能である，TP1インバウンド連携機能について説明します。

なお，この機能を使用できる製品については，「4.3　TP1インバウンド連携機能の前提条件」を参照してください。

＜この章の構成＞

4.1　この章の構成

4.2　TP1インバウンド連携機能の概要

4.3　TP1インバウンド連携機能の前提条件

4.4　OpenTP1の機能との対応

4.5　コネクション管理機能

4.6　RPC通信機能

4.7　スケジュール機能

4.8　トランザクション連携機能

4.9　Message-driven Bean（サービス）の実装

4.10　OpenTP1のアプリケーションプログラムの作成

4.11　アプリケーションサーバの実行環境での設定

4.12　OpenTP1での設定

4.13　OpenTP1とアプリケーションサーバ間のタイムアウトの設定

4.14　TP1インバウンドアダプタとMessage-driven Bean（サービス）の開始と終了

4.15　性能解析トレース情報の引き継ぎ

4.16　TP1インバウンドアダプタで発生するRPCエラー応答

4.1　この章の構成

この章では，TP1インバウンド連携機能について説明します。

この章の構成を次の表に示します。

表4-1　この章の構成（TP1インバウンド連携機能）

分類 | タイトル | 参照先
解説 | TP1インバウンド連携機能の概要 | 4.2
TP1インバウンド連携機能の前提条件 | 4.3
OpenTP1の機能との対応 | 4.4
コネクション管理機能 | 4.5
RPC通信機能 | 4.6
スケジュール機能 | 4.7
トランザクション連携機能 | 4.8
実装 | Message-driven Bean（サービス）の実装 | 4.9
OpenTP1のアプリケーションプログラムの作成 | 4.10
設定 | アプリケーションサーバの実行環境での設定 | 4.11
OpenTP1での設定 | 4.12
OpenTP1とアプリケーションサーバ間のタイムアウトの設定 | 4.13
運用 | TP1インバウンドアダプタとMessage-driven Bean（サービス）の開始と終了 | 4.14
性能解析トレース情報の引き継ぎ | 4.15
注意事項 | TP1インバウンドアダプタで発生するRPCエラー応答 | 4.16

4.2　TP1インバウンド連携機能の概要

TP1インバウンド連携機能は，OpenTP1システム上で動作するユーザアプリケーションプログラムから，アプリケーションサーバ上で動作するJ2EEアプリケーションを業務として呼び出すための機能です。この機能によって，OpenTP1を使用したレガシーシステムを運用している場合に，新たに追加する業務をJ2EEアプリケーションとして実装して，既存のシステムに組み込んで使用できます。また，OpenTP1システム上で動作するユーザアプリケーションプログラムで開始されたトランザクションに，アプリケーションサーバのMessage-driven Bean（CMT）で実行する処理を参加させられます。

TP1インバウンド連携機能では，OpenTP1のユーザアプリケーションプログラムからの呼び出しをアプリケーションサーバ上で動作するTP1インバウンドアダプタで受け付け，J2EEサーバ上のMessage-driven Beanで業務処理を実行します。TP1インバウンドアダプタは，Connector 1.5仕様に準拠したリソースアダプタです。

トランザクション連携機能を使用する場合のTP1インバウンド連携機能の概要について示します。

なお，TP1インバウンド連携機能は，ユーザアプリケーションプログラムのうちSUP，SPP，およびMHPからの呼び出しが可能ですが，このマニュアルでは，SUPからの呼び出しを例に説明します。

図4-1　TP1インバウンド連携機能の概要

TP1インバウンド連携機能を使用する場合，クライアントとなるSUPからは，OpenTP1システムのSPPを呼び出す場合と同様の手順でアプリケーションサーバ上の業務を呼び出します。また，SPPの呼び出し時と同様にデータをやり取りできます。

さらに，トランザクション連携機能を使用することで，SUPからのリソース更新と，Message-driven Beanからのリソース更新を同期できます。

TP1インバウンドアダプタは，SPPと同様の手順での業務の呼び出しを実現するために，次の4種類の機能を備えています。

コネクション管理機能
OpenTP1とアプリケーションサーバ間のコネクションの接続，切断，およびプーリングを制御する機能です。これによって，コネクションを接続したままでOpenTP1と通信できます。また，コネクションの接続と切断に伴うボトルネックを削減でき，通信効率を向上できます。なお，OpenTP1とアプリケーションサーバとの間のコネクション数がしきい値に達すると，コネクションを切断（一時クローズ処理）します。

RPC通信機能
OpenTP1で扱うRPC電文を解析し，応答電文を生成して，RPC通信を実行する機能です。JCAコンテナを介してMessage-driven Beanを呼び出します。

スケジュール機能
RPC要求のスケジューリングを実行する機能です。OpenTP1のスケジュールサービスと同様の処理を実現するために使用します。

トランザクション連携機能
OpenTP1のSUPで開始されたトランザクションにMessage-driven Bean（CMT）で実行した処理を参加させる機能です。

ただし，TP1インバウンドアダプタでは，OpenTP1のネームサービスの代替機能は提供しません。このため，TP1インバウンドアダプタを使用するためには，クライアントとなるOpenTP1側でユーザサービスネットワーク定義によるスケジューラダイレクト機能を利用する必要があります。

4.3　TP1インバウンド連携機能の前提条件

TP1インバウンド連携機能を利用するための前提となる，アプリケーションサーバ製品およびOpenTP1製品を次に示します。

前提となるアプリケーションサーバ製品

次のどれかの製品で利用できます。

uCosminexus Application Server Enterprise

uCosminexus Developer Professional

uCosminexus Service Architect

uCosminexus Service Platform

前提となるOpenTP1製品

次のどれかの製品で利用できます。

TP1/Server Base Version 5以降

uCosminexus TP1/Server Base Version 7以降

uCosminexus TP1/LiNK Version 7以降

4.4　OpenTP1の機能との対応

この節では，TP1インバウンド連携機能とOpenTP1の機能との対応について説明します。

＜この節の構成＞

4.4.1　クライアントでサポートするOpenTP1の機能

4.4.2　OpenTP1のサーバの機能との対応

4.4.1　クライアントでサポートするOpenTP1の機能

アプリケーションサーバを呼び出すOpenTP1のクライアントでのOpenTP1の機能の使用可否を次の表に示します。なお，OpenTP1のそれぞれの機能の詳細については，マニュアル「OpenTP1 解説」およびマニュアル「OpenTP1 プログラム作成の手引」を参照してください。

表4-2　クライアントでのOpenTP1の機能の使用可否

機能の分類 | OpenTP1の機能 | 使用可否
ユーザアプリケーションプログラムの種類 | SUP | ○
SPP | ○
MHP | ○
RPCの種類 | 同期応答型RPC | ○
非同期応答型RPC | ×
非応答型RPC | ×
連鎖RPC | ×
トランザクショナルRPC | ○
認証RPC | ×
呼び出し先のRPC受信形態 | キュー受信型サーバ | ○
ソケット受信型サーバ | ×
リモートAPI機能 | リモートAPI機能 | ×
RPCのサービス要求方式 | ユーザサービスネットワーク定義によるスケジューラダイレクト機能 | ○
dc_rpc_call_to関数によるスケジューラダイレクト機能 | ×
ネームサービス機能 | ×
ドメインネームシステム機能 | ×
グローバル検索機能 | ×
マルチスケジューラ機能 | ×
電文操作 | ユーザデータ電文の圧縮機能 | ×
ユーザ電文 | ユーザ電文長8メガバイト拡張 | ○
そのほか | コネクションの保持 | ○
テストモード | ×
要求用TCP/IPコネクションの接続リトライ | ○
詳細エラーコード取得機能 | ×

（凡例）

○：使用できる　×：使用できない

各機能に対するTP1インバウンドアダプタでの対応について，機能の分類ごとに説明します。

＜この項の構成＞

(1)　ユーザアプリケーションプログラムの種類

(2)　RPCの種類

(3)　呼び出し先のRPC受信形態

(4)　リモートAPI機能

(5)　RPCのサービス要求方式

(6)　電文操作

(7)　ユーザ電文

(8)　そのほか

(1)　ユーザアプリケーションプログラムの種類

TP1インバウンドアダプタでは，SUP（サービス利用プログラム），SPP（サービス提供プログラム），およびMHP（メッセージ処理プログラム）からの処理を受け付けます。

(2)　RPCの種類

TP1インバウンドアダプタでは，OpenTP1で使用できるRPC形態のうち，同期応答型RPCおよびトランザクショナルRPCを使用できます。

非同期応答型RPCまたは非応答型RPCを使用してTP1インバウンドアダプタを呼び出した場合，クライアントにはエラーが返されます。

連鎖RPCとは，RPCを複数回実行する場合に，各RPC呼び出しを必ず同じプロセスで実行することを保証するOpenTP1の機能です。TP1インバウンドアダプタでは，連鎖RPCを保証しません。クライアントで連鎖RPCを有効にしてRPC通信を実行した場合は，エラーが返されます。

なお，TP1インバウンドアダプタでは，認証RPCはサポートしません。

(3)　呼び出し先のRPC受信形態

TP1インバウンドアダプタでは，キュー受信型サーバだけを使用できます。

TP1インバウンドアダプタでは，必ずスケジュールキューを経由してサービス要求を受信します。このため，スケジュールキューを経由しないで直接サービス要求を受信する形態であるソケット受信型サーバ機能は使用できません。

(4)　リモートAPI機能

TP1インバウンドアダプタでは，リモートAPI機能は使用できません。

リモートAPI機能とは，OpenTP1のSPP側でRPCの代理実行をする機能です。OpenTP1では，リモートAPIを使用することで，ファイアウォールの内側にあるUAPに対してサービスを要求できます。TP1インバウンドアダプタを使用する場合，ファイアウォールの内側のUAPに対するサービス要求はできません。

(5)　RPCのサービス要求方式

TP1インバウンドアダプタでは，ユーザサービスネットワーク定義によるスケジューラダイレクト機能を利用して，SUPからSPPを呼び出します。ユーザサービスネットワーク定義によるスケジューラダイレクト機能とは，あらかじめ，ユーザサービスネットワーク定義にサービス情報を静的に定義しておくことで，ネームサービスを参照しないで，直接スケジュールサービスにアクセスするための機能です。TP1インバウンドアダプタを呼び出す場合，必ずこの機能を使用してください。

TP1インバウンドアダプタでは，OpenTP1のネームサービスを代替する機能は使用できません。このため，ネームサービスを使用したサービス情報の参照はできません。ユーザサービスネットワーク定義によるスケジューラダイレクト機能を使用する設定がない場合，SUPでサービス情報を取得できないため，TP1インバウンドアダプタを呼び出せません。

なお，TP1インバウンドアダプタでは，ネームサービスの代替機能を使用できないため，ネームサービスの付加機能である次の機能も使用できません。

ドメインネームシステム機能

グローバル検索機能

また，TP1インバウンドアダプタでは，OpenTP1のマルチスケジューラ機能を使用できません。マルチスケジューラ機能とは，複数のスケジューラを起動して複数のRPCを同時に受け付ける機能です。ただし，TP1インバウンドアダプタのスケジュール機能では，受け付けた要求をマルチスレッドで処理するため，すでに電文を処理している場合も，新たに受け付けた別のRPCを同時に処理できます。

参考

OpenTP1のネームサービス機能

OpenTP1では，ネームサービスを使用して，各ノードにあるサービスに関する情報を検索できます。

OpenTP1でSUPからSPPを呼び出す通常の手順では，SUPでdc_rpc_call関数を実行する際に，ローカル環境のOpenTP1システム中のネームサービスに対してサービス情報の検索を実行します。ローカル環境のネームサービスは，ほかのノードのネームサービスと情報連携して，各ノードに存在するサービス情報を保持しています。検索実行後，ネームサービスから目的のサービスグループに対応するサービスの情報（スケジュールサービスのあるホストおよびポート番号の情報）が返されます。SUPでは，返却された情報を基に，スケジュールサービスにRPC通信を実行します。

(6)　電文操作

TP1インバウンドアダプタでは，ユーザデータ電文圧縮機能を使用できません。

ユーザデータ電文圧縮機能とは，RPCによってネットワーク上に送信されたユーザ電文を圧縮することによって，パケット数を削減し，ネットワークの混雑を緩和するOpenTP1の機能です。

TP1インバウンドアダプタでは，ユーザデータが圧縮されていた場合，エラーを返却します。

(7)　ユーザ電文

RPC通信で，8メガバイトまでのユーザ電文を送受信できます。

(8)　そのほか

TP1インバウンドアダプタでは，表4-2で「そのほか」に分類した機能のうち，コネクションの保持，および要求用TCP/IPコネクションの接続リトライを実行できます。コネクションの保持では，ノード間で確立したコネクションを保持できます。また，要求用TCP/IPコネクションの接続リトライは，RPC要求時にコネクションの確立に失敗した場合に，コネクションの確立をリトライするOpenTP1の機能です。

次の機能は使用できません。

テストモードは有効にできません。テストモードが有効になっている場合は，エラーを返却します。

詳細エラーコード取得機能は使用できません。なお，詳細エラーコード出力機能とは，エラーが発生した場合に，OpenTP1の呼び出し元に返却されるエラーコードを詳細化する機能です。

4.4.2　OpenTP1のサーバの機能との対応

TP1インバウンドアダプタは，「4.4.1　クライアントでサポートするOpenTP1の機能」で示した機能のうち，TP1インバウンドアダプタで使用できる機能を使用して送信されたRPCを受け付ける機能を備えています。ただし，OpenTP1のSPPおよびスケジュールサービスで提供されているすべての機能を同じように使用できるわけではありません。

TP1インバウンドアダプタを使用して実現できることの詳細については，「4.6　RPC通信機能」および「4.7　スケジュール機能」で説明します。

ここでは，TP1インバウンドアダプタとOpenTP1のサーバで動作するSPPの機能との対応を次の表に示します。また，機能差または代替機能がある場合にその概要についても説明します。なお，OpenTP1の機能の詳細については，マニュアル「OpenTP1 解説」およびマニュアル「OpenTP1 プログラム作成の手引」を参照してください。

表4-3　OpenTP1のサーバの機能との対応

機能の分類
OpenTP1の機能
使用可否
機能差または代替機能の概要

受け付け可能なRPC形態
同期応答型RPC
○
機能差はありません。

非同期応答型RPC
×
使用できません。

非応答型RPC
×

連鎖RPC
×

トランザクショナルRPC
○
機能差はありません。

RPC機能
ネストを使用したコール
×
TP1インバウンドアダプタでは，別のOpenTP1のSPPへのネストコールは実行できません。
ただし，TP1/ClientなどのOpenTP1にOutboundでの接続をするための機能によって，ネストコールを実現できます。
また，リモートEJB呼び出しなど，アプリケーションサーバ間でネストの呼び出しは実現できます。

リカーシブコール
×
使用できません。

コールバック※
×

リモートAPI機能
リモートAPIの受け付け
×

サービス
サービスリトライ機能
×

サービス実行のタイマ監視
△
アプリケーションサーバ独自の方式でのタイマ監視を実行できます。詳細は，「4.7.4　サービス実行のタイムアウト」を参照してください。

サービスの並列処理
○
スレッドを使用してサービスを並列処理できます。

サービスグループ閉塞
×
使用できません。

サービス閉塞
×

サービスの同時実行数制御
○
アプリケーションサーバ独自の方式で同時実行数を制御できます。詳細は，「4.7.3　Message-driven Bean（サービス）の同時実行数の制御」を参照してください。

電文操作
電文の圧縮
×
常に非圧縮の状態で応答します。TP1インバウンドアダプタが圧縮された電文を受け取った場合は，エラーを返却します。

スケジュールサービス
サービス単位のスケジュールキュー
×
使用できません。

サービスグループ単位のスケジュールキュー
○
機能差はありません。

スケジュール閉塞
×
使用できません。

スケジュールプライオリティ制御
×

サービスのスケジュール方式
△
サービスのスケジュールは常にFIFO方式で制御されます。

スケジュールキューの滞留の監視
△
アプリケーションサーバ独自の方式でスケジュールキューの滞留を監視できます。

負荷バランス
マルチサーバ負荷バランス
△
アプリケーションサーバでは，プロセスではなくスレッドを使用します。
また，アプリケーションサーバ独自の機能を使用して，負荷に応じてスレッド数を調整できます。詳細は，「4.7.3　Message-driven Bean（サービス）の同時実行数の制御」を参照してください。

マルチスケジューラ
×
使用できません。
ただし，アプリケーションサーバではマルチスレッドでリクエストを処理するため，マルチスケジューラ機能を使用しなくても一つのスケジュールサービスで複数のリクエストを処理できます。

ノード間負荷バランス
×
使用できません。
アプリケーションサーバでは，負荷情報は管理しません。
ノード間の振り分けには，ユーザサービスネットワーク定義による，ランダムなサービス要求だけが使用できます。これは，ユーザサービスネットワーク定義に複数のホストを記載すると，OpenTP1の機能によってランダムに決定されたノードにサービス要求が転送される機能です。一度決定した転送先ノードは，基本的には固定されます。また，オプションの定義によって，ノード決定を定期間隔で再決定できるようにチューニングできます。

コネクション
コネクション確立/通信制御データのタイマ監視
△
アプリケーションサーバ独自の方式でのタイマ監視を実行できます。詳細は，「4.7.4　サービス実行のタイムアウト」を参照してください。

コネクション確立要求のキュー
△
アプリケーションサーバ独自の方式で管理するキューを使用できます。詳細は，「4.6　RPC通信機能」を参照してください。

一時クローズ処理機能
○
機能差はありません。

応答用TCP/IPコネクションの接続リトライ
○
使用できます。
詳細は，「4.6　RPC通信機能」を参照してください。

性能/障害調査
同期型dc_rpc_call関数のタイムアウト時のサーバ負荷軽減機能
×
アプリケーションサーバでは，クライアント側のタイムアウトに関係なく，サービス応答を実行します。

性能トレース取得機能
○
使用できます。
ただし，出力ファイルおよびファイルの内容は，アプリケーションサーバの性能解析トレースとしてのものになります。

OpenTP1デバッグ情報取得機能
×
OpenTP1独自のログは使用できません。
アプリケーションサーバでは，性能解析トレースまたはメッセージログを使用してデバッグを実行する必要があります。

RPCトレース
×
OpenTP1独自のログは使用できません。
アプリケーションサーバでは，通信トレースに相当するログは取得できません。ただし，クライアントのOpenTP1側のRPCトレースや，性能解析トレースを使用してリクエストの調査は実現できます。

統計情報取得
×
OpenTP1独自のログは使用できません。
ただし，アプリケーションサーバの稼働統計情報は取得できます。

監査ログ
×
OpenTP1独自の監査ログは使用できません。
ただし，アプリケーションサーバの監査ログは使用できます。

そのほか
MCFサービス
×
使用できません。

XATMIインタフェース(X/Open準拠)を使った通信
×

TXインタフェース(X/Open準拠)を使った通信
×

TxRPCインタフェース(X/Open準拠) を使った通信
×

OSI TPプロトコルを使った通信
×

（凡例）

○：使用できる

×：使用できない

△：使用できるが機能差がある

注※

dc_rpc_call関数で呼び出されたSPP内で，呼び出し元のサービスに対してee_rpc_call関数を発行する機能です。

4.5　コネクション管理機能

この節では，コネクション管理機能について説明します。

＜この節の構成＞

4.5.1　コネクション管理機能の概要

4.5.2　コネクション接続要求の受信

4.5.3　電文の受信

4.5.4　コネクション接続要求の送信

4.5.5　電文の送信

4.5.6　一時クローズ処理によるコネクション数の調整

4.5.7　コネクション接続要求または電文送信失敗時のリトライ

4.5.1　コネクション管理機能の概要

コネクション管理機能は，OpenTP1とTP1インバウンドアダプタ間のコネクションの接続，切断，およびプーリングを制御する機能です。コネクションを接続したままで，OpenTP1とTP1インバウンドアダプタの間で通信できます。そのため，コネクションの接続・切断に伴うボトルネックを削減し，通信効率が向上します。

コネクション管理機能が管理するコネクションは2種類あります。コネクション管理機能が管理するコネクションの種類，および役割について次の表に示します。

表4-4　コネクション管理機能が管理するコネクションの種類および役割

コネクションの種類
コネクションの役割

RPC受信コネクション
OpenTP1からのRPC要求を受信します。

RPC送信コネクション
OpenTP1へのRPC応答を送信します。
また，トランザクション連携機能を使用している場合，OpenTP1との同期点処理の送受信をします。

なお，一時クローズ処理の送受信では，どちらのコネクションも使用します。一時クローズ処理については，「4.5.6　一時クローズ処理によるコネクション数の調整」を参照してください。

TP1インバウンドアダプタでのコネクション管理機能の概要と位置づけについて次の図に示します。

図4-2　コネクション管理機能の位置づけ

OpenTP1からの接続要求をRPC待ち受けポートで受け付けます。受け付けた要求は，RPC受信監視スレッド内にあるRPC受信コネクションが受信します。RPC受信監視スレッドがRPC受信コネクションの受信を検知すると，RPC通信機能のリクエスト受け付けスレッドへリクエストを送信します。

コネクション管理機能は，次の要素で構成されています。

RPC待ち受けポート
OpenTP1からのRPC要求を受信する際にコネクションの接続要求を待ち受けるポートです。TP1インバウンドアダプタの開始時に開き，終了時に閉じます。

RPC監視スレッド
RPC受信コネクションに電文が送信されてきているかどうかを監視するスレッドです。RPC受信コネクションで電文の受信を検知すると，RPC通信機能のリクエスト受け付けスレッドに電文受信処理を渡します。
TP1インバウンドアダプタの開始時に作成し，終了時に消滅します。

同期点待ち受けポート
RPC応答を送信したRPC送信コネクションが切断済みの場合に，同期点待ち受けポートを利用してOpenTP1からRPC送信コネクションを接続します。
すでにRPC応答を送信したコネクションがある場合はそのコネクションを使って同期点処理を実行します。
TP1インバウンドアダプタの開始時に開き，終了時に閉じます。

同期点監視スレッド
RPC送信コネクションに電文が送信されてきているかどうかを監視するスレッドです。RPC送信コネクションでの電文の受信を検知すると，トランザクション連携機能の同期点電文送受信スレッドに電文受信処理を渡します。
TP1インバウンドアダプタの開始時に作成し，終了時に消滅します。

コネクション数調整スレッド
OpenTP1とのコネクションの接続数を監視し，一定のしきい値に達した場合に一時クローズ処理によって未使用のコネクションを切断するスレッドです。
コネクション数調整スレッドは，RPC受信コネクションとRPC送信コネクションをまとめて監視するため，TP1インバウンドアダプタごとに1スレッドが動作します。
コネクション数調整スレッドは，TP1インバウンドアダプタの開始時に作成し，終了時に消滅します。
一時クローズ処理については，「4.5.6　一時クローズ処理によるコネクション数の調整」を参照してください。

コネクション管理機能は，OpenTP1とアプリケーションサーバ間の通信で必要となる，コネクションに関する次の処理を制御します。

コネクション接続要求の受信

電文の受信

コネクション接続要求の送信

電文の送信

一時クローズ処理によるコネクション数の調整

コネクション接続要求または電文送信失敗時のリトライ

4.5.2　コネクション接続要求の受信

OpenTP1とTP1インバウンドアダプタ間で通信する際，接続済みのコネクションがあれば利用し，なければOpenTP1からTP1インバウンドアダプタへコネクション接続要求を送信してコネクションを接続します。

OpenTP1からのコネクションの接続要求は，RPC待ち受けポート，または同期点待ち受けポートで受け取ります。それぞれのポートが，OpenTP1からのコネクションの接続要求を受け取ったときの動作，およびコネクション接続要求に関する設定について説明します。

＜この項の構成＞

(1)　RPC待ち受けポートがコネクション接続要求を受信した際の動作

(2)　同期点待ち受けポートがコネクション接続要求を受信した際の動作

(3)　コネクション接続要求に関する設定

(4)　コネクション接続要求に失敗する原因およびOpenTP1での動作

(1)　RPC待ち受けポートがコネクション接続要求を受信した際の動作

TP1インバウンドアダプタのRPC待ち受けポートが，コネクション接続要求を受信した際の動作を次に示します。

図4-3　RPC待ち受けポートがコネクション接続要求を受信した際の動作

OpenTP1がRPC待ち受けポートに対してコネクション接続要求を送信します。コネクション接続要求は，TP1インバウンドアダプタが動作するOSのListenキュー（backlog）に格納されます。

TP1インバウンドアダプタのコネクション管理機能では，RPC監視スレッドがListenキューのコネクション接続要求を受信し，OpenTP1とのコネクションを確立します。

RPC監視スレッドは，確立したコネクションがOpenTP1から電文を受信しているかどうか監視を始めます。

(2)　同期点待ち受けポートがコネクション接続要求を受信した際の動作

TP1インバウンドアダプタの同期点待ち受けポートが，コネクション接続要求を受信した際の動作を次に示します。

図4-4　同期点待ち受けポートがコネクション接続要求を受信した際の動作

OpenTP1の同期点処理は，RPC応答を受信したコネクションを使用します。このコネクションが切断されていた際に，TP1インバウンドアダプタの同期点待ち受けポートにOpenTP1がコネクション接続要求をします。

OpenTP1が，同期点待ち受けポートに対してコネクション接続要求を送信します。コネクション接続要求は，TP1インバウンドアダプタが動作するOSのListenキュー（backlog）に格納されます。

TP1インバウンドアダプタのコネクション管理機能では，同期点監視スレッドがListenキューのコネクション接続要求を受信し，OpenTP1とのコネクションを確立します。

同期点監視スレッドは，確立したコネクションがOpenTP1から電文を受信しているかどうか監視を始めます。

(3)　コネクション接続要求に関する設定

コネクション接続要求に関する設定のうち，Connector属性ファイルに指定する項目は次のとおりです。

Listenキューの長さ

backlog_countプロパティ

コネクション接続要求を受信するポート番号

scd_portプロパティ

trn_portプロパティ

コネクションの最大同時接続数

max_connectionsプロパティ

trn_max_connectionsプロパティ

指定方法の詳細については，「4.11.2　リソースアダプタの設定」を参照してください。

コネクション接続要求に関する設定のうち，IPアドレス（バインド先アドレス）については，usrconf.properties（J2EEサーバ用ユーザプロパティファイル）のejbserver.jca.adapter.tp1.bind_hostプロパティに設定します。

バインド先アドレスを指定すると，TP1インバウンドアダプタが動作するホストが複数の物理ネットワークインタフェースを持つ場合に，特定のIPアドレスだけを使用するように設定できます。この設定をしない場合は，システムによって自動的に選択されたローカルアドレスが使用されます。指定方法の詳細については，「4.11.1　J2EEサーバの設定」を参照してください。

(4)　コネクション接続要求に失敗する原因およびOpenTP1での動作

TP1インバウンドアダプタが次に示す条件に当てはまる場合，OpenTP1からのコネクション接続要求に失敗します。コネクション接続要求に失敗する原因，およびOpenTP1での動作について説明します。

表4-5　コネクション接続要求に失敗する原因およびOpenTP1での動作

コネクション接続要求に失敗する原因
OpenTP1での動作

TP1インバウンドアダプタが起動していない

TP1インバウンドアダプタで通信障害が発生している

OpenTP1のdc_rpc_call関数，または同期点処理がエラーを返します。※

OSのListenキューにコネクション接続要求が上限まで滞留している状態で，OpenTP1が新たなコネクション接続要求を送信した（Listenキューあふれ）
新たなコネクション接続要求は，OSのListenキューによって拒否されます。OpenTP1のdc_rpc_call関数，または同期点処理がエラーを返します。※

コネクションの接続数がコネクション管理機能の最大同時接続数の設定値に達している
コネクション接続要求は，コネクションの接続数が最大同時接続数未満になるまでOSのListenキューに滞留します。OpenTP1のdc_rpc_call関数，または同期点処理は最大応答待ち時間に達してからエラーを返します。※

注※　エラーコードについては，「4.16　TP1インバウンドアダプタで発生するRPCエラー応答」を参照してください。

4.5.3　電文の受信

OpenTP1からの接続要求を受け，TP1インバウンドアダプタで電文を受信します。

TP1インバウンドアダプタがOpenTP1から受信する電文は，RPC要求，および同期点処理です。それぞれの電文を受信したときの動作について説明します。

＜この項の構成＞

(1)　RPC要求受信時の動作

(2)　同期点処理の受信時の動作

(3)　電文の受信に関する設定

(1)　RPC要求受信時の動作

TP1インバウンドアダプタがRPC要求を受信したときの動作を次に示します。

図4-5　RPC要求受信時の動作

コネクション管理機能のRPC監視スレッドは，電文受信中でないRPC受信コネクションがOpenTP1からの電文を受信していないかを監視します。

RPC監視スレッドがOpenTP1からの電文の受信を検知します。RPC監視スレッドは該当するコネクションで電文の受信が開始したことをRPC通信機能に通知します。RPC監視スレッドは，ほかのRPC受信コネクションがOpenTP1からの電文を受信していないかどうか監視を続けます。RPC通信機能の詳細は，「4.6　RPC通信機能」を参照してください。

RPC通信機能のリクエスト受け付けスレッドは，電文の受信開始が通知されたコネクションから，順次OpenTP1からの電文を受信します。

リクエスト受け付けスレッドは，OpenTP1からの電文の受信を完了すると，該当するコネクションでの受信が完了したことをコネクション管理機能に通知します。これによって，RPC受信監視スレッドは該当するコネクションで次の電文を受信していないかどうかの監視を始めます。

(2)　同期点処理の受信時の動作

TP1インバウンドアダプタが同期点処理を受信したときの動作を次に示します。

図4-6　同期点処理の受信時の動作

コネクション管理機能の同期点監視スレッドは，電文受信中でないRPC送信コネクションがOpenTP1からの電文を受信していないかどうか監視します。

同期点監視スレッドがOpenTP1からの電文の受信を検知すると，同期点監視スレッドは該当するコネクションで電文の受信が開始したことをトランザクション管理機能に通知します。同期点監視スレッドは，ほかのRPC送信コネクションがOpenTP1からの電文を受信していないかどうかの監視を続けます。詳細は，「4.8　トランザクション連携機能」を参照してください。

トランザクション連携機能の同期点電文送受信スレッドは，電文の受信開始が通知されたコネクションから，順次OpenTP1からの電文を読み込みます。

同期点電文送受信スレッドは，OpenTP1からの電文の受信を完了すると，使用しているコネクションでの受信が完了したことをコネクション管理機能に通知します。これによって，同期点監視スレッドは該当するコネクションで次の電文を受信していないかどうかの監視を始めます。

(3)　電文の受信に関する設定

電文の受信に関する設定は，Connector属性ファイルに指定します。指定する項目は次のとおりです。

電文受信時のTCP/IPのバッファサイズ

receive_buffer_sizeプロパティ

受信タイムアウト時間

tcp_receive_timeoutプロパティ

指定方法の詳細については，「4.11.2　リソースアダプタの設定」を参照してください。

4.5.4　コネクション接続要求の送信

TP1インバウンドアダプタがOpenTP1と通信する際に，送信先のOpenTP1と接続済みのコネクションがある場合は，接続済みのコネクションを利用します。接続済みのコネクションがない場合は，コネクション接続要求を送信してコネクションを接続します。

TP1インバウンドアダプタからOpenTP1へのコネクションの接続要求には，RPC応答，および同期点処理の2種類があります。それぞれのコネクション接続要求を送信したときの動作について説明します。

＜この項の構成＞

(1)　RPC応答および同期点処理でのコネクション接続要求送信時の動作

(2)　コネクション接続要求の送信に関する設定

(3)　コネクション接続要求に失敗する原因およびTP1インバウンドアダプタでの動作

(1)　RPC応答および同期点処理でのコネクション接続要求送信時の動作

RPC応答および同期点処理でのコネクション接続要求送信時の動作について，次の図に示します。

図4-7　RPC応答および同期点処理でのコネクション接続要求送信時の動作

それぞれの動作の流れについて，(a)および(b)で説明します。

(a)　RPC応答でのコネクション接続要求送信時の動作

RPC応答でのコネクション接続要求は，RPC通信機能のリクエスト受け付けスレッド，スケジュール機能のMessage-driven Bean（サービス）呼び出しスレッド，およびMessage-driven Bean（サービス）の停止処理を実行するスレッドが送信します。コネクション接続要求をOpenTP1に送信する際の流れを次に示します。

TP1インバウンドアダプタからOpenTP1へコネクション接続要求を送信します。コネクション接続要求は，OpenTP1が動作するOSのListenキュー（backlog）に格納されます。

OpenTP1がListenキューのコネクション接続要求を受信し，TP1インバウンドアダプタとのコネクションを確立します。

コネクションが確立したら，同期点監視スレッドは，OpenTP1への電文の送信と並行してOpenTP1からの電文を受信できるようにRPC送信コネクションがOpenTP1から電文を受信しているかどうかの監視を始めます。

(b)　同期点処理でのコネクション接続要求送信時の動作

同期点処理でのコネクション接続要求は，トランザクション連携機能の同期点電文送受信スレッドが送信します。コネクション接続要求をOpenTP1に送信する際の流れを次に示します。

TP1インバウンドアダプタからOpenTP1へコネクション接続要求を送信します。コネクション接続要求は，OpenTP1が動作するOSのListenキュー（backlog）に格納されます。

OpenTP1が，Listenキューのコネクション接続要求を受信し，TP1インバウンドアダプタとのコネクションを確立します。

コネクションが確立したら，同期点監視スレッドは，OpenTP1への電文の送信と並行してOpenTP1からの電文を受信できるように，RPC送信コネクションがOpenTP1から電文を受信しているかどうかの監視を始めます。

(2)　コネクション接続要求の送信に関する設定

コネクション接続要求の送信に関する設定は，Connector属性ファイルに指定します。指定する項目は次のとおりです。

コネクションの最大同時接続数

max_connectionsプロパティ

trn_max_connectionsプロパティ

コネクション接続失敗時のリトライ

send_retry_countプロパティ

send_retry_intervalプロパティ

コネクション接続時のタイムアウト時間

connection_timeoutプロパティ

指定方法の詳細については，「4.11.2　リソースアダプタの設定」を参照してください。

(3)　コネクション接続要求に失敗する原因およびTP1インバウンドアダプタでの動作

OpenTP1が，TP1インバウンドアダプタからのコネクション接続要求の受信に失敗する原因，およびTP1インバウンドアダプタでの動作を次に示します。

表4-6　コネクション接続要求に失敗する原因およびTP1インバウンドアダプタでの動作

コネクション接続要求に失敗する原因
TP1インバウンドアダプタでの動作

OpenTP1に障害が発生している

通信障害が発生している

TP1インバウンドアダプタは，コネクション接続要求をリトライします。※1
リトライしてもコネクションを接続できなかった場合は，エラーメッセージ（KDJE58400-E）を出力して未送信の電文を破棄します。

OSのListenキューにコネクション接続要求が上限まで滞留している状態で，TP1インバウンドアダプタが新たなコネクション接続要求を送信した（Listenキューあふれ）

TCP送信コネクション接続タイムアウトが発生した
TP1インバウンドアダプタは，エラーメッセージ（KDJE58400-E）を出力して未送信の電文を破棄します。

コネクションの接続数が最大同時接続数に達している
TP1インバウンドアダプタは，コネクションの接続数が最大同時接続数未満になるまでコネクション接続要求の送信を待機します。※2

注※1　コネクション接続要求のリトライについては，「4.11.2　リソースアダプタの設定」を参照してください。

注※2　どのコネクションからも一時クローズ処理の応答が返ってこない場合に，コネクションを切断できなかったとき，指定した一時クローズ応答の待ち時間が経過すると，TP1インバウンドアダプタは一時クローズ要求の応答を待つコネクションを強制的に切断します。このため，コネクション接続要求の送信を待ち続けることはありません。

4.5.5　電文の送信

TP1インバウンドアダプタがOpenTP1へ電文を送信する際の動作を次に示します。

図4-8　電文の送信する流れ

＜この項の構成＞

(1)　RPC応答と同期点処理送信時の動作

(2)　電文の送信時の設定

(1)　RPC応答と同期点処理送信時の動作

RPC応答は，RPC通信機能のリクエスト受け付けスレッド，受信タイマ監視スレッド，スケジュール機能のMessage-driven Bean（サービス）呼び出しスレッド，およびMessage-driven Bean（サービス）の停止処理を実行するスレッドが送信します。同期点処理は，トランザクション連携機能の同期点電文送受信スレッドが送信します。

次にRPC応答と同期点処理をOpenTP1に送信するときの流れを示します。

OpenTP1へ電文を送信する際，コネクション管理機能から送信先のOpenTP1とのコネクションを取得します。

コネクションを取得したスレッドは，取得したコネクションを使用してOpenTP1へ電文を送信します。

(2)　電文の送信時の設定

電文の送信時の設定は，Connector属性ファイルに指定します。指定する項目は次のとおりです。

電文送信時のTCP/IPのバッファサイズ

send_buffer_sizeプロパティ

送信リトライ

send_retry_countプロパティ

send_retry_intervalプロパティ

送信タイムアウト時間

tcp_send_timeoutプロパティ

指定方法の詳細については，「4.11.2　リソースアダプタの設定」を参照してください。

4.5.6　一時クローズ処理によるコネクション数の調整

OpenTP1とTP1インバウンドアダプタでは，コネクション接続時のオーバーヘッドを削減するために，一度接続したコネクションを切断しないで次回の通信で再利用します。そのため，コネクション管理機能の最大同時接続数の設定よりも多くの接続を受け付けるシステムでは，コネクションの接続数がすぐに最大同時接続数に達してしまいます。

これを防ぐために，コネクションの接続数が一定のしきい値に達したところで未使用のコネクションを切断する機能（一時クローズ処理）を使用します。

一時クローズ処理によってコネクション数を調整することで，コネクションを枯渇させることなく，効率良くコネクションを管理できます。

一時クローズ処理は，OpenTP1側から実行する場合と，TP1インバウンドアダプタ側から実行する場合の2種類があります。どちらの場合も，接続先に一時クローズ処理要求を送信して，接続先から一時クローズ処理応答を受信したタイミングでコネクションを切断します。一時クローズ処理要求の送信と一時クローズ処理の応答の受信は，非同期に処理されます。

なお，OpenTP1とTP1インバウンドアダプタ間のコネクションが一時クローズ処理中であっても，新しいRPC要求を受け付けることができます。また，新たなコネクションを接続することでRPC応答を送信することができるため，一時クローズ処理によってOpenTP1やTP1インバウンドアダプタでの処理がエラーになることはありません。

＜この項の構成＞

(1)　一時クローズ処理対象とするコネクション数の指定

(2)　一時クローズ処理の対象外とするコネクション数の指定

(3)　コネクション数が最大に達した際の一時クローズ処理の応答待ち時間の指定

(4)　一時クローズ処理に関する設定

(1)　一時クローズ処理対象とするコネクション数の指定

処理開始のしきい値には，TP1インバウンドアダプタが一時クローズ処理を開始するコネクション数の割合をパーセンテージで指定します。指定したしきい値に応じて，コネクションの種類ごとに次の条件で一時クローズ処理を開始します。

RPC受信コネクションの一時クローズ処理開始の条件

RPC受信コネクション数 ≧

RPC受信コネクションの最大同時接続数 ×

RPC受信コネクションの一時クローズ処理開始のしきい値 ／ 100

RPC送信コネクションの一時クローズ処理開始の条件

RPC送信コネクション数 ≧

RPC送信コネクションの最大同時接続数 ×

RPC送信コネクションの一時クローズ処理開始のしきい値 ／ 100

(2)　一時クローズ処理の対象外とするコネクション数の指定

一時クローズ処理の対象外とするコネクション数の割合をパーセンテージで指定します。

RPC受信コネクションの一時クローズ処理非対象コネクション数の算出

RPC受信コネクションの一時クローズ処理非対象コネクション数＝

RPC受信コネクションの最大同時接続数 ×

RPC受信コネクションの一時クローズ処理非対象とするコネクション数の割合／100

RPC送信コネクションの一時クローズ処理非対象コネクション数の算出

RPC送信コネクションの一時クローズ処理非対象コネクション数＝

RPC送信コネクションの最大同時接続数 ×

RPC送信コネクションの一時クローズ処理非対象とするコネクション数の割合／100

(3)　コネクション数が最大に達した際の一時クローズ処理の応答待ち時間の指定

一時クローズ処理では，コネクションを接続したOpenTP1とTP1インバウンドアダプタ間で，どちらかから一時クローズ処理の要求を送信したあと，その応答を受信してからコネクションを切断します。一時クローズ処理の応答を受信するまでコネクションを切断することはできません。

一時クローズ処理要求後にどのコネクションからも応答が返ってこなければ，コネクション数に空きができないため，新たなコネクションを接続することができなくなります。これを防ぐため，TP1インバウンド連携機能では，一時クローズ応答の待ち時間を指定することで，コネクション数が最大に達してからコネクション数に空きができるまでの時間を監視します。指定した一時クローズ応答の待ち時間を経過してもコネクション数が最大値のままの場合，エラーメッセージを出力してコネクションを切断します。

RPC受信コネクション，および送信コネクションでのコネクション数の監視について説明します。

(a)　RPC受信コネクションでのコネクション数の監視

RPC受信コネクションが最大RPC受信コネクション数に達してから，一時クローズ処理によってコネクション数に空きができるまでの時間を監視します。

指定した一時クローズ応答の待ち時間を経過しても，コネクション数が最大RPC受信コネクション数のままの場合は，エラーメッセージ（KDJE58501-E）を出力し，一時クローズ処理の応答を待っているRPC受信コネクションをすべて切断します。

(b)　RPC送信コネクションでのコネクション数の監視

RPC受信コネクション同様に，RPC送信コネクションが最大RPC送信コネクション数に達してから，一時クローズ処理によってコネクション数に空きができるまでの時間を監視します。

指定した一時クローズ応答の待ち時間を経過しても，コネクション数が最大RPC送信コネクション数のままの場合は，エラーメッセージ（KDJE58501-E）を出力し，一時クローズ処理の応答を待っているRPC送信コネクションをすべて切断します。

(4)　一時クローズ処理に関する設定

一時クローズ処理に関する設定は，Connector属性ファイルに指定します。指定する項目は次のとおりです。

RPC受信コネクションの一時クローズ処理

rpc_sockctl_highwaterプロパティ

rpc_sockctl_lowwaterプロパティ

RPC送信コネクションの一時クローズ処理

trn_sockctl_highwaterプロパティ

trn_sockctl_lowwaterプロパティ

一時クローズ応答の待ち時間

ipc_sockctl_watchtimeプロパティ

指定方法の詳細については，「4.11.2　リソースアダプタの設定」を参照してください。

4.5.7　コネクション接続要求または電文送信失敗時のリトライ

コネクション管理機能では，OpenTP1へのコネクション接続要求に失敗した場合，または電文送信に失敗した場合に，リトライします。コネクション接続要求に失敗した場合は，再度コネクション接続要求を試みます。電文送信に失敗した場合は，コネクションを切断して，新たなコネクションを接続してから再度送信を試みます。

ただし，コネクション接続要求時または電文送信時にタイムアウトが発生した場合は，リトライしません。コネクションのタイムアウトについては「4.13　OpenTP1とアプリケーションサーバ間のタイムアウトの設定」を参照してください。

＜この項の構成＞

(1)　リトライ時に出力されるメッセージ

(2)　コネクション接続要求または電文送信失敗時のリトライに関する設定

(1)　リトライ時に出力されるメッセージ

コネクション管理機能では，初回のリトライ時にだけ警告メッセージを出力します。リトライ時に出力する警告メッセージについて次に示します。

表4-7　リトライ時に出力する警告メッセージ

リトライの種別 | メッセージ
コネクション接続要求のリトライ | KDJE58402-W
電文送信のリトライ | KDJE58403-W

コネクション接続要求が設定したリトライ回数分失敗した場合，未送信の電文を破棄します。

また，電文送信のリトライが設定したリトライ回数分失敗した場合，コネクションを切断して未送信の電文を破棄します。これらの場合，最後のリトライの種別に応じて次のエラーメッセージを出力します。

表4-8　リトライ回数までリトライしても失敗した場合のエラーメッセージ

リトライの種別 | メッセージ
コネクション接続要求のリトライ | KDJE58400-E
電文送信のリトライ | KDJE58401-E

(2)　コネクション接続要求または電文送信失敗時のリトライに関する設定

コネクション接続要求または電文送信失敗時のリトライの設定は，Connector属性ファイルに指定します。指定する項目は次のとおりです。

コネクション接続要求または電文送信失敗時のリトライ

send_retry_countプロパティ

send_retry_intervalプロパティ

指定方法の詳細については，「4.11.2　リソースアダプタの設定」を参照してください。

4.6　RPC通信機能

この節では，RPC通信機能について説明します。

＜この節の構成＞

4.6.1　RPC通信機能の概要

4.6.2　RPC要求の受信と組み立て

4.6.3　RPC要求のチェック

4.6.4　RPC応答の生成から送信まで

4.6.5　最大同時RPC要求受け付け数および受信タイムアウト

4.6.1　RPC通信機能の概要

RPC通信機能は，OpenTP1から受信したRPC要求を解析・組み立てし，OpenTP1に送信するRPC応答を生成・分割する機能です。

TP1インバウンドアダプタでのRPC通信機能の位置づけを次の図に示します。

図4-9　RPC通信機能の位置づけ

RPC通信機能は，次の要素で構成されます。

リクエスト受け付けスレッド
OpenTP1からのRPC要求を受け付けるスレッドです。
TP1インバウンドアダプタの開始時に最大同時接続数分だけ作成し，TP1インバウンドアダプタ終了時に消滅します。最大同時接続数の設定については，「4.6.5　最大同時RPC要求受け付け数および受信タイムアウト」で説明します。

受信タイマ監視スレッド
RPC要求の受信タイムアウトを監視するスレッドです。TP1インバウンドアダプタごとに1スレッドが動作します。
受信タイマ監視スレッドは，TP1インバウンドアダプタの開始時に作成し，終了時に消滅します。

RPC通信機能では，OpenTP1とアプリケーションサーバ間でRPC通信によって電文を送受信するための次の処理を制御します。

RPC要求の受信と組み立て

RPC要求のチェック

RPC応答の生成から送信まで

最大同時RPC要求受け付け数および受信タイムアウト

OpenTP1では，電文を分割して送受信します。このため，TP1インバウンドアダプタでは，RPC通信の際に，受信した電文の組み立ておよび送信する電文の分割処理を実行します。

なお，RPC要求の受信とRPC応答の送信には，別のコネクションを使用します。

4.6.2　RPC要求の受信と組み立て

コネクションの確立後，OpenTP1からのRPC要求が，32キロバイトずつに分割された電文として送信されます。

RPC通信機能のリクエスト受け付けスレッドは，コネクション管理機能によって割り当てられたコネクションを使用して，分割された電文を順次受信し，一つの要求電文として組み立てます。

電文の受信と組み立ての流れを次の図に示します。

図4-10　電文の受信と組み立ての流れ

TP1インバウンドアダプタでは，分割された電文を受信すると，データチェックを実行します。データチェックで正常と判定した電文について，組み立てを実行します。組み立て後，次の電文を受信します。最後の電文の場合は，最後のデータチェックを実行し，電文受信を終了します。なお，データチェックで電文の異常を検知した場合は，エラー応答を送信します。

要求電文の受信中に，ネットワーク障害やOpenTP1の障害などによってコネクションが切断された場合，TP1インバウンドアダプタはエラーメッセージ（KDJE58354-E）を出力して電文の受信処理を中断します。なお，OpenTP1では，コネクションの切断を検知すると，再度コネクションを確立して，送信の途中だった電文の送信をリトライします。TP1インバウンドアダプタでは，OpenTP1からのリトライに備え，受信済みの電文を電文組み立てリストに保持します。電文組み立てリストは，最大同時接続数分保持できます。このリストは，残りの電文をすべて受信し終えるか，またはRPC要求の受信タイムアウトが発生するまで保持されます。

コネクション障害が頻発することによって電文組み立てリストが蓄積して電文の組み立てができなくなると，新たなRPC要求の受信ができなくなります。この場合，エラーメッセージ（KDJE58359-E）が出力されます。また，呼び出し元のdc_rpc_call関数にはRPCエラー（トランザクショナルRPCでない場合はDCRPCER_NO_BUFS(-304)，トランザクショナルRPCの場合はDCRPCER_NET_DOWN(-323)）が返されます。

電文組み立てリストが不足した状態は，OpenTP1から残りの電文がすべて再送されるか，またはRPC要求の受信タイムアウトが発生すると，解消します。

RPC要求の受信時のエラー，および電文組み立てリストが不足した場合のエラーについては，「4.16　TP1インバウンドアダプタで発生するRPCエラー応答」を参照してください。

また，最大同時接続数，および要求電文の受信処理のタイムアウトの設定は，Connector属性ファイルに指定します。指定する項目は次のとおりです。

最大同時接続数

max_connectionsプロパティ

要求電文の受信処理のタイムアウト

rpc_receive_timeoutプロパティ

指定方法の詳細については，「4.11.2　リソースアダプタの設定」を参照してください。

4.6.3　RPC要求のチェック

RPC通信機能では，受信した電文の形式と内容をチェックします。チェック内容および不正を検知した場合の動作を次に示します。

電文形式のチェック
受信したRPC要求がOpenTP1から送信された電文かどうかをチェックします。
不正を検知した場合は，エラーメッセージ（KDJE58355-E）を出力して，コネクションを切断します。応答送信はしません。エラーの詳細については，「4.16　TP1インバウンドアダプタで発生するRPCエラー応答」を参照してください。

TP1インバウンドアダプタで使用できない機能を使用していないかのチェック
TP1インバウンドアダプタで使用できないOpenTP1の機能を使用していないかどうかをチェックします。TP1インバウンドアダプタで使用できる機能については，「4.16　TP1インバウンドアダプタで発生するRPCエラー応答」を参照してください。
不正を検知した場合は，エラーメッセージ（KDJE58356-E）を出力して，コネクションを切断します。また，呼び出し元のdc_rpc_call関数にRPCエラーを応答します。エラーの詳細については，「4.16　TP1インバウンドアダプタで発生するRPCエラー応答」を参照してください。

dc_rpc_call関数の引数チェック
呼び出し元のdc_rpc_call関数の引数が適切に指定されているかどうかをチェックします。
不正を検知した場合は，エラーメッセージを出力して，コネクションを切断します。また，呼び出し元のdc_rpc_call関数にRPCエラーを応答します。
引数チェックでチェックされる内容，不正検知時に出力されるエラーメッセージ，およびRPCエラー応答について次の表に示します。

表4-9　dc_rpc_call関数の引数チェック

引数
チェック内容
不正検知時のエラーメッセージ
不正検知時のRPCエラー応答

group
引数に指定したサービスグループ名が，TP1インバウンドアダプタのサービスグループ名（Connector属性ファイルに指定したservice_groupプロパティ）と一致しているか。
KDJE58357-E
DCRPCER_SERVICE_NOT_UP(-314)

service
引数に指定したサービス名が，TP1インバウンドアダプタが呼び出すサービス名（Message-driven Bean（サービス）のActivationSpecのserviceプロパティ）の中に存在するか。
KDJE58362-E
DCRPCER_NO_SUCH_SERVICE(-311)

flags
引数に指定したRPC形態が，TP1インバウンドアダプタで利用できる次のどちらかの形態か。

DCNOFLAGS（同期応答型RPC）

DCNOFLAGS|DCRPC_TPNOTRAN（同期応答型，かつトランザクションを引き継がないRPC）

KDJE58356-E
DCRPCER_TIMED_OUT(-307)

エラーの詳細については，「4.16　TP1インバウンドアダプタで発生するRPCエラー応答」を参照してください。

4.6.4　RPC応答の生成から送信まで

ここでは，RPC応答の生成から送信までの処理について説明します。

＜この項の構成＞

(1)　応答電文生成

(2)　応答電文の分割と送信

(1)　応答電文生成

RPC通信機能が呼び出し元に送信する電文を生成します。

(2)　応答電文の分割と送信

RPC通信機能では，一つのRPC応答電文を32KBごとに分割して順次送信します。

送信にはコネクション管理機能のコネクションを使用します。応答電文の送信処理には，リトライやタイムアウトを設定できます。設定方法については，「4.13　OpenTP1とアプリケーションサーバ間のタイムアウトの設定」を参照してください。

4.6.5　最大同時RPC要求受け付け数および受信タイムアウト

最大同時RPC要求受け付け数および受信タイムアウトを指定する項目は次のとおりです。

OpenTP1から受信したRPC要求の最大同時RPC要求受け付け数

rpc_max_thread_countプロパティ
Connector属性ファイルの指定方法の詳細については，「4.11.2　リソースアダプタの設定」を参照してください。

RPC要求受信のタイムアウト時間
詳細については，「4.13　OpenTP1とアプリケーションサーバ間のタイムアウトの設定」を参照してください。

4.7　スケジュール機能

この節では，スケジュール機能について説明します。

＜この節の構成＞

4.7.1　スケジュール機能の概要

4.7.2　スケジュールキューの制御

4.7.3　Message-driven Bean（サービス）の同時実行数の制御

4.7.4　サービス実行のタイムアウト

4.7.1　スケジュール機能の概要

スケジュール機能は，RPC通信機能によって受信したRPC要求電文をJ2EEサーバで効率良く処理するための機能です。TP1/Server Baseのスケジュールサービスの一部の機能に相当します。

TP1インバウンドアダプタでのスケジュール機能の位置づけを次の図に示します。

図4-11　スケジュール通信機能の位置づけ

スケジュール機能は，次の要素で構成されます。

スケジュールキュー
RPC通信機能によって受信したRPC要求を保持するキューです。RPC要求は，FIFO方式で保持します。
スケジュールキューは，Message-driven Bean（サービス）開始時にMessage-driven Bean（サービス）ごとに一つ作成され，Message-driven Bean（サービス）の終了時に削除されます。

Message-driven Bean（サービス）実行制御スレッド
スケジュールキューからRPC要求を取り出して，空いているMessage-driven Bean（サービス）呼び出しスレッドに処理を委譲します。
Message-driven Bean（サービス）実行制御スレッドは，Message-driven Bean（サービス）開始時に，Message-driven Bean（サービス）ごとに一つ作成され，Message-driven Bean（サービス）の終了時に削除されます。

Message-driven Bean（サービス）呼び出しスレッド
Message-driven Bean（サービス）を実行するスレッドです。Connector 1.5仕様に準拠したWorkManagerによって管理されます。
Message-driven Bean（サービス）実行制御スレッドがRPC要求をスケジュールキューから取り出して受け付けたときにWorkManagerによって割り当てられます。
RPC応答後は，Message-driven Bean（サービス）呼び出しスレッドはWorkManagerに返されます。WorkManagerが管理するスレッドは，TP1インバウンドアダプタを開始したときに生成され，TP1インバウンドアダプタ終了時に削除されます。
スレッドの詳細については，「4.7.3　Message-driven Bean（サービス）の同時実行数の制御」を参照してください。

Message-driven Bean（サービス）
業務処理を実行するサービスとなるMessage-driven Beanです。OpenTP1のSPPに相当します。

スケジュール機能の処理の流れを次に示します。

Message-driven Bean（サービス）を開始した時に，Message-driven Bean単位にスケジュールキューおよびMessage-driven Bean（サービス）実行制御スレッドが作成されます。

RPC通信機能でのRPC要求受信後，受信したRPC要求はスケジュールキューに格納されます。

スケジュールキューに格納されたRPC要求がMessage-driven Bean（サービス）実行制御スレッドによって取り出されます。このタイミングで，Connector 1.5仕様に準拠したWorkManagerによって，Message-driven Bean（サービス）呼び出しスレッドが割り当てられます。

Message-driven Bean（サービス）実行制御スレッドがMessage-driven Bean（サービス）呼び出しスレッドにRPC要求を委譲します。

Message-driven Bean（サービス）呼び出しスレッドによって，Message-driven Beanが実行されます。

なお，TP1インバウンドアダプタでは，OpenTP1の機能であるスケジュールの優先順位（ユーザサービス定義のschedule_priority）を指定したRPC要求を受信した場合も，優先順位は無視します。優先順位を指定したRPC要求を受信した場合も，優先順序が設定されていないRPC要求と同じように扱い，受信した順番で処理を実行します。

スケジュール機能では，これらの処理をする際に，次の項目を制御できます。

スケジュールキューの制御

Message-driven Bean（サービス）の同時実行数の制御

サービス実行のタイムアウト

4.7.2　スケジュールキューの制御

スケジュールキューの制御では，スケジュールキューの長さを設定できます。また，スケジュールキューに滞留しているRPC要求の数がキュー長に近づいていることを検知するために，スケジュールキューを監視できます。

＜この項の構成＞

(1)　スケジュールキューの長さの設定

(2)　スケジュールキューの監視

(1)　スケジュールキューの長さの設定

スケジュールキューの長さは，Message-driven Bean（サービス）ごとに設定できます。

設定は，Message-driven BeanのActivationSpecのqueue_max_lengthプロパティに設定します。設定を省略した場合は，スケジュールキューの長さは100になります。ActivationSpecの設定については，「4.9.5　ejb-jar.xmlの定義」を参照してください。

スケジュールキューに滞留しているRPC要求の数がキュー長に達している状態で新たにRPC要求が送信されると，スケジュール機能では，エラーメッセージ（KDJE58360-E）を出力します。呼び出し元のdc_rpc_call関数にはRPCエラー(DCRPCER_NO_BUFS(-304))が返されます。エラーの詳細については，「4.16　TP1インバウンドアダプタで発生するRPCエラー応答」を参照してください。

スケジュールキューのキュー長をRPC要求数に対して小さい値を設定していると，キューあふれによってRPCエラーが発生するおそれがあります。そのため，RPC要求に正常に応答するためには，OpenTP1から同時に送信されるRPC要求数と同程度のキュー長を設定してください。ただし，スケジュールキューに保持するRPC要求はメモリ上に保持するため，多くのRPC要求がスケジュールキューに滞留し，メモリ使用量が増加するおそれがあります。TP1インバウンドアダプタのメモリ使用量については，リリースノートでご確認ください。

(2)　スケジュールキューの監視

スケジュール機能では，Message-driven Bean（サービス）ごとにしきい値を設定してスケジュールキューを監視することで，滞留しているRPC要求の数がキュー長に近づいていることを事前に検知できます。しきい値を設定しておくと，スケジュールキューに滞留しているRPC要求の数がしきい値を超えたときに，警告メッセージ（KDJE58361-W）が出力されます。なお，スケジュールキューの監視は，RPC通信機能のリクエスト受け付けスレッドによってRPC要求がスケジュールキューに登録されたタイミングで実行されます。

また，一度しきい値を超えたことを示すメッセージが出力されてから，再度メッセージを出力するまでの間隔（警告メッセージ抑止時間）も設定できます。

これらの設定は，Message-driven BeanのActivationSpecの次のプロパティに指定します。

stay_watch_queue_rateプロパティ
滞留数のしきい値を指定します。監視しない場合は0を指定します。

stay_watch_check_intervalプロパティ
警告メッセージの出力抑止時間を指定します。

ActivationSpecの設定については，「4.9.5　ejb-jar.xmlの定義」を参照してください。

4.7.3　Message-driven Bean（サービス）の同時実行数の制御

スケジュールキューに滞留しているRPC要求は，Message-driven Bean（サービス）実行制御スレッドによって順次取り出され，Connector 1.5仕様に準拠したWorkManagerによって管理されているMessage-driven Bean（サービス）呼び出しスレッドに委譲されます。RPC要求を委譲されたMessage-driven Bean（サービス）呼び出しスレッドによって，Message-driven Bean（サービス）が実行されます。

スケジュール機能では，WorkManagerのMessage-driven Bean（サービス）呼び出しスレッド数と，Message-driven Bean（サービス）のインスタンスプール数によって，同時に実行するRPC要求の数を制御します。

Message-driven Bean同時実行数の制御の概要を次の図に示します。

図4-12　Message-driven Bean同時実行数の制御の概要

Message-driven Bean（サービス）の同時実行数を制御するプロパティについて，次の表に示します。これらの値を適切に設定しないと，正しく同時実行数を制御できません。

表4-10　Message-driven Bean（サービス）の同時実行数を制御するプロパティ

設定項目
設定対象
（設定個所）
指定するタグ名
指定する内容

Message-driven Bean（サービス）の同時実行数
TP1インバウンドアダプタ
(Connector属性ファイル)
<hitachi-connector-property>下の<resourceadapter-runtime><property>の<MaxTPoolSize>
Message-driven Bean（サービス）呼び出しスレッドの最大数

<hitachi-connector-property>下の<resourceadapter-runtime><property>の<MinTPoolSize>
Message-driven Bean（サービス）呼び出しスレッドの最小数

Message-driven Bean（サービス）のインスタンスプール数
Message-driven Bean
(cosminexus.xml
または
MessageDrivenBean属性ファイル)
<pooled-instance><maximum>
Message-driven Bean（サービス）のインスタンスプール数の最大数

<pooled-instance><minimum>
Message-driven Bean（サービス）のインスタンスプール数の最小数（ただし，指定しても常に1とみなされます）

TP1インバウンドアダプタ単位の最大同時実行数は，WorkManagerのスレッドプール（MaxTPoolSize）に指定します。また，個々のMessage-driven Bean（サービス）単位の最大同時実行数は，Message-driven Beanのインスタンスプール（maximum）で指定します。

これらの最大値は，次の関係になるように指定してください。

Message-driven Bean（サービス）呼び出しスレッドの最大数（MaxTPoolSize）≧
それぞれのMessage-driven Bean（サービス）のインスタンスプール（maximum）の総和

注

指定した値がこの式の関係になっていない場合，Message-driven Bean（サービス）開始時に警告メッセージ（KDJE58452-W）が出力されます。

Message-driven Bean（サービス）実行制御スレッドでは，Message-driven Bean（サービス）呼び出しスレッド数がMessage-driven Bean（サービス）のインスタンスプールの最大値（maximum）の総和を超えることがないよう，Message-driven Bean（サービス）呼び出しスレッドの実行数を制御します。MaxTPoolSizeとmaximumの関係が上記の式の関係になっていない場合，RPC要求時にMessage-driven Bean（サービス）呼び出しスレッドまたはMessage-driven Bean（サービス）のインスタンスが不足することがあります。この場合，RPC要求はスケジュールキューに滞留した状態になります。

4.7.4　サービス実行のタイムアウト

Message-driven Bean（サービス）の実行にタイムアウトを設定することで，業務処理で無限ループやデッドロックが発生した場合などに，タイムアウトによって業務を強制的に停止できます。タイムアウトによる業務処理の強制停止には，アプリケーションサーバのメソッドキャンセル機能を使用します。

TP1インバウンドアダプタでのサービス実行のタイムアウトの概要を次の図に示します。

図4-13　TP1インバウンドアダプタでのサービス実行のタイムアウト

Message-driven Bean（サービス）の実行時間を監視することによって，障害が発生して応答がない場合，業務を強制停止して，Message-driven Bean（サービス）呼び出しスレッドでタイムアウトを検知できます。タイムアウトを検知したMessage-driven Bean（サービス）呼び出しスレッドは，OpenTP1にRPCエラー応答を返します。

なお，Message-driven Beanでの処理の実行状態によっては，メソッドキャンセル機能で強制停止を実行できないことがあります。この場合，業務処理の終了後，TP1インバウンドアダプタは呼び出し元のOpenTP1にRPC応答送信を試みます。呼び出し元がRPC最大応答待ち時間の経過によってすでに応答を待っていなかった場合には，応答送信のコネクション確立に失敗するため，エラーメッセージ（KDJE58400-E）が出力されます。

タイムアウトの詳細については，「4.13　OpenTP1とアプリケーションサーバ間のタイムアウトの設定」を参照してください。

4.8　トランザクション連携機能

この節では，トランザクション連携機能について説明します。

＜この節の構成＞

4.8.1　トランザクション連携機能の概要

4.8.2　グローバルトランザクションの範囲

4.8.3　グローバルトランザクションへのMessage-driven Bean（サービス）の参加条件

4.8.4　トランザクショナルRPCの受信と応答

4.8.5　同期点処理

4.8.6　同期点処理の最適化

4.8.7　トランザクション連携機能の設定

4.8.8　トランザクション障害発生時の対処

4.8.1　トランザクション連携機能の概要

トランザクション連携機能は，OpenTP1のSUPが開始したトランザクションにアプリケーションサーバのMessage-driven Bean（サービス）が開始したトランザクションを参加させる機能です。これによって，OpenTP1のSUPでのリソース更新と，アプリケーションサーバのMessage-driven Bean（サービス）でのリソース更新の同期を取り，データの整合性を保てます。

TP1インバウンドアダプタでのトランザクション連携機能の位置づけを次の図に示します。

図4-14　トランザクション連携機能の位置づけ

同期点監視スレッドが，OpenTP1からの同期点処理を受け付けます。RPC送信コネクションは，トランザクション連携機能の同期点電文送受信スレッドに対して，リクエストを送信し，処理を同期します。

トランザクション通信機能は，次の要素で構成されます。

同期点電文送受信スレッド
OpenTP1からの同期点処理（プリペア・コミット・ロールバック）を受信して，トランザクションマネージャ（JTA・OTS）に対してトランザクションの同期点処理を委譲するスレッドです。このスレッドは，TP1インバウンドアダプタの開始時に最大同時同期点処理数分作成し，終了時に消滅します。最大同時同期点処理数の指定方法については「4.11.2　リソースアダプタの設定」を参照してください。

トランザクション連携機能では，次の処理を制御します。

グローバルトランザクションの範囲

グローバルトランザクションへのMessage-driven Bean（サービス）の参加条件

トランザクショナルRPCの受信と応答

同期点処理

同期点処理の最適化

トランザクション連携機能の設定

トランザクション障害発生時の対処

4.8.2　グローバルトランザクションの範囲

トランザクション連携機能で実現できるグローバルトランザクションの範囲について説明します。

グローバルトランザクションとは，OpenTP1のアプリケーションプログラムで開始したトランザクションと，そのトランザクションに参加するRPC通信先のOpenTP1またはアプリケーションサーバのトランザクションの集合であり，データの整合性を確保する範囲となります。

トランザクション連携機能でのグローバルトランザクションの範囲を次の図に示します。

図4-15　トランザクション連携機能でのグローバルトランザクションの範囲

この図の中で示しているすべてのリソースに対して，データの整合性が確保されます。

4.8.3　グローバルトランザクションへのMessage-driven Bean（サービス）の参加条件

OpenTP1のアプリケーションプログラムが開始したトランザクションに，アプリケーションサーバのMessage-driven Bean（サービス）が参加できる条件は二つあります。それぞれについて説明します。

アプリケーションサーバのライトトランザクション機能が無効な場合

ライトトランザクション機能が無効な場合，Message-driven Bean（サービス）はグローバルトランザクションに参加できます。一方，ライトトランザクション機能が有効になっている場合，アプリケーションサーバのトランザクションマネージャを使用できません。このため，ライトトランザクション機能が有効な場合にTP1インバウンドアダプタがOpenTP1からトランザクショナルRPCを受信したときは，エラーメッセージ（KDJE58363-E）を出力し，OpenTP1がRPCエラー（DCRPCER_TRNCHK_EXTEND（-372））を返します。

Message-driven Bean（サービス）のトランザクション属性がRequiredの場合

OpenTP1のトランザクションに参加できるMessage-driven Bean（サービス）について次の表に示します。

表4-11　OpenTP1のトランザクションに参加できるMessage-driven Bean（サービス）

Message-driven Bean（サービス）のトランザクションの設定 | OpenTP1のトランザクションへの参加
タイプ | 属性
CMT | Required | ○
NotSupported | ×
BMT | － | ×

（凡例）

○：OpenTP1のトランザクションに参加できます。

×：OpenTP1のトランザクションに参加できません（Message-driven Bean（サービス）の呼び出しはできます）。この場合，OpenTP1ではノーアクセス最適化が適用されます。

－：該当しません。

4.8.4　トランザクショナルRPCの受信と応答

OpenTP1のSUPがトランザクション処理中にRPC通信をすると，RPC通信先はトランザクションブランチとしてOpenTP1のグローバルトランザクションに参加します。この場合のRPC通信をトランザクショナルRPCと呼びます。

TP1インバウンドアダプタがトランザクショナルRPCを受信して，OpenTP1へ応答を送信するまでの流れを次の図に示します。

図4-16　トランザクショナルRPCの受信と応答

OpenTP1のアプリケーションプログラムがTP1インバウンドアダプタに対してトランザクショナルRPCを送信します。
TP1インバウンドアダプタでは，コネクション管理機能がOpenTP1からの電文を検知して，RPC通信機能のリクエスト受け付けスレッドが電文を受信します。詳細は，「4.5.2　コネクション接続要求の受信」を参照してください。

RPC通信機能のリクエスト受け付けスレッドは，受信した電文がトランザクショナルRPCの場合，OpenTP1とトランザクション連携が可能な設定になっているかどうか（アプリケーションサーバのライトトランザクション機能が無効になっているか）を判定します。なお，受信した電文がトランザクショナルRPCでなければ判定しません。
OpenTP1とトランザクション連携が可能な設定については，「4.8.3　グローバルトランザクションへのMessage-driven Bean（サービス）の参加条件」を参照してください。
OpenTP1とトランザクション連携が可能な設定と判定した場合，リクエスト受け付けスレッドは，トランザクション識別子を生成し，RPC要求に関連づけて，そのRPC要求をスケジュール機能のスケジュールキューに登録します。スケジュール機能の詳細は，「4.7　スケジュール機能」を参照してください。

スケジュール機能のMessage-driven Bean（サービス）実行制御スレッドは，スケジュールキューからRPC要求を取り出し，そのRPC要求に関連づいたトランザクション識別子をトランザクションマネージャに登録します。トランザクションマネージャは，登録されたトランザクション識別子をアプリケーションサーバのトランザクション識別子とマッピングします。これによって，アプリケーションサーバのトランザクションが開始します。

Message-driven Bean（サービス）実行制御スレッドは，Message-driven Bean（サービス）呼び出しスレッドにRPC要求の処理を委譲します。Message-driven Bean（サービス）呼び出しスレッドはMessage-driven Bean（サービス）を実行します。

Message-driven Bean（サービス）が，データベースなどのリソースを更新します。

Message-driven Bean（サービス）呼び出しスレッドは，2.で生成したトランザクション識別子をRPC応答に含めてOpenTP1に送信します。この際，送信に使用するコネクションはRPC送信コネクションになります。

TP1インバウンドアダプタからRPC応答を受信したOpenTP1は，RPC応答に含まれているトランザクション識別子をトランザクションブランチの識別子として管理し，その後の同期点処理のトランザクション識別子として使用します。

4.8.5　同期点処理

同期点処理では，OpenTP1からのトランザクション処理（コミット・プリペア・ロールバック）を実行します。同期点処理は，トランザクション連携機能の同期点電文送受信スレッドが送受信します。トランザクション連携機能を使用した同期点処理の流れを次の図に示します。

図4-17　同期点処理の流れ

OpenTP1のSUPが，グローバルトランザクションをコミット（dc_trn_unchained_commit関数）します。
OpenTP1は，TP1インバウンドアダプタからのRPC応答を受信したコネクションを使用して，TP1インバウンドアダプタへプリペア（更新準備処理）を送信します。RPC応答を受信したコネクションが切断している場合，OpenTP1では，新たにTP1インバウンドアダプタとコネクションを接続してからプリペアを送信します。コネクションの接続は，「4.5.2(2)　同期点待ち受けポートがコネクション接続要求を受信した際の動作」を参照してください。

コネクション管理機能の同期点監視スレッドでは，OpenTP1からの電文の受信を検知すると，該当するコネクションにトランザクション連携機能の同期点電文送受信スレッドを割り当てます。
コネクションを割り当てられた同期点電文送受信スレッドは，OpenTP1からのプリペアを受信します。

同期点電文送受信スレッドは，トランザクションマネージャに対してプリペアを実行します。トランザクションマネージャのプリペアが完了すると，同期点電文送受信スレッドは，プリペアを受信したコネクションを使用して，OpenTP1へプリペアの応答を送信します。

OpenTP1は，TP1インバウンドアダプタからプリペアの応答を受信すると，同じコネクションを使用してTP1インバウンドアダプタへコミットまたはロールバック（更新処理）を送信します。プリペアの応答を受信したコネクションが切断している場合，OpenTP1では，新たにTP1インバウンドアダプタとコネクションを接続してからコミットまたはロールバックを送信します。コネクションの接続は，「4.5.2(2)　同期点待ち受けポートがコネクション接続要求を受信した際の動作」を参照してください。

コネクション管理機能の同期点監視スレッドでOpenTP1からの電文の受信を検知すると，同期点監視スレッドは該当するコネクションにトランザクション連携機能の同期点電文送受信スレッドを割り当てます。
コネクションを割り当てられた同期点電文送受信スレッドは，OpenTP1からのコミットまたはロールバックを受信します。

同期点電文送受信スレッドは，トランザクションマネージャに対してコミットまたはロールバックを実行します。

トランザクションマネージャのコミット・ロールバックが完了すると，同期点電文送受信スレッドは，コミット・ロールバックを受信したコネクションを使用してOpenTP1へコミット・ロールバックの応答を送信します。

ポイント

2相コミットによるトランザクションの決着

OpenTP1では，グローバルトランザクションに参加しているRPC通信先のOpenTP1，またはアプリケーションサーバのトランザクションの決着には2相コミットを使用しています。

2相コミットとは，アプリケーションサーバのトランザクションの決着処理をプリペアと，コミット・ロールバックの2段階に分ける方式です。これにより，複数のトランザクションを矛盾なく更新できます。

2相コミットの詳細については，マニュアル「分散トランザクション処理機能　OpenTP1 解説」の2相コミットに関する説明を参照してください。

4.8.6　同期点処理の最適化

OpenTP1では，トランザクションを効率良く決着するために，同期点処理を最適化しています。OpenTP1の最適化の種類と，TP1インバウンドアダプタのトランザクション連携機能での使用可否の対応を次の表に示します。

なお，それぞれの最適化処理の詳細については，マニュアル「分散トランザクション処理機能　OpenTP1 プログラム作成の手引」のトランザクションの最適化に関する説明を参照してください。

表4-12　トランザクション連携機能を使用した際に適用できるOpenTP1の最適化の種類

OpenTP1の最適化の種類
概要
トランザクション連携機能での使用可否

1相コミット最適化
アプリケーションサーバが更新するリソースが一つの場合，アプリケーションサーバの同期点処理だけで済ませます。
これによって，2回分の同期点処理の通信が不要になります。
○

リードオンリー最適化
アプリケーションサーバがリソースを更新しない場合，またはリソースにアクセスしていない場合，OpenTP1で同期点処理の2相目（コミット／ロールバック）を実行しません。
これによって，2回分の同期点処理の通信が不要になります。

OpenTP1との機能差

OpenTP1では，リソースにアクセスしていない場合にはノーアクセス最適化が適用されますが，TP1インバウンド連携機能では，リードオンリー最適化が適用されます。

△

ノーアクセス最適化
トランザクション属性がNotSupported，またはトランザクション管理種別がBMTのMessage-driven Bean（サービス）をトランザクショナルRPCで呼び出した場合，OpenTP1で同期点処理を実行しません。
これによって，4回分の同期点処理の通信が不要になります。

OpenTP1との機能差

OpenTP1では，リソースにアクセスしていない場合にノーアクセス最適化が適用されます。

コミット最適化
アプリケーションサーバで実行する同期点処理の2相目（コミット／ロールバック）をOpenTP1で実行します。
×

ロールバック最適化
アプリケーションサーバでロールバック処理を実行した場合，ほかのトランザクションブランチと同期を取らないでロールバックします。

プリペア最適化
アプリケーションサーバで実行する同期点処理の1相目（プリペア）を，OpenTP1で実行します。

非同期プリペア最適化
アプリケーションサーバのMessage-driven Bean（サービス）の実行が終了した時点でプリペアを実行します。

（凡例）

○：使用できます。

×：使用できません。

△：使用できますが機能差があります。

4.8.7　トランザクション連携機能の設定

トランザクション連携機能で指定する項目は次のとおりです。

OpenTP1と送受信する同期点処理の最大同時同期点処理数

trn_max_thread_countプロパティ
Connector属性ファイルの指定方法の詳細については，「4.11.2　リソースアダプタの設定」を参照してください。

Message-driven Bean（サービス）のトランザクションタイムアウト
詳細については「4.13　OpenTP1とアプリケーションサーバ間のタイムアウトの設定」を参照してください。

4.8.8　トランザクション障害発生時の対処

OpenTP1とアプリケーションサーバ間のトランザクション連携中にサーバに障害が発生した場合や，サーバを強制停止した場合，通常はサーバを再起動すればOpenTP1とアプリケーションサーバの自動決着機能によってトランザクションは自動的に決着します。しかし，タイミングによっては，再起動してもトランザクションが自動的に決着しないで，仕掛かり中のまま残ることがあります。

また，OpenTP1とアプリケーションサーバ間で一時的な通信障害が発生した場合でも，通常はOpenTP1とアプリケーションサーバの通信リトライによってトランザクションは自動的に決着します。しかし，障害が発生したタイミングや復旧までに掛かった時間によっては，トランザクションが自動的に決着しないで，仕掛かり中のまま残ることがあります。このような場合，コマンドを使用して，仕掛かり中のトランザクションを決着する必要があります。

ここでは，次に示す障害発生時での，仕掛かり中のトランザクションへの対処方法を示します。

OpenTP1に障害が発生，または強制停止した場合

アプリケーションサーバに障害が発生，または強制停止した場合

OpenTP1とアプリケーションサーバに障害が発生した場合

通信障害が発生した場合

OpenTP1に障害が発生した場合（再開始できない場合）

アプリケーションサーバに障害が発生した場合（再起動できない場合）

OpenTP1とアプリケーションサーバに障害が発生した場合（再開始または再起動できない場合）

仕掛かり中トランザクションの手動決着の順序

＜この項の構成＞

(1)　OpenTP1に障害が発生，または強制停止した場合

(2)　アプリケーションサーバに障害が発生，または強制停止した場合

(3)　OpenTP1とアプリケーションサーバに障害が発生した場合

(4)　通信障害が発生した場合

(5)　OpenTP1に障害が発生した場合（再開始できない場合）

(6)　アプリケーションサーバに障害が発生した場合（再起動できない場合）

(7)　OpenTP1とアプリケーションサーバに障害が発生した場合（再開始または再起動できない場合）

(8)　仕掛かり中トランザクションの手動決着の順序

(1)　OpenTP1に障害が発生，または強制停止した場合

トランザクション連携中にOpenTP1に障害が発生した場合や，強制停止した場合，次に示す手順で仕掛かり中のトランザクションの有無を確認し，トランザクションを決着してください。

OpenTP1の再開始
障害発生，または強制停止した原因を取り除き，OpenTP1を再開始します。OpenTP1を再開始できない場合の対処は，「(5)　OpenTP1に障害が発生した場合（再開始できない場合）」を参照してください。

OpenTP1とアプリケーションサーバの仕掛かり中トランザクションの決着
OpenTP1の再開始後に，「(8)　仕掛かり中トランザクションの手動決着の順序」に従ってOpenTP1とアプリケーションサーバの仕掛かり中のトランザクションを決着してください。

アプリケーションサーバだけに残っている仕掛かり中トランザクションの決着
手順2.の完了後，30～45秒経過後にアプリケーションサーバのメッセージログにKFCB40136-Wメッセージが出力される場合は，アプリケーションサーバ側だけに仕掛かり中のトランザクションが残っています。この場合，KFCB40136-Wメッセージの対処に従ってトランザクションを決着してください。KFCB40136-Wについては，マニュアル「Cosminexus アプリケーションサーバ メッセージ 3」の「7.4　KFCB40000からKFCB49999までのメッセージ」を参照してください。

(2)　アプリケーションサーバに障害が発生，または強制停止した場合

トランザクション連携中にアプリケーションサーバに障害が発生した場合や，強制停止した場合，次に示す手順で仕掛かり中のトランザクションの有無を確認し，トランザクションを決着してください。

アプリケーションサーバの再起動
障害発生，または強制停止した原因を取り除き，アプリケーションサーバを再起動します。
アプリケーションサーバを再起動できない場合の対処は，「(6)　アプリケーションサーバに障害が発生した場合（再起動できない場合）」を参照してください。

OpenTP1とアプリケーションサーバの仕掛かり中トランザクションの決着
アプリケーションサーバの障害発生，または強制停止したあとに，OpenTP1の標準出力にKFCA00991-WおよびKFCA00960-Iメッセージが出力された場合は，OpenTP1またはアプリケーションサーバに仕掛かり中のトランザクションが残っているおそれがあります。この場合は，「(8)　仕掛かり中トランザクションの手動決着の順序」に従ってOpenTP1とアプリケーションサーバの仕掛かり中のトランザクションを決着してください。

(3)　OpenTP1とアプリケーションサーバに障害が発生した場合

トランザクション連携中にOpenTP1とアプリケーションサーバの両方に障害が発生した場合，次に示す手順で，仕掛かり中のトランザクションの有無を確認し，トランザクションを決着してください。

アプリケーションサーバの再起動とOpenTP1の再開始
障害発生の原因を取り除き，アプリケーションサーバを再起動して，OpenTP1を再開始してください。
アプリケーションサーバを再起動できない場合の対処は，「(6)　アプリケーションサーバに障害が発生した場合（再起動できない場合）」を参照してください。OpenTP1を再開始できない場合の対処は，「(5)　OpenTP1に障害が発生した場合（再開始できない場合）」を参照してください。
アプリケーションサーバの再起動とOpenTP1の再開始の順序に決まりはありません。

OpenTP1とアプリケーションサーバの仕掛かり中トランザクションの決着
OpenTP1の再開始後に，「(8)　仕掛かり中トランザクションの手動決着の順序」に従ってOpenTP1とアプリケーションサーバの仕掛かり中のトランザクションを決着してください。

アプリケーションサーバだけに残っている仕掛かり中トランザクションの決着
手順2.完了後，30～45秒経過後にアプリケーションサーバのメッセージログにKFCB40136-Wメッセージが出力される場合は，アプリケーションサーバ側だけに仕掛かり中のトランザクションが残っています。
この場合，KFCB40136-Wメッセージの対処に従ってトランザクションを決着してください。KFCB40136-Wについては，マニュアル「Cosminexus アプリケーションサーバ メッセージ 3」の「7.4　KFCB40000からKFCB49999までのメッセージ」を参照してください。

(4)　通信障害が発生した場合

トランザクション連携中にOpenTP1とアプリケーションサーバ間，または，アプリケーションサーバとリソース間で通信障害が発生した場合，次に示す手順で，仕掛かり中のトランザクションの有無を確認し，トランザクションを決着させてください。

通信路の復旧
通信障害の原因を取り除き，通信路を復旧します。

OpenTP1とアプリケーションサーバの仕掛かり中トランザクションの決着
OpenTP1の標準出力にKFCA00991-WおよびKFCA00960-Iメッセージが出力されている場合は，OpenTP1またはアプリケーションサーバに仕掛かり中のトランザクションが残っているおそれがあります。この場合は，「(8)　仕掛かり中トランザクションの手動決着の順序」に従ってOpenTP1とアプリケーションサーバの仕掛かり中のトランザクションを決着します。

アプリケーションサーバだけに残っている仕掛かり中トランザクションの決着
手順2.完了後，30～45秒経過後にアプリケーションサーバのメッセージログにKFCB40136-Wメッセージが出力される場合は，アプリケーションサーバ側だけに仕掛かり中のトランザクションが残っています。
この場合，KFCB40136-Wメッセージの対処に従ってトランザクションを決着します。KFCB40136-Wについては，マニュアル「Cosminexus アプリケーションサーバ メッセージ 3」の「7.4　KFCB40000からKFCB49999までのメッセージ」を参照してください。

(5)　OpenTP1に障害が発生した場合（再開始できない場合）

トランザクション連携中にOpenTP1に障害が発生し，すぐに再開始できない場合は，次に示す手順で，仕掛かり中のトランザクションの有無を確認し，トランザクションを決着させてください。

トランザクションの決着状態の確認
トランザクション処理を開始して30～45秒経過後，アプリケーションサーバのメッセージログにKFCB40136-Wメッセージが出力される場合は，アプリケーションサーバ側に仕掛かり中のトランザクションが残っています。
この場合，KFCB40136-Wメッセージの内容を確認して，OpenTP1に関連づいたリソースがコミット決着したかロールバック決着したかを確認してください。

トランザクションの決着
手順1.の確認結果に応じてアプリケーションサーバ側のトランザクションをcjcommittrnコマンドまたはcjrollbacktrnコマンドで決着してください。

(6)　アプリケーションサーバに障害が発生した場合（再起動できない場合）

トランザクション連携中にアプリケーションサーバに障害が発生し，すぐに再起動できない場合は，cjlisttrnfileコマンドとアプリケーションサーバのPRFトレースを使用して，次に示す手順で仕掛かり中のトランザクションの有無を確認し，トランザクションを決着させてください。

アプリケーションサーバに残っている仕掛かり中トランザクションの有無の確認
アプリケーションサーバに障害が発生している場合は，cjlisttrnコマンドを使用できないため，cjlisttrnfileコマンドで仕掛かり中トランザクションの有無を確認します。
確認結果の出力例を次に示します。

> cjlisttrnfile
[Global transaction information(status file)]
status file1: C:¥Program Files¥HITACHI¥Cosminexus¥CC¥server¥public¥ejb¥MyServer¥
otsstatus¥transaction_1.status
host       (recorded in status file): "apsv1"
J2EE server(recorded in status file): "Myserver"

Status    GlobalTransactionId                                      BranchType
--------- -------------------------------------------------------- ----------
Prepared  d13800010000000000000000000000fefb58e6480000000000000001 Sub
Prepared  d13800010000000000000000000001fefb58e6480000000000000002 Sub

total count: 2

アプリケーションサーバ側のトランザクションの決着状態の確認
手順1.で出力されたトランザクションについて，アプリケーションサーバに関連するリソースがコミット決着またはロールバック決着したかを確認します。
なお，トランザクションの一貫性が保たれていない場合は修復してください。
アプリケーションサーバに関連するリソースのトランザクションの決着状態の確認方法，およびトランザクションの修復方法については，リソースのマニュアルを参照してください。

OpenTP1のトランザクショングローバル識別子の特定
アプリケーションサーバのPRFトレースの内容を基に，OpenTP1のトランザクショングローバル識別子を特定します。トランザクショングローバル識別子の特定方法の例を次の図に示します。

図4-18　OpenTP1のトランザクショングローバル識別子の特定

0x9400のOPT（ASCII列）が手順1.の出力例の「GlobalTransactionId」部分と一致するPRFトレースを特定します。0x9400と同じルートAP情報の0xAA00のOPT（ASCII列）の5文字目から20文字目までの文字列が，OpenTP1のトランザクショングローバル識別子となります。

OpenTP1側のトランザクションの決着状態の確認
手順3.で特定したOpenTP1のトランザクショングローバル識別子について，OpenTP1に関連するリソースがコミット決着またはロールバック決着したかを確認します。トランザクションの一貫性が保たれていない場合は，修復してください。

(7)　OpenTP1とアプリケーションサーバに障害が発生した場合（再開始または再起動できない場合）

トランザクション連携中にOpenTP1とアプリケーションサーバに障害が発生し，すぐに再開始または再起動できない場合は，「(6)　アプリケーションサーバに障害が発生した場合（再起動できない場合）」の手順に従って仕掛かり中のトランザクションの有無を確認し，仕掛かり中のトランザクションがあれば決着してください。

(8)　仕掛かり中トランザクションの手動決着の順序

OpenTP1とアプリケーションサーバ間のトランザクション連携中に障害が発生すると，OpenTP1またはアプリケーションサーバに仕掛かり中のトランザクションが残っているおそれがあります。この場合，次に示す手順で仕掛かり中のトランザクションの有無を確認し，トランザクションを決着させてください。仕掛かり中のトランザクションが複数ある場合は，次に示す手順を繰り返してください。

OpenTP1の仕掛かり中トランザクションの状態確認
OpenTP1のtrnlsコマンドを実行し，OpenTP1のトランザクションの状態を確認します。このとき，-tオプションを指定します。

> trnls -t
TRNGID                 TRNBID             状態                       PID    サーバ   サービス
cab9TP1S0000074f       TP1STP1S0000074f   HEURISTIC_FORGETTING(p,n)  0   TP1S

OpenTP1の仕掛かり中トランザクションの強制終了
手順1.の実行結果の「状態」部分が"HEURISTIC_FORGETTING"以外の場合は，手順3.へ進みます。「状態」部分が"HEURISTIC_FORGETTING"の場合は，OpenTP1のtrnfgtコマンドを実行し，OpenTP1のトランザクションを強制終了します。このとき，-Tオプションに手順1.の実行結果の「TRNGID」部分を指定します。

> trnfgt -T cab9TP1S0000074f

トランザクションの実行状態によっては，trnfgtコマンドは正常終了してもOpenTP1のトランザクションを強制終了できていなかったり，trnfgtコマンドがKFCA00970-Eを出力して異常終了していたりすることがあります。この場合は手順3.に進み，アプリケーションサーバの仕掛かり中トランザクションをすべて決着してから，手順5.を実施してください。

アプリケーションサーバの仕掛かり中トランザクションの特定
アプリケーションサーバのcjlisttrnコマンドを実行し，手順1.の実行結果の「TRNGID」部分と，cjlisttrnコマンドの実行結果の「TP1TRNGID」部分が一致するトランザクションを特定します。このとき，-tp1オプションと-pendingオプションを指定します。
なお，この例では，決着するアプリケーションサーバの仕掛かり中トランザクションの「Status」部分は"Prepared"となります。

> cjlisttrn MyServer -tp1 -pending
[Global transaction information]
Status            GlobalTransactionId                                      ElapsedTime BranchType TP1TRNGID        TP1TRNBID
----------------- -------------------------------------------------------- ----------- ---------- ---------------- ----------------
Prepared          d13800010000000000000000000000fefb58e6480000000000000001          30 Sub        cab9TP1S0000074f @@@@TP1S0000074f

total count: 1

アプリケーションサーバの仕掛かり中トランザクションの決着

手順1.の実行結果の「状態」部分が"HEURISTIC_FORGETTING"，または"COMMIT"だった場合
アプリケーションサーバのcjcommittrnコマンドを実行し，アプリケーションサーバの仕掛かり中トランザクションをコミットで決着します。このとき，-gidオプションに手順3.で特定したアプリケーションサーバの仕掛かり中トランザクションの「GlobalTransactionId」部分を指定します。

> cjcommittrn MyServer -gid d13800010000000000000000000000fefb58e6480000000000000001

「状態」部分が"ROLLBACK"だった場合
アプリケーションサーバのcjrollbacktrnコマンドを実行し，アプリケーションサーバの仕掛かり中トランザクションをロールバックで決着します。このとき，-gidオプションに手順3.で特定したアプリケーションサーバの仕掛かり中トランザクションの「GlobalTransactionId」部分を指定します。

> cjrollbacktrn MyServer -gid d13800010000000000000000000000fefb58e6480000000000000001

コマンドで決着できないOpenTP1の仕掛かり中トランザクションの強制終了
手順1.の実行結果の「状態」部分が"COMMIT"，または，手順2.のtrnfgtコマンドを実行しても強制終了できなかった"HEURISTIC_FORGETTING"のトランザクションは，コマンドを使った手動決着ができません。
そのため，すべての仕掛かり中のトランザクションに対して手順1.～4.を実施したあと，再度OpenTP1のtrnlsコマンドを実行します。コマンド実行後，「状態」部分に"COMMIT"または"HEURISTIC_FORGETTING"のトランザクションが残っている場合は，OpenTP1を強制停止してから強制正常開始してください。

4.9　Message-driven Bean（サービス）の実装

TP1インバウンドアダプタを利用したMessage-driven Bean（サービス）の実装手順を次に示します。

Message-driven Bean（サービス）の実装の準備
TP1インバウンドアダプタを開始します。

Message-driven Bean（サービス）の作成
TP1インバウンドアダプタから呼び出すMessage-driven Bean（サービス）を作成します。
次の作業を実施してください。

クラスパスの設定

リスナインタフェースの実装

onMessageメソッドでの業務ロジックの実装

ejb-jar.xmlの定義

cosminexus.xmlの定義

Message-driven Bean（サービス）の開始
Message-driven Bean（サービス）を含むJ2EEアプリケーションを開始します。

参考

アプリケーションサーバでは，TP1インバウンドアダプタから呼び出すMessage-driven Bean（サービス）のサンプルプログラムを提供しています。サンプルプログラムは，次に示すディレクトリに格納されています。

Windowsの場合
<Cosminexusインストールディレクトリ>¥CC¥examples¥tp1inbound

UNIXの場合
/opt/Cosminexus/CC/examples/tp1inbound

＜この節の構成＞

4.9.1　Message-driven Bean（サービス）の実装の準備

4.9.2　クラスパスの設定

4.9.3　リスナインタフェースの実装

4.9.4　onMessageメソッドでの業務ロジックの実装

4.9.5　ejb-jar.xmlの定義

4.9.6　cosminexus.xmlの定義

4.9.7　Message-driven Bean（サービス）の開始

4.9.1　Message-driven Bean（サービス）の実装の準備

Message-driven Bean（サービス）を実装する前にJ2EEサーバの設定，およびTP1インバウンドアダプタの開始を実施します。

＜この項の構成＞

(1)　トランザクション連携機能を使用する場合のJ2EEサーバの設定

(2)　TP1インバウンドアダプタの開始

(1)　トランザクション連携機能を使用する場合のJ2EEサーバの設定

トランザクション連携機能を使用する場合にJ2EEサーバの設定が必要です。

トランザクション連携機能では，グローバルトランザクションを利用します。そのため，トランザクション連携機能を使用する場合は，J2EEサーバのライトトランザクション機能を無効にする必要があります。

J2EEサーバのライトトランザクション機能を無効にするプロパティについて次に示します。なお，トランザクション連携機能を使用しない場合は，次のプロパティの設定は，有効または無効のどちらでもかまいません。

ejbserver.distributedtx.XATransaction.enabled

ライトトランザクションを使用するか，グローバルトランザクションを使用するかを指定します。trueを指定した場合，グローバルトランザクションを利用できます。

(2)　TP1インバウンドアダプタの開始

TP1インバウンドアダプタを開始する手順を示します。

TP1インバウンドアダプタをインポートします。
cjimportresコマンドを実行して，TP1インバウンドアダプタをインポートします。アプリケーションサーバでは，TP1インバウンドアダプタ（TP1InboundAdapter.rar）をConnector1.5仕様に準拠したインバウンドリソースアダプタとして提供しています。
実行形式を次に示します。

cjimportres <サーバ名> -type rar -f <ファイルパス>

<ファイルパス>には，TP1インバウンドアダプタのパスとして，次のパスを指定してください。

Windowsの場合
"<Cosminexusインストールディレクトリ>¥CC¥adapters¥OpenTP1¥TP1InboundAdapter.rar"

UNIXの場合
/opt/Cosminexus/CC/adapters/OpenTP1/TP1InboundAdapter.rar

TP1インバウンドアダプタをデプロイします。
cjdeployrarコマンドを実行して，インポートしたTP1インバウンドアダプタをデプロイします。
実行形式を次に示します。

cjdeployrar <サーバ名> -resname TP1_Inbound_Adapter

TP1インバウンドアダプタを定義します。
TP1インバウンドアダプタのConnector属性ファイルを編集して，TP1インバウンドアダプタのConnector属性を定義します。
TP1インバウンドアダプタのConnector属性の定義の詳細については，「4.11.2　リソースアダプタの設定」を参照してください。

TP1インバウンドアダプタを開始します。
cjstartrarコマンドを実行して，TP1インバウンドアダプタを開始します。
実行形式を次に示します。

cjstartrar <サーバ名> -resname TP1_Inbound_Adapter

4.9.2　クラスパスの設定

TP1インバウンドアダプタのリスナインタフェースクラスはejbserver.jarに含まれています。

Message-driven Bean（サービス）を作成する環境でejbserver.jarのクラスパスを設定してください。

Windowsの場合

set CLASSPATH=%CLASSPATH%;%COSMINEXUS_HOME%¥CC¥lib¥ejbserver.jar

UNIX（sh）の場合

CLASSPATH=${CLASSPATH}:/opt/Cosminexus/CC/lib/ejbserver.jar
export CLASSPATH

UNIX（csh）の場合

setenv CLASSPATH ${CLASSPATH}:/opt/Cosminexus/CC/lib/ejbserver.jar

4.9.3　リスナインタフェースの実装

Message-driven Bean（サービス）に，TP1インバウンドアダプタのリスナインタフェースを実装してください。

TP1インバウンドアダプタのリスナインタフェースを次に示します。

TP1MessageListener

Message-driven Bean（サービス）にリスナインタフェース（TP1MessageListener）を実装する例を次に示します。

public class SampleMDB
implements TP1MessageListener,MessageDrivenBean
{
 ・・・
}

4.9.4　onMessageメソッドでの業務ロジックの実装

onMessageメソッドに，次に示す業務ロジックを実装します。

public TP1OutMessage onMessage(TP1InMessage in)
{
 //入力パラメタ取得
 byte[] inputdata = in.getInputData();
 ・・・
 //出力データオブジェクトの生成
 TP1OutMessage out = in.createOutMessage();
 ・・・
 ・・・
 //出力データ格納領域の長さを取得
 int outLen = out.getMaxOutputLength();
 ・・・
 try {
   ・・・
   //出力データ格納領域の取得
   byte[] outputdata = out.getOutputData(outLen);
   ・・・
   //業務処理
   //outputdata中に出力データを格納
   ・・・
 } catch(Exception e) {
   //errorLenにエラー処理用の出力データ長を設定
   //エラー処理用の出力データ格納領域の取得
   byte[] outputdata = out.getOutputData(errorLen);
   ・・・
   //outputdata中にエラー情報を格納
   ・・・
 }
 return out;
}

TP1InMessageからユーザデータを取得して業務処理を実行します。

実行結果の出力データをTP1OutMessageのgetOutputDataメソッドで取得したbyte配列中に格納して返します。

getOutputDataメソッドの引数outLenには，応答の長さを指定します。応答の長さは，0～（TP1OutMessageインタフェースのgetMaxOutputLengthメソッドの戻り値）以下の範囲で指定してください。

onMessageメソッドの戻り値がnullの場合，またはgetOutputDataメソッドを呼び出していない場合は，出力データが未設定（null）のため，TP1インバウンドアダプタはエラーメッセージを出力して，RPCエラー(DCRPCER_SYSERR_AT_SERVER(-316))を返します。この場合，呼び出し元のdc_rpc_call関数はRPCエラー(トランザクショナルRPCでない場合はDCRPCER_SYSERR_AT_SERVER(-316)，トランザクショナルRPCの場合はDCRPCER_SYSERR_AT_SERVER_RB(-325))を返します。

業務処理では例外をすべてキャッチして，エラー時もエラー情報をTP1OutMessageインタフェースのgetOutputDataメソッドで取得したbyte配列にエラー情報を格納して返してください。業務処理で発生した例外をキャッチしなかった場合，またはnullを返した場合は，エラーメッセージ（KDJE58459-E）が出力されて，RPCエラー(DCRPCER_SYSERR_AT_SERVER(-316))になります。この場合，呼び出し元のdc_rpc_call関数はRPCエラー(トランザクショナルRPCでない場合はDCRPCER_SYSERR_AT_SERVER(-316)，トランザクショナルRPCの場合はDCRPCER_SYSERR_AT_SERVER_RB(-325))を返します。RPCエラー応答の詳細については，「4.16　TP1インバウンドアダプタで発生するRPCエラー応答」を参照してください。

Message-driven Bean（サービス）のコーディング例は，トランザクション連携機能を使用しない場合と，トランザクション連携機能を使用する場合の2種類があります。Message-driven Bean（サービス）のコーディング例を次に示します。

●トランザクション連携機能を使用しない場合のコーディング例

import java.sql.Connection;
import java.sql.PreparedStatement;
import javax.ejb.EJBException;
import javax.ejb.MessageDrivenBean;
import javax.ejb.MessageDrivenContext;
import javax.naming.InitialContext;
import javax.sql.DataSource;
import javax.transaction.UserTransaction;

import com.hitachi.software.ejb.adapter.tp1.TP1InMessage;
import com.hitachi.software.ejb.adapter.tp1.TP1MessageListener;
import com.hitachi.software.ejb.adapter.tp1.TP1OutMessage;

public class SampleMDB
implements TP1MessageListener, MessageDrivenBean {

   private MessageDrivenContext context;
   public TP1OutMessage onMessage(TP1InMessage in) {
       //入力パラメタ取得
       byte[] inputdata = in.getInputData();

       //出力データオブジェクトの生成
       TP1OutMessage out = in.createOutMessage();

       //出力データ格納領域の長さを取得
       int outLen = out.getMaxOutputLength();

       UserTransaction ut = null;
       Connection con = null;
       PreparedStatement prepStmt = null;
       try {
           //DB更新する業務処理を実装
           InitialContext ic = new InitialContext();
           DataSource ds = (DataSource)ic.lookup(
                               "java:comp/env/jdbc/SampleDB");
           ut = context.getUserTransaction();
           ut.begin();
           con = ds.getConnection();
           prepStmt = con.prepareStatement(
                             "update sample set name = ? where id = 1");
           prepStmt.setString(1, new String(inputdata));
           prepStmt.executeUpdate();
           ut.commit();
           byte[] result ="update complete.".getBytes();
           //出力データ格納領域の取得
           byte[] outputdata = out.getOutputData(outLen);

           //業務処理の結果を出力データにコピー
           System.arraycopy(result,0,outputdata,0,result.length);
       } catch(Exception e) {
           //エラー処理
           try {
               if(ut != null) {
                   ut.rollback();
               }
           } catch(Exception ex) {
           }
           byte[] wk = "An error occured.".getBytes();

           //エラー処理用の出力データ格納領域の取得
           byte[] outputdata = out.getOutputData(wk.length);
           //エラー処理の内容を出力データにコピー
           System.arraycopy(wk,0,outputdata,0,wk.length);
       }
       finally {
           if(prepStmt != null) {
               try {
                   prepStmt.close();
               } catch(Exception exp) {
               }
           }
           if(con != null) {
               try {
                   con.close();
               } catch(Exception exp) {
               }
           }
       }
       return out;
   }

   public void ejbCreate() {
   }
   public void ejbRemove() throws EJBException {
   }
   public void setMessageDrivenContext(MessageDrivenContext ctx)
           throws EJBException {
       this.context = ctx;
   }
}

●トランザクション連携機能を使用する場合のコーディング例

import java.sql.Connection;
import java.sql.PreparedStatement;
import javax.ejb.EJBException;
import javax.ejb.MessageDrivenBean;
import javax.ejb.MessageDrivenContext;
import javax.naming.InitialContext;
import javax.sql.DataSource;

import com.hitachi.software.ejb.adapter.tp1.TP1InMessage;
import com.hitachi.software.ejb.adapter.tp1.TP1MessageListener;
import com.hitachi.software.ejb.adapter.tp1.TP1OutMessage;
public class SampleMDB
implements TP1MessageListener, MessageDrivenBean {
   public TP1OutMessage onMessage(TP1InMessage in) {
       //入力パラメタ取得
       byte[] inputdata = in.getInputData();

       //出力データオブジェクトの生成
       TP1OutMessage out = in.createOutMessage();

       //出力データ格納領域の長さを取得
       int outLen = out.getMaxOutputLength();
       Connection con = null;
       PreparedStatement prepStmt = null;
       try {
           //DB更新する業務処理を実装
           InitialContext ic = new InitialContext();
           DataSource ds = (DataSource)ic.lookup(
                               "java:comp/env/jdbc/SampleDB");
           con = ds.getConnection();
           prepStmt = con.prepareStatement(
                             "update sample set name = ? where id = 1");
           prepStmt.setString(1, new String(inputdata));
           prepStmt.executeUpdate();
           byte[] result ="update complete.".getBytes();

           //出力データ格納領域の取得
           byte[] outputdata = out.getOutputData(outLen);
           //業務処理の結果を出力データにコピー
           System.arraycopy(result,0,outputdata,0,result.length);
       } catch(Exception e) {
           //エラー処理
           byte[] wk = "An error occured.".getBytes();

           //エラー処理用の出力データ格納領域の取得
           byte[] outputdata = out.getOutputData(wk.length);

           //エラー処理の内容を出力データにコピー
           System.arraycopy(wk,0,outputdata,0,wk.length);
       }
       finally {
           if(prepStmt != null) {
               try {
                   prepStmt.close();
               } catch(Exception exp) {
               }
           }
           if(con != null) {
               try {
                   con.close();
               } catch(Exception exp) {
               }
           }
       }
       return out;
   }

   public void ejbCreate() {
   }
   public void ejbRemove() throws EJBException {
   }
   public void setMessageDrivenContext(MessageDrivenContext ctx)
           throws EJBException {
   }
}

4.9.5　ejb-jar.xmlの定義

Message-driven Beanのejb-jar.xmlを定義します。

定義項目を次に示します。

Message-driven Bean（サービス）が実装するリスナインタフェース
<messaging-type>タグに次の値を設定します。
com.hitachi.software.ejb.adapter.tp1.TP1MessageListener

トランザクションの管理方法
<transaction-type>タグに次のどちらかを設定します。

Bean

Container

トランザクションの属性
<trans-attribute>タグに「Container」を指定した場合，Message-driven Beanのメソッドの属性に次のどちらかを設定します。

Required

NotSupported

ActivationSpecの設定
ActivationSpecに設定する値を<activation-config>タグの下の<activation-config-property>タグ内で定義します。プロパティ名とプロパティ値を指定してください。
<activation-config-property>タグ内で指定する値を次に示します。

activation-config-property-name※
データ型
activation-config-property-value

service
java.lang.String
Message-driven Bean（サービス）のサービス名を1～31文字で指定します。
1文字目は英字（A～Z　a～z），2文字目以降は英数字（A～Z　a～z　0～9）またはアンダースコア「_」で指定してください。
一つのサービスグループ内で一意のサービス名を指定してください。

queue_max_length
java.lang.Integer
サービスごとのスケジュールキューの長さを1～65535の整数で指定します。デフォルト値は100です。

stay_watch_queue_rate
スケジュールキューの滞留監視でのしきい値として，メッセージを出力するキューの滞留数の割合を，0～100の整数で指定します。デフォルト値は70です。
指定値が0の場合は滞留監視をしません。

stay_watch_check_interval
スケジュールキューの滞留監視での警告メッセージの抑止時間を1～2147483647の整数で指定します。デフォルト値は60です。

注※　ActivationSpecの設定では，リソースアダプタのDD（ra.xml）の<activationspec>-<required-config-property>タグに指定されているプロパティを設定する必要があります。

ActivationSpecの設定の詳細については，「3.16.8　Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定」を参照してください。

4.9.6　cosminexus.xmlの定義

cosminexus.xmlに，Message-driven Bean（サービス）に関連する項目を定義します。

次に定義項目を示します。

使用するTP1インバウンドアダプタの表示名
<resource-adapter>タグにConnector属性ファイルの<display-name>タグの値と同じ値を指定します。

プール内のインスタンスの設定
<pooled-instance>タグの下で，プール内のインスタンスを定義します。

minimum（Message-driven Bean（サービス）のインスタンスプールの最小数）
この値は変更できません。常に「1」です。

maximum（Message-driven Bean（サービス）のインスタンスプールの最大数）

定義項目の詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「2.2　Cosminexusアプリケーション属性ファイル（cosminexus.xml）で指定する各属性の詳細」を参照してください。

4.9.7　Message-driven Bean（サービス）の開始

次に，Message-driven Bean（サービス）を開始する手順を示します。

Message-driven Bean（サービス）をインポートします。
cjimportappのコマンドを実行して，Message-driven Bean（サービス）を含むJ2EEアプリケーションをインポートします。
実行形式を次に示します。

cjimportapp <サーバ名> -f "<J2EEアプリケーションのファイルパス>"

J2EEアプリケーションを開始します。
cjstartappコマンドを実行して，インポートしたJ2EEアプリケーションを開始します。
実行形式を次に示します。

cjstartapp <サーバ名> -name <J2EEアプリケーション名>

4.10　OpenTP1のアプリケーションプログラムの作成

ここでは，C言語でプログラムを作成する場合を例にして，TP1インバウンドアダプタを呼び出すアプリケーションプログラムの作成について説明します。

OpenTP1のアプリケーションプログラムからのTP1インバウンドアダプタの呼び出しは，dc_rpc_call関数を使用します。dc_rpc_call関数の各引数に指定する値を次の表に示します。

表4-13　dc_rpc_call関数の引数に指定する値

引数 | 指定する値
group | TP1インバウンドアダプタのConnector属性ファイルの<service_group>タグで定義したサービスグループ名を指定します。
service | Message-driven Bean（サービス）のActivationSpecの<service>タグで定義したサービス名を指定します。
in | サービスの入力パラメタを指定します。詳細は，マニュアル「OpenTP1 プログラム作成の手引」を参照してください。
in_len | サービスの入力パラメタ長を指定します。詳細は，マニュアル「OpenTP1 プログラム作成の手引」を参照してください。
out | 応答を格納する領域を指定します。詳細は，マニュアル「OpenTP1 プログラム作成の手引」を参照してください。
out_len | 応答の長さを指定します。詳細は，マニュアル「OpenTP1 プログラム作成の手引」を参照してください。
flags | RPCの形態を指定します。指定可能な値については「4.12.3　トランザクションの設定」を参照してください。

コーディング例は，トランザクション連携機能を使用しない場合と，トランザクション連携機能を使用する場合の2種類があります。

TP1インバウンドアダプタを呼び出すアプリケーションのSUPのコーディング例を次に示します。なお，この例はSUP固有のもので，SPP，MHPには該当しません。

●トランザクション連携機能を使用しない場合のコーディング例

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <dcrpc.h>
#include <dctrn.h>
#include <dcadm.h>

main ()
{

 static char    in_buf[1024];
 static DCLONG  in_buf_len;
 static char    out_buf[1024];
 static DCLONG  out_buf_len;
 int rc;

 rc = dc_rpc_open(DCNOFLAGS);
 if (rc != DC_OK) {
   printf("SUP01:dc_rpc_openに失敗しました。CODE = %d¥n", rc);
   goto PROG_END;
 }

 rc = dc_adm_complete(DCNOFLAGS);
 if (rc != DC_OK) {
   printf("SUP01:dc_adm_completeに失敗しました。CODE = %d¥n", rc);
   goto PROG_END;
 }

 strcpy(in_buf, "SUP01:DATA OpenTP1!!");
 in_buf_len = strlen(in_buf) + 1;
 out_buf_len = 1024;
 rc = dc_rpc_call("spp01grp", "svr01", in_buf, &in_buf_len, out_buf,
     &out_buf_len, DCNOFLAGS | DCRPC_TPNOTRAN);
 if (rc != DC_OK) {
   printf("SUP01:サービス要求に失敗しました。CODE = %d¥n", rc);
 }
 printf("SUP01:SERVICE FUNCTION RETURN = %s¥n", out_buf);

 PROG_END:
 dc_rpc_close(DCNOFLAGS);
 printf("SUP01:処理を終了しました。¥n");
 exit(0);
}

●トランザクション連携機能を使用する場合のコーディング例

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <dcadm.h>
#include <dcrpc.h>
#include <dctrn.h>

main()
{

 static char     in_buf[1024];
 static DCULONG  in_buf_len;
 static char     out_buf[1024];
 static DCULONG  out_buf_len;
 int rc;

 rc = dc_rpc_open(DCNOFLAGS);
 if (rc != DC_OK) {
   printf("SUP01:dc_rpc_openに失敗しました。CODE = %d¥n", rc);
   goto PROG_END;
 }

 rc = dc_adm_complete(DCNOFLAGS);
 if (rc != DC_OK) {
   printf("SUP01:dc_adm_completeに失敗しました。CODE = %d¥n", rc);
   goto PROG_END;
 }

 rc = dc_trn_begin();
 if (rc != DC_OK) {
   printf("SUP01:dc_trn_beginに失敗しました。CODE = %d¥n", rc);
   goto TRAN_END;
 }

 strcpy(in_buf, "SUP01:DATA OpenTP1!!");
 in_buf_len = strlen(in_buf) + 1;
 out_buf_len = 1024;
 rc = dc_rpc_call("spp01grp", "svr01", in_buf, &in_buf_len, out_buf,
                 &out_buf_len, DCNOFLAGS);
 if (rc != DC_OK) {
   printf("SUP01:サービス要求に失敗しました。CODE = %d¥n", rc);
   goto TRAN_END;
 }
 printf("SUP01:SERVICE FUNCTION RETURN = %s¥n", out_buf);

 TRAN_END:
 rc = dc_trn_unchained_commit();
 if (rc != DC_OK) {
   printf("SUP01:dc_trn_unchained_commitに失敗しました。CODE = %d¥n", rc);
 }

 PROG_END:
 dc_rpc_close(DCNOFLAGS);
 printf("SUP01:処理を終了しました。¥n");
 exit(0);
}

4.11　アプリケーションサーバの実行環境での設定

TP1インバウンド連携機能を使用する場合，J2EEサーバの設定とリソースアダプタの設定が必要です。

＜この節の構成＞

4.11.1　J2EEサーバの設定

4.11.2　リソースアダプタの設定

4.11.1　J2EEサーバの設定

J2EEサーバの設定は，簡易構築定義ファイルで実施します。TP1インバウンド連携機能の定義は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。簡易構築定義ファイルでの定義を次の表に示します。

表4-14　TP1インバウンド連携機能を使用するための簡易構築定義ファイルの定義

項目
指定するパラメタ
設定内容

通信に使用するIPアドレス
ejbserver.jca.adapter.tp1.bind_host
TP1インバウンド連携機能の通信（受信および送信）に使用するIPアドレスを指定します。ホスト名も指定できます。
指定がない場合，またはホスト名のアドレスが解決できない場合，システムによって自動的に選択された有効なローカルアドレスが使用されます。

4.11.2　リソースアダプタの設定

TP1インバウンド連携機能の定義には，TP1インバウンドアダプタのConnector属性ファイルを使用します。

次にTP1インバウンドアダプタのConnector属性ファイルの設定について説明します。

＜この項の構成＞

(1)　TP1インバウンドアダプタのRARファイル

(2)　Connector属性ファイルの取得と設定

(3)　Connector属性の定義

(4)　config-property-nameの説明

(1)　TP1インバウンドアダプタのRARファイル

TP1インバウンドアダプタのRARファイルは次のディレクトリに格納されています。

Windowsの場合

<Cosminexusインストールディレクトリ>¥CC¥adapters¥OpenTP1¥TP1InboundAdapter.rar

UNIXの場合

/opt/Cosminexus/CC/adapters/OpenTP1/TP1InboundAdapter.rar

(2)　Connector属性ファイルの取得と設定

Connector属性ファイルを取得して，値を編集してからTP1インバウンドアダプタに設定します。ここでは，取得と設定の手順について説明します。

参考

TP1インバウンドアダプタでは，アプリケーションサーバが提供するConnector属性ファイルのテンプレートファイルを使用できます。テンプレートファイルを使用すると，TP1インバウンドアダプタをインポートする前に，Connector属性ファイルを編集しておくことができます。テンプレートファイルを使用する場合は，編集対象のConnector属性ファイルをサーバ管理コマンド（cjgetrarpropコマンドまたはcjgetrespropコマンド）で取得する操作が不要です。

Connector属性ファイルのテンプレートファイルの格納先を次に示します。

Windowsの場合

<Cosminexusインストールディレクトリ>¥CC¥admin¥templates¥TP1InboundAdapter_cfg.xml

UNIXの場合

/opt/Cosminexus/CC/admin/templates/TP1InboundAdapter_cfg.xml

テンプレートファイル使用時の注意事項については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1.14　Connector属性ファイルのテンプレートファイル」を参照してください。

●Connector属性ファイルの取得

cjgetrarpropコマンドを実行して，TP1インバウンドアダプタのConnector属性を取得します。

実行形式を次に示します。

cjgetrarprop <サーバ名> -resname TP1_Inbound_Adapter -c <rar属性ファイルのファイルパス>

●Connector属性ファイルの設定

cjsetrarpropコマンドを実行して，編集後のTP1インバウンドアダプタのConnector属性ファイルを設定します。TP1インバウンドアダプタのConnector属性の編集内容については，「(3)　Connector属性の定義」を参照してください。

実行形式を次に示します。

cjsetrarprop <サーバ名> -resname TP1_Inbound_Adapter -c <rar属性ファイルのファイルパス>

(3)　Connector属性の定義

TP1インバウンドアダプタのConnector属性ファイルを定義します。

●TP1インバウンドアダプタのプロパティの設定

次の表に，TP1インバウンドアダプタのプロパティの設定内容を示します。

表4-15　Connector属性ファイルでのTP1インバウンド連携機能の定義

項目 | 指定するタグ | 設定内容
Deployツール上に表示されるリソースアダプタの名称 | <display-name> | 「TP1_Inbound_Adapter」を指定します。
リソースアダプタのコンフィグレーションプロパティの定義 | <resourceadapter>-<config-property> | リソースアダプタのコンフィグレーションプロパティのプロパティ名とプロパティ値を指定します※1。
リソースアダプタの実行時プロパティの定義 | <resourceadapter-runtime>-<property> | リソースアダプタの実行時プロパティのプロパティ名とプロパティ値を指定します※2。

注※1　リソースアダプタのコンフィグレーションプロパティのプロパティ名とプロパティ値を表4-16に示します。

注※2　リソースアダプタの実行時プロパティのプロパティ名とプロパティ値を表4-17に示します。

表4-16　リソースアダプタのコンフィグレーションプロパティ

config-property-name
config-property-value

backlog_count
RPC要求を待ち受けるポートのListenキューの長さを指定します。

connection_timeout
RPC要求の応答を送信する時のコネクション確立処理のタイムアウト時間を指定します。

ipc_sockctl_watchtime※
一時クローズ処理要求の応答待ち時間を指定します。

max_connections※
RPC要求を待ち受けるポートへの最大同時接続数を指定します。

node_id※
ノード識別子を指定します。

receive_buffer_size※
受信時の受信バッファサイズを指定します。

rpc_close_after_send※
コネクションを切断します。

rpc_max_thread_count※
最大同時RPC要求受け付け数を指定します。

rpc_receive_timeout
RPC要求の受信のタイムアウト時間を指定します。

rpc_receive_timeout_interval
RPC要求の受信のタイムアウトの監視間隔を指定します。

rpc_sockctl_highwater※
RPC受信コネクションの一時クローズ処理開始のしきい値を指定します。

rpc_sockctl_lowwater※
RPC受信コネクションの一時クローズ処理非対象とするコネクション数の割合を指定します。

scd_port
RPC要求を待ち受けるポートのポート番号を指定します。

send_buffer_size※
応答時の送信バッファサイズを指定します。

send_retry_count
サーバの応答送信時のTCP/IPコネクションの接続でエラーが発生したときのリトライ回数を指定します。

send_retry_interval
サーバの応答送信時のTCP/IPコネクションの接続でエラーが発生したときのリトライ間隔を指定します。

service_group※
TP1インバウンドアダプタのサービスグループ名を指定します。

tcp_receive_timeout
コネクションを接続してから，もしくはデータを受信してから次のデータを受信するまでのタイムアウト時間を指定します。

tcp_send_timeout
RPC要求の応答を送信する際の，1回のデータ送信ごとのタイムアウト時間を指定します。

tcp_send_timeout_interval
RPC要求の応答を送信する際の，一回のデータ送信のタイムアウトの監視間隔を指定します。
なお，08-53以降ではこのプロパティの設定は無視されます。

trn_max_connections※
RPC応答または同期点電文の送受信で使用するコネクションの最大同時接続数を指定します。

trn_max_thread_count※
最大同時同期点処理数を指定します。

trn_port
同期点電文を待ち受けるポートのポート番号を指定します。

trn_sockctl_highwater※
RPC送信コネクションの一時クローズ処理開始のしきい値を指定します。

trn_sockctl_lowwater※
RPC送信コネクションの一時クローズ処理非対象とするコネクション数の割合を指定します。

注※

プロパティに設定する値の考え方については，「(4)　config-property-nameの説明」を参照してください。

表4-17　リソースアダプタの実行時プロパティ

property-name | property-value
MaxTPoolSize | Message-driven Bean（サービス）呼び出しスレッドの最大数を指定します。
MinTPoolSize | Message-driven Bean（サービス）呼び出しスレッドの最小数を指定します。
TPoolKeepalive | 空いているMessage-driven Bean（サービス）呼び出しスレッドの最大生存時間を指定します。

(4)　config-property-nameの説明

リソースアダプタのコンフィグレーションプロパティに設定するプロパティ値について説明します。

なお，各プロパティの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1.11　TP1インバウンドアダプタに設定する<config-property>に指定できるプロパティ」を参照してください。

(a)　サービスグループ名（service_group）

OpenTP1でのサービスグループ名とは，サービスをまとめた単位であり，ネットワークで接続されるすべてのOpenTP1システムの中で一意な識別子です。OpenTP1のユーザサービス定義のservice_group句に設定します。

TP1インバウンドアダプタでのサービスグループ名とは，TP1インバウンドアダプタが呼び出すMessage-driven Bean（サービス）のグループです。OpenTP1と同様にネットワークで接続されるすべてのOpenTP1システムの中で一意な識別子にしてください。サービスグループ名はConnector属性ファイルのservice_groupプロパティに設定します。

(b)　ノード識別子（node_id）

OpenTP1でのノード識別子とは，OpenTP1のセットアップ単位に一意に割り当てる4文字の識別子のことです。OpenTP1のシステム共通定義のnode_id句に設定します。

TP1インバウンドアダプタのノード識別子とは，OpenTP1と同様にネットワークで接続されるすべてのOpenTP1システムの中で一意に割り当てる4文字の識別子です。Connector属性ファイルのnode_idプロパティに設定します。

なお，ノード識別子は，トランザクションの障害が発生し，コマンドを使ってトランザクションを強制決着する際にノードを特定するための情報です。そのため，トランザクション連携機能を使用する場合，OpenTP1システムの中で重複しない一意な文字列を設定しておくことを推奨します。トランザクション連携機能を使用しない場合，TP1インバウンドアダプタのノード識別子はデフォルトの設定値のままで問題ありません。

(c)　RPC要求の同時実行数（max_connections，rpc_max_thread_count）

RPC要求の同時実行数は，次の表に示すConnector属性ファイルのプロパティに設定します。

表4-18　RPC要求の同時実行数の設定で使用するプロパティ

設定項目 | Connector属性ファイルのプロパティ
RPC受信コネクションの最大同時接続数 | max_connections
最大同時RPC要求受け付け数 | rpc_max_thread_count

max_connectionsプロパティには，TP1インバウンドアダプタに同時にRPC要求を送信するOpenTP1のプロセス数を設定します。

rpc_max_thread_countプロパティには，TP1インバウンドアダプタで処理するRPC要求の処理時間とスループットから算出したスレッド数を設定します。

例えば，RPC要求の処理時間が50ms，RPC要求のスループットが200TPSを実現する場合に必要なスレッド数は，CPU使用率を100%としたときに，0.05（秒）×200（TPS）＝10（スレッド）となります。RPC要求の処理時間は，各システムでの実測値とします。また，CPU100%以下を想定する場合は，それに応じた安全係数を考慮してください。

(d)　RPC応答と同期点処理の同時実行数（trn_max_connections，trn_max_thread_count）

RPC応答と同期点処理の同時実行数は，次の表に示すConnector属性ファイルのプロパティに設定します。

表4-19　RPC応答と同期点処理の同時実行数の設定

設定項目 | Connector属性ファイルのプロパティ
RPC送信コネクションの最大同時接続数 | trn_max_connections
最大同時同期点処理数 | trn_max_thread_count

trn_max_connectionsプロパティには，TP1インバウンドアダプタからOpenTP1へRPC応答を送信するコネクションの最大同時接続数を設定します。設定値は，RPC受信コネクションの最大同時接続数（max_connectionsプロパティ）と同じ値を設定してください。

trn_max_thread_countプロパティには，TP1インバウンドアダプタのトランザクション連携機能を使用する場合に指定する同期点処理の同時処理数を設定します。設定値は，最大同時RPC要求受け付け数（rpc_max_thread_countプロパティ）と同じ値を設定してください。トランザクション連携機能を使用しない場合は，値はデフォルトのままで問題ありません。

(e)　一時クローズ処理（rpc_sockctl_highwater，rpc_sockctl_lowwater，trn_sockctl_highwater，trn_sockctl_lowwater，ipc_sockctl_watchtime）

一時クローズ処理は，次の表に示すConnector属性ファイルのプロパティに設定します。TP1インバウンドアダプタとOpenTP1の一時クローズ処理の設定項目の対応を次の表に示します。

表4-20　一時クローズ処理の設定項目の対応

設定項目 | TP1インバウンドアダプタのConnector属性ファイルのプロパティ | OpenTP1のシステム共通定義の定義句
RPC受信コネクションの一時クローズ処理開始のしきい値（%） | rpc_sockctl_highwater | ipc_sockctl_highwater※
RPC受信コネクションの一時クローズ処理非対象とするコネクション数の割合（%） | rpc_sockctl_lowwater | ipc_sockctl_highwater※
RPC送信コネクションの一時クローズ処理開始のしきい値（%） | trn_sockctl_highwater | ipc_sockctl_highwater※
RPC送信コネクションの一時クローズ処理非対象とするコネクション数の割合（%） | trn_sockctl_lowwater | ipc_sockctl_highwater※
一時クローズ応答の待ち時間（秒） | ipc_sockctl_watchtime | ipc_sockctl_watchtime

注※　一時クローズ処理のしきい値と一時クローズ処理非対象とするコネクション数の割合をコンマ区切りで指定します。

rpc_sockctl_lowwaterプロパティには，rpc_sockctl_highwaterプロパティの設定値以下の値を設定してください。rpc_sockctl_highwaterプロパティよりも大きい値を設定した場合は，rpc_sockctl_highwaterプロパティと同じ値が設定されます。

trn_sockctl_lowwaterプロパティには，trn_sockctl_highwaterプロパティの設定値以下の値を設定してください。trn_sockctl_highwaterプロパティよりも大きい値を設定した場合は，trn_sockctl_highwaterプロパティと同じ値が設定されます。

また，コネクションの最大同時接続数および一時クローズ処理のしきい値には，小さい値を指定しないでください。コネクションの最大同時接続数（max_connectionsプロパティとtrn_max_connectionsプロパティ）の設定値，および一時クローズ処理のしきい値（rpc_sockctl_highwaterプロパティとtrn_sockctl_highwaterプロパティ）に小さい値を指定すると，一時クローズ処理が多発し，性能に影響を与えたり，通信障害が発生したりするおそれがあります。

(f)　TCP/IPの通信バッファサイズ（receive_buffer_size，send_buffer_size）

TCP/IPの受信バッファサイズは，Connector属性ファイルのreceive_buffer_sizeプロパティに設定します。また，TCP/IPの送信バッファサイズは，Connector属性ファイルのsend_buffer_sizeプロパティに設定します。

バッファサイズを調整する場合，receive_buffer_sizeプロパティの設定値は，OpenTP1のユーザサービス定義のipc_sendbuf_sizeオペランドの設定値に合わせることを推奨します。また，send_buffer_sizeプロパティの設定値は，OpenTP1のユーザサービス定義のipc_recvbuf_sizeオペランドの設定値に合わせることを推奨します。

なお，設定したバッファサイズは，Java SEの仕様上，設定したサイズどおりにならない場合があります。詳細はJava SEのAPIドキュメントを参照してください。

(g)　コネクション切断オプション（rpc_close_after_send）

OpenTP1とTP1インバウンドアダプタ間のコネクションを接続すると，デフォルトの設定ではRPC通信および同期点処理後も接続したままとなります。

RPC通信および同期点処理後にコネクションを切断するには，TP1インバウンドアダプタとOpenTP1のコネクション切断オプションを設定します。

コネクション切断オプションは次のように設定します。

アプリケーションサーバのConnector属性ファイルのrpc_close_after_sendプロパティにtrueを指定

OpenTP1のシステム共通定義のrpc_close_after_send句にYを指定

なお，OpenTP1のrpc_close_after_send句は，ユーザサービス定義にも指定できます。OpenTP1システム全体にコネクション切断オプションを有効にする場合はシステム共通定義に設定してください。サービス単位に有効にする場合はユーザサービス定義に設定してください。

OpenTP1のシステム共通定義とユーザサービス定義の詳細は，マニュアル「OpenTP1 システム定義」を参照してください。

4.12　OpenTP1での設定

ここでは，次のOpenTP1での設定について説明します。

ユーザサービスネットワーク定義によるスケジューラダイレクトの設定

性能解析トレースの設定

トランザクションの設定

OpenTP1に関する詳細な設定や作業については，OpenTP1のマニュアルを参照してください。

＜この節の構成＞

4.12.1　ユーザサービスネットワーク定義によるスケジューラダイレクトの設定

4.12.2　性能解析トレースの設定

4.12.3　トランザクションの設定

4.12.1　ユーザサービスネットワーク定義によるスケジューラダイレクトの設定

TP1インバウンドアダプタをユーザサービスネットワーク定義によるスケジューラダイレクト機能を使って呼び出すために，次の定義を設定します。

ユーザサービスネットワーク定義

OpenTP1のユーザサービス定義

＜この項の構成＞

(1)　ユーザサービスネットワーク定義

(2)　OpenTP1のユーザサービス定義

(1)　ユーザサービスネットワーク定義

ユーザサービスネットワーク定義の設定項目を次の表に示します。

表4-21　ユーザサービスネットワーク定義の設定項目

設定項目 | 設定する値
サービスグループ名 | TP1インバウンドアダプタのConnector属性ファイルのservice_groupプロパティで定義したサービスグループ名を指定します。
ホスト名 | アプリケーションサーバのホスト名を指定します※。
ポート番号 | TP1インバウンドアダプタのConnector属性ファイルのscd_portプロパティで定義したポート番号を指定します。

注※　アプリケーションサーバのホスト名については，次の注意事項を参照してください。

注意

OpenTP1では，RPC送信元と送信先のIPアドレスを比較し，同一マシンであればUNIXドメイン通信，異なるマシンであればINETドメイン通信を実施します。TP1インバウンドアダプタでは，INETドメイン通信だけをサポートするため，OpenTP1とTP1インバウンドアダプタを同一マシンで利用する場合は，ユーザサービスネットワーク定義のホスト名にはIP alias機能によって割り振った送信元とは異なるIPアドレスを指定してください。

ユーザサービスネットワーク定義の例を次に示します。

dcsvgdef -g ＜サービスグループ名＞ -h ホスト名[:ポート番号]

(2)　OpenTP1のユーザサービス定義

ユーザサービス定義のrpc_destination_modeにdefinitionを設定します。definitionを設定することで，dc_rpc_call関数を呼び出すときに，ユーザサービスネットワーク定義の指定値から宛先を検索するようになります。

ユーザサービス定義の例を次に示します。

set rpc_destination_mode = definition

4.12.2　性能解析トレースの設定

TP1インバウンドアダプタでOpenTP1の性能解析トレース（PRF）の情報を引き継ぐため，システム共通定義に性能解析トレース（PRF）の定義を次の表に示す内容で設定してください。

表4-22　性能解析トレース（PRF）の設定

設定内容 | 説明
set prf_trace=Y | 性能検証用トレース情報を取得します。
set rpc_prf_trace_level=00010001 | OpenTP1のPRF情報をアプリケーションサーバに伝播するために設定します。

4.12.3　トランザクションの設定

トランザクション連携機能を使用する場合，OpenTP1にはTP1インバウンドアダプタとの連携でトランザクションを発生させるように設定する必要があります。

一方，トランザクション連携機能を使用しない場合は，OpenTP1にTP1インバウンドアダプタとの連携でトランザクションを発生させないように設定する必要があります。それぞれのトランザクションの設定について，SUPまたはSSPの場合，およびMHPの場合に分けて表に示します。

表4-23　トランザクションの設定（SUPまたはSPPの場合）

トランザクション連携の有無 | 設定内容 | 説明
ユーザサービス定義 | dc_rpc_call関数
トランザクション連携機能を使用する | set atomic_update=Y | 引数flagsにDCNOFLAGSを指定します。 | 呼び出し元のOpenTP1のサービスグループのプロセスでトランザクションを発生させ，TP1インバウンドアダプタをトランザクションに含めます。
トランザクション連携機能を使用しない | set atomic_update=Y | 引数flagsにDCNOFLAGS | DCRPC_TPNOTRANを指定します。 | 呼び出し元のOpenTP1のサービスグループのプロセスでトランザクションを発生させますが，TP1インバウンドアダプタをトランザクションに含めません。
set atomic_update=N | 引数flagsにDCNOFLAGSまたは，DCNOFLAGS | DCRPC_TPNOTRANを指定します。 | 呼び出し元のOpenTP1のサービスグループのプロセスでトランザクションを発生させません。

注　OpenTP1のユーザサービス定義やdc_rpc_call関数の詳細は，マニュアル「OpenTP1 システム定義」またはマニュアル「OpenTP1 プログラム作成の手引」を参照してください。

表4-24　トランザクションの設定（MHPの場合）

トランザクション連携の有無
設定内容
説明

アプリケーション属性定義
ユーザサービス定義
dc_rpc_call関数

トランザクション連携機能を使用する
mcfaalcapコマンドの-nオプションのtrnmodeオペランドに"trn"を指定します。※
set atomic_update=Y
引数flagsにDCNOFLAGSを指定します。
呼び出し元のOpenTP1のサービスグループのプロセスでトランザクションを発生させ，TP1インバウンドアダプタをトランザクションに含めます。

トランザクション連携機能を使用しない
mcfaalcapコマンドの-nオプションのtrnmodeオペランドに"trn"を指定します。※
set atomic_update=Y
引数flagsにDCNOFLAGS | DCRPC_TPNOTRANを指定します。
呼び出し元のOpenTP1のサービスグループのプロセスでトランザクションを発生させますが，TP1インバウンドアダプタをトランザクションに含めません。

mcfaalcapコマンドの-nオプションのtrnmodeオペランドに"nontrn"を指定します。
set atomic_update=Y
またはset atomic_update=N
引数flagsにDCNOFLAGSまたはDCNOFLAGS | DCRPC_TPNOTRANを指定します。
呼び出し元のOpenTP1のサービスグループのプロセスでトランザクションを発生させません。

注※　mcfaalcapコマンドの-nオプションのtrnmodeオペランドに"trn"を設定し，set atomic_update=Nを設定した場合，MHPは設定誤りのため異常終了します。

注　OpenTP1のアプリケーション属性定義，ユーザサービス定義やdc_rpc_call関数の詳細は，マニュアル「OpenTP1 システム定義」またはマニュアル「OpenTP1 プログラム作成の手引」を参照してください。

4.13　OpenTP1とアプリケーションサーバ間のタイムアウトの設定

TP1インバウンドアダプタでは，次のタイムアウトを設定できます。

RPC要求受信およびRPC応答送信時のタイムアウト

トランザクションに関するタイムアウト

それぞれについて説明します。

＜この節の構成＞

4.13.1　RPC要求受信およびRPC応答送信時のタイムアウト

4.13.2　トランザクションに関するタイムアウト

4.13.1　RPC要求受信およびRPC応答送信時のタイムアウト

TP1インバウンドアダプタでは，RPC要求受信およびRPC応答送信時のタイムアウトを設定できます。これにより，ネットワークの障害やOpenTP1の障害などが発生し，RPC通信が待ち状態となった場合に，通信タイムアウトが発生することで障害を検知できます。

また，TP1インバウンドアダプタではMessage-driven Bean（サービス）の実行時間タイムアウトも設定できます。これにより，業務処理で無限ループやデッドロックが発生した場合などに，実行時間タイムアウトによって強制的に業務処理を終了できます。

タイムアウトが設定できるポイントとタイムアウトの有効範囲を次の図に示します。

図4-19　タイムアウトが設定できるポイントとタイムアウトの有効範囲

次に，この図のタイムアウトが設定できるポイントでのタイムアウトの設定方法について説明します。

＜この項の構成＞

(1)　OpenTP1での設定

(2)　アプリケーションサーバの実行環境での設定

(1)　OpenTP1での設定

図4-19の1のポイントと7のポイントのタイムアウトの設定は，OpenTP1で実施します。タイムアウトの設定方法を次の表に示します。

表4-25　OpenTP1でのタイムアウトの設定方法

図中番号
設定項目
設定ファイル
説明

1
RPC最大応答待ち時間
ユーザサービス定義※
（watch_time）
RPC要求を送信してからサービスの応答が返るまでの待ち時間を秒単位で指定します。

7
TCP受信タイムアウト
ユーザサービス定義※
（ipc_header_recv_time）
データを受信してから通信制御用のデータを受信するまでのタイムアウト時間を秒単位で指定します。

注　タイムアウトが発生した場合，dc_rpc_call関数にはエラーが返されます。タイムアウトが発生した場合のTP1インバウンドアダプタのRPCエラー応答の詳細については，「4.16　TP1インバウンドアダプタで発生するRPCエラー応答」を参照してください。

注※　詳細については，マニュアル「OpenTP1 システム定義」のユーザサービス定義の説明を参照してください。

(2)　アプリケーションサーバの実行環境での設定

図4-19の2のポイントから6のポイントまでのタイムアウトの設定は，アプリケーションサーバの実行環境で実施します。タイムアウトの設定方法を次の表に示します。

表4-26　アプリケーションサーバの実行環境でのタイムアウトの設定方法

図中番号
設定項目
設定ファイル※1
説明

2
RPC要求の受信タイムアウト
Connector属性ファイル
（rpc_receive_timeoutプロパティ）
OpenTP1から最初の要求電文を受信し始めてから，すべての要求電文の受信を完了するまでのタイムアウト時間を秒単位で指定します。なお，すべての要求電文を受信する前にコネクションが切断されたRPC要求もタイムアウトの対象に含まれます※2。

3
TCP受信タイムアウト
Connector属性ファイル
（tcp_receive_timeoutプロパティ）
要求電文の受信（read）を開始してから完了するまでのタイムアウト時間を秒単位で指定します。

4
サービス実行タイムアウト※3
cosminexus.xml
（<ejb-method-observation-timeout>タグ）
Message-driven Bean（サービス）の実行時間を秒単位で指定します。

cosminexus.xml
（<method-observation-recovery-mode>タグ）
「thread」を指定します。

5
TCP送信コネクション確立タイムアウト
Connector属性ファイル
（connection_timeoutプロパティ）
電文を送信する際，新たにコネクションを接続する場合のコネクション確立処理のタイムアウト時間を秒単位で指定します。

6
TCP送信タイムアウト
Connector属性ファイル
（tcp_send_timeoutプロパティ）
応答電文の送信（write）を開始してから完了するまでのタイムアウト時間を秒単位で指定します。

注　タイムアウトが発生した場合，エラーメッセージが出力されます。また，dc_rpc_call関数にはエラーが返されます。タイムアウトが発生した場合のTP1インバウンドアダプタのRPCエラー応答の詳細については，「4.16　TP1インバウンドアダプタで発生するRPCエラー応答」を参照してください。

注※1　属性ファイルの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1　Connector属性ファイル」を参照してください。

注※2　分割された要求電文の受信中はTCP受信タイムアウトのチェックが優先されるため，RPC要求の受信タイムアウトは発生しません。また，Connector属性ファイルのrpc_receive_timeout_intervalプロパティに指定した時間の分，タイムアウトの発生が遅れる場合があります。

注※3　サービス実行のタイムアウトには，アプリケーションサーバのメソッドキャンセル機能を使用します。タイムアウトが発生した場合，Message-driven Bean（サービス）は，EJB仕様で定められたシステム例外が発生した場合と同等の動作をしたあとで，OpenTP1にRPCエラーを応答します。

4.13.2　トランザクションに関するタイムアウト

TP1インバウンドアダプタでは，トランザクションを開始してから決着処理を開始するまでのタイムアウトを設定できます。タイムアウトを設定しておくことで，ネットワークの障害やOpenTP1の障害などが発生して，トランザクションが決着できない場合に，自動でロールバックできます。

OpenTP1での設定，およびトランザクションに関するタイムアウトの有効範囲と設定方法を次に示します。

図4-20　トランザクションに関するタイムアウトの有効範囲

＜この項の構成＞

(1)　OpenTP1での設定

(2)　アプリケーションサーバの実行環境での設定

(1)　OpenTP1での設定

図4-20の1のポイントから3のポイント，および6のポイントのタイムアウトの設定は，OpenTP1で実施します。タイムアウトの設定方法を次の表に示します。

表4-27　OpenTP1でのタイムアウトの設定方法

図中番号
設定項目
設定ファイル※
説明

1
トランザクション完了限界時間
ユーザサービス定義
（trn_completion_limit_time）
トランザクションの開始から終了までの時間を指定します。

2
トランザクションブランチ限界経過時間
ユーザサービス定義
（trn_expiration_time）
トランザクションの開始から同期点処理を開始するまでの時間を指定します。

3
RPC最大応答待ち時間
ユーザサービス定義
（watch_time）
RPC要求を送信してからサービスの応答が返るまでの待ち時間を秒単位で指定します。

6
トランザクション同期点処理時の最大通信待ち時間
ユーザサービス定義
（trn_watch_time）
トランザクションの同期点処理で，トランザクションブランチ間の通信の受信待ち時間を指定します。

注　タイムアウトが発生した場合，dc_rpc_call関数にエラーが返されます。タイムアウトが発生した場合のTP1インバウンドアダプタのRPCエラー応答の詳細については，「4.16　TP1インバウンドアダプタで発生するRPCエラー応答」を参照してください。

注※　ユーザサービス定義の詳細については，マニュアル「OpenTP1 システム定義」のユーザサービス定義の説明を参照してください。

(2)　アプリケーションサーバの実行環境での設定

図4-20の4のポイントおよび5のポイントのタイムアウトの設定は，アプリケーションサーバの実行環境で実施します。タイムアウトの設定方法を次の表に示します。

表4-28　アプリケーションサーバの実行環境でのタイムアウトの設定方法

図中番号
設定項目
設定ファイル※1
説明

4
トランザクションタイムアウト時間
cosminexus.xml
（<ejb-transaction-timeout>タグ）
アプリケーションサーバ内でのトランザクション開始からトランザクション決着処理開始までの時間を指定します。

J2EEサーバ用ユーザプロパティファイル
（ejbserver.jta.TransactionManager.defaultTimeOut）

5
サービス実行タイムアウト※2
cosminexus.xml
（<ejb-method-observation-timeout>タグ）
Message-driven Bean（サービス）の実行時間を秒単位で指定します。

cosminexus.xml
（<method-observation-recovery-mode>タグ）
「thread」を指定します。

注　タイムアウトが発生した場合，エラーメッセージが出力されます。また，dc_rpc_call関数にエラーが返されます。タイムアウトが発生した場合のTP1インバウンドアダプタのRPCエラー応答の詳細については，「4.16　TP1インバウンドアダプタで発生するRPCエラー応答」を参照してください。

注※1　cosminexus.xmlの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「2.　Cosminexusアプリケーション属性ファイル（cosminexus.xml）」を参照してください。なお，J2EEサーバ用ユーザプロパティファイルについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「2.4　usrconf.properties（J2EEサーバ用ユーザプロパティファイル）」を参照してください。

注※2　サービス実行タイムアウトは，アプリケーションサーバのメソッドキャンセル機能を使用します。メソッドキャンセル機能の詳細は，マニュアル「Cosminexus アプリケーションサーバ 機能解説 運用／監視／連携編」の「5.3.2　J2EEアプリケーション実行時間の監視とは」を参照してください。

4.14　TP1インバウンドアダプタとMessage-driven Bean（サービス）の開始と終了

TP1インバウンドアダプタとMessage-driven Bean（サービス）の開始と終了は，次の手順で実施してください。

TP1インバウンドアダプタを開始します。

Message-driven Bean（サービス）を開始します。

Message-driven Bean（サービス）を終了します。

TP1インバウンドアダプタを終了します。

ここでは，TP1インバウンドアダプタとMessage-driven Bean（サービス）の開始と終了について説明します。

＜この節の構成＞

4.14.1　TP1インバウンドアダプタの開始と終了

4.14.2　Message-driven Bean（サービス）の開始と終了

4.14.1　TP1インバウンドアダプタの開始と終了

TP1インバウンドアダプタの開始と終了について説明します。

＜この項の構成＞

(1)　TP1インバウンドアダプタの開始

(2)　TP1インバウンドアダプタの終了

(1)　TP1インバウンドアダプタの開始

TP1インバウンドアダプタは，cjstartrarコマンドで開始します。

TP1インバウンドアダプタを開始すると，Connector属性ファイルの定義内容が読み込まれます。

service_groupプロパティが不正な場合，エラーメッセージを出力してTP1インバウンドアダプタの開始処理を終了します。出力するメッセージを次に示します。

service_groupプロパティが指定されていない場合

エラーメッセージ（KDJE58302-E）

設定範囲外の値を指定した場合

エラーメッセージ（KDJE58300-E）

すでに同じ名前のサービスグループ名のTP1インバウンドアダプタが開始済みの場合

エラーメッセージ（KDJE58303-E）

そのほかのConnector属性ファイルの定義が不正な場合

警告メッセージ（KDJE58301-W）を出力し，デフォルト値を適用してTP1インバウンドアダプタの開始処理を続行します。

TP1インバウンドアダプタの開始によって，リソースアダプタのConnector属性ファイルに指定した番号のポートが開かれ，RPC通信の待ち受けが開始されます。

指定した番号のポートが開けない場合，エラーメッセージが出力されて，TP1インバウンドアダプタの開始に失敗します。Connector属性ファイルに指定するプロパティについては，「4.11.2　リソースアダプタの設定」を参照してください。

なお，TP1インバウンドアダプタを開始した時点では，RPC通信を待ち受けるポートは開いていますが，Message-driven Bean（サービス）は開始していません。Message-driven Bean（サービス）が開始していない状態で，OpenTP1からRPC要求を受信した場合は，エラーメッセージが出力されてRPCエラーが返されます。

(2)　TP1インバウンドアダプタの終了

TP1インバウンドアダプタは，cjstoprarコマンドで終了します。

TP1インバウンドアダプタを終了する場合，TP1インバウンドアダプタを使用しているすべてのMessage-driven Bean（サービス）をあらかじめ停止しておいてください。

TP1インバウンドアダプタは，次に示す手順に沿って終了してください。

TP1インバウンドアダプタを使用しているすべてのMessage-driven Bean（サービス）を停止します。

Message-driven Bean（サービス）が使用していたすべてのOutboundのリソースアダプタ（DBConnector）を停止します。

TP1インバウンドアダプタを終了します。

TP1インバウンドアダプタの終了時にMessage-driven Bean（サービス）が起動されている場合は，エラーメッセージ（KDJE48547-E）が出力され，TP1インバウンドアダプタの終了に失敗します。なお，正常に終了した場合は，ログファイルにKDJE58351-Iが出力されます。

トランザクション連携機能を使用している場合，手順3.を手順2.の先に実施すると，OpenTP1とアプリケーションサーバに未決着のトランザクションが残ってしまうおそれがあります。この場合，TP1インバウンドアダプタを再開始し，未決着のトランザクションを決着させてください。詳細は「4.8.8(4)　通信障害が発生した場合」を参照してください。

4.14.2　Message-driven Bean（サービス）の開始と終了

Message-driven Bean（サービス）の開始と終了について説明します。

＜この項の構成＞

(1)　Message-driven Bean（サービス）の開始

(2)　終了

(1)　Message-driven Bean（サービス）の開始

TP1インバウンドアダプタを使用するJ2EEアプリケーションをcjstartappコマンドで起動すると，Message-driven Bean（サービス）は開始します。

ActivationSpecの設定値が不正な場合，エラーメッセージが出力され，Message-driven Bean（サービス）の起動は失敗します。ActivationSpecの設定については，「4.9.5　ejb-jar.xmlの定義」を参照してください。

(2)　終了

Message-driven Bean（サービス）は，TP1インバウンドアダプタを使用するJ2EEアプリケーションが次のどちらかで停止した場合に終了します。

cjstopappコマンドで通常停止した場合

cjstopappコマンドの-forceオプションまたは-cancelオプションを指定して強制停止した場合

Message-driven Bean（サービス）の終了処理中は，新たなRPC電文を受け付けないようにスケジュールキューは停止されます。また，未処理のRPC要求と実行中のMessage-driven Bean（サービス）は次のように処理されます。

新たに受信した未処理のRPC要求

リクエスト受け付けスレッドが受け付けたRPC要求です。RPC要求を破棄して，OpenTP1にRPCエラーを応答します。

RPCエラーコードとしてDCRPCER_NO_SUCH_SERVICE（-311）が返され，エラーメッセージが出力されます。

受信済みの未処理のRPC要求

スケジュールキューに登録済みのRPC要求です。RPC要求を破棄して，OpenTP1にRPCエラーを応答します。

RPCエラーコードとしてDCRPCER_SERVICE_TERMINATING（-313）が返され，エラーメッセージが出力されます。

実行中のMessage-driven Bean（サービス）

停止種別によって処理が次のように異なります。

通常停止の場合
終了するまで待機します。

強制停止の場合
強制終了（メソッドキャンセル）されます。
RPCエラーコードにDCRPCER_TIMED_OUT（-307）が返され，エラーメッセージが出力されます。
強制終了（メソッドキャンセル）は，Message-driven Bean（サービス）実行中にだけ実行できます。なお，保護区では強制終了（メソッドキャンセル）できません。

参考

正常に開始／終了した場合は，ログファイルにメッセージが出力されます。

4.15　性能解析トレース情報の引き継ぎ

TP1インバウンドアダプタを使用してOpenTP1のSUPからアプリケーションサーバ上の業務を呼び出す場合に，OpenTP1のSPPを呼び出す場合と同様に性能解析情報を引き継ぎ，OpenTP1とアプリケーションサーバの処理を突き合わせることができます。

この節では，性能解析情報を引き継ぐための準備，OpenTP1とアプリケーションサーバの性能解析情報の対応，および性能解析情報を突き合わせる方法について説明します。

＜この節の構成＞

4.15.1　性能解析情報を引き継ぐための準備

4.15.2　性能解析情報の対応

4.15.3　トランザクション連携機能を使用しない場合の性能解析トレース情報の引き継ぎ

4.15.4　トランザクション連携機能を使用する場合の性能解析トレース情報の引き継ぎ

4.15.1　性能解析情報を引き継ぐための準備

性能解析情報を引き継ぐ場合，OpenTP1のシステム共通定義に次の設定が必要です。

set prf_trace=Y

set rpc_prf_trace_level=00010001

これらの定義がある場合，OpenTP1，アプリケーションサーバ間で性能解析情報が引き継がれます。

性能解析情報の引き継ぎ有無と性能解析情報で確認できる処理の範囲を次の図に示します。

図4-21　性能解析情報の引き継ぎ有無と性能解析情報で確認できる処理の範囲

4.15.2　性能解析情報の対応

TP1インバウンドアダプタのRPC通信機能では，性能解析情報の引き継ぎが有効な場合，RPC要求電文を解析するときにOpenTP1のRPC要求電文に設定されている性能解析情報を取得して，アプリケーションサーバの性能解析情報として使用します。具体的には，TP1インバウンドアダプタの処理の延長で出力されるRootAP IPとRootAP CommNo.に，OpenTP1の呼び出し元のIPとルートRPC通信番号がそれぞれ引き継がれます。

引き継がれる情報の対応を次の表に示します。

表4-29　引き継がれる情報の対応

アプリケーションサーバの性能解析情報 | 引き継ぎ元のOpenTP1の性能解析情報
RootAP IP | 呼び出し元のOpenTP1のIP
RootAP PID | 0000（固定）
RootAP CommNo. | 呼び出し元のOpenTP1のルートRPC通信番号

また，TP1インバウンドアダプタの入り口で出力されるPRFトレース（0xAA00）では，RootAP IPとRootAP CommNo.に加えて，オプション文字列（OPT）にOpenTP1のルートRPCノード識別子などが出力されます。

PRFトレース（0xAA00）で出力される情報を次の表に示します。

表4-30　PRFトレース（0xAA00）で出力される情報

アプリケーションサーバの性能解析情報 | 引き継ぎ元のOpenTP1の性能解析情報
RootAP IP | 呼び出し元のOpenTP1のIP
RootAP PID | 0000（固定）
RootAP CommNo. | 呼び出し元のOpenTP1のルートRPC通信番号
INT | サービスグループ名
OPR | サービス名
OPT | 呼び出し元のOpenTP1のルートRPCノード識別子（4文字）。なお，トランザクショナルRPCの場合は，ノード識別子のあとにトランザクショングローバル識別子。

これらの情報を使用して性能解析情報を突き合わせることで，OpenTP1とアプリケーションサーバ間での処理を追跡できます。

また，性能解析トレース情報の引き継ぎはトランザクション連携機能を使用する場合と使用しない場合とで異なります。それぞれの場合の性能解析トレース情報の引き継ぎについて説明します。

4.15.3　トランザクション連携機能を使用しない場合の性能解析トレース情報の引き継ぎ

トランザクション連携機能を使用しない場合の性能解析トレース情報の引き継ぎについて説明します。ここでは，アプリケーションサーバの性能解析情報と引き継ぎ元のOpenTP1の性能解析情報を突き合わせることによって，OpenTP1とアプリケーションサーバ間でのRPC通信を追跡する例を示します。

RPCの実行によって突き合わせ可能な範囲を次の図に示します。

図4-22　RPCの実行によって突き合わせ可能な範囲

OpenTP1のdc_rpc_call関数でのサービス要求の送信直前，およびdc_rpc_call関数のリターン直前のPRFトレースと，アプリケーションサーバのPRFトレースの突き合わせの例を次の図に示します。

図4-23　突き合わせの例

OpenTP1のルートOpenTP1識別子は，アプリケーションサーバのPRFトレースの0xAA00，0xAA06のOPT（ASCII列）に出力されます。

なお，OpenTP1のルート通信番号とアプリケーションサーバのRootAP情報は，通信番号のけたが異なります。このため，数値は同じですが，文字列としては一致しません。

4.15.4　トランザクション連携機能を使用する場合の性能解析トレース情報の引き継ぎ

トランザクション連携機能を使用する場合の性能解析トレース情報の引き継ぎについて説明します。ここでは，アプリケーションサーバの性能解析情報と引き継ぎ元のOpenTP1の性能解析情報を突き合わせることによって，OpenTP1とアプリケーションサーバ間でのRPC通信を追跡する例を示します。

RPCおよび同期点処理の実行によって突き合わせ可能な範囲を次の図に示します。

図4-24　RPCおよび同期点処理の実行によって突き合わせ可能な範囲

次に示す性能解析トレース情報を突き合わせて，トレース情報を追跡します。

RPC要求を受信したときのOpenTP1とTP1インバウンドアダプタ間の性能解析トレース情報
アプリケーションサーバの性能解析情報と引き継ぎ元のOpenTP1の性能解析情報を突き合わせます。詳細は「4.15.3　トランザクション連携機能を使用しない場合の性能解析トレース情報の引き継ぎ」を参照してください。

同期点処理時のOpenTP1とTP1インバウンドアダプタ間の性能解析トレース情報
トランザクショングローバル識別子を突き合わせます。詳細は「(1)　同期点処理でのOpenTP1とTP1インバウンドアダプタ間の性能解析トレース情報の突き合わせ」を参照してください。

アプリケーションサーバ内でのRPC要求受信時と同期点処理時の間の性能解析トレース情報
PRFトレース（0xAA00）で出力したトランザクショングローバル識別子，および同期点処理時に出力するトランザクショングローバル識別子を突き合わせます。詳細は「(2)　RPC要求と同期点処理間の性能解析トレース情報の突き合わせ」を参照してください。

＜この項の構成＞

(1)　同期点処理でのOpenTP1とTP1インバウンドアダプタ間の性能解析トレース情報の突き合わせ

(2)　RPC要求と同期点処理間の性能解析トレース情報の突き合わせ

(1)　同期点処理でのOpenTP1とTP1インバウンドアダプタ間の性能解析トレース情報の突き合わせ

同期点処理では，OpenTP1から引き継がれるトランザクショングローバル識別子を突き合わせます。アプリケーションサーバの性能解析情報と引き継ぎ元のOpenTP1の性能解析情報を突き合わせることによって，OpenTP1とアプリケーションサーバ間での同期点処理を追跡する例を示します。

図4-25　同期点処理でのPRFトレースの突き合わせの例

OpenTP1のPRF（プリペアメッセージの送信時の場合は0x4000）のTrnの先頭16文字と，0xAA14のOPT（ASCII列）を突き合わせます。

また，0xAA14のRootAP情報のIPアドレス，およびINTに出力する送信元のノード識別子もOpenTP1のPRFと突き合わせます。

応答も同様に0xAA14のOPT（ASCII列）とOpenTP1のPRF（プリペア完了メッセージの受信時であれば0x4003）のTrnの先頭16文字と突き合わせます。

(2)　RPC要求と同期点処理間の性能解析トレース情報の突き合わせ

RPC要求と同期点処理間のPRFトレースは，0xAA00で出力したOPT（ASCII列）の5文字目から20文字目のトランザクショングローバル識別子と，同期点処理時に出力される0xAA14のOPT（ASCII列）のトランザクショングローバル識別子を突き合わせます。

RPC要求と同期点処理間のPRFトレースの突き合わせの例を次に示します。

図4-26　RPC要求と同期点処理間のPRFトレースの突き合わせの例

4.16　TP1インバウンドアダプタで発生するRPCエラー応答

この節では，それぞれのRPCエラー応答について説明します。

TP1インバウンドアダプタのRPCエラー応答一覧を次の表に示します。

表4-31　RPCエラー応答一覧

dc_rpc_call関数の戻り値
発生原因
TP1インバウンドアダプタの出力メッセージ

DCRPCER_NO_BUFS(-304)
TP1インバウンドアダプタの電文組み立てリストが不足している状態で，TP1インバウンドアダプタへトランザクショナルRPCではないRPC要求を送信した場合
KDJE58359-E

TP1インバウンドアダプタのスケジュールキューの電文滞留数が最大キュー長（Message-driven Bean（サービス）のDDのqueue_max_lengthプロパティ）に達している状態で，TP1インバウンドアダプタへRPC要求を送信した場合
KDJE58360-E

DCRPCER_NET_DOWN(-306)
TP1インバウンドアダプタへRPC要求を送信する際にコネクションを確立できなかった場合
－

TP1インバウンドアダプタのbacklog_countプロパティの設定数だけListenキューにコネクション確立要求が滞留している状態で，TP1インバウンドアダプタへRPC要求を送信した場合
－

TP1インバウンドアダプタへRPC要求を送信中にコネクションが切断された場合
KDJE58354-E

OpenTP1のスケジューラダイレクト機能を使用しないでTP1インバウンドアダプタへRPC要求を送信した場合
KDJE58355-E 詳細情報：
Scheduler direct function is not used.

TP1インバウンドアダプタの電文組み立てリストが不足している状態で，TP1インバウンドアダプタへRPC要求を送信した場合
KDJE58359-E

TP1インバウンドアダプタへRPC要求を送信中に，TP1インバウンドアダプタの電文読み込み処理がタイムアウトした場合
KDJE58354-E

TP1インバウンドアダプタへRPC要求を送信中に，TP1インバウンドアダプタのRPC要求を受信し始めてから受信し終わるまでの時間がタイムアウトした場合
KDJE58358-E

TP1インバウンドアダプタがOpenTP1からのRPC要求ではない電文を受信した場合（プロトコルエラー）
KDJE58355-E 詳細情報：
It is not the first request data.

DCRPCER_TIMED_OUT(-307)
TP1インバウンドアダプタへRPC要求を送信中に，TP1インバウンドアダプタの電文読み込み処理がタイムアウトした場合
KDJE58354-E

TP1インバウンドアダプタへRPC要求を送信中に，TP1インバウンドアダプタのRPC要求を受信し始めてから受信し終わるまでの時間がタイムアウトした場合
KDJE58358-E

Message-driven Bean（サービス）の実行中にMessage-driven Bean（サービス）の実行時間タイムアウトが発生した場合
KDJE58457-E

TP1インバウンドアダプタがOpenTP1へRPC応答を送信する際のコネクション確立要求でタイムアウトが発生した場合
KDJE58400-E

TP1インバウンドアダプタがOpenTP1へRPC応答を送信する際の電文書き込み処理でタイムアウトが発生した場合
KDJE58401-E

dc_rpc_call関数の引数flagsにDCNOFLAGSかDCRPC_TPNOTRAN以外を指定してTP1インバウンドアダプタへRPC要求を送信した場合
KDJE58356-E 詳細情報：
The value of the flags argument of the dc_rpc_call function is illegal.

OpenTP1のスケジューラダイレクト機能を使用しないでTP1インバウンドアダプタへRPC要求を送信した場合
KDJE58355-E 詳細情報：Scheduler direct function is not used.

Message-driven Bean（サービス）の実行中にMessage-driven Bean（サービス）を強制終了（cjstopappコマンドの-force， -cancelオプション）した場合
KDJE58455-E

TP1インバウンドアダプタへRPC要求を送信中にコネクションが切断された場合
KDJE58354-E

TP1インバウンドアダプタがOpenTP1へRPC応答を送信する際にコネクションを確立できなかった場合
KDJE58400-E

TP1インバウンドアダプタがOpenTP1へRPC応答を送信する際の電文書き込み処理でエラーが発生した場合
KDJE58401-E

TP1インバウンドアダプタがOpenTP1からのRPC要求ではない電文を受信した場合（プロトコルエラー）
KDJE58355-E 詳細情報：
It is not the first request data.

DCRPCER_NO_SUCH_SERVICE(-311)
dc_rpc_call関数の引数serviceに不正なサービス名を指定してTP1インバウンドアダプタへRPC要求を送信した場合
KDJE58362-E

Message-driven Bean（サービス）が開始していない，または終了中にTP1インバウンドアダプタへRPC要求を送信した場合
KDJE58362-E

DCRPCER_SERVICE_TERMINATING(-313)
Message-driven Bean（サービス）が開始していない，または終了中にTP1インバウンドアダプタのスケジュールキューに登録されていたRPC要求が処理された場合
KDJE58456-E

DCRPCER_SERVICE_NOT_UP(-314)
dc_rpc_call関数の引数groupに不正なサービスグループ名を指定してTP1インバウンドアダプタへRPC要求を送信した場合
KDJE58357-E※

DCRPCER_SYSERR_AT_SERVER(-316)
未サポートバージョンのOpenTP1からTP1インバウンドアダプタへトランザクショナルRPCではないRPC要求を送信した場合
KDJE58356-E 詳細情報：
Version of OpenTP1 is not supported.

OpenTP1でユーザデータ圧縮機能（システム共通定義のrpc_datacompオペランドにY）を使用してTP1インバウンドアダプタへトランザクショナルRPCではないRPC要求を送信した場合
KDJE58356-E 詳細情報：
User data compression function is not supported.

TP1インバウンドアダプタへトランザクショナルRPCではないRPC要求をした際に，Message-driven Bean（サービス）の実行中に例外が発生した場合，またはMessage-driven Bean（サービス）の実行結果に出力データを設定していない，もしくはJ2EEサーバでシステム例外が発生した場合
KDJE58459-E

DCRPCER_NO_BUFS_RB(-323)
TP1インバウンドアダプタの電文組み立てリストが不足している状態で，TP1インバウンドアダプタへトランザクショナルRPC要求を送信した場合
KDJE58359-E

DCRPCER_SYSERR_AT_SERVER_RB(-325)
未サポートバージョンのOpenTP1から，TP1インバウンドアダプタへトランザクショナルRPC要求を送信した場合
KDJE58356-E 詳細情報：
Version of OpenTP1 is not supported.

OpenTP1でユーザデータ圧縮機能（システム共通定義のrpc_datacompオペランドにY）を使用してTP1インバウンドアダプタへトランザクショナルRPC要求を送信した場合
KDJE58356-E 詳細情報：
User data compression function is not supported.

TP1インバウンドアダプタへトランザクショナルRPC要求をした際に，Message-driven Bean（サービス）の実行中に例外が発生した場合，または，Message-driven Bean（サービス）の実行結果に出力データを設定していない，または，J2EEサーバでシステム例外が発生した場合
KDJE58459-E

DCRPCER_TESTMODE(-366)
OpenTP1でオンラインテスタを使用してTP1インバウンドアダプタへRPC要求を送信した場合
KDJE58356-E 詳細情報：
TP1/Online Tester is not supported.

DCRPCER_TRNCHK_EXTEND(-372)
OpenTP1とのトランザクション連携でライトトランザクション（usrconf.propertiesのejbserver.distributedtx.XATransaction.enabledプロパティがfalse）の場合
－

（凡例）　－：該当なし

注※

サービスグループ名が不正の場合，OpenTP1はRPC要求を再送します。そのため，このエラーメッセージは，OpenTP1から再送された回数分だけ出力されます。

5.　アプリケーションサーバでのJPAの利用

この章では，JPAの概要とアプリケーションサーバでのJPAの利用について説明します。

＜この章の構成＞

5.1　この章の構成

5.2　JPAの特長

5.3　アプリケーションサーバで使用できるJPAの機能

5.4　EntityManagerとは

5.5　永続化コンテキストとは

5.6　コンテナ管理のEntityManagerを取得する方法

5.7　アプリケーション管理のEntityManagerを取得する方法

5.8　persistence.xmlでの定義

5.9　persistence.xmlの配置

5.10　JPAのインタフェース

5.11　アプリケーション設定時の注意事項

5.1　この章の構成

JPAとは，データベース関連処理の設計およびコーディングの簡略化を目的として，Javaのオブジェクトとリレーショナルデータベースとのマッピング（O/Rマッピング）に関して定められた仕様です。JPAを使用することで，ユーザはデータベースの持つ情報をJavaのオブジェクト（エンティティ）として操作することができるため，効率良くシステムを構築できます。

この章では，JPAの概要と，アプリケーションサーバでのJPAの利用について説明します。この章の構成を次の表に示します。

表5-1　この章の構成（アプリケーションサーバでのJPAの利用）

分類 | タイトル | 参照先
解説 | JPAの特長 | 5.2
アプリケーションサーバで使用できるJPAの機能 | 5.3
EntityManagerとは | 5.4
永続化コンテキストとは | 5.5
実装 | コンテナ管理のEntityManagerを取得する方法 | 5.6
アプリケーション管理のEntityManagerを取得する方法 | 5.7
persistence.xmlでの定義 | 5.8
persistence.xmlの配置 | 5.9
JPAのインタフェース | 5.10
注意事項 | アプリケーション設定時の注意事項 | 5.11

注　「設定」および「運用」について，この機能固有の説明はありません。

5.2　JPAの特長

ここでは，JPAを使用したアプリケーションの特長について説明します。

＜この節の構成＞

5.2.1　JPAを使用したアプリケーションの利点

5.2.2　エンティティクラスとは

5.2.3　JPAプロバイダとは

5.2.1　JPAを使用したアプリケーションの利点

JPAを利用したアプリケーションを使用すると，次に示すことが実現できます。

O/Rマッピングやデータベースアクセス処理の隠ぺいによって，ユーザプログラミングが容易になります。

アノテーションを利用することで，定義ファイル作成コストを削減し，POJO（Plain Old Java Object）によるコーディングが実現します。

デフォルト値の設定によって，ユーザのコーディング量が削減できます。

Cosminexus JPAプロバイダはJPA仕様書に準じているため，ほかのJPAプロバイダで使用しているアプリケーションを移行できます。

ここでは，JPAを使用しない場合とJPAを使用する場合のデータアクセスモデルを比較して，JPAを使用したアプリケーションの利点を説明します。

＜この項の構成＞

(1)　JPAを使用しない場合のデータアクセスモデル

(2)　JPAを使用した場合のデータアクセスモデル

(1)　JPAを使用しない場合のデータアクセスモデル

JPAを使用しない場合，J2EEアプリケーションからデータベースにアクセスするには，一般的に，次の図に示すようなデータアクセスモデルを使用してアプリケーションを作成します。

図5-1　JPAを使用しない場合のデータベースアクセスモデル

上記の図について説明します。

図の場合のデータアクセスモデルでは，SQLをビジネスロジックから隠ぺいするために，テーブルに対応するDAOと呼ばれるクラスを作成します。DAOクラスの中に，JDBCインタフェースでSQLを発行する処理を作成します。図の流れについて説明します。

ビジネスロジックを記述してあるEJBでは，DAOを使用してデータベースからデータを読み出します。

取得したデータをDTOと呼ばれるオブジェクトに格納します。

DTOオブジェクトをWebコンポーネントに返します。Webコンポーネントではデータベースから取得したデータをWebページに出力します。

このようなデータアクセスモデルでは，データベースのデータモデルが大きく複雑になると，作成しなければならないDAO，SQL，DTOクラスの量も多くなります。DAO，SQL，およびDTOの作成は単調な手作業のため，アプリケーション開発の生産性を低下させる原因となります。

(2)　JPAを使用した場合のデータアクセスモデル

JPAを使用した場合のデータアクセスモデルは次に示す図のようになります。

図5-2　JPAを使用した場合のデータベースアクセスモデル

JPAを使用した場合，データベースのテーブルの行に対応したクラスを作成します。これを，エンティティクラスといいます。ビジネスロジックを記述してあるEJBでは，このエンティティクラスのオブジェクトを直接データベースに格納するかのように，処理を記述できます。

図について説明します。

JPAプロバイダと呼ばれるJPAのエンジンがデータベースに対してSQLを発行します。また，JPAプロバイダがエンティティオブジェクトとデータベースのテーブルの状態を自動的に同期を取ります。

エンティティオブジェクトは，取得したデータをそのままWebコンポーネントに渡すことができます。

このように，JPAを使用するとDTOを作成する必要はありません。また，エンティティクラスは，MyEclipseなどの開発ツールを使用してデータベースのテーブルスキーマから自動的に生成することもできます。従来のデータアクセスモデルで生産性を低下させる原因となっていたDAO，SQL，DTOを作成する必要がないため，従来よりもアプリケーションの生産性を向上させることができます。

なお，エンティティクラスおよびJPAプロバイダについては，「5.2.2　エンティティクラスとは」および「5.2.3　JPAプロバイダとは」を参照してください。

5.2.2　エンティティクラスとは

JPAを使用する場合，アプリケーションではデータの入れ物となるクラスを作成します。これをエンティティクラスといいます。通常，エンティティクラスを作成する際には，エンティティクラスの一つのオブジェクトがデータベースのテーブルの一行に対応するように作成します。エンティティクラスは，普通のJavaクラス（POJO）で作成します。特別なインタフェースをインプリメントする必要はありません。

エンティティクラスのフィールドの値をデータベーステーブルのどのカラムに格納するのかといったマッピングは，エンティティクラスのフィールドなどにアノテーションを使用して指定します。ただし，JPAには開発容易性を向上させるためにCoCの考え方が取り入れられており，マッピングを明示的に指定しなくてもデフォルトでマッピングが行われるルールがあります。例えば，フィールドのマッピングを明示的に指定していない場合，フィールド名から対応するカラムが推定されてマッピングされます。

5.2.3　JPAプロバイダとは

JPAプロバイダとは，次に示すマッピング機能，API，およびクエリ言語を提供するJPA実装です。JPAプロバイダでは次の機能を提供しています。

Javaオブジェクトとデータベースのマッピング機能

データベースへの処理をカプセル化したAPI

JPA仕様で共通に使用できるクエリ言語

JPAプロバイダを使用すると，データベースとのやり取りに関する処理を意識しないでアプリケーションを設計できるという利点があります。また，JPAプロバイダで利用できるJPQLというクエリ言語を使用することで，データベースに詳しくなくてもクエリを送信できるという利点もあります。

JPAプロバイダが提供するマッピング機能について次の図に示します。

図5-3　JPAプロバイダが提供するマッピング機能の概要

図について説明します。

アプリケーション内にエンティティクラスを用意し，エンティティクラスからエンティティオブジェクトを生成します。ユーザは，エンティティオブジェクトの内容を変更することで，データベースの内容を変更します。これによって，データベースへの処理を意識しないで，データベースの内容を更新できます。

JPAプロバイダは，エンティティオブジェクトをデータベースのレコードとマッピングします。ユーザが実施した検索，挿入，削除，または更新の処理をデータベースに対して実行します。

生成されたエンティティオブジェクトはEntityManagerの管理下に置かれます。エンティティオブジェクトのフィールドの値が変更されると，EntityManagerは変更を自動的に検知して，変更をデータベースのテーブルに反映します。

EntityManagerは次の処理をするときに呼び出されます。

エンティティクラスのオブジェクトのデータをデータベースのテーブルに追加する。

データベースにすでに格納されているデータを検索してエンティティクラスのオブジェクトとして取り出す。

EntityManagerの詳細については，「5.4　EntityManagerとは」を参照してください。

5.3　アプリケーションサーバで使用できるJPAの機能

ここでは，JPAを利用する場合に，アプリケーションサーバで使用できるJPAプロバイダ，コンポーネント，リソースアダプタなどについて説明します。

＜この節の構成＞

5.3.1　使用できるJPAプロバイダ

5.3.2　使用できるコンポーネント

5.3.3　サポートするアプリケーションの形式

5.3.4　サポートするクラスローダ構成

5.3.5　使用できるリソースアダプタ

5.3.1　使用できるJPAプロバイダ

JPAプロバイダとはEntityManagerの機能を提供するエンジンのことです。アプリケーションサーバで利用できるJPAプロバイダには，Cosminexus JPAプロバイダとほかのベンダが提供するJPAプロバイダの2種類があります。それぞれのJPAプロバイダの利用について説明します。

＜この項の構成＞

(1)　Cosminexus JPAプロバイダを利用する場合

(2)　ほかのベンダのJPAプロバイダを利用する場合

(1)　Cosminexus JPAプロバイダを利用する場合

アプリケーションサーバで提供しているJPAプロバイダです。Cosminexus JPAプロバイダでは，JPA 1.0仕様に基づく機能のほかに，Cosminexus JPAプロバイダ独自の機能も提供しています。Cosminexus JPAプロバイダの概要，アプリケーション実装時の注意事項，およびCosminexus JPAプロバイダの使用方法については，「6.　Cosminexus JPAプロバイダ」を参照してください。

(2)　ほかのベンダのJPAプロバイダを利用する場合

ほかのベンダで提供しているJPAプロバイダです。JPA仕様でJPAプロバイダとアプリケーションサーバの間のインタフェースが明確にされているため，アプリケーションサーバではほかのベンダが提供しているJPA 1.0仕様に準拠したJPAプロバイダを利用することもできます。

アプリケーションサーバからほかのベンダのJPAプロバイダを利用する場合は，次の設定が必要になります。

JARファイルの指定
次のどちらかの方法でJPAプロバイダの実装が含まれるJARファイルを指定します。

簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ下にJARファイルを指定します。JARファイルを指定するには，<param-name>タグにadd.class.path，<param-value>タグにJARファイルを指定します。なお，簡易構築定義ファイルおよび指定するパラメタの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「4.6　簡易構築定義ファイル」を参照してください。

ライブラリとしてJ2EEアプリケーションに含めます。

persistence.xmlでの定義
persistence.xmlの<provider>タグに，利用するJPAプロバイダが提供するjavax.persistence.PersistenceProviderの実装クラス名を指定します。詳細については，「5.8.2(2)　<provider>タグ」を参照してください。

また，アプリケーションサーバで提供するJ2EEアプリケーション実行時間の監視機能を使用する場合は，JPAプロバイダのクラスおよびエンティティクラスを保護区リストに追加する必要があります。保護区リストへの追加方法については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「2.6　criticalList.cfg（保護区リストファイル）」を参照してください。

参考

JPAを使用したアプリケーションの実行では，アプリケーションサーバで提供する性能解析トレース機能を使用できます。

JPAプロバイダとしてCosminexus JPAプロバイダを使用する場合
性能解析トレースはアプリケーションサーバとCosminexus JPAプロバイダの両方で出力できます。

ほかのベンダのJPAプロバイダを使用する場合
アプリケーションサーバで出力する性能解析トレースだけ使用できます。

なお，アプリケーションサーバでは，javax.persistenceパッケージのEntityManagerFactory，EntityManager，EntityTransaction，およびQueryのAPIで性能解析トレースを出力します。また，JPAプロバイダでは，エンティティライフサイクルコールバックに関する性能解析トレースを出力します。

なお，性能解析トレースの概要については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「6.2　性能解析トレースの概要」を参照してください。性能解析トレースの出力ポイントについては，マニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「7.　性能解析トレースのトレース取得ポイントとPRFトレース取得レベル」を参照してください。

5.3.2　使用できるコンポーネント

アプリケーションサーバでは，EJB，WebアプリケーションでJPAを使用できます。また，Webアプリケーションからユーザスレッドを使用した場合も，JPAを使用できます。なお，次に示す環境またはライブラリではJPAを使用できません。

EJBクライアントアプリケーション環境

J2EEアプリケーションクライアント環境

コンテナ拡張ライブラリ

JPAを使用できるコンポーネントを次の表に示します。

表5-2　JPAを使用できるコンポーネント

コンポーネント | JPAの使用
EJB | Stateless Session Bean（EJB3.0以降）※1 | ○
Stateful Session Bean（EJB3.0以降）※1 | ○
Stateless Session Bean（EJB3.0より前） | ×
Stateful Session Bean（EJB3.0より前） | ×
インターセプタ | ○
Message-driven Bean | ×
Entity Bean | ×
Webアプリケーション | サーブレット，フィルタ，イベントリスナ（Servlet2.5以降） | ○
JSP，JSPのタグハンドラ，JSPのイベントリスナ，JSPのタグライブラリイベントリスナ※2（Servlet2.5以降） | ○
サーブレット，フィルタ，イベントリスナ（Servlet2.5より前） | ×
JSP，JSPのタグハンドラ，JSPのイベントリスナ，JSPのタグライブラリイベントリスナ（Servlet2.5より前） | ×

（凡例）○：使用できる　×：使用できない

注※1　アプリケーションサーバではEJB3.0のejb-jar.xmlを使用したJPAの定義はできません。このため，@PersistenceUnitや@PersistenceContextなどのアノテーションを使用して，永続化ユニットや永続化コンテキストの参照を定義してください。

注※2　アプリケーションサーバでは，JSPタグライブラリイベントリスナでのアノテーションの使用はできません。JSPタグライブラリイベントリスナでJPAの機能を使用する場合は，web.xmlの<persistence-unit-ref>タグや<persistence-context-ref>タグを使用して永続化ユニットや永続化コンテキストの参照を定義してください。

注意

Servlet 2.5のweb.xmlのmetadata-complete属性にtrueが設定されている場合，Webコンポーネントのアノテーションが読み込まれません。このため，アノテーションを使用して，永続化コンテキストまたは永続化ユニットの参照を定義することはできません。ただし，web.xmlに参照を定義することはできます。

5.3.3　サポートするアプリケーションの形式

JPAを使用したJ2EEアプリケーションは，次のどちらかの形式でアプリケーションサーバにデプロイします。

アーカイブ形式のJ2EEアプリケーション

展開ディレクトリ形式のJ2EEアプリケーション

また，デプロイ済みのJPAを使用したJ2EEアプリケーションを入れ替えることもできます。アーカイブ形式の場合はリデプロイ機能を，展開ディレクトリ形式の場合は，リロード機能を使用してください。

なお，リロード機能を使用する場合，O/Rマッピングファイルは更新検知の対象になりません。ただし，リロードされるタイミングで，O/Rマッピングファイルは再読み込みされます。次の表に，更新検知の対象およびリロード時の再読み込みについて示します。

表5-3　リロード実行時の更新検知および再読み込みの対象

対象となるクラスおよびファイル
更新検知
再読み込み

エンティティクラス
○
○

マップドスーパークラス
○
○

埋め込みクラス
○
○

persistence.xml
○
○

O/Rマッピングファイル
（META-INFの下にorm.xmlを配置する場合）
×
○

O/Rマッピングファイル
（persistence.xmlの<mapping-file>タグに指定した場所にorm.xmlを配置する場合）
○
○

（凡例）○：対象になる　×：対象にならない

アーカイブ形式のJ2EEアプリケーション，および展開ディレクトリ形式のJ2EEアプリケーションについては，「12.　J2EEアプリケーションの形式とデプロイ」を参照してください。

注意

展開ディレクトリ形式でJPAを使用したアプリケーションを利用する場合，アプリケーション動作中はクラスやライブラリJARを削除しないでください。削除した場合，アプリケーションサーバやJPAプロバイダが予期しない動作をするおそれがあります。

5.3.4　サポートするクラスローダ構成

JPAを使用したJ2EEアプリケーションでは，次の表に示すクラスローダをサポートしています。

表5-4　JPAを使用したJ2EEアプリケーションでサポートするクラスローダ

クラスローダ | サポート
デフォルトのクラスローダ構成 | ○
ローカル呼び出し最適化をしているとき※のクラスローダ構成 | ○
下位互換用のクラスローダ構成 | ×

（凡例）○：サポートする　×：サポートしない

注　下位互換用のクラスローダ構成はベーシックモードだけの使用となるため，サポートしていません。

注※　簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に次のように指定しているときを示します。

<param-name>ejbserver.rmi.localinvocation.scope</param-name>

<param-value>all</param-value>

5.3.5　使用できるリソースアダプタ

JPAを使用したJ2EEアプリケーションを実行する場合，アプリケーションサーバでは，コネクションファクトリインタフェースがjavax.sql.DataSourceであるリソースアダプタを使用できます。アプリケーションサーバで提供するリソースアダプタでは，DB Connectorを使用できます。

また，リソースアダプタを使用するには，J2EEリソースアダプタとしてデプロイする必要があります。JPAを使用したJ2EEアプリケーションの場合，リソースアダプタをJ2EEアプリケーションに含めてデプロイすることはできません。

アプリケーションサーバで使用できるリソースアダプタを次の表に示します。

表5-5　アプリケーションサーバで使用できるリソースアダプタ

コネクションファクトリインタフェース | リソースアダプタのデプロイ形式 | JPAからの使用
javax.sql.DataSource | J2EEリソースアダプタとしてデプロイする | ○
J2EEアプリケーションに含めてデプロイする | ×
javax.sql.DataSource以外 | － | ×

（凡例）○：使用できる　×：使用できない　－：該当しない

なお，Cosminexus JPAプロバイダを使用する場合に使用できるリソースアダプタについては，「6.2.3(3)　使用できるDB Connector」を参照してください。

5.4　EntityManagerとは

EntityManagerはデータベースに対してエンティティを登録したり，削除したりするためのインタフェースを持つオブジェクトです。ここでは，EntityManagerの概要について説明します。

＜この節の構成＞

5.4.1　EntityManagerで提供するメソッド

5.4.2　EntityManagerの種類

5.4.3　トランザクションの制御とEntityManager

5.4.4　永続化ユニットとは

5.4.1　EntityManagerで提供するメソッド

EntityManagerではメソッドを提供しています。代表的なメソッドを次に示します。

persistメソッド（SQLのINSERTに相当）
アプリケーションでnewを実行したエンティティオブジェクトをデータベースに追加するためのメソッドです。

findメソッド（SQLのSELECTに相当）
エンティティオブジェクトをデータベースから検索するためのメソッドです。

removeメソッド（SQLのDELETEに相当）
エンティティオブジェクトをデータベースから削除するためのメソッドです。

EntityManagerからfindメソッドで検索したエンティティオブジェクトや，persistメソッドでEntityManagerに渡したエンティティオブジェクトは，EntityManagerの管理下に置かれます。EntityManagerの管理下にあるエンティティオブジェクトについてフィールドの値が変更されると，EntityManagerは変更を自動的に検知して，変更をデータベースのテーブルに反映します。

JPAでは，EntityManagerの管理下にあるエンティティオブジェクトのことをmanaged状態のエンティティといいます。なお，デフォルトではトランザクションが決着したときに，エンティティはEntityManagerの管理下から外れます。EntityManagerの管理下から外れたエンティティのことをdetached状態のエンティティと呼びます。

5.4.2　EntityManagerの種類

EntityManagerの種類には，コンテナ管理のEntityManagerおよびアプリケーション管理のEntityManagerの2種類があります。それぞれ説明します。

＜この項の構成＞

(1)　コンテナ管理のEntityManager

(2)　アプリケーション管理のEntityManager

(1)　コンテナ管理のEntityManager

EntityManagerの作成や破棄をコンテナに任せる方法です。コンテナ管理のEntityManagerを使用すると，EntityManagerの生成や破棄を意識しないでアプリケーションをコーディングできます。コンテナ管理のEntityManagerを取得する方法と破棄する方法を説明します。

取得する方法
コンテナ管理のEntityManagerを取得するには，アプリケーションでDIまたはJNDIルックアップを使用します。この方法で取得するEntityManagerは，コンテナによって作成されたEntityManagerです。アプリケーションのコードでは，コンテナから取得したEntityManagerをそのまま使うことができます。
なお，アプリケーションからコンテナ管理のEntityManagerを取得する方法については，「5.6　コンテナ管理のEntityManagerを取得する方法」を参照してください。

破棄する方法
アプリケーション内で，EntityManagerの作成や破棄をコーディングする必要はありません。

(2)　アプリケーション管理のEntityManager

EntityManagerの作成や破棄をアプリケーションが明示的に行う方法です。アプリケーションのコードによって明示的にライフサイクルが管理されます。アプリケーション管理のEntityManagerを取得する方法と破棄する方法を説明します。

取得する方法
EntityManagerFactoryを使用して，アプリケーションでEntityManagerを作成します。EntityManagerFactoryを取得するには，アプリケーションでDIまたはJNDIルックアップを使用します。
なお，アプリケーション管理のEntityManagerを取得する方法については，「5.7　アプリケーション管理のEntityManagerを取得する方法」を参照してください。

破棄する方法
EntityManagerのcloseメソッドを呼んで，EntityManagerを破棄します。

5.4.3　トランザクションの制御とEntityManager

トランザクションの制御方法によって，EntityManagerには次の2種類があります。

JTAエンティティマネージャ
トランザクションがJTAによって制御されるEntityManagerです。

リソースローカルエンティティマネージャ
トランザクションがEntityTransaction APIによって制御されるEntityManagerです。

EntityManagerの種類とトランザクションの制御方法の関係について次の表に示します。

表5-6　EntityManagerの種類とトランザクションの制御方法の関係

EntityManagerの種類 | トランザクションの制御方法
JTA | リソースローカル
コンテナ管理のEntityManager | ○※1 | ×
アプリケーション管理のEntityManager※2 | ○ | ○

（凡例）

JTA：JTAエンティティマネージャ

リソースローカル：リソースローカルエンティティマネージャ

注※1　トランザクションは必ずJTAによって制御されます。

注※2　トランザクションをJTAによって制御するか，またはアプリケーションが明示的にEntityTransactionというAPIを使用して制御するかを選択できます。EntityTransaction APIを使用する場合は，そのトランザクションはリソースローカルトランザクションとなります。JTAトランザクションが存在した場合でも，JTAトランザクションとは無関係に制御されます。

JTAエンティティマネージャを使用するかリソースローカルエンティティマネージャを使用するかは，永続化ユニットの定義で指定します。永続化ユニットでの定義方法については，「5.8.1(2)　transaction-type属性」を参照してください。

5.4.4　永続化ユニットとは

アプリケーションからJPAを使用する場合，次のような情報を定義する必要があります。

アプリケーション内のエンティティクラスの情報

エンティティクラスとデータベーステーブルとのマッピング情報

JPAプロバイダがデータベースコネクションを取得するためのデータソースの情報

これらの情報を定義したものを永続化ユニットといいます。

永続化ユニットは，persistence.xmlで定義します。Java EE環境でJPAを使用する場合，persistence.xmlはユーザがアプリケーションをパッケージングするときに，EJB-JAR，WAR，またはEARの中の決められた場所に配置します。

persistence.xmlファイルの中には，永続化ユニットの定義を複数含めることができます。また，一つのアプリケーションの中に複数のpersistence.xmlを含めることもできます。これによって，一つのアプリケーションの中に，複数の永続化ユニットを定義できます。アプリケーション内に複数の永続化ユニットが定義されている場合，アプリケーションがどの永続化ユニットを使用するかは，@PersistenceContextのunitName属性で指定します。なお，アプリケーション内に一つだけ永続化ユニットが定義されている場合など，使用する永続化ユニットを一意に特定できる場合には，unitName属性は省略できます。

5.5　永続化コンテキストとは

EntityManagerは更新するエンティティオブジェクトや検索されたエンティティオブジェクトをキャッシングします。永続化コンテキストは，EntityManagerでキャッシングされたエンティティオブジェクトのキャッシュです。

＜この節の構成＞

5.5.1　EntityManagerと永続化コンテキスト

5.5.2　コンテナ管理のEntityManagerを使用する場合の永続化コンテキスト

5.5.3　アプリケーション管理のEntityManagerを使用する場合の永続化コンテキスト

5.5.1　EntityManagerと永続化コンテキスト

EntityManagerと永続化コンテキストの関係を次の図に示します。

図5-4　EntityManagerと永続化コンテキストの関係

EntityManagerは，永続化コンテキストの中にmanaged状態のエンティティオブジェクトを入れて管理しています。アプリケーションがエンティティオブジェクトをpersistメソッドに渡したときや，managed状態のエンティティオブジェクトについてフィールドの値を更新すると，永続化コンテキスト内のエンティティオブジェクトの状態が変更されます。EntityManagerは，トランザクションがコミットされる直前に，永続化コンテキスト内のエンティティオブジェクトとデータベースのテーブルの状態を同期させます。永続化コンテキスト内のエンティティオブジェクトの状態をデータベースのテーブルに反映するために，このときにまとめて更新SQLを発行します。これによって，データベースのロックの期間を短くできるので，同時実行性を向上したり，効率良くデータの更新をしたりできます。

＜この項の構成＞

(1)　EntityManagerの種類

(2)　永続化コンテキストの種類

(1)　EntityManagerの種類

永続化コンテキストとトランザクションの関係によって，コンテナ管理のEntityManagerとするか，アプリケーション管理のEntityManagerにするかを決めます。

永続化コンテキストがJTAトランザクションとともに自動的に伝播する必要がある場合
コンテナ管理のEntityManagerを使用します。コンテナ管理のEntityManagerを使用すると，永続化コンテキストがJTAトランザクションとともに自動的に伝播されます。このため，一つのJTAトランザクションの中で複数のコンポーネントが呼ばれた場合に，同じJTAトランザクションの中で使用されるEntityManagerは同じ永続化コンテキストに関連づけることができます。
これによって，アプリケーションはEntityManagerのリファレンスを，コンポーネントから別のコンポーネントに呼び出すときの引数に渡す必要がありません。

アプリケーションがJTAトランザクションとは独立した永続化コンテキストを使用する必要がある場合
アプリケーション管理のEntityManagerを使用します。アプリケーション管理のEntityManagerを使用すると，同じJTAトランザクションの中で別のEntityManagerを使用したときでも，これらのEntityManagerは永続化コンテキストを共有しないで，独立した永続化コンテキストを持ちます。

(2)　永続化コンテキストの種類

永続化コンテキストは生存区間によって次の2種類があります。

トランザクションスコープの永続化コンテキスト

拡張された永続化コンテキスト

コンテナ管理のEntityManagerの場合，永続化コンテキストの種類を選択できます。永続化コンテキストの種類は，@PersistenceContextのtype属性で指定します。デフォルトはトランザクションスコープの永続化コンテキストとなります。

なお，アプリケーション管理のEntityManagerの場合，常に拡張された永続化コンテキストとなります。永続化コンテキストの種類は選択できません。

5.5.2　コンテナ管理のEntityManagerを使用する場合の永続化コンテキスト

コンテナ管理のEntityManagerを使用する場合，永続化コンテキストのライフサイクルはコンテナによって管理され，JTAトランザクションとともに自動的に伝播されます。永続化コンテキストのライフサイクルの種類として，トランザクションスコープの永続化コンテキスト，または拡張された永続化コンテキストを選択できます。

それぞれの永続化コンテキストについて説明します。

＜この項の構成＞

(1)　トランザクションスコープの永続化コンテキスト

(2)　拡張された永続化コンテキスト

(3)　拡張された永続化コンテキストとトランザクション

(4)　永続化コンテキストの伝播

(1)　トランザクションスコープの永続化コンテキスト

JPA仕様では，トランザクションと同じライフサイクルの永続化コンテキストのことをトランザクションスコープの永続化コンテキストといいます。

EntityManagerのライフサイクルは，デフォルトでトランザクションのライフサイクルと同じです。このため，EntityManagerが持つ永続化コンテキストにキャッシュされた更新は，トランザクションがコミットするときにデータベースに反映されます。

(a)　永続化コンテキストのライフサイクル

トランザクションスコープの永続化コンテキストのライフサイクルを次に説明します。

永続化コンテキストの作成
トランザクションスコープの永続化コンテキストは，コンテナ管理のEntityManagerが，JTAトランザクションの中で初めて呼び出されたときに作成されます。
作成された永続化コンテキストはJTAトランザクションに関連づけられます。
その後，同じJTAトランザクションの中でコンテナ管理のEntityManagerを使用した場合には，この永続化コンテキストが使用されます。

永続化コンテキストの破棄
JTAトランザクションがコミットまたはロールバックするときに，トランザクションスコープの永続化コンテキストは破棄されます。

コンテナ管理のEntityManagerがトランザクションの外で呼び出された場合には，EntityManagerのメソッド呼び出しが終了した時点で，データベースからロードされたすべてのエンティティは即座にdetached状態となります。

(2)　拡張された永続化コンテキスト

Java EE環境では，Stateful Session BeanからEntityManagerを使用する場合には，永続化コンテキストの生存期間をStateful Session Beanの生存期間と同じにすることができます。この場合，更新はトランザクションがコミットするたびにデータベースに反映されますが，永続化コンテキスト内で管理されているエンティティオブジェクトは，複数のトランザクションにわたってmanaged状態のまま保持されます。Stateful Session Beanと同じライフサイクルの永続化コンテキストのことを，JPAでは拡張永続化コンテキストと呼びます。

拡張された永続化コンテキストは，Stateful Session Beanが作成されるのと同時に作成され，そのStateful Session Beanに関連づけされます。その後，Stateful Session Beanが破棄されるのと同時に破棄されます。

Stateful Session Beanが別のStateful Session Beanを作成する場合で，作成する側と作成される側が共に拡張永続化コンテキストを使用するように定義されている場合には，作成する側の永続化コンテキストが，作成される側に引き継がれます。この引き継ぎは，Stateful Session Beanを作成する時点でトランザクションがアクティブであるかどうかにかかわらず行われます。Stateful Session Beanの作成時に永続化コンテキストの引き継ぎが行われた場合には，その永続化コンテキストを共有するすべてのStateful Session Beanが破棄されるときに，永続化コンテキストも破棄されます。

(3)　拡張された永続化コンテキストとトランザクション

拡張された永続化コンテキストは，EntityManagerのインスタンスが作成されたときからクローズされるまで存在します。複数のトランザクションとEntityManagerのトランザクション外の呼び出しに対応しています。

トランザクションとの関連を次に示します。

EntityManagerがトランザクションの範囲内で呼び出されるか，永続化コンテキストがバインドしているstateful session beanがトランザクションのスコープで呼び出されると，EntityManagerで管理されたエンティティがトランザクションに参加します。

トランザクションが実行中かどうかにかかわらず，persist，remove，merge，refresh操作が行われることがあります。この場合，EntityManagerがトランザクションに参加して，トランザクションがコミットするときにデータベースに反映されます。

トランザクションがコミットされたあとでも，エンティティオブジェクトへの参照は保持されます。エンティティオブジェクトはEntityManagerに管理され，トランザクション間では，管理されているオブジェクト（managed状態のエンティティ）として更新されます。

(4)　永続化コンテキストの伝播

コンテナ管理のEntityManagerを使用する場合，永続化コンテキストはJTAトランザクションによって伝播され，複数のEntityManagerと関連づくことがあります。ただし，永続化コンテキストが伝播するのは，同じアプリケーションサーバ内だけです。リモートのアプリケーションサーバに永続化コンテキストが伝播されることはありません。

次に，永続化コンテキストの伝播についてコンポーネントが呼び出されたときの状態ごとに説明します。

コンポーネントが呼び出されたときに，JTAトランザクションが存在しないか，またはJTAトランザクションに永続化コンテキストが関連づいていない場合

永続化コンテキストは伝播されません。このコンポーネントからEntityManagerが呼び出した時の動作は，次のようになります。

トランザクションスコープの永続化コンテキストを使用するEntityManagerが呼び出された場合には，新しい永続化コンテキストが作成されます。

拡張永続化コンテキストを使用するEntityManagerが呼び出された場合には，呼び出されたStateful Session Beanに関連づいている拡張永続化コンテキストが使用されます。

EntityManagerが呼び出されたときに，JTAトランザクションが存在する場合には，JTAトランザクションに永続化コンテキストを関連づけます。

コンポーネントが呼び出されたときに，JTAトランザクションが伝播され，JTAトランザクションに永続化コンテキストが関連づいている場合

このコンポーネントからEntityManagerを呼び出した時の動作は次のようになります。

コンポーネントがすでに拡張永続化コンテキストを持っているStateful Session Beanにもかかわらず，JTAトランザクションに別の永続化コンテキストが関連づいている場合は，コンテナによってEJBExceptionがスローされます。

トランザクションスコープの永続化コンテキストを使用するEntityManagerが呼び出された場合，伝播してきたJTAトランザクションに関連づいている永続化コンテキストが使用されます。

5.5.3　アプリケーション管理のEntityManagerを使用する場合の永続化コンテキスト

アプリケーション管理のEntityManagerを使用する場合，アプリケーションがJPAプロバイダのEntityManagerFactoryを直接呼び出して，EntityManagerのライフサイクルおよび永続化コンテキストの作成や破棄を管理します。アプリケーション管理の永続化コンテキストのライフサイクルは，複数のトランザクションにわたったライフサイクルを管理できます。

＜この項の構成＞

(1)　EntityManagerのライフサイクルの管理

(2)　永続化コンテキストのライフサイクル

(3)　JTAエンティティマネージャを使用する場合の注意

(1)　EntityManagerのライフサイクルの管理

アプリケーションではEntityManagerのcloseメソッドやisOpenメソッドを使用して，アプリケーション管理のEntityManagerのライフサイクルを管理します。EntityManagerのcloseメソッドが呼ばれると，EntityManager，EntityManagerに関連づいた永続化コンテキストやそのほかのリソースが解放されます。closeメソッドを呼び出したあとは，アプリケーションではEntityManagerのgetTransactionメソッドとisOpenメソッド以外のメソッドを呼び出さないでください。呼び出した場合は，IllegalStateExceptionがスローされます。トランザクションがアクティブのときにcloseメソッドを呼び出した場合は，トランザクションが決着するまで永続化コンテキストは保持されたままとなります。EntityManagerのisOpenメソッドは，EntityManagerがクローズされるまではtrueを返し，クローズされたあとはfalseを返します。

(2)　永続化コンテキストのライフサイクル

アプリケーション管理の永続化コンテキストのライフサイクルを次に示します。

永続化コンテキストの作成
EntityManagerFactoryのcreateEntityManagerメソッドが呼ばれたときに作成されます。

永続化コンテキストの破棄
EntityManagerのcloseメソッドが呼ばれたときに破棄されます。

アプリケーション管理の永続化コンテキストは，トランザクションとは独立した永続化コンテキストです。このため，JTAトランザクションとともに伝播されることはありません。

(3)　JTAエンティティマネージャを使用する場合の注意

アプリケーション管理のEntityManagerでJTAエンティティマネージャを使用する場合，アプリケーションがEntityManagerをJTAトランザクションのスコープの外で作成するときは，EntityManagerのjoinTransactionを呼ぶのはアプリケーションの責任になります。アプリケーションはEntityManagerにトランザクションが開始されたことを通知する必要があるので，トランザクション開始後にEntityManagerのjoinTransactionメソッドを呼んでください。

5.6　コンテナ管理のEntityManagerを取得する方法

コンテナ管理のEntityManagerをJ2EEアプリケーションから取得するには，次の2種類の方法があります。

DIを使用してアプリケーションのフィールドやsetterメソッドにEntityManagerをインジェクトする方法

アプリケーションからJNDIを使用してEntityManagerをルックアップする方法

それぞれの方法について説明します。

＜この節の構成＞

5.6.1　アプリケーションにEntityManagerをインジェクトする方法

5.6.2　アプリケーションからEntityManagerをルックアップする方法

5.6.3　DDによる@PersistenceContext定義のオーバーライド

5.6.1　アプリケーションにEntityManagerをインジェクトする方法

アプリケーションのフィールドやsetterメソッドにEntityManagerをインジェクトする場合，さらに次の2種類の方法があります。

@PersistenceContextをインジェクト先のフィールドまたはメソッドに付加する方法

DD（web.xml）の<persistence-context-ref>タグで定義する方法

ただし，アプリケーションサーバではEJB3.0のejb-jar.xmlを使用したJPAの定義はできません。このため，EJBでJPAを使用する場合は，1.の方法で定義してください。

それぞれの方法について説明します。

＜この項の構成＞

(1)　@PersistenceContextを使用する方法

(2)　DDの<persistence-context-ref>を使用する方法

(1)　@PersistenceContextを使用する方法

@PersistenceContextを使用してEntityManagerをインジェクトする場合，インジェクト先のフィールドやsetterメソッドに@PersistenceContextを付加します。@PersistenceContextに指定できる属性について，次に示します。

(a)　unitName属性

unitName属性には，persistence.xmlで定義された永続化ユニットの名前を指定します。ただし，EJB-JARやWAR，EAR内に一つだけ永続化ユニットが定義されている場合など，使用する永続化ユニットが一意に特定できる場合には，unitName属性を省略することができます。unitName属性を省略した場合に，どの永続化ユニットが使用されるかについては，「5.11.2　永続化ユニット名の参照スコープ」を参照してください。

(b)　type属性

type属性には，永続化コンテキストのライフサイクルの種類を指定します。指定できる種類は，PersistenceContextType.TRANSACTIONまたはPersistenceContextType.EXTENDEDです。

PersistenceContextType.TRANSACTIONを指定した場合
トランザクションスコープの永続化コンテキストが使用され，トランザクションの生存期間と永続化コンテキストの生存期間が同じになります。

PersistenceContextType.EXTENDEDを指定した場合
拡張永続化コンテキストが使用され，Stateful Session Beanの生存期間と永続化コンテキストの生存期間が同じとなります。
なお，type属性にPersistenceContextType.EXTENDEDを指定した@PersistenceContextは，Stateful Session Beanのフィールドまたはメソッドにだけ付けることができます。

type属性を省略した場合のデフォルトは，PersistenceContextType.TRANSACTIONです。

(c)　properties属性

properties属性には，永続化ユニットを設定するためのJPAプロバイダ用のプロパティを指定できます。ここに指定したプロパティは，JPAプロバイダからEntityManagerを取得するときに，JPAプロバイダに渡されます。

(d)　name属性

インジェクションを使用する場合，通常name属性を指定する必要はありませんが，指定した場合には，name属性に指定した名前でEntityManagerがJNDI名前空間（java:comp/env）に登録されます。@PersistenceContextを使用してEntityManagerをインジェクトする例を次に示します。

@Stateless
public class InventoryManagerBean implements InventoryManager {
 @PersistenceContext(unitName="myUnit")
 private EntityManager em;
 ・・・
}

(2)　DDの<persistence-context-ref>を使用する方法

DDを使用してEntityManagerをインジェクトする場合，DDの<persistence-context-ref>タグに次に示すタグを定義します。

(a)　<description>タグ

<description>タグには，定義するEntityManagerリファレンスの説明をユーザが自由に記述できます。このタグを指定した場合でも，指定した内容がアプリケーションの動作に影響を与えることはありません。また，このタグは省略できます。

(b)　<persistence-context-ref-name>タグ

<persistence-context-ref-name>タグには，EntityManagerがJNDI名前空間に登録されるときの名前を指定します。指定する名前は，java:comp/envからの相対パスです。EntityManagerのJNDI登録名は必須ではありませんが，JPA仕様では，java:comp/env/persistence以下にすることが推奨されています。

(c)　<persistence-unit-name>タグ

<persistence-unit-name>タグには，persistence.xmlに定義された永続化ユニットの名前を指定します。EJB-JARやWAR，EAR内に一つだけ永続化ユニットが定義されている場合など，使用する永続化ユニットを一意に特定できる場合には，<persistence-unit-name>タグは省略できます。<persistence-unit-name>タグを省略した場合に，どの永続化ユニットが使用されるかについては，「5.11.2　永続化ユニット名の参照スコープ」を参照してください。

(d)　<persistence-context-type>タグ

<persistence-context-type>タグには，永続化コンテキストのライフサイクルの種類を指定します。「Transaction」または「Extended」を指定します。

「Transaction」を指定した場合
トランザクションスコープの永続化コンテキストが使用され，トランザクションの生存期間と永続化コンテキストの生存期間が同じになります。

「Extended」を指定した場合
拡張永続化コンテキストが使用され，Stateful Session Beanの生存期間と永続化コンテキストの生存期間が同じとなります。
なお，<persistence-context-type>タグに「Extended」を指定した<persistence-context-ref>タグは，Stateful Session Beanに対してだけ定義できます。

<persistence-context-type>タグを省略した場合のデフォルトは，「Transaction」になります。

(e)　<persistence-property>タグ

<persistence-property>タグには，永続化ユニットを設定するためのJPAプロバイダ用のプロパティを指定できます。ここに指定したプロパティは，JPAプロバイダからEntityManagerのファクトリを取得するときに，JPAプロバイダに渡されます。このタグは省略できます。

(f)　<injection-target>タグ

<injection-target>タグの<injection-target-class>タグにはインジェクト先のクラスを指定します。<injection-target>タグの<injection-target-name>タグには，インジェクト先のフィールド名またはsetterメソッド名を指定します。web.xmlに<persistence-context-ref>タグを定義してEntityManagerをインジェクトする例を次に示します。

...
<web-app>
 ...
 <servlet>
   <display-name>InventoryManagerServlet</display-name>
   <servlet-name>InventoryManagerServlet</servlet-name>
   <servlet-class>com.hitachi.InventoryManagerServlet</servlet-class>
 </servlet>
 ...
 <persistence-context-ref>
   <description>
     Persistence context for the inventory management application.
   </description>
   <persistence-context-ref-name>persistence/InventoryAppMgr
   </persistence-context-ref-name>
   <persistence-unit-name>InventoryManagement</persistence-unit-name>
   <persistence-context-type>Transaction</persistence-context-type>
   <injection-target>
     <injection-target-class>
       com.hitachi.InventoryManagerServlet
     </injection-target-class>
     <injection-target-name>em</injection-target-name>
   </injection-target>
 </persistence-context-ref>
 ...
</web-app>
...

5.6.2　アプリケーションからEntityManagerをルックアップする方法

JNDIを使用してアプリケーションからEntityManagerをルックアップする場合，さらに次の2種類の方法があります。

EntityManagerをルックアップするクラスに@PersistenceContextを付加して，EntityManagerのリファレンスを定義する方法

DD（web.xml）で<persistence-context-ref>タグを定義して，EntityManagerのリファレンスを定義する方法

ただし，アプリケーションサーバではEJB3.0のejb-jar.xmlを使用したJPAの定義はできません。このため，EJBでJPAを使用する場合は，1.の方法で定義してください。

それぞれの方法について説明します。

＜この項の構成＞

(1)　@PersistenceContextを使用する方法

(2)　DDの<persistence-context-ref>を使用する方法

(1)　@PersistenceContextを使用する方法

@PersistenceContextを使用してEntityManagerのリファレンスを定義する場合，ルックアップを実行するクラスに@PersistenceContextを付加します。

@PersistenceContextに指定できる属性について，次に説明します。

(a)　name属性

name属性には，アプリケーションのコードがEntityManagerをルックアップするときのルックアップ名を指定します。指定するルックアップ名は，java:comp/envからの相対パスです。EntityManagerのルックアップ名は，必須ではありませんが，JPA仕様では，java:comp/env/persistence以下にすることが推奨されています。

@PersistenceContextのそのほかの属性については，「5.6.1　アプリケーションにEntityManagerをインジェクトする方法」と同じです。なお，拡張スコープのEntityManagerのルックアップは，Stateful Session Beanだけできます。また，一つのクラスに複数の@PersistenceContextを付加する場合には，クラスに@PersistenceContextsを付加し，そのvalue属性として@PersistenceContextの配列を指定してください。次に，@PersistenceContextを使用してSessionContextからEntityManagerをルックアップする例を示します。

@Stateless
@PersistenceContext(name="persistence/OrderEM")
public class MySessionBean implements MyInterface {
 @Resource SessionContext ctx;
 public void doSomething() {
   ・・・
   EntityManager em = (EntityManager)ctx.lookup("persistence/OrderEM");
   ・・・
 }
}

次に，@PersistenceContextを使用してInitialContextからEntityManagerをルックアップする例を示します。

@Stateless
@PersistenceContext(name="persistence/InventoryAppMgr")
public class InventoryManagerBean implements InventoryManager {
 public void updateInventory(...) {
   ・・・
   Context initCtx = new InitialContext();
   EntityManager em = (EntityManager)
     initCtx.lookup("java:comp/env/persistence/InventoryAppMgr");
   ・・・
 }
}

(2)　DDの<persistence-context-ref>を使用する方法

DDを使用してEntityManagerのリファレンスを定義する場合，DDの<persistence-context-ref>タグに次に示すタグを定義します。

(a)　<persistence-context-ref-name>タグ

<persistence-context-ref-name>タグには，アプリケーションのコードがEntityManager をルックアップするときのルックアップ名を指定します。指定するルックアップ名は，java:comp/envからの相対パスです。EntityManagerのルックアップ名は，必須ではありませんが，JPA仕様ではjava:comp/env/persistence以下にすることが推奨されています。

<persistence-context-ref>タグのそのほかのタグについては，「5.6.1　アプリケーションにEntityManagerをインジェクトする方法」と同じです。ただし，JNDIルックアップでEntityManager を取得する場合，<injection-target>は指定しません。なお，拡張スコープのEntityManagerのルックアップは，Stateful Session Beanからできます。

次に，web.xmlに<persistence-context-ref>を定義する例を示します。

...
<web-app>
 ...
 <servlet>
   <display-name>InventoryManagerServlet</display-name>
   <servlet-name>InventoryManagerServlet</servlet-name>
   <servlet-class>com.hitachi.InventoryManagerServlet</servlet-class>
 </servlet>
 ...
 <persistence-context-ref>
   <description>
     Persistence context for the inventory management application.
   </description>
   <persistence-context-ref-name>
     persistence/InventoryAppMgr
   </persistence-context-ref-name>
   <persistence-unit-name>InventoryManagement</persistence-unit-name>
   <persistence-context-type>Transaction</persistence-context-type>
 </persistence-context-ref>
 ...
</web-app>
...

5.6.3　DDによる@PersistenceContext定義のオーバーライド

@PersistenceContextをアプリケーションに記載している場合に，DDで<persistence-context-ref>タグを定義していると，アノテーションで定義した内容はDDで定義した内容で上書きされます。この場合，アノテーションとDDとの対応は，@PersistenceContextのname属性と，DDの<persistence-context-ref>タグ下にある<persistence-context-ref-name>タグの対応で判断されます。なお，@PersistenceContextでname属性が明示的に指定されていない場合でも，name属性にはデフォルト値が存在するので注意が必要です。

次に@PersistenceContextに指定した属性がDDのタグでオーバーライドされるときの注意について説明します。

＜この項の構成＞

(1)　<persistence-unit-name>タグとunitName属性

(2)　<persistence-context-type>タグとtype属性

(3)　<persistence-property>タグとproperties属性

(4)　<injection-target>タグ

(1)　<persistence-unit-name>タグとunitName属性

DDの<persistence-unit-name>タグは@PersistenceContextのunitName属性をオーバーライドします。通常，永続化ユニット名を変更すると，アプリケーションは動作しなくなるので，DDおよびアノテーションを定義する際には注意してください。

(2)　<persistence-context-type>タグとtype属性

DDの<persistence-context-type>タグは@PersistenceContextのtype属性をオーバーライドします。通常，永続化コンテキストのライフサイクルの種類を変更すると，アプリケーションは動作しなくなるので，DDおよびアノテーションを定義する際には注意してください。

(3)　<persistence-property>タグとproperties属性

DDの<persistence-property>に指定されたプロパティは，@PersistenceContexのproperties属性に指定されたプロパティに追加されます。ただし，プロパティ名が同じ場合には，プロパティ値がオーバーライドされます。

(4)　<injection-target>タグ

インジェクションターゲットをオーバーライドすることはできません。なお，DDに<injection-target>タグを記述する場合には，@PersistenceContexが付加されたフィールドやメソッドを正確に指定してください。

5.7　アプリケーション管理のEntityManagerを取得する方法

アプリケーション管理のEntityManagerを使用する場合，アプリケーションはEntityManagerFactoryを使用してEntityManagerを作成します。アプリケーションがEntityManagerFactoryを取得するには，次の2種類の方法があります。

DIを使用してアプリケーションのフィールドやsetterメソッドにEntityManagerFactoryをインジェクトする方法

アプリケーションからJNDIを使用してEntityManagerFactoryをルックアップする方法

それぞれの方法について説明します。

＜この節の構成＞

5.7.1　アプリケーションにEntityManagerFactoryをインジェクトする方法

5.7.2　アプリケーションからEntityManagerFactoryをルックアップする方法

5.7.3　DDによる@PersistenceUnit定義のオーバーライド

5.7.1　アプリケーションにEntityManagerFactoryをインジェクトする方法

アプリケーションのフィールドやsetterメソッドにEntityManagerFactoryをインジェクトする場合，さらに次の2種類の方法があります。

@PersistenceUnitをインジェクト先のフィールドまたはメソッドに付加する方法

DD（web.xml）の<persistence-unit-ref>タグで定義する方法

ただし，アプリケーションサーバではEJB3.0のejb-jar.xmlを使用したJPAの定義はできません。このため，EJBでJPAを使用する場合は，1.の方法で定義してください。

それぞれの方法について説明します。

＜この項の構成＞

(1)　@PersistenceUnit を使用する方法

(2)　DDの<persistence-unit-ref>タグを使用する方法

(1)　@PersistenceUnit を使用する方法

@PersistenceUnitを使用してEntityManagerFactoryをインジェクトする場合，インジェクト先のフィールドやsetterメソッドに@PersistenceUnitを付加します。@PersistenceUnitに指定できる属性について説明します。

(a)　unitName属性

unitName属性には，persistence.xmlで定義された永続化ユニットの名前を指定します。ただし，EJB-JARやWAR，EAR内に一つだけ永続化ユニットが定義されている場合など，使用する永続化ユニットが一意に特定できる場合には，unitName属性を省略できます。unitName属性を省略した場合に，どの永続化ユニットが使用されるかについては，「5.11.2　永続化ユニット名の参照スコープ」を参照してください。

(b)　name属性

インジェクションを使用する場合，通常name属性を指定する必要はありませんが，指定した場合には，name属性に指定した名前でEntityManagerがJNDI 名前空間（java:comp/env）に登録されます。次に，@PersistenceUnit を使用してEntityManagerFactory をインジェクトする例を示します。

@Stateless
public class InventoryManagerBean implements InventoryManager {
 @PersistenceUnit(unitName="myUnit")
 private EntityManagerFactory emf;
 ・・・
}

(2)　DDの<persistence-unit-ref>タグを使用する方法

DDを使用してEntityManagerFactoryをインジェクトする場合，DDの<persistence-unit-ref>タグに次に示すタグを定義します。

(a)　<persistence-unit-ref-name>タグ

<persistence-unit-ref-name>タグには，EntityManagerFactoryがJNDI名前空間に登録されるときの名前を指定します。指定する名前は，java:comp/envからの相対パスです。

EntityManagerFactoryのJNDI登録名は必須ではありませんが，JPA仕様では，java:comp/env/persistence以下にすることが推奨されています。

(b)　<description>タグ

<description>タグには，定義するEntityManagerFactoryリファレンスの説明をユーザが自由に記述することができます。このエレメントを指定した場合でも，指定した内容がアプリケーションの動作に影響を与えることはありません。また，このタグは省略できます。

(c)　<persistence-unit-name>タグ

<persistence-unit-name>タグには，persistence.xmlに定義された永続化ユニットの名前を指定します。EJB-JARやWAR，EAR内に一つだけ永続化ユニットが定義されている場合など，使用する永続化ユニットを一意に特定できる場合には，<persistence-unit-name>タグは省略できます。<persistence-unit-name>タグを省略した場合に，どの永続化ユニットが使用されるかについては，「5.11.2　永続化ユニット名の参照スコープ」を参照してください。

(d)　<injection-target>タグ

<injection-target>タグの<injection-target-class>タグにはインジェクト先のクラスを指定します。<injection-target>タグの<injection-target-name>タグには，インジェクト先のフィールド名またはsetterメソッド名を指定します。次に，web.xmlに<persistence-unit-ref>を定義してEntityManagerFactory をインジェクトする例を示します。

...
<web-app>
 ...
 <servlet>
   <display-name>InventoryManagerServlet</display-name>
   <servlet-name>InventoryManagerServlet</servlet-name>
   <servlet-class>com.hitachi.InventoryManagerServlet</servlet-class>
 </servlet>
 ...
 <persistence-unit-ref>
   <description>
     Persistence unit for the inventory management application.
   </description>
   <persistence-unit-ref-name>persistence/InventoryAppDB
   </persistence-unit-ref-name>
   <persistence-unit-name>InventoryManagement</persistence-unit-name>
   <injection-target>
     <injection-target-class>
       com.hitachi.InventoryManagerServlet
     </injection-target-class>
     <injection-target-name>emf</injection-target-name>
   </injection-target>
 </persistence-unit-ref>
 ...
</web-app>
...

5.7.2　アプリケーションからEntityManagerFactoryをルックアップする方法

JNDIを使用してアプリケーションからEntityManagerFactoryをルックアップする場合，さらに次の2種類の方法があります。

EntityManagerFactoryをルックアップするクラスに@PersistenceUnitを付加して，EntityManagerFactoryのリファレンスを定義する方法

DD（web.xml）で<persistence-unit-ref>タグを定義して，EntityManagerFactoryのリファレンスを定義する方法

ただし，アプリケーションサーバではEJB3.0のejb-jar.xmlを使用したJPAの定義はできません。このため，EJBでJPAを使用する場合は，1.の方法で定義してください。

それぞれの方法について説明します。

＜この項の構成＞

(1)　@PersistenceUnitを使用する方法

(2)　DDの<persistence-unit-ref>タグを使用する方法

(1)　@PersistenceUnitを使用する方法

@PersistenceUnitを使用してEntityManagerFactoryのリファレンスを定義する場合，ルックアップを行うクラスに@PersistenceUnitを付加します。@PersistenceUnitに指定できる属性について説明します。

(a)　name属性

name属性には，アプリケーションのコードがEntityManagerFactoryをルックアップするときのルックアップ名を指定します。指定するルックアップ名は，java:comp/envからの相対パスです。EntityManagerFactoryのルックアップ名は，必須ではありませんが，JPA 仕様ではjava:comp/env/persistence以下にすることが推奨されています。

@PersistenceUnitのそのほかの属性については，「5.7.1　アプリケーションにEntityManagerFactoryをインジェクトする方法」と同じです。なお，一つのクラスに複数の@PersistenceUnitを付加する場合には，クラスに@PersistenceUnitsを付加し，そのvalue属性として@PersistenceUnitの配列を指定してください。次に，@PersistenceContextを使用してSessionContextからEntityManagerFactoryをルックアップする例を示します。

@Stateless
@PersistenceUnit(name="persistence/InventoryAppDB")
public class InventoryManagerBean implements InventoryManager {
 @Resource SessionContext ctx;
 public void updateInventory(...) {
   ・・・
   EntityManagerFactory emf = (EntityManagerFactory)
     ctx.lookup("persistence/InventoryAppDB");
   EntityManager em = emf.createEntityManager();
   ・・・
 }
}

次に，@PersistenceContextを使用してInitialContextからEntityManagerFactoryをルックアップする例を示します。

@Stateless
@PersistenceUnit(name="persistence/InventoryAppDB")
public class InventoryManagerBean implements InventoryManager {
 public void updateInventory(...) {
   Context initCtx = new InitialContext();
   EntityManagerFactory emf = (EntityManagerFactory)
     initCtx.lookup("java:comp/env/persistence/InventoryAppDB");
   EntityManager em = emf.createEntityManager();
   ・・・
 }
}

(2)　DDの<persistence-unit-ref>タグを使用する方法

DDを使用してEntityManagerFactoryのリファレンスを定義する場合，DDの<persistence-unit-ref>タグを定義します。

(a)　<persistence-unit-ref-name>タグ

<persistence-unit-ref-name>タグには，アプリケーションのコードがEntityManagerFactoryをルックアップするときのルックアップ名を指定します。指定するルックアップ名は，java:comp/envからの相対パスです。EntityManagerFactoryのルックアップ名は，必須ではありませんが，JPA仕様でjava:comp/env/persistence以下にすることが推奨されています。

<persistence-unit-ref>のそのほかのタグについては，「5.7.1　アプリケーションにEntityManagerFactoryをインジェクトする方法」と同じです。ただし，JNDIルックアップでEntityManagerFactoryを取得する場合，<injection-target>タグは指定しません。次に，web.xmlに<persistence-unit-ref>を定義する例を示します。

...
<web-app>
 ...
 <servlet>
   <display-name>InventoryManagerServlet</display-name>
   <servlet-name>InventoryManagerServlet</servlet-name>
   <servlet-class>com.hitachi.InventoryManagerServlet</servlet-class>
 </servlet>
 ...
 <persistence-unit-ref>
   <description>
    Persistence unit for the inventory management application.
   </description>
   <persistence-unit-ref-name>
     persistence/InventoryAppDB
   </persistence-unit-ref-name>
   <persistence-unit-name>InventoryManagement</persistence-unit-name>
 </persistence-unit-ref>
 ...
</web-app>
...

5.7.3　DDによる@PersistenceUnit定義のオーバーライド

@PersistenceUnitをアプリケーションに記載している場合に，DDで<persistence-unit-ref>タグを定義していると，アノテーションで定義した内容はDDで定義した内容で上書きされます。この場合，アノテーションとDDとの対応は，@PersistenceUnitのname属性とDDの<persistence-unit-ref>タグ下にある<persistence-unit-ref-name>タグの対応で判断されます。@PersistenceUnitでname属性が明示的に指定されていない場合，name属性にはデフォルト値が存在するので注意が必要です。

次に@PersistenceUnitに指定した属性がDDのタグでオーバーライドされるときの注意について説明します。

＜この項の構成＞

(1)　<persistence-unit-name>とunitName属性

(2)　<injection-target>タグ

(1)　<persistence-unit-name>とunitName属性

DDの<persistence-unit-name>は@PersistenceUnitのunitName属性をオーバーライドします。通常，永続化ユニット名を変更すると，アプリケーションは動作しなくなるので，変更には注意が必要です。

(2)　<injection-target>タグ

DDでインジェクションターゲットをオーバーライドすることはできません。DDに<injection-target>を記述する場合には，@PersistenceContextが付加されたフィールドやメソッドを正確に指定しなければなりません。

5.8　persistence.xmlでの定義

永続化ユニットの情報はpersistence.xmlの<persistence-unit>タグを使用して定義します。ここでは，<persistence-unit>タグの属性および<persistence-unit>タグ下に指定するタグについて説明します。

なお，<persistence-unit>タグの属性および<persistence-unit>タグ下に指定するタグに指定した値の先頭および末尾に付加された空白文字や改行文字は無視されます。

persistence.xmlのタグの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「6.2　persistence.xml」を参照してください。

＜この節の構成＞

5.8.1　<persistence-unit>タグに指定する属性

5.8.2　<persistence-unit>タグ下に指定するタグ

5.8.1　<persistence-unit>タグに指定する属性

<persistence-unit>タグにはname属性とtransaction-type属性を指定します。

＜この項の構成＞

(1)　name属性

(2)　transaction-type属性

(1)　name属性

定義する永続化ユニットの名前を指定します。ここで指定した名前は，アノテーションの場合，@PersistenceUnitまたは@PersistenceContextのunitName属性から参照されます。また，DDの場合は，<persistence-context-ref>タグ下または<persistence-unit-ref>タグ下の<persistence-unit-name>タグから参照されます。

name属性は省略できません。また，アプリケーションサーバでJPAを使用する場合，name属性には空文字を指定できません。1文字以上の文字列を指定してください。

(2)　transaction-type属性

定義する永続化ユニットで，トランザクションをJTAによってコントロールするか，javax.persistence.EntityTransactionを使用してアプリケーションがコントロールするかを指定します。

トランザクションをJTAによってコントロールする場合
transaction-type属性には「JTA」を指定します。「JTA」を指定した場合には，同時に<jta-data-source>タグも指定する必要があります。

EntityTransactionを使用してアプリケーションがトランザクションをコントロールする場合
transaction-type属性には「RESOURCE_LOCAL」を指定します。「RESOURCE_LOCAL」を指定した場合には，<non-jta-data-source>タグも同時に指定する必要があります。

なお，transaction-type属性を省略した場合，デフォルトは「JTA」となります。

5.8.2　<persistence-unit>タグ下に指定するタグ

<persistence-unit>タグ下には，次の表に示すタグを指定します。

表5-7　<persistence-unit>タグ下に指定するタグ

指定するタグ
設定内容

<description>タグ
永続化ユニットの説明を記載します。

<provider>タグ
使用するJPAプロバイダを指定します。

<jta-data-source>タグ
<non-jta-data-source>タグ
JPAプロバイダで使用するJTAデータソースまたは非JTAデータソースを指定します。

<mapping-file>タグ
使用するO/Rマッピングファイルを指定します。

<jar-file>タグ
entityクラス，embeddableクラス，mappedsuperクラスを含むJARファイル名を指定します。

<class>タグ
entityクラス，embeddableクラス，mappedsuperクラスを指定します。

<exclude-unlisted-classes>タグ
Perisitenceクラスとして扱うかどうかを指定します。

<properties>タグ
JPAプロバイダ固有のプロパティを指定します。

それぞれのタグについて説明します。

＜この項の構成＞

(1)　<description>タグ

(2)　<provider>タグ

(3)　<jta-data-source>タグ，<non-jta-data-source>タグ

(4)　<mapping-file>，<jar-file>，<class>，<exclude-unlisted-classes>タグ

(5)　<properties>タグ

(1)　<description>タグ

ユーザが永続化ユニットの説明を自由に記述できます。ここに指定した内容がアプリケーションの動作に影響を与えることはありません。なお，このタグは省略できます。

(2)　<provider>タグ

永続化ユニットで使用するJPAプロバイダを指定します。JPAプロバイダのjavax.persistence.spi.PersistenceProviderインタフェースの実装クラス名を，パッケージ名を含めた完全修飾名で指定します。このタグは省略できます。

このタグを省略した場合，簡易構築定義ファイルで指定したデフォルトのJPAプロバイダが使用されます。また，このタグを省略した場合で，簡易構築定義ファイルでデフォルトのJPAプロバイダが指定されていないときには，JPAプロバイダとしてCosminexus JPAプロバイダが使用されます。

なお，アプリケーションが特定のJPAプロバイダの機能や挙動に依存している場合は，<provider>タグを必ず指定してください。

ポイント

簡易構築定義ファイルでデフォルトのJPAプロバイダを指定するには，論理J2EEサーバの<param-name>タグにejbserver.jpa.defaultProviderClassNameを指定して，<param-value>タグにデフォルトのJPAプロバイダクラス名を指定します。

なお，簡易構築定義ファイルで，論理J2EEサーバの<param-name>タグにejbserver.jpa.overrideProviderパラメタが指定されているときは，ejbserver.jpa.overrideProviderパラメタの<param-value>タグに指定されているJPAプロバイダクラス名が，<provider>タグやejbserver.jpa.defaultProviderClassNameパラメタに指定した値よりも優先して使用されます。

簡易構築定義ファイルに指定するパラメタについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「4.6.2　簡易構築定義ファイルの指定内容」を参照してください。

永続化ユニットで使用されるJPAプロバイダを決定する優先順位を次の表に示します。

表5-8　永続化ユニットで使用されるJPAプロバイダを決定する優先順位

優先度
使用するJPAプロバイダ

1
簡易構築定義ファイルのejbserver.jpa.overrideProviderプロパティに指定された値

2
persistence.xmlの<provider>タグに指定された値

3
Cosminexus JPAプロバイダ
（簡易構築定義ファイルのejbserver.jpa.defaultProviderClassNameパラメタを使用して変更することもできる）

(3)　<jta-data-source>タグ，<non-jta-data-source>タグ

JPAプロバイダが使用するJTAデータソースまたは非JTAデータソースを指定します。ここに指定する値は，JPA仕様上は製品依存となっていますが，アプリケーションサーバでは次のようにデータソースの参照を定義します。

Connector 1.0に準拠したリソースアダプタを参照する場合
「<リソースアダプタの表示名>」または「<リソースアダプタの別名>」を指定してください。

Connector 1.5に準拠したリソースアダプタを参照する場合
「<リソースアダプタの表示名>!<コネクション定義識別子>」または「リソースアダプタの別名」を指定してください。

指定した値は「<リソースアダプタの表示名>」または「<リソースアダプタの表示名>!<コネクション定義識別子>」として解釈され，該当するリソースアダプタを検索します。該当するリソースアダプタが存在しない場合，指定した値は「<リソースアダプタの別名>」として解釈され，該当するリソースアダプタを検索します。

また，参照するリソースアダプタは，J2EEリソースアダプタとしてデプロイする必要があります（スタンドアロンモジュールとしてデプロイする方法）。リソースアダプタは，永続化ユニットを含むアプリケーションを開始するより前に，開始してください。

<jta-data-source>タグ，<non-jta-data-source>タグは省略できます。省略した場合には，簡易構築定義ファイルのejbserver.jpa.defaultJtaDsNameパラメタまたはejbserver.jpa.defaultNonJtaDsNameパラメタに指定した値が使用されます。ただし，これらのプロパティにはデフォルト値がありません。

ejbserver.jpa.overrideJtaDsNameパラメタまたはejbserver.jpa.overrideNonJtaDsNameパラメタに値が指定されている場合は，<jta-data-source>タグ，<non-jta-data-source>タグに指定された値や，ejbserver.jpa.defaultJtaDsNameパラメタ，ejbserver.jpa.defaultNonJtaDsNameパラメタに指定された値よりも優先して使用されます。

なお，<jta-data-source>タグに指定するリソースアダプタのトランザクションサポートレベルには，LocalTransactionまたはXATransactionを指定する必要があります。また，<non-jta-data-source>に指定するリソースアダプタのトランザクションサポートレベルには，NoTransactionを指定する必要があります。

永続化ユニットで使用されるJTAデータソースおよび非JTAデータソースを決定するときの優先順位を次の表に示します。

表5-9　永続化ユニットで使用されるJTA データソースおよび非JTAデータソースを決定する優先順位

優先度 | 使用するJPAプロバイダ
1 | 簡易構築定義ファイルのejbserver.jpa.overrideJtaDsNameプロパティまたはejbserver.jpa.overrideNonJtaDsNameプロパティに指定された値
2 | persistence.xml の<jta-data-source>または<non-jta-data-source>エレメントに指定された値
3 | 簡易構築定義ファイルのejbserver.jpa.defaultJtaDsNameプロパティまたはejbserver.jpa.defaultNonJtaDsNameプロパティに指定した値

注意

persistence.xmlの<jta-data-source>タグまたは<non-jta-data-source>タグで，半角英数字およびアンダースコア(_)以外の文字が含まれているリソースアダプタの表示名を指定する場合，その文字をアンダースコア（_）に置き換えて指定してください。ただし，置き換えたあとの表示名の文字列がほかのリソースアダプタの表示名や別名と重複した場合，永続化ユニットは意図しないデータソースを使用して動作をしてしまう場合があるので注意してください。

(4)　<mapping-file>，<jar-file>，<class>，<exclude-unlisted-classes>タグ

永続化ユニットに含めるエンティティクラス，埋め込み可能クラス，マッピングされたスーパークラスを指定するには次の二つの方法があります。

O/Rマッピングファイルや<class>タグを使用して明示的に指定する方法

明示的には指定しないでJPAプロバイダによる自動検索を使用する方法

ここでは，1.の方法について説明します。

(a)　O/Rマッピングファイルを使って指定する

永続化ユニットルートのMETA-INFの下，または永続化ユニットから<jar-file>タグで参照している別のJARファイル内のMETA-INFの下に，「orm.xml」という名前のXMLファイルが配置されている場合，<mapping-file>タグに指定しなくても自動的にO/Rマッピングファイルとして扱われます。さらに，<mapping-file>タグにクラスパス上でロードできるXMLファイル名を指定した場合，そのXMLファイルもO/Rマッピングファイルとして扱われます。一つの永続化ユニットに複数のO/Rマッピングファイルが含まれている場合，すべてのO/Rマッピングファイルからマッピング情報が読み込まれます。ただし，複数のO/Rマッピングファイルの間で，重複してマッピングを定義している場合の動作は規定されていません。

(b)　パシステンスクラスを検索するJARファイルを指定する

<jar-file>タグには，パシステンスクラスやO/Rマッピングファイルを含んだJARファイルを指定できます。<jar-file>タグに指定されたJARファイルからは，@Entity，@Embeddable，@MappedSuperclassが付加されたクラスが検索され，マッピング情報が自動的に取得されます。指定したJARファイル内にMETA-INF/orm.xmlが存在する場合，orm.xmlからもマッピング情報が取得されます。なお，<jar-file>タグと<mapping-file>タグを併用することもできます。

<jar-file>タグで指定できるJARファイルは，クラスパスに含まれている必要があります。指定できるのは次に示すJARファイルとなります。

EARのルートに置いたJARファイル

EARのライブラリディレクトリに置いたJARファイル

EJB-JAR

WARの中のWEB-INF/libに置いたJARファイル

ただし，EARレベルまたはEJB-JARレベルに定義された永続化ユニットの<jar-file>タグに，WARの中のWEB-INF/libに置いたJARファイルを指定することはできません。これは，WARの中のWEB-INF/libに置いたJARファイルはWEBアプリケーション用のクラスローダでロードされるので，WARの中のコンポーネント以外からは参照できないためです。

また，WARレベルに定義された永続化ユニットの<jar-file>タグからは，同じWARの中に含まれたJARファイルだけが指定できます。これは，同じWAR以外の場所に配置されたJARファイルに含まれるクラスは，WARレベルに定義された永続化ユニットのデプロイメントが行われるよりも前にクラスローダによってロードされる可能性があるためです。このような場合，JPAプロバイダによるバイトコードの変換が正しく行われないおそれがあります。

<jar-file>タグには，永続化ユニットルートからJARファイルへの相対パスを指定します。指定例を次に示します。

例1

次の図に示す場合の相対パスの指定について説明します。

EARのlibにエンティティクラスを格納したmyEntities.jarがある。

EARのルートに置いたEJB-JARのMETA-INF/persistence.xmlの<jar-file>タグでmyEntities.jarを指定する。

この図の場合，永続化ユニットのルートはEJB-JARそのものになるので，EJB-JARからmyEntities.jarへの相対パスを指定します。相対パスは，「lib/myEntities.jar」です。このため，<jar-file>タグに「lib/myEntities.jar」と指定します。

例2

次の図に示す場合の相対パスの指定について説明します。

EARのルートにエンティティクラスを格納したmyEntities.jarがある。

EARのlib/myPersistenceUnit.jarのMETA-INF/persistence.xmlの<jar-file>タグでmyEntities.jarを指定する。

この図の場合，永続化ユニットのルートはmyPersistenceUnit.jarになるので，myPersistenceUnit.jarからmyEntities.jarへの相対パスを指定します。相対パスは，「../myEntities.jar」です。このため，<jar-file>タグには「../myEntities.jar」と指定します。

例3

次の図に示す場合の相対パスの指定について説明します。

WARのWEB-INF/libにエンティティクラスを格納したmyEntities.jarがある。

WARのWEB-INF/classes/META-INF/persistence.xmlの<jar-file>タグでmyEntities.jarを指定する。

この図の場合，永続化ユニットルートはWARのWEB-INF/classesになるので，WEB-INF/classesからmyEntities.jarへの相対パスを指定します。相対パスは「../lib/myEntities.jar」です。このため，<jar-file>タグには「../lib/myEntities.jar」と指定します。

(c)　パシステンスクラスのリストを明示的に指定する

<class>タグを使用すると，パシステンスクラスのリストを明示的に指定できます。マッピング情報は，指定されたクラスに付加されたアノテーションから取得されます。なお，<class>タグは，<mapping-file>タグや<jar-file>タグと併用することもできます。

(d)　アノテーションを付加したパシステンスクラスを永続化ユニットのルートに配置する

永続化ユニットのルートからは，@Entity，@Embeddable，@MappedSuperclassの付加されたパシステンスクラスが自動的に検索されます。マッピング情報はクラスに付加されたアノテーションから取得されます。永続化ユニットのルートに配置したアノテーションの付加されたクラスを永続化ユニットに加えたくない場合には，<exclude-unlisted-classes>タグを指定しておく必要があります。

(5)　<properties>タグ

JPAプロバイダのベンダ特有のプロパティを指定できます。JPAプロバイダが理解できないプロパティを指定した場合は，単に無視されます。なお，「javax.persistence」で始まるプロパティを<properties>に指定することはできません。

システムプロパティとして，プロパティ名がプレフィックス「ejbserver.jpa.emfprop.」で始まるプロパティを指定しておくと，プレフィックスを除去したプロパティが，永続化ユニットのプロパティに追加されます。

5.9　persistence.xmlの配置

persistence.xmlはEJB-JAR，WAR，EARの中に配置します。persistence.xmlは必ずMETA-INFの下に置く必要があります。META-INFの下にpersistence.xmlを持つパスを永続化ユニットのルートと呼びます。

persistence.xmlを配置できる場所を次に示します。

EJB-JARのMETA-INF/persistence.xml

WARのWEB-INF/classes/META-INF/persistence.xml

WARのWEB-INF/libの下に置いたjarファイルの中のMETA-INF/persistence.xml

EARのルートディレクトリに置いたjarファイルの中のMETA-INF/persistence.xml

EARのライブラリディレクトリに置いたjarファイルの中のMETA-INF/persistence.xml

一つのpersistence.xmlには複数の永続化ユニットを定義できます。永続化ユニットには名前を付ける必要があります。ただし，一つのEJB-JAR，WAR，EAR内には，重複した名前の永続化ユニットを複数定義することはできません。

EAR内に定義した永続化ユニットで管理されるクラスは，アプリケーションのクラスローダでロードされ，アプリケーション内のすべてのコンポーネントから参照できます。

また，別々のEJB-JARやWAR内のコンポーネントから，同じエンティティクラスを参照する場合，仮に永続化ユニットが別々であったとしても参照されるクラスは同じ一意なクラスとなります。

5.10　JPAのインタフェース

JPAのインタフェースを紹介します。ここでは，javax.persistence.EntityManagerインタフェースおよびjavax.persistence.EntityManagerFactoryインタフェースについて説明します。

＜この節の構成＞

5.10.1　javax.persistence.EntityManagerインタフェース

5.10.2　javax.persistence.EntityManagerFactoryインタフェース

5.10.1　javax.persistence.EntityManagerインタフェース

ここでは，javax.persistence.EntityManagerインタフェースについてインタフェース定義と注事事項を説明します。

＜この項の構成＞

(1)　インタフェース定義

(2)　注意事項

(1)　インタフェース定義

package javax.persistence;

/**
* 永続化コンテキストを操作するためのインタフェース。
*
* EntityManagerインスタンスは永続化コンテキストと関連づけられています。
* 永続化コンテキストは，エンティティインスタンスのセットであり，
* 永続化されたエンティティごとに，エンティティのインスタンスは
* ユニークになっています。
* 永続化コンテキスト内では，エンティティのインスタンスと
* そのライフサイクルが管理されています。
* EntityManagerインタフェースは，永続化コンテキストを操作するための
* メソッドを定義しており，永続化されたエンティティインスタンスの作成・削除や，
* プライマリキーによるエンティティの検索，エンティティのクエリの実行などに
* 使用されます。
*
* EntityManagerによって管理できるエンティティのセットは，永続化ユニットで
* 定義します。
* 永続化ユニットは，アプリケーションによって使用されるエンティティクラスの
* グループを定義し，エンティティクラスとデータベースとのマッピングも
* 定義します。
*/
public interface EntityManager {

 /**
 * インスタンスをマネージド状態にして，永続化します。
 * @param entity 永続化するエンティティのインスタンス
 * @throws EntityExistsException エンティティがすでに存在した場合
 * （persistメソッドが呼ばれた時にEntityExistsExceptionがスローされるか，
 * flushまたはコミット時にEntityExistsExceptionまたは
 * そのほかのPersistenceExceptionがスローされます）
 * @throws IllegalArgumentException エンティティではない場合
 * @throws TransactionRequiredException PersistenceContextType.TRANSACTIONが指定された
 * コンテナ管理のエンティティマネージャが，トランザクションが存在しない時に
 * 呼ばれた場合
 */
 public void persist(Object entity);

 /**
 * エンティティの状態を現在の永続化コンテキストにマージします。
 * @param entity エンティティ
 * @return 状態が永続化コンテキストにマージされたインスタンス
 * @throws IllegalArgumentExceptionインスタンスがエンティティ
 * ではないか，removed状態のエンティティである場合
 * @throws TransactionRequiredException PersistenceContextType.TRANSACTION
 * を指定したコンテナ管理のエンティティマネージャが，トランザクションが
 * 存在しない時に呼ばれた場合
 */
 public <T> T merge(T entity);

 /**
 * エンティティのインスタンスを削除します。
 * @param entity エンティティ
 * @throws IllegalArgumentExceptionインスタンスがエンティティ
 * ではないか，detached状態のエンティティである場合
 * @throws TransactionRequiredException PersistenceContextType.TRANSACTION
 * を指定したコンテナ管理のエンティティマネージャが，トランザクションが
 * 存在しない時に呼ばれた場合
 */
 public void remove(Object entity);

 /**
 * プライマリキーを検索します。
 * @param entityClass エンティティクラス
 * @param primaryKey プライマリキー
 * @return 検索したエンティティのインスタンス
 * エンティティが存在しない場合はnull
 * @throws IllegalArgumentException entityClass引数がエンティティの型
 * でない場合，またはprimaryKey引数がそのエンティティのプライマリキー
 * として有効な型でない場合
 */
 public <T> T find(Class<T> entityClass, Object primaryKey);

 /**
 * 状態が遅延フェッチされるインスタンスを取得します。
 * リクエストしたエンティティがデータベースに存在しない場合，
 * インスタンスの状態に最初にアクセスしたときに，
 * EntityNotFoundExceptionがスローされます。
 * （getReferenceが呼ばれた時に，JPAプロバイダが
 * EntityNotFoundExceptionをスローすることも許されています）
 * アプリケーションは，エンティティマネージャがオープンしている間に
 * インスタンスにアクセスしない場合，デタッチ時にインスタンスの状態に
 * アクセスできることを期待しないでください。
 * @param entityClass エンティティクラス
 * @param primaryKey プライマリキー
 * @return 検索したエンティティのインスタンス。
 * @throws IllegalArgumentException entityClass引数がエンティティの型
 * でない場合，またはprimaryKey引数がそのエンティティのプライマリキー
 * として有効な型でない場合
 * @throws EntityNotFoundException エンティティの状態に
 * アクセスできない場合
 */
 public <T> T getReference(Class<T> entityClass, Object primaryKey);

 /**
 * 永続化コンテキストの状態をデータベースにフラッシュさせます。
 * @throws TransactionRequiredException トランザクションが存在しない場合
 * @throws PersistenceException フラッシュに失敗した場合
 */
 public void flush();

 /**
 * 永続化コンテキストに含まれるすべてのオブジェクトに適用される
 * フラッシュモードを設定します。
 * @param flushMode フラッシュモード
 */
 public void setFlushMode(FlushModeType flushMode);

 /**
 * 永続化コンテキストに含まれるすべてのオブジェクトに適用される
 * フラッシュモードを取得します。
 * @return flushMode フラッシュモード
 */
 public FlushModeType getFlushMode();

 /**
 * 永続化コンテキストに含まれるエンティティオブジェクトのロックモードを
 * セットします。
 * @param entity エンティティ
 * @param lockMode ロックモード
 * @throws PersistenceException サポートされていないロック呼び出しが
 * 行われた場合
 * @throws IllegalArgumentException インスタンスがエンティティ
 * でない場合，またはデタッチされたエンティティである場合
 * @throws TransactionRequiredException トランザクションが存在しない場合
 */
 public void lock(Object entity, LockModeType lockMode);

 /**
 * インスタンスの状態をデータベースの状態にリフレッシュします。
 * インスタンスの状態が変更されている場合，データベースの状態で
 * 上書きされます。
 * @param entity エンティティ
 * @throws IllegalArgumentException エンティティでないか，
 * managed状態でない場合
 * @throws TransactionRequiredException PersistenceContextType.TRANSACTION
 * が指定された
 * コンテナ管理のエンティティマネージャが，トランザクションが存在しない時に
 * 呼ばれた場合
 * @throws EntityNotFoundException エンティティがすでにデータベースに
 * 存在しない場合
 */
 public void refresh(Object entity);

 /**
 * 永続化コンテキストをクリアし，すべてのmanaged状態のエンティティを
 * デタッチします。
 * エンティティにデータベースにフラッシュされていない変更がある場合，
 * 永続化されません。
 */
 public void clear();

 /**
 * インスタンスが現在の永続化コンテキストに含まれているかをチェックします。
 * @param entity エンティティ
 * @return 含まれている場合true
 * @throws IllegalArgumentException エンティティではない場合
 */
 public boolean contains(Object entity);

 /**
 * JPQL(Java Persistence Query language)の文を実行するための
 * Queryインスタンスを作成します。
 * @param qlString Java Persistence Queryの文
 * @return 新しいQueryのインスタンス
 * @throws IllegalArgumentException クエリ文が有効でない場合
 */
 public Query createQuery(String qlString);

 /**
 * 名前付きクエリ（JPQLまたはネイティブSQL）を実行するための
 * Queryインスタンスを作成します。
 * @param name メタデータで定義されたクエリの名前
 * @return 新しいQueryのインスタンス
 * @throws IllegalArgumentException 指定された名前のクエリが
 * 定義されていない場合
 */
 public Query createNamedQuery(String name);

 /**
 * ネイティブSQL文（update文，delete文）を実行するための
 * Queryインスタンスを作成します。
 * @param sqlString ネイティブSQL文
 * @return 新しいQueryのインスタンス
 */
 public Query createNativeQuery(String sqlString);

 /**
 * ネイティブSQLのクエリを実行するためのQueryインスタンスを作成します。
 * @param sqlString ネイティブSQL文
 * @param resultClass 返り値となるインスタンスのクラス
 * @return 新しいQueryのインスタンス
 */
 public Query createNativeQuery(String sqlString, Class result-
 Class);

 /**
 * ネイティブSQLのクエリを実行するためのQueryインスタンスを作成します。
 * @param sqlString ネイティブSQL文
 * @param resultSetMapping 結果セットマッピングの名前
 * @return 新しいQueryのインスタンス
 */
 public Query createNativeQuery(String sqlString, String result-
 SetMapping);

 /**
 * EntityManagerにJTAトランザクションがアクティブになったことを通知します。
 * このメソッドは，トランザクションのスコープの外で作成された
 * アプリケーション管理のJTAエンティティマネージャを
 * 現在のJTAトランザクションに関連づけるために，
 * アプリケーションによって呼び出されます。
 * @throws TransactionRequiredException トランザクションが存在しない場合
 */
 public void joinTransaction();

 /**
 * 下位にあるプロバイダのオブジェクトが存在する場合は返します。
 * このメソッドの返り値は実装依存ですが，
 * Cosminexus Component Containerでコンテナ管理のエンティティマネージャを
 * 使用する場合は，JPAプロバイダのEntityManagerオブジェクトを返します。
 * @return JPAプロバイダのEntityManagerオブジェクト
 * /
 public Object getDelegate();

 /**
 * アプリケーション管理のEntityManagerをクローズします。
 * closeメソッドが呼び出されたあとは，EntityManagerインスタンスと
 * EntityManagerから取得したQueryオブジェクトの，
 * getTransactionとisOpen（falseを返します）以外のすべてのメソッドは，
 * IllegalStateExceptionをスローします。
 * EntityManagerがアクティブなトランザクションに関連づいている時に
 * このメソッドが呼ばれた場合，トランザクションが決着するまで
 * 永続化コンテキストは存続します。
 * @throws IllegalStateException コンテナ管理のEntityManagerである場合
 */
 public void close();

 /**
 * EntityManagerがオープンされているかどうかを返す。
 * @return EntityManagerがクローズされるまではtrueを返す。
 */
 public boolean isOpen();

 /**
 * リソースレベルのトランザクションオブジェクトを返します。
 * EntityTransactionインスタンスは，複数のトランザクションを，
 * シリアルに開始，コミットするために使用されます。
 * @return EntityTransactionのインスタンス
 * @throws IllegalStateException JTAエンティティマネージャで
 * このメソッドが呼び出された場合
 */
 public EntityTransaction getTransaction();

}

(2)　注意事項

トランザクションスコープの永続化コンテキストを使用している場合，persist，merge，remove，refreshメソッドは，トランザクションコンテキスト内で呼び出す必要があります。トランザクションコンテキストが存在しない場合，javax.persistence.TransactionRequiredExceptionがスローされます。

find，getReferenceメソッドは，トランザクションコンテキスト外で呼び出すこともできます。トランザクションスコープの永続化コンテキストを使用している場合，結果のエンティティはデタッチド状態になります。拡張永続化コンテキストを使用している場合，結果のエンティティはmanaged状態になります。

EntityManagerから取得したQueryとEntityTransactionオブジェクトは，EntityManagerがオープンされている間，使用できます。

createQueryメソッドの引数が有効なJPQL（Java Persistence Query Language）でない場合，IllegalArgumentExceptionがスローされるか，クエリの実行が失敗します。ネイティブクエリが正しくない場合や，結果セットの定義がクエリの結果と互換性がない場合には，クエリが実行される時にPersistenceExceptionがスローされ，クエリの実行が失敗します。PersistenceExceptionは，可能な場合はデータベースの例外をラップしたものになっています。

EntityManagerインタフェースのメソッドでランタイム例外がスローされる場合，トランザクションはロールバックします。

close，isOpen，joinTransaction，getTransactionはアプリケーション管理のEntityManagerを管理するためのメソッドです。

EJB仕様では，Stateless Session Beanで，EntityManagerのメソッドを呼び出せるのは次のメソッドです。

ビジネスインタフェースまたはコンポーネントインタフェースのビジネスメソッド

ビジネスメソッド

インターセプターメソッド

タイムアウトコールバックメソッド

コンストラクタや，DIのセッターメソッド（setSessionContextメソッドを含む），ライフサイクルコールバックメソッド（PostConstructやPreDestroy）では，EntityManagerのメソッドを呼び出せません。許可されていない場所でEntityManagerのメソッドを呼び出した場合，KDJE56538-Eメッセージが出力され，java.lang.IllegalStateExceptionがスローされます。

EJB仕様では，Stateful Session BeanでEntityManagerのメソッドを呼び出せるのは，次のメソッドです。

ライフサイクルコールバックメソッド（PostConstructやPreDestroy）

ビジネスインタフェースまたはコンポーネントインタフェースのビジネスメソッド

ビジネスメソッド

インターセプターメソッド

SessionSynchronizationのafterBeginおよびbeforeCompletionメソッド

コンストラクタや，DIのセッターメソッド，SessionSynchronizationのafterCompletionメソッドでは，EntityManagerのメソッドを呼び出せません。許可されていない場所でEntityManagerのメソッドを呼び出した場合，KDJE56538-Eメッセージが出力され，java.lang.IllegalStateExceptionがスローされます。

なお，アプリケーションサーバでJPAを使用する場合は次の点にも注意してください。

アプリケーションがインジェクト，JNDIでのルックアップ，およびEntityManagerFactoryを使用して取得したEntityManagerは，JPAプロバイダが提供するEntityManagerオブジェクトではなく，アプリケーションサーバが提供するEntityManagerのプロキシクラスになっています。このプロキシクラスのgetDelegate()を使用すると，JPAプロバイダが提供するEntityManagerオブジェクトを取得できます。ただし，コンテナ管理のEntityManagerを使用する場合，EntityManagerのライフサイクルはコンテナが管理しているので，getDelegate()を使用して取得したEntityManagerオブジェクトのclose()をアプリケーションから呼ばないでください。

トランザクションスコープの永続化コンテキストを使用する場合で，トランザクションが存在しないときにEntityManagerのgetDelegate()を呼び出すと，コンテナは返されたEntityManagerをクローズできません。この場合には，アプリケーションでEntityManager.close()を呼び出す必要があります。

5.10.2　javax.persistence.EntityManagerFactoryインタフェース

ここでは，javax.persistence.EntityManagerFactoryインタフェースについてインタフェース定義と注事事項を説明します。

＜この項の構成＞

(1)　インタフェース定義

(2)　注意事項

(1)　インタフェース定義

package javax.persistence;

/**
* EntityManagerFactoryインタフェースは，
* アプリケーションがアプリケーション管理のEntityManagerを取得するために
* 使用します。
* アプリケーションがEntityManagerFactoryの使用を終了する時には，
* アプリケーションはEntityManagerFactoryをクローズする必要があります。
* EntityManagerFactoryがクローズされたあとは，
* EntityManagerFactoryから作成したすべてのEntityManagerはクローズされた
* ものとして扱われます。
*/
public interface EntityManagerFactory {
 /**
 * 新しいEntityManagerを作成します。
 * このメソッドは，呼び出されるたびに新しいEntityManagerのインスタンスを
 * 返します。
 * このメソッドが返すEntityManagerのisOpenメソッドはtrueを返します。
 * @return 新しいEntityManager
 */
 public EntityManager createEntityManager();

 /**
 * 指定したプロパティのマップを使用して新しいEntityManagerを作成します。
 * このメソッドは，呼び出されるたびに新しいEntityManagerのインスタンスを
 * 返します。
 * このメソッドが返すEntityManagerのisOpenメソッドはtrueを返します。
 * @param map EntityManagerのプロパティを格納したMap
 * @return 新しいEntityManager
 */
 public EntityManager createEntityManager(Map map);

 /**
 * ファクトリをクローズし，ファクトリが保持しているすべてのリソースを
 * 解放します。
 * ファクトリがクローズされたあとは，isOpen以外のメソッドを呼び出すと，
 * IllegalStateExceptionがスローされます。isOpenメソッドは，falseを
 * 返します。
 * EntityManagerFactoryがクローズされると，ファクトリから作成した
 * すべてのEntityManagerも，クローズされたものとして扱われます。
 */
 public void close();

 /**
 * ファクトリがオープンしているかどうかを返します。
 * @return ファクトリがクローズされるまではtrue
 */
 public boolean isOpen();

}

(2)　注意事項

createEntityManagerに渡すマップには，JPAプロバイダのベンダ特有プロパティを含めることができます。JPAプロバイダが認識できないプロパティは，単に無視されます。

EJB仕様では，Stateless Session BeanでEntityManagerFactoryのメソッドを呼び出せるのは，次のメソッドです。

ライフサイクルコールバックメソッド（PostConstructやPreDestroy）

ビジネスインタフェースまたはコンポーネントインタフェースのビジネスメソッド

ビジネスメソッド

インターセプターメソッド

タイムアウトコールバックメソッドです。

コンストラクタや，DIのセッターメソッド（setSessionContextメソッドを含む）では，EntityManagerFactoryのメソッドを呼び出せません。

EJB仕様では，Stateful Session BeanでEntityManagerFactoryのメソッドを呼び出せるのは，次のメソッドです。

ライフサイクルコールバックメソッド（PostConstructやPreDestroy）

ビジネスインタフェースまたはコンポーネントインタフェースのビジネスメソッド

ビジネスメソッド

インターセプターメソッド

SessionSynchronizationのafterBeginおよびbeforeCompletionメソッドです。

コンストラクタや，Dependency Injectionのセッターメソッド，SessionSynchronizationのafterCompletionメソッドでは，EntityManagerFactoryのメソッドを呼び出せません。

5.11　アプリケーション設定時の注意事項

ここでは，アプリケーションサーバ上で動作させるJPAを利用したアプリケーションを設定するときの注意事項を説明します。

＜この節の構成＞

5.11.1　エンティティクラス配置時の注意

5.11.2　永続化ユニット名の参照スコープ

5.11.3　アプリケーションのデプロイ時にチェックされる項目

5.11.4　アプリケーションサーバでJPAを使用するときの注意事項

5.11.5　CosminexusのJPA機能を使用しないときの注意事項

5.11.1　エンティティクラス配置時の注意

アプリケーションサーバでは，エンティティクラスはEAR，EJB-JAR，またはWARの中のJPA仕様で定められた場所にパッケージングしてください。なお，エンティティクラスは，システムクラスパスに追加しないでください。

エンティティクラスは，アプリケーションのクラスローダまたはWebアプリケーションのクラスローダでローディングされるときに，Lazyフェッチなどを実現するために，JPAプロバイダによってクラスのバイトコード変換が行われることがあります。エンティティクラスがシステムクラスパスに含まれていると，エンティティクラスがシステムクラスローダでローディングされてしまうため，バイトコード変換が動作しません。このため，JPAプロバイダが正しく動作できなくなります。

5.11.2　永続化ユニット名の参照スコープ

アプリケーションに含まれるEJBやサーブレットなどのコンポーネントは，@PersistenceUnitや@PersistenceContextのunitName属性，DDに定義した<persistence-context-ref>タグ下または<persistence-unit-ref>タグ下の<persistence-unit-name>タグで永続化ユニット名を指定して，使用する永続化ユニットを参照します。ただし，各コンポーネントから参照できる永続化ユニットのスコープは，次のとおりになります。

EJB-JARまたはWARの中に定義した永続化ユニットは，EJB-JARまたはWARに含まれているコンポーネントから参照できます。

EARの中に定義した永続化ユニットは，EARに含まれるすべてのコンポーネントから参照できます。

EARで定義した永続化ユニットの名前と，EJB-JARまたはWARで定義した永続化ユニットの名前が重複している場合，EJB-JARまたはWAR内のコンポーネントからは，より狭い範囲で定義された永続化ユニットが優先されます。例えば，EARとWAR内に同じ名前の永続化ユニットが定義されている場合，WARに含まれているコンポーネントからは，WARで定義した永続化ユニットが優先して見えます。EARの中にある永続化ユニットは見えません。

＜この項の構成＞

(1)　永続化ユニット名を省略した場合に使用される永続化ユニット

(2)　「#」文法を使用したEARレベル永続化ユニットの明示的な参照

(1)　永続化ユニット名を省略した場合に使用される永続化ユニット

アプリケーションサーバでJPAを使用する場合，コンポーネントが参照する永続化ユニット名を省略すると，次に示すルールで使用する永続化ユニットが決定されます。

コンポーネントが含まれるEJB-JARまたはWARの中に，永続化ユニットが一つだけ定義されている場合は，その永続化ユニットが使用されます。

コンポーネントが含まれるEJB-JARまたはWARの中に，永続化ユニットが一つも定義されていなく，EAR内に永続化ユニットが一つだけ定義されている場合は，EAR内の永続化ユニットが使用されます。

なお，次の条件に該当する場合は，使用する永続化ユニットを一つに特定できないため，永続化ユニット名は省略できません。

コンポーネントが含まれるEJB-JARまたはWARの中に，永続化ユニットが二つ以上定義されている場合

コンポーネントが含まれるEJB-JARまたはWARの中に，永続化ユニットが一つも定義されていなく，EAR内に永続化ユニットが二つ以上定義されている場合

(2)　「#」文法を使用したEARレベル永続化ユニットの明示的な参照

EARで定義した永続化ユニットの名前と，EJB-JARまたはWARで定義した永続化ユニットの名前が重複している場合，EJB-JARまたはWAR内のコンポーネントからは，より狭い範囲で定義された永続化ユニットが優先して見えます。ただし，永続化ユニットの参照名に「#」文法を使用することで，EARに定義した永続化ユニットを明示的に参照することもできます。「#」文法を使用する場合，永続化ユニット名は次のとおり指定します。

「コンポーネントが含まれるEJB-JARやWARから永続化ユニットルートへの相対パス」#「永続化ユニット名」

例えば，EARのejbs/myEjbs.jarに含まれたEJBから，EARのlib/persistenceUnitRoot.jarに含まれた永続化ユニット「myPersistenceUnit」を参照する場合，参照する永続化ユニット名は「../lib/persistenceUnitRoot.jar#myPersistenceUnit」になります。

5.11.3　アプリケーションのデプロイ時にチェックされる項目

JPAを利用したアプリケーションをJ2EEサーバにデプロイするとき，次の項目がチェックされます。

永続化ユニット定義のチェック

EntityManagerやEntityManagerFactoryのリファレンスのチェック

それぞれについて説明します。

＜この項の構成＞

(1)　永続化ユニット定義のチェック

(2)　EntityManagerやEntityManagerFactoryのリファレンスのチェック

(1)　永続化ユニット定義のチェック

永続化ユニット定義でチェックされる内容を説明します。

(a)　persistence.xmlのバリデーション

アプリケーションに含まれるpersistence.xmlがpersistence_1_0.xsdスキーマに従っているかを検証します。検証でエラーが発見された場合は，エラーメッセージKDJE56526-Eを出力してデプロイを中止します。

(b)　永続化ユニット名のチェック

永続化ユニット名が空文字でないことをチェックします。永続化ユニット名が空文字である場合，エラーメッセージKDJE56505-Eを出力してデプロイを中止します。

また，アプリケーションのEARや，一つのEJB-JARまたはWARの中に，重複した名前の永続化ユニットが定義されていないかをチェックします。重複した名前の永続化ユニットが定義されている場合には，警告メッセージKDJE56500-Wを出力し，デプロイを継続します。なお，この場合は実際にデプロイされる永続化ユニットは一つだけです。

(c)　永続化ユニットが参照するデータソースの存在チェック

永続化ユニットのトランザクションタイプによってチェックされる内容が異なります。

永続化ユニットのトランザクションタイプがJTAの場合
チェックされる内容とチェック時にエラーが発生したときの動作を次の表に示します。

表5-10　チェックされる内容とチェック時にエラーが発生したときの動作（トランザクションタイプがJTAの場合）

チェックされる内容 | チェック時にエラーが発生したときの動作
永続化ユニットで使用するJTAデータソース（persistence.xmlの<jta-data-source>タグに指定されたもの，またはシステムプロパティで指定したデフォルト値）が指定されていること。 | エラーメッセージKDJE56527-Eを出力して，デプロイを中止します。
JTAデータソースを提供するリソースアダプタが存在すること。 | エラーメッセージKDJE56529-Eを出力して，デプロイを中止します。
JTAデータソースを提供するリソースアダプタが開始されていること。
リソースアダプタのトランザクションサポートレベルが，LocalTransactionまたはXATrasnactionになっていること。 | エラーメッセージKDJE56531-Eを出力して，デプロイを中止します。
リソースアダプタのコネクションファクトリインタフェースが「javax.sql.DataSource」であること。 | エラーメッセージKDJE56533-Eを出力して，デプロイを中止します。

永続化ユニットのトランザクションタイプがRESOURCE_LOCALの場合
チェックされる内容とチェック時にエラーが発生したときの動作を次の表に示します。

表5-11　チェックされる内容とチェック時にエラーが発生したときの動作（トランザクションタイプがRESOURCE_LOCALの場合）

チェックされる内容 | チェック時にエラーが発生したときの動作
永続化ユニットで使用する非JTAデータソース（persistence.xmlの<non-jta-data-source>タグに指定されたもの，またはシステムプロパティで指定したデフォルト値）が指定されていること。 | エラーメッセージKDJE56528-Eを出力して，デプロイを中止します。
非JTAデータソースを提供するリソースアダプタが存在すること。 | エラーメッセージKDJE56530-Eを出力して，デプロイを中止します。
非JTAデータソースを提供するリソースアダプタが開始されていること。
リソースアダプタのトランザクションサポートレベルが，NoTransactionになっていること。 | エラーメッセージKDJE56532-Eを出力して，デプロイを中止します。
リソースアダプタのコネクションファクトリインタフェースが「javax.sql.DataSource」であること。 | エラーメッセージKDJE56533-Eを出力して，デプロイを中止します。

(d)　永続化ユニットに指定されたプロバイダクラスのチェック

永続化ユニットが使用するJPAプロバイダのクラス（persistence.xmlの<provider>タグに指定されたクラス）を，アプリケーションからロードできることをチェックします。ロードに失敗した場合には，エラーメッセージKDJE56503-Eを出力して，デプロイを中止します。

(e)　永続化ユニットが参照するJARファイルの存在チェック

永続化ユニットが参照するJARファイル（persistence.xmlの<jar-file>タグに指定されたJARファイル）が存在するかをチェックします。JARファイルが存在しない場合には，エラーメッセージKDJE56506-Eを出力して，デプロイを中止します。

(f)　JPAプロバイダによる永続化ユニットの定義内容のチェック

JPAコンテナが解析したpersistence.xmlの内容からJPAプロバイダが永続化ユニットを生成します。永続化ユニットの定義に問題があり，JPAプロバイダがエラーを返した場合，エラーメッセージ（KDJE56539-E）を表示してデプロイメントを中止します。

(2)　EntityManagerやEntityManagerFactoryのリファレンスのチェック

EntityManagerやEntityManagerFactoryのリファレンスでチェックされる内容を説明します。

(a)　永続化ユニットの存在チェック

EJBやWebコンポーネントで定義したEntityManagerやEntityManagerFactoryのリファレンスで，指定した永続化ユニット名が実際に参照できる永続化ユニット名であるかをチェックします。また，永続化ユニット名が省略されている場合は，使用する永続化ユニットを特定できるかをチェックします。このチェックでエラーが発見された場合には，エラーメッセージKDJE56501-Eを出力して，デプロイを中止します。

(b)　コンテナ管理のEntityManagerを使用する場合のトランザクションタイプのチェック

コンテナ管理のEntityManagerを使用する場合は，永続化ユニットのトランザクションタイプがJTAになっていることをチェックします。このチェックでエラーが発生した場合は，エラーメッセージKDJE56534-Eを出力して，デプロイを中止します。

(c)　拡張永続化コンテキストがStateful Session Bean以外から使用されていないことをチェック

EntityManagerのリファレンスでは，永続化コンテキストのタイプにEXTENDEDが指定されている場合，そのリファレンスが定義されている場所がStateful Session Beanであることをチェックします。Stateful Session Bean以外の場所で定義されている場合には，エラーメッセージKDJE56535-Eを出力して，デプロイを中止します。

5.11.4　アプリケーションサーバでJPAを使用するときの注意事項

アプリケーションが取得できるEntityManagerの型は，JPAプロバイダのEntityManagerオブジェクトではなく，アプリケーションサーバが提供するEntityManagerのプロキシクラスです。

EntityManagerオブジェクトは，インジェクション，JNDIルックアップ，またはEntityManagerFactoryで取得できます。

なお，インジェクションを使用してEntityManagerを取得する場合には，EntityManagerをインジェクトするフィールドまたはメソッド引数の型は，javax.persistence.EntityManagerにしてください。

また，インジェクション，JNDIルックアップ，またはEntityManagerFactoryで取得したEntityManagerは，JPAプロバイダのEntityManagerの実装クラスにキャストできません。

JPAプロバイダのEntityManagerオブジェクトを取得する必要がある場合は，インジェクション，JNDIルックアップ，またはEntityManagerFactoryで取得したEntityManagerプロキシオブジェクトのgetDelegateメソッドを使用してください。

5.11.5　CosminexusのJPA機能を使用しないときの注意事項

CosminexusのJPA機能では，アプリケーションにpersistence.xmlが含まれている場合，デフォルトの設定では，CosminexusのJPA機能を使用するかどうかに関係なくpersistence.xmlの読み込みが実行されます。アプリケーションサーバでpersistence.xmlの解釈ができない場合，アプリケーションの開始に失敗します。

この状況を避けるため，アプリケーションにpersistence.xmlが含まれ，かつCosminexusのJPA機能を使用しない場合には，J2EEサーバのejbserver.jpa.disableプロパティに「true」を設定してください。

これによって，アプリケーションサーバではpersistence.xmlの読み込みを実行しなくなります。

6.　Cosminexus JPAプロバイダ

この章では，Cosminexus JPAプロバイダの機能概要，アプリケーションの実装方法，および実行環境の設定について説明します。

＜この章の構成＞

6.1　この章の構成

6.2　Cosminexus JPAプロバイダとは

6.3　エンティティを使用したデータベースの更新

6.4　EntityManagerによるエンティティの操作

6.5　データベースとJavaオブジェクトとのマッピング情報の定義

6.6　エンティティのリレーションシップ

6.7　エンティティオブジェクトのキャッシュ機能

6.8　プライマリキー値の自動採番

6.9　クエリ言語によるデータベース操作

6.10　楽観的ロック

6.11　JPQLでの悲観的ロック

6.12　エンティティクラスの作成

6.13　エンティティクラスの継承方法

6.14　EntityManagerおよびEntityManagerFactoryの使用方法

6.15　コールバックメソッドの指定方法

6.16　クエリ言語を利用したデータベースの参照および更新方法

6.17　JPQLの記述方法

6.18　persistence.xmlの定義

6.19　実行環境での設定

6.1　この章の構成

Cosminexus JPAプロバイダとは，JPA仕様書に定められたAPIや内部処理を実装し，ライブラリ形式でユーザに提供するアプリケーションサーバが提供するJPAプロバイダです。

この章では，Cosminexus JPAプロバイダの機能について説明します。この章の構成を次の表に示します。

表6-1　この章の構成（Cosminexus JPAプロバイダの機能）

分類 | タイトル | 参照先
解説 | Cosminexus JPAプロバイダとは | 6.2
エンティティを使用したデータベースの更新 | 6.3
EntityManagerによるエンティティの操作 | 6.4
データベースとJavaオブジェクトとのマッピング情報の定義 | 6.5
エンティティのリレーションシップ | 6.6
エンティティオブジェクトのキャッシュ機能 | 6.7
プライマリキー値の自動採番 | 6.8
クエリ言語によるデータベース操作 | 6.9
楽観的ロック | 6.10
JPQLでの悲観的ロック | 6.11
実装 | エンティティクラスの作成 | 6.12
エンティティクラスの継承方法 | 6.13
EntityManagerおよびEntityManagerFactoryの使用方法 | 6.14
コールバックメソッドの指定方法 | 6.15
クエリ言語を利用したデータベースの参照および更新方法 | 6.16
JPQLの記述方法 | 6.17
persistence.xmlの定義 | 6.18
設定 | 実行環境での設定 | 6.19

注　「運用」について，この機能固有の説明はありません。

6.2　Cosminexus JPAプロバイダとは

Cosminexus JPAプロバイダとは，アプリケーションサーバが提供するJPAプロバイダです。Cosminexus JPAプロバイダの位置づけを次の図に示します。

図6-1　Cosminexus JPAプロバイダの位置づけ

Cosminexus JPAプロバイダはJ2EEサーバの一機能です。JTAおよびJNDIを使用して，データベースを操作します。ここでは，Cosminexus JPAプロバイダの機能概要について説明します。

＜この節の構成＞

6.2.1　Cosminexus JPAプロバイダでの処理

6.2.2　Cosminexus JPAプロバイダが提供する機能

6.2.3　Cosminexus JPAプロバイダを使用するための前提条件

6.2.4　DB Connectorのコネクション数の見積もり

6.2.1　Cosminexus JPAプロバイダでの処理

Cosminexus JPAプロバイダでは，次の機能を提供しています。

エンティティオブジェクトとデータベースのマッピング

エンティティオブジェクトの管理

JPQLによるデータの操作

JDBCを通じてのデータベースへのアクセス

JPAを使用するには，ユーザが作成したアプリケーションでCosminexus JPAプロバイダが提供するインタフェースを操作します。Cosminexus JPAプロバイダで実行する処理を次の図に示します。

図6-2　Cosminexus JPAプロバイダで実行される処理

図について説明します。

persistence.xmlに定義されている永続化ユニットの情報から，Cosminexus JPAプロバイダはEntityManagerFactoryを生成します。
永続化ユニットとは，マッピング対象となるクラス，O/Rマッピングの情報，データソースなどを集めた論理的なグループです。永続化ユニットの詳細については，「5.4.4　永続化ユニットとは」を参照してください。

生成されたEntityManagerFactoryからEntityManagerを生成します。

ユーザアプリケーションから，EntityManager，クエリ，またはトランザクションを操作します。

EntityManager，クエリ，トランザクションから永続化コンテキストを通して，エンティティオブジェクトを操作します。

エンティティオブジェクトの変更をJDBCドライバを介してデータベースに反映します。

なお，EntityManagerには，次の2種類があります。

コンテナ管理EntityManager
J2EEコンテナによって管理されるEntityManagerです。

アプリケーション管理EntityManager
アプリケーションによって管理されるEntityManagerです。

EntityManagerの種類の詳細については，「5.5.1　EntityManagerと永続化コンテキスト」を参照してください。

また，トランザクションではトランザクションのコミットやロールバックなどを管理します。Cosminexus JPAプロバイダでは，トランザクションとしてリソースローカルトランザクションを使用できます。JTAトランザクションと連携する場合，J2EEコンテナが提供する機能を使用します。

6.2.2　Cosminexus JPAプロバイダが提供する機能

Cosminexus JPAプロバイダでは次に示す機能を提供しています。

表6-2　Cosminexus JPAプロバイダが提供する機能

機能
機能の概要
標準/拡張※
参照先

エンティティを使用したデータベースの更新
ユーザのアプリケーションから生成したエンティティによって，データベースのデータを更新します。
標準
6.3
6.4

データベースとJavaオブジェクトとのマッピング情報の定義
Javaオブジェクトとデータベースとのマッピング情報は，アノテーションまたはO/Rマッピングファイルで定義できます。
標準
6.5

エンティティのリレーションシップの設定
データベースのテーブル間の関連をエンティティで設定します。
標準
6.6

エンティティオブジェクトのキャッシュ
EntityManagerのエンティティオブジェクトの内容をメモリに保持する機能です。同じ内容のエンティティオブジェクトが呼ばれた場合，メモリのエンティティオブジェクトを使用します。
拡張
6.7

プライマリキーの自動採番
エンティティオブジェクトを使用してデータベースにデータを挿入するときに，Cosminexus JPAプロバイダはプライマリキーを自動的に格納します。ユーザがプライマリキーを指定しなくても，一意の値が格納されます。
標準
6.8

クエリ言語によるデータベース操作
クエリ言語を使用してデータベースを操作できます。Cosminexus JPAプロバイダでは，クエリ言語としてJPQLまたはSQLを使用できます。
標準
6.9

楽観的ロック
データベースの排他方法の一つです。データベースのデータがほかのトランザクションから更新されていないかを確認してからデータを更新します。楽観的ロックではデータをロックしないため，デッドロックは発生しません。
標準
6.10

JPQLでの悲観的ロック
データベースの排他方法の一つです。ほかのトランザクションから更新されないように，レコードを占有ロックします。悲観的ロックはJPQLを使用した場合だけ実行されます。
拡張
6.11

注※　JPA1.0仕様に基づいた機能かどうかを示します。

標準：JPA1.0仕様に基づいた機能であることを示します。

拡張：Cosminexus JPAプロバイダ独自の機能であることを示します。

これらの機能の詳細については，表中の「参照先」に示す節を参照してください。

また，Cosminexus JPAプロバイダでは，PRFトレースを取得できます。PRFトレースの取得ポイントについては，マニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「7.　性能解析トレースのトレース取得ポイントとPRFトレース取得レベル」を参照してください。

6.2.3　Cosminexus JPAプロバイダを使用するための前提条件

ここでは，Cosminexus JPAプロバイダを使用するための前提条件について説明します。

＜この項の構成＞

(1)　使用できるコンポーネント

(2)　接続できるデータベース

(3)　使用できるDB Connector

(4)　使用できない環境

(5)　メソッドキャンセル機能の使用について

(6)　アノテーションの参照抑止機能の使用について

(1)　使用できるコンポーネント

Cosminexus JPAプロバイダを利用するコンポーネントは，EJBの場合はEJB 3.0以降，Webコンポーネントの場合はServlet 2.5以降となります。使用できるコンポーネントの詳細については，「5.3.2　使用できるコンポーネント」を参照してください。

(2)　接続できるデータベース

Cosminexus JPAプロバイダを使用する場合，次に示すデータベースに接続できます。

Oracle10g

Oracle11g

HiRDB Version 8

HiRDB Version 9

(3)　使用できるDB Connector

Cosminexus JPAプロバイダは，DB Connectorを使用してデータベースを更新します。Cosminexus JPAプロバイダでは次の表に示すDB Connectorを使用できます。

表6-3　Cosminexus JPAプロバイダで使用できるDB Connector

使用するデータベース
トランザクションタイプ
使用できるDB Connector

Oracle
LocalTransaction
NoTransaction
DBConnector_Oracle_CP.rar

XATransaction
DBConnector_Oracle_XA.rar

Oracle RAC
LocalTransaction
NoTransaction
DBConnector_Oracle_CP.rar
DBConnector_CP_ClusterPool_Root.rar
DBConnector_Oracle_CP_ClusterPool_Member.rar

HiRDB
LocalTransaction
NoTransaction
DBConnector_HiRDB_Type4_CP.rar

XATransaction
DBConnector_HiRDB_Type4_XA.rar

(4)　使用できない環境

次の環境ではCosminexus JPAプロバイダを使用できません。

バッチアプリケーションの実行環境

EJBクライアントアプリケーションの実行環境

(5)　メソッドキャンセル機能の使用について

Cosminexus JPAプロバイダでは，OneToOneおよびManyToOneのLAZYフェッチの場合，アクセサメソッドに独自のバイナリコードを埋め込みます。これによって，アクセサメソッドがメソッドキャンセルの対象になります。このため，OneToOneリレーションシップ，またはManyToOneリレーションシップでLAZYフェッチが指定されている場合は，エンティティクラス，埋め込み可能クラス，およびマップドスーパークラスを保護区に登録する必要があります。

なお，保護区に登録しない場合は，埋め込んだバイナリコード上でメソッドキャンセルが起こるおそれがあります。保護区に登録しない場合の動作は保証しません。

保護区に登録されている場合でも，登録されていない場合でも，メソッドタイムアウトで下記のようなスタックトレースが出力されます。ただし，保護区に登録しているとメソッドキャンセルは発生しません。

次に示す例では，ユーザが呼び出したEntityClass1.getMappingClass2メソッドの延長で，埋め込んだEntityClass1._toplink_getmappingClass2が呼ばれています。そこでメソッドタイムアウトが発生していますが，メソッドキャンセルは発生しません。

message-id       message(LANG=ja)
KDJE52703-W      A timeout occurred while the user program was executing. (threadID = 23794987, rootAPInfo = 10.209.11.124/5964/0x4828eb62000128e0, application = JPA_JavaEE_TP, bean = TestBean, method = doTest)
   jpa.test.annotation.onetoone.entity.EntityClass1._toplink_getmappingClass2(EntityClass1.java)
                      locals:
                        (jpa.test.annotation.onetoone.entity.EntityClass1) this = <0x11e35878> (jpa.test.annotation.onetoone.entity.EntityClass1)
                       at jpa.test.annotation.onetoone.entity.EntityClass1.getMappingClass2(EntityClass1.java:34)
                      locals:
                        (jpa.test.annotation.onetoone.entity.EntityClass1) this = <0x11e35878> (jpa.test.annotation.onetoone.entity.EntityClass1)

保護区への登録については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「2.6　criticalList.cfg（保護区リストファイル）」を参照してください。

(6)　アノテーションの参照抑止機能の使用について

Cosminexus JPAプロバイダを使用する場合，アノテーションの参照抑止機能は使用できません。アノテーションの参照抑止機能が有効になっていると，永続化コンテキストおよび永続化ユニットの参照を定義できません。

6.2.4　DB Connectorのコネクション数の見積もり

Cosminexus JPAプロバイダを使用する場合に必要となるDB Connectorのリソースの見積もりについて説明します。

Cosminexus JPAプロバイダでは，DB Connectorのコネクションを取得します。Cosminexus JPAプロバイダが使用するコネクション数の見積もり式を次に示します。

コネクション数の見積もり式

Cosminexus JPAプロバイダのアプリケーションで利用されるコネクション数

　　＝JPA機能を利用したアプリケーションの同時実行数※

注※　JPA機能を利用したアプリケーションで，複数の永続化ユニットのEntityManagerを利用する場合や，ビジネスメソッドの呼び出しでEntityManagerが利用するトランザクションが異なる場合，EntityManagerごとにそれぞれコネクションが必要となります。

注意

ユーザがJPA機能とは別にコネクションを取得する場合，コネクションシェアリング機能を利用することでコネクション数を削減できます。コネクションシェアリングの詳細については，「3.14.3　コネクションシェアリング・アソシエーション」を参照してください。

6.3　エンティティを使用したデータベースの更新

Cosminexus JPAプロバイダでは，エンティティを使用したデータベースの更新ができます。

JPAを使用するには，ユーザはデータベースのテーブルをJavaのオブジェクトとして扱うためのエンティティクラスを作成する必要があります。エンティティクラスを使用すると，Cosminexus JPAプロバイダを通してデータベースのデータを操作します。このとき，Cosminexus JPAプロバイダが提供するEntityManagerインタフェースを介して，データベースを操作します。

エンティティクラスを使用したデータベースの操作は次のとおりです。

エンティティクラスのインスタンス（エンティティオブジェクト）を生成します。

EntityManagerインタフェースの引数に，エンティティオブジェクトを渡し，データベースを操作します。
この操作をするためには，エンティティクラスを作成する必要があります。

EntityManagerとはエンティティを操作して，状態を制御するためのオブジェクトです。エンティティの操作には，persist操作，remove操作，merge操作，flush操作，およびrefresh操作があります。これらの操作の詳細については，「6.4.1　エンティティの状態遷移」を参照してください。

6.4　EntityManagerによるエンティティの操作

エンティティの状態は，Cosminexus JPAプロバイダで提供するEntityManagerで制御されます。ここでは，EntityManagerでのエンティティの操作について説明します。

＜この節の構成＞

6.4.1　エンティティの状態遷移

6.4.2　エンティティに対するpersist操作

6.4.3　エンティティに対するremove操作

6.4.4　データベースからのエンティティの取得

6.4.5　データベースとの同期

6.4.6　永続化コンテキストからのエンティティの切り離しとmerge操作

6.4.7　managed状態のエンティティ

6.4.1　エンティティの状態遷移

エンティティには状態があります。エンティティに対して操作するとエンティティの状態は遷移します。ここでは，エンティティの状態の種類，エンティティに対して実行する操作，およびエンティティの操作と状態遷移について説明します。

＜この項の構成＞

(1)　エンティティの状態の種類

(2)　エンティティに対する操作

(3)　エンティティに対する操作と状態遷移

(4)　エンティティに対する操作の伝播

(1)　エンティティの状態の種類

エンティティの状態には，new，managed，detached，removedの4種類があります。EntityManagerのメソッドを利用してエンティティを操作することで，エンティティの状態が変更されます。

エンティティのそれぞれの状態について次の表に示します。

表6-4　エンティティの状態

エンティティインスタンスの状態
説明

new
新しく生成された状態のエンティティです。
新しく生成されたエンティティインスタンスは，永続化アイデンティティを持ちません。このため，永続化コンテキストに関連づいていません。

managed
永続化コンテキストに関連づけられた永続化アイデンティティを持ち，永続化コンテキストで管理されている状態です。

detached
永続化コンテキストに関連づけられていない永続化アイデンティティを持つ状態です。

removed
永続化アイデンティティを持ち，永続化コンテキストに関連づけられている状態です。また，エンティティインスタンスがデータベースから削除されることが予定されている状態でもあります。

(2)　エンティティに対する操作

ユーザがデータベースのレコードを検索すると，Cosminexus JPAプロバイダは取得したデータをエンティティのフィールドに保持します。また，ユーザがデータベースの内容を更新する場合は，永続化コンテキストに登録されているエンティティの状態を変更して，トランザクションをコミットすることでデータベースにエンティティの状態を反映します。このように，エンティティに対して操作することで，データベースの情報を更新します。

エンティティに対する操作の種類を次の表に示します。

表6-5　エンティティに対する操作の種類

操作 | 説明
flush | エンティティオブジェクトの内容をデータベースに反映します。
merge | EntityManagerの管理対象外となっているエンティティオブジェクトをEntityManagerの管理対象とします。
persist | エンティティオブジェクトを管理して，永続化します。
refresh | エンティティオブジェクトにデータベースの内容を反映します。
remove | エンティティオブジェクトを削除予定状態にします。

(3)　エンティティに対する操作と状態遷移

エンティティインスタンスに対する操作と状態遷移について次の図で説明します。

図6-3　エンティティインスタンスに対する操作と状態遷移

エンティティに対する操作と状態遷移について次の表にまとめます。

表6-6　エンティティの状態遷移

操作
状態

new
managed
detached
removed

persist
managed※1
managed
managed※1
managed

remove
new
removed
例外※2，※3
Removed

merge

コピー元
new

コピー先
managed

コピー元
managed

コピー先
managed

コピー元
detached

コピー先
managed

例外※3，※4

refresh
例外※2，※4
managed※5
例外※2，※4
例外※2，※4

commit
－
※6
－
detached

rollback
－
detached
－
detached

flush
－
managed
－
detached

clear
－
detached
－
detached

（凡例）－：該当しない

注※1　persist操作で例外が発生した場合，状態は遷移しないで元の状態になります。

注※2　発生する例外はIllegalArgumentExceptionです。

注※3　データベース上に対応する行が存在しない場合，操作は無視されます。

注※4　例外時には状態は遷移しないで，元のままとなります。

注※5　データベース上に対応する行が存在しない場合，EntityNotFoundExceptionが発生します。

注※6　トランザクションスコープの永続化コンテキストの場合はdetachedになります。拡張された永続化コンテキストの場合はmanagedになります。

また，persist，remove，merge，refreshをトランザクション外で実行した場合の動作は，永続化コンテキストの種類によって異なります。

トランザクションスコープの永続化コンテキストの場合
TransactionRequiredExceptionとなります。

拡張された永続化コンテキストの場合
状態が遷移して，次のトランザクション決着のタイミングでデータベースに状態が反映されます。

(4)　エンティティに対する操作の伝播

エンティティがリレーションシップを持つ場合に，リレーションシップを表すアノテーションのcascade属性を指定すると，エンティティに対する操作が関連するエンティティに対して伝播されます。cascade属性には，次の表に示す値を指定できます。

表6-7　cascade属性の種類

cascade属性の種類 | 説明
CascadeType.ALL | persist，remove，merge，refreshの操作が関連先に伝播されます。
CascadeType.PERSIST | persist操作が関連先に伝播されます。
CascadeType.REMOVE | remove操作が関連先に伝播されます。
CascadeType.MERGE | merge操作が関連先に伝播されます。
CascadeType.REFRESH | refresh操作が関連先に伝播されます。

6.4.2　エンティティに対するpersist操作

エンティティに対するpersist操作を実行するには，EntityManagerのpersistメソッドを呼び出します。EntityManagerのpersistメソッドを呼び出したり，persist処理がカスケードされたりすると，エンティティはデータベースへの永続化や永続化コンテキストでの管理対象になります。

次の表に，persist操作後のエンティティの状態をエンティティの状態ごとに示します。

表6-8　Persist操作でのエンティティの状態

エンティティの状態 | persist操作後のエンティティの状態
new※ | managedに遷移します。managedに遷移したエンティティはトランザクションのコミット時またはコミット前にデータベースに追加されます。または，flush操作の実行の結果としてデータベースに追加されます。
managed | persist操作は無視されます。ただし，エンティティからほかのエンティティへのリレーションシップのcascade属性にPERSISTまたはALLが指定されていると，このエンティティが参照するエンティティにpersist操作が伝播されます。
detached※ | データベースにエンティティと対応する行が存在しない場合は，managedに遷移します。対応する行が存在する場合，EntityExistsExceptionが発生します。
removed | managedに遷移します。

注※　Cosminexus JPAプロバイダの場合，エンティティの状態がnewまたはdetachedの場合，データベース上にエンティティに対応するデータが存在するかどうかでエンティティの状態遷移の結果が異なります。Cosminexus JPAプロバイダの場合，次のことに注意してください。

データベースに永続化されていないエンティティを引数に指定した場合は，managedに遷移します。

データベースに引数で渡されたエンティティと重複する行が存在し，そのエンティティが永続化コンテキストで管理されている場合，persist処理時にEntityExistsExceptionが発生します。

データベースに引数で渡されたエンティティと重複する行が存在するが，永続化コンテキストでエンティティが管理されていない場合，flushやコミット時にEntityExistsExceptionまたはほかのPersistenceExceptionが発生します。

注意

エンティティをデータベースに永続化したり，データベースからエンティティの情報を読み込んだりするタイミングで，エンティティは永続化コンテキストに登録されます。エンティティをmanagedに遷移したあとに，永続化処理をロールバックした場合は，エンティティは永続化コンテキストで管理されていないので注意してください。

6.4.3　エンティティに対するremove操作

エンティティに対するremove操作を実行するには，EntityManagerのremoveメソッドを呼び出します。EntityManagerのremoveメソッドを呼び出したり，remove処理がカスケードされたりすると，エンティティはremoved状態になります。removed状態のエンティティはトランザクションのコミット処理でデータベースから削除されます。

次の表に，remove操作後のエンティティの状態をエンティティの状態ごとに示します。

表6-9　remove操作でのエンティティの状態

エンティティの状態
状態遷移の結果

new
remove操作は無視されます。ただし，エンティティからほかのエンティティへのリレーションシップのcascade属性にREMOVEまたはALLが指定されていると，このエンティティが参照するエンティティにremove操作が伝播されます。

managed
removedに遷移します。エンティティからほかのエンティティへのリレーションシップのcascade属性にREMOVEまたはALLが指定されていると，このエンティティが参照するエンティティにremove操作が伝播されます。

detached
次のように遷移します。

引数で渡されたdetached状態のエンティティに対応する行がデータベースに存在する場合，remove操作時にIllegalArgumentExceptionがスローされます。

Cosminexus JPAプロバイダの場合，データベースに対応する行が存在しないときには，remove操作は無視されます。ただし，ほかのエンティティへのリレーションシップのcascade属性にREMOVEまたはALLが指定されていれると，このエンティティが参照するエンティティにremove操作が伝播されます。

removed
remove操作は無視されます。ほかのエンティティへの伝播もしません。

注1　removed状態のエンティティはトランザクションのコミット時，トランザクションのコミット前，またはflush操作時の実行結果としてデータベースから削除されます。

注2　エンティティが削除されたあと，エンティティの内容はremove処理が呼び出された直後の内容になります。ただし，エンティティの生成直後の場合を除きます。

6.4.4　データベースからのエンティティの取得

EntityManagerのfindメソッドまたはgetReferenceメソッドの呼び出しによって，引数で指定した主キーに対応するエンティティをデータベースから取得できます。

EntityManagerのfindメソッドまたはgetReferenceメソッドで返されるエンティティは，トランザクションスコープの永続化コンテキストを利用します。このため，トランザクション内でメソッドを呼び出した場合はmanaged状態になります。また，トランザクション外でfindメソッドまたはgetReferenceメソッドを呼び出した場合はdetached状態になります。

find操作またはgetReference操作で取得したエンティティの状態を次の表に示します。

表6-10　find操作またはgetReference操作で取得したエンティティの状態

永続化コンテキスト | 取得したエンティティの状態
トランザクションスコープの永続化コンテキスト（トランザクション外） | detached
トランザクションスコープの永続化コンテキスト（トランザクション内） | managed
拡張された永続化コンテキスト（トランザクション外） | managed
拡張された永続化コンテキスト（トランザクション内） | managed

なお，Cosminexus JPAプロバイダの場合，find操作またはgetReference操作では次の点がJPA仕様と異なります。なお，このほかにJPA仕様との機能差はありません。

JPA仕様では，EntityManagerのgetReferenceメソッドでは実際のインスタンスではなく，引数で与えられた主キーに対応するエンティティにProxyを返すことができます。ただし，Cosminexus JPAプロバイダでは，@Basicに対するLazyローディングをサポートしていません。このため，Cosminexus JPAプロバイダでは，getReferenceの戻り値として，Proxyではなくエンティティインスタンスを返します。
なお，リレーションシップに対するLazyローディングのサポート範囲については，「6.4.5(2)　データベースからのエンティティ情報の読み込み」を参照してください。

Cosminexus JPAプロバイダでは，findメソッドとgetReferenceメソッドの間で存在しないエンティティを引数に指定した場合，findメソッドではnull値が返ります。また，getReferenceメソッドではEntityNotFoundExceptionが発生します。

6.4.5　データベースとの同期

トランザクションのコミットまたはflushメソッドの実行時に，エンティティの状態がデータベースに書き込まれます。一方，明示的にrefreshを呼び出さないかぎり，メモリにロードされたエンティティの状態のリフレッシュは実行されません。

ここでは，データベースへのエンティティ情報の書き込みと，データベースからのエンティティ情報の読み込みについて説明します。

＜この項の構成＞

(1)　データベースへのエンティティ情報の書き込み

(2)　データベースからのエンティティ情報の読み込み

(1)　データベースへのエンティティ情報の書き込み

flush操作またはトランザクションのコミットでのエンティティの状態遷移について説明します。次の表ではエンティティAの状態ごとに状態遷移の結果を示しています。

表6-11　flush操作またはトランザクションのコミットでのエンティティインスタンスの状態遷移

エンティティAの状態 | 状態遷移の結果
new | flush操作は無視されます。
managed | データベースと同期されます。
removed | エンティティAはデータベースから削除されます。
detached | flush操作は無視されます。

また，managed状態のエンティティAがエンティティBに対してリレーションシップを持っている場合，flush処理の延長で次の表に示す条件に従って，persist操作がカスケードされます。

表6-12　関連するエンティティBへのflush処理およびコミットでのpersist操作のカスケード

エンティティBへのリレーションシップのcascade属性の指定
エンティティBの状態
結果

PERSISTまたはALLが指定されている
－
persist操作がエンティティBにカスケードされます。

PERSISTまたはALLが指定されていない
new

flush操作の場合
IllegalStateExceptionが発生してトランザクションはロールバックにマークされます。

コミット処理の場合
IllegalStateExceptionが発生してトランザクションのコミットに失敗します。

managed
データベースと同期化されます。

removed

flush操作の場合
IllegalStateExceptionが発生してトランザクションはロールバックにマークされます。

コミット処理の場合
IllegalStateExceptionが発生してトランザクションのコミットに失敗します。

detached

エンティティAがリレーションシップの所有者の場合
リレーションシップの変更はデータベースと同期されます。

エンティティBがリレーションシップの所有者の場合
例外が発生します。Cosminexus JPAプロバイダでは，この場合の動作はサポート対象外となります。

なお，トランザクションの外でflushメソッドを呼び出すと，TransactionRequiredExceptionが発生します。

ポイント

リレーションシップとデータベースに対する永続化の関連

双方向のリレーションシップを持つmanaged状態のエンティティは，リレーションシップの所有者側で保持される参照を基に永続化されます。アプリケーション開発者は，変更が発生したときに所有者側と被所有者側でそれぞれ，メモリ上の状態に矛盾がないようにエンティティを保持するようアプリケーションを作成してください。

単方向のOneToOne，OneToManyの場合，エンティティで定義しているリレーションシップの関係とデータベースのテーブル間の関係が合っていることは，開発者の責任で保証してください。

(2)　データベースからのエンティティ情報の読み込み

EntityManagerのrefreshメソッドを呼び出すと，それまでに行われたエンティティの変更は破棄され，データベースの内容でエンティティの状態を上書きします。このとき，データベース上に対応する行が存在しない場合はEntityNotFoundExceptionが発生します。

エンティティがmanaged状態以外の場合に，EntityManagerのrefreshメソッドを呼び出すとIllegalArgumentExceptionが発生します。

(a)　データベースからのエンティティ情報を読み込むタイミング

refreshメソッドもしくはfindメソッドの実行時，またはクエリの発行時に，データベースからエンティティが読み込まれます。このときに，関連するエンティティもあわせて読み込むことができます。これをフェッチ戦略といいます。フェッチ戦略は各リレーションシップのfetch属性で指定します。fetch属性には次の2種類のどちらかを指定します。

FetchType.EAGER
データベースからエンティティの情報を読み込むときに，関連するフィールドやエンティティの情報を読み込みます。

FetchType.LAZY
フィールドまたは関連先に初めてアクセスしたときにデータベースからの読み込みが実行されます。これを，Lazyローディングといいます。

FetchType.EAGERを指定するとデータベースからエンティティの情報を読み込むたびに，関連するフィールドやエンティティの情報を読み込みます。このため，不要な関連先のエンティティの取得を回避したい場合は，FetchType.LAZYを指定してください。

Cosminexus JPAプロバイダでのfetch属性のサポート範囲を次の表に示します。

表6-13　リレーションシップごとのfetch属性のサポート範囲

リレーションシップのアノテーション | サポート範囲
@ManyToMany | デフォルトはFetchType.LAZYです。
@OneToMany | デフォルトはFetchType.LAZYです。
@OneToOne | デフォルトはFetchType.EAGERです。なお，LAZYを指定したときには，(b)を参照してください。
@ManyToOne | デフォルトではFetchType.EAGERです。なお，LAZYを指定したときには，(b)を参照してください。
@Basic | fetch属性は無視されます。デフォルトのFetchType.EAGERが常に適用されます。

(b)　@OneToOneおよび@ManyToOneでのLAZYフェッチ

@OneToOneおよび@ManyToOneのリレーションシップに対してフェッチ戦略にLAZYを指定した場合，エンティティクラスのローディング時に，LAZYを指定したフィールドのgetterメソッドにバイナリコードを埋め込みます。

getterメソッドが呼び出されると，埋め込んだバイナリコードの処理を通して，データベースから関連先のエンティティを取得します。getterメソッドがバイナリの埋め込み対象になるため，リレーションの対象となるフィールドにアクセスするためのgetterメソッドを設定しておく必要があります。また，そのgetterメソッドに@OneToOneまたは@ManyToOneを設定しておく必要があります。

注意

getterメソッドでは，リレーションシップのtargetEntityの型から，関連先のエンティティの型を決定します。targetEntityに指定するクラスの型は，フィールド・プロパティの型にキャストできる必要があります。

6.4.6　永続化コンテキストからのエンティティの切り離しとmerge操作

永続化コンテキストから切り離されたエンティティをdetached状態のエンティティといいます。エンティティは次のタイミングでdetached状態になります。

トランザクションスコープの永続化コンテキストでのトランザクションをコミットしたとき

トランザクションのロールバックを実行したとき

永続化コンテキストをクリアしたとき（EntityManager.clear()を呼び出したとき）

EntityManagerをクローズしたとき

エンティティのシリアライズおよびエンティティの値渡しをしたとき

切り離されたエンティティのインスタンスは，永続化や取得をした永続化コンテキストの外で存在し続けます。エンティティの状態とデータベースの状態は同期されません。

＜この項の構成＞

(1)　detached状態のエンティティへのアクセス

(2)　エンティティのmerge処理

(3)　注意事項

(1)　detached状態のエンティティへのアクセス

アプリケーションは永続化コンテキストの終了後でも，detached状態のエンティティにアクセスできます。この場合，エンティティのフィールドおよび関連先は，フェッチ済みである必要があります。detached状態のエンティティでフェッチされていないフィールドおよび関連先のエンティティにはアクセスできません。なお，フィールドに指定する@Basicには常にFetchType.EAGERが適用されるため，関連先のエンティティやフィールドの情報が取得済みとなります。

リレーションシップではdetached状態のエンティティからアクセスするには，次に示すどれかの条件を満たす必要があります。

find()で取得されたエンティティインスタンスであること

クエリを使って取得されたエンティティまたはFETCH JOIN節で明示的に要求されたエンティティであること

プライマリキーでない永続状態のインスタンスをアプリケーションでアクセス済みであること

fetch=EAGERと指定された関連をたどって別の有効なエンティティから取得済みのエンティティであること

利用できないインスタンスへのアクセス，および利用できるインスタンスの無効なステートへのアクセスを行った場合は，例外が発生します。ただし，Cosminexus JPAプロバイダでは，FetchType.LAZYを指定した場合，EntityManagerの終了後にdetached状態になっていても，フェッチされていないフィールドおよび関連先エンティティにアクセスすると，データベースから値を取得して，内容を参照することができる場合があります。

(2)　エンティティのmerge処理

EntityManagerのmergeメソッドの呼び出し，またはmerge処理のカスケードによって，detached状態のエンティティをEntityManagerで管理される永続化コンテキストにマージできます。

次の表にmerge処理でのエンティティの状態遷移を，エンティティAの状態ごとに示します。

表6-14　merge処理でのエンティティの状態遷移の結果

エンティティAの状態 | 状態遷移の結果
new | managed状態のエンティティA'が新しく作成されて，エンティティAの状態がエンティティA'にコピーされます。mergeの引数のエンティティはnewのままであることに注意してください。
managed | merge操作は無視されます。しかし，エンティティAからほかのエンティティへのリレーションシップのcascade属性に，MERGEまたはALLが指定されている場合，エンティティAが参照するエンティティにmerge操作が伝播されます。
detached | エンティティAの状態が，同じIDを持つすでに存在している管理されたエンティティA'にコピーされます。または，エンティティAのコピーである新しいmanaged状態のエンティティが作成されます。mergeの引数のエンティティはdetached状態のままであることに注意してください。
removed | merge操作によって，IllegalArgumentExceptionが発生します。または，トランザクションのコミットに失敗します。エンティティAの状態はremoved状態のままであることに注意してください。

注1　エンティティAからエンティティBへのリレーションがcascade=MERGEまたはcascade=ALLで指定されていると，すべてのエンティティBは再帰的にエンティティB'としてマージされます。エンティティA'にはエンティティB'がセットされます。なお，エンティティAがmanaged状態の場合，エンティティAとエンティティA'は同じであることに注意してください。

注2　エンティティAのリレーションにcascade=MERGEまたはcascade=ALLが指定されていない状態でエンティティBを参照している場合，エンティティAがエンティティA'にマージされるときには，エンティティA'から関連をたどるとエンティティBと同じ永続化アイデンティティを持つ管理されたエンティティB'の参照にたどり着きます。

JPA仕様では，フェッチされていないことを意味するLAZYにマークされたフィールドはマージのときに無視されます。ただし，Cosminexus JPAプロバイダでは，@BasicはEAGERとして動作するため，リレーションシップでないすべてのフィールドはマージ処理の対象となります。

また，Version列がエンティティで使われている場合は，マージ操作とそのあとに呼ばれるフラッシュおよびコミット処理時に，エンティティのバージョンチェックを実行します。Version列が存在しない場合，merge操作ではエンティティのバージョンチェックは実行されません。詳細については，「6.10.1　楽観的ロックの処理」を参照してください。

なお，Cosminexus JPAプロバイダでは，ほかベンダとの間で，エンティティのマージ処理によって永続化コンテキストに戻すという処理はサポートしていません。

(3)　注意事項

Cosminexus JPAプロバイダの場合，トランザクションスコープの永続化コンテキストでは，managed状態のエンティティはトランザクションのコミットによってdetached状態になります。一方，拡張された永続化コンテキストでは，managed状態のエンティティは管理されたままとなります。

トランザクションスコープでも拡張された永続化コンテキストでも，トランザクションをロールバックすると，すべての存在しているmanaged状態のインスタンスとremoved状態のインスタンスは，detached状態になります。インスタンスの状態は，トランザクションがロールバックされた時点の状態です。

トランザクションをロールバックすると，永続化コンテキストの状態はロールバックした時点の状態になるため，データベースの状態と矛盾します。なお，Cosminexus JPAプロバイダの場合は，バージョン属性の状態と生成された状態は矛盾した状態になるため，merge操作などを行うと例外になることがあります。

6.4.7　managed状態のエンティティ

EntityManagerのcontains()メソッドはエンティティのインスタンスがカレントの永続化コンテキストで管理されているかを取得するために利用できます。

ここでは，contains()メソッドの戻り値の条件について説明します。

contains()メソッドがtrueを返す条件

エンティティがデータベースから取得されていて，EntityManagerから削除されていない場合，または切り離されていない場合

エンティティのインスタンスが生成され，persistメソッドがそのエンティティに対して実行されている場合，またはpersist操作がそのエンティティに伝播されている場合

contains()メソッドがfalseを返す条件

エンティティのインスタンスが切り離されている場合

removeメソッドがエンティティに対して実行されている場合，またはremove操作がエンティティに伝播されている場合

エンティティのインスタンスが生成され，persistメソッドがそのエンティティに対して実行されていない場合，またはpersist操作がそのエンティティに伝播されていない場合

実際のデータベースでのinsertおよびdelete処理がトランザクションの決着まで遅延されます。これに対して，persistやremoveの伝播はcontainsメソッドではすぐに反映されることに注意してください。

なお，エンティティのインスタンスが単一の永続化コンテキストでだけ管理されていることは，アプリケーション側で保証してください。Cosminexus JPAプロバイダでは，同じJavaのインスタンスを複数の永続化コンテキストで管理した場合の動作は保証しません。

6.5　データベースとJavaオブジェクトとのマッピング情報の定義

Cosminexus JPAプロバイダでは，データベースとJavaオブジェクトをマッピングするための情報を定義できます。マッピング情報はアノテーションまたはO/Rマッピングファイルで定義します。

アノテーションを使用した定義
アプリケーションのエンティティクラスに直接マッピング情報を定義します。

O/Rマッピングファイルを使用した定義
O/Rマッピングファイルとは，マッピング情報を記載するためのXML形式のファイルです。タグを使用してマッピング情報を定義します。

アノテーションとO/Rマッピングファイルの両方でマッピング情報を定義している場合，O/Rマッピングファイルの定義が優先されます。このため，アノテーションを使用して定義したマッピング情報を変更する場合にO/Rマッピングファイルを使用すると，アプリケーションを変更することなくマッピング情報を変更できます。

アプリケーションの作成方針に合わせて，アノテーションを使用するか，O/Rマッピングファイルを使用するか，またはアノテーションとO/Rマッピングファイルを併用するかを決定してください。

6.6　エンティティのリレーションシップ

エンティティでは，データベースのテーブル間の関連をリレーションシップで表現できます。Cosminexus JPAプロバイダでは，エンティティのリレーションシップを設定できます。

＜この節の構成＞

6.6.1　リレーションシップの種類

6.6.2　リレーションシップのアノテーション

6.6.3　リレーションシップの方向

6.6.4　デフォルトマッピング（双方向のリレーションシップ）

6.6.5　デフォルトマッピング（単方向のリレーションシップ）

6.6.1　リレーションシップの種類

リレーションシップには関連と方向があります。関連には，OneToOne，ManyToOne，OneToMany，およびManyToManyがあります。また，それぞれの関連の方向には，単方向と双方向があります。関連と方向を組み合わせると，リレーションシップの種類には次の7種類があります。

単方向のOneToOneリレーションシップ

単方向のManyToOneリレーションシップ

単方向のOneToManyリレーションシップ

単方向のManyToManyリレーションシップ

双方向のOneToOneリレーションシップ

双方向のManyToOne/OneToManyリレーションシップ

双方向のManyToManyリレーションシップ

ある会社の従業員と部門を例にリレーションシップについて説明します。従業員と部門は次のような関連があります。

エンティティでは，従業員と部門をそれぞれ表現します。

従業員は必ずどこかの部門に所属するものとします。

部門では複数の従業員を保持します。

従業員から部門を参照したり，部門から従業員を参照したりします。

この例の場合，エンティティの双方向のManyToOne/OneToManyリレーションシップで表現します。この場合，Manyが従業員，Oneが部門となります。従業員のエンティティと部門のエンティティの関連を次の図に示します。

図6-4　従業員のエンティティと部門のエンティティの関連

なお，エンティティには，関連先のエンティティに操作を伝播させる設定ができます。この設定をカスケードといいます。カスケードが設定されていると，エンティティに対して操作した場合，操作したエンティティとリレーションシップがあるエンティティにも自動的に同様の操作が実行されます。カスケードを利用すると，ユーザは関連先のエンティティへの操作の手間を省くことができます。

6.6.2　リレーションシップのアノテーション

エンティティではテーブル間の関連をリレーションシップとして扱います。リレーションシップをエンティティで扱う場合，エンティティでフィールドとしてほかのエンティティへの参照を保持します。その上で，次に示すリレーションシップのアノテーションを，エンティティを参照する永続化プロパティまたはインスタンス変数に設定してください。

OneToOne（1対1）

OneToMany（1対多）

ManyToOne（多対1）

ManyToMany（多対多）

エンティティのリレーションシップとテーブル間の関連を次の図に示します。

図6-5　エンティティのリレーションシップとテーブル間の関連

エンティティへの参照に対して，リレーションシップのアノテーションが指定されていない場合は動作を保証しません。なお，コレクションを使用した参照で，generic型を利用しない場合，リレーションシップのtargetとして，対象のエンティティを指定する必要があります。

なお，アノテーションを使用する代わりに，O/Rマッピングファイルでリレーションシップを定義することもできます。ただし，O/Rマッピングファイルで定義している場合で，同じ定義をアノテーションに指定しているときには，アノテーションの定義は上書きされるので注意してください。

リレーションシップのアノテーションでのデフォルトマッピング

OneToOne，OneToMany，ManyToOne，ManyToManyのリレーションシップのアノテーションを適用した場合，デフォルトマッピングの規則が適用されます。O/Rマッピングファイルでリレーションシップを指定した場合も同様に，デフォルトマッピングが適用されます。

リレーションシップのアノテーションのデフォルトマッピングを使用する場合，データベースのテーブルおよびリレーションが，「6.6.4　デフォルトマッピング（双方向のリレーションシップ）」または「6.6.5　デフォルトマッピング（単方向のリレーションシップ）」にあるデフォルトと異なると，実行時にデータベース問い合わせでSQL文が正しく作成できません。例外が発生します。

6.6.3　リレーションシップの方向

リレーションシップには，双方向のリレーションシップと単方向のリレーションシップがあります。双方向のリレーションシップを扱う場合，リレーションシップには所有者と被所有者があります。単方向のリレーションシップには所有者だけがあります。リレーションシップの所有者は，データベースのリレーションシップの更新を決定できます。

双方向のリレーションシップでは，次のルールが適用されます。

双方向のリレーションシップの被所有者は，@OneToOne，@OneToMany，@ManyToManyのmappedBy要素によって，所有者を指定します。mappedBy要素では，所有者のエンティティで，被所有者側を参照しているプロパティまたはフィールドの名前を指定します。

ManyToOne/OneToMany双方向のリレーションシップでは，many側を所有者にしてください。そのため，mappedBy要素は@ManyToOneでは指定できません。

OneToOneの双方向のリレーションシップでは，外部キーを含む側のエンティティが所有者になります。

ManyToManyの双方向のリレーションシップは，どちらが所有者でもかまいません。

リレーションシップのアノテーションにはcascade属性があります。cascade属性を指定すると，エンティティに対する操作を参照先のエンティティに対しても伝播させることができます。ただし，リレーションシップのアノテーションのcascade属性にREMOVEを指定できるのは，OneToOneまたはOneToManyのときだけです。ほかのリレーションに対してcascade=REMOVEを適用した場合の動作は保証しません。エンティティがリレーションシップを持つ場合のcascade属性については，「6.4.1(4)　エンティティに対する操作の伝播」を参照してください。

注意

Cosminexus JPAプロバイダでは，実行時のリレーションシップの一貫性を保つためのチェックは実施しません。このため，アプリケーションの実行時にリレーションシップを更新する場合に，リレーションシップに矛盾が発生するような更新を行っても，警告や例外は発生しません。

なお，OneToMany，ManyToManyなどのコレクションのリレーションシップでは，データベースから値をフェッチした場合に，関連するエンティティが存在しないときには，リレーションシップの値として空のコレクションを返します。

6.6.4　デフォルトマッピング（双方向のリレーションシップ）

ここでは，双方向のリレーションシップのデフォルトマッピングについて説明します。

＜この項の構成＞

(1)　双方向のOneToOneリレーションシップ

(2)　双方向のManyToOne/OneToManyリレーションシップ

(3)　双方向のManyToManyリレーションシップ

(1)　双方向のOneToOneリレーションシップ

次に示す条件の場合に適用される双方向のOneToOneリレーションシップのデフォルトマッピングについて説明します。

条件

エンティティAはエンティティBの単体のインスタンスを参照して，@OneToOneを設定します。

エンティティBはエンティティAの単体のインスタンスを参照して，@OneToOneを設定します。@OneToOneのmappedBy属性にエンティティAでエンティティBを参照する永続化プロパティ（またはフィールド）名を指定します。

エンティティAは，リレーションシップの所有者です。

適用されるデフォルトマッピング

エンティティAは，テーブルAにマップされます。

エンティティBは，テーブルBにマップされます。

テーブルAは，テーブルBの外部キーを持つ必要があります。なお，外部キー列の名前は，次のようになります。
外部キー列の名前
エンティティAのリレーションシッププロパティ（またはフィールド）の名前_テーブルBのプライマリキー列の名前
注　斜体は可変値を表します。

また，外部キー列は，テーブルBのプライマリキーと同じ型を持ち，ユニークキー制約があります。

図6-6　双方向のOneToOneでのデフォルトマッピング

(2)　双方向のManyToOne/OneToManyリレーションシップ

次に示す条件の場合に適用される双方向のManyToOne/OneToManyリレーションシップのデフォルトマッピングについて説明します。

条件

エンティティAはエンティティBの単体のインスタンスを参照して，@ManyToOne（または，O/Rマッピングファイルの該当するXMLタグ）を設定します。

エンティティBは，エンティティAのコレクションを参照して，@OneToMany（または，O/Rマッピングファイルの該当するXMLタグ）を設定します。@OneToManyにはmappedBy属性を指定します。mappedBy属性は，エンティティAで，エンティティBを参照するために設定した永続プロパティ（またはフィールド）名を指定します。

エンティティAは，リレーションシップの所有者です。

適用されるデフォルトマッピング

エンティティAはテーブルAにマップされます。

エンティティBはテーブルBにマップされます。

テーブルAは，テーブルBに対する外部キーを持つ必要があります。外部キー列の名前は，次のようになります。
外部キー列の名前
エンティティAのリレーションシッププロパティ（またはフィールド）の名前_テーブルBのプライマリキー列の名前
注　斜体は可変値を表します。

外部キー列はテーブルBのプライマリキーと同じ型を持ちます。

図6-7　双方向のManyToOne/OneToManyでのデフォルトマッピング

(3)　双方向のManyToManyリレーションシップ

次に示す条件の場合に適用される双方向のManyToManyリレーションシップのデフォルトマッピングについて説明します。

条件

エンティティAは，エンティティBのコレクションを参照します。コレクションには，@ManyToMany（または，O/Rマッピングファイルで該当するXML要素）を設定します。

エンティティBは，エンティティAのコレクションを参照します。コレクションには，@ManyToMany（または，O/Rマッピングファイルで該当するXMLタグ）を設定して，mappedBy属性を指定します。mappedBy属性には，エンティティAで，エンティティBを参照するために設定した永続化プロパティ（またはフィールド）名を指定します。

エンティティAは，リレーションシップの所有者側です。

適用されるデフォルトマッピング

エンティティAは，テーブルAにマップされます。

エンティティBは，テーブルBにマップされます。

テーブルA，Bのほかに，所有者側のテーブルの名前が最初にくるA_Bという名前の結合表が必要です。この結合表は，二つの外部キー列を持ちます。
一つ目の外部キー列はテーブルAを参照し，テーブルAのプライマリキーと同じ型を持ちます。この外部キー列の名前は，次のようになります。
外部キー列の名前
エンティティBのリレーションシップのプロパティ（またはフィールド）の名前_テーブルAのプライマリキーの名前
また，もう一つの外部キー列は，テーブルBを参照し，テーブルBのプライマリキーと同じ型を持ちます。この外部キー列の名前は，次のようになります。
外部キー列の名前
エンティティAのリレーションシップのプロパティ（またはフィールド）の名前_テーブルBのプライマリキーの名前
注　斜体は可変値を表します。

図6-8　双方向ManyToManyでのデフォルトマッピング

6.6.5　デフォルトマッピング（単方向のリレーションシップ）

単方向のリレーションシップには，Single-ValuedリレーションシップとMulti-Valuedリレーションシップがあります。それぞれのリレーションシップについて説明します。

単方向のSingle-Valuedリレーションシップ
単方向のSingle-Valuedリレーションシップとは，単体のインスタンスを参照し，所有者だけが存在するリレーションシップのことです。
単方向Single-Valuedリレーションシップには，単方向のOneToOneリレーションシップと単方向のManyToOneリレーションシップがあります。

単方向のMulti-Valuedリレーションシップ
単方向のMulti-Valuedリレーションシップとは，コレクションの形でエンティティを参照し，所有者だけが存在するリレーションシップのことです。
単方向Multi-Valuedリレーションシップには，単方向のOneToManyリレーションシップと単方向のManyToManyリレーションシップがあります。

ここでは，単方向のリレーションシップのデフォルトマッピングについて説明します。

＜この項の構成＞

(1)　単方向のSingle-Valuedリレーションシップ

(2)　単方向のMulti-Valuedリレーションシップ

(1)　単方向のSingle-Valuedリレーションシップ

単方向のOneToOneリレーションシップと単方向のManyToOneリレーションシップのデフォルトマッピングについて説明します。

(a)　単方向のOneToOneリレーションシップ

次に示す条件の場合に適用される単方向のOneToOneリレーションシップのデフォルトマッピングについて説明します。

条件

エンティティAは，エンティティBの単体のインスタンスを参照して，@OneToOne（または，O/Rマッピングファイルで該当するXMLタグ）を設定します。

エンティティBからは，エンティティAを参照しません。

エンティティAがリレーションシップの所有者となります。

適用されるデフォルトマッピング

エンティティAは，テーブルAにマップされます。

エンティティBは，テーブルBにマップされます。

テーブルAは，テーブルBに対する外部キーを持つ必要があります。外部キー列の名前は，次のようになります。
外部キー列の名前
エンティティAのリレーションシップのプロパティ（または，フィールド）の名前_テーブルBのプライマリキー列の名前
注　斜体は可変値を表します。

外部キー列は，テーブルBのプライマリキーと同じ型を持ち，ユニークキー制約です。

図6-9　単方向のOneToOneでのデフォルトマッピング

(b)　単方向のManyToOneリレーションシップ

次に示す条件の場合に適用される単方向のManyToOneリレーションシップのデフォルトマッピングについて説明します。

条件

エンティティAは，エンティティBの単体のインスタンスを参照し，@ManyToOne（または，O/Rマッピングファイルで該当するXMLタグ）を設定します。

エンティティBからは，エンティティAを参照しません。

適用されるデフォルトマッピング

エンティティAは，テーブルAにマップされます。

エンティティBは，テーブルBにマップされます。

テーブルAは，テーブルBに対する外部キーを持つ必要があります。外部キー列の名前は，次のようになります。
外部キー列の名前
エンティティAのリレーションシップのプロパティ（またはフィールド）の名前_テーブルBのプライマリキー列の名前
注　斜体は可変値を表します。

外部キー列は，テーブルBのプライマリキーと同じ型を持つ必要があります。

図6-10　単方向のManyToOneでのデフォルトマッピング

(2)　単方向のMulti-Valuedリレーションシップ

単方向のOneToManyリレーションシップと単方向のManyToManyリレーションシップのデフォルトマッピングについて説明します。

(a)　単方向のOneToManyリレーションシップ

次に示す条件の場合に適用される単方向のOneToManyリレーションシップのデフォルトマッピングについて説明します。

条件

エンティティAは，エンティティBのコレクションを参照します。コレクションに@OneToMany（または，O/Rマッピングファイルで該当するXMLタグ）を設定します。

エンティティBからは，エンティティAを参照しません。

エンティティAがリレーションシップの所有者です。

適用されるデフォルトマッピング

エンティティAは，テーブルAにマップされます。

エンティティBは，テーブルBにマップされます。

テーブルA，Bのほかに，所有者側のテーブルの名前が最初にくるA_Bという名前の結合表が必要となります。この結合表は，二つの外部キー列を持ちます。
一つ目の外部キー列は，テーブルAを参照し，テーブルAのプライマリキーと同じ型を持ちます。この外部キー列の名前は，次のようになります。
外部キー列の名前
エンティティAの名前_テーブルAのプライマリキー列の名前
また，もう一つの外部キー列は，テーブルBを参照し，テーブルBの外部キーと同じ型を持ち，ユニークキー制約があります。この外部キー列の名前は，次のようになります。
外部キー列の名前
エンティティAのリレーションシッププロパティ（またはフィールド）の名前_テーブルBのプライマリキー列の名前
注　斜体は可変値を表します。

注意

この例のような結合表を使用した単方向のOneToManyリレーションシップは，Cosminexus JPAプロバイダ以外のJPAプロバイダではサポートされていない可能性があります。単方向のOneToManyリレーションシップで作成したアプリケーションをCosminexus JPAプロバイダ以外のJPAプロバイダで動作させる場合は注意してください。

図6-11　単方向OneToManyでのデフォルトマッピング

(b)　単方向のManyToManyリレーションシップ

次に示す条件の場合に適用される単方向のManyToManyリレーションシップのデフォルトマッピングについて説明します。

条件

エンティティAは，エンティティBのコレクションを参照します。コレクションに@ManyToMany（または，O/Rマッピングファイルで該当するXMLタグ）を設定します。

エンティティBは，エンティティAを参照しません。

所有者はエンティティAです。

適用されるデフォルトマッピング

エンティティAは，テーブルAにマップされます。

エンティティBは，テーブルBにマップされます。

テーブルA，Bのほかに，所有者側のテーブルの名前が最初にくるA_Bという名前の結合表が必要となります。この結合表は，二つ外部キー列を持ちます。
外部キー列の一つは，テーブルAを参照し，テーブルAの外部キーと同じ型を持ちます。この外部キー列の名前は，次のようになります。
外部キー列の名前
エンティティAの名前_テーブルAのプライマリキーの名前
また，もう一つの外部キー列は，テーブルBを参照し，テーブルBのプライマリキーと同じ型を持ちます。外部キー列の名前は，次のようになります。
外部キー列の名前
エンティティAのリレーションシップのプロパティ（またはフィールド）の名前_テーブルBのプライマリキーの名前
注　斜体は可変値を表します。

図6-12　単方向ManyToManyでのデフォルトマッピング

6.7　エンティティオブジェクトのキャッシュ機能

エンティティオブジェクトのキャッシュ機能とは，アプリケーションで使用したエンティティオブジェクトをメモリ内で保持するための機能です。エンティティオブジェクトのキャッシュ機能を使用している場合に，同じエンティティオブジェクトが操作されると，Cosminexus JPAプロバイダ内にキャッシュされているエンティティオブジェクトが使用されます。データベースから再度データを読み込むことがないので，データベースへのアクセスが最小限になり，処理性能の負荷を軽減できます。なお，この機能は，Cosminexus JPAプロバイダ独自の機能です。

ここでは，エンティティオブジェクトのキャッシュ機能について説明します。

＜この節の構成＞

6.7.1　キャッシュ機能の処理

6.7.2　キャッシュの参照形態とキャッシュタイプ

6.7.3　キャッシュ機能の有効範囲

6.7.4　キャッシュ機能を使用するときの注意事項

6.7.1　キャッシュ機能の処理

キャッシュ機能を使用している場合，同じエンティティに対して読み込みをすると，データベースではなく，キャッシュからデータが取得されるようになります。キャッシュ機能の処理の流れ，キャッシュの登録および更新のタイミング，およびキャッシュの更新処理の流れを説明します。

＜この項の構成＞

(1)　キャッシュ機能の処理の流れ

(2)　キャッシュの登録および更新のタイミング

(3)　キャッシュの更新処理の流れ

(4)　JPQLとキャッシュの関係

(1)　キャッシュ機能の処理の流れ

キャッシュ機能の処理の流れについて次の図に示します。

図6-13　キャッシュ機能の処理の流れ

上記の図について説明します。

エンティティの読み込み処理
findなどのメソッドで最初にエンティティを読み込むときは次の流れで処理されます。

エンティティの読み込み処理をします。

データベースからデータを取得します。

取得したデータのエンティティオブジェクトをキャッシュに登録します。

エンティティがリレーションシップを持つ場合でリレーションシップ先のエンティティを取得するとき，目的のエンティティがキャッシュに存在すると，データベースにアクセスしないでキャッシュのエンティティを参照します。

キャッシュは，永続化コンテキスト単位で存在します。

(2)　キャッシュの登録および更新のタイミング

キャッシュへの登録および更新は次に示すタイミングで実施されます。

キャッシュの登録のタイミング
対象となるキャッシュが存在しない状態でのエンティティオブジェクトの読み込み時（find操作）

キャッシュの更新のタイミング

エンティティのリフレッシュ処理時（refresh操作）

トランザクションのコミット時

楽観的ロックの処理で例外が発生した場合
なお，楽観的ロックの処理でOptimisticLockException例外が発生した場合には，キャッシュに登録されているエンティティオブジェクトは削除されます。

(3)　キャッシュの更新処理の流れ

キャッシュの更新処理の流れについて次の図に示します。

図6-14　キャッシュの更新処理

図について説明します。

エンティティオブジェクトに対して，次の操作を実施します。

refresh操作

トランザクションのコミット

refresh操作の場合は，データベースにアクセスします。

永続化コンテキストにあるデータをキャッシュに登録して，キャッシュのデータを更新します。

なお，JPQLを実行した場合にもキャッシュは登録されます。登録されるタイミングは，対象となるキャッシュが存在しない状態でJPQLを実行した場合です。JPQLでもキャッシュのデータを使用しますが，キャッシュのデータの有無に関係なく，データベースのアクセスが発生します。このため，キャッシュによる処理性能の向上は期待できません。詳細については，(4)を参照してください。

キャッシュは，エンティティのオブジェクト単位で情報を保持しているため，クエリの実行時に返されるオブジェクトがエンティティ自身の場合には，キャッシュへの更新が実行されます。それ以外のフィールドを指定するような場合では，更新はされません。キャッシュの更新が有効になる場合と，ならない場合のJQPLの例を次に示します。

キャッシュの更新が有効に行われるJPQLの例

SELECT emp FROM Employee AS emp

キャッシュの更新がされないJPQLの例

SELECT emp.id, emp.name, emp.address FROM Employee AS emp

(4)　JPQLとキャッシュの関係

JPQLでエンティティオブジェクト全体を取得するような場合，キャッシュに登録されている情報が存在すればキャッシュの情報を取得します。Cosminexus JPAプロバイダのキャッシュ機能では，対象となるエンティティを特定するためのIDであるプライマリキーが必要になります。プライマリキーを取得するには，JPQLの結果を取得する必要があり，この際にデータベースへのアクセスが発生します。データベースへのアクセスの結果から，プライマリキーを抽出して，キャッシュからエンティティオブジェクトを取得します。また，キャッシュに対象となるデータが存在しない場合は，データベースの情報からエンティティを作成します。

JPQLでは，キャッシュのデータの有無に関係なく必ずデータベースへのアクセスが発生します。そのため，JPQLの場合，キャッシュによる性能向上は望めません。

6.7.2　キャッシュの参照形態とキャッシュタイプ

キャッシュの参照形態には次の3種類があります。

強参照
ガーベージコレクションによる回収の対象になりません。

弱参照（java.lang.ref.WeakReference）
弱可到達の場合，ガーベージコレクションによる回収の対象になります。なお，弱可到達かどうかは，java.lang.ref.WeakReferenceの仕様に依存します。
Cosminexus JPAプロバイダで弱参照のキャッシュが回収対象にならない例を次に示します。

永続化コンテキストに登録されているエンティティオブジェクトのキャッシュ

弱可到達でないキャッシュにリレーションシップで参照されているキャッシュ

エンティティの継承戦略を使用している場合，継承関係にある別のエンティティオブジェクトのキャッシュが，弱可到達でないキャッシュ

ソフト参照（java.lang.ref.SoftReference）
メモリ残量の低下時にキャッシュアウトする参照形態です。
リソースの消費率や生存期間に応じて，ガーベージコレクションによる回収の対象になります。回収されるタイミングや，回収対象となるオブジェクトの選択方法などの仕様は，JavaVMに依存します。

どの形態でキャッシュを参照するかによってキャッシュタイプの種類が異なります。キャッシュの参照形態とキャッシュタイプの対応を次の表に示します。

表6-15　キャッシュの参照形態とキャッシュタイプの対応

キャッシュの参照形態 | キャッシュタイプ
強参照 | Full
強参照＋弱参照※1 | HardWeak
弱参照＋ソフト参照※1 | SoftWeak
弱参照 | Weak
なし※2 | None

注※1　参照形態を組み合わせます。

注※2　エンティティオブジェクトをキャッシュしません。

Cosminexus JPAプロバイダでは，キャッシュのタイプを選択できます。アプリケーションの設計や環境によってタイプを選択してください。キャッシュタイプは，persistence.xmlで指定します。persistence.xmlについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「6.2　persistence.xml」を参照してください。

次にキャッシュタイプについて説明します。

＜この項の構成＞

(1)　Full

(2)　HardWeak

(3)　SoftWeak

(4)　Weak

(5)　NONE

(1)　Full

すべてのエンティティを強参照でキャッシュします。

キャッシュタイプにFullを指定した場合，データベースへのアクセスが少なくなるため，処理に対する負荷が少なくなります。ただし，メモリを占有し続けるため，メモリへの負荷が高くなります。

Fullは，エンティティオブジェクトの存続期間が長く，頻繁なアクセスを必要とする少数のエンティティオブジェクトで作成される場合に指定します。また，多数のエンティティオブジェクトを読み取る場合は，メモリの負荷が高くなるので，複数レコードを一括更新する場合の使用はお勧めしません。

Fullを指定した場合，指定されたキャッシュサイズで強参照領域を確保します。強参照領域が規定のサイズを超えた場合，Hashtableの仕様に基づいて領域を増やします。Fullを指定した場合のキャッシュ内のイメージを次の図に示します。

図6-15　Fullの場合のキャッシュ内イメージ

(2)　HardWeak

強参照と弱参照でキャッシュします。

エンティティオブジェクトをリストで保持するときには，強参照を使用します。キャッシュサイズに指定した値だけ，強参照領域を固定長で作成します。キャッシュサイズが指定された値に達すると，古いエンティティオブジェクトを弱参照に移動します。このとき，キャッシュへの登録が最も長く使用されていないエンティティオブジェクトから順に弱参照に移動されます。弱参照に移動したエンティティオブジェクトが使用されると，再度，強参照の領域に格納されます。

HardWeakを指定すると，存続期間の長いエンティティオブジェクトを使用して，キャッシュで使用されるメモリを効率良く制御できます。

SoftWeakを使用したシステムでメモリ不足の状態が頻繁に発生する場合には，ソフト参照の利点を生かすことができないため，HardWeakを使用してください。HardWeakの場合のキャッシュ内イメージを次の図に示します。

図6-16　HardWeakの場合のキャッシュ内イメージ

HardWeakの場合，強参照のキャッシュ領域では強参照でキャッシュを保持します。また，弱参照のキャッシュ領域では弱参照でキャッシュを保持します。

(3)　SoftWeak

ソフト参照と弱参照でキャッシュします。

ソフト参照を使用して，エンティティオブジェクトをリストで保持し，キャッシュサイズに指定した値だけ，ソフト参照領域を固定長で作成します。キャッシュサイズが指定された値に達すると，古いエンティティオブジェクトを弱参照の領域に移動します。このとき，キャッシュへの登録が最も長く使用されていないエンティティオブジェクトから順に弱参照に移動されます。弱参照に移動したエンティティオブジェクトが使用されると，再度，強参照の領域に格納されます。

SoftWeakを指定すると，存続期間の長いエンティティオブジェクトを使用して，キャッシュで使用されるメモリを効率良く制御できます。このため，キャッシュ機能を使用する場合は，SoftWeakを指定することをお勧めします。SoftWeakの場合のキャッシュ内イメージを次の図に示します。

図6-17　SoftWeakの場合のキャッシュ内イメージ

SoftWeakの場合，ソフト参照のキャッシュ領域ではソフト参照でキャッシュを保持します。また，弱参照のキャッシュ領域では弱参照でキャッシュを保持します。

(4)　Weak

すべてのエンティティを弱参照でキャッシュします。

このため，すべてのエンティティオブジェクトがガーベージコレクションの対象になります。Weakを指定するとメモリへの負荷が少なくなりますが，ガーベージコレクションによってキャッシュが削除されるおそれがあります。エンティティオブジェクトのキャッシュ機能を重視しないシステムで使用してください。Weakの場合のキャッシュ内イメージを次の図に示します。

図6-18　Weakの場合のキャッシュ内イメージ

Weakの場合，弱参照でエンティティをキャッシュします。

(5)　NONE

エンティティオブジェクトはキャッシュされません。エンティティオブジェクトをデータベースから読み取ったあと，すぐに破棄する場合に使用します。

6.7.3　キャッシュ機能の有効範囲

キャッシュのデータは永続化コンテキスト単位で保持されます。このため，別の永続化コンテキストでエンティティオブジェクトが呼び出されていても，キャッシュからデータを取得できません。

なお，キャッシュのデータは，永続化コンテキストが生成されたときから破棄されるまでの間保持されます。

6.7.4　キャッシュ機能を使用するときの注意事項

ここでは，エンティティオブジェクトのキャッシュ機能を使用するときの注意事項を説明します。

＜この項の構成＞

(1)　クエリでデータを更新または削除した場合の注意

(2)　キャッシュを使用する永続化コンテキストが複数ある場合の注意

(3)　キャッシュの登録および更新タイミングに関する注意事項

(1)　クエリでデータを更新または削除した場合の注意

アプリケーション内でJPQLやネイティブクエリを使用して，データを更新したり，削除したりした場合，キャッシュの内容は更新されません。refresh操作などを行って，データベースの内容を取得し直してください。

次に示す操作の場合，キャッシュのデータを読み込むため，データベースへの更新がされません。

データをエンティティオブジェクトに読み込む。
キャッシュにもエンティティのデータが登録されます。

1.で読み込んだデータを含む削除クエリを実行する。
削除クエリの実行でデータは削除されますが，キャッシュは削除されません。

1.と同じデータをエンティティオブジェクトに読み込む。
1.と同じデータのため，キャッシュにあるデータを読み込みます。

3.のデータをflushする。
データベースには該当する行がないため，追加または更新処理ができません。

(2)　キャッシュを使用する永続化コンテキストが複数ある場合の注意

キャッシュを使用することで，データベースへのアクセス頻度を下げることができます。ただし，一方でキャッシュによるデータのタイムラグが発生して，楽観的ロック例外の発生頻度が高くなるおそれもあります。

キャッシュは永続化コンテキスト単位に存在します。そのため，永続化コンテキストと対で存在するEntityManagerが複数かつ同時期に生成され，同一プライマリキーのエンティティを同時に操作すると，一方でデータを更新しても他方でタイミング良く，更新後のデータを参照できないことがあります。これによって，楽観的ロック例外が発生しやすくなります。

次に，楽観的ロック例外が発生する仕組みと対処方法について説明します。

(a)　楽観的ロック例外が発生する例

ここでは，次の図に示す環境で，永続化コンテキスト単位にキャッシュが存在する場合を例に説明します。

図6-19　この例で説明する環境

図の状態では，キャッシュとデータベースには不整合はなく，すでにキャッシュにAというデータが格納されているものとします。

永続化コンテキスト1でデータをAからBに変更します。
このとき，キャッシュとデータベースの内容が等しいため例外は発生しません。

図6-20　永続化コンテキスト1でのデータの変更

1.の処理が終了後，永続化コンテキスト2でAのデータを変更します。
キャッシュのデータは変更されていないため，データベースのデータとキャッシュに不整合があります。このため，楽観的ロックによる例外が発生します。

図6-21　永続化コンテキスト2でのデータの変更

このような環境の場合，キャッシュを使用すると，更新されないキャッシュが残ってしまい，楽観的ロックによる例外が発生することがあります。

(b)　対処方法

楽観的ロック例外が発生した場合は，キャッシュ内の該当オブジェクトは削除されます。このため，findメソッドを実行するか，またはrefreshメソッドを実行して関連するすべてのデータを再度データベースから取得してください。これによって，キャッシュのデータとデータベースを同期できます。

(3)　キャッシュの登録および更新タイミングに関する注意事項

JPQLを使用して悲観的ロックを取得する場合，クエリの実行時に返されるエンティティオブジェクトはキャッシュに登録されません。

ネイティブクエリを利用して，@SqlResultSetMappingでエンティティを戻り値とするクエリを実行した場合，戻り値のエンティティオブジェクトはキャッシュに格納されます。

エンティティのrefresh操作で，エンティティオブジェクトの読み込み後にほかのスレッドでOptimisticLockExceptionが発生してキャッシュが削除されると，リフレッシュ処理を実行してもキャッシュにエンティティオブジェクトは登録されません。

6.8　プライマリキー値の自動採番

プライマリキー採番機能とは，エンティティオブジェクトを使用してレコードを挿入する際に，プライマリキー値を自動で生成する機能です。この機能によって，ユーザがプライマリキー値を指定しなくても一意の値が格納されるようになります。Cosminexus JPAプロバイダでは，プライマリキー採番機能を提供しています。

プライマリキー値の生成方法

プライマリキー値の生成方法には次の4種類があります。

TABLE
プライマリキー値を保存しておくためのテーブルを使用して，プライマリキー値を生成する方法です。

SEQUENCE
データベースのシーケンスオブジェクトを使用して，プライマリキー値を生成する方法です。ただし，データベースにHiRDBを使用している場合，Cosminexus JPAプロバイダではTABLEと同じ処理を実施します。

IDENTITY
データベースのidentity列を利用してプライマリキー値を生成する方法です。ただし，Cosminexus JPAプロバイダでは，使用しているデータベースの種類によって動作が異なります。
HiRDBの場合，TABLEと同じ処理を実施します。
Oracleの場合，SEQUENCEと同じ処理を実施します。

AUTO
使用しているデータベースに適した生成方法を選択します。Cosminexus JPAプロバイダでは，HiRDBの場合，Oracleの場合ともにTABLEを選択します。

プライマリキー値が採番されるタイミング

Cosminexus JPAプロバイダの場合，flush操作またはトランザクションのコミットのタイミングでプライマリキー値が採番されます。

プライマリキー値の生成方法がSEQUENCEの場合の例

プライマリキー値の生成方法がSEQUENCEの場合の例を示します。この例では，事前にEMP_SEQという名称のシーケンスオブジェクトが作成されているものとします。

@Entity
public class Employee {
・・・
   @SequenceGenerator(
       name="EMPLOYEE_GENERATOR",
       sequenceName="EMP_SEQ"

   )
   @Id
   @GeneratedValue(strategy=GenerationType.SEQUENCE,
generator="EMPLOYEE_GENERATOR")
   @Column(name="EMPLOYEE_ID")
   public Integer getId() {
       return id;
   }
・・・
}

6.9　クエリ言語によるデータベース操作

JPAを使用してデータベースのデータを操作するには，javax.persistence.Queryインタフェースを通して実施します。javax.persistence.Queryインタフェースを使用すると，複数のレコードに対してまとめて，検索，更新，削除などの操作ができます。javax.persistence.Queryインタフェースを使用するには，ユーザはクエリ言語を使用してデータベースを操作します。

Cosminexus JPAプロバイダでは，クエリ言語としてJPQLおよびSQLを使用できます。JPQLおよびSQLについてそれぞれ説明します。

JPQL
JPA仕様で定義されているクエリ言語です。データベースに依存しない言語で，エンティティクラスを対象に操作します。

SQL
データベースに依存したクエリ言語です。ネイティブクエリともいいます。データベースのデータを対象に操作します。

JPQLやSQLによるデータベース操作については，「6.16　クエリ言語を利用したデータベースの参照および更新方法」を参照してください。また，JPQLの文法については，「6.17　JPQLの記述方法」を参照してください。

6.10　楽観的ロック

Cosminexus JPAプロバイダでは，EntityManagerと永続化コンテキストを利用して永続化対象のエンティティを管理します。変更されたエンティティの情報は，flushメソッドまたはトランザクションのコミット処理が実行されたときにデータベースに反映されます。複数のトランザクションで同時にデータベースの同じ行を更新するおそれがある場合，データの整合性を保証する必要があります。データの整合性を保証するために，Cosminexus JPAプロバイダでは楽観的ロックを提供しています。

楽観的ロックとは，データの更新処理を始めてから更新が完了するまでの間に，ほかから更新されていないことを確認するためのロック機能です。楽観的ロックはデータベースをロックしないので，デッドロックなどが発生しないという利点があります。

ここでは，楽観的ロックについて説明します。

＜この節の構成＞

6.10.1　楽観的ロックの処理

6.10.2　楽観的ロックに失敗した場合の例外処理

6.10.3　楽観的ロックを使用する際の注意事項

6.10.1　楽観的ロックの処理

楽観的ロックを使用すると，Cosminexus JPAプロバイダはデータベースのデータがほかのアプリケーションから更新されていないかをユーザに代わってチェックします。データベースのデータが更新されていると，Cosminexus JPAプロバイダは例外を発生させて，ユーザにデータが更新されていることを通知します。また，トランザクションをロールバックにマークします。

＜この項の構成＞

(1)　データ更新の有無のチェック方法

(2)　永続化フィールドおよびリレーションシップのバージョンチェック

(3)　flush操作またはトランザクションの決着時のバージョンチェック

(1)　データ更新の有無のチェック方法

データが更新されているかどうかは，データベースのテーブル上に用意したバージョン列の更新の有無によってチェックします。データベース上のデータが更新されると，バージョン列のバージョン番号が更新されます。これによって，ほかのアプリケーションなどからデータベースが更新されたことがわかります。データベースを更新するときのバージョン列の状態と動作について次の表に示します。

表6-16　データベースを更新するときのバージョン列の状態と動作

テーブルのバージョン列の状態 | 動作
バージョン列の値が更新されていない場合 | Cosminexus JPAプロバイダは，エンティティの情報をデータベースに反映します。このとき，データベースのバージョン列の値を更新します。
バージョン列の値が更新されている場合 | ほかのアプリケーションなどからデータベースのデータが更新されていることを表します。このため，Cosminexus JPAプロバイダはOptimisticLockExceptionを発生させて，トランザクションをロールバックにマークします。

このように，バージョン列の状態によって，エンティティを読み込んだ状態からデータベースを更新するまでに，ほかのトランザクションがデータを更新していないことを保証できます。

(2)　永続化フィールドおよびリレーションシップのバージョンチェック

楽観的ロックを使用するには，エンティティの永続化フィールドおよびリレーションシップの両方をバージョンチェックの対象にします。バージョンチェックの対象とするには，エンティティにバージョン列に対応するVersionフィールド（プロパティ）を設定してください。Versionフィールドは@VersionまたはO/Rマッピングファイルの<version>タグを使用して設定します。

エンティティのバージョンチェックは次のどちらかのタイミングで実行されます。

エンティティの状態が変更され，その変更をデータベースに書き込むとき

merge処理によって，エンティティがmanaged状態に変更されたとき※

注※

バージョンチェックはmerge実行時だけでなく，flushまたはトランザクションのコミット時にもチェックが実行されます。

バージョンチェックによってエンティティのバージョンが古いことが判明した場合，OptimisticLockExceptionが発生します。また，トランザクションはロールバックにマークされます。

(3)　flush操作またはトランザクションの決着時のバージョンチェック

エンティティをflush操作またはトランザクションの決着時にバージョンチェックの対象にできます。バージョンチェックの対象とするには，EntityManagerのlockメソッドにエンティティを指定します。EntityManagerのlockメソッドを使用することで，トランザクションでのバージョンチェック対象にエンティティを追加したり，バージョン列の更新方針を変更したりできます。

Cosminexus JPAプロバイダでは，バージョン列の更新タイミング（lockメソッドのLockModeType）としてLockModeType.READおよびLockModeType.WRITEの二つをサポートしています。バージョン列の更新タイミングの指定内容にかかわらず，Cosminexus JPAプロバイダではトランザクションの決着時に次に示す二つの事象が起きないことを保証します。

ダーティリード（Dirty Read）
トランザクション「T1」が行を変更します。次に，「T1」がコミットやロールバックを行う前に別のトランザクション「T2」が同じ行を読み込み，変更した値を取得します。最終的に「T2」がコミットに成功します。
「T1」がコミットかロールバックをするかどうかが重要ではなく，「T2」のコミットの前またはあとのどちらで「T1」のコミットかロールバックが行われるかが重要になります。

繰り返し不可能な読み込み（un-Repeatable Read）
トランザクション「T1」が行を読み込みます。次に，「T1」がコミットする前に，もう一方のトランザクション「T2」がその行の変更や削除を実施します。最終的に両方のトランザクションはコミットに成功します。

LockModeTypeとしてLockModeType.WRITEを指定すると，エンティティの状態変更がない場合でもバージョン列は強制的に更新されます。バージョン列の更新はflushまたはトランザクションのコミットが呼び出されたタイミングで実行されます。なお，バージョン列の更新前にエンティティが削除された場合，バージョン列の更新は省略されることもあります。

6.10.2　楽観的ロックに失敗した場合の例外処理

明示的に楽観的ロックの実行を確認したい場合は，flush()メソッドを呼び出します。flush()メソッドの呼び出しで楽観的ロック例外が発生した場合，例外処理をキャッチしてリカバリ処理を行うことができます。楽観的ロックに問題がない場合，flush()メソッドによってエンティティのバージョンのチェックおよびVersion列が更新されます。

例外処理の記述例を次に示します。

try{
 em.flush();
} catch (OptimisticLockException e){
 // 例外処理
}

この例に示すように，例外処理の中でOptimisticLockExceptionをラップすることで楽観的ロックの例外をアプリケーション例外として見せることができます。ただし，この場合のトランザクションはロールバックにマークされているので，コミットできないことに注意してください。

なお，Cosminexus JPAプロバイダでは，例外の原因となったエンティティをOptimisticLockExceptionに格納しません。OptimisticLockExceptionのgetEntity()メソッドは常にnull値を返します。

6.10.3　楽観的ロックを使用する際の注意事項

ここでは，楽観的ロックを使用する際の注意事項について説明します。

＜この項の構成＞

(1)　Versionフィールドの設定時の注意事項

(2)　lockメソッド使用時の注意

(3)　HiRDBでのクライアント単位の排他制御について

(1)　Versionフィールドの設定時の注意事項

Versionフィールドの設定時の注意事項を次に示します。

Versionフィールドが設定されていない場合，そのエンティティに対するバージョンチェックは実施しません。その場合，エンティティとデータベースの間の整合性を保つようなアプリケーションをユーザ責任で作成してください。

トランザクションにVersionフィールドが設定されているエンティティと設定されていないエンティティが含まれている場合，Versionフィールドが設定されているエンティティに対してだけバージョンチェックが実行されます。なお，エンティティにバージョンが含まれていないことはトランザクションの決着処理には影響ありません。

ユーザはVersionフィールドの値を参照できますが，更新はしないでください。ただし，バルク更新処理ではVersionフィールドの値を更新できます。

(2)　lockメソッド使用時の注意

lockメソッド使用時の注意事項を次に示します。

Versionフィールド（プロパティ）を持たないエンティティに対するEntityManagerのlockメソッドはサポートしていません。Versionフィールド（プロパティ）を持たないエンティティを指定して，lock(entity, LockModeType.READ)またはlock(entity, LockModeType.WRITE)が呼ばれた場合は，PersistenceExceptionが発生します。

Versionフィールド（プロパティ）を持つエンティティの状態が更新される場合は，lockメソッドの呼び出し有無にかかわらず，ダーティリード，および繰り返し不可能な読み込みの現象は発生しません。

Cosminexus JPAプロバイダではLockModeType.READが指定された場合，エンティティに該当するデータベースの値に変更がないかを確認するために，UPDATE文を発行します。このため，データベースに対してUPDATE文による排他が掛かります。UPDATE文は，flush処理の実行時およびトランザクションのコミット時に発行されます。エンティティオブジェクトの状態に変更がない場合でも発行されます。ただし，エンティティが削除された場合は発行されません。

(3)　HiRDBでのクライアント単位の排他制御について

Cosminexus JPAプロバイダの楽観的ロックは，データベースのIsolationレベルがRead Committedでアクセスされることを想定したロック方式です。データベースがHiRDBの場合，Isolationレベルがデフォルトの設定ではRepeatable Readであるため，Read Committedに変更する必要があります。

クライアント単位のIsolationレベルは，クライアント環境変数のデータ保証レベルのPDISLLVLパラメタで設定します。デフォルトの値はRepeatable Read (2)です。このため，Read Committed (1) に変更してください。変更例を次に示します。

変更例：PDISLLVL=1

クライアント環境変数はConnector属性ファイルの<config-property>タグでenvironmentVariablesプロパティの値に指定するか，またはHiRDBのクライアント環境変数グループの設定ファイルに追加してください。

クライアント環境変数のデータ保証レベルをデフォルト設定のRepeatable Readで動作させた場合は，共有モードで排他が掛かります。このため，findメソッドなどの参照系SQLの発行とflushメソッドなどの更新系SQLの発行を組み合わせることによって，デッドロックが発生しやすくなるので注意してください。

6.11　JPQLでの悲観的ロック

悲観的ロックとは，複数のトランザクションによってデータベース上の同じレコードを更新するときに，対象となるレコードを占有ロックする方法です。あるトランザクションがあるレコードに対して悲観的ロックを掛けると，ほかのトランザクションはそのレコードを参照または更新できません（ただし，Oracleの場合，参照はできます）。悲観的ロックはJPQLを使用しているときだけ使用できます。

悲観的ロックを使用すると，ロックを取得したトランザクションが終了するまでロックの解放待ちが発生します。このため，楽観的ロックよりも同時実行性はありませんが，楽観的ロックで発生するトランザクションのコミット時のエラーを回避できます。

悲観的ロックの指定方法

悲観的ロックは，Cosminexus JPAプロバイダがサポートするクエリヒントを利用することで実現します。悲観的ロックは，QueryメソッドのsetHint()メソッドまたは@NamedQueryの属性に@QueryHintを指定して実行します。

悲観的ロック機能の実装例

悲観的ロック機能の実装例を次に示します。

実装例1

QueryメソッドのsetHint()メソッドで悲観的ロックを指定する場合の例を次に示します。

Query query = manager.createQuery("SELECT emp FROM  Employee  AS emp");
query.setHint("cosminexus.jpa.pessimistic-lock","Lock");

実装例2

@NamedQueryの属性の@QueryHintで悲観的ロックを指定する場合の例を次に示します。

@NamedQuery(
name="employee_list",
query="SELECT emp FROM  Employee AS emp",
hints={ @QueryHint(name="cosminexus.jpa.pessimistic-lock", value="Lock") }
)
@Entity
public class Employee{
・・・
}

注意

悲観的ロックが使用できるのはJPQLの時だけです。createNativeQueryメソッドや@NamedNativeQueryのhints属性に@QueryHintを指定しても有効にはなりません。また，O/Rマッピングファイルの<named-native-query>タグのhint属性に指定した場合も有効にはなりません。なお，Cosminexus JPAプロバイダでの悲観的ロックの排他仕様は，使用するデータベースの仕様に準じます。

6.12　エンティティクラスの作成

JPAを利用したアプリケーションを作成するには，アプリケーションでエンティティクラスを定義します。エンティティクラスは，データベースのテーブルのレコードをJavaのオブジェクトとして扱うためのクラスです。ユーザがアプリケーションでnewオペレーションを行うと，エンティティクラスのインスタンスが生成されます。

ここでは，JPAアプリケーションの作成について説明します。

＜この節の構成＞

6.12.1　エンティティクラスとデータベースの対応の定義

6.12.2　エンティティクラスの作成要件

6.12.3　エンティティクラスのフィールドに対するアクセス方法の指定

6.12.4　アクセサメソッドの作成

6.12.5　エンティティの永続化フィールドおよび永続プロパティの型

6.12.6　エンティティでのプライマリキーの指定

6.12.7　永続化フィールドおよび永続化プロパティのデフォルトマッピング規則

6.12.1　エンティティクラスとデータベースの対応の定義

エンティティクラスは，データベースのテーブルの行に対応します。また，エンティティクラスが保持するフィールドは，テーブルのカラムの値に対応します。ユーザがエンティティクラスのインスタンスに対してフィールドの値を更新すると，Cosminexus JPAプロバイダによって対応するデータベースのテーブルのカラムも更新されます。そのため，ユーザはデータベースに対してSQLを発行することなく，データベースの状態を変更できます。

エンティティクラスとデータベースのテーブルとのマッピングについて次の図に示します。

図6-22　エンティティクラスとデータベースのテーブルとのマッピング

エンティティのフィールドとデータベースのカラムの対応関係は，アノテーションまたはO/Rマッピングファイルで定義します。アノテーションとO/Rマッピングファイルのどちらでも定義はできます。ただし，両方で定義している場合は，O/Rマッピングファイルの設定がアノテーションよりも優先されます。アノテーションとO/Rマッピングファイルとで同じ設定項目に対して異なる値を設定している場合は，アノテーションの値をO/Rマッピングファイルの値で上書きします。

6.12.2　エンティティクラスの作成要件

JPAを使用したアプリケーションを作成する場合には，JPA仕様で決められたエンティティクラスの作成要件やデータベースのマッピング要件を守る必要があります。作成要件を次に示します。

エンティティクラスは@EntityまたはO/Rマッピングファイルの<entity>タグに指定する必要があります。

エンティティクラスは引数なしのコンストラクタを持ちます。

enumやインタフェースはエンティティクラスとしてはいけません。

エンティティクラスのクラス階層のルートとなるエンティティまたはマップドスーパークラスでは，プライマリキーを持つ必要があります。プライマリキーは，エンティティ階層で必ず一つ定義してください。

エンティティクラスのインスタンスを値渡しでメソッドの引数として渡す場合，Serializableインタフェースを実装する必要があります。

データベースのカラムの状態はエンティティのインスタンス変数で表現し，インスタンス変数はJavaBeanのプロパティに対応します。なお，インスタンス変数は，クライアントから直接アクセスして値を変更してはいけません。アクセサメソッド（getter／setterメソッド）や，ビジネスメソッド経由で値を変更してください。

エンティティの永続インスタンス変数は，private，protected，またはpackageから参照できるアクセスレベルにしてください。

引数なしのコンストラクタは，publicかprotectedで宣言してください。

エンティティクラスはfinalにしないでください。また，エンティティクラスの永続化インスタンス変数とすべてのメソッドもfinalにしてはいけません。

Cosminexus JPAプロバイダでは，これらの条件に合わない場合，例外が発生するおそれがあります。なお，例外が発生しない場合でもこれらの条件に合わないエンティティクラスを作成している場合の動作は保証しません。

また，Cosminexus JPAプロバイダの場合，エンティティクラスでは，データベースの一つのカラムを複数のフィールドに対応づけないでください。この条件に合わない場合，アプリケーション実行時に例外が発生することがあります。例外が発生しない場合でも，動作は保証しません。

6.12.3　エンティティクラスのフィールドに対するアクセス方法の指定

Cosminexus JPAプロバイダは，エンティティの状態をデータベースに書き込んだり，データベースの状態をエンティティとして読み込んだりするときに，エンティティクラスのフィールドにアクセスします。このときのアクセス方法をアクセスタイプと呼びます。アクセスタイプには，プロパティとフィールドの2種類があります。また，アクセスタイプはアノテーションまたはO/Rマッピングファイルで指定します。アクセスタイプと指定方法について次の表に示します。

表6-17　アクセスタイプと指定方法

アクセスタイプ | 説明 | 指定方法
アノテーション | O/Rマッピングファイル
プロパティ | getterメソッドを経由して取得する方法です。 | フィールドのgetterメソッドにアノテーションを指定します。 | <access>タグにPROPERTYを指定します。
フィールド | インスタンス変数を直接参照する方法です。 | フィールドにアノテーションを指定します。 | <access>タグにFIELDを指定します。

アクセスタイプがプロパティの場合，エンティティが保持するプロパティを永続化プロパティといいます。また，アクセスタイプがフィールドの場合，エンティティのフィールドを永続化フィールドといいます。

アクセスタイプに関連する注意事項

アクセスタイプを指定するときには，次の点を考慮してください。

アクセスタイプがフィールドの場合，Cosminexus JPAプロバイダは永続化フィールドに直接アクセスします。@Transientを設定されていないインスタンス変数は，永続化の対象となります。

アクセスタイプがプロパティの場合，Cosminexus JPAプロバイダはアクセサメソッドを利用して永続化プロパティの値を取得します。@Transientがアクセサメソッドに設定されていないプロパティは，永続化の対象となります。

アクセスタイプがプロパティの場合，setterメソッドにマッピングアノテーションは設定できません。Cosminexus JPAプロバイダの場合，setterメソッドに設定したマッピングアノテーションは無視されます。

@TransientまたはO/Rマッピングファイルで<transient>タグが付与されたフィールドとプロパティには，マッピングアノテーションは設定できません。設定した場合には，アプリケーションの開始時に例外が発生します。

プロパティのアクセサメソッドはpublicまたはprotectedにしてください。これは，JPA仕様で禁止されていますが，Cosminexus JPAではチェックしません。また，privateであっても例外も発生しません。

永続化フィールドと永続化プロパティのアクセサメソッドの両方にマッピングアノテーションが適用された場合，永続化プロパティのアクセサメソッドに設定されたアノテーションはすべて無視されます。

6.12.4　アクセサメソッドの作成

ここでは，アクセサメソッドのシグネチャ規則，およびアクセサメソッドへのビジネスロジックの追加について説明します。

＜この項の構成＞

(1)　アクセサメソッドのメソッドシグネチャ規則

(2)　アクセサメソッドへのビジネスロジックの追加

(1)　アクセサメソッドのメソッドシグネチャ規則

Cosminexus JPAプロバイダが永続化プロパティに対してアクセスする場合，プロパティのアクセサメソッドは，次に示すJavaBeansと同じメソッドシグネチャ規則に従っている必要があります。

T getProperty()

void setProperty(T t)

booleanの戻り値を返すプロパティの場合，getterメソッドはisPropertyという名前にすることもできます。なお，Cosminexus JPAプロバイダを使用する場合，getterメソッドとsetterメソッドのどちらかしかないときには，アプリケーション開始時に例外が発生します。

また，永続化フィールド，永続化プロパティでコレクション値を扱う場合は，次に示すコレクション値をインタフェースで定義してください。

java.util.Collection

java.util.Set

java.util.List

java.util.Map

永続化プロパティがコレクション値となる場合，アクセサメソッドのメソッドシグネチャはこれらのインタフェースのどれかにしてください。または，これらのコレクションのジェネリックな型を使用することもできます（例：Set<T>）。

(2)　アクセサメソッドへのビジネスロジックの追加

アクセサメソッドは，プロパティのsetter/getter処理に加えて，値を検証するなどのビジネスロジックを含むことができます。アクセスタイプがプロパティの場合，Cosminexus JPAプロバイダがアクセサメソッドを呼び出すタイミングでビジネスロジックが動作します。

ただし，この場合には，次の点に注意してください。

Cosminexus JPAプロバイダの実行時に，永続状態をロードして格納するアクセサメソッドが呼び出される順番は定義されていません。このため，getterに含まれるロジックの実行順序は未定となります。

アクセスタイプがプロパティで，永続化プロパティでlazyフェッチが指定されている場合で，移植性を求めるには，エンティティの内容がCosminexus JPAプロバイダにフェッチされるまで，エンティティの内容にアクセスしないことをお勧めします。

アクセスタイプがプロパティの場合で，ビジネスロジックとして値を変更するロジックを追加したときには，Cosminexus JPAプロバイダではデータの一貫性は保証しません。

プロパティアクセサメソッドでRuntime例外が発生すると，現在のトランザクションはロールバックにマークされます。Cosminexus JPAプロバイダがエンティティの永続状態の内容を読み込んだり，格納する際のアクセサメソッドで例外が発生したりした場合，トランザクションはロールバックされます。また，アプリケーション例外をラップするPersistenceException例外が発生します。

6.12.5　エンティティの永続化フィールドおよび永続プロパティの型

エンティティの永続化フィールド／永続化プロパティは，次に示す型にしてください。

Javaのプリミティブ型

java.lang.String

ほかのシリアライズ型

プリミティブ型のラッパークラス

java.math.BigInteger

java.math.BigDecimal

java.util.Date

java.util.Calendar

java.sql.Date

java.sql.Time

java.sql.Timestamp

ユーザが定義するシリアライズな型

byte[]

Byte[]

char[]

Character[]

enum

エンティティタイプとエンティティタイプで複製できるコレクション

埋め込みできるクラス

Cosminexus JPAプロバイダを使用する場合は，上記以外の型が指定されたときの動作は保証しません。アプリケーションの実行時に例外が発生するおそれもあります。

ただし，Cosminexus JPAプロバイダを使用している場合，エンティティのインスタンス変数の型は，データベースのカラムの型と対応づけしている必要があります。Javaの型とデータベースの型の対応づけは，JDBCドライバが行います。Cosminexus JPAプロバイダでは，Oracle接続時にはOracleが提供するOracle JDBC Thin DriverをJDBCドライバとして利用します。HiRDB接続時にはHiRDB Type4 JDBC DriverをJDBCドライバとして利用します。ユーザはJDBCドライバがサポートする型の変換に合わせてエンティティのインスタンス変数の型を決定してください。

6.12.6　エンティティでのプライマリキーの指定

エンティティでは，プライマリキーをクラス階層の中で必ず指定してください。プライマリキーを指定する場合には，次に示すルールに従ってください。

単体の（複合型でない）プライマリキーは，永続化フィールドまたは永続化プロパティに@Idを指定するか，O/Rマッピングファイルで指定します。これによって，エンティティのフィールドとの対応づけをしてください。

複合型のプライマリキーの場合，@EmbeddedIdとして単一のフィールドでプライマリキークラスを指定するか，または@IdClassと@Idによって，フィールドのセットとして複合プライマリキーを指定します。

複合型のプライマリキーの場合，プライマリキークラスと呼ばれるプライマリキーを含むクラスを作成します。

これらの条件に従っていない場合は，アプリケーション開始時に例外が発生します。

また，アプリケーションでエンティティのプライマリキーの値を変更しないでください。アプリケーションでプライマリキーの値を変更した場合，実行時に例外が発生します。

＜この項の構成＞

(1)　プライマリキーの型

(2)　複合型のプライマリキー

(3)　埋め込み型クラス

(1)　プライマリキーの型

単体または複合型のプライマリキーは，次に示す型のどれかにしてください。

Javaのプリミティブ型

プリミティブをラッパした型

java.lang.String

java.util.Date

java.sql.Date

なお，近似値型（例えば浮動小数点数型）をプライマリキーとして指定すると，Cosminexus JPAプロバイダの場合，丸め誤差が発生したり，equalsメソッドの結果に信頼性がないという問題が発生したりします。このため，Cosminexus JPAプロバイダではプライマリキーに近似値型を使用した場合の動作は保証しません。java.util.Dateがプライマリキーとしてフィールド／プロパティで使用される場合，temporal type属性はDATE型として指定する必要があります。

(2)　複合型のプライマリキー

エンティティでは複合型のプライマリキーを扱うことができます。エンティティで複合型のプライマリキーを指定するには，埋め込み型クラスを利用する方法と@IdClassを利用する方法の2とおりがあります。それぞれの方法を説明します。

(a)　埋め込み型クラスを利用する方法

埋め込み型クラスを利用するには，@Embeddableを付与したクラスを作成し，そのクラスのフィールドとして複合型のプライマリキーを定義します。エンティティクラスでは，@Embeddableを付与したクラスの型のフィールドを定義して，@EmbeddedIdをアノテートします。エンティティクラスの例と埋め込み型クラスの例を次に示します。

エンティティクラスの例

@Entity
public class Employee {
   private EmployeePK employeePK;

   public Employee(){
   }

   @EmbeddedId
   public EmployeePK getEmployeePK(){
     retrun this.employeePK;
   }

   public void setEmployeePK(EmployeePK employeePK){
     this.employeePK = employeePK;
   }
   ・・・
}

埋め込み型クラスの例

@Embeddable
public class EmployeePK {
   private String name;
   private int employeeId;

   public EmployeePK(){
   }

   public boolean equals(Object obj){
     ・・・
   }

   public int hashCode(){
     ・・・
   }
   ・・・
}

埋め込み型クラスについては「(3)　埋め込み型クラス」を参照してください。なお，アノテーションの代わりにO/Rマッピングファイルを利用することもできます。

(b)　@IdClassを利用する方法

@IdClassを利用するには，エンティティクラスでプライマリキーに対応する複数のインスタンス変数を定義して@Idを付与します。また，@IdClassを使用してプライマリキークラスを指定します。プライマリキークラスでは，エンティティで定義したプライマリキーと同じ名前と型を持つフィールドまたはプロパティを定義します。エンティティクラスの例とプライマリキークラスの例を次に示します。

エンティティクラスの例

@Entity
@IdClass(EmployeePK.class)
public class Employee {
   private String name;
   private int employeeId;

   public Employee(){
   }

   @Id
   public String getName(){
     retrun this.name;
   }

   public void setName(String name){
     this.name = name;
   }

   @Id
   public int getEmployeeId(){
     retrun this.employeeId;
   }

   public void setName(int employeeId){
     this.employeeId = employeeId;
   }
   ・・・
}

プライマリキークラスの例

public class EmployeePK implements Serializable {
   private String name;
   private int employeeId;

   public EmployeePK(){
   }

   public boolean equals(Object obj){
     ・・・
   }

   public int hashCode(){
     ・・・
   }
   ・・・
}

埋め込み型クラスの場合と同様に，アノテーションの代わりにO/Rマッピングファイルを利用することもできます。なお，プライマリキークラスのアクセスタイプは，プライマリキーに対応するエンティティクラスのアクセスタイプで決定します。

複合型のプライマリキーを扱うためには，埋め込み型クラスまたは@IdClassのどちらかを使用します。ただし，次に示すルールに従ってください。

プライマリキークラスは，publicで引数のないコンストラクタを持たなければならなりません。

永続化プロパティを使用する場合，プライマリキークラスのプロパティはpublicまたはprotectedにしてください。

プライマリキークラスは，直列化可能にしてください。

プライマリキークラスではequalsとhashCodeメソッドを定義します。マップされているデータベース上で主キーが等しい場合にはequalsでtrueを返し，hashCodeの値を等しくする必要があります。

複合プライマリキーは，埋め込みクラスとしてマップされているか，エンティティクラスの複数のフィールド／プロパティをマップされている必要があります。

プライマリキークラスがエンティティクラスの複合フィールド／プロパティにマップされる場合，プライマリキークラスのプライマリキーのフィールド／プロパティの名前と，エンティティクラスの名前を一致させてください。また，型も同じにしてください。

Cosminexus JPAプロバイダでは，これらの条件を満たさない場合動作は保証しません。また，条件を満たさない場合はアプリケーションの開始時に例外が発生することもあります。

(3)　埋め込み型クラス

永続化対象の幾つかのフィールドをまとめたクラスを用意すると，エンティティのフィールドとして保持できます。このようなクラスを埋め込み型クラスといいます。

埋め込み型クラスは，エンティティに埋め込まれてエンティティと同じデータベースのテーブルにマップされます。このため，エンティティとは異なり，プライマリキーを持ちません。

ユーザが埋め込み型クラスを利用する場合，埋め込むクラスには@Embeddableを設定します。また，埋め込まれる側のエンティティクラスでは，埋め込み先のフィールド，プロパティに@Embeddedを指定します。なお，アノテーションの代わりにO/Rマッピングファイルで同様に定義することもできます。

埋め込み型クラスは複合型のプライマリキーを定義するために利用することもできます。この場合，埋め込まれるエンティティクラスでは，@Embeddedの代わりに@EmbeddedIdを設定します。

埋め込み型クラスでは，次に示す作成要件を必ず守ってください。

埋め込み型クラスは，必ず@Embeddableで定義するか，O/Rマッピングファイルの<embeddable>タグで定義してください。

enumやインタフェースを埋め込み型クラスとしないでください。

埋め込み型クラスを含むエンティティクラスをdetachedオブジェクトとして値渡ししている場合，Serializableインタフェースを実装してください。

埋め込み型クラスおよび埋め込み型クラスの永続化インスタンス変数と，すべてのメソッドではfinalにしないでください。

引数なしのコンストラクタを持つ必要があります。

引数なしコンストラクタは，publicかprotectedで宣言してください。

埋め込み型クラスのインスタンス変数は，private，protected，またはpackageから参照できなければなりません。

埋め込み型クラスの永続化インスタンス変数は，クライアントから直接アクセスされないようにしてください。エンティティのアクセサメソッド（getter／setterメソッド）や，ほかのビジネスメソッドでアクセスしないでください。

Cosminexus JPAプロバイダでは，1.および2.の条件を満たさない場合には例外が発生して，アプリケーションの開始に失敗します。また，3.から8.についても例外が発生するおそれがありますが，例外が発生しない場合でも動作は保証しません。

埋め込み型クラスのアクセスタイプは，埋め込まれた側のエンティティクラスのアクセスタイプで決定します。

埋め込み型クラスを利用する場合，埋め込みの階層は一つにしてください。また，複数のエンティティから埋め込み型クラスのオブジェクトを共有することはできません。これらの条件を満たさない場合，Cosminexus JPAプロバイダでは動作を保証しません。

6.12.7　永続化フィールドおよび永続化プロパティのデフォルトマッピング規則

リレーションシップ以外の永続化フィールドまたは永続化プロパティに対して，O/Rマッピング情報が指定されていない場合は，次に示すデフォルトのマッピング規則が適用されます。

@Embeddableがアノテートされたクラスの場合，フィールド／プロパティは@Embedded側のエンティティでの指定に従ってデータベースにマップされます。

永続化フィールド／永続化プロパティの型が次のどれかである場合，@Basicが定義されているのと同じ方法でマップされます。

Javaのプリミティブ型

プリミティブ型のラッパ

java.lang.String

java.math.BigInteger

java.math.BigDecimal

java.util.Date

java.util.Calendar

java.sql.Date

java.sql.Time

java.sql.Timestamp

byte[]

Byte[]

char[]

Character[]

enum

Serializableを実装した任意の型

なお，上記以外の型が指定されている場合の動作は保証しません。

6.13　エンティティクラスの継承方法

エンティティクラスの継承には次に示す特長があります。

エンティティクラスは抽象クラス，具象クラスのどちらでも使用できます。抽象クラスおよび具象クラスともに，@Entityが定義できます。また，エンティティとしてマップでき，抽象クラスおよび具象クラスの両方に対してクエリを発行できます。

エンティティクラスはほかのエンティティクラスから継承できます。

エンティティクラスは非エンティティクラスを継承できます。また，非エンティティクラスはエンティティクラスを継承できます。

ここでは，エンティティクラスの継承クラスの種類と継承マッピング戦略について説明します。

＜この節の構成＞

6.13.1　継承クラスの種類

6.13.2　継承マッピング戦略

6.13.1　継承クラスの種類

エンティティクラスの継承クラスの種類には，抽象エンティティクラス，マップドスーパークラス，および非エンティティクラスがあります。それぞれ説明します。

＜この項の構成＞

(1)　抽象エンティティクラス

(2)　マップドスーパークラス

(3)　エンティティ継承階層構造の非エンティティのクラス

(1)　抽象エンティティクラス

抽象クラスはエンティティクラスとして定義できます。抽象エンティティクラスは，直接インスタンスを作成できない点が具象エンティティクラスとは異なります。抽象エンティティクラスは，エンティティとしてマップすることも，サブクラスのエンティティを操作・取得するためにクエリの対象に指定することもできます。

サブクラスでは，プロパティのアクセサメソッドをオーバーライドできます。ただし，永続化フィールドおよび永続化プロパティのO/Rマッピング情報をサブクラスでオーバーライドした場合，動作は保証しません。サブクラスでO/Rマッピング情報をオーバーライドする場合は，@AssociationOverrideや@AttributeOverrideなどを使用してください。

抽象エンティティクラスは，@EntityまたはO/Rマッピングファイルで指定します。

(2)　マップドスーパークラス

マップドスーパークラスとは，エンティティクラスのスーパークラスになることができるクラスです。永続化フィールドやマッピング情報を定義でき，さらにこれらを継承するような構成にできます。

マップドスーパークラスは，特定のテーブルを指定できないため，@Tableの指定はできません。そのため，マップドスーパークラスをエンティティにすることはできません。マップドスーパークラスはエンティティクラスとは異なり，問い合わせができないため，EntityManagerやクエリの操作の引数に渡すこともできません。また，リレーションシップの対象にすることもできません。

マップドスーパークラスは，抽象クラスとしても，具象クラスとしても定義できます。クラスをマップドスーパークラスとして定義する場合は，@MappedSuperclass，またはO/Rマッピングファイルに<mapped-superclass>タグを定義します。マッピング情報は，継承されたエンティティクラスに対して提供されます。

マップドスーパークラスとして設計したクラスは，マッピングがサブクラスにだけ提供できるマッピングであることを除いて，エンティティクラスと同様の方法でマップできます。

エンティティがサブクラスとして適用されると，マップドスーパークラスで指定された情報が，サブクラスに継承されます。@AssociationOverrideやO/Rマッピングファイルで対応するXML要素を使用して，マッピング情報をサブクラス上でオーバーライドすることができます。

(3)　エンティティ継承階層構造の非エンティティのクラス

エンティティクラスは非エンティティクラスのスーパークラスを持つことができます。スーパークラスは具象クラスおよび抽象クラスとして定義できます。

非エンティティクラスのスーパークラスには次に示す特長があります。

振る舞いだけを継承します。

状態は永続ではありません。

継承したすべての状態は，継承したエンティティクラスでも永続ではありません。

永続でない状態は，EntityManagerの制御の対象ではありません。

スーパークラスのアノテーションは無視されます。

非エンティティクラスをEntityManagerやQueryインタフェースのメソッドの引数にしたり，マッピング情報にしたりしないでください。Cosminexus JPAプロバイダの場合，アプリケーションの実行時に例外が発生します。

6.13.2　継承マッピング戦略

エンティティを継承した場合，クラス階層をテーブルにマッピングする方法を継承マッピング戦略として指定できます。継承マッピング戦略は，@InheritanceまたはO/Rマッピングファイルの<entity>タグの<inheritance>タグを使用して指定します。

継承マッピング戦略には次の3種類があります。

SINGLE TABLE戦略
SINGLE TABLE戦略は，エンティティクラスの継承階層にあるすべてのクラスが一つのテーブルにマップする戦略方法です。

JOINED戦略
JOINED戦略は，クラス階層の最上位は単一のテーブルにマップする戦略方法です。

TABLE PER CLASS戦略
エンティティクラスのクラス階層中の各クラスを別々のテーブルにマップする戦略方法です。

ただし，Cosminexus JPAプロバイダでは，TABLE PER CLASS戦略は使用できません。Cosminexus JPAプロバイダを使用している場合で，TABLE PER CLASS戦略を指定したときには，アプリケーションの起動時に例外が発生します。

注意

Cosminexus JPAプロバイダを使用する場合，次のことに注意してください。

クラス階層中で継承戦略を複数組み合わせて指定することはできません。また，複数の継承戦略を組み合わせているかどうかのチェックも実施しません。指定した場合の動作は保証しません。

@DiscriminatorColumnで指定したカラムをエンティティのフィールドに定義した場合，persist操作をしてコミットしてもエンティティのフィールドに設定した値はデータベースに反映されません。@DiscriminatorValueで指定した値またはそのデフォルト値が反映されます。また，コミット後には，コミット前にフィールドに設定されていた値が格納されたままとなるため注意が必要です。

これらはjavax.persistence.DiscriminatorType列挙型の値で指定されます。それぞれの戦略について説明します。

＜この項の構成＞

(1)　SINGLE TABLE戦略

(2)　JOINED戦略

(1)　SINGLE TABLE戦略

SINGLE TABLE戦略とは，エンティティクラスの継承階層にあるすべてのクラスが一つのテーブルにマップする戦略方法です。そのため，テーブルではクラスを識別するためのカラムとして，識別カラムを持つ必要があります。

識別カラムは@DiscriminatorColumn，またはO/Rマッピングファイルで指定します。なお，デフォルトの識別カラム名は「DTYPE」です。データベースに識別カラムがない場合，アプリケーションの実行時に例外が発生します。

識別カラムに格納される値を指定したい場合には，@DiscriminatorValueまたはO/Rマッピングファイルの<entity>タグ下の<discriminator-value>タグを使用して指定します。

注意

SINGLE TABLE戦略を利用する場合，サブクラスのフィールドに対応するテーブルのカラムでは，null値を指定できるようにする必要があります。

(2)　JOINED戦略

JOINED戦略とは，クラス階層の最上位は単一のテーブルにマップする戦略方法です。各サブクラスは，スーパークラスから継承されていないサブクラス特有のフィールドと，スーパークラス表の主キーの外部キーとして機能する主キー列を持つ別々のテーブルで示されます。

JOINED戦略の場合も，SINGLE TABLEの場合と同様にスーパークラスがマップされるテーブルに識別カラムを持つ必要があります。

注意

JOINED戦略を利用する場合，サブクラスのインスタンスの生成で複数回の結合の実行が必要になります。このため，階層構造が深くなると，性能が劣化するおそれがあります。また，クラス階層にわたる範囲でクエリを発行する場合，JOINが必要です。

6.14　EntityManagerおよびEntityManagerFactoryの使用方法

ここでは，アプリケーションから利用するEntityManagerおよびEntityManagerFactoryの使用方法について説明します。

＜この節の構成＞

6.14.1　EntityManagerでのエンティティのライフサイクル管理

6.14.2　EntityManagerおよびEntityManagerFactoryの設定方法

6.14.3　EntityManagerのAPIに関する注意事項

6.14.1　EntityManagerでのエンティティのライフサイクル管理

EntityManagerはデータベースに対して次の操作をするためのインタフェースを持つオブジェクトです。

エンティティを登録したり，削除したりする。

プライマリキーによってエンティティを検索する。

エンティティをわたったクエリを発行する。

EntityManagerに対してエンティティを登録すると，トランザクションのコミットなどの適切なタイミングでエンティティの状態がデータベースで永続化されます。

また，EntityManagerはエンティティの集合を表す永続化コンテキストと関連を持ちます。EntityManagerにエンティティが登録されると，エンティティは特定の永続化コンテキストに属します。また，EntityManagerは，エンティティのライフサイクルを管理します。

EntityManagerで管理するエンティティの集合は永続化ユニットという単位で定義します。永続化ユニットはアプリケーションの設定ファイルであるpersistence.xmlで定義します。

永続化コンテキストと永続化ユニットの注意事項について説明します。

永続化コンテキスト内ではエンティティは一意となるようにします。このため，同一の永続化コンテキスト内では，データベースの同じ行を表すエンティティは一つとしてください。なお，永続化コンテキストが異なる場合は，データベースの同じ行を表すエンティティを複数持つことができます。この場合のデータベース上での排他方法については，「6.10　楽観的ロック」または「6.11　JPQLでの悲観的ロック」を参照してください。

永続化ユニットはそれぞれ単一のデータベースにマッピングされます。定義の詳細については，「5.8　persistence.xmlでの定義」を参照してください。

6.14.2　EntityManagerおよびEntityManagerFactoryの設定方法

アプリケーションで利用するEntityManagerおよびEntityManagerFactoryは，アノテーションまたはDDで設定します。

EntityManagerFactoryの設定

アノテーションの場合：@PersistenceUnitで設定します。

DDの場合：<persistence-unit-ref>タグで設定します。

EntityManagerの設定

アノテーションの場合：@PersistenceContextで設定します。

DDの場合：<persistence-context-ref>タグで設定します。

なお，アノテーションの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス API編」の「2.　アプリケーションサーバが対応しているアノテーションおよびDependency Injection」を参照してください。また，DDに設定するタグの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」を参照してください。

6.14.3　EntityManagerのAPIに関する注意事項

EntityManagerが提供するAPIについての注意事項を次に示します。なお，EntityManagerのAPIについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス API編」の「2.6　javax.persistenceパッケージ」を参照してください。

トランザクションスコープ永続化コンテキストのEntityManagerが使用されるとき，persist，merge，remove，refreshメソッドは，トランザクションコンテキスト内で実行する必要があります。トランザクションコンテキストがない場合は，javax.persistence.TransactionRequiredExceptionがスローされます。

findメソッドとgetReferenceメソッドは，トランザクションコンテキストでの実行を要求しません。このため，トランザクションスコープ永続化コンテキストのEntityManagerが使用された場合，結果のエンティティはdetached状態になります。また，拡張された永続化コンテキストのEntityManagerが使用された場合，結果のエンティティはmanaged状態になります。

createQueryメソッドの引数が有効なJPQLの文字列でなければ，IllegalArgument例外を送出し，クエリの実行が失敗します。

実行するネイティブクエリが，接続先のデータベースの仕様に合わない場合，または定義された結果のセットがクエリの結果と互換性がない場合，クエリの実行は失敗し，クエリの実行時にPersistenceExceptoin例外がスローされます。

EntityManagerインタフェースのメソッドからランタイム例外が送出されると，カレントのトランザクションはロールバックにマークされます。

EntityManagerから取得したQueryオブジェクト，およびEntityTransactionオブジェクトは，EntityManagerがオープンしている間は有効です。

6.15　コールバックメソッドの指定方法

エンティティのライフサイクルを受け取るために，メソッドをライフサイクルのコールバックメソッドに指定できます。コールバックメソッドとして定義されたメソッドは永続化に関するライフサイクルイベントに対応して呼び出されます。

ここでは，コールバックメソッドの指定個所，実装方法，および呼び出し順序について説明します。

＜この節の構成＞

6.15.1　コールバックメソッドの指定個所

6.15.2　コールバックメソッドの実装

6.15.3　コールバックメソッドの呼び出し順序

6.15.1　コールバックメソッドの指定個所

コールバックメソッドは，次の場所に指定できます。

エンティティクラスまたはマップドスーパークラス内

エンティティクラスまたはマップドスーパークラスに関連づけられたエンティティリスナクラス

エンティティリスナクラスとは，コールバックメソッドを実装するための専用のクラスです。エンティティリスナクラスを使用すると，コールバックメソッドの実装部分を分離できます。

コールバックメソッドは，アノテーションまたはO/Rマッピングファイルで指定します。ただし，デフォルトのコールバックメソッドは，O/Rマッピングファイルで指定します。アノテーションでは指定できません。なお，デフォルトのコールバックメソッドとは，永続化ユニット内のすべてのエンティティに適用されるエンティティリスナを指します。

コールバックリスナの指定方法について説明します。

＜この項の構成＞

(1)　アノテーションでのコールバックメソッドの指定

(2)　O/Rマッピングファイルでのコールバックリスナの指定

(1)　アノテーションでのコールバックメソッドの指定

コールバックメソッドの指定にアノテーションを使用する場合は，次の表にあるアノテーションをメソッドに設定してください。ライフサイクルイベントに応じてメソッドを呼び出すことができます。

表6-18　アノテーションを使用したコールバックメソッドの指定

アノテーション
実行される内容

@PostLoad
エンティティが永続化コンテキストにロードされたあとか，またはrefresh操作が適用されたあとに，コールバックメソッドが実行されます。キャッシュからエンティティを読み込んだあと，またはデータベースにSELECT文を発行したタイミングで実行されます。

@PrePersist
@PreRemove
EntityManagerがエンティティのpersistまたはremove操作を行う前にコールバックメソッドが呼び出されます。マージ操作が適用され，新しくmanaged状態のインスタンスが作成される場合，managed状態のインスタンスへのPrePersistコールバックメソッドは，エンティティの状態がコピーされたあとに呼び出されます。これらのPrePersistまたはPreRemoveのコールバックは操作がカスケードされるすべてのインスタンスに対しても呼び出されます。PrePersistまたはPreRemoveメソッドは常にpersist，merge，またはremove操作の一部として同期を取って呼び出されます。

@PostPersist
@PostRemove
PostPersistおよびPostRemoveコールバックメソッドは，エンティティがpersistまたはremove操作で，永続化されたあとまたは削除されたあとで呼び出されます。
これらのコールバックは操作がカスケードされたすべてのエンティティに対しても呼び出されます。PostPersistまたはPostRemoveメソッドは，それぞれデータベースのinsertまたはdelete操作が行われたあとに呼び出されます。これらのデータベースへの操作はpersist，merge，もしくはremove操作の直後，またはflushメソッドが呼び出されたあとになります。ただし，トランザクションの終了時になることもあります。生成されたプライマリキーはPostPersistメソッドで利用できます。

@PreUpdate
@PostUpdate
PreUpdateおよびPostUpdateのコールバックはそれぞれエンティティデータのデータベースへのupdate操作の前後に呼び出されます。
これらのデータベースへの操作はエンティティの状態が更新された場合，または状態がデータベースにフラッシュされた場合に実行されます。ただし，データベースへの操作は，トランザクションの終了時になることもあります。一つのトランザクション内で，エンティティを永続化してから更新したり，エンティティを更新してから削除したりした場合には，PreUpdateやPostUpdateのコールバックが発生しないことがあります。

エンティティリスナクラスを利用する場合，エンティティに対して@EntityListenerを指定してエンティティリスナクラスを指定する必要があります。指定方法の例を次に示します。

@Entity
@EntityListeners(CallbackListener.class)
public class Employee implements Serializable{
・・・
}

(2)　O/Rマッピングファイルでのコールバックリスナの指定

O/Rマッピングファイルを使用してコールバックメソッドを指定する場合は次のように指定します。

エンティティリスナのクラスおよびそのクラスのコールバックメソッドを指定する場合，O/Rマッピングファイルの<entity-listener>タグを使用します。ライフサイクルリスナメソッドは，<entity-listener>タグ下の，<pre-persist>タグ，<post-persist,>タグ，<pre-remove>タグ，<post-remove>タグ，<pre-update>タグ，<post-update>タグ，および<post-load>タグを使用して指定します。

エンティティリスナクラスのコールバックメソッドを指定する場合は，コールバックイベントごとに最大一つのメソッドを<entity-listener>タグ以下のタグを使用して指定できます。

<persistence-unit-defaults>タグの<entity-listeners>タグの下位タグに対して，O/Rマッピングファイルの<entity-listener>タグを指定するとデフォルトコールバックメソッドが指定できます。

<entity>タグまたは<mapped-subclass>タグにある<entity-listeners>タグの下位タグに，<entity-listener>タグを指定すると，エンティティまたはマップドスーパークラスとそのサブクラスに対するコールバックリスナの指定になります。

<entity-listeners>タグに指定したリスナの順番でコールバックリスナは呼び出されます。リスナの呼び出し順序については，「6.15.3　コールバックメソッドの呼び出し順序」を参照してください。

6.15.2　コールバックメソッドの実装

ユーザは必要に応じてコールバックメソッドを実装します。エンティティクラスやマップドスーパークラス内に実装するコールバックメソッドとエンティティリスナクラスのコールバックメソッドでコールバックメソッドのシグネチャは異なります。

エンティティクラスやマップドスーパークラスで定義されるコールバックメソッドは次に示すシグネチャになります。

void <METHOD>

また，エンティティリスナクラスで定義されるコールバックメソッドは次に示すシグネチャになります。

void <METHOD>(Object)

引数のObjectには，コールバックメソッドが実行されるエンティティのインスタンスを指定します。

＜この項の構成＞

(1)　コールバックメソッド使用時の注意事項

(2)　コールバックメソッドに適用されるルール

(1)　コールバックメソッド使用時の注意事項

コールバックメソッドについては，次に示す注意事項があります。これらの条件を満たさない場合，アプリケーションの開始時に例外が発生して，アプリケーションの開始に失敗します。

publicで引数がないコンストラクタを持たなければなりません。

コールバックメソッドではpublic，private，protected，およびパッケージレベルのアクセスができます。ただし，staticやfinalは使用できません。

一つのクラスが同じライフサイクルイベントに対して複数のライフサイクルコールバックメソッドを持つことはできません。ただし，同じメソッドが複数のコールバックイベントで使用されることがあります。

(2)　コールバックメソッドに適用されるルール

コールバックメソッドについては次に示すルールが適用されます。

コールバックメソッドでは，未チェックまたは実行時例外の送出が許可されています。トランザクション中に実行したコールバックメソッドでスローされた実行時例外は，トランザクションをロールバックさせます。コールバックメソッドが複数指定されている場合，実行時例外がスローされたあとには残りのコールバックメソッドは実行されません。

コールバックメソッドでは，JNDI，JDBC，JMS，Enterprise Beanを実行できます。

コールバックメソッドで次の操作をしないでください。

EntityManagerを呼び出す。

クエリ操作を実行する。

ほかのエンティティインスタンスにアクセスする。

リレーションシップを更新する。

このような方法で使用した場合，動作を保証しません。

Java EE環境でコールバックメソッドが呼び出された場合，エンティティのコールバックリスナは呼び出すコンポーネントのネーミングコンテキストを共有します。また，エンティティのコールバックメソッドは，コールバックメソッドが呼び出された時点の呼び出し元コンポーネントのトランザクションとセキュリティコンテキストで呼び出されます。

6.15.3　コールバックメソッドの呼び出し順序

エンティティに対して複数のコールバックメソッドを定義した場合，呼び出し順序は次の規則に従います。

O/Rマッピングファイルに定義した順番でデフォルトリスナが呼び出されます。
明示的に@ExcludeDefaultListenersまたはO/Rマッピングファイルの<exclude-default-listeners>タグを指定しないかぎり，デフォルトリスナは永続化ユニット内のすべてのエンティティに適用されます。

@EntityListenersで指定された順番にコールバックメソッドが呼び出されます。
なお，O/Rマッピングファイルを使用すると，次の操作ができます。

エンティティに対するコールバックメソッドの呼び出し順序を指定する。

アノテーションでの指定順序をオーバーライドする。

エンティティ（またはマップドスーパークラス）に指定されたコールバックメソッドが呼び出されます。

＜この項の構成＞

(1)　継承階層内での呼び出し順序

(2)　コールバックメソッドの除外について

(1)　継承階層内での呼び出し順序

エンティティクラスやマップドスーパークラスの継承階層の中で複数回のエンティティリスナを定義した場合，呼び出し順序は次のようになります。

デフォルトコールバックリスナがあれば，最初に呼び出されます。

エンティティリスナクラスのコールバックメソッドがスーパークラスに指定されているリスナから順番に呼び出されます。このとき，@EntityListenerなどの指定があれば，その順序に従います。

すべてのエンティティリスナのコールバックメソッドが呼び出されたあとで，エンティティ（またはマップドスーパークラス）に定義されたコールバックメソッドがスーパークラスに指定されているリスナから順番に呼び出されます。

コールバックメソッドをサブクラスでオーバーライドした場合には，オーバーライドされたメソッドは呼び出されません。オーバーライドしたコールバックメソッドが異なるライフサイクルのイベントを指定している場合，またはライフサイクルコールバックメソッドではない場合，オーバーライドされた側のメソッドは呼び出されます。また，メソッドのコールバックメソッドの設定はオーバーライドされます。

(2)　コールバックメソッドの除外について

@ExcludeDefaultListenersまたはO/Rマッピングファイルの<exclude-default-listeners>タグを指定すると，デフォルトエンティティリスナはエンティティクラス（またはmapped superclass）とそのサブクラスでは呼び出されません。

@ExcludeSuperclassListenersまたはO/Rマッピングファイルの<exclude-superclass-listeners>タグがエンティティクラスやmapped superclassに適用されると，そのクラスとそのサブクラスではリスナのコールバックメソッドは呼び出されません。@ExcludeSuperclassListenersまたはO/Rマッピングファイルの<exclude-superclass-listeners>タグは，デフォルトのエンティティリスナの呼び出しを除外することにはなりません。

O/Rマッピングファイルを使用して，entityやmapped superclassへの除外されたデフォルト/スーパークラスリスナを明示的に指定すると，エンティティやそのサブクラスに適用されることになります。

6.16　クエリ言語を利用したデータベースの参照および更新方法

クエリとは，データベースに対する処理要求（問い合わせ）を文字列として表したものです。データベース上のデータの検索，更新，削除などの命令をシステムに発行するときに使用します。クエリを実行するには，javax.persistence.Queryインタフェースを使用します。クエリには，JPQLとネイティブクエリの2種類があります。ここでは，クエリを利用したデータベースの参照および更新方法について説明します。

＜この節の構成＞

6.16.1　JPQLでのデータベースの参照および更新方法

6.16.2　ネイティブクエリでのデータベースの参照および更新方法

6.16.3　クエリ結果件数の範囲指定

6.16.4　フラッシュモードの指定

6.16.5　クエリヒントの指定

6.16.6　クエリの実行時の注意事項

6.16.1　JPQLでのデータベースの参照および更新方法

JPQLは，データベースを検索・更新したり，データベースが持っている集合関数などの機能を利用したりするためのクエリ言語です。SQLがテーブルを対象としたクエリ言語であるのに対して，JPQLはエンティティクラスを対象としたJPA仕様で定義されているクエリ言語です。

クエリはアノテーションまたはO/Rマッピングファイルで定義できます。クエリと同じ永続化ユニットでエンティティが定義されている場合，エンティティの集合を表す抽象スキーマ型をクエリで使用できます。また，パス式を使用すると，永続化ユニット内で定義されたリレーションシップをわたってクエリを使用できます。パス式の詳細については，「6.17.4(2)　パス式」を参照してください。

アプリケーションにJPQLを記述して実行すると，次の順序で接続先のデータベースに対してSQLが発行されます。

JPQLが実行されると，Cosminexus JPAプロバイダによってJPQLの内容が解釈される。

対象となるエンティティクラス内に記述されたアノテーションやO/Rマッピングファイルの情報を基に，接続先のデータベース製品固有のSQL文に組み立てて発行する。

ここでは，JPQLの使用方法について説明します。

＜この項の構成＞

(1)　Queryオブジェクトの取得方法

(2)　パラメタの指定方法

(3)　クエリ結果の取得および実行

(1)　Queryオブジェクトの取得方法

JPQLを使用してQueryオブジェクトを取得するためには，Cosminexus JPAプロバイダが提供する次のEntityManagerインタフェースのメソッドを使用します。EntityManagerインタフェースのメソッドについて説明します。

(a)　Query createQuery(String JPQL文)

createQueryの記述例を次に示します。引数には実行するJPQL文を指定します。

Query q = em.createQuery(
                  "SELECT c  " +
                  "FROM Customer c " +
                  " WHERE c.name LIKE "Smith");

(b)　Query createNamedQuery(String クエリ名)

あらかじめ名前を付けて定義しておくことのできるクエリを名前付きクエリといいます。名前付きクエリは，@NamedQueryを任意のエンティティクラスに付与して定義します。@NamedQueryのname属性にクエリ名を指定して，query属性にはJPQL文を指定します。

Cosminexus JPAプロバイダの場合，同じ名称の名前付きクエリを複数指定することはできません。同じ名称の名前付きクエリを複数指定した場合には，警告メッセージKDJE55535-Wを出力します。Cosminexus JPAプロバイダで指定した場合，どのクエリが動作するかは保証しません。

次に，@NamedQueryの定義例を示します。この例では，@NamedQueryを使用してあらかじめfindAllCustomersWithNameという名前でクエリを登録しています。アプリケーションのcreateNamedQueryメソッドに登録した名前付きクエリ名を渡すことで，事前に登録されているクエリを取得して利用します。

@NamedQueryでのクエリ名の登録

@NamedQuery(
     name="findAllCustomersWithName",
     query="SELECT c FROM Customer c WHERE c.name LIKE :custName"
)
@Entity
public class Customer {
・・・
}

createNamedQueryメソッドでの名前付きクエリの記述例

@Stateless
public class MySessionBean {
・・・
 @PersistenceContext
 public EntityManager em;
 ・・・
 public void doSomething() {
   ・・・
   Query q = em.createNamedQuery("findAllCustomersWithName")
                                    .setParameter("custName", "Smith");
 }
}

なお，同一の永続化ユニット内では，ほかのエンティティで定義した名前付きクエリを使用することもできます。

(2)　パラメタの指定方法

JPQLでは，クエリを生成する際に，WHERE節に記述する条件式にパラメタを使用して，動的に値を設定することができます。パラメタの値はQueryインタフェースのsetParameterメソッドで設定します。パラメタには，位置パラメタと名前付きパラメタがあります。それぞれについて説明します。

位置パラメタ

WHERE節の中のパラメタを組み込みたい位置に，「?」と数値の組み合わせを記述します。パラメタの値は，QueryインタフェースのsetParameterメソッドで設定します。位置パラメタの記述形式と記述例を次に示します。

記述形式

Query setParameter(int 位置, Object 値)

記述例

Query q = em.createQuery(
       "SELECT c FROM Customer c WHERE c.balance < ?1")
.setParameter(1, 20000);

名前付きパラメタ

WHERE節の中のパラメタを組み込みたい位置に，「:」と任意の文字列（ただし，0～9の文字を除く）の組み合わせを記述します。パラメタの値は，QueryインタフェースのsetParameterメソッドで設定します。名前付きパラメタの記述形式と記述例を次に示します。

記述形式

Query setParameter(String パラメタ名, Object 値)

パラメタ名の先頭には「:」を指定しないでください。また，名前付きパラメタは大文字・小文字を区別します。

記述例

Query q = em.createQuery(
       "SELECT c FROM Customer c WHERE c.name LIKE :custName")
       .setParameter("custName", "John");

なお，パラメタを使用するときには次のことに注意してください。

一つのクエリで位置パラメタと名前付きパラメタを混在して使用しないでください。Cosminexus JPAプロバイダの場合，混在して使用したときの動作は保証しません。

setParameterメソッドには，java.util.Date型またはjava.util.Calendar型のオブジェクトをパラメタ値として設定するときに，次のように指定できます。なお，パラメタ値の時間タイプはTemporalType列挙型で指定する必要があります。詳細についてはJavaのドキュメントを参照してください。

Query setParameter(int 位置, Date 日付, TemporalType 時間タイプ)

Query setParameter(String パラメタ名, Date 日付, TemporalType 時間タイプ)

Query setParameter(int 位置, Calendar カレンダ, TemporalType 時間タイプ)

Query setParameter(String パラメタ名, Calendar カレンダ, TemporalType 時間タイプ)

(3)　クエリ結果の取得および実行

生成したクエリを実行して，そのクエリ結果を返したり，更新クエリを実行したりするためには，Queryインタフェースの次のメソッドを使用します。それぞれのメソッドについて説明します。

(a)　Object getSingleResult()

このメソッドは，クエリ結果を単一のオブジェクトとして返す場合に使用します。

メソッドを実行するとデータを検索します。検索の結果，ヒットした単一の行をエンティティオブジェクトに格納し，Object型で返します。Object型の戻り値は対象のエンティティクラスにキャストする必要があります。

複数の行がヒットした場合は，NonUniqueResultException例外が発生します。ヒットする行がなかった場合は，NoResultException例外が発生します。

(b)　List getResultList()

このメソッドは，クエリ結果をリストとして返す場合に使用します。

メソッドを実行するとデータを検索します。検索の結果，ヒットした複数の行をエンティティオブジェクトに格納し，リストで返します。実行結果として複数の行が返されること想定しているため，ヒットする行が一つもなかった場合は，空のリストが返ります。

(c)　int executeUpdate()

このメソッドは，更新クエリを実行する場合に使用します。

メソッドを実行するとテーブルから複数の行を一斉に削除または更新するクエリを実行します。実行結果にはヒットした行の件数が返ります。

6.16.2　ネイティブクエリでのデータベースの参照および更新方法

Cosminexus JPAプロバイダでは，JPQL以外のクエリ言語として，データベース固有のネイティブクエリを直接記述して，データベースの参照・更新などを実行できます。

ここでは，ネイティブクエリでの使用方法について説明します。

＜この項の構成＞

(1)　Queryオブジェクトの取得方法

(2)　結果セットマッピング

(3)　パラメタの指定方法

(4)　ネイティブクエリ結果の取得および実行

(1)　Queryオブジェクトの取得方法

ネイティブクエリを使用してQueryオブジェクトを取得するためには，次に示すCosminexus JPAプロバイダが提供するEntityManagerインタフェースのメソッドを使用します。

(a)　Query createNativeQuery(String SQL文)

createNativeQueryの記述例を次に示します。引数には実行するネイティブクエリを指定します。

Query q = em.createNativeQuery(
                  "SELECT o.id, o.quantity, o.item " +
                  "FROM Order o, Item i " +
                  "WHERE (o.item = i.id) AND (i.name = 'widget')");

(b)　Query createNativeQuery(String SQL文，Class 結果格納クラス)

createNativeQueryの記述例を次に示します。第1引数には実行するネイティブクエリ，第2引数には実行結果を格納するクラスオブジェクトを指定します。

Query q = em.createNativeQuery(
                  "SELECT o.id, o.quantity, o.item " +
                  "FROM Order o, Item i " +
                  "WHERE (o.item = i.id) AND (i.name = 'book')",
                  com.hitachi.Order.class);

この例の場合，クエリが実行されると「book」という名前のアイテムに対するすべてのOrderエンティティのコレクションを返します。

なお，SELECT節で指定したクエリの結果と引数に指定したクラスオブジェクトの整合性がない場合は例外が発生します。

(c)　Query createNativeQuery(String SQL文，String 結果セットマッピング名)

第1引数には実行するネイティブクエリ，第2引数には実行結果を格納する結果セットマッピング名を指定します。結果セットマッピングは，@ SqlResultSetMappingで指定します。なお，結果セットマッピングについては，「(2)　結果セットマッピング」を参照してください。

@SqlResultSetMappingの定義例とcreateNativeQueryの記述例を次に示します。

@SqlResultSetMappingの定義例

@SqlResultSetMapping(name="BookOrderResults",
     entities=@EntityResult(entityClass=com.hitachi.Order.class))

createNativeQueryの記述例

Query q = em.createNativeQuery(
                  "SELECT o.id, o.quantity, o.item " +
                  "FROM Order o, Item i " +
                  "WHERE (o.item = i.id) AND (i.name = 'book')",
                  "BookOrderResults");

この例の場合，クエリが実行されると「book」という名前のアイテムに対するすべてのOrderエンティティのコレクションを返します。@SqlResultSetMappingを使用することで，「6.16.1(1)　Queryオブジェクトの取得方法」の@NamedQueryを使用した場合の記述例と同じ結果を得ることができます。

なお，SELECT節で指定したクエリ結果と引数に指定した@SqlResultSetMapping設定の整合性がない場合は例外が発生します。

(d)　Query createNamedQuery(String クエリ名)

ネイティブクエリの場合も，JPQLと同じようにcreateNamedQueryメソッドを使用できます。ネイティブクエリの場合は，引数に名前付きネイティブクエリ名を指定してください。

名前付きネイティブクエリは，@NamedNativeQueryを任意のエンティティクラスに付与して定義します。引数のクエリ名には，@NamedNativeQueryのname属性で指定した名前を使用します。

Cosminexus JPAプロバイダの場合，同じ名称の名前付きクエリを複数指定することはできません。同じ名称の名前付きクエリを複数指定した場合には，警告メッセージKDJE55522-Wを出力します。Cosminexus JPAプロバイダで指定した場合，どのクエリが動作するかは保証しません。

次に，createNamedQueryメソッドの使用例を示します。この例では，@NamedNativeQueryを使用してあらかじめfindBookOrderという名前でクエリを登録しています。アプリケーションのcreateNamedQueryメソッドに登録した名前付きクエリ名を渡すことで，事前に登録されているクエリを取得して利用します。

@NamedNativeQueryでのクエリ名の登録

@NamedNativeQuery( name="findBookOrder",
      query="SELECT o.id, o.quantity, o.item " +"
            "FROM Order o, Item i " +
            "WHERE (o.item = i.id) AND (i.name = 'book')")
)
@Entity
public class Order {
・・・
}

createNamedQueryメソッドでの名前付きネイティブクエリの記述例

@Stateless
public class MySessionBean {
 ・・・
 @PersistenceContext
 public EntityManager em;
 ・・・
 public void doSomething() {
   ・・・
   Query q = em.createNamedQuery("findBookOrder ")
 }
}

なお，同一の永続化ユニット内では，ほかのエンティティで定義した名前付きネイティブクエリを使用することもできます。

(2)　結果セットマッピング

結果セットマッピングとは，ネイティブクエリの実行結果を任意のエンティティクラスにマッピングして受け取ったり，スカラ値で受け取ったりするための機能です。

結果セットマッピングでは，ネイティブクエリの実行結果として取得した各カラム値のマッピング情報を@SqlResultSetMappingを指定して任意のエンティティクラスに対して付与します。

(a)　@SqlResultSetMappingの記述形式

@SqlResultSetMappingの記述形式を次に示します。

@SqlResultSetMapping(
 name= 結果セットマッピングの名前,
 entities= 結果をマッピングするためのエンティティクラス指定(@EntityResultの配列),
 columns= 結果をマッピングするためのカラム指定(@ColumnResultの配列) )

name属性

結果セットマッピング名を指定します。

entities属性

@EntityResultの配列を指定します。@EntityResultの記述形式を次に示します。

@EntityResult(
   entityClass= 結果をマッピングするためのクラスを指定,
   fields= 結果をマッピングするためのフィールド指定(@FieldResultの配列) )

@EntityResultのentityClass属性には，カラム値を格納するエンティティクラスを指定します。また，field属性には，@FieldResultの配列を指定します。

@EntityResultの記述形式を次に示します。

@FiledResult(
   name= クラスの永続プロパティ(またはフィールド)の名前,
   column= SELECT節のカラムの名前(または別名) )

@FieldResultのname属性には，@EntityResultのentityClass属性に指定したエンティティクラスの永続化フィールド名を指定します。また，column属性にはカラム名を指定します。

columns属性

columns属性は，エンティティクラスに格納しないでスカラ値として受け取るために，@ColumnResultの配列を指定します。スカラ値を取り出す必要がない場合は指定する必要はありません。@ColumnResultのname属性には，値を取り出すカラム名を指定してください。@ColumnResultの記述形式を次に示します。

@ColumnResult(
   name= SELECT節のカラムの名前(または別名) )

なお，カラム名はASで指定したエリアス名でも指定できます。SELECT節に同じ名前の複数の列を含む場合は，列の別名を使用してください。

(b)　使用例

従業員テーブル（Employee）と部門テーブル（Department）から従業員番号12003のクエリ結果を任意のエンティティクラス（EmployeeSetmap）にマッピングして，スカラ値（EMP_MONTHLY_SALARYカラム）を受け取る例を次に示します。

結果セットマッピング名（NativeQuerySetMap）をcreateNativeQueryの第2引数に指定して，結果セットマッピングを実行します。

結果セットマッピングを使用したネイティブクエリの記述例

query = em.createNativeQuery(
               "SELECT e.EMPLOYEE_ID AS EMP_EMPLOYEE_ID, " +
               "e.EMPLOYEE_NAME AS EMP_EMPLOYEE_NAME, " +
               "d.DEPARTMENT_NAME AS DEP_DEPARTMENT_NAME, " +
               "e.MONTHLY_SALARY AS EMP_MONTHLY_SALARY  " +
               "FROM EMPLOYEE e, DEPARTMENT d " +
               "WHERE e.DEPARTMENT_ID = d.DEPARTMENT_ID " +
               "AND e.EMPLOYEE_ID = 12003",
               "NativeQuerySetMap");

ネイティブクエリの実行結果を格納する任意のエンティティクラス

@Entity
public class EmployeeSetmap implements Serializable {
:
@Id
public int getEmployeeId() { return employeeId; }
public String getEmployeeName() { return employeeName; }
public String getDepartmentName() { return departmentName; }
:
}

@ SqlResultSetMappingの記述例

@SqlResultSetMapping(
      name="NativeQuerySetmap",
      entities={ @EntityResult(
                         entityClass=EmployeeSetmap.class,
                         fields={ @FiledResult(
                                     name="employeeId",
                                     column="EMP_EMPLOYEE_ID"),
                                 @FiledResult(
                                     name="employeeName",
                                     column="EMP_EMPLOYEE_NAME"),
                                 @FiledResult(
                                     name="departmentName",
                                     column="DEP_DEPARTMENT_NAME") } ) },
      columns={ @ColumnResult(
                         name="EMP_MONTHLY_SALARY") }

なお，@ SqlResultSetMappingを実行してネイティブクエリを実行した結果のObject型配列は，次のようになります。

Object[0]

EmployeeSetmapクラスのオブジェクト

（EMP_EMPLOYEE_IDカラム，EMP_EMPLOYEE_NAMEカラム，DEP_DEPARTMENT_NAMEカラムの値が各フィールドに格納される）

Object[1]

EMP_MONTHLY_SALARYカラムの値

(3)　パラメタの指定方法

ネイティブクエリは，JPQLと同様に，パラメタによって動的に値を設定することができます。WHERE節の中のパラメタを組み込みたい位置に，「?」と数値の組み合わせを記述します。パラメタの値は，QueryインタフェースのsetParameterメソッドで設定します。ただし，ネイティブクエリでは，JPQLの名前付きパラメタは使用できません。

パラメタの記述形式を次に示します。

Query setParameter(int 位置, Object 値)

(4)　ネイティブクエリ結果の取得および実行

ネイティブクエリ結果の取得および実行は，JPQLと同様に，Queryインタフェースの次のメソッドを使用します。

Object getSingleResult()

List getResultList()

int executeUpdate()

これらのメソッドの詳細については，「6.16.1　JPQLでのデータベースの参照および更新方法」を参照してください。

6.16.3　クエリ結果件数の範囲指定

複数件あるクエリ結果の中から任意に指定した件数だけを取得したり，開始位置で指定したクエリ結果だけを取得したりすることができます。これらの情報を取得するには，Queryインタフェースのメソッドを使用します。メソッドについて次に説明します。

＜この項の構成＞

(1)　setMaxResultsメソッド

(2)　setFirstResultメソッド

(3)　Queryインタフェースのメソッドの使用例

(4)　注意事項

(1)　setMaxResultsメソッド

複数件あるクエリ結果の中から任意に指定した件数だけを取得するにはQueryインタフェースのsetMaxResultsメソッドを使用します。setMaxResultsメソッドの記述形式を次に示します。

Query setMaxResults(int検索結果の最大数)

メソッドの引数には，検索結果の最大数を指定します。

(2)　setFirstResultメソッド

開始位置で指定したクエリ結果だけを取得するにはsetFirstResultメソッドを使用します。setFirstResultメソッドの記述形式を次に示します。

Query setFirstResult(int検索結果の開始位置)

メソッドの引数に検索結果の開始位置を指定します。なお，開始位置は0から始まる数値を指定してください。

(3)　Queryインタフェースのメソッドの使用例

setMaxResultsメソッドおよびsetFirstResultメソッドの使用例を示します。この例では，従業員データ（Employee）から，月給（e.monthlySalary）の多い順に10番目から5人分のEmployeeオブジェクトを取得します。

Query query = em.createQuery( "SELECT e FROM Employee AS e " +
                             "ORDER BY e.monthlySalary DESC" )
                             .setFirstResult(9)
                             .setMaxResults(5);
List resultList = query.getResultList();

(4)　注意事項

setFirstResultメソッドを使用して開始位置を指定した場合，引数に指定した値によって，getResultListメソッドおよびgetSingleResultメソッドを呼び出してから結果の値を取得するまでの時間が変わります。通常，引数に指定した開始位置の値に比例して，結果の値が戻ってくるまでの時間が掛かります。

6.16.4　フラッシュモードの指定

エンティティオブジェクトに対して実行された未コミット操作をクエリがどのように扱うかを指定できます。この指定をフラッシュモードの指定といいます。

フラッシュモードは，javax.persistence.QueryインタフェースのsetFlushModeメソッドで設定します。Cosminexus JPAプロバイダでは，設定できる値はAUTOだけです。COMMITは設定できません。

FlushModeType.AUTOの場合

トランザクション内でクエリが実行されたとき，クエリ結果に影響を及ぼす永続化コンテキストにあるすべてのエンティティの変更内容がクエリ結果に反映されます。

この設定は，EntityManagerインタフェースのsetFlushModeメソッドのフラッシュモードに関係なくクエリに適用されます。

6.16.5　クエリヒントの指定

クエリ実行時に，ベンダに依存するヒントとしてクエリヒントを指定できます。Cosminexus JPAプロバイダでは，悲観的ロックを使用するときに指定します。

クエリヒントは次に示す場所に指定します。

QueryオブジェクトのsetHint()メソッドの引数

@NamedQueryの引数の@Hint

O/Rマッピングファイルの<named-query>タグの下位要素である<hint>タグ

クエリヒントに指定できる範囲以外の値が設定された場合は例外が発生します。なお，指定する値は大文字と小文字を区別しません。

例外が発生するタイミングは，クエリヒントが指定された個所によって異なります。次に例外発生のタイミングを示します。

setHint()メソッドの場合，アプリケーションのクエリ実行時

アノテーションの場合，デプロイ時

O/Rマッピングファイルの場合，アプリケーション開始時

Cosminexus JPAプロバイダがサポートするクエリヒントについては，アノテーションを使用する場合は，マニュアル「Cosminexus アプリケーションサーバ リファレンス API編」の「2.1　対応するアノテーションのサポート範囲」，O/Rマッピングファイルを使用する場合は，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「6.3　O/Rマッピングファイル」を参照してください。

6.16.6　クエリの実行時の注意事項

ここでは，クエリ実行時の注意事項について説明します。

setMaxResultsメソッドまたはsetFirstResultメソッドで，コレクション同士がFETCH JOINを含むクエリを実行した場合，結果は保証されません。

executeUpdateメソッド以外のQueryメソッドは，トランザクション内で実行する必要はありません。特にgetResultListとgetSingleResultメソッドはトランザクション内で実行する必要はありません。

トランザクションスコープ永続化コンテキストのEntityManagerで，クエリが実行された場合の結果のエンティティは，detached状態になります。拡張永続化コンテキストのEntityManagerでクエリが実行された場合，すべてmanaged状態になります。

QueryインタフェースのメソッドからスローされるNoResultExceptionとNonUniqueResultException以外の実行時例外はカレントのトランザクションをロールバックします。

6.17　JPQLの記述方法

ここでは，JPQLの記述方法について説明します。

＜この節の構成＞

6.17.1　JPQLの構文

6.17.2　SELECT文

6.17.3　SELECT節

6.17.4　FROM節

6.17.5　WHERE節

6.17.6　GROUP BY節およびHAVING節

6.17.7　ORDER BY節

6.17.8　バルクUPDATE文およびバルクDELETE文

6.17.9　JPQL使用時の注意事項

6.17.10　クエリ使用時に発生する例外

6.17.1　JPQLの構文

JPQL文には，SELECT文とUPDATE文，DELETE文があります。

JPQL文は，動的に指定したり，アノテーションやO/Rマッピングファイルのタグで静的に定義したりすることができます。また，JPQLのすべての文でパラメタの指定ができます。

JPQLは型付き言語で，すべての式は型を持ちます。式の型は，式の構成や識別変数で定義された抽象スキーマ型，永続化フィールドとリレーションシップを評価する型，およびリテラル型で構成されています。なお，構文の文法については，「付録D　JPQLのBNF」を参照してください。

注意

Cosminexus JPAプロバイダの場合，BNF構文に準拠しないJPQLを使用すると，例外が発生するおそれがあります。例外が発生しない場合でも，動作は保証しません。また，BNF構文に準拠したJPQLを使用した場合でも，使用するデータベースで該当する機能をサポートしていない場合の動作は保証しません。

＜この項の構成＞

(1)　抽象スキーマ型

(2)　抽象スキーマ名

(3)　クエリのドメイン

(1)　抽象スキーマ型

JPQLでは，エンティティを対象にクエリを発行します。そのため，クエリでは対象となるエンティティの抽象スキーマを定義する必要があります。エンティティの抽象スキーマ型は，アノテーションまたはO/Rマッピングファイルによって提供されるエンティティクラスとO/Rマッピングの情報によって定義されます。

抽象スキーマ型とは，エンティティクラスのことを指します。エンティティクラスを構成するものとして，フィールドや，アノテーションなどのO/Rマッピング情報があります。

エンティティの抽象スキーマ型は次に示すフィールドを持ちます。

ステートフィールド
ステートフィールドは，エンティティクラスの永続化フィールド，または永続化プロパティで，リレーションシップによる関連が存在しないフィールド，またはプロパティです。

関連フィールド
関連フィールドは，エンティティクラスでリレーションシップによって関連づいた永続化フィールド，または永続化プロパティです。リレーションシップがOneToManyまたはManyToManyの場合，フィールドはコレクションになります。

(2)　抽象スキーマ名

JPQLでは，エンティティを示すために，その抽象スキーマ型を指定する必要があります。抽象スキーマ型を示すための名前を抽象スキーマ名といいます。抽象スキーマ名は@Entityのname属性（またはO/Rマッピングファイルの<entity>タグのname属性）で定義します。name属性が指定されなかった場合は，エンティティクラスの（パッケージ名抜きの）クラス名となります。

抽象スキーマ名は，永続化ユニット単位で固有となります。

(3)　クエリのドメイン

クエリのドメインは，永続化ユニット内で定義されたすべてのエンティティの抽象スキーマ型を参照できます。抽象スキーマ型の中で定義されている関連フィールドによって，ほかの関連するエンティティの抽象スキーマ型を参照できます。

6.17.2　SELECT文

SELECT文には次の節があります。

SELECT節
検索するオブジェクトの型か集合関数による値を指定します。SELECT節は必ず指定します。

FROM節
検索が適用される範囲を指定します。FROM節は必ず指定します。

WHERE節
検索結果を絞るために使用します。WHERE節は省略できます。

GROUP BY節
検索結果をグループ化するために使用します。GROUP BY節は省略できます。

HAVING節
グループ化されたものをフィルタリングするために使用します。HAVING節は省略できます。

ORDER BY節
検索結果の順序化をするために使用します。ORDER BY節は省略できます。

SELECT文に，SELECT節およびFROM節の指定がない場合は例外が発生します。

6.17.3　SELECT節

SELECT節ではクエリの結果を表します。一つ以上の値がクエリのSELECT節から返ります。SELECT節には，次に示す要素をコンマで区切って指定します。なお，コンマで区切られた一つのまとまりをselect式と呼びます。

抽象スキーマの識別子または識別子を付与した永続化フィールド

パス式

集合関数

コンストラクタ式

なお，DISTINCTキーワードは，重複する値をクエリ結果から除くときに指定してください。

SELECT節の記述例を次に示します。

SELECT e.employeeName, e.monthlySalary
FROM Employee AS e
WHERE e.monthlySalary  < 150000

＜この項の構成＞

(1)　コンストラクタ式

(2)　集合関数

(3)　SELECT節の実行結果

(1)　コンストラクタ式

コンストラクタ式は，一つ以上のJavaのインスタンスを返すSELECT節のselect式で使用されます。生成名は完全修飾名を指定します。

コンストラクタ式は，エンティティのカラムの一部または全部や，関連する別のエンティティのカラムと組み合わせた形で取得できます。なお，この結果を格納するクラスはエンティティである必要はありません。

コンストラクタ式の構文は，select式にNEW演算子を付けて指定します。格納するクラスがエンティティの場合，エンティティクラスのインスタンスの状態はnewになります。コンストラクタ式の記述例を次に示します。

SELECT NEW com.hitachi.jpa.test.entity.EmployeeTmp
(e.employeeId, e.employeeName, d.departmentName)
FROM Department AS d, d.employees AS e
WHERE e.employeeId = 12003

(2)　集合関数

SELECT節では集合関数を使用できます。使用できる集合関数を次の表に示します。

表6-19　JPQLのSELECT節で使用できる集合関数

集合関数
引数
結果の型
適用される値がない場合の結果

AVG
数値型のステートフィールド※
Double型
null

MAX
順序を指定できるフィールド型（数値型，文字列型，文字型，または日付型）※
適用するフィールドの型
null

MIN
順序を指定できるフィールド型（数値型，文字列型，文字型，または日付型）※
適用するフィールドの型
null

SUM
数値型のステートフィールド※

整数型の場合：Long型

浮動小数点型の場合：Double型

BigInteger型の場合：BigInteger型

BigDecimal型の場合：BigDecimal型

null

COUNT
識別変数（引数にパス式を指定する場合，ステートフィールドか関連フィールドを指定する）
Long型
0

注　DISTINCTが指定されているかどうかにかかわらず，集合関数が適用される前にnull値は除去されます。

注※　引数にパス式を指定する場合，関連フィールドを指定することはできません。

なお，集合関数式の構文の詳細については，「付録D　JPQLのBNF」を参照してください。

(3)　SELECT節の実行結果

クエリのSELECT節で定義されるクエリ結果の型は，次のどれか一つになります。なお，複数ある場合は順番に並べられます。

エンティティ抽象スキーマ型

フィールド型

集合関数の結果

コンストラクタ式の結果

SELECT節の結果の型は，SELECT節に含まれるselect式の結果の型によって定義されます。複数のselect式がSELECT節で使われている場合，クエリの結果はObject[]型となります。この結果の要素はSELECT節で指定された順番に一致し，各select式の結果の型と一致します。

6.17.4　FROM節

ここではFROM節について説明します。

＜この項の構成＞

(1)　範囲変数宣言と識別変数

(2)　パス式

(3)　Joins式

(4)　コレクションメンバの宣言

(5)　注意事項

(1)　範囲変数宣言と識別変数

範囲変数宣言とは，FROM節内でエンティティクラスの論理的な名前を記述し，そのあとにASと識別子を指定する宣言です（ASは省略できます）。この範囲変数宣言の識別子を識別変数といいます。範囲変数宣言と識別変数の例を次に示します。

SELECT ・・・（省略）・・・

FROM  Department AS dep

WHERE ・・・（省略）・・・

「Department AS dep」の部分が範囲変数宣言です。また，「dep」が識別変数となります。次に，範囲変数宣言の構文を示します。

range_variable_declaration ::=
abstract_schema_name [AS] identification_variable

範囲変数宣言での識別変数の構文は，SQLの構文と同じです。構文について説明します。

キーワードASの使用は任意です。

識別変数を省略することはできません。ただし，抽象スキーマと識別変数の間に指定するASは省略できます。識別変数はFROM節で指定します。

予約済みの識別子は使用できません。使用した場合は例外が発生します。

同じ永続化ユニットのほかのエンティティと同じ名前は使用できません。Cosminexus JPAプロバイダでは，同じ名前のエンティティを使用した場合の動作は保証しません。

識別変数は大文字，小文字の区別をしません。

抽象スキーマ名と同一の名前は指定できません。Cosminexus JPAプロバイダでは，同じ名前の抽象スキーマを指定した場合の動作は保証しません。

Java識別子文字で始まり，ほかのすべての文字はJava識別子の部分文字となる必要があります。それ以外の文字が指定された場合は，例外が発生します。最初の文字は，Character.isJavaIdentifierStartメソッドの戻り値がtrueになる文字にします（アンダースコア（_）とドルマーク（$）文字を含む）。最初以外の文字は，Character.isJavaIdentifierPartメソッドの戻り値がtrueになる文字にします（ただし，クエスチョンマーク（?）は，JPQLの予約語のため使用できません）。

JPQLの予約語は次のとおりです。
SELECT，FROM，WHERE，UPDATE，DELETE，JOIN，OUTER，INNER，LEFT，GROUP，BY，HAVING，FETCH，DISTINCT，OBJECT，NULL，TRUE，FALSE，NOT，AND，OR，BETWEEN，LIKE，IN，AS，UNKNOWN，EMPTY，MEMBER，OF，IS，AVG，MAX，MIN，SUM，COUNT，ORDER，BY，ASC，DESC，MOD，UPPER，LOWER，TRIM，POSITION，CHARACTER_LENGTH，CHAR_LENGTH，BIT_LENGTH，CURRENT_TIME，CURRENT_DATE，CURRENT_TIMESTAMP，NEW，EXISTS，ALL，ANY，SOME
なお，「UNKNOWN」はJPA1.0では利用していませんが，Cosminexus JPAプロバイダでは予約語となっているので注意してください。

(2)　パス式

パス式は，識別変数のあとにピリオド（.）を付加し，ステートフィールドまたは関連フィールドを続けるための式です。このため，パス式の型は，ステートフィールドまたは関連フィールドの型になります。

パス式をたどって得た関連フィールドから，さらにパス式を組み立てることができます。ただし，基になるパス式の型がコレクション関連フィールドである場合，パス式を組み立てることはできません。コレクション型からパス式を作ることは，構成的に誤りとなります。

なお，パス式の途中の関連フィールドがnull値の場合，パスは値がないとみなされるので，クエリの結果には影響はありません。

パス式は，inner joinを使用する構文で使用できます。パス式の構文の詳細については，「付録D　JPQLのBNF」を参照してください。

参考

関連フィールドの種類を次に示します。

コレクション関連フィールド（collection_valued_association_field）とは，関連フィールドがコレクションで指定されているものです。OneToManyまたはManyToManyの関係で示されます。

非コレクション関連フィールド（single_valued_association_field）とは，関連フィールドがsingle-valuedで指定されているものです。OneToOneまたはManyToOneの関係で示されます。

エンベッデドクラスフィールドは，embeddedクラスに対応するエンティティのフィールド名です。

(3)　Joins式

Joins式はFROM節で使用できます。使用できるJoins式を次の表に示します。

表6-20　FROM節で使用できるJoins式

Joins式 | 内容 | BNF構文の構文名※1
Inner Joins | 関係するフィールドで，二つのエンティティクラスを結合し，関連を持っているエンティティオブジェクトだけを抽出します。 | join, join_spec
Left Outer Joins | 関係するフィールドで，二つのエンティティクラスを結合し，関連を持っているエンティティオブジェクトおよび，関連を持っていないエンティティオブジェクトも抽出します。 | join, join_spec
Fetch Joins | 関係のあるフィールドで，二つエンティティクラスを結合します。なお，エンティティ間にはリレーションシップによる関連があるため，Select節中には一つのエンティティクラスだけを指定します。※2 | fetch_join

注※1　BNF構文の構文名の詳細については，「付録D　JPQLのBNF」を参照してください。

注※2　Fetch Joinsでエンティティを取得した場合，右側で指定した関連先のエンティティの情報をクエリ実行と同時に取得します。これによって，フェッチ戦略に依存しないで関連先の情報を取得できます。Fetch Joinsの記述例を次に示します。

SELECT emp FROM Employee AS emp JOIN FETCH emp.company

Join式を使用する場合の注意事項

Join式を使用する場合の注意事項について説明します。

Inner Joinsの注意事項

INNERキーワードは，任意で使われます。

Left Outer Joinsの注意事項

OUTERキーワードは，任意で使われます。

Fetch Joinsの注意事項

Fetch Joinsでは，一つのエンティティで二つのエンティティ情報を指定します。指定するエンティティと，そのエンティティと関連する別のエンティティ情報を結合します。
なお，Cosminexus JPAプロバイダの場合，一つのエンティティ情報で結合するため，リレーションシップを持つエンティティを指定してください。リレーションシップを持たないエンティティを指定した場合は例外が発生します。

JOIN FETCHの右側で参照される関係は，クエリの結果として返されるエンティティに属する関係となる必要があります。Cosminexus JPAプロバイダの場合，エンティティに属さないときは例外が発生します。

JOIN FETCHの右側で参照されるエンティティには，識別子を指定できません。このため，クエリ内で参照することはできません。

(4)　コレクションメンバの宣言

コレクションメンバ宣言の識別変数は，予約された識別子INを使って宣言します。コレクションメンバ式で定義された識別変数は，パス式を使ってコレクションの値を取得できます。コレクションメンバ式の記述例を次に示します。

SELECT emp.employeeId, emp.employeeName, dep.departmentName
FROM Department AS dep, IN (dep.employees) AS emp
WHERE dep.departmentId = 3

なお，コレクションメンバ式の構文の詳細については，「付録D　JPQLのBNF」を参照してください。

(5)　注意事項

ここでは，FROM節での注意事項について説明します。

識別変数の影響
FROM節で宣言された識別変数がWHERE節の中で使用されなくても，宣言された識別変数がクエリの結果に反映されます。

多態性の注意事項
JPQLはポリフォリズムです。FROM節で明確に参照している特定のエンティティクラスのインスタンスだけでなく，そのサブクラスも対象になります。このため，クエリによって取得できるインスタンスは，クエリ条件を満たすサブクラスのインスタンスを含みます。

6.17.5　WHERE節

WHERE節は式を満たすオブジェクトまたは変数を検索するために使われる条件式で構成されています。WHERE節では，select文の結果やupdateやdelete操作の範囲を特定します。

＜この項の構成＞

(1)　WHERE節で使用できる条件式

(2)　関数式

(3)　注意事項

(1)　WHERE節で使用できる条件式

WHERE節で使用できる条件式を次の表に示します。

表6-21　WHERE節で使用できる条件式

式 | 内容 | BNF構文の構文名※
BETWEEN | フィールドで指定した範囲に含まれていることを評価します。 | between_expression
IN | フィールドで指定したどれかの値と一致することを評価します。 | in_expression
LIKE | フィールドでワイルドカード記号を展開したあとの文字列と一致することを評価します。 | like_expression
IS [NOT] NULL | null値かどうかをテストします。 | null_comparison_expression
IS [NOT] EMPTY | 指定したコレクション値が空かどうかをテストします。 | empty_collection_comparison_expression
[NOT] MEMBER [OF] | 指定したコレクション値がコレクションのメンバであるかどうかをテストします。空のコレクションを表す場合，MEMBER OF式の値はFALSE，NOT MEMBER OF式の値はTRUEとなります。 | collection_member_expression
EXISTS | サブクエリの結果を判定します。一つ以上の値がある場合はtrue，それ以外はfalseを返します。 | exists_expression
ALL | サブクエリで返されたすべての値と比較します。 | all_or_any_expression
ANY (SOME) | サブクエリで返されたどれかの値と比較します。 | all_or_any_expression
サブクエリ | selectによる結果を記述できます。 | subquery
関数式 | 「(2)　関数式」を参照してください。 | 該当する関数構文を参照

注※　BNF構文の構文名の詳細については，「付録D　JPQLのBNF」を参照してください。

WHERE節を使用する場合の注意事項について説明します。

IN式

評価対象のフィールドがnull値かunknownの場合，式の値はunknownになります。

IN式に対する値の集合を定義したコンマで区切られたリストでは，少なくとも一つ以上の要素が必要です。Cosminexus JPAプロバイダの場合，一つ以上の要素がないと例外が発生します。

評価対象のフィールドは，文字列，数値，またはenum値を持つ必要があります。

リテラルや入力パラメタ値，およびサブクエリの結果は，評価対象のフィールドと同じ抽象スキーマ型にしてください。Cosminexus JPAプロバイダの場合，同じ抽象スキーマ型でないと例外が発生します。

LIKE式

BNF構文で示されるstring_expressionまたはpattern_valueの値が，nullまたはunknownの場合，LIKE式の値はunknownになります。

BNF構文で示されるescape_characterが指定されている場合で，値がnullのとき，LIKE式の値はunknownになります。

指定するパターン値は，アンダースコア（_）が1文字に相当し，パーセント（%）文字が連続文字（空の連続文字も含む）に相当します。なお，ほかの文字は検索文字列を示します。

オプションのエスケープ文字は，文字列リテラルかまたはcharacter文字です。パターン文字列のアンダースコアとパーセント文字を標準の文字として解釈させる場合に使用します。

IS [NOT] NULL式
指定したコレクション値がnullまたはunknownの場合，IS [NOT] EMPTY式の値はunknownになります。

[NOT] MEMBER [OF]式
指定した値がnullまたはunknownの場合，戻り値はunknownになります。

ALL式またはANY (SOME)式

条件演算がtrueでもfalseでもない場合は，unknownになります。

一緒に使用できる比較演算子は，=，<，<=，>，>=，<>です。

サブクエリの結果の型は比較演算子の型と同じにする必要があります。Cosminexus JPAプロバイダの場合，型が異なると例外が発生します。

SOMEは，ANYの同義語です。※

注※　この注意事項はANY (SOME)式の場合だけ該当します。

サブクエリ
WHERE節やHAVING節で使用します。FROM節では使用できません。

(2)　関数式

JPQLでは次の表に示す関数をWHERE節やHAVING節で使用できます。関数式の引数の値がnullかunknownの場合，関数式の値はunknownになります。

表6-22　JPQLで使用できる関数

分類 | 関数 | 返り値 | 引数についての補足説明
文字列関数 | CONCAT | 引数の連結した文字列 | －
SUBSTRING | 引数で指定した開始位置と長さの文字列 | 2番目と3番目引数は，返されるサブストリングの開始位置および長さを整数で指定します。文字列の先頭の位置は1です。
TRIM | 特定の文字を取り除いた文字列 | 取り除く文字がない場合は，スペース（空白）と見なされます。任意のtrim文字はcharacterの入力文字列です。トリムの方法が指定されない場合はBOTHとなります。
LOWER | 小文字化した文字列 | －
UPPER | 大文字化した文字列 | －
LENGTH | 文字列長の整数値 | －
LOCATE | 指定された位置から検索し，与えられた文字列で最初に文字列を見つけた位置の整数値 （文字列が見つからない場合は0） | 1番目引数は検索する文字列，2番目引数は検索される文字列を示します。任意となる3番目の引数は，検索を開始する文字の位置を示します（デフォルトは先頭から検索）。文字列の先頭位置は1です。
算術関数 | ABS | 関数の引数と同じ型（Integer，Float，またはDouble）の絶対値 | 引数として数値を渡します。
SQRT | 引数で渡された数値の平方根（実数） | 引数として数値を渡します。
MOD | 引数で渡された二つの数値の剰余（整数） | 二つの整数を渡します。
SIZE | コレクションの要素数（整数） | コレクションを渡します。
日付時間関数 | CURRENT_DATE | データベースの日付 | －
CURRENT_TIME | データベースの時刻 | －
CURRENT_TIMESTAMP | データベースのタイムスタンプ | －

（凡例）－：該当しない

(3)　注意事項

WHERE節の注意事項について説明します。

(a)　演算子の優先順位

演算子の優先順位を次に示します。

ピリオド（.）

算術演算子
単項演算（+，-），乗算と除算（*，/），加算と減算（+，-）

比較演算子
=，>，>=，<，<=，<>（not equal），[NOT] BETWEEN，[NOT] LIKE，[NOT] IN，IS [NOT] NULL，IS [NOT] EMPTY，[NOT] MEMBER [OF]

論理演算子
NOT，AND，OR

(b)　条件式の注意事項

条件式は，条件式，比較式，論理演算子，評価結果がboolean値になるパス式，booleanリテラル，boolean型の入力パラメタで構成されます。

算術式は，比較式で使用できます。算術式は，ほかの算術式，四則演算，結果が数値になるパス式，数値リテラル，数値型の入力パラメタで構成されます。

算術操作は，数値昇格（numeric promotion）を使用します。

式の評価順序を示すために括弧で囲むことができます。

集合関数は，HAVING節の条件式だけで使用できます。

条件式の中では，シリアライズ形式またはlobsとしてマップされるフィールドを使用しないでください。

(c)　リテラルの注意事項

文字リテラルは，シングルクォテーションで囲みます（例：'literal'）。シングルクォテーションを含む文字列リテラルは，二つシングルクォテーションを使用します。

JavaStringリテラルのように，クエリの文字列リテラルはUnicode文字のエンコードを使用します。

Javaのエスケープ表記の使用は，クエリの文字列リテラルではサポートしません。

enumのリテラルは，Javaのenumリテラル構文のリテラルが使用できます。enumリテラルにはenumクラス名が必要です。

booleanリテラルは，TRUEとFALSEである。このリテラルは大文字小文字を区別しません。

(d)　識別変数の注意事項

識別変数は，クエリのFROM節で宣言された識別子であるため，ほかの節では宣言できません。FROM節以外で宣言した場合は例外が発生します。SELECT文，またはDELETE文のWHEREかHAVING節で使用されるすべての識別変数は，FROM節で定義されたものを使用します。

識別変数の範囲は，WHERE節とHAVING節で決定されます。識別変数は，エンティティの抽象スキーマタイプのコレクションメンバやインスタンスは指定できますが，コレクション自体は指定できません。コレクションを指定した場合は例外が発生します。

(e)　Path式の注意事項

WHEREかHAVING節内でのコレクションのパス式で，条件式の一部としてIS [NOT] EMPTY式や[NOT] MEMBER [OF]式，またはSIZE操作への引数以外を使用しないでください。

(f)　入力パラメタの注意事項

入力パラメタは，クエリのWHERE節かHAVING節で使用できます。

一つのクエリで位置パラメタと名前付きパラメタを混在して使用しないでください。混在した場合の動作は保証されません。

入力パラメタの値がnullの場合，入力パラメタを含む比較操作か算術操作で返される値はunknownになります。

なお，位置パラメタと名前付きパラメタの使い方については，「6.16.1(2)　パラメタの指定方法」を参照してください。

6.17.6　GROUP BY節およびHAVING節

GROUP BY節では，クエリの結果をグループごとにまとめます。また，HAVING節では，クエリ結果をさらに絞り込むための条件指定ができます。グループを指定した上で，HAVING節の条件を指定してください。

クエリにWHERE節とGROUP BY節の両方が含まれる場合，WHERE節が最初に実行され，その後，GROUP BY節で形式を整えてHAVING節に従ってフィルタリングします。

SELECT節に現れる集合関数以外のアイテムは，GROUP BY節にも指定する必要があります。グルーピングでは，null値も含めて条件として扱います。GROUP BY節およびHAVING節の注意事項について説明します。

エンティティによるグルーピングはできますが，シリアライズしたフィールドや，lobフィールドを含むことはできません。Cosminexus JPAプロバイダでは，指定した場合には例外が発生します。

HAVING節にはグループアイテムに対する検索条件を指定するため，グループアイテムに適用する集合関数を指定する必要があります。Cosminexus JPAプロバイダでは，検索条件の指定がない場合は例外が発生します。

GROUP BY節がない状態でHAVING節は使用しないでください。使用した場合は例外が発生します。

GROUP BY節およびHAVING節の記述例を次に示します。

SELECT e.department.departmentId
FROM Employee AS e
GROUP BY e.department.departmentId
HAVING COUNT(e.department.departmentId) <= 2

なお，GROUP BY節およびHAVING節の構文については，「付録D　JPQLのBNF」を参照してください。

6.17.7　ORDER BY節

ORDER BY節ではオブジェクトや値が順序付けされてクエリの結果を返します。ORDER BY節の記述例を次に示します。

SELECT e
FROM Employee AS e
ORDER BY e.monthlySalary DESC

ORDER BY節について説明します。

一つ以上のorder項目が指定された場合，orderby項目要素の左から右へ順に優先度を決め，いちばん左のorderby項目がいちばん高い優先度を持ちます。

ASCは昇順のときに，DESCは降順のときに指定します。なお，デフォルト値はASCです。

null値がある場合の順番はSQLのルールを適用します。

ORDER BY節が使用された場合，クエリの結果の順番はクエリメソッドの結果に保存されます。

なお，ORDER BY節の構文については，「付録D　JPQLのBNF」を参照してください。

また，ORDER BY節では次に示す条件を満たす必要があります。

ORDER BY節で指定するorder項目は順序付けができること。

ORDER BY節で指定するorder項目はSELECT節のselect式からたどれること。

これらの条件に合わない場合，Cosminexus JPAプロバイダでは例外が発生するおそれがあります。ただし，例外が発生しない場合でも動作は保証しません。

6.17.8　バルクUPDATE文およびバルクDELETE文

複数のレコードを一括して更新することをバルク更新といいます。バルク更新をするには，バルクUPDATE文およびバルクDELETE文を使用します。バルクUPDATEとDELETEの操作は，単体のエンティティクラスまたはサブクラスと合わせたエンティティクラスに適用されます。UPDATE文ではUPDATE節に，DELETE文ではFROM節に識別変数を定義して，1種類のエンティティを指定します。

バルクUPDATE文およびバルクDELETE文を使用するときの注意時について説明します。

delete操作は，指定されたクラスとそのサブクラスのエンティティにだけ適用されます。関係するエンティティへのカスケードはされません。

update操作で指定される更新値（new_value）は，割り当てられたフィールドの型との互換性が必要です。互換性がない場合は例外が発生します。

バルクUPDATE文は，楽観的ロックを掛けないでデータベースの更新操作を実行するため，楽観的ロックに関する処理は実行しません。このため，バージョン列の値を手動で参照・更新する必要があります。

注意

バルクUPDATE文やバルクDELETE文を実行するときは，データベースと活性化している永続化コンテキストのエンティティとの間で不一致になるため注意が必要です。バルクUPDATE文とバルクDELETE文での操作は，トランザクションと切り離したところで実行するか，トランザクションの開始時に実行する必要があります。

バルクUPDATE文およびバルクDELETE文の記述例を次に示します。

UPDATE EMPLOYEE
SET MONTHLY_SALARY = MONTHLY_SALARY + 1000
WHERE DEPARTMENT_ID = 3

DELETE FROM EMPLOYEE e
WHERE e.EMPLOYEE_NAME IS NULL AND e.monthlySalary  IS EMPTY

なお，バルクUPDATE文，バルクDELETE文の構文については，「付録D　JPQLのBNF」を参照してください。

6.17.9　JPQL使用時の注意事項

ここでは，JPQL使用時の注意事項について説明します。

＜この項の構成＞

(1)　null値の注意事項

(2)　HiRDBでJPQLを使用する場合の注意事項

(1)　null値の注意事項

クエリ結果のnull値

クエリの結果の値が，null値を持つ関連フィールドまたはステートフィールドに対応する場合，そのnull値がクエリメソッドの結果として返されます。

IS NOT NULLの構文は，クエリの結果の集合からnull値を除去するために使用できます。

Javaの数値系プリミティブ型によって定義されるフィールドには，クエリの結果としてnull値を生成できません。

比較，条件式でのnull値

参照の対象がデータベースに存在しない場合，その値はnullとみなされます。null値を検索するには，比較条件IS NULLおよびIS NOT NULLだけが使用できます。

null値をIS NULLやIS NOT NULL以外の条件で使用して，その結果がnull値に依存する場合，結果はunknownになります。

null値の比較または算術操作の結果は，常にunknown値になります。

二つのnull値の比較結果はunknown値になります。

unknown値のある比較または算術操作の結果は，常にunknown値になります。

boolean演算子は3値論理を使用します。ANDの場合，ORの場合，およびNOTの場合の3値論理式をそれぞれ表に示します。

表6-23　ANDの3値論理式（A AND Bの結果）

A | B
True | False | Unknown
True | True | False | Unknown
False | False | False | False
Unknown | Unknown | False | Unknown

表6-24　ORの3値論理式（A OR Bの結果）

A | B
True | False | Unknown
True | True | True | True
False | True | False | Unknown
Unknown | True | Unknown | Unknown

表6-25　NOTの3値論理式（NOT Aの結果）

A | NOT Aの結果
True | False
False | True
Unknown | Unknown

(2)　HiRDBでJPQLを使用する場合の注意事項

次に示すJPQLの関数の引数に，位置パラメタや名前パラメタを指定することはできません。
TRIM，SQRT，ABS，LENGTH，LOWER，MOD，LOCATE，UPPER，CONCAT，SUBSTRING，IS [NOT] NULL
これらの関数の引数に位置パラメタや名前パラメタを指定した場合，動作は保証されません。なお，位置パラメタや名前パラメタを指定した場合はHiRDBのSQL構文エラーとなり，SQLException例外を含んだPersistenceException例外をスローすることがあります。
これらの関数の機能を使用したい場合は，ネイティブクエリを使用してください。

四則演算子（＋，－，＊，／）の両側に？パラメタは指定できません。また，比較演算子（=，>，>=，<，<=，<>）の両側に？パラメタを指定したり，片側に？パラメタを指定したりしてもう一方にリテラルを指定することはできません。指定した場合の動作は保証されません。指定した場合はHiRDBのSQL構文エラーとなり，SQLException例外を含んだPersistenceException例外をスローすることがあります。
JPQLの中で四則演算や比較演算しないで，JPQLを使用する前に四則演算や比較演算の操作をしてからJPQLを使用するようにしてください。

HiRDBでJPQLを使用する場合に使用できないクエリの記述例を次に示します。

使用できない例1：関数の引数に位置パラメタを指定する

Query query1 = em.createQuery(
"SELECT  o FROM TestEntity o "+
               "WHERE o.name=TRIM(LEADING FROM ?1)")
             .setParameter(1, "  HitachiTaro");

使用できない例2：四則演算子に位置パラメタを指定する

int no_A=2;
int no_B=4;
Query query2 = em.createQuery(
"SELECT  o FROM TestEntity o WHERE o.id = ?1 + ?2")
              .setParameter(1, no_A)
              .setParameter(2, no_B);

使用できない例3：比較演算子に位置パラメタを指定する

int cmp_no=3;
Query query3 = em.createQuery(
"SELECT  o FROM TestEntity o WHERE o.id = ?1 AND ?1 < 9")
              .setParameter(1, cmp_no);

6.17.10　クエリ使用時に発生する例外

Cosminexus JPAプロバイダの場合，クエリ関連のアノテーションで文法的に間違いがあると，アプリケーションをデプロイするとき例外が発生します。また，クエリ関連のメソッドの引数が不正であったり，指定された文字列が有効なJPQLの文字列でなかったりすると，IllegalArgumentException例外が発生するか，クエリの実行が失敗します。

ネイティブクエリを使用しているデータベースのクエリに対して有効でない場合，または定義された結果のセットがクエリの結果と互換性がない場合，クエリの実行は失敗します。Cosminexus JPAプロバイダでは，クエリの実行時にPersistenceException例外がスローされます。

＜この項の構成＞

(1)　EntityManager内のクエリ関連インタフェースのAPIで発生する例外

(2)　QueryインタフェースのAPIで発生する例外

(1)　EntityManager内のクエリ関連インタフェースのAPIで発生する例外

EntityManager内のクエリ関連インタフェースのAPIで発生する例外を次に示します。

createQueryメソッドのクエリ文字列が正しくない場合は，IllegalArgumentException例外がスローされます。

createNamedQueryメソッドに指定された名前でクエリが定義されていない場合は，IllegalArgumentException例外がスローされます。

(2)　QueryインタフェースのAPIで発生する例外

QueryインタフェースのAPIで発生する例外を次に示します。

getResultListメソッドで，JPQLのUPDATE文またはDELETE文が呼び出された場合は，IllegalStateException例外がスローされます。

getSingleResultメソッドで，クエリ結果がない場合は，NoResultException例外がスローされます。なお，クエリ結果が二つ以上ある場合は，NonUniqueResultException例外がスローされます。JPQLのUPDATE文，またはDELETE文が呼び出された場合は，IllegalStateException例外がスローされます。

executeUpdateメソッドで，JPQLのSELECT文が呼び出された場合は，IllegalStateException例外がスローされます。このとき，トランザクションがない場合は，TransactionRequiredException例外がスローされます。

setHintメソッドの第2引数が実装に対して正しくない場合は，IllegalArgumentException例外がスローされます。

setParameterメソッドの引数の位置がクエリの位置パラメタと一致しない場合，または引数のパラメタ名がクエリ文字列のパラメタと一致しない場合は，IllegalArgumentException例外がスローされます。

setMaxResultsまたはsetFirstResultメソッドの引数が負数の場合は，IllegalArgumentException例外がスローされます。

なお，APIの詳細については，Javaのドキュメントを参照してください。

6.18　persistence.xmlの定義

この節では，persistence.xmlの定義について，Cosminexus JPAプロバイダ独自の機能であるエンティティオブジェクトのキャッシュ機能の定義と，データソースの指定の注意を説明します。

＜この節の構成＞

(1)　エンティティオブジェクトのキャッシュ機能の定義

(2)　データソースの指定の注意

(1)　エンティティオブジェクトのキャッシュ機能の定義

Cosminexus JPAプロバイダで提供するエンティティオブジェクトのキャッシュ機能の定義は，persistence.xmlの<property>タグ内に指定します。persistence.xmlでのエンティティオブジェクトのキャッシュ機能の定義について次の表に示します。

表6-26　persistence.xmlでのエンティティオブジェクトのキャッシュ機能の定義

指定するプロパティ | 設定内容
cosminexus.jpa.cache.size.<ENTITY> | エンティティをキャッシュする場合のキャッシュサイズを指定します。
cosminexus.jpa.cache.size.default | エンティティをキャッシュする場合のキャッシュサイズのデフォルトを指定します。
cosminexus.jpa.cache.type.<ENTITY> | エンティティのキャッシュタイプを指定します。
cosminexus.jpa.cache.type.default | エンティティのキャッシュタイプのデフォルトを指定します。
cosminexus.jpa.target-database | 接続するデータベースの名前を指定します。

タグの詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「6.2.2　<property>タグに指定できるCosminexus JPAプロバイダ独自のプロパティ」を参照してください。

参考

ここで説明しているプロパティは，Cosminexus JPAプロバイダ独自のプロパティです。persistence.xmlには，このほかにJPA仕様で定義されたプロパティを指定することができます。ただし，Cosminexus JPAプロバイダの場合，JPA仕様で規定されているjavaxから始まるプロパティは使用できません。

(2)　データソースの指定の注意

persistence.xmlでのデータソースの指定では，アプリケーションサーバの機能であるユーザ指定名前空間機能を使用して，リソースアダプタに別名を付けることができます。persistence.xmlの設定でリソースアダプタに別名を設定した場合は，Connector属性ファイルでもリソースアダプタの別名の定義が必要です。詳細については，「6.19　実行環境での設定」を参照してください。

6.19　実行環境での設定

Cosminexus JPAプロバイダを使用する場合，J2EEサーバの設定およびDB Connectorの設定が必要です。

＜この節の構成＞

(1)　J2EEサーバの設定

(2)　DB Connectorの設定

(1)　J2EEサーバの設定

J2EEサーバの設定は，簡易構築定義ファイルで実施します。Cosminexus JPAプロバイダが出力するログファイルの設定は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。

簡易構築定義ファイルでのCosminexus JPAプロバイダが出力するログファイルの設定について次の表に示します。

表6-27　簡易構築定義ファイルでのCosminexus JPAプロバイダが出力するログファイルの設定

指定するパラメタ | 設定内容
ejbserver.logger.channels.define.JPAOperationLogFile.filenum | 稼働ログの面数を指定します。
ejbserver.logger.channels.define.JPAMaintenanceLogFile.filenum | 保守ログの面数を指定します。
ejbserver.logger.channels.define.JPAOperationLogFile.filesize | 稼働ログのサイズを指定します。
ejbserver.logger.channels.define.JPAMaintenanceLogFile.filesize | 保守ログのサイズを指定します。
cosminexus.jpa.logging.level.operation.<category> | 稼働ログのログレベルを指定します。

簡易構築定義ファイルおよび指定するパラメタの詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「4.6　簡易構築定義ファイル」を参照してください。

(2)　DB Connectorの設定

DB Connectorの設定は，サーバ管理コマンドおよびConnector属性ファイルで実施します。

Connector属性ファイルでの設定について次の表に示します。

表6-28　Connector属性ファイルでの設定

指定するタグ
設定内容

<resource-external-property>－<optional-name>タグ
persistence.xmlのデータソースの指定でリソースアダプタの別名を使用している場合，リソースアダプタの別名を設定します。persistence.xmlでリソースアダプタの別名を使用しない場合は設定不要です。

<resource-external-property>－<res-auth>タグ
persistence.xmlのデータソースの指定でリソースアダプタの別名を使用している場合，リソースの認証方式として必ず「Container」を指定してください。

<resource-external-property>－<res-sharing-scope>タグ
persistence.xmlのデータソースの指定でリソースアダプタの別名を使用している場合，リソース接続を共有するかどうかの指定として必ず「Shareable」を指定してください。

<property>－<property-name>タグ
<property>－<property-value>タグ
データベースへの接続情報を指定します。

ユーザ名の指定
<property-name>タグにUserを，<property-value>タグにデータベース接続で使用するユーザ名を指定します。

パスワードの指定
<property-name>タグにPasswordを，<property-value>タグにデータベース接続で使用するパスワードを指定します。

<connection-definition>－<transaction-support>タグ
トランザクションのサポートレベルを指定します。ここに指定する値は，persistence.xmlの<persistence-unit>タグのtransaction-type属性に指定した値と合わせてください。

Connector属性ファイルおよび指定するタグの詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1　Connector属性ファイル」を参照してください。

7.　Cosminexus JMSプロバイダ

この章では，Cosminexus JMSプロバイダを使用してメッセージを送受信する機能について説明します。Cosminexus JMSプロバイダは，JMS仕様に準拠したメッセージの送受信を実現するための機能です。

＜この章の構成＞

7.1　この章の構成

7.2　Cosminexus JMSプロバイダの概要

7.3　CJMSPリソースアダプタとCJMSPブローカーの配置

7.4　メッセージングモデルの種類

7.5　メッセージの構成

7.6　メッセージセレクターによる受信メッセージの選択

7.7　メッセージ配信の高信頼性確保の仕組み

7.8　CJMSPブローカーの機能

7.9　CJMSPリソースアダプタの機能

7.10　Message-driven Beanの呼び出し

7.11　アプリケーション実装時の制限事項

7.12　DDでの定義

7.13　実行環境の構築の流れ

7.14　CJMSPブローカーの設定

7.15　CJMSPリソースアダプタの設定

7.16　J2EEアプリケーションの設定

7.17　Cosminexus JMSプロバイダを使用する場合のシステムの開始と停止

7.18　障害対応用の情報の確認

7.19　Cosminexus JMSプロバイダ使用時の注意事項

7.1　この章の構成

この章では，Cosminexus JMSプロバイダの機能について説明します。

この章の構成を次の表に示します。

表7-1　この章の構成（Cosminexus JMSプロバイダ機能）

分類 | タイトル | 参照先
解説 | Cosminexus JMSプロバイダの概要 | 7.2
CJMSPリソースアダプタとCJMSPブローカーの配置 | 7.3
メッセージングモデルの種類 | 7.4
メッセージの構成 | 7.5
メッセージセレクターによる受信メッセージの選択 | 7.6
メッセージ配信の高信頼性確保の仕組み | 7.7
CJMSPブローカーの機能 | 7.8
CJMSPリソースアダプタの機能 | 7.9
Message-driven Beanの呼び出し | 7.10
実装 | アプリケーション実装時の制限事項 | 7.11
DDでの定義 | 7.12
設定 | 実行環境の構築の流れ | 7.13
CJMSPブローカーの設定 | 7.14
CJMSPリソースアダプタの設定 | 7.15
J2EEアプリケーションの設定 | 7.16
運用 | Cosminexus JMSプロバイダを使用する場合のシステムの開始と停止 | 7.17
障害対応用の情報の確認 | 7.18
注意事項 | Cosminexus JMSプロバイダ使用時の注意事項 | 7.19

7.2　Cosminexus JMSプロバイダの概要

この節では，Cosminexus JMSプロバイダの概要について説明します。

＜この節の構成＞

7.2.1　Cosminexus JMSプロバイダとは

7.2.2　Cosminexus JMSプロバイダのアプリケーションサーバ内での位置づけ

7.2.3　Cosminexus JMSプロバイダの機能の概要

7.2.1　Cosminexus JMSプロバイダとは

Cosminexus JMSプロバイダは，メッセージの送受信を実現するためのアプリケーションサーバの機能です。JMS 1.1の仕様に準拠しています。

Cosminexus JMSプロバイダで送受信するメッセージは，プロデューサーによって作成され，送信されます。送信されたメッセージは，Cosminexus JMSプロバイダが管理する送信先（キューまたはトピック）に登録されます。その後，コンシューマーに配信され，処理が実行されます。

Cosminexus JMSプロバイダを使用したメッセージの送受信の概要を次の図に示します。

図7-1　Cosminexus JMSプロバイダを使用したメッセージの送受信の概要

送信先を介してメッセージをやり取りする仕組みによって，メッセージの送信側と受信側での非同期処理を実現します。

7.2.2　Cosminexus JMSプロバイダのアプリケーションサーバ内での位置づけ

Cosminexus JMSプロバイダは，CJMSPブローカーとCJMSPリソースアダプタという二つのコンポーネントで構成されます。CJMSPブローカーは，メッセージの送信先の管理をするためのコンポーネントです。J2EEサーバとは別のプロセスとして動作します。CJMSPリソースアダプタは，J2EEサーバからCJMSPブローカーに接続するためのリソースアダプタです。

これらのコンポーネントは，Cosminexusのアプリケーションサーバだけで使用できます。

Cosminexus JMSプロバイダのアプリケーションサーバ内での位置づけについて，次の図に示します。

図7-2　Cosminexus JMSプロバイダのアプリケーションサーバ内での位置づけ

Cosminexus JMSプロバイダを使用するJ2EEアプリケーションは，サーブレット，JSP，Enterprise Beanなどで構成されます。J2EEアプリケーションは，CJMSPリソースアダプタを経由して，CJMSPブローカーの機能を使用します。

Cosminexus JMSプロバイダを使用してメッセージを送受信するプロデューサーおよびコンシューマーには，J2EEサーバ上のJ2EEアプリケーションが該当します。メッセージの送信側であるプロデューサーでは，サーブレット，JSP，Enterprise Beanなどが動作します。また，受信側であるコンシューマーでは，Message-driven Beanが動作します。送信側と受信側のJ2EEサーバが別のマシンにある場合は，両方のマシンにCJMSPリソースアダプタが必要です。

なお，JMSの機能を使用するJ2EEアプリケーションをJMSアプリケーションともいいます。

7.2.3　Cosminexus JMSプロバイダの機能の概要

Cosminexus JMSプロバイダでは，JMS仕様に準拠したメッセージ送受信を実現するための機能や，送受信を効率的に実現するための管理機能や監視機能などを提供しています。

Cosminexus JMSプロバイダの機能の概要を次の表に示します。機能の詳細については，参照先の説明を参照してください。

表7-2　Cosminexus JMSプロバイダの機能

機能
概要
参照先

JMS仕様に準拠したメッセージの送受信
PTPメッセージングモデルまたはPub/SubメッセージングモデルでJMSメッセージを送受信します。Pub/Subメッセージングモデルでは，永続化サブスクライバーも使用できます。
受信側では，メッセージセレクターを使用して受信するメッセージを選択できます。

メッセージングモデルの種類

7.4

メッセージの構成

7.5

メッセージセレクターによる受信メッセージの選択

7.6

メッセージ配信の高信頼性確保の仕組み
JTAトランザクションの利用や，メッセージの種類ごとの流量制御の実施によって，メッセージ配信の高信頼性を確保します。
7.7

CJMSPブローカーの機能
メッセージの送信先を管理します。また，永続化したメッセージも管理します。
そのほか，CJMSPブローカーは，コネクションやルーティングの管理や，性能監視などをするための機能も備えています。
7.8

CJMSPリソースアダプタの機能
J2EEサーバ上のJ2EEアプリケーションとCJMSPブローカーを接続します。
7.9

Message-driven Beanの呼び出し
Message-driven Beanをメッセージのコンシューマーとして，業務を実行します。
7.10

このほか，Cosminexus JMSプロバイダでは，実運用時に必要な運用管理のための機能や障害に対応するための機能も備えています。これらの機能によって，信頼性の高いメッセージングシステムを構築・運用できます。

7.3　CJMSPリソースアダプタとCJMSPブローカーの配置

この節では，CJMSPリソースアダプタとCJMSPブローカーの配置について説明します。CJMSPリソースアダプタとCJMSPブローカーは，同じマシンまたは異なるマシンに配置できます。

一つのCJMSPブローカーに対して，CJMSPリソースアダプタは複数配置できます。ただし，一つのJ2EEサーバにデプロイできるCJMSPリソースアダプタは一つです。

CJMSPリソースアダプタおよびCJMSPブローカー以外のコンポーネントの配置については，マニュアル「Cosminexus アプリケーションサーバ システム設計ガイド」の「3.8　サーバ間で非同期通信をする場合の構成を検討する」を参照してください。なお，CJMSPブローカーが管理する永続化メッセージは，CJMSPブローカーと同じマシンにファイルとして保存されます。

＜この節の構成＞

7.3.1　一つのCJMSPリソースアダプタに対して一つのCJMSPブローカーを配置する構成

7.3.2　複数のCJMSPリソースアダプタに対して一つのCJMSPブローカーを配置する構成

7.3.1　一つのCJMSPリソースアダプタに対して一つのCJMSPブローカーを配置する構成

CJMSPリソースアダプタとCJMSPブローカーを一つずつ配置する構成です。CJMSPブローカーは，J2EEサーバと同じマシンまたは異なるマシンに配置します。CJMSPブローカーが管理する永続化メッセージおよび管理情報はファイルで管理されます。

一つのCJMSPリソースアダプタに対して一つのCJMSPブローカーを配置する構成を次の図に示します。

図7-3　一つのCJMSPリソースアダプタに対して一つのCJMSPブローカーを配置する構成

7.3.2　複数のCJMSPリソースアダプタに対して一つのCJMSPブローカーを配置する構成

複数のCJMSPリソースアダプタに対して一つのCJMSPブローカーを配置する構成です。CJMSPブローカーは，J2EEサーバと同じマシンまたは異なるマシンに配置します。CJMSPリソースアダプタは，J2EEサーバごとに一つデプロイできます。

この構成では，複数のCJMSPリソースアダプタによって，一つのCJMSPブローカーが管理する送信先やリソースが共有されます。CJMSPブローカーが管理する永続化メッセージおよび管理情報はファイルで管理されます。

複数のCJMSPリソースアダプタに対して一つのCJMSPブローカーを配置する構成を次の図に示します。

図7-4　複数のCJMSPリソースアダプタに対して一つのCJMSPブローカーを配置する構成

7.4　メッセージングモデルの種類

メッセージの送受信の方法は，メッセージングモデルによって異なります。

Cosminexus JMSプロバイダでは，次の2種類のメッセージングモデルに対応しています。

PTPメッセージングモデル

Pub/Subメッセージングモデル

ここでは，それぞれのメッセージングモデルでのメッセージ送受信の概要について説明します。

なお，これらのメッセージングモデルは，JMS仕様に準拠しています。

＜この節の構成＞

7.4.1　PTPメッセージングモデル

7.4.2　Pub/Subメッセージングモデル

7.4.1　PTPメッセージングモデル

PTPメッセージングモデルは，ポイント・ツー・ポイント（Point-to-Point）方式でメッセージを送受信するためのモデルです。

＜この項の構成＞

(1)　PTPメッセージングモデルによるメッセージの送受信

(2)　PTPメッセージングモデルの特徴

(1)　PTPメッセージングモデルによるメッセージの送受信

PTPメッセージングモデルでは，メッセージを作成して送信する送信側のクライアント（プロデューサー）をセンダーといいます。また，メッセージを受信する側のクライアント（コンシューマー）をレシーバーといいます。

センダーから送信されたメッセージは，キューという送信先に登録されます。キューに格納されたメッセージは，レシーバーが受け取ると，キューから削除されます。

PTPメッセージングモデルでのメッセージの流れを次の図に示します。

図7-5　PTPメッセージングモデルでのメッセージの流れ

メッセージは，センダーから送信され，キューに登録されます。キューに登録されたメッセージは，その時に起動しているレシーバーのどれかに配信されます（メッセージ1，メッセージ2）。レシーバーに配信されたメッセージは，キューから削除されます。配信先のレシーバーがない場合，メッセージはキューに滞留します（メッセージ3）。

なお，メッセージが登録されたキューの状態は，JMS仕様で規定されているキューブラウザーを使用して確認できます。キューブラウザーについては，JMS仕様を参照してください。

(2)　PTPメッセージングモデルの特徴

PTPメッセージングモデルの特徴を次に示します。

メッセージの送信～処理実行までの特徴

PTPメッセージングモデルでのメッセージの送信から処理実行までの特徴について説明します。

一つまたは複数のセンダーからキューにメッセージを送信できます。

レシーバーは，メッセージを送信したセンダーがどれかに関係なく，メッセージを受け取り，処理します。

一つのメッセージは，一つのレシーバーだけで処理されます。

センダーとレシーバーが処理を実行するタイミングに依存性はありません。センダーがメッセージを送信したときにレシーバーが起動していなくても，レシーバーは次に起動したときにメッセージを受け取ることができます。

複数のレシーバーが同じキューからメッセージを受け取る場合に，メッセージの順序性が重要でないときには，それぞれのレシーバーで処理が実行されます。

メッセージは，センダーが送信した順序でキューに登録されます。

メッセージの処理順序は，メッセージの有効期限，メッセージに設定された優先順位，およびレシーバーが使用しているメッセージセレクターによって決定され，この順序に従ってレシーバーが呼び出されます。

レシーバーがまったく起動していない場合，送信されたメッセージはキューで保管されます。

システムの特徴

センダーとレシーバーは，動的に追加・削除できます。これによって，使用状況に応じてシステムを拡張，縮小できます。

Cosminexus JMSプロバイダとの接続で使用するコネクションは，複数のセンダーで共有できます。また，Cosminexus JMSプロバイダが管理するコネクションは，複数のレシーバーで共有できます。例えば，センダー1とセンダー2でコネクションを共有したり，レシーバー1とレシーバー2でコネクションを共有したりできます。コネクションについては，「7.8.1　コネクションサービス」を参照してください。

7.4.2　Pub/Subメッセージングモデル

Pub/Subメッセージングモデルは，パブリッシュ・サブスクライブ（Publish-Subscribe）方式でメッセージを送受信するためのモデルです。

＜この項の構成＞

(1)　Pub/Subメッセージングモデルによるメッセージの送受信

(2)　Pub/Subメッセージングモデルの特徴

(3)　永続化サブスクライバーの利用

(1)　Pub/Subメッセージングモデルによるメッセージの送受信

Pub/Subメッセージングモデルでは，メッセージを作成して送信する送信側のクライアント（プロデューサー）をパブリッシャーといいます。また，メッセージを受信する側のクライアント（コンシューマー）をサブスクライバーといいます。

パブリッシャーから送信されたメッセージは，トピックという送信先に登録されます。トピックに登録されたメッセージは，そのトピックに対して配信を申し込んでいた一つまたは複数のサブスクライバーに配信されます。

Pub/Subメッセージングモデルでのメッセージの流れを次の図に示します。

図7-6　Pub/Subメッセージングモデルでのメッセージの流れ

メッセージは，パブリッシャーから送信され，トピックに登録されます。図の場合，トピック1にはサブスクライバー1，トピック2にはサブスクライバー2とサブスクライバー3が登録されています。このとき，トピック1に登録されたメッセージ1とメッセージ2はサブスクライバー1に配信されます。トピック2に登録されたメッセージ3はサブスクライバー2とサブスクライバー3に配信されます。

(2)　Pub/Subメッセージングモデルの特徴

Pub/Subメッセージングモデルの特徴を次に示します。

メッセージの送信～処理実行までの特徴

一つまたは複数のパブリッシャーから，メッセージをトピックに登録できます。

一つまたは複数のサブスクライバーが，トピックからメッセージを取り出して処理できます。

サブスクライバーは，配信を申し込んだトピックに登録されたすべてのメッセージについて，受信して処理できます。ただし，メッセージセレクターで設定した基準に該当しないメッセージ，または受信する前にメッセージの有効期限が過ぎたメッセージについては受信できません。

メッセージは，パブリッシャーが送信した順序でトピックに登録されます。ただし，サブスクライバーで処理される順序は，それぞれのメッセージの有効期限，優先順位，またはサブスクライバーで設定されたメッセージセレクターの内容によって決まります。

パブリッシャーとサブスクライバーが処理を実行するタイミングには依存性があります。トピックに登録されたメッセージは，メッセージが登録される前に開始されていたサブスクライバーだけに配信されます。

サブスクライバーの属性に「NoLocal」を指定した場合，サブスクライバーが使用しているコネクションと同じコネクションで送信されたメッセージの受信を抑止できます。この属性のデフォルトは「false」です。

システムの特徴

パブリッシャーとサブスクライバーは動的に追加・削除できます。これによって，使用状況に応じてシステムを拡張，縮小できます。

Cosminexus JMSプロバイダとの接続で使用するコネクションは，複数のプロデューサーで共有できます。なお，コネクションを共有しているかどうかに関係なく，複数のプロデューサーから同じのトピックにメッセージを送信できます。

Cosminexus JMSプロバイダとの接続で使用するコネクションは，複数のサブスクライバーで共有できます。なお，コネクションを共有しているかどうかに関係なく，複数のサブスクライバーから同じトピックに接続できます。

(3)　永続化サブスクライバーの利用

トピックに登録されたメッセージは，メッセージ登録時に開始されていたサブスクライバーだけが受信できます。通常のサブスクライバーは，停止していた期間に登録されたメッセージは受信できません。

これに対して，サブスクライバーを永続化することで，停止していた期間に登録されたメッセージも受信できるようになります。永続化したサブスクライバーを永続化サブスクライバーといいます。

永続化サブスクライバーが登録されたトピックのメッセージは，次のどちらかの状態になるまで削除されません。

永続化サブスクライバーに配信された場合

メッセージの有効期限が過ぎた場合

永続化サブスクライバーを利用する場合，そのサブスクライバーに固有の識別子と名称を登録します。登録した情報は，CJMSPブローカーによって保持されます。永続化サブスクライバーが停止しているときに登録されたメッセージは，登録した識別子および名称のサブスクライバーが再開されたときに，そのサブスクライバーに配信されます。

永続化サブスクライバーを利用した場合のメッセージの送受信の流れを次の図に示します。

図7-7　永続化サブスクライバーを利用した場合のメッセージの送受信の流れ

永続化サブスクライバーを利用した場合のメッセージの送受信の流れについて説明します。なお，説明の番号は図中の番号と対応しています。

サブスクライバー1を永続化サブスクライバーとしてトピックに登録します。
識別子（ClientID）は，「1」とします。

パブリッシャー1が，メッセージ1をトピックに登録します。

サブスクライバー1は，メッセージ1をトピックから受信します。

サブスクライバー1を停止します。
停止した状態になると，トピックに登録されたメッセージは受信できません。

パブリッシャー2が，メッセージ2をトピックに登録します。サブスクライバー1は停止中のため，メッセージ2を受信できません。ただし，サブスクライバー1は永続化サブスクライバーとして登録されているため，このメッセージは登録された永続化サブスクライバーがメッセージを受信するまでトピックで保管されます。

サブスクライバー2を永続化サブスクライバーとしてトピックに登録します。このとき，識別子（ClientID）を「1」として，サブスクライバーの名称はサブスクライバー1と同じ値にします。
永続化サブスクライバーの情報を保持しているCJMSPブローカーは，識別子と名称からサブスクライバー2は登録済みの永続化サブスクライバーが再開したものと判断します。

トピックに保管されていたメッセージ2がサブスクライバー2に配信されます。

永続化サブスクライバーの指定を解除する場合は，次のどちらかの方法で解除してください。

cjmsicmd destroy durコマンドを実行する

unsubscribeメソッドを使用する

cjmsicmd destroy durコマンドについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjmsicmd destroy dur（永続化サブスクライバーの破棄）」を参照してください。

unsubscribeメソッドを使用すると，サブスクライバーのために保持されたトピックの状態を解除できます。ただし，このメソッドは，次のタイミングでは使用しないでください。

永続化サブスクライバーの指定を解除する対象のトピックに対して，開始されているサブスクライバーがある場合

トピックに配信されたメッセージが，未決着のトランザクションである場合

そのセッションでの配信が承認されていない場合

なお，確認応答モードが「CLIENT_ACKNOWLEDGE」のセッションによって永続化サブスクライバーが作成された場合に，メッセージ受信が確認されていない状態でunsubscribeメソッドが実行されたときには，メッセージは送信先に残ってしまいます。この状況を避けるため，unsubscribeメソッドを使用する場合，事前にcjmsicmd purge durコマンドを実行して，永続化サブスクライバーに関連づけられているすべてのメッセージを削除してください。

注意

一時的な送信先として作成したトピックに対して，永続化サブスクライバーは登録できません。作成しようとすると，例外がスローされます。

7.5　メッセージの構成

Cosminexus JMSプロバイダで扱うメッセージは，次に示す要素で構成されます。

メッセージヘッダー

メッセージプロパティ

メッセージボディ

これらの要素については，JMSの仕様として規定されています。詳細は，JMSの仕様を参照してください。

7.6　メッセージセレクターによる受信メッセージの選択

コンシューマーは，受信するメッセージをメッセージセレクターによって選択できます。メッセージセレクターを使用したコンシューマーでは，送信先に登録されたメッセージのうち，必要なものだけを受信できます。

メッセージセレクターでは，選択対象の指定にメッセージプロパティの値を使用します。コンシューマーは，メッセージセレクターに指定した選択条件とメッセージプロパティの値を比較し，条件に一致するメッセージだけを受信します。

メッセージセレクターを使用した受信メッセージの選択の概要を次の図に示します。

図7-8　メッセージセレクターを使用した受信メッセージの選択の概要

この図では，コンシューマー2に「Color=red」という選択条件を指定しています。コンシューマー1にはメッセージセレクターは指定しません。

プロデューサーからColorプロパティが異なる四つのメッセージを送信した場合，メッセージセレクターを使用していないコンシューマー1はすべてのメッセージを受信します。コンシューマー2は選択条件に一致する二つのメッセージだけを受信します。

なお，メッセージセレクターの選択条件は，コンシューマーで動作するMessage-driven Beanの属性，またはJMSのAPIで指定します。属性の詳細については，「7.12　DDでの定義」を参照してください。また，選択条件の構文およびAPIについては，JMS仕様を参照してください。

参考

メッセージセレクターは，キューブラウザーでも使用できます。

7.7　メッセージ配信の高信頼性確保の仕組み

この節では，Cosminexus JMSプロバイダを使用したメッセージ配信で高信頼性を確保するための仕組みについて説明します。

＜この節の構成＞

7.7.1　メッセージ配信時に発生するトラブルの種類と信頼性を確保する方法

7.7.2　トランザクションの利用

7.7.3　メッセージの流量制御

7.7.1　メッセージ配信時に発生するトラブルの種類と信頼性を確保する方法

メッセージは，次の2段階で配信されます。

プロデューサーからCJMSPブローカーが管理する送信先への配信

CJMSPブローカーが管理する送信先からコンシューマーへの配信

この間，次のタイミングでトラブルが発生した場合に，メッセージが失われるおそれがあります。

メッセージ転送時

プロデューサーからCJMSPブローカーが管理する送信先へのメッセージ転送時

CJMSPブローカーが管理する送信先からコンシューマーへのメッセージ転送時

CJMSPブローカーの障害発生時

これらの場合に信頼性を確保する方法について，次に示します。

メッセージ転送時にトラブルが発生した場合
メッセージ転送時のメッセージの信頼性を確保する方法としては，JMS仕様で規定されている，メッセージ配信の確認応答（Acknowledge Mode）の仕組みを使用できます。
また，トランザクションの利用によって，メッセージの送信から受信までにトラブルが発生した場合に，システムの整合性を保つことができます。

CJMSPブローカーに障害が発生した場合
CJMSPブローカーに障害が発生した場合に送信先に登録されていたメッセージを保持するためには，メッセージを永続化しておくことが必要です。Cosminexus JMSプロバイダでは，メッセージをファイルに保存して永続化できます。

この節では，これらの方法のうち，トランザクションの利用によって信頼性を確保する方法について，「7.7.2　トランザクションの利用」で説明します。

また，メッセージ配信時には，送受信されるメッセージの量によって，メモリリソースの問題が発生することもあります。メモリリソースを適切に運用するためにメッセージの流量を制御する方法については，「7.7.3　メッセージの流量制御」で説明します。

なお，メッセージ配信の確認応答の詳細については，JMS仕様を参照してください。なお，CJMSPブローカーによるファイルの永続化については，「7.8.4　管理情報およびメッセージの永続化サービス」で説明します。

7.7.2　トランザクションの利用

トランザクションを利用すると，メッセージの作成から処理の実行までを一連の処理としてまとめることができます。トランザクションに含まれるすべての操作は，クライアント側のアプリケーション（メッセージを送信したアプリケーション）がトランザクションをコミットしたときに完了します。

Cosminexus JMSプロバイダでは，JTAトランザクションを利用できます。

JTAトランザクションは，アプリケーションサーバのトランザクション管理用API（JTA）によって管理されます。トランザクション内の操作が失敗した場合，アプリケーションサーバによって例外が処理され，トランザクション内の処理がリトライまたはロールバックされます。ローカルトランザクションの管理には，BMTまたはCMTを使用できます。BMTまたはCMTによるトランザクションの管理については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.7　Enterprise Beanでのトランザクション管理」を参照してください。

注意

Cosminexus JMSプロバイダでは，JTAトランザクションを利用する場合，コンテナがBeanの代わりにJMSセッションのトランザクションを管理します。このため，次のメソッドの引数「transacted」の値に「true」は指定しないでください。

createSession(boolean transacted, int acknowledgeMode)メソッド

createQueueSession(boolean transacted, int acknowledgeMode)メソッド

createTopicSession(boolean transacted, int acknowledgeMode)メソッド

「true」を指定した場合は，無視され，警告メッセージが出力されます。

なお，EJBアプリケーションを使用する場合，トランザクション内でJMSの承認メソッドを使用しないでください。承認メソッドを指定していないトランザクションコンテキスト内では，コンテナによってメッセージの承認が管理されます。

また，一つのトランザクション内で，大量のメッセージを送信すると,メッセージの配信確認に関する情報を管理しているファイルの容量が増え，ディスク容量を圧迫するおそれがあります。大量のメッセージを送信する場合，性能テストを実施して，必要なファイルサイズを見積もってください。

7.7.3　メッセージの流量制御

ここでは，メッセージの流量制御について説明します。

Cosminexus JMSプロバイダを使用したメッセージの送受信では，プロデューサーからコンシューマーに送信するメッセージのほか，Cosminexus JMSプロバイダが使用する制御用のメッセージも送受信されます。これらのメッセージの送受信は，お互いに影響します。例えば，プロデューサーからコンシューマーに送信したメッセージに対するCJMSPブローカーでの確認応答の承認が遅れた場合などは，制御用のメッセージの送受信も遅れてしまうことになり，システム全体のパフォーマンスが低下してしまいます。

コネクション上のこれらのメッセージの流量を制御することで，メッセージ送受信の信頼性を高め，システムのパフォーマンスを向上させることができます。

Cosminexus JMSプロバイダでは，メッセージの流量を制御するために，コンシューマーごとに送信するメッセージの流量を制限できます。

例えば，PTPメッセージングモデルでメッセージを送受信している場合，それぞれのコンシューマーの処理速度が低いときには，コンシューマー単位に配信するメッセージを制限します。これによって，複数のコンシューマーを使用してラウンドロビン方式で処理を実行し，システム全体の処理性能を向上させることができます。コンシューマー単位のメッセージの流量には，複数のコンシューマーに分散してメッセージを配信するためのオーバーヘッドの増加との関係を考慮して，適切な値を決定してください。

コンシューマー単位の制限値（consumerFlowLimit）については，送信先ごとにcjmsicmd create dstコマンドで設定します。コマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjmsicmd create dst（物理的送信先の作成）」を参照してください。なお，consumerFlowLimitの値は，コンシューマーで動作しているMessage-driven Bean単位の同時実行数（プールの最大インスタンス数）との関係も考慮して設定する必要があります。設定のパターンの例を次に示します。

「consumerFlowLimitの値＜Message-driven Beanのプールの最大インスタンス数」と設定した場合

Message-driven Beanでは，consumerFlowLimitで指定した数のスレッドで処理が実行されます。

「consumerFlowLimitの値＝Message-driven Beanのプールの最大インスタンス数」と設定した場合

プロデューサーから送信されたメッセージの数がconsumerFlowLimit以下の場合は，一つのコンシューマーですべての処理が実行されます。

プロデューサーから送信されたメッセージの数がconsumerFlowLimitを超える場合は，複数のコンシューマーで処理が実行されます。

consumerFlowLimitの設定による流量制御の概要を次の図に示します。

図7-9　consumerFlowLimitの設定による流量制御の概要

この例では，コンシューマー単位の制限値として，consumerFlowLimitを「10」と設定しています。プロデューサーから12個のメッセージが送信された場合，送信先からコンシューマー1には制限値である10個のメッセージが送信され，残りのメッセージはコンシューマー2に送信されます。各コンシューマーでは，Message-driven Beanの最大インスタンス数で設定した数以下のスレッドを使用して処理が実行されます。

7.8　CJMSPブローカーの機能

この節では，CJMSPブローカーの機能について説明します。

CJMSPブローカーの主な機能を次に示します。

コネクションサービス

送信先の管理とルーティングサービス

CJMSPブローカーの性能監視

管理情報とメッセージの永続化サービス

なお，このほか，CJMSPブローカーはログ出力の機能も備えています。CJMSPブローカーのログ出力については，「7.18　障害対応用の情報の確認」を参照してください。

＜この節の構成＞

7.8.1　コネクションサービス

7.8.2　送信先の管理とルーティングサービス

7.8.3　CJMSPブローカーの性能監視

7.8.4　管理情報およびメッセージの永続化サービス

7.8.1　コネクションサービス

コネクションサービスは，TCP層上でのCJMSPブローカーとCJMSPリソースアダプタの接続（jmsコネクション），およびCJMSPブローカーとシステムの管理ユーザの接続（adminコネクション）を管理するためのサービスです。

＜この項の構成＞

(1)　コネクションサービスの種類

(2)　コネクションサービスのスレッドプール管理

(1)　コネクションサービスの種類

Cosminexus JMSプロバイダが提供するコネクションサービスには，次の2種類があります。

jmsサービス
CJMSPリソースアダプタからCJMSPブローカーへの接続を管理するサービスです。メッセージを送受信する際，CJMSPリソースアダプタがCJMSPブローカーに接続するときにこのサービスを使用します。

adminサービス
システムの管理ユーザからCJMSPブローカーへの接続を管理するサービスです。管理ユーザがコマンドの実行によって次のような操作をする場合にこのサービスを使用します。

物理的送信先の作成

送信先またはCJMSPブローカーの問い合わせ

コネクションサービスでは，ポートマッパーによって静的または動的に割り当てられた，専用のポートを使用します。

ポートマッパーによるコネクションサービスへのポートの割り当ての概要を次の図に示します。

図7-10　コネクションサービスへのポートの割り当ての概要

ポートマッパーは，デフォルトでは7676のポートを使用します。これ以外のポートを使用する場合は，CJMSPブローカーのimq.portmapper.portプロパティで設定してください。

ポートの割り当ての流れを次に示します。

ポートマッパーに対して，CJMSPリソースアダプタからjmsサービスでの接続をするためのリクエストを送信します。または管理ユーザからadminサービスでの接続をするためのリクエストを送信します。

ポートマッパーがコネクションサービスの要求に対して，ポートを動的に割り当てます。ただし，事前にCJMSPブローカーのプロパティとしてimq.jms.tcp.portプロパティまたはimq.admin.tcp.portプロパティを指定した場合は，コネクションサービスごとに指定したポートが割り当てられます。

なお，ポートマッパーがコネクションを接続するためのリクエストを複数同時に受け付けた場合，処理待ちのリクエストはOSのバックログに格納されて待機します。

コネクションサービスで使用する各プロパティの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「7.4　config.properties（CJMSPブローカー個別プロパティファイル）」を参照してください。

(2)　コネクションサービスのスレッドプール管理

コネクションサービスはマルチスレッドで動作するため，複数のコネクションを同時に管理できます。コネクションサービスで使用するスレッドは，CJMSPブローカーが管理するスレッドプールで管理されています。

なお，コネクションサービスのスレッドプールは，処理性能を向上させるために，独自の方式で管理されています。一つのコネクションでは，メッセージ受信用および送信用の二つのスレッドを使用します。

7.8.2　送信先の管理とルーティングサービス

ここでは，CJMSPブローカーによる送信先の管理，およびルーティングサービスについて説明します。

CJMSPブローカーは，物理的な送信先として，キューやトピックをシステムのメモリ内に作成・管理します。

ルーティングサービスは，リソースを効率的に使用しながら，プロデューサー，コンシューマーと送信先間での確実で円滑なメッセージの送受信を実現するためのサービスです。

＜この項の構成＞

(1)　送信先の種類

(2)　送信先の設定と管理

(3)　デッドメッセージキューの管理

(1)　送信先の種類

送信先は，作成方法および存在期間によって，次の2種類に分類できます。

コマンドで作成する送信先

APIで作成される一時的な送信先

それぞれの送信先の特徴について説明します。

コマンドで作成する送信先

システムを管理するユーザがコマンドで明示的に作成した送信先です。

コマンドで作成した送信先は，明示的にコマンドで削除するまで削除されません。

APIで作成される一時的な送信先

J2EEアプリケーション内のAPIによって作成される送信先です。プログラムの中でメッセージの送受信に必要な送信先が作成され，削除されます。一時的な送信先は，送信先を作成したコネクションの中だけで保持されます。また，メッセージの永続化はできず，CJMSPブローカーを再起動しても再作成はされません。

注意

一時的送信先を使用するコンシューマーは，その一時的送信先を作成したコネクションだけで作成できます。

また，通常のメッセージ送受信に使用する送信先以外に，デッドメッセージキューというCJMSPブローカーによって自動的に作成される送信先があります。

デッドメッセージキューは，CJMSPブローカーを最初に起動したタイミングで作成されます。この送信先には，CJMSPブローカーによって，次のメッセージ（デッドメッセージ）が登録されます。

処理できないメッセージ

有効期限を過ぎたメッセージ

デッドメッセージキューには，ほかの送信先で処理できずに廃棄されたメッセージが格納されるため，メッセージ送受信で発生した問題についての調査などに利用できます。

デッドメッセージキューの管理については，「(3)　デッドメッセージキューの管理」を参照してください。

(2)　送信先の設定と管理

CJMSPブローカーでは，送信先を設定・管理するために，次の処理を実行できます。

送信先の作成・休止・再開・削除

すべての送信先の一覧表示

個々のメッセージ，およびCJMSPブローカーで管理するメッセージ全体の制限値管理

メッセージの最大数の管理

送信先の状態およびプロパティの表示

永続化メッセージを格納するディスクの圧縮

デッドメッセージキューの管理

これらの処理は，コマンドで実行できます。詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「5.3　CJMSPブローカー管理のコマンドの詳細」を参照してください。

(3)　デッドメッセージキューの管理

デッドメッセージキューは，すべての送信先で必ず使用する設定になっています。

メッセージがデッドメッセージキューに登録された場合の処理については，メッセージごとのメッセージプロパティに設定します。

メッセージプロパティに設定できる内容を次の表に示します。

表7-3　デッドメッセージキューに登録する際の処理としてメッセージプロパティに設定できる内容

プロパティ
データ型
説明

CJMS_PRESERVE_UNDELIVERED
Boolean
メッセージが配信できなかった場合の処理を設定します。

「true」を設定した場合，メッセージはデッドメッセージキューに登録されます。

「false」を設定した場合，メッセージはデッドメッセージキューには登録されません。

CJMS_LOG_DEAD_MESSAGES
Boolean
メッセージが送信先から削除されてデッドメッセージキューに登録されたことをログに出力するかどうかを設定します。

「true」を設定した場合，ログに出力します。

「false」を設定した場合，ログに出力しません。

CJMS_TRUNCATE_MSG_BODY
Boolean
デッドメッセージキューに登録するメッセージのメッセージボディを削除するかどうかを設定します。

「true」を設定した場合，メッセージボディを削除してからデッドメッセージキューに登録します。

「false」を設定した場合，メッセージボディを削除しないでデッドメッセージキューに登録します。

また，デッドメッセージキューに登録されたデッドメッセージには，CJMSPブローカーによってプロパティが設定されます。設定されたプロパティの情報によって，メッセージがデッドメッセージキューに登録された要因と，要因となった処理を確認できます。

CJMSPブローカーによってデッドメッセージに設定されるプロパティについて，次の表に示します。

表7-4　CJMSPブローカーによってデッドメッセージに設定されるプロパティ

プロパティ
データ型
説明

JMSXDeliveryCount
Integer
特定のコンシューマーに対して配信されたメッセージの最大数が設定されます。
この値は，CJMS_DMQ_UNDELIVERED_REASONプロパティにERRORまたはUNDELIVERABLEと設定されたプロパティの場合にだけ設定されます。

CJMS_DMQ_UNDELIVERED_TIMESTAMP
Long
デッドメッセージキューに登録された時刻がミリ秒で設定されます。

CJMS_DMQ_UNDELIVERED_REASON
String
デッドメッセージキューに登録された要因を示す値が設定されます。設定されるのは次の値です。

OLDEST
最も古いメッセージだったため処理されなかったことを示します。

LOW_PRIORITY
優先順位が低かったため処理されなかったことを示します。

EXPIRED
メッセージの有効期限が過ぎたため処理されなかったことを示します。

UNDELIVERABLE
配信されなかったことを示します。

ERROR
エラーが発生したことを示します。この要因が設定されたメッセージは，内部的な要因で処理ができなかったため，プロデューサーからメッセージを送信し直す必要があります。

なお，複数の要因が該当した場合は，どれか一つの要因だけが設定されます。

CJMS_DMQ_PRODUCING_BROKER
String
このメッセージを作成したCJMSPブローカーの名前およびポート番号が設定されます。「null」が設定された場合は，ローカルで動作するCJMSPブローカーであることを示します。

CJMS_DMQ_DEAD_BROKER
String
デッドメッセージキューを管理しているCJMSPブローカーの名前およびポート番号が設定されます。「null」が設定された場合は，ローカルで動作するCJMSPブローカーであることを示します。

CJMS_DMQ_UNDELIVERED_EXCEPTION
String
例外の発生が原因で配信されなかったメッセージの場合に，アプリケーションまたはCJMSPブローカーで発生した例外名が設定されます。

CJMS_DMQ_UNDELIVERED_COMMENT
String
メッセージが送信されなかった付加的な要因がある場合に設定されます。

CJMS_DMQ_BODY_TRUNCATED
Boolean
デッドメッセージキューへの登録時にメッセージボディが削除されたかどうかが設定されます。
「true」の場合，メッセージボディは削除されています。
「false」の場合，メッセージボディは削除されていません。

7.8.3　CJMSPブローカーの性能監視

CJMSPブローカーでは，CJMSPブローカーの性能情報（メトリクス）を監視できます。

CJMSPブローカーの性能情報には，ヒープサイズ，接続状況，受信メッセージの割合，送信メッセージの割合などの情報が含まれます。これらの情報は，コンソールに表示されて，ログファイルに出力されます。

CJMSPブローカーの性能情報の出力方法は，imq.metrics.intervalプロパティで指定します。このプロパティに指定した出力間隔で性能情報が出力されます。なお，デフォルトの設定は0（出力しない）です。

CJMSPブローカーの性能情報の出力例を次に示します。

KDAN24558-I Displaying broker metrics :
Connections: 10 JVM Heap: 13082624 bytes (1501448 free) Threads: 22 (14-1010)

In: 3001 msgs (631149 bytes) 4297 pkts (795219 bytes)
Out: 1253 msgs (263099 bytes) 5495 pkts (690645 bytes)
Rate In: 298 msgs/sec (62622 bytes/sec) 419 pkts/sec (77978 bytes/sec)
Rate Out: 125 msgs/sec (26271 bytes/sec) 540 pkts/sec (66573 bytes/sec)

出力項目について，次の表に示します。

表7-5　CJMSPブローカーの性能情報に出力される項目

出力項目
説明

Connections
接続状態のコネクション数です。

JVM Heap
使用しているJavaVMのヒープサイズと使用可能なメモリ量です。

Threads
使用されているスレッド数です。
なお，出力例では22となっています。特定の時間だけCJMSPブローカーに接続している場合，使用されているスレッド数は自動で更新されます。
（　）内はスレッドプール値の最小値と最大値です。

最小値（14）

最小のスレッドプール値を示します（jmsサービスの最小値は10，adminサービスの最小値は4です。このため，最小値は14になります）。

最大値（1010）

最大のスレッドプール値を示します（jmsサービスの最大値は1000，adminサービスの最大値は10です。このため，最大値は1010となります）。

In
CJMSPブローカーの受信メッセージ数です。

Out
CJMSPブローカーから送信されたメッセージ数です。

Rate In
CJMSPブローカーの受信メッセージの割合です。また，1秒間のメッセージ数と1秒当たりのメッセージパケットが表示されます。

Rate Out
CJMSPブローカーから送信されたメッセージの割合です。また，1秒間のメッセージ数と1秒当たりのメッセージパケットが表示されます。

7.8.4　管理情報およびメッセージの永続化サービス

CJMSPブローカーに障害が発生した場合，回復には，障害発生前のメッセージ送受信操作の状態を示す情報が必要です。CJMSPブローカーでは，回復に必要な状態についての情報をファイルに保存して管理します。障害が発生した場合，保存された情報を基にCJMSPブローカーの状態を回復して，操作を再開できるため，メッセージ配信の信頼性を確保できます。

CJMSPブローカーは，次のような情報をファイルに保存して管理します。

送信先の情報

永続化サブスクライバーの情報

メッセージの情報

トランザクションの情報

メッセージ配信の確認応答についての情報

障害発生後にCJMSPブローカーを再起動すると，保存していた各情報を基に，送信先と永続化サブスクライバーの再作成，永続化メッセージの回復，トランザクションのロールバックが実施され，未配信のメッセージのためのルートが再作成されます。その後，メッセージ配信が再開されます。

＜この項の構成＞

(1)　管理情報およびメッセージの永続化の仕組み

(2)　ファイルプールの利用

(3)　ファイルへの書き込みのタイミング

(4)　ファイルの格納先

(5)　ファイルのバックアップ

(1)　管理情報およびメッセージの永続化の仕組み

CJMSPブローカーでは，永続化する情報の種類ごとにファイルを作成して管理します。保存用のファイルは，CJMSPブローカーが作成されたときに自動的に作成されます。情報の種類ごとに保存先のファイルは異なります。

しきい値（1メガバイト）以下のサイズのメッセージは，メッセージごとに一つの可変長のファイルに保存されます。また，しきい値を超えるサイズのメッセージは，ファイルプールの複数のファイルで管理されます。ファイルプールの各ファイルのサイズは1メガバイトです。

(2)　ファイルプールの利用

CJMSPブローカーが管理するファイルプールの概要を次の図に示します。

図7-11　CJMSPブローカーが管理するファイルプールの概要

ファイルプールの特徴を次に示します。

不要になったファイルは，フリーファイルとしてファイルプールに返却されます。ファイルプールは，送信先ごとに管理されています。

ファイルプールで管理するファイル数の最大値は100です。ファイル数が最大値を超えた場合，不要になったファイルはプールに返却されないで削除されます。

ファイルプール内のファイルは，CJMSPブローカーを停止して再起動したあとも残ります。

(3)　ファイルへの書き込みのタイミング

ファイルへのデータの書き込みは，OSの機能で実行します。このとき，書き込みを同期・非同期のどちらで実行するかをimq.persist.file.sync.enabledプロパティで選択できます。なお，デフォルトでは書き込みは非同期で実施されます。

同期書き込み・非同期書き込みの利点と欠点を次の表に示します。

表7-6　ファイルへの同期書き込み・非同期書き込みの利点と欠点

書き込みのタイミング | 利点 | 欠点
非同期 | 書き込み処理による処理性能への影響がありません。 | 障害が発生したときに，一部のデータが失われることがあります。
同期 | 障害発生時点までのデータが保存されているため，障害発生直前の状態からCJMSPブローカーの処理を再開できます。 | 書き込み処理による処理性能への影響があります。

(4)　ファイルの格納先

CJMSPブローカーが管理する永続化データを保存したファイルは，デフォルトでは次のディレクトリに保存されています。なお，varディレクトリの格納先は，cjmsbrokerコマンドの-varhomeオプションで変更できます。

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥cjmsp¥var¥instances¥<CJMSPブローカーの名称>¥fs370

UNIXの場合

/opt/Cosminexus/CC/cjmsp/var/instances/<CJMSPブローカーの名称>/fs370

fs370ディレクトリ下の構成を次に示します。

表7-7　fs370ディレクトリ下の構成

ディレクトリ・ファイル名 | 説明
messageディレクトリ | このディレクトリ下に，送信先名ごとのサブディレクトリが作成されます。それぞれのサブディレクトリ内に，メッセージごとの個別のファイルが格納されています。
interestファイル | コンシューマーの情報が格納されています。
destinationファイル | 送信先の情報が格納されています。
propertyファイル | 内部情報が格納されています。
txnファイル | トランザクションIDが格納されています。
txnackファイル | すべてのトランザクションIDに対する配信確認が格納されています。
configrecordファイル | 内部情報が格納されています。

このディレクトリの内容は，不正にアクセスされないよう，OSのアクセス権などを設定して適切に管理してください。

注意

fs370ディレクトリ下のファイルを移動したり，ファイルの属性を読み取り専用に変更したりしないでください。CJMSPブローカーが正しく動作しなくなるおそれがあります。

ネットワークドライブや，ネットワーク上のファイルを使用することはできません。cjmsbrokerコマンドの-varhomeオプションでvarディレクトリの格納先を変更する場合は，CJMSPブローカーと同じマシン上のディレクトリを選択するようにしてください。

一つのトランザクションの中で大量のメッセージを処理すると，txnackファイルのファイルサイズが大幅に増加することがあります。大量のメッセージを送信する場合，性能テストを実施して，必要なファイルサイズを見積もってください。

(5)　ファイルのバックアップ

永続化データのバックアップを取得する場合は，CJMSPブローカー単位で取得します。varディレクトリ下のinstancesディレクトリをほかの場所にコピーして保存してください。

回復する場合は，まず，CJMSPブローカーを停止します。バックアップしておいたinstancesディレクトリ以下のファイルをvarディレクトリ下に上書きしてから，CJMSPブローカーを再起動してください。

7.9　CJMSPリソースアダプタの機能

CJMSPリソースアダプタは，J2EEサーバとCJMSPブローカーを接続するためのリソースアダプタです。J2EEサーバのWebコンテナまたはEJBコンテナ上で動作するJ2EEアプリケーションとCJMSPブローカー間のメッセージの送受信を実現します。

CJMSPリソースアダプタの動作はConnector属性ファイルに設定します。なお，属性の設定個所に応じて，指定した内容の影響範囲が異なります。指定個所と影響範囲について次の表に示します。

表7-8　Connector属性ファイルの指定個所と指定内容

Connector属性ファイルのタグ※ | 指定内容
<resourceadapter> | CJMSPリソースアダプタ全体の動作に影響する属性を指定します。
<connection-definition> | コネクションインタフェースごとの設定を指定します。

注※　JavaBeanの実装と対応しています。

7.10　Message-driven Beanの呼び出し

Message-driven Beanは，コンシューマーとして動作し，メッセージの非同期処理を実行するためのEnterprise Beanです。送信先にメッセージが到着したタイミングでアクティブになり，メッセージを受け取って処理します。

この節では，コンシューマーであるMessage-driven Beanの動作について説明します。

＜この節の構成＞

7.10.1　Message-driven Beanによるメッセージ処理の特徴

7.10.2　Message-driven Beanを呼び出す流れ

7.10.3　Message-driven Beanで必要な設定

7.10.4　トランザクションコンテキストの設定

7.10.1　Message-driven Beanによるメッセージ処理の特徴

Message-driven Beanは，クライアントアプリケーションであるプロデューサーから直接呼び出すことはできません。プロデューサーは，送信先にメッセージを送信することで，Message-driven Beanを間接的に呼び出します。

Message-driven Beanは基本的に状態を保持せず，また特定のクライアントアプリケーションと関連づけられて処理を実行されることがありません。このため，送信されたメッセージは複数のMessage-driven Beanによって同時に並行処理できます。

注意

Message-driven Beanの複数のインスタンスの同時実行によって，複数のメッセージは並行処理されます。Message-driven Beanクラスのインスタンスによって実行される処理の順序性は保証されません。

大量のメッセージをMessage-driven Beanに配信しようとしたときに，RejectedExecutionException例外が発生することがあります。この例外が発生した場合，一部のメッセージはMessage-driven Beanに配信されません。この状況を避けるためには，CJMSPリソースアダプタの実行時属性として，スレッドプールの最大数をMessage-driven Beanのインスタンス数以上に設定してください。

Message-driven Beanに設定した同時実行インスタンス数の制限によってメッセージの送信が遅れることがあります。この問題を防ぐためには，Message-driven Beanのインスタンス数以上の値をCJMSPリソースアダプタで実行するスレッド数として指定してください。
また，Message-driven Beanのエンドポイント数は，メッセージを並列処理できる数になります。エンドポイント数の制限によって問題が発生するのを防ぐために，エンドポイント数にはMessage-driven Beanのインスタンス数以上の値を指定してください。式を示します。

Message-driven Beanのインスタンス数の総数<=CJMSPリソースアダプタのWorkスレッド数

Message-driven Beanのインスタンス数>=エンドポイントのインスタンス数

なお，Message-driven Beanのインスタンス数は，cosminexus.xmlまたはMessageDrivenBean属性ファイルで定義します。Message-driven Beanのエンドポイント数は，DDで定義します。CJMSPリソースアダプタのスレッド数の定義はConnector属性ファイルで定義します。
cosminexus.xmlの詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「2.　Cosminexusアプリケーション属性ファイル（cosminexus.xml）」を参照してください。MessageDrivenBean属性ファイルの詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「3.6　MessageDrivenBean属性ファイル」を参照してください。Connector属性ファイルの詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1　Connector属性ファイル」を参照してください。

7.10.2　Message-driven Beanを呼び出す流れ

メッセージの送信元となるアプリケーションにとって，Message-driven Beanはメッセージのコンシューマーです。アプリケーションからMessage-driven Beanにとってのメッセージリスナである送信先にメッセージを送信すると， Message-driven Beanがメッセージを受け取り，コンシューマーとして処理を実行します。

メッセージが到着すると，Message-driven Beanのメッセージリスナメソッドであるjavax.jms.MessageListener#onMessageメソッドがJ2EEコンテナによって呼び出されます。メッセージリスナメソッドに含まれるビジネスロジックによって，処理が実行されます。

Message-driven Beanを動作させる流れを次の図に示します。

図7-12　Message-driven Beanを動作させる流れ

なお，送信元のJ2EEアプリケーションのJNDI名前空間には，Message-driven Beanを動作させるための送信先が設定されている必要があります。

Message-driven Beanと送信先であるキューまたはトピックは，Message-driven Beanを含むJ2EEアプリケーションをJ2EEサーバにデプロイしたときに関連づけられます。

7.10.3　Message-driven Beanで必要な設定

Message-driven Beanの動作は，Message-driven Beanの属性として設定します。送信先の情報，メッセージの確認応答モード，およびメッセージセレクターなどが設定できます。属性は，DDまたはMessageDrivenBean属性ファイルの<activation-config>タグで設定します。詳細は，「7.12　DDでの定義」およびマニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「3.6　MessageDrivenBean属性ファイル」を参照してください。

ここでは，主な設定項目について説明します。

＜この項の構成＞

(1)　送信先の設定

(2)　メッセージの確認応答モードの設定

(3)　メッセージセレクターの設定

(1)　送信先の設定

Message-driven Beanと関連づける送信先の種類として，キュー（javax.jms.Queue）またはトピック（javax.jms.Topic）のどちらかを設定します。トピックと設定した場合は，さらに永続化サブスクライバーを使用するかどうかも設定します。

送信先をキューとした場合，または永続化サブスクライバーを使用する設定にした場合は，Message-driven Beanが動作するJ2EEアプリケーションが動作していないときなどには送信先がメッセージを保持します。

送信先をトピックとして永続化サブスクライバーを使用しない設定にした場合は，Message-driven Beanが動作するJ2EEアプリケーションが動作していないときに送信されたメッセージはMessage-driven Beanに配信されません。

送信先の種類や永続化サブスクライバーについては，「7.4　メッセージングモデルの種類」を参照してください。

(2)　メッセージの確認応答モードの設定

メッセージの確認応答モードとして，AUTO_ACKNOWLEDGEまたはDUPS_OK_ACKNOWLEDGEのどちらかを設定します。それぞれのモードの詳細については，JMS仕様を参照してください。

メッセージの確認応答は，コンテナが実行します。トランザクションをCMTで管理している場合，確認応答はトランザクションをコミットする処理の一部として実行されます。BMTで管理している場合は，トランザクションとは別に，コンテナによって承認処理が実行されます。なお，確認応答をAPIで実行する実装はしないでください。

(3)　メッセージセレクターの設定

メッセージセレクターとして，Message-driven Beanが受信するメッセージの選択基準を設定します。これによって，メッセージプロパティに特定の値が設定されたメッセージだけを受信して，Message-driven Beanを動作させることができます。

メッセージセレクターについては，「7.6　メッセージセレクターによる受信メッセージの選択」を参照してください。

7.10.4　トランザクションコンテキストの設定

Message-driven Beanのメッセージリスナ，およびタイムアウトコールバックメソッドを呼び出すトランザクションのスコープを示す，トランザクションコンテキストを設定します。

トランザクション管理にCMTを使用する場合は，NOT_SUPPORTED属性を指定してください。

なお，BMTを使用するMessage-driven Beanがjavax.transaction.UserTransactionインタフェースを使用してトランザクションを管理する場合，メッセージの受信はトランザクションの処理に含まれません。

7.11　アプリケーション実装時の制限事項

この節では，Cosminexus JMSプロバイダを使用してアプリケーションを実装する際の制限事項について説明します。

Cosminexus JMSプロバイダはJMS1.1仕様に準拠していますが，一部のインタフェースおよびメソッドは使用できません。アプリケーションで使用できないインタフェースまたはメソッドを使用すると，JMSException例外がスローされるおそれがあります。

使用できないインタフェースを次に示します。

javax.jms.ServerSession

javax.jms.ServerSessionPool

javax.jms.ConnectionConsumer

すべてのjavax.jms XAインタフェース

また，次の表に示すインタフェースの一部のメソッドは，アプリケーションクライアントコンテナで実行するアプリケーションで使用するメソッドです。Cosminexus JMSプロバイダでは使用できません。

Cosminexus JMSプロバイダで使用できないメソッドをインタフェースごとに次の表に示します。

表7-9　Cosminexus JMSプロバイダで使用できないメソッド

インタフェース
使用できないメソッド

javax.jms.Session

setMessageListener(MessageListener listener)

getMessageListener()

run()

javax.jms.Connection

setExceptionListener(ExceptionListener listener)

stop()

setClientID(String clientID)

トランザクション処理されるSessionオブジェクトを作成するメソッド
（例えば，createSessionメソッドの一つ目の引数「transacted」に「true」を指定することができません）。

javax.jms.QueueConnection

createConnectionConsumer(Queue queue, String messageSelector, ServerSessionPool sessionPool, int maxMessages)

トランザクション処理されるQueueSessionオブジェクトを作成するメソッド
（例えば，createQueueSessionメソッドの一つ目の引数「transacted」に「true」を指定することができません）。

javax.jms.TopicConnection

createConnectionConsumer(Topic topic, String messageSelector, ServerSessionPool sessionPool, int maxMessages)

createDurableConnectionConsumer(Topic topic, String subscriptionName, String messageSelector, ServerSessionPool sessionPool, int maxMessages)

トランザクション処理されるTopicSessionオブジェクトを作成するメソッド
（例えば，createTopicSessionメソッドの一つ目の引数「transacted」に「true」を指定することができません）。

また，WebコンテナまたはEJBコンテナで動作するアプリケーションのコンポーネントでは，一つの接続で複数のアクティブなセッションオブジェクトを作成してはいけません。すでにアクティブなセッションオブジェクトがある場合に，createSessionメソッドでオブジェクトを作成しようとした場合，JMSException例外がスローされることがあります。

7.12　DDでの定義

この節では，Message-driven BeanのDDで定義する項目について説明します。

Message-driven BeanのDDでは，<activation-config>タグ下の属性で次の表に示す項目を設定します。

表7-10　<activation-config>タグ下の属性で指定する項目

属性
データ型
指定可能値
省略値
説明

destination
String
－
－
Message-driven Beanにメッセージを送信する，送信先の名称を指定します。この属性には，CJMSPリソースアダプタの管理対象オブジェクトのNameに設定した名称を設定してください。

destinationType
String

javax.jms.Queue

javax.jms.Topic

－
送信先の種類として，キュー（javax.jms.Queue）またはトピック（javax.jms.Topic）を指定します。

messageSelector
String
－
－
受信するメッセージを選択するためのメッセージセレクターを指定します。

subscriptionName
String
－
－
永続化サブスクライバーの名称を指定します。
subscriptionDurability属性に「Durable」を指定した場合は，必ず指定してください。

subscriptionDurability
String

Durable

NonDurable

NonDurable
永続化サブスクライバーにするかどうかを指定します。
永続化サブスクライバーにする場合は「Durable」，しない場合は「NonDurable」を指定します。
この属性は，destinationType属性に「javax.jms.Topic」を指定した場合にだけ有効になります。
また，「Durable」と指定した場合，次の属性も必ず指定してください。

subscriptionName

clientId

clientId
String
－
－
CJMSPブローカーに接続するための永続化サブスクライバーの識別子を指定します。
subscriptionDurability属性に「Durable」を指定した場合は，必ず指定してください。

acknowledgeMode
String

Auto-acknowledge

Dups-ok-acknowledge

Auto-acknowledge
確認応答モードを指定します。指定するモードの詳細はJMS仕様を参照してください。

endpointExceptionRedeliveryAttempts
Integer
1～2147483647
6
メッセージ配信中に例外が発生した場合に再配信する回数を指定します。

sendUndeliverableMsgsToDMQ
Boolean

true

false

true
Message-driven Beanが実行時例外をスローした場合で，再配信した回数がendpointExceptionRedeliveryAttempts属性に指定した回数を超えたときに，配信されなかったメッセージをデッドメッセージキューに登録するかどうかを指定します。
登録する場合は「true」，しない場合は「false」を指定します。
「false」を指定した場合，該当するメッセージはCJMSPブローカーによって，有効なコンシューマーに再配信されます（再度同じMessage-driven Beanに配信される場合もあります）。

endpointPoolMaxSize
Integer
1～2147483647
1
エンドポイントのプールの最大値を指定します。

endpointPoolSteadySize
Integer
0～2147483647
1
エンドポイントのプールの最小値を指定します。

endpointExceptionRedeliveryInterval
Integer
1～2147483647
500
例外が発生した場合にエンドポイントにメッセージを再配信する間隔をミリ秒で指定します。

（凡例）

－：指定可能値の制限または省略値はなし

7.13　実行環境の構築の流れ

この節では，Cosminexus JMSプロバイダを使用する場合の実行環境の構築の流れについて説明します。

メッセージの送受信を実行するJ2EEアプリケーションの実行環境については，あらかじめ運用管理ポータル（Management Server）を使用して構築しておいてください。J2EEアプリケーションの実行環境の構築手順の詳細は，マニュアル「Cosminexus アプリケーションサーバ システム構築・運用ガイド」の「1.2　J2EEアプリケーションを実行するシステムの構築」を参照してください。

なお，CJMSPブローカーは，Management Serverの管理対象になりません。このため，CJMSPブローカーの構築・運用は，コマンドおよび定義ファイルで実行します。

ポイント

Cosminexus JMSプロバイダを使用する場合のユースケースについては，「付録E　Cosminexus JMSプロバイダのユースケース」を参照してください。

実行環境の構築の流れを次の図に示します。

図7-13　実行環境の構築の流れ

操作の流れを説明します。説明の番号は図中の番号と対応しています。

前提環境の準備として，Application Serverのインストールと初期設定を実行します。
CJMSPブローカーとJ2EEサーバを異なるマシンに構築する場合は，それぞれのマシンにApplication Serverをインストールしてください。
Application Serverのインストールと初期設定については，マニュアル「Cosminexus アプリケーションサーバ システム構築・運用ガイド」の「7.2.1　インストール方法」を参照してください。

CJMSPブローカーの共通プロパティと管理コマンドのプロパティを設定します。
同じマシン内に作成するすべてのCJMSPブローカーに共通するプロパティを設定します。また，管理コマンドのログ出力に関するプロパティを設定します。設定方法については，「7.14.1　CJMSPブローカーの共通プロパティと管理コマンドのプロパティの設定」を参照してください。

CJMSPブローカーを作成します。
作成方法については，「7.14.2　CJMSPブローカーの作成」を参照してください。

CJMSPブローカーの個別プロパティを設定します。
それぞれのCJMSPブローカーに対して，個別のプロパティを設定します。設定方法については，「7.14.3　CJMSPブローカーの個別プロパティの設定」を参照してください。

CJMSPブローカーを起動します。
起動方法については，「7.14.4　CJMSPブローカーの起動」を参照してください。

各CJMSPブローカーに送信先を作成します。
作成方法については，「7.14.5　送信先の作成」を参照してください。

CJMSPリソースアダプタを設定して，開始します。
CJMSPリソースアダプタへの属性の設定には，Connector属性ファイルを使用します。
属性の設定後，CJMSPリソースアダプタを開始します。
設定および開始方法については，「7.15　CJMSPリソースアダプタの設定」を参照してください。

J2EEアプリケーションを設定して，開始します。
プロデューサーおよびコンシューマーとなるJ2EEアプリケーションをそれぞれインポートして属性を設定します。なお，コンシューマーとなるJ2EEアプリケーションのMessage-driven Beanに属性を設定する場合は，DD，cosminexus.xmlまたはMessageDrivenBean属性ファイルを使用します。
設定および開始方法については，「7.16　J2EEアプリケーションの設定」を参照してください。

ポイント

Cosminexus JMSプロバイダに関するファイルは，インストール時に次のディレクトリに格納されます。

Windowsの場合
<Cosminexusのインストールディレクトリ>¥CC¥cjmsp

UNIXの場合
/opt/Cosminexus/CC/cjmsp

注意

CJMSPリソースアダプタを開始する前に，CJMSPブローカーを起動しておく必要があります。CJMSPリソースアダプタの開始中にCJMSPブローカーが停止した場合，CJMSPリソースアダプタは，120秒ごとにCJMSPブローカーへの接続をリトライします。

7.14　CJMSPブローカーの設定

この節では，CJMSPブローカーの設定について説明します。

なお，CJMSPブローカーへのプロパティの設定方法には，2種類の方法があります。複数の設定方法で異なる値を指定した場合，次の表に示す番号の順で設定が優先されます。すべてのCJMSPブローカーに共通の設定をする場合は，commonconfig.propertiesに設定することをお勧めします。

表7-11　 CJMSPブローカーへのプロパティの設定方法

優先順位 | 設定方法 | 設定個所 | プロパティの有効範囲
1 | CJMSPブローカー個別プロパティファイルを使用する設定方法 | config.properties※1 | 個別のCJMSPブローカーだけに有効です。
2 | CJMSPブローカー共通プロパティファイルを使用する設定 | commonconfig.properties※2 | 同じマシン内のすべてのCJMSPブローカーに有効です。

注※1　デフォルトでは次のディレクトリに格納されます。なお，varディレクトリはCJMSPブローカーを最初に起動したあとで使用できるディレクトリです。

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥cjmsp¥var¥instances¥<CJMSPブローカーの名称>¥props

UNIXの場合

/opt/Cosminexus/CC/cjmsp/var/instances/<CJMSPブローカーの名称>/props

注※2　次のディレクトリに格納されています。

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥cjmsp¥lib¥props¥broker

UNIXの場合

/opt/Cosminexus/CC/cjmsp/lib/props/broker

また，管理コマンド（cjmsicmd）のログの出力方法についてのプロパティは，admin.propertiesに指定します。admin.propertiesは，次のディレクトリに格納されています。

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥cjmsp¥var¥admin¥config

UNIXの場合

/opt/Cosminexus/CC/cjmsp/var/admin/config

注意

CJMSPブローカーの設定をする場合，cjmspディレクトリ下のファイルのうち，次のファイル以外は編集しないでください。

config.properties

commonconfig.properties

admin.properties

また，これらのファイルに対しても，OSの機能によるアクセス権の変更はしないでください。

なお，ファイアウォールを使用するシステムの場合，Cosminexus JMSプロバイダによるポートの利用を許可する設定が必要です。

例えば，Windowsの場合，次のコマンドの実行によって利用を許可できます。

netsh firewall add allowedprogram program= "<COSMINEXUS_HOME>/jdk/bin/java.exe" name="Java Virtual Machine" mode=ENABLE.

Cosminexus JMSプロバイダが利用するポート番号は，次のとおりです。（ ）内はそのポート番号を設定するプロパティです。config.propertiesで設定できます。

CJMSPブローカーのポートマッパーが使用するポート番号（imq.portmapper.port）

jmsサービスが使用するポート番号（imq.jms.tcp.port）

adminサービスが使用するポート番号（imq.admin.tcp.port）

＜この節の構成＞

7.14.1　CJMSPブローカーの共通プロパティと管理コマンドのプロパティの設定

7.14.2　CJMSPブローカーの作成

7.14.3　CJMSPブローカーの個別プロパティの設定

7.14.4　CJMSPブローカーの起動

7.14.5　送信先の作成

7.14.1　CJMSPブローカーの共通プロパティと管理コマンドのプロパティの設定

CJMSPブローカーのプロパティには，デフォルト値が設定されています。必要に応じて，commonconfig.propertiesを編集してすべてのCJMSPブローカーに設定するプロパティの値を変更してください。

また，admin.propertiesを編集して，管理コマンドのログの出力に関するプロパティを設定してください。

7.14.2　CJMSPブローカーの作成

CJMSPブローカーは，cjmsbrokerコマンドを実行して作成します。

手順を次に示します。

cdコマンドでカレントディレクトリを次のディレクトリに移動します。

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥cjmsp¥bin

UNIXの場合

/opt/Cosminexus/CC/cjmsp/bin

cjmsbrokerコマンドを実行します。
CJMSPブローカーの名前を-nameオプションに指定して実行します。

実行例（名前「MyBroker」を指定してCJMSPブローカーを作成する場合）

cjmsbroker -name MyBroker

cjmsicmd shutdown bkrコマンドを実行します。
作成したCJMSPブローカーを停止します。以降で個別のCJMSPブローカーのプロパティを設定するためです。

実行例

cjmsicmd shutdown bkr

手順2.でcjmsbrokerを実行したときに，varディレクトリ下のinstances下に指定した名前（実行例の場合は「MyBroker」）のディレクトリが作成されます。名前を指定しなかった場合は，デフォルトのCJMSPブローカーが起動します。

なお，varディレクトリの格納場所はcjmsbrokerコマンドの-varhomeオプションで指定します。

注意

-varhomeオプションでディレクトリを指定した場合は，2回目以降のCJMSPブローカー起動時にも，-varhomeオプションで同じ値を指定してください。

2回目以降の起動時に-varhomeオプションを指定しなかったり，別の場所を指定したりすると，-nameオプションに同じ名前を指定しても，指定したvarディレクトリまたはデフォルトディレクトリ下に新しいインスタンスが作成されます。

7.14.3　CJMSPブローカーの個別プロパティの設定

ここでは，CJMSPブローカーの個別プロパティの設定について説明します。

CJMSPブローカーの個別のプロパティは，config.propertiesの指定で設定できます。ただし，config.propertiesを指定できるのは，一度cjmsbrokerコマンドで起動され，varディレクトリ以下が作成されているCJMSPブローカーだけです。

config.propertiesを使用したプロパティの指定例を次に示します。

config.propertiesを使用したプロパティの指定例

imq.portmapper.port=7777

broker.logger.MessageLogFile.filenum=4

指定内容の意味

CJMSPブローカーのポートマッパーが使用するポート番号は7777です。

メッセージログファイルの面数は4です。

注意

複数のCJMSPブローカーを起動するシステムの場合は，必ずimq.portmapper.portプロパティの値を変更してください。デフォルトポート（7676）を使用しているCJMSPブローカーがあると，新しいCJMSPブローカーは作成できません。

7.14.4　CJMSPブローカーの起動

ここでは，CJMSPブローカーの起動について説明します。

手順を示します。カレントディレクトリは次のディレクトリに移動していることを前提とします。

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥cjmsp¥bin

UNIXの場合

/opt/Cosminexus/CC/cjmsp/bin

cjmsbrokerコマンドを実行します。
ここでは，「MyBroker」を起動する実行例を示します。

実行例（「MyBroker」を起動する場合）

cjmsbroker -name MyBroker

7.14.5　送信先の作成

ここでは，CJMSPブローカーで管理する送信先の作成について説明します。

手順を示します。カレントディレクトリは次のディレクトリに移動していることを前提とします。

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥cjmsp¥bin

UNIXの場合

/opt/Cosminexus/CC/cjmsp/bin

cjmsicmd create dstコマンドを実行します。
ここでは，キューを作成する実行例とトピックを作成する実行例を示します。

実行例（キュー「Queue1」を作成する場合）

cjmsicmd create dst -t q -n Queue1

実行例（トピック「Topic1」を作成する場合）

cjmsicmd create dst -t t -n Topic1

なお，送信先は，コマンドで作成するほか，アプリケーション内でAPIによって作成する方法があります。詳細は，「7.8.2　送信先の管理とルーティングサービス」を参照してください。

7.15　CJMSPリソースアダプタの設定

CJMSPリソースアダプタは，次のディレクトリ下に，cjmsra.rarとして格納されています。デフォルトの名称は，「Cosminexus_JMS_Provider_RA」です。

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥cjmsp¥lib

UNIXの場合

/opt/Cosminexus/CC/cjmsp/lib

リソースアダプタのインポートから開始までの手順については，マニュアル「Cosminexus アプリケーションサーバ システム構築・運用ガイド」の「8.8.3　リソースアダプタのインポートと開始」またはマニュアル「Cosminexus アプリケーションサーバ システム構築・運用ガイド」の「10.6.2　リソースアダプタのインポートと開始」を参照してください。

CJMSPリソースアダプタには，属性として，次の項目が設定できます。

ConnectionFactoryや送信先など，管理対象オブジェクトの属性

トランザクションサポートレベル

ログ出力に関する属性

これらの属性を変更する場合は，CJMSPリソースアダプタに設定するConnector属性ファイルを編集してください。

CJMSPリソースアダプタの属性には，リソースアダプタ単位に指定する項目と，ManagedConnectionFactoryクラス単位に指定する項目があります。CJMSPリソースアダプタで指定する主な属性を次の表に示します。

表7-12　CJMSPリソースアダプタで指定する主な属性

対象
Connector属性ファイルのタグ
指定する項目

リソースアダプタ単位の属性
<resourceadapter>下の<config-property>
CJMSPリソースアダプタ全体に影響する属性

connectionURL

reconnectEnabled

reconnectAttempts

reconnectInterval

ログに関する属性

MsgLogLevel

MsgLogFileNum

MsgLogFileSize

ExpLogFileNum

ExpLogFileSize

ManagedConnectionFactoryクラス単位の属性
<connection-definition>下の<config-property>
コネクションインタフェースごとの属性

clientId

reconnectEnabled

reconnectAttempts

reconnectInterval

管理対象オブジェクトの属性
<adminobject>下の<adminobject-name>，<adminobject-interface>，<adminobject-class>
管理対象オブジェクトの名称，送信先の種類，およびクラスの情報

<adminobject>下の<config-property>
送信先の名前（Message-driven Beanのdestination属性に指定する値）

Name

なお，Cosminexus JMSプロバイダでは，Connector属性ファイルのテンプレートファイルを提供しています。必要に応じて使用してください。テンプレートファイルの格納先については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「4.1.14　Connector属性ファイルのテンプレートファイル」を参照してください。

7.16　J2EEアプリケーションの設定

Cosminexus JMSプロバイダを使用するJ2EEアプリケーションをインポートします。

J2EEアプリケーションのインポートから開始までの手順については，マニュアル「Cosminexus アプリケーションサーバ システム構築・運用ガイド」の「2.2.14　J2EEアプリケーションのインポートと開始」またはマニュアル「Cosminexus アプリケーションサーバ システム構築・運用ガイド」の「8.8.4　J2EEアプリケーションのインポートと開始」を参照してください。

J2EEアプリケーションに設定する属性は，DDまたはcosminexus.xmlに指定できます。Cosminexus JMSプロバイダを使用する場合にDDに必要な設定については，「7.12　DDでの定義」を参照してください。なお，cosminexus.xmlを含まないJ2EEアプリケーションに対して，J2EEサーバにインポートしたあとで属性を設定する場合は，属性ファイルを使用して，サーバ管理コマンドで設定ください。

7.17　Cosminexus JMSプロバイダを使用する場合のシステムの開始と停止

この節では，Cosminexus JMSプロバイダを使用する場合のシステムの開始手順と停止手順について説明します。

＜この節の構成＞

7.17.1　システムの開始手順

7.17.2　システムの停止手順

7.17.3　CJMSPブローカーの状態の確認

7.17.1　システムの開始手順

Cosminexus JMSプロバイダを使用するシステムは，次の手順で開始します。なお，手順1.と手順2.は順不同です。

注意

CJMSPリソースアダプタを開始する前に，必ずCJMSPブローカーを起動してください。CJMSPブローカー起動前にCJMSPリソースアダプタを開始することはできません。また，CJMSPリソースアダプタが開始した状態でJ2EEサーバを停止し，CJMSPブローカーを停止してからJ2EEサーバを再起動すると，再起動後のCJMSPリソースアダプタの再開始には失敗します。

J2EEサーバを含むJ2EEアプリケーションの実行環境の各プロセスを起動します。
Smart Composerで構築したシステムの場合は，一括起動ができます。詳細は，マニュアル「Cosminexus アプリケーションサーバ システム構築・運用ガイド」の「8.9　システムの一括起動（サービスユニットの開始）」を参照してください。

注意

この時点でCJMSPリソースアダプタおよびJ2EEアプリケーションは開始しません。

CJMSPブローカーを起動します。
ここでは，CJMSPブローカー「MyBroker」を起動する場合の実行例を示します。

実行例

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥cjmsp¥bin¥cjmsbroker -name MyBroker

UNIXの場合

/opt/Cosminexus/CC/cjmsp/bin/cjmsbroker -name MyBroker

なお，CJMSPブローカーを起動する際，必要に応じてCJMSPブローカーが使用するJavaヒープサイズを変更してください※。

CJMSPリソースアダプタを開始します。
サーバ管理コマンドを使用した実行例を次に示します。この例では，J2EEサーバの名称は「cmx_MyWebSystem_unit1_J2EE_01」，CJMSPリソースアダプタの名称は「Cosminexus_JMS_Provider_RA」とします。

実行例

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥admin¥bin¥cjstartrar "cmx_MyWebSystem_unit1_J2EE_01" -resname "Cosminexus_JMS_Provider_RA"

UNIXの場合

/opt/Cosminexus/CC/admin/bin/cjstartrar "cmx_MyWebSystem_unit1_J2EE_01" -resname "Cosminexus_JMS_Provider_RA"

メッセージを送受信するJ2EEアプリケーションを開始します。
サーバ管理コマンドを使用した実行例を次に示します。なお，J2EEサーバの名称は「cmx_MyWebSystem_unit1_J2EE_01」，J2EEアプリケーションの名称は「JMSSampleApp」とします。

実行例

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥admin¥bin¥cjstartapp "cmx_MyWebSystem_unit1_J2EE_01" -name "JMSSampleApp"

UNIXの場合

/opt/Cosminexus/CC/admin/bin/cjstartapp "cmx_MyWebSystem_unit1_J2EE_01" -name "JMSSampleApp"

注※　CJMSPブローカーが使用するJavaヒープサイズの考え方

CJMSPブローカーは，デフォルトの設定では，192メガバイトのJavaヒープを使用する設定になっています。この値は，大量のメッセージを扱うには小さ過ぎるため，必要に応じて増加させてください。

使用するJavaヒープのメモリサイズが小さ過ぎると，空きメモリを確保するためにJ2EEアプリケーションとのコネクションをクローズする必要が発生し，処理できるメッセージの量が少なくなります。

ただし，CJMSPブローカーで使用できるJavaヒープサイズの最大値を大きくし過ぎると，システムの物理メモリに影響が出て，システムにOutOfMemoryErrorを発生させる要因になります。OutOfMemoryErrorが発生すると，システムの処理性能を低下させるほか，予想外の状態でCJMSPブローカーに障害が発生したり，ほかのアプリケーションやサービスの実行に影響を及ぼしたりします。

これらを考慮し，実行する環境に応じて，適切な値を設定してください。

CJMSPブローカーが使用するJavaヒープのサイズは，CJMSPブローカーを起動するときにcjmsbrokerコマンドの-vmargsオプションで指定できます。

実行例を示します。

実行例

cjmsbroker -vmargs "-Xms256m -Xmx1024m"

この例では，CJMSPブローカーは，CJMSPブローカーの起動時には256メガバイトのメモリを使用し，最大で1ギガバイトのJavaヒープを使用するように設定しています。

7.17.2　システムの停止手順

Cosminexus JMSプロバイダを使用するシステムは，次の手順で停止します。なお，手順3.と手順4.は順不同です。

メッセージを送受信するJ2EEアプリケーションを停止します。
サーバ管理コマンドを使用した実行例を次に示します。この例では，J2EEサーバの名称は「cmx_MyWebSystem_unit1_J2EE_01」，J2EEアプリケーションの名称は「JMSSampleApp」とします。

実行例

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥admin¥bin¥cjstopapp "cmx_MyWebSystem_unit1_J2EE_01" -resname "JMSSampleApp"

UNIXの場合

/opt/Cosminexus/CC/admin/bin/cjstopapp "cmx_MyWebSystem_unit1_J2EE_01" -resname "JMSSampleApp"

CJMSPリソースアダプタを停止します。
サーバ管理コマンドを使用した実行例を次に示します。なお，J2EEサーバの名称は「cmx_MyWebSystem_unit1_J2EE_01」，CJMSPリソースアダプタの名称は「Cosminexus_JMS_Provider_RA」とします。

実行例

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥admin¥bin¥cjstoprar "cmx_MyWebSystem_unit1_J2EE_01" -resname "Cosminexus_JMS_Provider_RA"

UNIXの場合

/opt/Cosminexus/CC/admin/bin/cjstoprar "cmx_MyWebSystem_unit1_J2EE_01" -resname "Cosminexus_JMS_Provider_RA"

CJMSPブローカーを停止します。
CJMSPブローカー「MyBroker」を停止する場合の実行例を示します。

実行例

Windowsの場合

<Cosminexusのインストールディレクトリ>¥CC¥cjmsp¥bin¥cjmsicmd shutdown bkr

UNIXの場合

/opt/Cosminexus/CC/cjmsp/bin/cjmsicmd shutdown bkr

ポイント

CJMSPブローカーを停止する場合は，ホスト名とポート番号によって対象にするCJMSPブローカーを特定します。ポート番号を指定しないでcjmsicmd shutdown bkrコマンドを実行すると，デフォルトの7676のポートを使用しているCJMSPブローカーが停止処理の対象となります。ほかのポートを使用しているCJMSPブローカーを停止する場合は，-bオプションでホスト名とポート番号を指定してください。実行例を次に示します。

実行例（7777のポートを使用しているCJMSPブローカーを停止する場合）

cjmsicmd shutdown bkr -b localhost:7777

詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjmsicmd shutdown bkr（CJMSPブローカーの停止）」を参照してください。

J2EEサーバを含むJ2EEアプリケーションの実行環境の各プロセスを停止します。
Smart Composerで構築したシステムの場合は，一括停止ができます。詳細は，マニュアル「Cosminexus アプリケーションサーバ システム構築・運用ガイド」の「9.3.1　すべてのサービスユニットの一括起動と一括停止」を参照してください。

7.17.3　CJMSPブローカーの状態の確認

ここでは，CJMSPブローカーの状態遷移および状態の確認方法について説明します。CJMSPブローカーには，3種類の状態があります。コマンドの実行などによって状態が遷移します。

CJMSPブローカーの状態は，cjmsicmd list bkrコマンドを使用して確認できます。詳細は，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjmsicmd list bkr（CJMSPブローカーの一覧表示）」を参照してください。

コマンド実行によるCJMSPブローカーの状態遷移を次に示します。

図7-14　CJMSPブローカーの状態遷移

表7-13　 CJMSPブローカーの状態

CJMSPブローカーの状態
説明

OPERATING
CJMSPブローカーがメッセージを処理できる状態です。
cjmsbrokerコマンドによってCJMSPブローカーを起動するとこの状態になります。なお，OPERATINGの状態のCJMSPブローカーに対してcjmsicmd pause bkrコマンドを実行した場合，状態は変わりません。

SHUTDOWN_STARTED
CJMSPブローカーが停止処理（シャットダウン）を開始した状態です。直後または数分後に，CJMSPブローカーはシャットダウンされます。
cjmsicmd shutdown bkrコマンドを実行するとこの状態になります。

SHUTDOWN_COMPLETE
CJMSPブローカーの停止（シャットダウン）処理が完了した状態です。すべてのリソースは解放されています。CJMSPブローカーがシャットダウンされるかどうかは，実行中のプロセスがあるかどうかに依存します。
cjmsicmd shutdown bkrコマンドを実行するとこの状態になります。

7.18　障害対応用の情報の確認

この節では，Cosminexus JMSプロバイダ使用時に障害が発生した場合に使用する，障害対応用の情報について説明します。

Cosminexus JMSプロバイダでは，次の3種類のコンポーネントがログを出力します。

CJMSPリソースアダプタ

CJMSPブローカー

管理コマンド（cjmsicmd）

これらのコンポーネントは，メッセージログと例外ログを出力します。メッセージログと例外ログは，コンポーネントごとのログファイルに出力されます。

ログの形式は，日立トレース共通ライブラリ形式です。

メッセージログ

メッセージログには，J2EEアプリケーションから実行された操作が原因で発生した状態が出力されます。

出力するメッセージの種類は，ログレベルによって設定します。

Cosminexus JMSプロバイダでのログレベルの意味を次の表に示します。

表7-14　Cosminexus JMSプロバイダでのログレベルの意味

ログレベル
意味

ERROR
システムの障害につながる深刻な問題が発生したことを示すメッセージのログレベルです。
エラーと例外の情報だけの，最小限の情報が出力されます。
このログレベルを指定した場合は，ERRORレベルに該当するメッセージだけがログ出力されます。

WARNING
システムの障害にはつながらないものの，注意が必要な状態であることを示すメッセージのログレベルです。
処理が正常終了し，状態に問題がある場合に出力されます。
このログレベルを指定した場合は，ERRORレベルとWARNINGレベルに該当するメッセージがログ出力されます。

INFO
メトリクスやそのほかのメッセージを出力するログレベルです。
処理の流れや，通常処理でどのように操作が行われているかを示す情報が出力されます。
このログレベルを指定した場合は，ERRORレベル，WARNINGレベルおよびINFOレベルに該当するメッセージがログ出力されます。

注

重要なメッセージについては，ログレベルの設定に関係なく，コンソールまたはログファイルに出力されることがあります。

例外ログ

例外ログには，J2EEアプリケーション実行時にエラーまたは例外が発生した場合の情報（例外メッセージ）が出力されます。

ログファイルに出力されるメッセージの詳細については，マニュアル「Cosminexus アプリケーションサーバ メッセージ 1」の「3.　KDAN（Cosminexus JMSプロバイダで出力されるメッセージ）」を参照してください。また，日立トレース共通ライブラリ形式については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「5.2.1　日立トレース共通ライブラリ形式のログの出力形式と出力項目」を参照してください。

参考

Cosminexus JMSプロバイダでは，PRFトレースも取得できます。Cosminexus JMSプロバイダ使用時のPRFトレースの取得ポイントについては，マニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「7.　性能解析トレースのトレース取得ポイントとPRFトレース取得レベル」を参照してください。

CJMSPブローカーがJavaVMの障害で停止した場合は，次のディレクトリにスレッドダンプまたはcoreファイルが出力されます。
Windowsの場合
<Cosminexusのインストールディレクトリ>¥CC¥cjmsp¥var¥instances
UNIXの場合
/opt/Cosminexus/CC/cjmsp/var/instances

7.19　Cosminexus JMSプロバイダ使用時の注意事項

この節では，Cosminexus JMSプロバイダ使用時の注意事項について説明します。

＜この節の構成＞

(1)　デフォルトの設定でのCosminexus JMSプロバイダの動作

(2)　メッセージ処理の優先順位についての注意事項

(3)　有効期限が過ぎたメッセージの扱い

(4)　メッセージプロパティの順序性

(5)　メッセージプロパティでのバイトメッセージの扱い

(1)　デフォルトの設定でのCosminexus JMSプロバイダの動作

デフォルトの設定では，Cosminexus JMSプロバイダは次のように動作します。

CJMSPブローカーが管理しているメッセージの数またはメッセージの容量が，すべての物理的送信先に対して設定した最大値に到達した場合，CJMSPブローカーはメモリリソースを確保するために，最新のメッセージの受け付けを拒否します。また，そのメッセージが永続化メッセージの場合にだけ，メッセージを送信したクライアントに受け付けを拒否したことを通知します。

デッドメッセージキューに送信された有効期限を過ぎたメッセージは，60秒間保留されます。この期間を過ぎたメッセージをデッドメッセージキューから回復することはできません。

使用されなくなった一時的送信先は，120秒後に破棄されます。

永続化データのファイルへの格納は，非同期で実行されます。このため，突然CJMSPブローカーが故障したり停止したりした場合，データが失われることがあります。

(2)　メッセージ処理の優先順位についての注意事項

Cosminexus JMSプロバイダのメッセージ送信では，優先順位の高いメッセージが最初に実行されることが保証されません。例えば，優先順位を1，2，3と設定した「メッセージ1」「メッセージ2」および「メッセージ3」というの三つのメッセージをプロデューサーから送信した場合に，コンシューマーでは「メッセージ1」「メッセージ3」「メッセージ2」のように異なる順番で処理が実行されることがあります。

優先順位と処理順の相違は，次のような要因で発生します。

プロデューサーが先に優先順位の低いメッセージを送信したあとで，優先順位が高いメッセージを送信した場合，あとから送ったメッセージが届く前にコンシューマーではすでに優先順位の低いメッセージを受信し，処理を開始していることがあります。

コンシューマーが優先順位の高いメッセージを受信する前に，そのメッセージの有効期限が過ぎた場合，優先順位の高いメッセージの処理は実行されません。

プロデューサーが優先順位に沿ってメッセージを送信した場合も，内部処理の遅延などによって，コンシューマーに送信される順序が変わることがあります。

優先順位が高いメッセージが永続化メッセージでない場合，CJMSPブローカーに障害が発生すると，そのメッセージは失われます。この場合，CJMSPブローカーが再起動したあとでは，優先度が低い永続化メッセージの処理だけが実行されます。

(3)　有効期限が過ぎたメッセージの扱い

送信先があるマシンのシステム時間を変更した場合，クライアントは期限切れのメッセージを受信することがあります。

メッセージの有効期限は，JMSExpirationヘッダーフィールドにメッセージを送信したメソッドによって設定されます。もし，誤ってシステムの時間設定が変更されていた場合，有効期限が過ぎたメッセージがコンシューマーに送信されるおそれがあります。

(4)　メッセージプロパティの順序性

メッセージプロパティの処理順序は保証されません。

メッセージプロパティは，順序性を維持した構造で管理されていません。このため，例えば，「プロパティ1」「プロパティ2」「プロパティ3」というプロパティがある場合に，この順序で送信先に送信しても，同じ順序で処理されるとは限りません。ただし，プロパティとその値は，送信前と受信時で変わりません。

(5)　メッセージプロパティでのバイトメッセージの扱い

メッセージプロパティでは，バイトメッセージを使用しないでください。

バイトメッセージでは，すべてのデータ型のデータを読み出すことができます。例えば，long型の値を含むメッセージをshort型のメソッドで呼び出して処理した場合，意味的には不正な値ですが，最初の2バイトの読み出しには成功してしまいます。これは，ほかのメッセージのデータ型では禁止されている処理です。

Cosminexus JMSプロバイダでは，データのデータ型を保持し，正しい変換規則の適用に対応するよう，データを管理しています。

8.　JavaMailの利用

この章では，SMTPプロバイダ独自のセッションプロバイダ，POP3のプロパティ，およびJavaMailを利用する場合の注意事項について説明します。

＜この章の構成＞

8.1　この章の構成

8.2　セッションプロパティ

8.3　JavaMailを利用する場合の注意事項

8.1　この章の構成

この章では，SMTPプロバイダ独自のセッションプロバイダ，およびPOP3のプロパティについて説明します。

この章の構成を次の表に示します。

表8-1　この章の構成（セッションプロパティ）

分類 | タイトル | 参照先
実装 | セッションプロパティ | 8.2
注意事項 | JavaMailを利用する場合の注意事項 | 8.3

注　「解説」，「設定」，および「運用」について，この機能固有の説明はありません。

8.2　セッションプロパティ

JavaMailでは，javax.mail.Sessionクラス作成時に，メールの送受信に関する設定をセッションプロパティとして設定します。

セッションプロパティには，次に示す種類があります。

JavaMail APIで提供するセッションプロパティ

JavaMail仕様で定められたSMTPプロバイダが提供するセッションプロパティ

JavaMail仕様で定められたPOP3プロバイダが提供するセッションプロパティ

SMTPプロバイダ独自のセッションプロパティ

POP3プロバイダ独自のセッションプロパティ

セッションプロパティの指定値は，「"」で囲み文字列として指定する必要があります。

なお，ここではSMTPプロバイダ独自のセッションプロパティ，およびPOP3プロバイダ独自のセッションプロパティについて説明します。

＜この節の構成＞

8.2.1　SMTPサーバに接続するためのセッションプロパティ

8.2.2　POP3サーバに接続するためのセッションプロパティ

8.2.1　SMTPサーバに接続するためのセッションプロパティ

ここでは，SMTPプロバイダ独自のセッションプロパティについて説明します。

SMTPプロバイダ独自のセッションプロパティの一覧を次の表に示します。

表8-2　SMTPプロバイダ独自のセッションプロパティの一覧

項番
プロパティ
デフォルト値
有効な指定値
無効な値を指定した場合の動作

1
mail.smtp.allow8bitmime
false
true，false
（大文字と小文字の区別はなし）
メールサーバへの送信処理でメッセージKDJE59100-Wを出力します。
値は，デフォルト値を使用します。

2
mail.smtp.auth
false
true，false
（大文字と小文字の区別はなし）
メールサーバとの接続処理でメッセージKDJE59100-Wを出力します。
値は，デフォルト値を使用します。

3
mail.smtp.connectiontimeout
0
（無限待ち）
0～2147483647
（単位:ミリ秒）
メールサーバとの接続処理でメッセージKDJE59100-Wを出力します。
値は，デフォルト値を使用します。

4
mail.smtp.dsn.notify
なし

SUCCESS，FAILURE，DELAYのうち一つ，または複数を「,」で区切って指定

NEVER

指定した値をそのまま使用します。
メールサーバ側で不正と見なした場合は，RCPTコマンドが失敗し，メール送信処理が中断します。
メールサーバの処理は，メールサーバに依存します。

5
mail.smtp.dsn.ret
なし
FULL，HDRS
指定した値をそのまま使用します。
メールサーバ側で不正と見なした場合は，MAILコマンドが失敗し，メール送信処理が中断します。
メールサーバの処理は，メールサーバに依存します。

6
mail.smtp.ehlo
true
true，false
（大文字と小文字の区別はなし）
メールサーバとの接続処理でメッセージKDJE59100-Wを出力します。
値は，デフォルト値を使用します。

7
mail.smtp.from
<mail.form>に指定した値
文字列
JavaMail，またはメールサーバから例外が返る可能性があります。メールサーバがどのような場合に例外を返すかは，メールサーバに依存します。

8
mail.smtp.localhost
java.net.InetAddress.getLocalHost().getHostName()の戻り値
文字列
指定した値をそのまま使用します。

9
mail.smtp.quitwait
false
true，false
（大文字と小文字の区別はなし）
javax.mail.Transportオブジェクト取得時にメッセージKDJE59100-Wを出力します。
値は，デフォルト値を使用します。

10
mail.smtp.saslrealm
なし
文字列
指定した値をそのまま使用します。

11
mail.smtp.sendpartial
false
true，false
（大文字と小文字の区別はなし）
メールサーバへの送信処理でメッセージKDJE59100-Wを出力します。
値は，デフォルト値を使用します。

12
mail.smtp.timeout
0
（無限待ち）
0～2147483647
（単位:ミリ秒）
メールサーバとの接続処理でメッセージKDJE59100-Wを出力します。
値は，デフォルト値を使用します。

それぞれのプロパティについて，以降で説明します。

＜この項の構成＞

(1)　mail.smtp.allow8bitmime

(2)　mail.smtp.auth

(3)　mail.smtp.connectiontimeout

(4)　mail.smtp.dsn.notify

(5)　mail.smtp.dsn.ret

(6)　mail.smtp.ehlo

(7)　mail.smtp.from

(8)　mail.smtp.localhost

(9)　mail.smtp.quitwait

(10)　mail.smtp.saslrealm

(11)　mail.smtp.sendpartial

(12)　mail.smtp.timeout

(1)　mail.smtp.allow8bitmime

quoted-printableやbase64エンコーディングを使用するメッセージのテキスト部分を，8ビットエンコーディングへ変換するかどうかを指定します。

trueを指定した場合，次の条件を満たしていれば，quoted-printableやbase64エンコーディングを使用するメッセージのテキスト部分は8ビットエンコーディングへ変換されます。

サーバが8ビット転送をサポートしている

quoted-printableやbase64エンコーディングを使用するメッセージのテキスト部分がRFC2045に準拠している

falseを指定した場合は，8ビットエンコーディングへは変換しません。

(2)　mail.smtp.auth

AUTHコマンドを使用したユーザ認証をするかどうかを指定します。

trueを指定した場合，AUTHコマンドを使用してユーザ認証をします。falseを指定した場合，AUTHコマンドを使用したユーザ認証はしません。

(3)　mail.smtp.connectiontimeout

コネクション確立までのタイムアウト時間（単位：ミリ秒）を指定します。

0を指定すると，無限に待ち続けます。

このプロパティが指定されている場合，スレッドを使用してタイムアウト時間を監視します。ポリシーやシステムの制限でスレッドが作成できない場合は，タイムアウト時間を監視しません。

タイムアウト時間が，OSのTCPの再送タイマによるタイムアウト時間より大きいか，またはタイムアウト監視をしない設定の場合，TCPの再送タイマによるタイムアウト時間が有効となります。なお，再送タイマによるタイムアウトは，OSによって異なります。

(4)　mail.smtp.dsn.notify

RCPTコマンドのNOTIFYオプションを指定します。

このオプションはDSN（Delivery Status Notification：配送状態通知）を生成する条件を指定します。コンマを区切りにして，次の表に示す値を組み合わせて指定できます。

表8-3　mail.smtp.dsn.notifyに指定できる値

項番 | 値 | 指定される内容
1 | NEVER | 配送状態に関係なく，送信者にDSNを返さない。
2 | SUCCESS | メッセージの配送が成功した場合，DSNを生成する。
3 | FAILURE | メッセージの配送が失敗した場合，DSNを生成する。
4 | DELAY | メッセージの配送が遅延した場合，DSNを生成する。

指定しない場合のDSN生成については，RFC1891ではNOTIFY=FAILUREまたはNOTIFY=FAILURE,DELAYとして指定されたと解釈してよいとされており，サーバの実装に依存します。

(5)　mail.smtp.dsn.ret

MAILコマンドのRET追加パラメタ値を指定します。

次の表に示す値を組み合わせて指定できます。

表8-4　mail.smtp.dsn.ret指定できる値

項番 | 値 | 指定される内容
1 | FULL | 配送失敗通知メッセージに送信メッセージ全体を含める。
2 | HDRS | 配送失敗通知メッセージに送信メッセージのヘッダだけを含める。

プロパティを指定しない場合，配送失敗通知メッセージに何が含まれるかは，サーバの実装に依存します。

(6)　mail.smtp.ehlo

EHLOコマンドを使用するかどうかを指定します。

trueを指定した場合，EHLOコマンドを使用します。EHLOコマンドでエラーが発生した場合，代替にHELOコマンドを使用します。falseを指定した場合，EHLOコマンドは使用しません。

(7)　mail.smtp.from

SMTPのMAILコマンドのreverse-pathに使用する電子メールアドレスを指定します。

(8)　mail.smtp.localhost

SMTPのHELOコマンドまたはEHLOコマンドで使用されるローカルホストのドメイン名を指定します。

JDKおよびネームサービスが適切に定義されている場合，指定する必要はありません。

(9)　mail.smtp.quitwait

QUITコマンドに対する応答を待つかどうかを指定します。

trueを指定した場合は，QUITコマンドに対する応答を待ちます。falseを指定した場合は，QUITコマンド送信直後にコネクションをクローズします。

(10)　mail.smtp.saslrealm

DIGEST-MD5認証で使用するレルムを指定します。

省略した場合，サーバからのチャレンジに含まれる最初のレルムを使用します。チャレンジにレルムが含まれていない場合，接続先ホスト名をレルムとして使用します。

(11)　mail.smtp.sendpartial

メッセージに指定されている電子メールアドレスに，正しくない電子メールアドレスが含まれている場合の動作を指定します。

trueを指定した場合は，メッセージを送信した上で，エラーになった電子メールアドレスをSendFailedExceptionで報告します。falseを指定した場合は，メッセージを送信しません。

(12)　mail.smtp.timeout

SMTPサーバとの通信（read）のタイムアウト時間（単位：ミリ秒）を指定します。

0を指定すると，無限に待ち続けます。

タイムアウト時間が，OSのTCPの再送タイマによるタイムアウト時間より大きいか，またはタイムアウト監視をしない設定の場合，TCPの再送タイマによるタイムアウト時間が有効となります。なお，再送タイマによるタイムアウトは，OSによって異なります。

8.2.2　POP3サーバに接続するためのセッションプロパティ

ここでは，POP3プロバイダ独自のセッションプロパティについて説明します。

POP3プロバイダ独自のセッションプロパティの一覧を次の表に示します。

表8-5　POP3プロバイダ独自のセッションプロパティの一覧

項番
プロパティ
デフォルト値
有効な指定値
無効な値を指定した場合の動作

1
mail.pop3.connectiontimeout
0
（無限待ち）
0～2147483647
（単位:ミリ秒）
メールサーバとの接続処理でメッセージKDJE59100-Wを出力します。
値は，デフォルト値を使用します。

2
mail.pop3.rsetbeforequit
false
true，false
（大文字と小文字の区別はなし）
javax.mail.Storeオブジェクト取得時にメッセージKDJE59100-Wを出力します。
値は，デフォルト値を使用します。

3
mail.pop3.timeout
0
（無限待ち）
0～2147483647
（単位:ミリ秒）
メールサーバとの接続処理でメッセージKDJE59100-Wを出力します。
値は，デフォルト値を使用します。

それぞれのプロパティについて，以降で説明します。

＜この項の構成＞

(1)　mail.pop3.connectiontimeout

(2)　mail.pop3.rsetbeforequit

(3)　mail.pop3.timeout

(1)　mail.pop3.connectiontimeout

コネクション確立までのタイムアウト時間（単位：ミリ秒）を指定します。

0を指定すると，無限に待ち続けます。

タイムアウト時間が，OSのTCPの再送タイマによるタイムアウト時間より大きいか，またはタイムアウト監視をしない設定の場合，TCPの再送タイマによるタイムアウト時間が有効となります。なお，再送タイマによるタイムアウトは，OSによって異なります。

(2)　mail.pop3.rsetbeforequit

フォルダを閉じる場合に，QUITコマンドの前にRSETコマンドを発行するかどうかを指定します。

trueを指定した場合，QUITコマンドの前にRSETコマンドを発行し，メッセージに付けた削除マークを取り除きます。自動的に削除マークが付けられるようなサーバの場合に，ユーザのリクエストなしにメッセージが削除されることを防げます。

falseを指定した場合，QUITコマンドの前にRSETコマンドを発行しません。

(3)　mail.pop3.timeout

POP3サーバとの通信（read）のタイムアウト時間（単位：ミリ秒）を指定します。

0を指定すると，無限に待ち続けます。

タイムアウト時間が，OSのTCPの再送タイマによるタイムアウト時間より大きいか，またはタイムアウト監視をしない設定の場合，TCPの再送タイマによるタイムアウト時間が有効となります。なお，再送タイマによるタイムアウトは，OSによって異なります。

8.3　JavaMailを利用する場合の注意事項

この節では，JavaMailを利用する場合の注意事項について説明します。

＜この節の構成＞

(1)　メソッドの例外発生について

(2)　POP3でのSEENフラグの動作について

(3)　JavaMailのプロバイダについて

(1)　メソッドの例外発生について

次のクラスのメソッドでは，JavaMail仕様どおりに例外が発生しません。

項番 | クラス名 | メソッド名
1 | javax.mail.Message | setFlag，setFlags
2 | javax.mail.Folder | setFlags

READ_ONLYを設定したjavax.mail.Folderオブジェクトから取得したjavax.mail.Messageオブジェクトに対して，表中に示したメソッドでフラグの値を変更しても，READ_WRITEを設定したときと同様に正しくフラグが設定されます。

ただし，POP3の場合，READ_ONLYでフォルダをオープンし，メッセージにDELETEDフラグを設定しても，実際にはメールは削除されません。

(2)　POP3でのSEENフラグの動作について

JavaMail仕様ではMessageのgetInputStreamメソッドとgetContentメソッドを使用した場合，SEENフラグが設定される仕様となっていますが，実際にはSEENフラグは設定されません。

(3)　JavaMailのプロバイダについて

アプリケーションサーバで使用できるJavaMailのプロバイダは，アプリケーションサーバがデフォルトで提供するSMTPおよびPOP3のプロバイダだけです。javamail.providersファイルを使用して別のプロバイダに差し替えた場合の動作は保証しません。

9.　セキュリティ管理

この章では，セキュリティ管理の機能について説明します。

＜この章の構成＞

9.1　この章の構成

9.2　SSL使用による認証情報とデータの暗号化

9.3　ロールに基づくWebコンテナのユーザ認証

9.4　SecurityManagerによるWebコンテナの実行時の保護

9.5　セキュリティアイデンティティを使用した認証

9.1　この章の構成

この章では，セキュリティ管理の機能について説明します。セキュリティ管理の機能には，Webコンテナで提供する，SSLによる暗号化，ロールに基づくユーザ認証，またはWebコンテナの実行時の保護機能があります。また，EJBコンテナとWebコンテナでは，セキュリティアイデンティティを使用した認証の機能が使用できます。

この章の構成を次の表に示します。

表9-1　この章の構成（セキュリティ管理機能）

機能 | 参照先
SSL使用による認証情報とデータの暗号化 | 9.2
ロールに基づくWebコンテナのユーザ認証 | 9.3
SecurityManagerによるWebコンテナの実行時の保護 | 9.4
セキュリティアイデンティティを使用した認証 | 9.5

9.2　SSL使用による認証情報とデータの暗号化

SSLをサポートするWebサーバとの連携では，WebサーバとWebクライアント間のSSLによる暗号化が有効になります。

この節の構成を次の表に示します。

表9-2　この節の構成（SSL使用による認証情報とデータの暗号化）

分類 | タイトル | 参照先
解説 | Webサーバの認証機能 | 9.2.1
通信路のセキュリティレベルの要請 | 9.2.2
SSLで使用された証明書情報の取得 | 9.2.3
実装 | DDでの定義 | 9.2.4
設定 | Hitachi Web ServerのSSLの設定 | 9.2.5
Hitachi Web ServerのSSLの設定（Webリダイレクタ環境の場合） | 9.2.6
Microsoft IISの設定（Webリダイレクタ環境の場合） | 9.2.7
実行環境での設定 | 9.2.8

注　「運用」について，この機能固有の説明はありません。

＜この節の構成＞

9.2.1　Webサーバの認証機能

9.2.2　通信路のセキュリティレベルの要請

9.2.3　SSLで使用された証明書情報の取得

9.2.4　DDでの定義

9.2.5　Hitachi Web ServerのSSLの設定

9.2.6　Hitachi Web ServerのSSLの設定（Webリダイレクタ環境の場合）

9.2.7　Microsoft IISの設定（Webリダイレクタ環境の場合）

9.2.8　実行環境での設定

9.2.1　Webサーバの認証機能

Webサーバの機能には，サーバ認証の機能とクライアント認証の機能があります。

サーバ認証

サーバ認証では，サーバにインストールされた鍵交換用の証書を用いて，ブラウザからサーバあてに共通鍵の基となる乱数情報を暗号化して送ります。

この暗号を解くための秘密鍵は，鍵交換用の証書の持ち主であるサーバだけが知っているので，クライアントから見て正当なサーバの場合だけ，ハンドシェイクが成立します。この過程では，サーバは電子署名をしませんが，ハンドシェイクの成立後にサーバが正当であるかどうかの見直しができます。

クライアント認証

クライアント認証では，サーバからブラウザに乱数データを送ってクライアントで電子署名を付与させて，ブラウザにインストールされた電子署名用の証書とともにサーバに送り返させます。

乱数データにブラウザが電子署名を付けて見せることで，ブラウザ自身が秘密鍵を保有していることをサーバに証明します。これによって，サーバ側では，クライアントが証明書に対応した秘密鍵を所有していることを確認できます。

なお，ここで説明するSSL関連の機能を使用する場合，あらかじめWebサーバであるHitachi Web ServerまたはMicrosoft IISにSSLの設定をしておく必要があります。Hitachi Web ServerまたはMicrosoft IISのSSLの設定方法については，次の個所説明を参照してください。

Hitachi Web Serverを使用する場合（Webリダイレクタ環境以外の場合）
「9.2.5　Hitachi Web ServerのSSLの設定」を参照してください。

Hitachi Web Serverを使用する場合（Webリダイレクタ環境以外の場合）
「9.2.6　Hitachi Web ServerのSSLの設定（Webリダイレクタ環境の場合）」を参照してください。

Microsoft IISを使用する場合
「9.2.7　Microsoft IISの設定（Webリダイレクタ環境の場合）」を参照してください。

9.2.2　通信路のセキュリティレベルの要請

WebアプリケーションからWebコンテナに対して，通信路の暗号化レベルの要請をします。通信路の暗号化レベルの要請は，Webサーバと連携する場合に使用できます。

暗号化レベルには，保護なし（NONE），改ざん防止（INTEGRAL），または秘匿（CONFIDENTIAL）の3段階を指定できます。暗号化レベルに，改ざん防止または秘匿が指定された場合に，SSLが使用されます。

この機能を使用すると，保護が要求されたページに対してアクセスできるのは，SSLを使用したアクセスだけに限定できます。保護が要請されたページに対してブラウザがHTTPでリクエストを送った場合，Webコンテナはブラウザに対してHTTPSで同じページに再度アクセスを要求するHTTPレスポンスを返します。その結果，ブラウザはHTTPSで同じページにアクセスし直します。なお，セキュリティレベルの設定は，Webアプリケーション全体だけではなく，Webアプリケーション内の一部のページに対しても指定できます。これによって，HTTPS以外での該当ページへのアクセスを防止します。

通信路の暗号化レベルの要請は，J2EEアプリケーションに含まれるWebアプリケーションのDD（WEB-INF/web.xml）として設定します。J2EEアプリケーションの設定については，「9.2.8　実行環境での設定」を参照してください。

注意

Webサーバと連携している場合で，転送先のHTTPSのポート番号を設定していない場合，保護が要請されたページに対してアクセスすると403エラーになります。

なお，インプロセスHTTPサーバまたは簡易Webサーバを使用している場合は転送先のHTTPSのポート番号の設定内容にかかわらず，保護が要請されたページにはアクセスできません。403エラーになります。

転送先のHTTPサーバのポート番号の設定は，J2EEサーバのプロパティをカスタマイズして設定します。J2EEサーバの動作設定のカスタマイズについては，「9.2.8　実行環境での設定」を参照してください。

9.2.3　SSLで使用された証明書情報の取得

サーブレットのAPIによって，ハンドシェイクで用いられた証書についての情報，およびハンドシェイクの結果選択された暗号化アルゴリズムについての情報を取得できます。

クライアント認証を用いた場合，クライアントが提示したX.509証書に記載された事項がjava.security.cert.X509Certificateクラスのオブジェクトとして取得できます。

なお，クライアント証明書情報をサーブレット内で取得できるのは，SSLのクライアント認証をした場合だけです。SSLのクライアント認証をする場合，Webサーバで設定する必要があります。

また，WebサーバにMicrosoft IISを使用してWebコンテナと連携している場合，Servlet v2.3仕様で定められている「javax.servlet.request.cipher_suite」によるSSL通信時の暗号化アルゴリズムの取得はできません。

9.2.4　DDでの定義

通信路の暗号化レベルの要請は，web.xmlに指定します。DDでの定義を次に示します。

<security-constraint>－<user-data-constraint>タグ
SSL使用による認証情報とデータの暗号化をする場合の暗号レベルを設定します。

なお，web.xmlの設定は，J2EEサーバにデプロイする前のWebアプリケーションで実施します。J2EEサーバにデプロイ済みのWebアプリケーションに設定する場合は属性ファイルに設定します。属性ファイルでの設定については，「9.2.8(2)　J2EEアプリケーションの設定」を参照してください。

9.2.5　Hitachi Web ServerのSSLの設定

Hitachi Web Serverを使用してSSLによる認証やデータの暗号化をする場合，秘密鍵の作成，認証局（CA）が発行した証明書の取得，およびhttpsd.conf（Hitachi Web Server定義ファイル）の設定が必要です。

また，クライアント認証をする場合，クライアント証明書と認証局（CA）の証明書の取得，およびhttpsd.conf（Hitachi Web Server定義ファイル）の設定が必要です。

ここでは，Hitachi Web ServerのSSLによる認証，暗号化の設定，およびクライアント認証の設定について説明します。なお，詳細については，マニュアル「Hitachi Web Server」を参照してください。

＜この項の構成＞

(1)　Hitachi Web ServerのSSLによる認証，暗号化の設定

(2)　クライアント認証の設定

(1)　Hitachi Web ServerのSSLによる認証，暗号化の設定

Hitachi Web Serverを使用してSSLによる認証やデータの暗号化をする場合，次の設定をしてください。

秘密鍵の作成と認証局が発行した証明書の取得

httpsd.confの設定

(a)　秘密鍵の作成と認証局が発行した証明書の取得

Hitachi Web Serverが用意しているsslcユティリティを使用し，次に示す手順に従って証明書発行局（CA）から証明書を取得します。なお，Hitachi Web Serverが提供するテスト用CAを利用する場合は，マニュアル「Hitachi Web Server」を参照してください。

秘密鍵の作成
sslc -genrsaコマンド（UNIXの場合，sslc genrsaコマンド）を使用して，Hitachi Web Server用の秘密鍵を作成します。

証明書発行要求（CSR）の作成
sslc -reqコマンド（UNIXの場合，sslc reqコマンド）を使用して，認証局（CA）に証明書を発行してもらうための証明書発行要求（CSR）を作成します。

認証局（CA）への証明書発行要求の送付
作成したCSRファイルを電子メールなどで認証局に送って証明書を取得してください。

(b)　httpsd.confの設定

httpsd.conf（Hitachi Web Server定義ファイル）に，次に示す設定を記述してください。

SSL通信用のポートの設定
ListenディレクティブにSSL通信で使用するポートを設定します。通常，SSL通信で使用するポート番号は443です。SSL通信で使用するポート番号を指定したListenディレクティブだけを定義した場合，そのサーバはブラウザからHTTPSのリクエスト（SSL通信）以外を受け付けなくなります。そのため，HTTPのリクエストも受け付ける場合には，HTTPのリクエスト用のポート番号（通常には80）を指定したListenディレクティブの指定は残した上で，SSL通信で使用するポート番号を指定したListenディレクティブを追加してください。

SSLを有効にする設定
SSLEnableディレクティブを指定します。

秘密鍵ファイルの設定
SSLCertificateKeyFileディレクティブに「(a) 秘密鍵の作成と認証局が発行した証明書の取得」で作成した秘密鍵ファイルへのパスを指定します。

認証局（CA）が発行した証明書ファイルの設定
SSLCertificateFileディレクティブに「(a) 秘密鍵の作成と認証局が発行した証明書の取得」で取得した証明書ファイルへのパスを指定します。

記述例

SSL通信に必要な設定をしたhttpsd.confの記述例を次に示します。なお，次の記述例は，ファイルの内容の一部となります。

Windowsの場合

ServerName localhost
Port 80
Listen 80

#--途中省略--
Listen 443
<VirtualHost host1:443>
SSLEnable
SSLCertificateFile "C:/Program Files/Hitachi/httpsd/conf/ssl/server/httpsdcert.pem"
SSLCertificateKeyFile "C:/Program Files/Hitachi/httpsd/conf/ssl/server/httpsdkey.pem"
</VirtualHost>
Include "C:/Program Files/Hitachi/Cosminexus/CC/web/redirector/mod_jk.conf"

UNIXの場合

ServerName localhost
Port 80
Listen 80

#--途中省略--
Listen 443
<VirtualHost host1:443>
SSLEnable
SSLCertificateFile "/opt/hitachi/httpsd/conf/ssl/server/httpsdcert.pem"
SSLCertificateKeyFile "/opt/hitachi/httpsd/conf/ssl/server/httpsdkey.pem"
</VirtualHost>
Include "/opt/Cosminexus/CC/web/redirector/mod_jk.conf"

(2)　クライアント認証の設定

クライアント認証をする場合，次の設定をしてください。

クライアント証明書と認証局（CA）の証明書の取得

httpsd.confの設定

(a)　クライアント証明書と認証局（CA）の証明書の取得

クライアント証明書の取得
証明書の発行に使用する認証局（CA）の指示に従って，Webブラウザにクライアント証明書をインストールします。

認証局（CA）の証明書の取得
クライアント証明書を発行した認証局（CA）の証明書（PEM形式）を入手します。

(b)　httpsd.confの設定

httpsd.conf（Hitachi Web Server定義ファイル）に，次に示す設定を記述してください。

認証局（CA）の証明書ファイルの設定
SSLCACertificateFileディレクティブに「(a)　クライアント証明書と認証局（CA）の証明書の取得」で取得した証明書ファイルへのパスを指定します。

クライアント認証についての設定
SSLVerifyClientおよびSSLVerifyDepthディレクティブを使用します。

クライアント証明書情報についての設定
SSLExportClientCertificatesおよびSSLExportCertChainDepthディレクティブを使用します。

記述例

クライアント認証に必要な設定をしたhttpsd.confの記述例を次に示します。なお，次の記述例は，ファイルの内容の一部となります。

Windowsの場合

ServerName localhost
Port 80
Listen 80

#--途中省略--
Listen 443
<VirtualHost host1:443>
SSLEnable
SSLCertificateFile "C:/Program Files/Hitachi/httpsd/conf/ssl/server/httpsdcert.pem"
SSLCertificateKeyFile "C:/Program Files/Hitachi/httpsd/conf/ssl/server/httpsdkey.pem"
SSLCACertificateFile "C:/Program Files/Hitachi/httpsd/conf/ssl/cacert/cacert.pem"
SSLVerifyClient 2
SSLVerifyDepth 2
SSLExportClientCertificates
SSLExportCertChainDepth 2
</VirtualHost>

Include "C:/Program Files/Hitachi/Cosminexus/CC/web/redirector/mod_jk.conf"

UNIXの場合

ServerName localhost
Port 80
Listen 80

#--途中省略--
Listen 443
<VirtualHost host1:443>
SSLEnable
SSLCertificateFile "/opt/hitachi/httpsd/conf/ssl/server/httpsdcert.pem"
SSLCertificateKeyFile "/opt/hitachi/httpsd/conf/ssl/server/httpsdkey.pem"
SSLCACertificateFile "/opt/hitachi/httpsd/conf/ssl/cacert/cacert.pem"
SSLVerifyClient 2
SSLVerifyDepth 2
SSLExportClientCertificates
SSLExportCertChainDepth 2
</VirtualHost>

Include "/opt/Cosminexus/CC/web/redirector/mod_jk.conf"

9.2.6　Hitachi Web ServerのSSLの設定（Webリダイレクタ環境の場合）

Hitachi Web Serverを使用してSSLによる認証やデータの暗号化をする場合，秘密鍵の作成，認証局（CA）が発行した証明書の取得，およびhttpsd.conf（Hitachi Web Server定義ファイル）の設定が必要です。

また，クライアント認証をする場合，クライアント証明書と認証局（CA）の証明書の取得，およびhttpsd.conf（Hitachi Web Server定義ファイル）の設定が必要です。

ここでは，Hitachi Web ServerのSSLによる認証，暗号化の設定，およびクライアント認証の設定について説明します。なお，詳細については，マニュアル「Hitachi Web Server」を参照してください。

＜この項の構成＞

(1)　Hitachi Web ServerのSSLによる認証，暗号化の設定

(2)　クライアント認証の設定

(1)　Hitachi Web ServerのSSLによる認証，暗号化の設定

Hitachi Web Serverを使用してSSLによる認証やデータの暗号化をする場合，次の設定をしてください。

秘密鍵の作成と認証局が発行した証明書の取得

httpsd.confの設定

(a)　秘密鍵の作成と認証局が発行した証明書の取得

Hitachi Web Serverが用意しているsslcユティリティを使用し，次に示す手順に従って証明書発行局（CA）から証明書を取得します。なお，Hitachi Web Serverが提供するテスト用CAを利用する場合は，マニュアル「Hitachi Web Server」を参照してください。

秘密鍵の作成
sslc -genrsaコマンド（UNIXの場合，sslc genrsaコマンド）を使用して，Hitachi Web Server用の秘密鍵を作成します。

証明書発行要求（CSR）の作成
sslc -reqコマンド（UNIXの場合，sslc reqコマンド）を使用して，認証局（CA）に証明書を発行してもらうための証明書発行要求（CSR）を作成します。

認証局（CA）への証明書発行要求の送付
作成したCSRファイルを電子メールなどで認証局に送って証明書を取得してください。

(b)　httpsd.confの設定

httpsd.conf（Hitachi Web Server定義ファイル）に，次に示す設定を記述してください。

SSL通信用のポートの設定
ListenディレクティブにSSL通信で使用するポートを設定します。通常，SSL通信で使用するポート番号は443です。SSL通信で使用するポート番号を指定したListenディレクティブだけを定義した場合，そのサーバはブラウザからHTTPSのリクエスト（SSL通信）以外を受け付けなくなります。そのため，HTTPのリクエストも受け付ける場合には，HTTPのリクエスト用のポート番号（通常には80）を指定したListenディレクティブの指定は残した上で，SSL通信で使用するポート番号を指定したListenディレクティブを追加してください。

SSLを有効にする設定
SSLEnableディレクティブを指定します。

秘密鍵ファイルの設定
SSLCertificateKeyFileディレクティブに「(a)　秘密鍵の作成と認証局が発行した証明書の取得」で作成した秘密鍵ファイルへのパスを指定します。

認証局（CA）が発行した証明書ファイルの設定
SSLCertificateFileディレクティブに「(a)　秘密鍵の作成と認証局が発行した証明書の取得」で取得した証明書ファイルへのパスを指定します。

記述例

SSL通信に必要な設定をしたhttpsd.confの記述例を次に示します。なお，次の記述例は，ファイルの内容の一部となります。

Windowsの場合

ServerName localhost
Port 80
Listen 80

#--途中省略--
Listen 443
<VirtualHost host1:443>
SSLEnable
SSLCertificateFile "C:/Program Files/Hitachi/httpsd/conf/ssl/server/httpsdcert.pem"
SSLCertificateKeyFile "C:/Program Files/Hitachi/httpsd/conf/ssl/server/httpsdkey.pem"
</VirtualHost>
Include "C:/Program Files/Hitachi/Cosminexus/CC/web/redirector/mod_jk.conf"

UNIXの場合

ServerName localhost
Port 80
Listen 80

#--途中省略--
Listen 443
<VirtualHost host1:443>
SSLEnable
SSLCertificateFile "/opt/hitachi/httpsd/conf/ssl/server/httpsdcert.pem"
SSLCertificateKeyFile "/opt/hitachi/httpsd/conf/ssl/server/httpsdkey.pem"
</VirtualHost>
Include "/opt/Cosminexus/CC/web/redirector/mod_jk.conf"

(2)　クライアント認証の設定

クライアント認証をする場合，次の設定をしてください。

クライアント証明書と認証局（CA）の証明書の取得

httpsd.confの設定

(a)　クライアント証明書と認証局（CA）の証明書の取得

クライアント証明書の取得
証明書の発行に使用する認証局（CA）の指示に従って，Webブラウザにクライアント証明書をインストールします。

認証局（CA）の証明書の取得
クライアント証明書を発行した認証局（CA）の証明書（PEM形式）を入手します。

(b)　httpsd.confの設定

httpsd.conf（Hitachi Web Server定義ファイル）に，次に示す設定を記述してください。

認証局（CA）の証明書ファイルの設定
SSLCACertificateFileディレクティブに「(a)　クライアント証明書と認証局（CA）の証明書の取得」で取得した証明書ファイルへのパスを指定します。

クライアント認証についての設定
SSLVerifyClientおよびSSLVerifyDepthディレクティブを使用します。

クライアント証明書情報についての設定
SSLExportClientCertificatesおよびSSLExportCertChainDepthディレクティブを使用します。

記述例

クライアント認証に必要な設定をしたhttpsd.confの記述例を次に示します。なお，次の記述例は，ファイルの内容の一部となります。

Windowsの場合

ServerName localhost
Port 80
Listen 80

#--途中省略--
Listen 443
<VirtualHost host1:443>
SSLEnable
SSLCertificateFile "C:/Program Files/Hitachi/httpsd/conf/ssl/server/httpsdcert.pem"
SSLCertificateKeyFile "C:/Program Files/Hitachi/httpsd/conf/ssl/server/httpsdkey.pem"
SSLCACertificateFile "C:/Program Files/Hitachi/httpsd/conf/ssl/cacert/cacert.pem"
SSLVerifyClient 2
SSLVerifyDepth 2
SSLExportClientCertificates
SSLExportCertChainDepth 2
</VirtualHost>

Include "C:/Program Files/Hitachi/Cosminexus/CC/web/redirector/mod_jk.conf"

UNIXの場合

ServerName localhost
Port 80
Listen 80

#--途中省略--
Listen 443
<VirtualHost host1:443>
SSLEnable
SSLCertificateFile "/opt/hitachi/httpsd/conf/ssl/server/httpsdcert.pem"
SSLCertificateKeyFile "/opt/hitachi/httpsd/conf/ssl/server/httpsdkey.pem"
SSLCACertificateFile "/opt/hitachi/httpsd/conf/ssl/cacert/cacert.pem"
SSLVerifyClient 2
SSLVerifyDepth 2
SSLExportClientCertificates
SSLExportCertChainDepth 2
</VirtualHost>

Include "/opt/Cosminexus/CC/web/redirector/mod_jk.conf"

9.2.7　Microsoft IISの設定（Webリダイレクタ環境の場合）

Microsoft IISのSSLの設定方法については，Microsoft IISのSSLのヘルプを参照してください。

9.2.8　実行環境での設定

通信路の暗号化レベルの要請の機能を使用する場合，J2EEサーバの設定，およびJ2EEアプリケーションの設定が必要です。

＜この項の構成＞

(1)　J2EEサーバの設定

(2)　J2EEアプリケーションの設定

(1)　J2EEサーバの設定

J2EEサーバの設定は，簡易構築定義ファイルで実施します。Webサーバが使用するポート番号の指定は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。

簡易構築定義ファイルでのWebサーバが使用するポート番号の指定を次に示します。

webserver.connector.redirect_https.port
Webサーバが使用しているHTTPSのポート番号を指定します。なお，この設定は，Webサーバと連携している場合だけ有効となります。

(2)　J2EEアプリケーションの設定

実行環境でのJ2EEアプリケーションの設定は，サーバ管理コマンドおよび属性ファイルで実施します。通信路の暗号化レベルの要請の設定には，WAR属性ファイルを使用します。

<security-constraint>－<user-data-constraint>タグ
SSL使用による認証情報とデータの暗号化をする場合の暗号レベルを設定します。

なお，WAR属性ファイルの設定は，J2EEサーバにデプロイ済みのWebアプリケーションに設定する場合に設定します。J2EEサーバにデプロイする前のWebアプリケーションで設定する場合は，web.xmlで設定します。web.xmlでの設定については，「9.2.4　DDでの定義」を参照してください。

9.3　ロールに基づくWebコンテナのユーザ認証

この節では，ロールを使用したユーザ認証について説明します。

Webコンテナはロールという仕組みに基づいて認証処理をします。ロールは，ユーザを管理するための単位です。各ユーザに一つ以上設定されます。一方，Webアプリケーションではコンテキスト内の特定のURLごとに，そのURLへアクセスするのに必要なロールを定義できます。認証処理は，Webクライアントが制限されたURLへリクエストをする場合に，次に示す二つの段階を踏みます。

認証によるリクエストが正当なユーザによるものであるかの判定

ユーザに設定されたロールと，アクセスするのに必要なロールが一致するかの判定

両方の判定で正当と認められたユーザだけが，制限されたURLへアクセスできます。

この節の構成を次の表に示します。

表9-3　この節の構成（ロールに基づくWebコンテナのユーザ認証）

分類 | タイトル | 参照先
解説 | ロールに基づくWebコンテナのユーザ認証の機能 | 9.3.1
実装 | DDでの定義 | 9.3.2
設定 | 実行環境での設定（J2EEアプリケーションの設定） | 9.3.3
注意事項 | 認証機能を併用するときの注意 | 9.3.4

注　「運用」について，この機能固有の説明はありません。

＜この節の構成＞

9.3.1　ロールに基づくWebコンテナのユーザ認証の機能

9.3.2　DDでの定義

9.3.3　実行環境での設定（J2EEアプリケーションの設定）

9.3.4　認証機能を併用するときの注意

9.3.1　ロールに基づくWebコンテナのユーザ認証の機能

アクセスするのに必要なロールは，J2EEアプリケーションに含まれるDD（WEB-INF/web.xml）内の<security-constraint>タグに指定します。J2EEアプリケーションの設定については，「9.3.2　DDでの定義」を参照してください。

ここでは，ロールに基づくWebコンテナのユーザ認証で実現できる機能について説明します。

＜この項の構成＞

(1)　ユーザ情報の管理

(2)　コンテナセキュリティとアクセス権管理

(3)　プログラムセキュリティ

(1)　ユーザ情報の管理

Webコンテナでは，各ユーザのユーザ名，パスワード，および所属するロールを，J2EEサーバ付属のユーザ管理機能によって定義し，保持・管理します。

(2)　コンテナセキュリティとアクセス権管理

Webコンテナでは，Webクライアントから特定のURLへのアクセスを制限できます。

特定のURLへのアクセスを制限するには，DD（WEB-INF/web.xml）に次に示す情報を記述します。

アクセスの制限対象となるURLパターン

アクセスするのに必要なロールなどのセキュリティ定義情報

ユーザに定義されたロールを取得するための認証方式

Webクライアントが認証に失敗した場合，またはユーザがアクセスするのに必要なロールを持たない場合には，アクセス制限対象となっているURLパターンへのアクセスはエラーになります。なお，認証に成功したクライアントは，セッションの有効期間内には再度認証の対象になることはありません。

セキュリティ定義情報，および認証方式を定義する方法は，Servlet API 2.3で規定されているDD（WEB-INF/web.xml）の仕様に従います。

なお，Webコンテナでの認証方式は，Basic認証とForm認証とがあります。これらは，J2EEアプリケーションに含まれるDD（WEB-INF/web.xml）に<login-config>タグを追加することで定義できます。J2EEアプリケーションの設定については，「9.3.2　DDでの定義」を参照してください。

注意

WebサーバにHitachi Web ServerまたはMicrosoft IISを使用する場合，WebコンテナによるBasic認証を正しく動作させるには，Webサーバ認証機能を解除しておく必要があります。

詳細については，「9.3.4　認証機能を併用するときの注意」を参照してください。

(3)　プログラムセキュリティ

DD（WEB-INF/web.xml）によってBasic，またはForm認証によるアクセス制限が設定されたサーブレット，JSPでは，HttpServletRequestの次に示すAPIを使用することで，ログインしたユーザのユーザ名やロール名などに応じて処理を切り替えるなど，プログラムレベルでのより細かいセキュリティ処理を行えます。

getRemoteUser()

isUserInRole()

getUserPrincipal()

これらのAPIの詳細については，Java Servlet Specification v2.3を参照してください。

9.3.2　DDでの定義

ロールに基づくWebコンテナのユーザ認証の設定は，web.xmlに指定します。DDでの定義を次の表に示します。

表9-4　ロールに基づくWebコンテナのユーザ認証の設定

指定するタグ | 設定内容
<security-constraint>タグ | セキュリティ制約を指定します。
<login-config>－<auth-method>タグ | Webコンテナでの認証方法を指定します。

なお，web.xmlの設定は，J2EEサーバにデプロイする前のWebアプリケーションで実施します。J2EEサーバにデプロイ済みのWebアプリケーションに設定する場合は属性ファイルに設定します。属性ファイルでの設定については，「9.3.3　実行環境での設定（J2EEアプリケーションの設定）」を参照してください。

9.3.3　実行環境での設定（J2EEアプリケーションの設定）

ロールに基づくWebコンテナのユーザ認証の設定は，サーバ管理コマンドおよび属性ファイルで実施します。ロールに基づくWebコンテナのユーザ認証の設定は，WAR属性ファイルを使用します。WAR属性ファイルでの定義を次の表に示します。

表9-5　ロールに基づくWebコンテナのユーザ認証の設定

指定するタグ | 設定内容
<security-constraint>タグ | セキュリティ制約を指定します。
<login-config>－<auth-method>タグ | Webコンテナでの認証方法を指定します。

なお，WAR属性ファイルの設定は，J2EEサーバにデプロイ済みのWebアプリケーションに設定する場合に設定します。J2EEサーバにデプロイする前のWebアプリケーションで設定する場合は，web.xmlで設定します。web.xmlでの設定については，「9.3.2　DDでの定義」を参照してください。

9.3.4　認証機能を併用するときの注意

ここでは，Webコンテナの認証機能と，Webサーバの認証機能を併用するときの注意について説明します。

＜この項の構成＞

(1)　認証の順序

(2)　Webサーバの基本認証とWebコンテナのBasic認証を併用するときの注意

(3)　WebサーバにMicrosoft IISを使用している場合の注意

(1)　認証の順序

Webコンテナが提供する認証機能とWebサーバの認証機能を併用した場合，次の順序で認証が実施されます。

Webサーバでの認証

Webコンテナでの認証

なお，Webサーバの認証機能とは，Webサーバの基本認証，SSLのサーバ認証，SSLのクライアント認証を指します。Web認証機能の併用とは，Webコンテナが提供する認証機能を使用している場合に，Webサーバの基本認証，SSLのサーバ認証，SSLのクライアント認証のどれか一つ以上を使用していることを指します。

Hitachi Web Serverのユーザ認証機能，およびアクセス制御機能については，マニュアル「Hitachi Web Server」を参照してください。

(2)　Webサーバの基本認証とWebコンテナのBasic認証を併用するときの注意

Webサーバの基本認証とWebコンテナのBasic認証を併用した場合は，Webサーバで認証されたユーザ名とパスワードがWebコンテナに引き継がれます。このため，WebサーバとWebコンテナには，共通のユーザ情報を定義する必要があります。

なお，Webサーバの認証後，Webコンテナでの認証の状況によっては，Webコンテナの動作が異なります。Webコンテナでの動作について次に示します。

Webサーバで認証されたユーザが，Webコンテナで認証されない場合
Webコンテナにユーザ名・パスワード入力のダイアログが表示されるので，そこにWebサーバとWebコンテナ共通のユーザ名・パスワードを入力します。

Webサーバで認証されたユーザが，Webコンテナにアクセスするのに必要なロールを持っていない場合
アクセス制御対象となっているURLパターンへのアクセスはエラーとなります。

Webサーバで認証されたユーザが，Webコンテナにアクセスするのに必要なロールを持っている場合
ユーザ名・パスワードの入力ダイアログが表示されることなく，アクセス制限対象となっているURLパターンへアクセスできます。

(3)　WebサーバにMicrosoft IISを使用している場合の注意

Webコンテナの認証を使用する場合，Microsoft IISで提供する次の認証機能には制限があります。

ダイジェスト認証
Webコンテナでの認証機能の使用の有無にかかわらず，ダイジェスト認証は使用できません。Microsoft IISで，必ずダイジェスト認証の設定を解除してください。

統合Windows認証
WebコンテナのBasic認証を使用する場合は，統合Windows認証は使用できません。Microsoft IISで，統合Windows認証の設定を解除してください。

9.4　SecurityManagerによるWebコンテナの実行時の保護

Java2のSecurityManagerに基づいたWebコンテナの実行時保護を実現します。これによって，次に示すような現象を防ぐことができます。

内部でSystem.exit()などを発行するような，不正なサーブレット，JSPによってWebコンテナ全体が勝手に終了する。

システムプロパティなどを勝手に書き換えるような不正なサーブレット，JSPによって，Webコンテナの実行に不具合が生じる。

なお，Webコンテナの保護はデフォルトで有効になっています。使用しない場合は，J2EEサーバを開始するcjstartsvコマンドに-nosecurityオプションを指定します。

9.5　セキュリティアイデンティティを使用した認証

この節では，セキュリティアイデンティティを使用した認証について説明します。

この節の構成を次の表に示します。

表9-6　この節の構成（セキュリティアイデンティティを使用した認証）

分類 | タイトル | 参照先
解説 | セキュリティアイデンティティの機能 | 9.5.1
設定 | セキュリティアイデンティティを使用した認証の設定 | 9.5.2

注　「実装」および「運用」について，この機能固有の説明はありません。

＜この節の構成＞

9.5.1　セキュリティアイデンティティの機能

9.5.2　セキュリティアイデンティティを使用した認証の設定

9.5.1　セキュリティアイデンティティの機能

セキュリティ管理機能を使用して，WebコンテナやEJBコンテナへのアクセス時のユーザ認証を実現できます。認証には，ユーザおよびパスワードを使用します。

セキュリティ管理機能での認証に成功した場合は，セキュリティアイデンティティという認証情報が作成され，WebコンテナやEJBコンテナに伝達されます。なお，認証に失敗した場合は例外が発生します。

認証処理でのセキュリティアイデンティティの流れを次の図に示します。

図9-1　認証処理でのセキュリティアイデンティティの流れ

また，セキュリティ管理では，中間コンポーネントで指定したセキュリティアイデンティティを伝達するRun as機能も使用できます。

Run as機能とは，Enterprise Beanを呼び出す中間コンポーネントで，クライアントでログインしたセキュリティアイデンティティと異なるセキュリティアイデンティティを指定すると，指定したセキュリティアイデンティティでEnterprise Beanの呼び出しができる機能です。Run as機能について次の図に示します。

図9-2　Run as機能

なお，アプリケーションサーバのセキュリティ管理機能では，コンポーネントへアクセスするときのメッセージを暗号化する機能，メッセージに署名を付ける機能，証明書による認証機能はサポートしていません。

9.5.2　セキュリティアイデンティティを使用した認証の設定

セキュリティアイデンティティを使用してセキュリティを管理する場合は，サーバ管理コマンドを使用して，ユーザおよびロールの情報を登録します。セキュリティアイデンティティを使用した認証およびRunAs機能を使用するためのJ2EEアプリケーションの設定を次の表に示します。

表9-7　セキュリティアイデンティティを使用した認証およびRunAs機能を使用するためのJ2EEアプリケーションの設定

機能
項目
設定対象
設定内容

セキュリティアイデンティティを使用した認証
セキュリティアイデンティティを使用した認証をするかどうか
Session Bean，
Entity Bean，
Message-driven Bean
Session Bean属性ファイル，Entity Bean属性ファイル，MessageDrivenBean属性ファイルの<security-identity>タグに，認証するかどうかを指定します。

RunAs機能
RunAs機能を使用するかどうか
Session Bean属性ファイル，Entity Bean属性ファイル，MessageDrivenBean属性ファイルの<run-as>タグに，RunAs機能を使用するかどうかを指定します。

RunAs機能で使用するセキュリティロール名
Session Bean属性ファイル，Entity Bean属性ファイル，MessageDrivenBean属性ファイルの<role-name>タグに，セキュリティロール名を指定します。

RunAs機能で使用するプリンシパル名
Session Bean属性ファイル，Entity Bean属性ファイル，MessageDrivenBean属性ファイルの<user-name>タグに，プリンシパル名を指定します。

セキュリティアイデンティティの設定手順については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「9.20　セキュリティの定義（セキュリティアイデンティティ）」を参照してください。

10.　アプリケーションの属性管理

この章では，アプリケーションの属性管理について説明します。アプリケーションを作成するに当たり，アプリケーションを構成する要素である，EJB-JAR属性，WAR属性，リソースなどを定義する必要があります。

アプリケーションサーバでは，ぞれぞれの属性ファイルにアプリケーションを使用する場合に必要な情報を定義します。また，cosminexus.xmlにアプリケーションサーバ独自の情報を定義してアプリケーションに含めることで，標準DDの定義とアプリケーションサーバ独自の定義を別々に管理できます。アプリケーションを設定するに当たって必要な属性ファイル，およびcosminexus.xmlを使ったアプリケーションの運用などについて説明します。

＜この章の構成＞

10.1　この章の構成

10.2　属性の管理

10.3　cosminexus.xmlを含むアプリケーション

10.4　DDの省略

10.1　この章の構成

アプリケーションの属性管理で説明する内容と参照先を次の表に示します。

表10-1　アプリケーションの属性管理で説明する内容と参照先

機能 | 参照先
属性の管理 | 10.2
cosminexus.xmlを含むアプリケーション | 10.3
DDの省略 | 10.4

10.2　属性の管理

アプリケーションサーバでは，DDとCosminexus アプリケーションサーバ独自の情報を定義するファイル（cosminexus.xml）を使ってアプリケーションを定義できます。

アプリケーションサーバでのDDのサポート範囲を次の表に示します。

表10-2　アプリケーションサーバでのDDのサポート範囲

DDの種類 | バージョン | サポート有無
application.xml | 1.2 | △※
1.3 | △※
1.4 | ○
5.0 | ○
DDなし（5.0） | ○
ejb-jar.xml | 1.1 | △
2.0 | ○
2.1 | ○
3.0 | ○
DDなし（3.0） | ○
web.xml | 2.2 | △
2.3 | ○
2.4 | ○
2.5 | ○
DDなし（2.5） | ○
ra.xml | 1.0 | ○
1.5 | ○

（凡例）

○：サポートする。

△：サポートするが，インポート時にDDのバージョンを書き換える。

注※

application.xmlのバージョンが1.2または1.3の場合，<context-root>がEARファイル内で一意でないときにも，インポート時にバージョンとして1.4が設定されます。

注意

バージョン3.0のejb-jar.xmlに指定できる要素

EJB-JARの<display-name>，インターセプタに関する要素，およびアプリケーション例外に関する要素が指定できます。これら以外の要素や属性を指定しても，無視されます。

具体的には，次の要素を指定できます。

/ejb-jar/display-name

/ejb-jar/assembly-descriptor/interceptor-binding，およびその配下の要素

/ejb-jar/assembly-descriptor/application-exception，およびその配下の要素

ejb-name要素に*を指定したinterceptor-binding要素が複数ある場合，いちばん上に記述された内容だけが使用されます。2番目以降の内容は無視されます。

<ejb-name>，<named-method>，およびその配下の要素すべてが一致する<interceptor-binding>が複数存在する場合，いちばん上に記述された内容だけが使用されます。2番目以降の内容は無視されます。

アプリケーションサーバでは，DDとcosminexus.xmlを別々に管理してJ2EEアプリケーションに含めることができます。cosminexus.xmlをJ2EEアプリケーションに含めることで，アプリケーションをインポートしたあとの属性ファイルの設定が不要になります。そのため，cosminexus.xmlを含むアプリケーションは，インポートしたあとそのまま開始して使用できます。

また，アプリケーションサーバでは，アプリケーションの属性を定義するDD（application.xml，ejb-jar.xmlおよびweb.xml）を省略できます。

10.3以降では，cosminexus.xmlを含むアプリケーションの作成のしかたおよび運用のしかたについて説明します。また，10.4以降では，DDの省略について説明します。

10.3　cosminexus.xmlを含むアプリケーション

この節では，cosminexus.xmlを含むアプリケーションの概要について説明します。

この節の構成を次の表に示します。

表10-3　この節の構成（cosminexus.xmlを含むアプリケーション）

分類 | タイトル | 参照先
解説 | cosminexus.xmlとは | 10.3.1
cosminexus.xmlを含むアプリケーションを使用する利点 | 10.3.2
cosminexus.xmlを含むアプリケーションの作成 | 10.3.3
実装 | cosminexus.xmlの作成 | 10.3.4
cosminexus.xmlの作成例 | 10.3.5
運用 | cosminexus.xmlを含むアプリケーションの運用 | 10.3.6
cosminexus.xmlを含まないアプリケーションから移行する手順 | 10.3.7

注　「設定」，および「注意事項」について，この機能固有の説明はありません。

＜この節の構成＞

10.3.1　cosminexus.xmlとは

10.3.2　cosminexus.xmlを含むアプリケーションを使用する利点

10.3.3　cosminexus.xmlを含むアプリケーションの作成

10.3.4　cosminexus.xmlの作成

10.3.5　cosminexus.xmlの作成例

10.3.6　cosminexus.xmlを含むアプリケーションの運用

10.3.7　cosminexus.xmlを含まないアプリケーションから移行する手順

10.3.1　cosminexus.xmlとは

cosminexus.xmlは，アプリケーションに関するCosminexus アプリケーションサーバ独自の定義情報を記載する属性ファイルです。cosminexus.xmlは，アプリケーションごとに作成できます。

cosminexus.xmlをアーカイブ形式のアプリケーションに含めてインポートまたはリデプロイしたり，展開ディレクトリ形式のアプリケーションに含めてアプリケーションを開始したりすることで，Cosminexus アプリケーションサーバ独自の定義情報を設定した状態でアプリケーションを実行できます。

cosminexus.xmlを含むアプリケーションの場合，DDの情報とCosminexus アプリケーションサーバ独自の情報が別々に管理されます。そのため，Cosminexus アプリケーションサーバ独自の情報を編集したときに，DDの情報を編集する必要がありません。cosminexus.xmlを含むアプリケーションでは，J2EEサーバ上でのコマンドによるアプリケーションの属性の設定が不要です。

cosminexus.xmlを含むアプリケーションの概念を図に示します。

図10-1　cosminexus.xmlを含むアプリケーションの概念図

cosminexus.xmlとDDの定義を関連づける例を次の図に示します。

図10-2　cosminexus.xmlとDDの定義を関連づける例

図について説明します。この例では，cosminexus.xmlによって，EJB-JARからのリソースの参照を解決して，リソースのプロパティを設定します。なお，説明の番号は図中の番号と対応しています。

<module-name>で対象とするEJB-JARを特定します。ここでは，adder.jarが対象になります。

adder.jarのDD（ejb-jar.xml）とcosminexus.xmlを関連づけます。ここでは，<ejb-name>で対象となるSession Bean（MyAdder）を特定します。

Session Bean（MyAdder）で参照しているリソース（MyRef）のリソース参照を解決します。<res-ref-name>に指定した名称に対する参照先として，リソースの表示名（DBC）を<linked-to>に指定します。

リソース（DBC）に対するプロパティを設定します。なお，cosminexus.xmlで設定できるのは，J2EEアプリケーションに含まれるリソースアダプタのプロパティです。

このcosminexus.xmlをJ2EEアプリケーションに含めてインポートすることで，J2EEサーバ上でのリソース参照解決やリソースアダプタのプロパティ設定が不要になります。

10.3.2　cosminexus.xmlを含むアプリケーションを使用する利点

cosminexus.xmlを含むアプリケーションを使用する利点を次に示します。

＜この項の構成＞

(1)　定義情報を最小限にできる

(2)　アプリケーションのインポートから開始までの手順を簡略化できる

(3)　DDを変更した際の属性ファイルの変更が不要

(1)　定義情報を最小限にできる

cosminexus.xmlを含むアプリケーションには，Cosminexus アプリケーションサーバ独自の定義情報のうち，ユーザがカスタマイズしたい情報だけを記述します。省略した場合はデフォルト値が使用されます。

(2)　アプリケーションのインポートから開始までの手順を簡略化できる

アプリケーションをインポートしたあと，アプリケーションの属性設定コマンド（cjgetapppropコマンドおよびcjsetapppropコマンド）による操作をしないでアプリケーションを実行できます。

cosminexus.xmlを含むアプリケーションとcosminexus.xmlを含まないアプリケーションでのアプリケーションのインポートから開始までの流れについて図で示します。

図10-3　cosminexus.xmlを含むアプリケーションとcosminexus.xmlを含まないアプリケーションのインポートから開始までの流れ

(3)　DDを変更した際の属性ファイルの変更が不要

cosminexus.xmlを含まないアプリケーションの場合，標準DDを変更してアプリケーションを入れ替えた場合，サーバ管理コマンドを使ってCosminexus アプリケーションサーバ独自の定義を設定し直す必要があります。しかし，cosminexus.xmlを含むアプリケーションの場合，Cosminexus アプリケーションサーバ独自の定義はDDと別のファイルで管理されているため，実行環境でサーバ管理コマンドを使って設定し直す必要がありません。

ただし，次に示す場合には，cosminexus.xmlを変更する必要があります。

Cosminexus アプリケーションサーバ独自の定義情報と標準DDおよびアノテーションの定義情報を関連づける情報（J2EEリソースのモジュール名など）を変更した場合

アプリケーションを開始するためにリンク解決が必要な定義情報（リソースなど）を追加した場合

cosminexus.xmlに記述した定義情報と，標準DDおよびアノテーションの定義情報を関連づける定義情報およびリンク解決が必要な定義情報については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「2.　Cosminexusアプリケーション属性ファイル（cosminexus.xml）」を参照してください。

10.3.3　cosminexus.xmlを含むアプリケーションの作成

ここでは，cosminexus.xmlを含むアプリケーションの作成について説明します。cosminexus.xmlを含むアプリケーションを作成するには，あらかじめクラスファイル，DD，およびcosminexus.xmlを作成する必要があります。cosminexus.xmlを含むアプリケーションを作成する流れを図で示します。

図10-4　cosminexus.xmlを含むアプリケーションを作成する流れ

クラスファイルの作成，DDの作成，およびcosminexus.xmlを含むアプリケーションの作成についてはマニュアル「Cosminexus アプリケーションサーバ アプリケーション開発ガイド」を参照してください。10.3.4以降では，cosminexus.xmlの作成について説明します。

10.3.4　cosminexus.xmlの作成

cosminexus.xmlを含むアプリケーションを作成するには，あらかじめ作成したcosminexus.xmlをアプリケーションに含める必要があります。cosminexus.xmlを作成する方法を次に示します。

図10-5　cosminexus.xmlを作成する方法

cosminexus.xmlを作成する方法には，DeveloperのMyEclipseを使って作成する方法とテキストエディタを使って作成する方法があります。それぞれの方法を，図中の（1）～（3）に沿って説明します。

＜この項の構成＞

(1)　Developerを使って作成する方法

(2)　テンプレートを使って作成する方法

(3)　テンプレートを使わないで作成する方法

(1)　Developerを使って作成する方法

アプリケーションサーバでは，DeveloperのMyEclipseを使ってcosminexus.xmlを作成できます。DeveloperのMyEclipseを使ってcosminexus.xmlを作成する方法については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション開発ガイド」の「5.3.1　cosminexus.xmlの作成」を参照してください。

(2)　テンプレートを使って作成する方法

テキストエディタを使ってcosminexus.xmlを作成する場合，テンプレートファイルを使用すると容易に作成できます。

テンプレートの格納場所を次に示します。

テンプレートの格納場所

Windowsの場合
<Cosminexusのインストール先>¥CC¥admin¥templates¥cosminexus.xml

UNIXの場合
/opt/Cosminexus/CC/admin/templates/cosminexus.xml

テンプレートをコピーしてEARまたはアプリケーションディレクトリ内に格納します。EARまたはアプリケーションディレクトリ内でのcosminexus.xmlの格納先を次に示します。

cosminexus.xmlの格納先

EAR内の格納先（アーカイブ形式のアプリケーションの場合）
<EARのルート>/META-INF/cosminexus.xml

アプリケーションディレクトリ内の格納先（展開ディレクトリ形式のアプリケーション場合）
展開ディレクトリ形式のアプリケーションでのcosminexus.xmlの格納先については，「12.4.2　アプリケーションディレクトリの構成」を参照してください。

注意

テンプレートには，DOCTYPE要素に指定するスキーマ定義ファイルの格納先として，Cosminexusのインストール先の書き換えを前提としたURL「file:///<Cosminexusのインストール先>/CC/admin/dtds/cosminexus_8_0.dtd」が記載されています。XMLエディタを使ってcosminexus.xmlを編集する前に，cosminexus.xmlのDOCTYPE要素に定義するファイルパスを書き換えてください。

Cosminexusのインストール先がD:¥Cosminexusの場合の，ファイルパスの書き換えの例を示します。

<!DOCTYPE cosminexus-app PUBLIC '-//Hitachi, Ltd.//DTD Cosminexus 8.0//EN' 'file:///D:/Cosminexus/CC/admin/dtds/cosminexus_8_0.dtd'>

(3)　テンプレートを使わないで作成する方法

テンプレートを使わないでcosminexus.xmlを作成する場合は，マニュアルを基に，テキストエディタを使ってCosminexus アプリケーションサーバ独自の情報を定義します。テキストエディタを使ってcosminexus.xmlの作成する場合に必要なDOCTYPE要素，およびcosminexus.xmlの定義内容については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「2.　Cosminexusアプリケーション属性ファイル（cosminexus.xml）」を参照してください。

10.3.5　cosminexus.xmlの作成例

テキストエディタを使ったcosminexus.xmlの作成例を示します。ここでは，次のDDの定義内容を基にcosminexus.xmlを作成します。

標準DDの定義内容

Webアプリケーションのモジュール名：war/webapp.war

Servlet名：MyServ

Servlet（MyServ）から参照するリソース名：DB_Connector_for_Oracle

cosminexus.xmlの作成例を図で説明します。

図10-6　cosminexus.xmlの作成例

図中の1.～3.について説明します。

テンプレートファイルを基に，cosminexus.xmlを作成する。
テンプレートファイルをコピーしてEARまたはアプリケーションディレクトリ内に格納します。コピーしたテンプレートファイルは，テキストエディタを使って編集します。

EJB／Servletおよびリンク解決を特定するキー（モジュール名やリソース名）を設定する。
DDで定義した情報と関連づけるキーを設定します。ここでは，Webアプリケーションのモジュール名，および参照しているリソース名を設定しています。

リンク解決したいリソース名を設定する。
2.で設定したキーのリンク解決をするリソースを設定します。

なお，cosminexus.xmlの定義内容の詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「2.1　Cosminexusアプリケーション属性ファイル（cosminexus.xml）の指定内容」を参照してください。

10.3.6　cosminexus.xmlを含むアプリケーションの運用

ここでは，cosminexus.xmlを含むアプリケーションの運用について説明します。

＜この項の構成＞

(1)　cosminexus.xmlを含むアプリケーションを新規作成する流れ

(2)　アプリケーションのインポート

(3)　アプリケーションの開始

(4)　アプリケーションの開始後に定義情報を変更する流れ

(5)　アプリケーションの入れ替え

(6)　アプリケーションのエクスポート

(7)　アプリケーションからのJ2EEリソースの削除

(1)　cosminexus.xmlを含むアプリケーションを新規作成する流れ

cosminexus.xmlを含むアプリケーションを新規で作成する流れについて説明します。

cosminexus.xmlを含むアプリケーションは，開発環境で作成します。作成したアプリケーションを実行環境へインポートし，アプリケーションを開始します。

開発環境でのcosminexus.xmlを含むアプリケーションの作成から，実行環境でのアプリケーションの開始までの流れを図で説明します。

図10-7　cosminexus.xmlを含むアプリケーションの作成から実行環境でのアプリケーションの開始までの流れ

図中の1.～3.について説明します。

cosminexus.xmlを含めたアプリケーションの作成
クラスファイル，標準DDおよびcosminexus.xmlを作成し，アプリケーションの形式に合わせてアーカイブしたりアプリケーションディレクトリに配置したりします。クラスファイル，DD，およびcosminexus.xmlを含むアプリケーションの作成については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション開発ガイド」を参照してください。また，テキストエディタを使ったcosminexus.xmlの作成については，「10.3.4　cosminexus.xmlの作成」を参照してください。

アプリケーションのインポート
開発環境で作成したアプリケーションを実行環境へインポートします。アプリケーションのインポートについては，「(2)　アプリケーションのインポート」を参照してください。

アプリケーションの開始
インポートしたアプリケーションを開始します。アプリケーションの開始方法については，「(3)　アプリケーションの開始」を参照してください。

(2)　アプリケーションのインポート

cosminexus.xmlを含むアプリケーションのインポートについて説明します。

cosminexus.xmlを含むアプリケーションの場合，インポートするタイミングでcosminexus.xmlの情報が読み込まれます。アプリケーションをインポートするには，cjimportappコマンドを実行します。cjimportappコマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。また，J2EEアプリケーションのインポートに関する注意事項については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「8.1　J2EEアプリケーションのインポート」を参照してください。

(3)　アプリケーションの開始

cosminexus.xmlを含むアプリケーションの開始について説明します。

cosminexus.xmlを含むアプリケーションを開始する手順は，cosminexus.xmlを含まないアプリケーションを開始する手順と変わりません。アプリケーションを開始するにはcjstartappコマンドを実行します。cjstartappコマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。また，J2EEアプリケーションの開始に関する注意事項については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「10.2.1　J2EEアプリケーションの開始」を参照してください。

cosminexus.xmlを含むアプリケーションを実行環境で開始したあとで一度アプリケーションを停止し，再度，アプリケーションを開始する場合のアプリケーションの動作について説明します。

ここでは，アプリケーションを再開始した際のアプリケーションの形式が，アーカイブ形式の場合，展開ディレクトリ形式の場合，cosminexus.xmlを含まないアプリケーションの場合に分けて説明します。

アーカイブ形式のアプリケーションの場合
アーカイブ形式のアプリケーションにcosminexus.xmlが含まれている場合，アプリケーションに含まれているcosminexus.xmlの情報が読み込まれます。アーカイブ形式のアプリケーションには，停止する前のアプリケーションに対するサーバ管理コマンドを使った定義情報の変更は反映されません。

展開ディレクトリ形式の場合
展開ディレクトリ形式のアプリケーションにcosminexus.xmlが含まれている場合，アプリケーションを開始するときに，実行環境で変更したCosminexus アプリケーションサーバ独自のアプリケーションに関する情報を上書きします。つまり，展開ディレクトリ形式のアプリケーションの場合には，サーバ管理コマンドを使った定義情報の変更がファイルに反映されます。

アプリケーションにcosminexus.xmlが含まれていない場合
アプリケーションにcosminexus.xmlが含まれていない場合は，前回アプリケーションを開始した際のCosminexus アプリケーションサーバ独自の定義内容でアプリケーションを開始します。

(4)　アプリケーションの開始後に定義情報を変更する流れ

開発環境からインポートしたアプリケーションを実行環境で開始したあとで，アプリケーションの定義情報を変更したい場合の手順について説明します。

cosminexus.xmlを含むアプリケーションの定義を変更する場合，アプリケーションの形式がアーカイブ形式か，または展開ディレクトリ形式かによって手順が異なります。

アプリケーションの形式ごとに，定義内容の変更手順について説明します。

参考

cosminexus.xmlを含まないアプリケーションと同じように，サーバ管理コマンド（cjgetapppropコマンドおよびcjsetapppropコマンド）を使ったアプリケーションの定義内容の変更もできます。

注意

cosminexus.xmlを含むアプリケーションの定義情報を変更する場合の注意事項を示します。

Cosminexus アプリケーションサーバ独自の定義情報をすべてデフォルト値に戻したい場合は，cosminexus.xmlのファイルから，<cosminexus-app>要素以外すべての要素を削除してください。

サーバ管理コマンドを使ってアプリケーションの定義を変更した場合の注意事項を，アプリケーションの形式ごとに説明します。

アーカイブ形式の場合

リデプロイ機能による定義情報の変更では，Cosminexus アプリケーションサーバのアプリケーションの実行時情報をいったんデフォルトに戻したあとで，入れ替え後のcosminexus.xmlに定義されている情報を読み込みます。そのため，サーバ管理コマンドで設定した定義情報はすべて失われます。

展開ディレクトリ形式の場合

サーバ管理コマンドを使用して変更したアプリケーションの属性の内容は，そのままアプリケーションディレクトリ内のcosminexus.xmlに反映されます。

なお，リロード機能では，cosminexus.xmlの定義情報は読み込まれません。変更した定義情報を反映したい場合は，アプリケーションの再開始が必要です。アプリケーション統合属性ファイルとサーバ管理コマンドを使用して定義情報を変更する場合については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「9.　J2EEアプリケーションのプロパティ設定」を参照してください。

(a)　アーカイブ形式の場合

cosminexus.xmlを含むアプリケーションがアーカイブ形式の場合の変更手順について説明します。なお，cosminexus.xmlを含むアプリケーションの定義情報は，ここで示した手順だけでなく，サーバ管理コマンドと属性ファイルを使う手順でも実行できます。

cosminexus.xmlを含むアプリケーションを実行環境で開始したあとで，定義内容を変更したい場合は，開発環境でアプリケーションの定義内容を変更します。開発環境で定義内容を変更してアーカイブし直したあと，再度アプリケーションを実行環境へインポートし，アプリケーションを入れ替えます。

また，稼働中のJ2EEアプリケーションを実行時情報付きZIP形式にしてエクスポートできます。実行時情報付きZIP形式のアプリケーションの操作手順は，cosminexus.xmlを含むアプリケーションとcosminexus.xmlを含まないアプリケーションとで差異はありません。アプリケーションのエクスポートについては「(6)　アプリケーションのエクスポート」を参照してください。

cosminexus.xmlを含むアプリケーションの定義内容の変更手順について図で説明します。

図10-8　cosminexus.xmlを含むアプリケーションの定義内容の変更手順（アーカイブ形式の場合）

図中の1.～4.について説明します。

cosminexus.xmlの編集
cosminexus.xmlを含むアプリケーションを実行環境へインポートしたあとで，定義情報を変更する場合，開発環境でcosminexus.xmlを編集します。cosminexus.xmlの編集については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション開発ガイド」の「5.3.2　cosminexus.xmlエディタの操作方法」を参照してください。

EARの再アーカイブ
編集したcosminexus.xmlをアプリケーションに含めてアーカイブします。EARの再アーカイブについては，マニュアル「Cosminexus アプリケーションサーバ アプリケーション開発ガイド」の「14.4.3　EARファイルの作成（jarコマンド）」を参照してください。

アプリケーションの入れ替え
開発環境で作成し直したアプリケーションを，実行環境で使用しているアプリケーションと入れ替えます。アプリケーションの入れ替えについては，「(5)　アプリケーションの入れ替え」を参照してください。

アプリケーションの開始
アプリケーションを開始します。アプリケーションの開始方法については，「(3)　アプリケーションの開始」を参照してください。

ポイント

サーバ管理コマンドを使ってcosminexus.xmlの定義情報を変更した場合，アプリケーションを入れ替えたときに入れ替え後のJ2EEアプリケーションに含まれるcosminexus.xmlの定義情報が上書きされます。cosminexus.xmlの定義情報を変更する場合は，開発環境でcosminexus.xmlを編集し，アプリケーションをリデプロイまたは再度インポートし直してください。

サーバ管理コマンドを使用して定義情報を変更する方法については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「9.　J2EEアプリケーションのプロパティ設定」を参照してください。

(b)　展開ディレクトリ形式の場合

cosminexus.xmlを含むアプリケーションが展開ディレクトリ形式の場合の変更手順について説明します。

cosminexus.xmlを含むアプリケーションの定義内容の変更手順について図で説明します。

図10-9　cosminexus.xmlを含むアプリケーションの定義内容の変更手順（展開ディレクトリ形式）

図中の1.～4.について説明します。

cosminexus.xmlの編集
cosminexus.xmlを含むアプリケーションを実行環境へインポートしたあとで，定義情報を変更する場合，開発環境でcosminexus.xmlを編集します。cosminexus.xmlの編集については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション開発ガイド」の「5.3.2　cosminexus.xmlエディタの操作方法」を参照してください。

アプリケーションディレクトリへの配置
編集したcosminexus.xmlをアプリケーションディレクトリへ配置します。アプリケーションディレクトリへ配置については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション開発ガイド」の「1.3.1　展開ディレクトリ形式のJ2EEアプリケーション」を参照してください。

アプリケーションの停止
実行環境で使っているアプリケーションを停止します。アプリケーションの停止については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「10.2.2　J2EEアプリケーションの停止」を参照してください。

アプリケーションの開始
インポートしたアプリケーションを開始します。アプリケーションの開始については「(3)　アプリケーションの開始」を参照してください。

(5)　アプリケーションの入れ替え

cosminexus.xmlを含むアプリケーションの入れ替えについて説明します。

アーカイブ形式のアプリケーションを入れ替えるには，リデプロイ機能を使用します。リデプロイ機能を使ってアプリケーションを入れ替える場合，入れ替え後のアプリケーションに含まれるcosminexus.xmlの情報が再度読み込まれます。開発環境でcosminexus.xmlを変更し，EARファイルにアーカイブし直してリデプロイを実行することで，Cosminexus アプリケーションサーバ独自の定義情報が変更されます。

なお，入れ替えるアプリケーションにcosminexus.xmlが含まれていない場合，入れ替え前のcosminexus.xmlの定義情報を引き継ぎます。※

リデプロイ機能を使用するには，cjreplaceappコマンドを使用します。cjreplaceappコマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjreplaceapp（アプリケーションの入れ替え）」を参照してください。また，リデプロイ機能に関する注意事項については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「10.6.1　アーカイブ形式のアプリケーション」を参照してください。

注※　入れ替えるアプリケーションのcosminexus.xmlの有無にかかわらず，DDの入れ替えはできません。

注意

アーカイブ形式のアプリケーションを入れ替える場合の注意事項を示します。

cosminexus.xmlを含むアプリケーションに対して，サーバ管理コマンドでCosminexus アプリケーションサーバ独自の定義情報を変更したあとでリデプロイ機能を使用すると，サーバ管理コマンドで変更したCosminexus アプリケーションサーバ独自の情報は失われます。

Cosminexus アプリケーションサーバ独自の情報をすべてデフォルト値に戻したい場合は，cosminexus.xmlから<cosminexus-app>以外の要素をすべて削除してから，cosminexus.xmlを含むアプリケーションを入れ替えてください。

(6)　アプリケーションのエクスポート

cosminexus.xmlを含むアプリケーションのエクスポートについて説明します。

アプリケーションをエクスポートするには，cjexportappコマンドを使用します。cjexportappコマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjexportapp（J2EEアプリケーションのエクスポート）」を参照してください。また，アプリケーションのエクスポートに関する注意事項については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「8.2　J2EEアプリケーションのエクスポート」を参照してください。

cosminexus.xmlを含むアプリケーションをアーカイブ形式でエクスポートした場合，エクスポートされたEARファイルにはcosminexus.xmlが含まれます。エクスポートの対象となるアプリケーションおよびエクスポートされたEARファイルの組み合わせを次に示します。

表10-4　エクスポートの対象となるアプリケーションおよびエクスポートされたEARファイルの組み合わせ

エクスポートの対象となるアプリケーションの形式 | エクスポートされたEARファイルの形式
cjexportappコマンドに-normalオプションを指定した場合 | cjexportappコマンドに-rawオプションを指定した場合
cosminexus.xmlを含むアプリケーション | cosminexus.xmlを含む実行時情報付きZIP形式 | cosminexus.xmlを含むEAR
cosminexus.xmlを含まないアプリケーション | cosminexus.xmlを含まない実行時情報付きZIP形式 | cosminexus.xmlを含まないEAR

注意

cosminexus.xmlの定義情報を変更，追加，および削除したアプリケーションをエクスポートした場合に，J2EEアプリケーションに含まれるcosminexus.xmlに関する注意事項を示します。

コメントは保持されません。

文字エンコードはUTF-8になります。

エクスポートしたEAR/ZIPに含まれるのはJ2EEサーバが最後に読み込みに成功したcosminexus.xmlです。J2EEサーバがcosminexus.xmlを読み込んだあとにアプリケーションディレクトリ内のcosminexus.xmlを変更しても，変更後の定義情報はエクスポートしたEAR/ZIPに含まれません。例えば，展開ディレクトリ形式のアプリケーションをインポートしたあと，アプリケーションディレクトリ内のcosminexus.xmlを書き換え，アプリケーションを開始しないでアプリケーションをEAR形式でエクスポートした場合，EARにはインポートした時と同様のcosminexus.xmlが含まれます。インポート後に更新したアプリケーションディレクトリ内のcosminexus.xmlは含まれません。

(7)　アプリケーションからのJ2EEリソースの削除

アプリケーションからJ2EEリソースを削除する場合，cosminexus.xmlに削除するJ2EEリソースの情報が含まれていても，その情報は削除されません。

アプリケーション内にない要素をカスタマイズする定義情報がcosminexus.xmlにある場合，cosminexus.xmlを読み込むサーバ管理コマンドの実行時に警告メッセージが出力されます。

10.3.7　cosminexus.xmlを含まないアプリケーションから移行する手順

ここでは，cosminexus.xmlを含まないアプリケーションからcosminexus.xmlを含むアプリケーションに移行する手順について説明します。

次の手順でアプリケーションを移行してください。

移行前のアプリケーションからアプリケーション統合属性ファイルを取得します。
取得にはサーバ管理コマンド（cjgetappprop）を使用します。

cosminexus.xmlを作成します。
cosminexus.xmlとアプリケーション統合属性ファイルの対応については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「2.2.1　アプリケーション統合属性の詳細」を参照してください。

EAR（アーカイブ形式の場合）またはアプリケーションディレクトリ（展開ディレクトリ形式の場合）に手順2.で作成したcosminexus.xmlを含めます。

アプリケーションを入れ替えます。

正しくアプリケーションについての定義情報が移行できているかを検証します。
入れ替え後のアプリケーションからアプリケーション統合属性ファイルを取得して，手順1.で取得したファイルと比較することで検証できます。

10.4　DDの省略

アプリケーションサーバでは，application.xml，ejb-jar.xmlおよびweb.xmlを省略できます。ただし，モジュールやDDのバージョンの組み合わせによっては省略できないものもあります。

この節では，アプリケーションサーバで動作するアプリケーションでの各DDの省略値の組み合わせと，各DDを省略した場合の動作について説明します。

この節の構成を次の表に示します。

表10-5　この節の構成（cosminexus.xmlを含むアプリケーション）

分類 | タイトル | 参照先
解説 | アプリケーションサーバで実行できるアプリケーションの構成 | 10.4.1
application.xmlの有無による機能の違い | 10.4.2
application.xmlがある場合のモジュールの決定規則 | 10.4.3
application.xmlがない場合のモジュールの決定規則 | 10.4.4
web.xmlを省略したWebアプリケーションに対する操作 | 10.4.5
DDを省略した場合に設定される表示名 | 10.4.6
application.xmlを省略した場合にapplication.xmlが作成される操作 | 10.4.7
注意事項 | application.xmlを省略した場合にJ2EEアプリケーションにリソースを追加するときの注意 | 10.4.8

注　「設定」，「実装」および「運用」について，この機能固有の説明はありません。

＜この節の構成＞

10.4.1　アプリケーションサーバで実行できるアプリケーションの構成

10.4.2　application.xmlの有無による機能の違い

10.4.3　application.xmlがある場合のモジュールの決定規則

10.4.4　application.xmlがない場合のモジュールの決定規則

10.4.5　web.xmlを省略したWebアプリケーションに対する操作

10.4.6　DDを省略した場合に設定される表示名

10.4.7　application.xmlを省略した場合にapplication.xmlが作成される操作

10.4.8　application.xmlを省略した場合にJ2EEアプリケーションにリソースを追加するときの注意

10.4.1　アプリケーションサーバで実行できるアプリケーションの構成

アプリケーションサーバでは，次のDDを省略できます。

Java EE 5.0のapplication.xml

EJB 3.0のejb-jar.xml

Servlet 2.5のweb.xml

application.xmlのDDのバージョンとDDの省略，および各モジュールのDD（ejb-jar.xml，web.xml，ra.xml）のバージョンとDDの省略の組み合わせを表で示します。

表10-6　DDの組み合わせ

DDの種別 | application.xml
1.4以前※ | Java EE 5.0 | DDなし
ejb-jar.xml | 2.0以前※ | ○ | ○ | ○
2.1 | ○ | ○ | ○
3.0 | × | ○ | ○
DDなし（3.0） | ○ | ○ | ○
web.xml | 2.3以前※ | ○ | ○ | ○
2.4 | ○ | ○ | ○
2.5 | × | ○ | ○
DDなし（2.5） | × | ○ | ○
ra.xml | 1.0 | ○ | ○ | ○
1.5 | ○ | ○ | ○

（凡例）○：サポートする　×：サポートしない

注※　バージョンアップ，またはバージョンアップしたあとのサーバ管理コマンド実行時に，次に示すバージョンに変更になります。

表10-7　DDのバージョンアップ

DD | バージョンアップ前のバージョン | バージョンアップ後のバージョン
application.xml | 1.2 | 1.4
1.3
ejb-jar.xml | 1.1 | 2.0
web.xml | 2.2 | 2.3

参考

次のコマンドを実行したとき，J2EEアプリケーションがサポートしていない構成の場合はメッセージKDJE42361-Eを出力し，エラーとなります。

cjimportapp

cjreplaceapp

cjaddapp

10.4.2　application.xmlの有無による機能の違い

application.xmlを省略した場合，コマンドを実行したときのアセンブル機能およびデプロイ機能に違いが出ます。J2EEアプリケーションにapplication.xmlがある場合，およびapplication.xmlがない場合に分けて，サーバ管理コマンドの機能の違いを説明します。

表10-8　application.xmlの有無による機能の違い一覧

J2EEアプリケーションを操作するコマンド
application.xmlあり
application.xmlなし

cjimportapp

モジュールの決定

application.xmlによってモジュールを決定します。

J2EEアプリケーションの表示名

application.xmlの<display-name>タグによって決定します。<display-name>タグがなければEARファイル名によって決定します。

EJB-JARディレクトリ，WARディレクトリの決定

展開ディレクトリ形式（-aオプション指定）の場合，application.xmlの<module>タグに記述されたパス名から拡張子を除いた名称がとなります。

モジュールの決定

ファイルの位置，拡張子，およびファイルの内容によってモジュールを決定します。

J2EEアプリケーションの表示名

EARファイル名によって決定します。

EJB-JARディレクトリ，WARディレクトリの決定

展開ディレクトリ形式の場合，EJB-JARディレクトリ名の最後は「_jar」，WARディレクトリ名の最後は「_war」となります。

cjexportapp
application.xmlありのJ2EEアプリケーションをエクスポートします。
application.xmlなしのJ2EEアプリケーションをエクスポートします。

cjaddapp
J2EEアプリケーションへリソースを追加します。application.xmlにモジュールの情報を追加します。追加できるリソースファイルの拡張子に制限はありません。
J2EEアプリケーションへリソースを追加します。その際，リソースファイルの拡張子がapplication.xml省略時のJava EE仕様に準拠していない場合はエラーとなります。

cjsetappprop
属性ファイルに指定した内容を設定します。
属性ファイルに指定した内容を設定します。設定する内容によってapplication.xmlを作成します。

cjrenameapp
J2EEアプリケーション名を変更します。
J2EEアプリケーション名を変更します。application.xmlを作成します。

参考

次に示すサーバ管理コマンドの機能には，application.xmlがある場合とapplication.xmlがない場合とで差異はありません。

cjdeleteapp

cjstartapp

cjstopapp

cjchmodapp

cjgencmpsl

cjgetappprop

cjgetstubsjar

cjimportlibjar

cjdeletelibjar

cjlistlibjar

cjlistapp

cjreloadapp

cjreplaceapp

10.4.3　application.xmlがある場合のモジュールの決定規則

アプリケーション内にapplication.xmlがある場合，ライブラリJAR以外はJava EE仕様に従ってapplication.xmlの内容からモジュールを決定します。ただし，application.xmlのバージョンが1.4以前の場合，ライブラリJARはアプリケーションサーバ独自の仕様に従って決定します。ライブラリJARは，application.xmlのバージョンがJava EE 5.0以降の場合と，J2EE1.4以前の場合とでモジュールの決定規則が異なります。ライブラリJARのモジュールの決定規則について，application.xmlのバージョンがJava EE 5.0以降の場合と，J2EE1.4以前の場合とに分けて説明します。

＜この項の構成＞

(1)　application.xmlのバージョンがJava EE 5.0以降の場合

(2)　application.xmlのバージョンがJ2EE1.2，1.3，1.4の場合

(3)　ライブラリJARとして扱われるJARファイルの例

(1)　application.xmlのバージョンがJava EE 5.0以降の場合

application.xmlのバージョンがJava EE 5.0以降の場合，次に示すファイルを除いて，ライブラリディレクトリ直下と，J2EEアプリケーションのルート直下にあるJARファイル（拡張子が小文字の.jarのファイル）がライブラリJARと見なされます。

除外されるファイル

META-INFディレクトリ直下のapplication.xmlの<module>タグに書かれているファイル

J2EEアプリケーションのルート直下のhitachi-runtime.jar

application.xmlのバージョンがJava EE 5.0以降の場合のモジュールの決定規則を次に示します。

表10-9　application.xmlのバージョンがJava EE 5.0以降の場合のモジュールの決定規則

<library-directory>タグの値
ライブラリJAR※

存在するディレクトリ
/
<ファイル名>.jar

/以外

<ファイル名>.jar

<library-directory>タグの値/<ファイル名>.jar

存在しないディレクトリ
<ファイル名>.jar

存在するファイル
インポート時にKDJE42360-Eを出力してエラーにする。

空文字
<ファイル名>.jar

タグ自体が存在しない

<ファイル名>.jar

/lib（小文字）/<ファイル名>.jar

注※

「除外されるファイル」で示したファイルは除きます。

(2)　application.xmlのバージョンがJ2EE1.2，1.3，1.4の場合

次に示すファイル以外のJARファイル（拡張子が小文字の.jarのファイル）がライブラリJARと見なされます。

META-INFディレクトリ直下のapplication.xmlの<module>タグに書かれているファイル

J2EEアプリケーションのルート直下のhitachi-runtime.jar

(3)　ライブラリJARとして扱われるJARファイルの例

META-INFディレクトリ直下のapplication.xmlの<module>タグに<ライブラリディレクトリ>/<ファイル名>.jarと書いた場合，そのJARファイルはライブラリJARと認識されません。また，hitachi-runtime.jarもライブラリJARとして認識されません。ライブラリJARとして扱われるJARファイルの例を次に示します。

表10-10　ライブラリJARとして扱われるJARファイルの例

EARファイル内のパス | application.xmlのバージョン
J2EE1.4 | Java EE 5.0
<library-directory>の値
lib | library | タグなし
lib1.jar | ライブラリJAR | ライブラリJAR | ライブラリJAR | ライブラリJAR
lib/lib2.jar | ライブラリJAR | ライブラリJAR | － | －
library/lib3.jar | ライブラリJAR | － | ライブラリJAR | －

（凡例）－：該当なし

10.4.4　application.xmlがない場合のモジュールの決定規則

J2EEアプリケーションにapplication.xmlが存在しない場合のモジュールの決定規則について説明します。J2EEアプリケーションにapplication.xmlが存在しない場合は，アプリケーションの形式ごとにライブラリJARの決定規則が異なります。アプリケーションの形式ごとにモジュールの決定規則を説明します。

＜この項の構成＞

(1)　アーカイブ形式または-dオプションを指定してインポートした展開ディレクトリ形式のアプリケーションの場合

(2)　-aオプションを指定してインポートした展開ディレクトリ形式のアプリケーションの場合

(3)　EARファイル内またはアプリケーションディレクトリのライブラリディレクトリの扱われ方

(1)　アーカイブ形式または-dオプションを指定してインポートした展開ディレクトリ形式のアプリケーションの場合

application.xmlが含まれていないアプリケーションを，アーカイブ形式でインポートした場合，または展開ディレクトリ形式（cjimportappコマンドに-dオプションを指定）でインポートした場合，Java EE仕様に従ってモジュールが決定されます。モジュールが決定される順番を示します。

ファイルの拡張子が.warのファイルすべてを，Webモジュールと見なします。

ファイルの拡張子が.rarのファイルすべてをリソースアダプタと見なします。

libディレクトリをライブラリディレクトリと見なします。

libディレクトリ以下を除き，ファイルの拡張子が.jarのファイルについては次のように決定します。

META-INF/ejb-jar.xmlファイルを含む，またはEJBコンポーネントアノテーションを含むJARファイルはEJBモジュールと見なします。

「hitachi-runtime.jar」を除いたJ2EEアプリケーションのルート直下のJARファイルをライブラリJARと見なします。

これらのルールに該当しないすべてのファイルは無視されます。

ポイント

Webモジュールのコンテキストルート

Webモジュールのコンテキストルートは，アプリケーションパッケージのルートからWARファイルへの相対パス名から，拡張子である.warを除いたものになります。

このため，application.xmlを省略する場合，WARファイルへのパスのディレクトリ名，およびWARファイル名は，URI（RFC3986）で使用できる文字で指定してください。

Webモジュールの構成とコンテキストルートの例を次の図に示します。

図10-10　Webモジュールの構成とコンテキストルートの例（アーカイブ形式または-dオプションを指定してインポートした展開ディレクトリ形式のアプリケーションの場合）

なお，WARファイルへのパス名によっては，複数のWARファイルに対するコンテキストルートが重複することがあります。例えば，「sub/.war」という名称のWARファイルと，「sub.war」という名称のWARファイルがある場合，どちらのコンテキストルートも「sub」になります。

(2)　-aオプションを指定してインポートした展開ディレクトリ形式のアプリケーションの場合

application.xmlが含まれていないアプリケーションを，展開ディレクトリ形式（cjimportappコマンドに-aオプションを指定）でインポートした場合，次の規則に従って順番にWARディレクトリ，EJB-JARディレクトリ，モジュールが決定されます。次に，モジュールが決定する順番を記します。

アプリケーションディレクトリのルート以下の階層に「_war」で終わるディレクトリがある場合，そのディレクトリをWARディレクトリと見なします。ただし，次の条件に当てはまる場合は，WARディレクトリとは見なしません。

WARディレクトリ以下のディレクトリ

EJB-JARディレクトリ以下のディレクトリ

libディレクトリ

アプリケーションディレクトリのルート以下の階層に「_jar」で終わるディレクトリがある場合，そのディレクトリをEJB-JARディレクトリと見なします。ただし，次の条件に当てはまる場合は，EJB-JARディレクトリとは見なしません。

WARディレクトリ以下のディレクトリ

EJB-JARディレクトリ以下のディレクトリ

libディレクトリおよびlibディレクトリ以下のディレクトリ

WARディレクトリ以下，およびEJB-JARディレクトリ以下のファイルを除いて，ファイル名の拡張子が.rarのファイルすべてをリソースアダプタと見なします。

libディレクトリをライブラリディレクトリと見なします。

WARディレクトリ以下，EJB-JARディレクトリ以下，およびlibディレクトリ以下のファイルを除き，ファイル名の拡張子が.jarのファイルについては「hitachi-runtime.jar」を除いたJ2EEアプリケーションのルート直下のJARファイルをライブラリJARと見なします。

これらのルールに該当しないすべてのファイルは無視されます。

ポイント

Webモジュールのコンテキストルート

Webモジュールのコンテキストルートは，アプリケーションディレクトリからWARディレクトリへの相対パス名の後ろから，「_war」を除いたものになります。

このため，application.xmlを省略する場合，WARディレクトリへのパスのディレクトリ名，およびWARディレクトリ名は，URI（RFC3986）で使用できる文字で指定してください。

Webモジュールの構成とコンテキストルートの例を次の図に示します。

図10-11　Webモジュールの構成とコンテキストルートの例（-aオプションを指定してインポートした展開ディレクトリ形式のアプリケーションの場合）

なお，WARディレクトリへのパス名によっては，複数のWARディレクトリに対するコンテキストルートが重複することがあります。例えば，「sub/_war」という名称のWARディレクトリと，「sub_war」という名称のWARディレクトリがある場合，どちらのコンテキストルートも「sub」になります。

(3)　EARファイル内またはアプリケーションディレクトリのライブラリディレクトリの扱われ方

ここでは，application.xmlがない場合のEARファイル内またはアプリケーションディレクトリのライブラリディレクトリの扱われ方について示します。ライブラリディレクトリの扱われ方は，EARファイル内またはアプリケーションディレクトリに，libというディレクトリまたはファイルがある場合と，どちらもない場合で異なります。

表10-11　application.xmlがない場合のEARファイル内またはアプリケーションディレクトリのライブラリディレクトリの扱われ方

EARファイル内のlibまたはアプリケーションディレクトリ内のlib
扱われ方

ディレクトリがある場合
libがライブラリディレクトリとして扱われます。

ファイルがある場合
インポート時にKDJE42360-Eが出力され，エラーになります。

ディレクトリまたはファイルがない場合
ライブラリディレクトリはないものとして動作します。
（ほかの個所にあるlibは，ライブラリディレクトリとして扱われません）。

10.4.5　web.xmlを省略したWebアプリケーションに対する操作

web.xmlを省略した場合，サーバ管理コマンドでのWebアプリケーションに対する操作に制限があります。web.xml省略時のWebアプリケーションに対する操作の可否について，次の表に示します。

表10-12　web.xml省略時のWebアプリケーションに対する操作の可否

操作 | 操作の可否
コマンド | 引数 | 操作内容
cjaddapp | -type filter | フィルタの追加 | ×※1
-type war | WARファイルの追加 | ○
cjcopyres | -type war | WARファイルのコピー | ○
cjdeleteapp | -type filter | フィルタの削除 | ×※2
-type war | WARファイルの削除 | ○
なし | アプリケーションの削除 | ○
cjdeleteres | -type war | WARファイルの削除 | ○
cjexportapp | -raw | アプリケーションのエクスポート（実行時情報を含まない） | ○※3
-normal | アプリケーションのエクスポート（実行時情報を含む） | ○※3
cjgetappprop | -type war | WARファイルの属性の取得 | ○
-type all | アプリケーションの属性の取得 | ○
cjgetresprop | -type war | WARファイルの属性の取得 | ○
cjimportapp | J2EEアプリケーションのインポート | ○※4
cjimportres | -type war | WARファイルのインポート | ○※4
cjlistapp | -type war | WARファイルの一覧表示 | ○
cjlistres | -type war | WARファイルの一覧表示 | ○
cjreloadapp | アプリケーションのリロード | ○
cjreplaceapp | -replaceDD | アプリケーションの入れ替え（DDの定義を引き継がない） | ○
なし | アプリケーションの入れ替え（DDの定義を引き継ぐ） | ○
cjsetappprop | -type war | 属性設定 | 標準DDに関する情報 | ×※5
実行時情報 | ○
-type all | 属性設定 | 標準DDに関する情報 | ×※5
実行時情報 | ○
cjsetresprop | -type war | 属性設定 | 標準DDに関する情報 | ×※5
実行時情報 | ○
cjstartapp | アプリケーションの開始 | ○
cjstopapp | アプリケーションの停止 | ○

（凡例）　○：操作できる　×：操作できない

注※1　コマンド実行時にエラーが発生し，メッセージKDJE37606-Eが出力されます。

注※2　web.xmlを省略したアプリケーションにはフィルタを追加できないため，フィルタの削除もできません。

注※3　エクスポートしたファイルにweb.xmlを含みません。

注※4　インポートしたWARは，JSPおよび静的コンテンツだけが使用できます。

注※5　読み取り専用の属性として扱われるため，設定が無視されます。

10.4.6　DDを省略した場合に設定される表示名

アプリケーションサーバでは，DDを省略した場合インポートしたタイミングで表示名が補完されます。また，J2EEサーバが表示名の妥当性確認を実施します。インポート時の表示名の補完規則，および表示名の妥当性の確認について説明します。

＜この項の構成＞

(1)　インポート時の表示名の補完規則

(2)　表示名の妥当性の確認

(1)　インポート時の表示名の補完規則

EJB-JAR，WAR，RAR，またはEARの各J2EEコンポーネントのDDの<display-name>タグが設定されていない場合，J2EEサーバによって表示名が設定されます。表示名は，J2EEコンポーネントのファイル名，およびディレクトリ名を基に決められます。DDを省略した場合も同様にJ2EEサーバによって設定されます。その場合にファイル名，およびディレクトリ名として使用できる文字は半角英数字（0～9，A～Z，a～z），およびアンダースコア(_)です。EJB-JAR，WAR，RAR，またはEARの表示名を特定したい場合は，<display-name>タグを設定することをお勧めします。

(2)　表示名の妥当性の確認

J2EEアプリケーション，EJB-JAR，WAR，RARおよびその構成要素（Enterprise Bean，Servlet，JSP， Filter）のlang属性「en」の表示名に使用できる文字は，英数字（0～9，A～Z，a～z），およびアンダースコア(_)です。J2EEサーバは表示名に半角英数字以外の文字が含まれている場合は，その文字をアンダースコア「_」に変換して使用します。J2EEサーバはJ2EEアプリケーション，EJB-JAR，WAR，RARをインポートする際に表示名の妥当性を確認して，表示名に使用できない文字列が使用されている場合は警告メッセージKDJE42374-Wメッセージを出力します。

ただし，表示名が「TP1/Message Queue - Access」の場合は警告メッセージを出力しません。

表示名の妥当性を確認するサーバ管理コマンドについて説明します。

cjimportappコマンド
アプリケーションの表示名およびアプリケーションに含まれるJ2EEリソース（EJB-JAR，WAR，RAR，Enterprise Bean，Servlet/JSP，Filter）の表示名の妥当性が確認されます。実行時情報付きZIP形式では妥当性は確認されません。

cjimportresコマンド
J2EEリソース（EJB-JAR，WAR，RAR，Enterprise Bean，Servlet/JSP，Filter）の表示名の妥当性が確認されます。実行時情報付きRAR形式では妥当性は確認されません。

妥当性の確認が実施される表示名を次の表に示します。

表10-13　妥当性の確認を行う表示名の一覧

項番 | 表示名を表すDDの要素 | 定義の種別
1 | <application><display-name> | application.xmlの定義
2 | <ejb-jar><display-name> | ejb-jar.xmlの定義
3 | <ejb-jar><enterprise-beans><session><display-name> | ejb-jar.xmlの定義
4 | <ejb-jar><enterprise-beans><entity><display-name> | ejb-jar.xmlの定義
5 | <ejb-jar><enterprise-beans><message-driven><display-name> | ejb-jar.xmlの定義
6 | <web-app><display-name> | web.xmlの定義
7 | <web-app><filter><display-name> | web.xmlの定義
8 | <web-app><servlet><display-name> | web.xmlの定義
9 | <connector><display-name> | ra.xmlの定義

10.4.7　application.xmlを省略した場合にapplication.xmlが作成される操作

インポートしたJ2EEアプリケーションにapplication.xmlがない場合でも，次の操作を実行すると，application.xmlが作成されます。

cjsetapppropコマンドによって，各属性ファイルの次のどれかのタグの値を変更した場合

アプリケーション属性ファイル

<hitachi-application-property>/<description>

<hitachi-application-property>/<icon>/<small-icon>

<hitachi-application-property>/<icon>/<large-icon>

WAR属性ファイル

<hitachi-war-property>/<war-runtime>/<context-root>

cjrenameappコマンドを実行した場合

10.4.8　application.xmlを省略した場合にJ2EEアプリケーションにリソースを追加するときの注意

インポート済みのEJB-JARファイル，WARファイル，またはRARファイルをapplication.xmlを省略したJ2EEアプリケーションに追加する場合の注意事項を説明します。

J2EEアプリケーションにapplication.xmlが存在しない場合，リソースファイルの拡張子はJava EE仕様によって次のように決められています。

EJB-JARファイルの拡張子は.jar

WARファイルの拡張子は.war

RARファイルの拡張子は.rar

リソースファイルの拡張子がこれらの拡張子ではない場合，J2EEアプリケーションへの追加はできません。追加時にメッセージKDJE42366-Eを出力し，エラーとなります。

11.　アノテーションの使用

この章では，アノテーションの機能について説明します。

Servlet 2.4以降またはEJB 2.1以降のアプリケーションでアノテーションを使用する場合に参照してください。

＜この章の構成＞

11.1　この章の構成

11.2　アノテーションの指定

11.3　ロード対象のクラスとロード時に必要なクラスパス

11.4　DIの使用

11.5　アノテーションの参照抑止

11.6　アノテーションで定義した内容の更新

11.7　アノテーション使用時の注意事項

11.1　この章の構成

アノテーションとは，ソースコードにクラスやメソッドの付加情報などを埋め込むための記述方式です。アノテーションを使用することで，従来，DD（web.xmlまたはejb-jar.xml）で指定していた情報を，ServletやEnterprise Beanのソースコード上に指定できます。

この章の構成を次の表に示します。

表11-1　この章の構成（アノテーションの使用）

タイトル | 参照先
アノテーションの指定 | 11.2
ロード対象のクラスとロード時に必要なクラスパス | 11.3
DIの使用 | 11.4
アノテーションの参照抑止 | 11.5
アノテーションで定義した内容の更新 | 11.6
アノテーション使用時の注意事項 | 11.7

11.2　アノテーションの指定

この節では，アプリケーションサーバで指定できるアノテーションの種類，およびアノテーションを指定したアプリケーションの実装のポイントについて説明します。

この節の構成を次の表に示します。

表11-2　この節の構成（アノテーションの指定）

分類 | タイトル | 参照先
解説 | アノテーションを使用するメリットと指定できるアノテーション | 11.2.1
アノテーションを宣言したライブラリJARのクラスの使用 | 11.2.2
実装 | アノテーションを指定する場合のEnterprise Beanの実装 | 11.2.3

注　「設定」および「運用」について，この機能固有の説明はありません。

＜この節の構成＞

11.2.1　アノテーションを使用するメリットと指定できるアノテーション

11.2.2　アノテーションを宣言したライブラリJARのクラスの使用

11.2.3　アノテーションを指定する場合のEnterprise Beanの実装

11.2.1　アノテーションを使用するメリットと指定できるアノテーション

ここでは，アノテーションを使用するメリットと指定できるアノテーションについて説明します。

＜この項の構成＞

(1)　アノテーションを使用するメリット

(2)　Webアプリケーションで指定できるアノテーション

(3)　Enterprise Beanで指定できるアノテーション

(1)　アノテーションを使用するメリット

アノテーションを使用するメリットを次に示します。

ソースコードとDDに分散していた情報を，ソースコード上に集約できます。

WebアプリケーションやEnterprise BeanのDDを作成する必要がありません。

DIによって，ほかのEnterprise Beanやリソースへの参照を取得できます。

DIについては，「11.4　DIの使用」を参照してください。

(2)　Webアプリケーションで指定できるアノテーション

Webアプリケーションにアノテーションを指定できるのは，Servlet 2.4またはServlet 2.5の場合です。ただし，指定できるアノテーションは，Servlet 2.4とServlet 2.5の場合で異なります。

指定できるアノテーションについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス API編」の「2.1　対応するアノテーションのサポート範囲」を参照してください。

なお，@Resourceアノテーションで指定できるリソースのタイプについては，「11.4.1　@Resourceアノテーションで指定できるリソースのタイプ」を参照してください。また，@EJBおよび@Resourceアノテーションのname属性は，web.xmlのタグの要素と対応しています。対応については，標準仕様を確認してください。

ポイント

Servlet 2.3以前のバージョンのweb.xmlがある場合，アノテーションの指定は無効になります。

(3)　Enterprise Beanで指定できるアノテーション

Enterprise Beanにアノテーションを指定できるのは，EJB 2.1またはEJB 3.0の場合です。ただし，指定できるアノテーションは，EJB 2.1とEJB 3.0の場合で異なります。

指定できるアノテーションについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス API編」の「2.1　対応するアノテーションのサポート範囲」を参照してください。

なお，@RemoteHomeまたは@LocalHomeアノテーションを使用してホームインタフェースを指定する場合，指定されたホームインタフェースのcreateメソッドの戻り値がコンポーネントインタフェースとみなされます。

11.2.2　アノテーションを宣言したライブラリJARのクラスの使用

ライブラリJARに含まれるクラスは，各コンポーネントから使用されます。ライブラリJARのクラスに記述できるのは，そのクラスを使用するコンポーネントでサポートされているアノテーションです。

ライブラリJARで指定できるアノテーションには，次の制限があります。

ライブラリJARでは，コンポーネントを宣言するアノテーションは指定できません。指定しても無視されます。

ライブラリJAR内のコンポーネントであるクラスに定義されたアノテーションは，サポート対象外とします。

次のEJB-JARやWARから参照された場合，ライブラリJARで宣言されているアノテーションは無視されます。

EJB 2.1以前のモジュールを含むEJB-JAR

Servlet 2.4以前のモジュールを含むWAR

J2EE 1.4のJ2EEアプリケーションに含まれるEJB 3.0（DDなし）から参照された場合，ライブラリJARで宣言されているアノテーションは無視されます。

ライブラリJAR内のアノテーションを記述したクラスの使用例を次の図に示します。

図11-1　ライブラリJAR内のアノテーションを記述したクラスの使用例

EJB 3.0以降またはServlet 2.5以降から参照した場合，ライブラリJARに含まれる「@Resource」や「@EJB」が有効になります。EJB 2.1以前またはServlet 2.4以前のコンポーネントから参照した場合，ライブラリJARに含まれる「@Resource」や「@EJB」は無視されます。ただし，参照元のJ2EEアプリケーションのバージョンは，Java EE 5以上であることが前提です。

11.2.3　アノテーションを指定する場合のEnterprise Beanの実装

Enterprise Beanの場合，アノテーションは，Session Beanで指定できます。ここでは，アノテーションを指定して，Stateless Session Bean，またはStateful Session Beanを実装する場合のポイントについて説明します。

＜この項の構成＞

(1)　Stateless Session Beanの実装

(2)　Stateful Session Beanの実装

(1)　Stateless Session Beanの実装

Enterprise Beanの種類（Stateless Session Bean）は，@Statelessアノテーションで指定するか，またはDD（ejb-jar.xml）に指定します。

ビジネスインタフェースを使用してSession Beanを実装できます。

javax.ejb.SessionBeanインタフェースをインプリメントすることは，必須ではありません。

インターセプタクラスは，必要に応じて実装します。

Stateless Session Beanには，次のコールバックを定義できます。

@PostConstruct

@PreDestroy

コールバック，またはメソッドが呼び出されるタイミングについては，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.2.3　Enterprise Beanのライフサイクル」を参照してください。

(2)　Stateful Session Beanの実装

Enterprise Beanの種類（Stateful Session Bean）は，@Statefulアノテーションで指定するか，またはDD（ejb-jar.xml）に指定します。

ビジネスインタフェースを使用してSession Beanを実装できます。

javax.ejb.SessionBeanインタフェース，およびjava.io.Serializableインタフェースをインプリメントすることは，必須ではありません。

インターセプタクラスは，必要に応じて実装します。

次のコールバックを定義できます。

@PostConstruct

@PreDestroy

実装クラスのメソッドに@Initアノテーションおよび@Removeアノテーションを指定できます。

コールバック，またはメソッドが呼び出されるタイミングについては，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.2.3　Enterprise Beanのライフサイクル」を参照してください。

11.3　ロード対象のクラスとロード時に必要なクラスパス

アノテーション情報は，次のような操作を実行したときに読み込まれます。

リソースの追加（cjaddapp）※

インポート時（cjimportapp）

インポート時（cjimportres）

インポート時（cjimportlibjar）※

開始時（cjstartapp）

リプレース時（cjreplaceapp）

リロード時（cjreloadapp）

注※

対象となるのはライブラリJARのクラスです。

アノテーション情報を読み込むためには，まずクラスをロードする必要があります。

アノテーション情報を読み込むためにロードするクラスを次の図に示します。

図11-2　アノテーション情報を読み込むためにロードするクラス

EJB-JAR（ejb-jar.xmlのバージョンが2.1）に含まれるクラスファイルまたはWAR（web.xmlのバージョンが2.4）に含まれるクラスファイルからアノテーション情報を読み込む場合のアノテーションは，Cosminexus アプリケーションサーバ独自の仕様です。また，アプリケーションサーバでは，Cosminexus アプリケーションサーバ独自の仕様によって，J2EE 1.4の場合でもejb-jar.xmlの省略とアノテーションの使用ができます。

なお，J2EE 1.4以前に準拠したJ2EEアプリケーションの場合，EJB-JAR（ejb-jar.xmlのバージョンが2.1，またはejb-jar.xmlが省略されたもの）やWAR（web.xmlのバージョンが2.4）からライブラリJARを使用することはできません。指定しても無視されます。

アノテーション情報を取得するためにクラスをロードするかどうかは，各モジュールのバージョン，DD内の属性定義，およびJ2EEサーバで設定されているプロパティに依存します。

モジュールのバージョンがEJB-JAR（3.0）またはWAR（2.5）の場合のアノテーション情報を取得するかどうかの条件を次の表に示します。

表11-3　モジュールのバージョンがEJB-JAR（3.0）またはWAR（2.5）の場合

モジュール | DDのmetadata-completeタグ | DD省略
falseまたはタグを省略 | true
EJB-JAR（3.0） | ○ | － | ○
WAR（2.5） | ○ | － | ○

（凡例）

○：アノテーション情報を取得する

－：アノテーション情報を取得しない

モジュールのバージョンがEJB-JAR（2.1）またはWAR（2.4）の場合のアノテーション情報を取得するかどうかの条件を次の表に示します。

表11-4　モジュールのバージョンがEJB-JAR（2.1）またはWAR（2.4）の場合

モジュール
J2EEサーバのプロパティ
ejbserver.deploy.applications.metadata_complete

falseまたはプロパティを省略時
true

EJB-JAR（2.1）
○
－

WAR（2.4）
WEB-INF/classes以下
○
－

WEB-INF/lib/JARファイル
－
－

（凡例）

○：アノテーション情報を取得する

－：アノテーション情報を取得しない

ライブラリJARのアノテーション情報を取得するかどうかを次の表に示します。

表11-5　ライブラリJARの場合

モジュール | Java EE 5に準拠するJ2EEアプリケーション | J2EE 1.4以前に準拠するJ2EEアプリケーション
DDのmetadata-completeタグ | DD省略 | DDのmetadata-completeタグ | DD省略
falseまたはタグを省略 | true | falseまたはタグを省略 | true
EJB-JAR（3.0） | ○ | － | ○ | × | × | －
WAR（2.5） | ○ | － | ○ | × | × | ×

（凡例）

○：アノテーション情報を取得する（J2EEアプリケーションに一つでも該当するモジュールが含まれている場合，取得する）

－：アノテーション情報を取得しない

×：サポートされていない組み合わせである

注意

アノテーション情報を読み込むために必要なクラスが不足している場合，または不正なクラスがある場合は，アノテーション情報の取得処理中に例外が発生します。クラスのロード時に例外が発生した場合の挙動について次に示します。

アプリケーションサーバのバージョンが08-00以降の場合

例外ログ，およびメッセージKDJE42380-Wを出力し処理を続行します。なお，例外が発生した場合にエラーにしたいときは，プロパティejbserver.deploy.annotations.load_check.enabledの値をfalseからtrueへ変更してください。

アプリケーションサーバのバージョンが08-00よりも前の場合

エラーとなり処理を中断します。

11.4　DIの使用

Dependency Injection（DI）とは，EJBやインターセプタクラスのフィールドやsetterメソッドに，@EJBや@Resourceアノテーションを指定することで，Enterprise Beanやリソースへの参照をEJBコンテナが自動的にセットする機能です。DIを使用すると，Enterprise Beanやリソースへの参照を，JNDIを使用してルックアップする必要がなくなります。ここでは，@Resourceアノテーションで指定できるリソースのタイプ，@Resourceアノテーションを使用したリソースの参照解決，およびDIに関する注意事項について説明します。

この節の構成を次の表に示します。

表11-6　この節の構成（DIの使用）

分類 | タイトル | 参照先
解説 | @Resourceアノテーションで指定できるリソースのタイプ | 11.4.1
@Resourceアノテーションを使用したリソースの参照解決 | 11.4.2
DI失敗時の動作 | 11.4.3
注意事項 | 注意事項 | 11.4.4

注　「実装」，「設定」および「運用」について，この機能固有の説明はありません。

＜この節の構成＞

11.4.1　@Resourceアノテーションで指定できるリソースのタイプ

11.4.2　@Resourceアノテーションを使用したリソースの参照解決

11.4.3　DI失敗時の動作

11.4.4　注意事項

11.4.1　@Resourceアノテーションで指定できるリソースのタイプ

@Resourceアノテーションを使用して，リファレンスを定義できます。@Resourceアノテーションで指定できるリソースのタイプを次の表に示します。

表11-7　@Resourceアノテーションで指定できるリソースのタイプ

リソースのタイプ | 指定可否
javax.sql.DataSource※1 | ○
javax.mail.Session | ○
java.net.URL | ×
javax.jms.ConnectionFactory | ○
javax.jms.QueueConnectionFactory※2 | ○
javax.jms.TopicConnectionFactory | ○
javax.jms.Queue※2 | ○
javax.jms.Topic | ○
javax.resource.cci.ConnectionFactory※3 | ○
javax.resource.cci.InteractionSpec | ×
javax.transaction.UserTransaction | ○※4
org.omg.CORBA_ 2_3.ORB | ○※5
javax.xml.rpc.Service | ×
javax.xml.ws.Service | ×
javax.jws.WebService | ×
javax.ejb.EJBContext | ○※6
javax.ejb.SessionContext | ○※6
javax.ejb.TimerService | ○※6※7
JavaBeansリソース独自 | ○
java.lang.String | ○※8
java.lang.Character | ○※8
java.lang.Integer | ○※8
java.lang.Boolean | ○※8
java.lang.Double | ○※8
java.lang.Byte | ○※8
java.lang.Short | ○※8
java.lang.Long | ○※8
java.lang.Float | ○※8

（凡例）　○：指定できる　×：指定できない

注※1　DB Connectorが該当します。

注※2　TP1/Message Queue - Access，Cosminexus RMが該当します。

注※3　uCosminexus TP1 Connectorが該当します。

注※4　CMTで動作するEnterprise Beanまたはインターセプタでは使用できません。

注※5　ORBのshareable属性はtrueが指定されているものとして動作します。なお，注入されるORBオブジェクトは，ほかのコンポーネントでも使用される共有のインスタンスです。

注※6　Webコンテナ上で動作するクラスでは使用できません。

注※7　Stateful SessionBeanやStateful SessionBeanに適用されたインターセプタでは使用できません。

注※8　<env-entry-value>タグに，DIまたはルックアップで取得できる値を設定できません。

11.4.2　@Resourceアノテーションを使用したリソースの参照解決

@Resourceアノテーションを使用してリソースの参照解決をする方法には，次の2種類があります。

name属性にリソースの別名を指定する方法

mappedName属性に参照先リソースを指定する方法

@Resourceアノテーションに属性を指定しない場合は，cosminexus.xmlまたはcosminexus.xml以外の属性ファイルによってリンクを解決する必要があります。ここでは，それぞれの方法について説明します。

＜この項の構成＞

(1)　@Resourceアノテーションのname属性で指定する方法

(2)　@ResourceアノテーションのmappedName属性で指定する方法

(3)　cosminexus.xmlまたはそれ以外の属性ファイルで指定する方法

(4)　参照解決方法の優先順位

(1)　@Resourceアノテーションのname属性で指定する方法

@Resourceアノテーションのname属性にリソースの別名を指定します。

@Resourceアノテーションのname属性に指定できるリソースを次に示します。

javax.sql.DataSource

javax.jms.ConnectionFactory

javax.jms.QueueConnectionFactory

javax.jms.TopicConnectionFactory

javax.resource.cci.ConnectionFactory

コーディング例を次に示します。この例は，@Resourceアノテーションのname属性に別名「jdbc/ds」を設定する場合の例です。

package sample;

@Stateless public class MySessionBean implements MySession {
@Resource(name="jdbc/ds") public DataSource customerDB;
   ...
}

@Resourceアノテーションのname属性にリソースアダプタの別名を指定した場合，参照解決が自動で実施されます。そのため，属性ファイルを編集する必要はありません。属性ファイルを取得した場合は，次のようになります。

<resource-ref>
 <description xml:lang="en"></description>
 <res-ref-name>jdbc/ds</res-ref-name>
 <res-type>javax.sql.DataSource</res-type>
 <res-auth>Container</res-auth>
 <res-sharing-scope>Shareable</res-sharing-scope>
 <injection-target>
    <injection-target-class>sample.MySessionBean</injection-target-class>
    <injection-target-name>customerDB</injection-target-name>
 </injection-target>
 <linked-to></linked-to>
</resource-ref>

(2)　@ResourceアノテーションのmappedName属性で指定する方法

@ResourceアノテーションのmappedName属性にリソースの表示名やキュー表示名を指定します。

@ResourceアノテーションのmappedName属性に記述したリソース表示名が参照解決に使用されます。

コーディング例を次に示します。この例は，@ResourceアノテーションのmappedName属性にリソース表示名「DB_Connector_for_Oracle」を設定する場合の例です。

package sample;

@Stateless public class MySessionBean implements MySession {
@Resource(mappedName="DB_Connector_for_Oracle") public DataSource customerDB;
   ...
}

ここでは，@Resourceのname属性を省略しているため，デフォルト値「クラス名/フィールド名」が使用されます。この場合のデフォルト値は「sample.MySessionBean/customerDB」となります。属性ファイルを取得した場合は，次のようになります。

<resource-ref>
 <description xml:lang="en"></description>
 <res-ref-name>sample.MySessionBean/customerDB</res-ref-name>
 <res-type>javax.sql.DataSource</res-type>
 <res-auth>Container</res-auth>
 <res-sharing-scope>Shareable</res-sharing-scope>
 <mapped-name>DB_Connector_for_Oracle</mapped-name>
 <injection-target>
    <injection-target-class>sample.MySessionBean</injection-target-class>
    <injection-target-name>customerDB</injection-target-name>
 </injection-target>
 <linked-to></linked-to>
</resource-ref>

(3)　cosminexus.xmlまたはそれ以外の属性ファイルで指定する方法

@Resourceアノテーションの属性を指定しない場合，cosminexus.xmlやcosminexus.xml以外の属性ファイルを使って参照解決をする必要があります。cosminexus.xml，またはcosminexus.xml以外の属性ファイルの<linked-to>に，リソースの表示名を指定します。参照先リソースがキューの場合は，<linked-queue>にリソースアダプタの表示名とキュー表示名を記述します。参照先リソースが管理対象オブジェクトの場合は，<linked-adminobject>にリソースアダプタの表示名と管理対象オブジェクト名を記述します。

コーディング例を次に示します。この例では，@Resourceアノテーションのname属性を省略しているため，別名としてデフォルト値の「クラス名/フィールド名」が使用されます。ここでは，「sample.MySessionBean/customerDB」が設定されます。

package sample;

@Stateless public class MySessionBean implements MySession {
@Resource public DataSource customerDB;
   ...
}

cosminexus.xmlで参照解決をする場合は，<link-to>，<linked-queue>または<linked-adminobject>にリソースの表示名を指定してから，アプリケーションをインポートします。cosminexus.xml以外の属性ファイルで参照解決をする場合は，アプリケーションをインポートしたあとで，属性ファイル（アプリケーション統合属性ファイルなど）を取得します。取得した属性ファイルに，<linked-to><linked-queue>または<linked-adminobject>に参照先となるリソース表示名を記述します。

属性を設定したあとで属性ファイルを取得した場合は，次のようになります。

<resource-ref>
 <description xml:lang="en"></description>
 <res-ref-name> sample.MySessionBean/customerDB</res-ref-name>
 <res-type>javax.sql.DataSource</res-type>
 <res-auth>Container</res-auth>
 <res-sharing-scope>Shareable</res-sharing-scope>
 <injection-target>
    <injection-target-class>sample.MySessionBean</injection-target-class>
    <injection-target-name>customerDB</injection-target-name>
 </injection-target>
 <linked-to>DB_Connector_for_Oracle</linked-to>
</resource-ref>

(4)　参照解決方法の優先順位

@Resourceアノテーションを使用してリソースの参照解決をする場合に，複数の方法を同時に設定したときには，次の優先順位で設定が有効になります。

cosminexus.xmlまたはcosminexus.xml以外の属性ファイルによる設定

@ResourceアノテーションのmappedName属性の設定

@Resourceアノテーションのname属性の設定

J2EEリソースに異なる別名が同時に設定された場合に有効となる別名の設定について表に示します。

表11-8　複数の方法を同時に設定した場合に有効となる参照先の設定

name属性の設定の有無※1
mappedName属性の設定の有無
属性ファイル※2の<linked-to>などの設定の有無
有効となる別名の設定※3

あり
あり
あり
属性ファイル※2の<linked-to>などの設定

なし
@ResourceアノテーションのmappedName属性の設定

なし
あり
属性ファイル※2の<linked-to>などの設定

なし
@Resourceアノテーションのname属性の設定

なし
@Resourceアノテーションがフィールド・メソッドに指定されていればデフォルト値が使用されて，「あり」の場合と同様になります※4。
また，@Resourceアノテーションがクラスに指定された場合は，@Resourceアノテーションのname属性は省略できません。クラスに指定された@Resourceのname属性がない場合，アノテーションの読み込みに失敗して，インポート時にエラーになります。※5

（凡例）

あり：アノテーションや属性ファイルで属性が設定されていることを示します。

なし：「なし」の場合の説明を次に示します。

@Resourceアノテーションのname属性および@ResourceアノテーションのmappedName属性そのものの記述がない場合を示します。または，cosminexus.xmlまたはcosminexus.xml以外の属性ファイルの<linked-to>のタグそのものがない場合を示します。

属性またはタグに指定された値がない（空文字）場合を示します。

注※1　@Resourceアノテーションのname属性に対応する標準DDの<resource-ref>または<res-ref-name>にもリソースの別名を指定できます。@ResourceアノテーションのmappedName属性，および属性ファイルの<linked-to>などに指定がない場合は，標準DDの<resource-ref>または<res-ref-name>に指定した別名を持つリソースが参照先となります。

注※2　cosminexus.xmlおよびcosminexus.xml以外の属性ファイルが該当します。

注※3　別名の設定がない場合，アプリケーションの開始に失敗します。

注※4　@ResourceアノテーションのmappedName属性と属性ファイル（cosminexus.xmlおよびcosminexus.xml以外の属性ファイル）の<linked-to>などに指定がなく，name属性のデフォルト値，またはクラスに指定した@Resourceアノテーションのname属性の値とリソースの別名が一致した場合は，その別名を持つリソースが参照先となります。

注※5　mappedName属性と属性ファイル（cosminexus.xmlおよびcosminexus.xml以外の属性ファイル）の<linked-to>などに指定がなく，クラスに指定した@Resourceのname属性の値とリソースの別名が一致した場合は，その別名を持つリソースが参照先となります。

11.4.3　DI失敗時の動作

DIが失敗した時の動作について説明します。

DDの<injection-target-class>タグに指定したクラスがない場合，または<injection-target-name>タグに指定したメソッドおよびフィールドがない場合，DIに失敗します。この場合のアプリケーション開始時，およびDI実行時の挙動を次に示します。

＜この項の構成＞

(1)　DDの<injection-target-class>タグに指定したクラスがない場合

(2)　DDの<injection-target-name>タグに指定したメソッドおよびフィールドがない場合

(1)　DDの<injection-target-class>タグに指定したクラスがない場合

挙動を次に示します。

アプリケーション開始時

メッセージ（KDJE53905-W）を出力します。アプリケーション開始処理は続行します。

DI実行時

<injection-target-class>タグに指定したクラスがないため，DIは実行できません。

(2)　DDの<injection-target-name>タグに指定したメソッドおよびフィールドがない場合

挙動を次に示します。

アプリケーション開始時

メッセージ（KDJE53905-W）を出力します。アプリケーション開始処理は続行します。

DI実行時

メッセージ（KDJE53900-E）を出力して，DIに失敗します。

11.4.4　注意事項

DIを使用した場合の注意事項を示します。

DIを使用した場合の，Stateful Session Beanのリファレンス取得時の注意事項を次に示します。

J2EEアプリケーションがサーブレットからStateful Session Beanを呼び出す構成の場合，サーブレットでStateful Session Beanのリファレンスを取得するときは，DIを使用しないで，JNDI経由で行ってください。

J2EEアプリケーションがStateless Session BeanからStateful Session Beanを呼び出す構成の場合に，DIを使用してStateful Session BeanのビジネスインタフェースをStateless Session Beanに注入するとき，Stateless Session Beanのビジネスメソッド呼び出し，またはタイムアウトメソッド呼び出しのたびにDIが実行されます。

@Resourceアノテーションで指定できないリソースのタイプを指定した場合，インポート時に例外が発生します。

@EJBおよび@Resourceアノテーションのname属性は，次の表に示すejb-jar.xmlのタグの要素と対応しています。このため，アノテーションでEnterprise Beanおよびリソースへの参照を定義する場合は，@EJBおよび@Resourceアノテーションのname属性と，name属性に対応するejb-jar.xmlのタグに指定する要素は，重複しないように設定してください。name属性に対応するejb-jar.xmlのタグを次の表に示します。

表11-9　name属性に対応するejb-jar.xmlのタグ

アノテーションと属性 | name属性に対応するejb-jar.xmlのタグ
@EJB　name() | <ejb-ref>タグ下の<ejb-ref-name>タグ
<ejb-local-ref>タグ下の<ejb-ref-name>タグ
@Resource　name() | <env-entry>タグ下の<env-entry-name>タグ
<resource-ref>タグ下の<res-ref-name>タグ
<resource-env-ref>タグ下の<resource-env-ref-name>タグ

DIを使用するWebアプリケーションのリロード時には，例外が発生することがあります。例外が発生する場合を次に示します。

DIターゲット（DI機能を使用して参照を注入する対象）を定義しているクラス，または参照先クラスのロードに失敗した場合

DIターゲット名に対応したフィールド，メソッドがリロード後に削除されて，存在しない場合

例外が発生すると，メッセージログにKDJE53904-Wのメッセージが出力され，処理が続行されます。処理は続行されますが，対象となるインスタンスに対するDIが実行できない状態になり，対象のインスタンスへのリクエストが実行できなくなります。このため，このメッセージが出力された場合は，Webアプリケーションを修正して再度リロードを実施してください。

11.5　アノテーションの参照抑止

この節では，アノテーションの参照抑止機能について説明します。

アノテーション参照抑止機能を使用すると，アノテーションを使用していないモジュールに対する解析処理を抑止できます。これによって，不要なオーバーヘッドや不要な解析エラーの発生を防げます。

この節の構成を次の表に示します。

表11-10　この節の構成（アノテーション参照抑止機能）

分類 | タイトル | 参照先
解説 | アノテーション参照抑止機能の目的と適用範囲 | 11.5.1
アノテーションを参照するタイミング | 11.5.2
実装 | DDでの定義（モジュール単位の設定） | 11.5.3
設定 | 実行環境での設定（J2EEサーバ単位の設定） | 11.5.4
運用 | アノテーション参照抑止機能の設定変更 | 11.5.5

＜この節の構成＞

11.5.1　アノテーション参照抑止機能の目的と適用範囲

11.5.2　アノテーションを参照するタイミング

11.5.3　DDでの定義（モジュール単位の設定）

11.5.4　実行環境での設定（J2EEサーバ単位の設定）

11.5.5　アノテーション参照抑止機能の設定変更

11.5.1　アノテーション参照抑止機能の目的と適用範囲

ここでは，アノテーション参照抑止機能の目的と適用範囲について説明します。

＜この項の構成＞

(1)　アノテーション参照抑止機能の目的

(2)　適用範囲

(1)　アノテーション参照抑止機能の目的

アノテーション参照抑止機能は，J2EEアプリケーション中のアノテーションの参照（解析処理）を実施するかどうかを設定する機能です。モジュール内のアノテーションの有無を判断するためには，アプリケーションの解析が必要です。しかし，すべてのアプリケーションを解析すると，アノテーションを使用していないアプリケーションの場合，不要なオーバーヘッドが発生します。また，リソースやほかのアプリケーションを参照するアプリケーションの場合，アノテーション解析時にクラスファイルの参照エラーが発生して，デプロイに失敗することがあります。

アノテーション参照抑止機能を使用すると，アノテーションを使用しない場合に，アノテーションの解析処理を抑止することができます。

アノテーションの参照を抑止する範囲および抑止方法は，EJB 2.1またはServlet 2.4の場合と，Servlet 2.5の場合で異なります。なお，アプリケーションサーバでは，EJB 3.0の場合，アノテーション参照抑止機能は使用できません。

EJB 2.1またはServlet 2.4の場合

EJB 2.1またはServlet 2.4でのアノテーションの使用は，アプリケーションサーバで拡張された機能です。DDだけでmetadata情報が完結している，標準仕様に準拠したJ2EEアプリケーションの場合，アノテーションの解析処理は不要です。

EJB 2.1またはServlet 2.4の場合，J2EEサーバ単位でアノテーションの参照を抑止できます。J2EEサーバ単位のアノテーション参照抑止機能は，アプリケーションサーバ独自の機能です。

Servlet 2.5の場合

Java EE 5アプリケーションでは，標準仕様でアノテーションを使用できます。Servlet 2.5のDDには，アノテーションの参照を抑止するための属性であるmetadata-complete属性が追加されています。metadata-complete属性を使用して，モジュール単位にアノテーションの参照を抑止できます。

ただし，DDが省略されているアプリケーションの場合は，モジュール定義情報を読み込むために必ずアノテーションが参照されるため，参照抑止機能は使用できません。

モジュール単位のアノテーション参照抑止機能は，Java EE 5の標準仕様に準拠した機能です。

参考

アプリケーションサーバでは，EJB 3.0のDDにはインターセプタだけが定義できます。それ以外のEJB 3.0のモジュール定義情報は，すべてアノテーションで定義する必要があります。このため，EJB 3.0ではアノテーション参照抑止機能を使用できません。

(2)　適用範囲

アノテーション参照抑止機能の適用範囲は，アノテーションを含むモジュールの種類によって異なります。

アノテーション抑止機能の適用範囲を次の表に示します。

表11-11　アノテーション抑止機能の適用範囲

モジュールのバージョン | DDの有無と指定内容 | 参照抑止の範囲
J2EEサーバ単位 | モジュール単位
EJB | 1.1，2.0 | DDあり（metadata-complete属性なし） | － | －
2.1 | DDあり（metadata-complete属性なし） | ○※1 | －
3.0 | DDなし | × | ○
DDあり（metadata-complete属性あり） | 省略 | × | ○
指定あり | × | ○※2
Servlet | 2.2，2.3 | DDあり（metadata-complete属性なし） | － | －
2.4 | DDあり（metadata-complete属性なし） | ○※1 | －
2.5 | DDなし | × | ○
DDあり（metadata-complete属性あり） | 省略 | × | ○
指定あり | × | ○

（凡例）○：有効になる　×：使用できない　－：該当しない

注※1　有効にすると，アノテーションを記述したEJB 2.1またはServlet 2.4のモジュールを含むJ2EEアプリケーションは使用できなくなります。

注※2　値にtrueは指定できません。trueを指定した場合，J2EEサーバへのアプリケーションのインポートおよびリデプロイに失敗します。

モジュール単位の設定はDDのmetadata-complete属性で設定します。J2EEサーバ単位の設定は，ejbserver.deploy.applications.metadata_completeプロパティで設定します。モジュール単位の設定とJ2EEサーバ単位の設定の組み合わせた場合にアノテーションが参照されるかどうかを次の表に示します。

表11-12　J2EEサーバ単位の設定とモジュール単位の設定の組み合わせ

モジュールのバージョン | モジュール単位の設定 | J2EEサーバ単位の設定
プロパティの指定なし | ejbserver.deploy.applications.metadata_completeプロパティ
false | true
EJB 2.1，Servlet 2.4 | 設定できない | ○ | ○ | ×
EJB 3.0 | DDなし | ○ | ○ | ○
DDあり（metadata-complete属性あり） | 省略 | ○ | ○ | ○
false | ○ | ○ | ○
true | －※ | －※ | －※
Servlet 2.5 | DDなし | ○ | ○ | ○
DDあり（metadata-complete属性あり） | 省略 | ○ | ○ | ○
false | ○ | ○ | ○
true | × | × | ×

（凡例）○：参照する　×：参照しない　－：対象外

注※　DDのmetadata-complete属性にtrueを指定したEJB 3.0を含むアプリケーションは，インポートおよびリデプロイに失敗します。

11.5.2　アノテーションを参照するタイミング

アノテーションを参照するタイミングを，アプリケーション参照抑止機能を使用する場合としない場合に分けて次の表に示します。なお，J2EEサーバ単位，モジュール単位どちらの参照抑止機能でも，アノテーションを参照するタイミングは同じです。

表11-13　アノテーションを参照するタイミング

タイミング
（実行したコマンド）
参照抑止機能の設定
アプリケーションの形式

アーカイブ形式
展開ディレクトリ形式

インポート時（cjimportapp）
使用する
×
×

使用しない
○
○

インポート時（cjimportres※1）
使用する
×
－

使用しない
○
－

開始時（cjstartapp※2）
使用する
×
×

使用しない
○※3
○

リプレース時（cjreplaceapp）
使用する
×
－

使用しない
△
－

リロード時（cjreloadapp）
使用する
－
×

使用しない
－
○

属性取得時
（cjgetappprop）
使用する
×
×

使用しない
×
×

属性設定時
（cjsetappprop）
使用する
×
×

使用しない
×
×

（凡例）

使用しない：アプリケーション参照抑止機能を使用しない設定

使用する：アプリケーション参照抑止機能を使用する設定

○：アノテーションを参照する

×：アノテーションを参照しない

△：アノテーションを参照するが変更は反映されない

－：該当しない

注※1　cjimportresコマンドに引数「-type ejb」または「-type war」を指定して実行した場合です。

注※2　J2EEサーバの再起動時も含みます。

注※3　その前にJ2EEサーバを起動したときと設定が異なる場合だけアノテーションをロードします。

参考

展開ディレクトリ形式のアプリケーションをインポートしたあとでアノテーション情報を変更した場合，cjgetapppropコマンドによって属性ファイルを取得しても変更後のアノテーション情報は取得できません。これは，属性ファイルを取得する時にはアノテーション情報がクラスファイルからロードされないためです。

変更後のアノテーション情報を属性ファイルに取得するためには，cjstartappコマンドなど，アノテーション情報をクラスファイルからロードするコマンドを実行してから，属性ファイルを取得してください。

11.5.3　DDでの定義（モジュール単位の設定）

Servlet 2.5のモジュールに対するアノテーション参照抑止機能の定義は，web.xmlに指定します。なお，EJB 3.0の場合，<ejb-jar>タグのmetadata-complete属性にはfalseだけが指定できます。

DDでのアノテーション参照抑止機能の定義について次の表に示します。

表11-14　DDでのアノテーション参照抑止機能の定義

項目
DDの種類
指定するタグおよび属性
設定内容

Servlet 2.5
web.xml
<web-app>タグのmetadata-complete属性
アノテーション参照を抑止する場合はtrueを設定します。
アノテーションを参照する場合はfalseを設定します。

EJB 3.0
ejb-jar.xml
<ejb-jar>タグのmetadata-complete属性
アノテーションを参照する場合はfalseを設定します。

設定例を次に示します。

設定例（Servlet 2.5の場合）

<web-app metadata-complete="true"
 xmlns="http://java.sun.com/xml/ns/javaee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"  version="2.5">
 ：
</web-app>

太字の部分がアノテーション参照抑止機能の設定です。

DDのmetadata-complete属性の指定を省略した場合，またDDを省略した場合は，metadata-complete属性にfalseを指定した場合と同様に動作します。

11.5.4　実行環境での設定（J2EEサーバ単位の設定）

EJB 2.1またはServlet 2.4のモジュールに対するアノテーション参照抑止機能の定義は，J2EEサーバ単位に設定します。設定した内容は，そのJ2EEサーバにデプロイされているすべてのJ2EEアプリケーションに適用されます。

J2EEサーバ単位でアノテーションの参照を抑止する設定は，簡易構築定義ファイルを編集して行います。論理J2EEサーバ（j2ee-server）の<configuration>タグ内に，次のパラメタで設定します。

ejbserver.deploy.applications.metadata_complete
アノテーションの参照を抑止するかどうかを指定します。

パラメタの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「4.14.1　J2EEサーバ用ユーザプロパティを設定するパラメタ」を参照してください。

アノテーションの参照を抑止する設定をした場合，設定したJ2EEサーバの起動時に，アノテーションの参照を抑止することを示すメッセージが出力されます。J2EEサーバ起動前または起動後にアノテーションの参照を抑止しているかどうかの設定を確認する場合は，簡易構築定義ファイルの<configuration>タグ内のパラメタ「ejbserver.deploy.applications.metadata_complete」に設定された値を参照してください。

注意

J2EEサーバでejbserver.deploy.applications.metadata_completeにtrueを指定した場合，アノテーションを記述したEJB 2.1またはServlet 2.4のモジュールを含むJ2EEアプリケーションは使用できなくなります。

11.5.5　アノテーション参照抑止機能の設定変更

アノテーション参照抑止機能の設定を変更する場合について説明します。

＜この項の構成＞

(1)　モジュール単位の設定（DDのmetadata-complete属性の値）を変更する場合

(2)　J2EEサーバ単位の設定（簡易構築定義ファイルのejbserver.deploy.applications.metadata_completeの値）を変更する場合

(1)　モジュール単位の設定（DDのmetadata-complete属性の値）を変更する場合

DDのmetadata-complete属性を変更する場合は，metadata-complete属性を変更したアプリケーションを作成して，J2EEサーバに再度インポートする必要があります。

metadata-complete属性を変更した場合，リデプロイ機能（-replaceDDオプションを指定したcjreplaceappコマンド）によってアプリケーションを入れ替えようとすると，エラーになり，入れ替え処理は中断されます。

(2)　J2EEサーバ単位の設定（簡易構築定義ファイルのejbserver.deploy.applications.metadata_completeの値）を変更する場合

アプリケーションインポート後にejbserver.deploy.applications.metadata_completeの値を変更する場合について説明します。

trueからfalseに変更した場合は，アプリケーションのアノテーションが参照されるようになります。特に対処は不要です。

falseからtrueに変更した場合は，アノテーションが参照されなくなります。これに伴い，アプリケーションが正常に動作しなくなることがあります。アプリケーションが正常に動作しなくなった場合は，次の対処を実施してください。

アーカイブ形式のアプリケーションの場合

アノテーション参照抑止機能の設定を見直してください。または，J2EEアプリケーションの実装およびDDの設定を見直して，アノテーションを参照しなくても正しく動作するように設定を変更してください。変更後，アプリケーションを再度インポートしてください。

展開ディレクトリ形式のアプリケーションの場合

アノテーション参照抑止機能の設定を見直してください。または，J2EEアプリケーションの実装およびDDの設定を見直して，アノテーションを参照しなくても正しく動作するように設定を変更してください。変更後，アプリケーションを再開始してください。

11.6　アノテーションで定義した内容の更新

この節では，アノテーションで定義した内容の更新方法について説明します。

アノテーションを更新した場合，アプリケーションをインポートし直すか，リロード機能を使用することで，アプリケーションに変更を反映できます。また，Java EE 5の標準仕様では，アノテーションで定義した情報を標準DDで上書きできることが決められています。アプリケーションサーバでは，標準DDによるアノテーションでの定義内容の上書き，およびサーバ管理コマンドを使用した定義内容の更新ができます。

この節の構成を次の表に示します。

表11-15　この節の構成（アノテーションで定義した内容の更新）

分類 | タイトル | 参照先
解説 | アノテーションの更新 | 11.6.1
DDによるアノテーションの上書き | 11.6.2
サーバ管理コマンドを使用した定義の参照と更新 | 11.6.3

注　「実装」，「設定」および「運用」について，この機能固有の説明はありません。

＜この節の構成＞

11.6.1　アノテーションの更新

11.6.2　DDによるアノテーションの上書き

11.6.3　サーバ管理コマンドを使用した定義の参照と更新

11.6.1　アノテーションの更新

アノテーションの定義内容を更新した場合は，次のどちらかの方法でアプリケーションに反映できます。

アプリケーションをインポートし直す方法

通常の入れ替えによって更新内容を反映する方法です。アプリケーションを停止してから入れ替えます。

リロード機能を使用する方法（展開ディレクトリ形式のアプリケーションの場合）

更新検知またはcjreloadappコマンドの実行によって，デプロイ済みのアプリケーションの内容を動的に入れ替える方法です。展開ディレクトリ形式のアプリケーションの場合に使用できます。

ただし，リロード機能で更新できるアノテーションには制限があります。各アノテーションのリロード機能での更新可否を次の表に示します。

表11-16　各アノテーションのリロード機能での更新可否

アノテーション名 | 更新可否
@PostConstruct | ○
@PreDestroy | ○
@Resource | ×
@Resources | ×
@RunAs | ×
@DeclareRoles | ○
@RolesAllowed | ×
@PermitAll | ○
@DenyAll | ○
@Stateless | ×
@Stateful | ×
@Init | ○
@Remove | ○
@Remote | ×
@Local | ×
@RemoteHome | ×
@LocalHome | ×
@TransactionManagement | ○
@TransactionAttribute | ○
@PostActivate | ○
@PrePassivate | ○
@Interceptors | ○
@AroundInvoke | ○
@ExcludeDefautInterceptors | ○
@ExcludeClassInterceptors | ○
@Timeout | ×
@ApplicationException | ○
@EJB | ×
@EJBs | ×
@WebService | ○
@WebServiceProvider | ○
@PersistenceContext | ○
@PersistenceContexts | ○
@PersistenceProperty | ○
@PersistenceUnit | ○
@PersistenceUnits | ○

（凡例）○：更新できる　×：更新できない

11.6.2　DDによるアノテーションの上書き

アノテーションに定義した情報は，DDで上書きできます。DDによって上書きできるのは，Servlet 2.5およびEJB3.0のモジュールに定義されたアノテーションです。

Servlet 2.5のモジュールを上書きする方法には，次の2種類があります。

DDを編集して上書きする方法

DDを直接編集する方法です。

サーバ管理コマンドを使用して属性を変更して上書きする方法

J2EEサーバにインポート後のアプリケーションに対して，cjsetapppropコマンドまたはcjsetrespropコマンドを使用して属性を変更する方法です。ただし，この方法で上書きできるアノテーションには条件があります。詳細については「11.6.3　サーバ管理コマンドを使用した定義の参照と更新」を参照してください。

注意

次に示すモジュールに定義されたアノテーションの情報は，DDに定義しても上書きはされません。

EJB 2.1，Servlet 2.4
これらのモジュールに定義できるのは，アプリケーションサーバ独自のアノテーションです。DDによって上書きすることはできません。

EJB 3.0
アプリケーションサーバにインポートするEJB 3.0のDDにはインターセプタだけが定義できます。この定義をDDで上書きすることはできません。

上書き方法は，対象となるDDの要素および子要素が複数回出現できる要素かどうかによって異なります。

DDの要素が0回（出現なし）または1回しか出現しない要素の場合

アノテーションの情報はDDの情報で上書きされます。

DDの要素が0回以上または1回以上出現する要素の場合

DDとアノテーションを関連づける要素（キー）の有無，およびDDの要素内の子要素の出現回数で上書き規則が異なります。

ここでは，DDによるアノテーションの上書き規則を次の四つのパターンに分けて説明します。

表11-17　DDによるアノテーションの上書き規則のパターン

パターン | アノテーションと対応するDDの要素の出現回数 | キーの有無 | DDの子要素の出現回数 | 参照先
パターン1 | 0回または1回 | キーがない場合 | － | (1)
パターン2 | 0回以上または1回以上 | キーがない場合 | － | (2)
パターン3 | キーがある場合 | 0回または1回 | (3)
パターン4 | 0回以上または1回以上 | (4)

（凡例）－：キーの有無による違いがない

アノテーションとDDの要素の対応，各要素のキーの有無，およびキーとなる要素については，標準仕様を参照してください。

それぞれのパターンについて説明します。

＜この項の構成＞

(1)　パターン1（0回または1回出現する要素の場合）

(2)　パターン2（0回以上または1回以上出現する要素でキーがない場合）

(3)　パターン3（0回以上または1回以上出現する要素で子要素が0回または1回出現する場合）

(4)　パターン4（0回以上または1回以上出現する要素で子要素が0回以上または1回以上出現する場合）

(1)　パターン1（0回または1回出現する要素の場合）

出現回数が0回または1回出現する要素の場合は，アノテーションに対応する要素がDDに定義されているかどうかで上書きするかどうかが決まります。キーの値は関係ありません。

アノテーションに対応する要素がDDに定義されている場合

DDの定義でアノテーションの定義が上書きされます。

アノテーションに対応する要素がDDに定義されていない場合

アノテーションの定義が有効になります。

出現回数が0回または1回の要素の例を次の図に示します。キーがある場合の例です。

図11-3　0回または1回出現する要素の例

(2)　パターン2（0回以上または1回以上出現する要素でキーがない場合）

DDとアノテーションの両方の定義が有効になります。

キーがない場合の例を次の図に示します。「@DeclareRoles」で定義したセキュリティロールに加えて，DDで新しいセキュリティロールを定義します。

図11-4　キーがない場合の例

この例では，アノテーションで「admin」「adminadmin」および「adminadminadmin」の三つのセキュリティロールを定義しています。これに加えて，DDで定義した「admin2」が追加されてマージ後のDDに反映されます。なお，「adminadmin」はアノテーションおよびDDの両方で定義されているセキュリティロールです。アプリケーションは，マージ後のDDが定義されたものとして動作します。

なお，このパターンに該当する場合，アノテーションの定義はサーバ管理コマンドで変更できません。アノテーションに対応する情報を属性ファイルで削除・変更してcjsetapppropコマンドを実行しても，そのあとでcjgetapppropコマンドによって取得した属性ファイルには，アノテーションで定義された情報が出力されます。

(3)　パターン3（0回以上または1回以上出現する要素で子要素が0回または1回出現する場合）

DDの要素内の子要素が0回または1回出現する場合は，キーの値によって上書きの方法が異なります。

キーの値がDDとアノテーションで一致している場合

アノテーションの定義にDDの要素を上書きします。

キーの値がDDとアノテーションで一致しない場合

上書きされません。DDとアノテーションの両方の定義が有効になります。

図11-5　子要素が0回または1回出現する例

この例では，「res1」の環境エントリの値をアノテーションで定義した「TEST」からDDで定義した「RUNNING」に変更します。アプリケーションは，マージ後のDDが定義されたものとして動作します。

(4)　パターン4（0回以上または1回以上出現する要素で子要素が0回以上または1回以上出現する場合）

DDの要素内の子要素が0回以上または1回以上出現する場合は，キーの値によって上書きの方法が異なります。

キーの値がDDとアノテーションで一致している場合

アノテーションの定義にDDの要素が追加されます。

キーの値がDDとアノテーションで一致しない場合

上書きされません。DDとアノテーションの両方の定義が有効になります。

図11-6　子要素が0回以上または1回以上出現する例

この例では，アノテーションの定義に対して，DDで定義した要素「injection-target」が追加されます。アプリケーションは，マージ後のDDが定義されたものとして動作します。

11.6.3　サーバ管理コマンドを使用した定義の参照と更新

アノテーションで定義した要素は，サーバ管理コマンドのcjgetapppropコマンドまたはcjgetrespropコマンドを使用して参照できます。また，一部の定義はcjsetapppropコマンドまたはcjsetrespropコマンドを使用して更新できます。

＜この項の構成＞

(1)　アノテーションで定義した要素を参照・更新した場合の動作

(2)　サーバ管理コマンドによる定義の更新

(1)　アノテーションで定義した要素を参照・更新した場合の動作

サーバ管理コマンドを使用してアノテーションで定義した要素を参照・更新した場合の動作について次の表に示します。動作は，DDがある場合とない場合で異なります。

表11-18　サーバ管理コマンドを使用してアノテーションで定義した要素を参照・更新した場合の動作

要素の種類 | cjgetapppropまたはcjgetrespropによる参照 | cjsetapppropまたはcjsetrespropによる更新
DDがある場合 | DDで定義した要素 | DDで定義した内容が出力されます。 | DDの内容が更新されます。
アノテーションで定義した要素 | アノテーションで定義した内容が出力されます。 | 更新はできません。
アノテーションの定義をDDで上書きした要素 | アノテーションとDDの定義をマージした結果が出力されます。 | 「(2) サーバ管理コマンドによる定義の更新」を参照してください。
DDがない場合 | アノテーションで定義した要素 | アノテーションで定義した内容が出力されます。 | 更新はできません。

(2)　サーバ管理コマンドによる定義の更新

cjsetapppropコマンドまたはcjsetrespropコマンドを使用してアノテーションで定義した属性を上書き更新できるかどうかは，更新する情報がどこに定義されているかによって異なります。

定義されている場所と上書き可否の対応を次の表に示します。

表11-19　定義されている場所と上書き可否の対応

定義されている場所 | 上書き可否
DDだけに定義されている要素 | 可
アノテーションだけに定義されている要素 | 不可
アノテーションの定義をDDで上書きされている要素 | 可※

注※　更新後にアプリケーションをエクスポートした場合，エクスポートしたアプリケーションに含まれるWARファイル内のDD（web.xml）に，アノテーションとDDで定義した内容がマージされて出力されます。展開ディレクトリ形式のアプリケーションの場合は，<WARディレクトリ>/WEB-INF/web.xmlに，アノテーションとDDで定義した内容がマージされて出力されます。

●注意事項

アノテーションの定義をDDで上書きした要素を，cjsetapppropコマンドまたはcjsetrespropコマンドを使用して上書き更新した場合，アプリケーションディレクトリ内のDDにはDDとアノテーションの情報がマージされて出力されます。この場合，アノテーションで定義した内容がDDに反映されるため，それ以降にクラスファイル内のアノテーションを変更したときは，DDに残っている定義が優先されて変更したアノテーションの定義は有効になりません。

このような場合，DDに反映されているアノテーションの定義を削除して，アプリケーションを再インポートすることでアノテーションの定義が有効になります。また，属性ファイルで定義を追加，変更した場合は，アプリケーションを再インポートする必要はありません。

11.7　アノテーション使用時の注意事項

アノテーションを使用する場合の注意事項を示します。

＜この節の構成＞

(1)　インポート時の注意

(2)　@Resourceのmapped-name属性指定時の注意

(3)　EJBのリンク解決に関する注意

(4)　@RemoteHomeまたは@LocalHome使用時の注意

(5)　@PostConstructまたは@PreDestroy使用時の注意

(6)　そのほかの注意

(1)　インポート時の注意

クラスに宣言されたアノテーションが，外部のアーカイブファイルのクラスを参照していると，それらを単体でインポートできません。

EJB（ejb-jar.xmlのバージョン2.1以降またはejb-jar.xmlなし）

Servlet（web.xmlのバージョン2.4以降またはweb.xmlなし）

ライブラリJAR

外部参照は，次のどれかの方法で実施してください。

参照するクラスをすべてEARに含めてインポートする。

参照するクラスをすべてアプリケーションディレクトリに含めてインポートする。

外部参照しているクラスが含まれるJARファイルをコンテナ拡張ライブラリとして設定する。また，インポートするプロセスのクラスパスにも設定する。

操作方法ごとの設定例を示します。

例1：サーバ管理コマンドによって操作する場合

J2EEサーバ用オプション定義ファイルのキー（add.class.path）に参照しているJARファイルを指定します。また，サーバ管理コマンド用オプション定義ファイルのキー（USRCONF_JVM_CLASSPATH）に参照しているJARファイルを指定します。

例2：Management Serverによって操作する場合

運用管理ポータルによる論理J2EEサーバのJ2EEコンテナの設定で，拡張パラメタに"add.class.path=<参照しているJARファイル>"を指定します。

また，adminagentuser.cfgのadd.class.pathキーに参照しているJARファイルを指定します。さらに，サーバ管理コマンド用オプション定義ファイルのキー（USRCONF_JVM_CLASSPATH）に参照しているJARファイルを指定します。

次の場合はサーバ管理コマンド実行時にエラーになります。

@Resourceの要素type()にアプリケーションサーバでサポートしていないJava Typeを設定した場合。

EJB-JARにejb-jar.xmlがなく，かつ@Statelessまたは@Statefulアノテーションを宣言したクラスが一つもない場合。

DDのスキーマ定義の出現回数を上回るアノテーションを宣言していた場合。

WARファイルからEJB-JARファイルを参照している場合，WARファイルとEJB-JARファイルの両方を含んだアプリケーションにしてからインポートしてください。ただし，参照するインタフェースをWARファイルに含めている場合は，WARファイルを個別にインポートすることもできます。

アノテーションの属性にライブラリJAR内のクラスを記述している場合，ライブラリJARを含んだ形のアプリケーションとしてインポートしてください。

ほかのEJB-JARを参照するEJB-JARが存在する場合，両方のEJB-JARを含んだ形のアプリケーションとしてインポートしてください。ただし，参照する側のEJB-JARに，参照される側のインタフェースを含めている場合は，EJB-JARごとにインポートすることもできます。

(2)　@Resourceのmapped-name属性指定時の注意

アプリケーションサーバでは，@Resourceで指定されたmapped-name属性だけ処理対象とします。@Resourceに指定したmapped-name属性は，属性ファイルの<resource-ref>タグ下の<linked-to>タグ，<resource-env-ref>タグ下の<linked-to>タグ，および<resource-env-ref>タグ下の<linked-queue>タグに対応するものとして処理します。ただし，属性ファイルの<linked-to>タグおよび<linked-queue>タグとmapped-name属性が両方指定されていた場合は，<linked-to>タグおよび<linked-queue>タグの指定値を優先します。

(3)　EJBのリンク解決に関する注意

@EJBはDDの<ejb-ref>タグに対応するアノテーションです。同一アプリケーションの範囲内でEJBのリンクを解決します。@EJBにbeanName属性が指定されている場合，対応するEJB名を持つEJBを検索してリンクを解決します。EJB名とはejb-jar.xmlの場合，<session>タグ，<entity>タグ，および<message-driven>タグ下の<ejb-name>タグを指します。また，アノテーションであれば@Statelessおよび@Statefulのname属性で指定されたものを指します。

@EJBにbeanName属性が指定されていない場合，@EJBのbeanInterface属性と適合する型のEJBを検索してリンクを解決します。@EJBのbeanInterface属性と適合する型のEJBを次に示します。

@EJBのbeanInterface属性で指定したものと同じクラス型のホームインタフェースを持つEJB

@EJBのbeanInterface属性で指定したものと同じクラス型のビジネスインタフェースを持つEJB

一つのビジネスインタフェースを複数のEJBが実装しているようなケースでは，@EJBおよび@EJBsに適合するEJBが複数存在することがあります。参照先を一つに絞り込めない場合はリンクを解決しません。

(4)　@RemoteHomeまたは@LocalHome使用時の注意

アプリケーションサーバでは，@RemoteHomeまたは@LocalHomeで指定したホームインタフェースのcreateメソッドの戻り値の型となるインタフェースは，コンポーネントインタフェースと見なされます。ホームインタフェースとビジネスインタフェースの組み合わせでは使用できません。

(5)　@PostConstructまたは@PreDestroy使用時の注意

@PostConstructまたは@PreDestroyの定義がJava EE仕様に沿っているかどうか，Webアプリケーション開始時にチェックされます。Java EE仕様に沿わない定義があった場合は，アノテーションに関するメッセージが出力され，Webアプリケーションの開始が中断されます。

web.xmlで<post-construct>または<pre-destroy>タグを指定している場合，Webアプリケーション開始時にメソッドがチェックされます。指定されたクラス，メソッドが見つからない場合は，KDJE39332-Eが出力されエラーとなります。

一つのクラス内で二つ以上のメソッドに@PostConstructまたは@PreDestroyを指定した場合，Webアプリケーションの開始時にKDJE39327-Eが出力されてエラーとなります。

アプリケーションサーバでは，@PostConstructまたは@PreDestroyを指定したメソッド定義をする場合，次の表に示す仕様に注意してください。@PostConstructまたは@PreDestroyを指定したメソッド定義をする場合の仕様について，次の表に示します。

表11-20　@PostConstructまたは@PreDestroyを指定したメソッド定義をする場合の仕様

メソッド定義の仕様 | Java EE仕様との違い | 説明
引数を持てません。 | － | 引数を持つメソッドの場合，Webアプリケーション開始時にKDJE39328-Eのメッセージが出力され，エラーとなります。
検査例外をスローできます。非検査例外と同様に扱われます。 | Java EE仕様では，検査例外をスローできません。 | throwsの定義があるメソッドの場合，Webアプリケーション開始時にKDJE39329-Wのメッセージが出力されます。
インスタンスメソッドおよびクラス（static）メソッドで使用できます。 | Java EE仕様では，staticメソッドでは指定できません。 | staticメソッドの場合，Webアプリケーション開始時にKDJE39330-Wのメッセージが出力されます。
戻り値があるメソッドを使用することができます。 | Java EE仕様では，戻り値はvoidに限定する必要があります。 | 戻り値があるメソッドの場合，Webアプリケーション開始時にKDJE39331-Wのメッセージが出力されます。
public，protected，パッケージプライベート，privateのどれかを指定できます。 | － | －
finalとして宣言できます。 | － | －

（凡例）－：なし

@PostConstructアノテーションを指定したメソッドで例外が発生した場合，メッセージKDJE53906-Eが出力され，例外の発生したインスタンスが破棄されます。

Webアプリケーション開始後に初期化するクラスの場合，初期化に失敗してもクラスを使用するたびに初期化が試行されます。例えば，サーブレットへの初回リクエスト時に，@PostConstructを指定したメソッドで例外が発生した場合，次に同じサーブレットへアクセスする際にもサーブレットの初期化が試行されます。

@PreDestroyアノテーションを指定したメソッドで例外が発生した場合，メッセージKDJE53907-Wが出力され，Webコンテナからのオブジェクトの破棄処理が継続されます。

(6)　そのほかの注意

@TimeoutをEJBの複数のメソッドに指定した場合，どのメソッドが対象となるかは特定できません。

インターセプタとして指定したクラスのアノテーション情報が取得できない場合は，属性ファイル設定時にエラーになります。アノテーション情報を取得するには，対象のクラスとそのスーパークラス・インタフェース，およびそれらのクラス上で宣言されたすべてのフィールド・メソッドについて情報が取得できるようにクラスパスを指定する必要があります。

12.　J2EEアプリケーションの形式とデプロイ

この章では，J2EEサーバで実行できるJ2EEアプリケーションの形式と，形式ごとに実行できるJ2EEアプリケーションのデプロイ，アンデプロイおよび入れ替え機能について説明します。

＜この章の構成＞

12.1　この章の構成

12.2　実行できるJ2EEアプリケーションの形式

12.3　アーカイブ形式のJ2EEアプリケーション

12.4　展開ディレクトリ形式のJ2EEアプリケーション

12.5　J2EEアプリケーションのデプロイとアンデプロイ

12.6　J2EEアプリケーションの入れ替え

12.7　J2EEアプリケーションのリデプロイ

12.8　J2EEアプリケーションの更新検知とリロード

12.1　この章の構成

J2EEアプリケーションの形式とデプロイの機能と参照先を次の表に示します。

表12-1　J2EEアプリケーションの形式およびデプロイ機能と参照先

機能 | 参照先
実行できるJ2EEアプリケーションの形式 | 12.2
アーカイブ形式のJ2EEアプリケーション | 12.3
展開ディレクトリ形式のJ2EEアプリケーション | 12.4
J2EEアプリケーションのデプロイとアンデプロイ | 12.5
J2EEアプリケーションの入れ替え | 12.6
J2EEアプリケーションのリデプロイ | 12.7
J2EEアプリケーションの更新検知とリロード | 12.8

12.2　実行できるJ2EEアプリケーションの形式

J2EEサーバ上で実行できるアプリケーションを，J2EEアプリケーションといいます。WAR形式のWebアプリケーション，またはEJB-JAR形式のEJBアプリケーションをJ2EEサーバで実行するためには，J2EEアプリケーションとしてデプロイする必要があります。J2EEサーバ上で実行できるJ2EEアプリケーションは，次に示す2種類です。

アーカイブ形式のJ2EEアプリケーション
EJBやサーブレットなどのアプリケーションの実体をJ2EEサーバの作業ディレクトリに持つJ2EEアプリケーションです。

展開ディレクトリ形式のJ2EEアプリケーション
EJBやサーブレットなどのアプリケーションの実体を，J2EEサーバの外部にある一定のルールに従ったファイル／ディレクトリに持つJ2EEアプリケーションです。

12.3以降で，それぞれの形式のJ2EEアプリケーションのデプロイについて説明します。また，J2EEアプリケーションの実行機能として，J2EEアプリケーションのリデプロイ，J2EEアプリケーションの更新検知とリロードについても説明します。

なお，システムの運用を開始したあとでJ2EEアプリケーションの運用中に使用する機能については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 運用／監視／連携編」の「5.　J2EEアプリケーションの運用」を参照してください。

12.3　アーカイブ形式のJ2EEアプリケーション

この節では，アーカイブ形式によるJ2EEアプリケーションのデプロイについて説明します。

J2EEサーバ上で実行できるアプリケーションの形式の一つに，アーカイブ形式のJ2EEアプリケーションがあります。アーカイブ形式のJ2EEアプリケーションは，EJBやサーブレットなどのアプリケーションの実体をJ2EEサーバの作業ディレクトリに持つアプリケーションです。アーカイブ形式のJ2EEアプリケーションを次の図に示します。

図12-1　アーカイブ形式のJ2EEアプリケーション

アーカイブ形式のJ2EEアプリケーションでは，アプリケーションの実体はJ2EEサーバ上にあり，J2EEサーバの作業ディレクトリ下にアプリケーションの構成要素を保持します。

通常，アーカイブ形式のJ2EEアプリケーションを入れ替える場合には，J2EEサーバ上で動作しているJ2EEアプリケーションの停止，新しいJ2EEアプリケーションのインポート，デプロイなどの作業が発生します。このとき，リデプロイ機能を使用すると，通常のJ2EEアプリケーションの入れ替えに比べて，少ない手順で入れ替えができるようになります。

リデプロイ機能を使用したJ2EEアプリケーションの入れ替えでは，J2EEアプリケーションの属性情報を引き継ぐことができ，J2EEサーバ上で動作しているJ2EEアプリケーションの停止，新しいJ2EEアプリケーションのインポート，デプロイなどの作業が不要になります。リデプロイ機能については，「12.7　J2EEアプリケーションのリデプロイ」を参照してください。

注意

アプリケーションのバージョンがJava EE 5の場合，EARファイル内のエントリ名にアプリケーションパッケージのルートよりも上位を指定することはできません。指定した場合は，J2EEアプリケーションのインポート時にKDJE42387-Eのメッセージが出力され，エラーになります。

12.4　展開ディレクトリ形式のJ2EEアプリケーション

この節では，展開ディレクトリ形式によるJ2EEアプリケーションのデプロイについて説明します。

この節の構成を次の表に示します。

表12-2　この節の構成（SSL使用による認証情報とデータの暗号化）

分類 | タイトル | 参照先
解説 | 展開ディレクトリ形式の概要 | 12.4.1
アプリケーションディレクトリの構成 | 12.4.2
設定 | 展開ディレクトリ形式のJ2EEアプリケーションを使用するための設定（セキュリティの設定変更） | 12.4.3
注意事項 | 展開ディレクトリ形式を使用する場合の注意事項 | 12.4.4

注　「実装」および「運用」について，この機能固有の説明はありません。

＜この節の構成＞

12.4.1　展開ディレクトリ形式の概要

12.4.2　アプリケーションディレクトリの構成

12.4.3　展開ディレクトリ形式のJ2EEアプリケーションを使用するための設定（セキュリティの設定変更）

12.4.4　展開ディレクトリ形式を使用する場合の注意事項

12.4.1　展開ディレクトリ形式の概要

ここでは，展開ディレクトリ形式の概要，デプロイおよびアンデプロイの方法について説明します。

＜この項の構成＞

(1)　展開ディレクトリ形式のJ2EEアプリケーションとは

(1)　展開ディレクトリ形式のJ2EEアプリケーションとは

J2EEサーバ上で実行できるアプリケーションの形式の一つに，展開ディレクトリ形式のJ2EEアプリケーションがあります。展開ディレクトリ形式のJ2EEアプリケーションは，EJBやサーブレットなどのアプリケーションの実体を，J2EEサーバの外部にある一定のルールに従ったファイル／ディレクトリに持つアプリケーションです。アプリケーションディレクトリというルートディレクトリを作成し，アプリケーションディレクトリ下に，EJB-JAR，Webアプリケーションなどの構成要素が格納されていれば，J2EEアプリケーションとして動作できます。アプリケーションディレクトリについては，「12.4.2　アプリケーションディレクトリの構成」を参照してください。

展開ディレクトリ形式のJ2EEアプリケーションを次の図に示します。

図12-2　展開ディレクトリ形式のJ2EEアプリケーション

展開ディレクトリ形式のJ2EEアプリケーションが保持するのは，DDとアプリケーションディレクトリへのパス情報です。J2EEサーバの作業ディレクトリ下に，EJB-JAR，Webアプリケーションなどの構成要素を保持しません。

展開ディレクトリ形式のJ2EEアプリケーションの特長について説明します。

(a)　J2EEアプリケーションの入れ替えの容易化

展開ディレクトリ形式のJ2EEアプリケーションでは，構成要素をEAR形式にアーカイブする必要はありません。このため，アーカイブ形式のJ2EEアプリケーションと比べて，少ない手順でJ2EEアプリケーションの入れ替えができます。

また，リロード機能を使用することで，さらに少ない手順でJ2EEアプリケーションを動的に入れ替えられます。リロード機能では，J2EEアプリケーションを構成するファイルの更新を検知し，更新したJ2EEアプリケーションをリロードします。リロード機能を使用することで，J2EEサーバを再起動することなく，デプロイ済みのサーブレット，JSPやEJB-JARを動的に入れ替えられるようになります。リロード機能については，「12.8　J2EEアプリケーションの更新検知とリロード」を参照してください。

(b)　複数のJ2EEサーバでのアプリケーションディレクトリの共有

展開ディレクトリ形式のJ2EEアプリケーションでは，複数のJ2EEサーバでアプリケーションディレクトリを共有できます。

例えば，アーカイブ形式のJ2EEアプリケーションを使用している場合に，同じ内容のJ2EEアプリケーションを複数のJ2EEサーバで実行させるときは，複数のJ2EEサーバ上に，EARファイル／ZIPファイルをそれぞれ配置する必要があります。また，インポートしたJ2EEアプリケーションを入れ替える場合には，J2EEサーバの数だけ，再インポートや再デプロイが必要になります。

しかし，展開ディレクトリ形式のJ2EEアプリケーションでは，DDとアプリケーションディレクトリへのパス情報だけを保持するため，アプリケーションディレクトリ以下にあるEJB-JAR，Webアプリケーションなどの構成要素を，複数のJ2EEサーバで共有できます。

例えば，J2EEサーバをクラスタ構成で配置している場合にそれぞれのJ2EEサーバで同じJ2EEアプリケーションを使用するときは，同一のディレクトリをアプリケーションディレクトリとして指定できます。同一のアプリケーションディレクトリを参照しているため，J2EEアプリケーションに変更が発生した場合には，そのアプリケーションディレクトリでクラスファイルなどを更新するだけで，すべてのJ2EEアプリケーションの入れ替えができるようになります。アプリケーションディレクトリの共有の例を次の図に示します。

図12-3　アプリケーションディレクトリの共有の例

なお，J2EEアプリケーションを共有する場合には，それぞれのJ2EEサーバから参照できる環境（共有ディスク装置など）にアプリケーションディレクトリを配置してください。

12.4.2　アプリケーションディレクトリの構成

アプリケーションディレクトリは，展開ディレクトリ形式のJ2EEアプリケーションのルートディレクトリです。展開ディレクトリ形式のJ2EEアプリケーションを作成する場合には，アプリケーションディレクトリを作成し，アプリケーションディレクトリ下に，EJB-JAR，Webアプリケーションなどの構成要素を格納します。アプリケーションディレクトリの構成を次の表に示します。

表12-3　アプリケーションディレクトリの構成

ディレクトリ
ディレクトリの説明

<アプリケーションディレクトリ>
展開ディレクトリ形式のJ2EEアプリケーションのルートディレクトリです。アプリケーションディレクトリの名称は任意です。

META-INF
J2EEアプリケーションのDDおよびcosminexus.xmlの格納ディレクトリです。このディレクトリの直下に，application.xmlおよびcosminexus.xmlが格納されます。

<EJB-JARディレクトリ>
EJBアプリケーションのルートディレクトリです。

META-INF
EJB-JARのDDの格納ディレクトリです。このディレクトリの直下に，ejb-jar.xmlが格納されます。

<パッケージ名>
EJB-JARのクラスファイルやプロパティファイルを格納するディレクトリです。

（例）

MyEJB.class

MyEJBHome.class

MyEJBRemote.class

MyResource.properties

<WARディレクトリ>
Webアプリケーションのルートディレクトリです。
なお，このディレクトリの直下に，JSPファイルが格納されます。

（例）

index.jsp

WEB-INF
WebアプリケーションのDDの格納ディレクトリです。このディレクトリの直下に，web.xmlが格納されます。

classes
サーブレットクラスファイルやプロパティファイルを格納するディレクトリです。

（例）

MyServlet.class

lib
タグライブラリなどのJARファイルを格納するディレクトリです。

（例）

MyTagLibrary.jar

RARファイル※
J2EEアプリケーションで使用するリソースアダプタです。

<ライブラリディレクトリ>
ライブラリJARを格納するディレクトリです。アプリケーションのバージョンがJava EE 5以降の場合，このディレクトリの直下にライブラリJARが格納されます。

注※　リソースアダプタ（RARファイル）をJ2EEアプリケーションに含めて使用する場合に配置します。RARファイルは，アーカイブファイルのまま格納します。リソースアダプタをJ2EEリソースアダプタとしてデプロイする場合は，アプリケーションディレクトリにリソースアダプタを格納する必要はありません。

アプリケーションディレクトリの留意事項を次に示します。

<EJB-JARディレクトリ>，<WARディレクトリ>，およびRARファイルを配置する場合の留意点をapplication.xmlがある場合とapplication.xmlがない場合とに分けて説明します。

application.xmlがある場合には，それぞれapplication.xmlの<module>タグ以下に記述した相対パスに従って作成してください。また，EJB-JARディレクトリとWARディレクトリの名称もapplication.xmlの記述と合わせてください。application.xmlの<module>タグ以下に記述したEAR上の相対パス（EJB-JARファイル名，またはWARファイル名）から拡張子（「.jar」または「.war」）を除いたものが，EJB-JARディレクトリとWARディレクトリの名称になります。

application.xmlがない場合には，ディレクトリ名の最後は「_jar」または「_war」となります。

application.xmlの<module>/<ejb>，<module>/<web>，<module>/<connector>タグの値に（../）を含む相対パスは記述できません。記述した場合エラーになります。

application.xmlの<module>タグ以下で，EJB-JARとWARのモジュールが，「.jar」または「.war」以外の拡張子で宣言されていた場合，アプリケーションのインポートに失敗します。

ライブラリJARの扱われ方は，アプリケーションのバージョンによって異なります。

アプリケーションのバージョンがJ2EE1.4以前の場合
アプリケーションディレクトリ以下のJARファイルのうち，application.xmlの<module>タグ以下で定義していない，拡張子が小文字（.jar）のJARファイルは，ライブラリJARとして扱われます。

アプリケーションのバージョンがJava EE 5以降の場合
サブディレクトリを含まないライブラリディレクトリの直下，またはアプリケーションディレクトリの直下に置かれていて，application.xmlの<module>タグに定義されていないJARファイルがライブラリJARとして扱われます。ライブラリディレクトリには（../）を含むパスの記述はできません。記述した場合はアプリケーションをインポートするタイミングでエラーになります。

アプリケーションディレクトリにないJARを指定する場合は，参照ライブラリを使用します。

アプリケーションディレクトリを変更する場合には，「(2)　アプリケーションディレクトリの変更」に示す規則に従ってください。

＜この項の構成＞

(1)　アプリケーションディレクトリの作成例

(2)　アプリケーションディレクトリの変更

(1)　アプリケーションディレクトリの作成例

アプリケーションディレクトリの作成例を次に示します。

ここでは，EJB-JARディレクトリが「subdir/converter」，WARディレクトリが「MyWebApp」，RARファイルが「rardir/DBConnector_DABJ_CP.rar」の場合のアプリケーションディレクトリの構成例，application.xmlの記述例を示します。

アプリケーションディレクトリの構成例
この例でのアプリケーションディレクトリの構成を次に示します。

application.xmlの記述例
この例でのapplication.xmlを次に示します。

<?xml version="1.0" encoding="Shift_JIS" ?>
<application xmlns="http://java.sun.com/xml/ns/j2ee"
            version="1.4"
            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/application_1_4.xsd">
 <display-name>converter</display-name>
 <module>
   <ejb>subdir/converter.jar</ejb>
 </module>
 <module>
   <web>
     <web-uri>MyWebApp.war</web-uri>
     <context-root>/</context-root>
   </web>
 </module>
 <module>
   <connector>rardir/DBConnector_DABJ_CP.rar</connector>
 </module>
</application>

(2)　アプリケーションディレクトリの変更

アプリケーションディレクトリを変更する場合，変更の対象となるディレクトリやファイルの種類と操作の内容によって，変更できなかったり，変更後にアプリケーションの再インポートが必要になったりします。次に，アプリケーションディレクトリを変更した場合に必要となる作業について説明します。

（例）

ディレクトリの削除／名称変更
アプリケーションディレクトリ，EJB-JARディレクトリ，およびWARディレクトリは削除できません。また，ディレクトリ名は変更できません。削除した場合や名称を変更した場合には，アプリケーションを再インポートする必要があります。

JARファイルの追加／変更／削除
ライブラリJARの追加，削除，およびファイル名の変更はできません。ライブラリJAR（application.xmlで宣言していないJARファイル）を追加しても，そのJARファイルは読み込まれません。アプリケーションのインポート時に存在したライブラリJARのファイル名を変更した場合や，ライブラリJARを削除した場合には，アプリケーションを再インポートする必要があります。
なお，WARディレクトリ/WEB-INF/libディレクトリでは，JARファイルの追加／変更／削除はできます。

DDの変更
ユーザがアプリケーションディレクトリに存在するDDを変更しても，J2EEサーバは更新を検知しません。DDの定義を変更する場合，開発環境で定義を変更してからアプリケーションをインポートし直してください。または，サーバ管理コマンドを使用してください。ただし，クラスファイルに記述されたアノテーションまたはcosminexus.xmlは，次回J2EEアプリケーションを開始したときのクラスファイルの再読み込みで，更新を反映させることができます。
なお，サーバ管理コマンド実行時にアプリケーションディレクトリの構成がチェックされます。

アプリケーションディレクトリの変更可否を次の表に示します。

表12-4　アプリケーションディレクトリの変更可否

対象
ディレクトリおよびファイル
ディレクトリおよびファイルへの操作
アプリケーションの状態
説明

停止
開始

J2EEアプリケーション
アプリケーションディレクトリ
追加
－
－
－

内容変更
－
－
－

名称変更
△
×
アプリケーションの構成変更はできない。

削除
△
×
アプリケーションの構成変更はできない。

application.xml
追加
－
－
－

内容変更
○
×
DDの直接編集はできない。DDの定義の更新にはサーバ管理コマンドを使用する。※1

名称変更
－
－
－

削除
△
×
－

cosminexus.xml
追加
◎
○
－

内容変更
◎
○
－

名称変更
－
－
－

削除
◎
○
－

EJBアプリケーション
EJB-JARディレクトリ
追加
△
－
－

内容変更
－
－
－

名称変更
△
×
アプリケーションの構成変更はできない。

削除
△
×
アプリケーションの構成変更はできない。

EJBを構成するクラスファイル
追加
◎
×
クラスを追加したあとで，サーバ管理コマンドで属性を編集する必要がある。

内容変更
◎
×
DDにメソッド情報（container-transactionやmethod-permission）が記述されている場合には，DDの情報と同期を取って修正する必要がある。

名称変更
△
×
クラスファイルの内容を変更しないでクラスファイル名を変更しようとした場合，次回クラスローダ時にエラーになる。

削除
◎
×
クラスを削除したあとで，サーバ管理コマンドで属性を編集する必要がある。

ほかのクラスファイル
追加
◎
×
－

内容変更
◎
×
－

名称変更
△
×
クラスファイルの内容を変更しないでクラスファイル名を変更しようとした場合，次回クラスローダ時にエラーになる。

削除
◎
×
－

ejb-jar.xml
追加
－
－
－

内容変更
○
×
DDの直接編集はできない。DDの定義の更新にはサーバ管理コマンドを使用する。※1

名称変更
－
－
－

削除
△
×
－

Webアプリケーション
WARディレクトリ
追加
△
－
－

内容変更
－
－
－

名称変更
△
×
アプリケーションの構成変更はできない。

削除
△
×
アプリケーションの構成変更はできない。

WEB-INF/classes下のクラスファイルやプロパティファイル
追加
◎
×
－

内容変更
◎
×
－

名称変更
－
－
クラスファイルの内容を変更しないでクラスファイル名を変更しようとした場合，次回クラスローダ時にエラーになる。

削除
◎
×
－

WEB-INF/lib下のJARファイル
追加
◎
×
－

内容変更
◎
×
－

名称変更
◎
×
－

削除
◎
×
－

web.xml
追加
－
－
－

内容変更
○
×
DDの直接編集はできない。DDの定義の更新にはサーバ管理コマンドを使用する。※1

名称変更
－
－
－

削除
△
×
－

JSPファイル，
タグファイル，
静的コンテンツ（HTMLやJavaScriptなど），
JSPファイルまたはタグファイルが依存するファイル※2，
JSPコンパイル結果
追加
◎
×
－

内容変更
◎
×
－

名称変更
－
－
－

削除
◎
×
－

ライブラリ
ライブラリJAR
追加
△
×
アプリケーションの構成変更はできない。ライブラリJARを追加しても無視される。

内容変更
◎
×
－

名称変更
△
×
アプリケーションの構成変更はできない。

削除
△
×
アプリケーションの構成変更はできない。

参照ライブラリ
追加
◎
×
サーバ管理コマンド（cjsetappprop）で定義を変更する。

内容変更
◎
×
－

名称変更
－
－
サーバ管理コマンド（cjsetappprop）で定義を変更する。開始状態では変更できない。

削除
○
×
サーバ管理コマンド（cjsetappprop）で定義を変更する。開始状態では削除できない。

参照ライブラリのディレクトリ
追加
◎
×
－

内容変更
◎
×
－

名称変更
◎
×
－

削除
◎
×
－

リソースアダプタ
RARファイル
追加
△
×
－

内容変更
○
×
RARファイルを直接変更できない。サーバ管理コマンドを使用してプロパティを変更する。

名称変更
△
×
－

削除
△
×
－

（凡例）

「アプリケーションの状態」が「停止」の場合

アプリケーションが停止状態の場合，ディレクトリおよびファイルの種類や操作の内容によって，アプリケーションの再インポートの要否が異なります。

◎：再インポートは不要（次回アプリケーション開始時に操作が反映される）。

○：条件を満たす場合には，再インポートは不要。条件は「説明」を参照。

△：再インポートが必要。

－：該当しない。

「アプリケーションの状態」が「開始」の場合

アプリケーションが開始状態でリロード機能が無効の場合，ディレクトリおよびファイルの種類や操作の内容によって，操作を許可するかどうかが異なります。

○：操作できる。

×：操作できない。

－：該当しない。

注※1

DDを変更してもJ2EEサーバは更新を検知しないで，操作は無視されます。

次に示すコマンドを次回，実行したときに上書きされます。

cjsetappprop

cjaddapp（-type filterオプション指定時）

cjdeleteapp（-type filterオプション指定時）

cjrenameapp

cjstartapp

注※2

依存するファイルは，JSPファイルまたはタグファイルのincludeディレクティブでインクルードされるファイルや，web.xmlの<include-prelude>または<include-coda>でインクルードされるファイルのことです。

12.4.3　展開ディレクトリ形式のJ2EEアプリケーションを使用するための設定（セキュリティの設定変更）

ここでは，展開ディレクトリ形式のJ2EEアプリケーションを使用するために必要な設定について説明します。

展開ディレクトリ形式のJ2EEアプリケーションを使用する場合には，次のどちらかの方法でセキュリティの設定を変更することをお勧めします。

SecurityManagerの解除

セキュリティポリシーの設定変更

それぞれの方法について説明します。

＜この項の構成＞

(1)　SecurityManagerを解除する場合

(2)　セキュリティポリシーの設定を変更する場合

(1)　SecurityManagerを解除する場合

J2EEサーバを起動するときに，cjstartsvコマンドに-nosecurityオプションを指定し，SecurityManagerを解除します。

# cjstartsv <サーバ名称> -nosecurity

注意

SecurityManagerを解除することで，リソースアクセス時の権限チェックのオーバーヘッドを削減できますが，J2EEアプリケーションは任意のリソースへのアクセスができるようになるため，セキュリティが低下します。

(2)　セキュリティポリシーの設定を変更する場合

アプリケーションディレクトリ以下のJARファイルやクラスファイルに，リソースに対するアクセス権を与えるために，server.policyを次のように編集します。

grant codeBase "file:/D:/MyApplicationDir/Web.war/-"{
   permission java.lang.RuntimePermission "loadLibrary.*";
   permission java.lang.RuntimePermission "queuePrintJob";
   permission java.net.SocketPermission "*", "connect";
   permission java.io.FilePermission "<<ALL FILES>>", "read, write";
   permission java.util.PropertyPermission "*", "read";
   permission javax.security.auth.AuthPermission "getSubject";
   permission javax.security.auth.AuthPermission "createLoginContext.*";
};        

server.policyは，Smart Composer機能のコマンドでシステムを構築したあとに設定してください。

12.4.4　展開ディレクトリ形式を使用する場合の注意事項

展開ディレクトリ形式を使用する場合の注意事項を次に示します。

展開ディレクトリ形式のJ2EEアプリケーションでは，アーカイブ形式のJ2EEアプリケーションと比べて，次の作業ができません。

EJB-JAR／WAR／RARの追加

EJB-JAR／WAR／RARの削除

ライブラリJARの追加

ライブラリJARの削除

展開ディレクトリ形式のJ2EEアプリケーションでこれらの作業を実施したい場合には，次の手順で実施してください。

J2EEサーバから展開ディレクトリ形式のJ2EEアプリケーションを削除します。

アプリケーションディレクトリを修正します。

修正した展開ディレクトリ形式のJ2EEアプリケーションをインポートします。

展開ディレクトリ形式のJ2EEアプリケーションを使用する場合には，J2EEアプリケーションが任意のリソースへアクセスできるように，セキュリティの設定を変更することをお勧めします。セキュリティの設定の変更については，「12.4.3　展開ディレクトリ形式のJ2EEアプリケーションを使用するための設定（セキュリティの設定変更）」を参照してください。

展開ディレクトリ形式のJ2EEアプリケーションをインポートする場合に，アプリケーションディレクトリのパスとしてUNC名を含むパスは指定できません。UNC名を含むパスを指定した場合には，コマンドの実行エラーになります。

J2EEサーバの起動処理中やサーバ管理コマンドの実行中にアプリケーションディレクトリ以下のファイルおよびディレクトリを追加／削除／上書きしないでください。

application.xmlに<alt-dd>タグが指定されているJ2EEアプリケーションは，展開ディレクトリ形式で使用できません。展開ディレクトリ形式のJ2EEアプリケーションをインポートする場合，またはEARファイルや，J2EEサーバからエクスポートしたZIPファイルを展開ディレクトリ形式でインポートする場合に，J2EEアプリケーションのapplication.xmlに<alt-dd>タグが指定されているときは，コマンドの実行エラーになります。

J2EEサーバ内で，複数のJ2EEアプリケーションが同一のディレクトリをアプリケーションディレクトリとして指定することはできません。展開ディレクトリ形式のJ2EEアプリケーションをインポートする場合，またはEARファイルや，J2EEサーバからエクスポートしたZIPファイルを展開ディレクトリ形式でインポートする場合に，指定したディレクトリがすでにほかのJ2EEアプリケーションのアプリケーションディレクトリであるときは，コマンドの実行エラーになります。

アプリケーションディレクトリ以下にJavaソースファイルを置くような構成は推奨しません。同じディレクトリに置かれているクラスファイルとJavaソースファイルの同期が取れていない場合，アプリケーションの開始やリロードに失敗する場合があります。

次の半角記号はエスケープ文字として扱われるため，アプリケーションディレクトリ名およびモジュール名には指定しないでください。
!　#　%　+

アプリケーションディレクトリ以下に置かれているJARファイルはライブラリJARとして扱われます。このため，アプリケーションディレクトリ以下には，cjgetstubsjarコマンドで取得したスタブおよびインタフェースを置かないでください。

12.5　J2EEアプリケーションのデプロイとアンデプロイ

この節では，J2EEアプリケーションのデプロイとアンデプロイについて説明します。

この節の構成を次の表に示します。

表12-5　この節の構成（J2EEアプリケーションのデプロイとアンデプロイ）

分類 | タイトル | 参照先
解説 | アーカイブ形式のJ2EEアプリケーションのデプロイとアンデプロイ | 12.5.1
展開ディレクトリ形式のJ2EEアプリケーションのデプロイとアンデプロイ | 12.5.2
EARファイル／ZIPファイルの展開ディレクトリ形式でのデプロイ | 12.5.3
設定 | J2EEアプリケーションへのプロパティの設定 | 12.5.4

注　「実装」および「運用」について，この機能固有の説明はありません。

＜この節の構成＞

12.5.1　アーカイブ形式のJ2EEアプリケーションのデプロイとアンデプロイ

12.5.2　展開ディレクトリ形式のJ2EEアプリケーションのデプロイとアンデプロイ

12.5.3　EARファイル／ZIPファイルの展開ディレクトリ形式でのデプロイ

12.5.4　J2EEアプリケーションへのプロパティの設定

12.5.1　アーカイブ形式のJ2EEアプリケーションのデプロイとアンデプロイ

アーカイブ形式のJ2EEアプリケーションのデプロイとアンデプロイについて説明します。

＜この項の構成＞

(1)　J2EEアプリケーションのデプロイ

(2)　J2EEアプリケーションのアンデプロイ

(1)　J2EEアプリケーションのデプロイ

Webアプリケーション，またはEJBアプリケーションをJ2EEサーバで実行するためには，J2EEアプリケーションとしてデプロイする必要があります。J2EEアプリケーションを実行するJ2EEサーバにEARファイルをインポートしてください。

(2)　J2EEアプリケーションのアンデプロイ

アーカイブ形式のJ2EEアプリケーションを削除する場合は，J2EEアプリケーションに対してアンデプロイを実行します。アンデプロイの処理完了後に，J2EEサーバからJ2EEアプリケーションが削除されます。

12.5.2　展開ディレクトリ形式のJ2EEアプリケーションのデプロイとアンデプロイ

展開ディレクトリ形式のJ2EEアプリケーションのデプロイとアンデプロイについて説明します。

＜この項の構成＞

(1)　J2EEアプリケーションのデプロイ

(2)　J2EEアプリケーションのアンデプロイ

(1)　J2EEアプリケーションのデプロイ

展開ディレクトリ形式のJ2EEアプリケーションをJ2EEサーバ内にインポートしてクライアントから実行可能な状態にするためには，デプロイが必要です。J2EEアプリケーションを実行するJ2EEサーバに，展開ディレクトリ形式のJ2EEアプリケーションをインポートしてください。アプリケーション開始時に生成される各クラスローダは，クラスパスとしてアプリケーションディレクトリを保持して動作します。

(2)　J2EEアプリケーションのアンデプロイ

展開ディレクトリ形式のJ2EEアプリケーションを削除する場合は，展開ディレクトリ形式のJ2EEアプリケーションに対してアンデプロイを実行します。アンデプロイの処理完了後に，J2EEサーバへのJ2EEアプリケーションの登録が解除されます。なお，アプリケーションディレクトリは削除されません。

12.5.3　EARファイル／ZIPファイルの展開ディレクトリ形式でのデプロイ

EARファイルや，J2EEサーバからエクスポートしたZIPファイルを，展開ディレクトリ形式でJ2EEサーバにインポートできます。この機能を使用することで，作成済みのEARファイル／ZIPファイルを，展開ディレクトリ形式のJ2EEアプリケーションとして動作させることが容易になります。

＜この項の構成＞

(1)　EARファイル／ZIPファイルの展開

(2)　ディレクトリ名の生成規則

(1)　EARファイル／ZIPファイルの展開

EARファイル／ZIPファイルの内容を任意のディレクトリに展開して，展開ディレクトリ形式のJ2EEアプリケーションとしてJ2EEサーバにインポートします。EARファイル／ZIPファイルの展開を次の図に示します。

図12-4　EARファイル／ZIPファイルの展開

インポートするときに，コマンドの引数として，EARファイル／ZIPファイルと，アプリケーションディレクトリとなる展開先のディレクトリを指定します。J2EEサーバは，展開先のディレクトリのパス情報をコマンドから受け取り，そのパス情報を基にアプリケーションディレクトリを生成して，アプリケーションディレクトリ下にEARファイル／ZIPファイルの内容を展開します。

(2)　ディレクトリ名の生成規則

EARファイル／ZIPファイルを展開ディレクトリ形式としてインポートする場合，ディレクトリ名の衝突が発生することがあります。ディレクトリ名の生成規則は，ディレクトリ名の衝突パターンによって異なります。EARファイル／ZIPファイルを展開する場合の，EJB-JARディレクトリとWARディレクトリのディレクトリ名の生成規則を表に示します。

表12-6　EARファイル／ZIPファイルを展開する場合の，EJB-JARディレクトリとWARディレクトリのディレクトリ名の生成規則

ディレクトリ名の衝突パターン
ディレクトリ名の生成規則

application.xmlがあり，EARファイル内のディレクトリと衝突しない。
EJB-JARファイルとWARファイルから拡張子（「.jar」または「.war」）を除いたものが，EJB-JARディレクトリとWARディレクトリの名称になる。
EJB-JARファイルとWARファイルに拡張子がない場合は，ファイル名がそのままディレクトリ名になる。

EJB-JARファイルとWARファイルで衝突する。

EAR内のディレクトリと衝突する。

EJB-JARファイルとWARファイルの拡張子（「.jar」または「.war」）をそれぞれ「_jar」または「_war」に置き換えたものが，EJB-JARディレクトリとWARディレクトリの名称になる。

「_jar」または「_war」に置き換えても衝突する。
「_jar」または「_war」の後ろに通し番号（1～2147483647）が付加される。

ディレクトリ名の衝突が発生する場合のEARファイルの構成と，生成されるアプリケーションディレクトリの構成を次の図に示します。

図12-5　ディレクトリ名の衝突の例

注意

cjimportappコマンドの-dオプションを使用してEARファイル／ZIPファイルを展開して作成されたアプリケーションディレクトリが，次に示す条件のどれかに合致する場合，そのアプリケーションディレクトリをcjimportappコマンドの-aオプションに指定していると，インポートに失敗します。

EJB-JARのモジュール名が「.jar」で終わっていない。

WARのモジュール名が「.war」で終わっていない。

モジュールの拡張子を除いた名称が，ほかのモジュールの拡張子を除いた名称と重複する。

モジュールの拡張子を除いた名称が，EARファイル内のディレクトリと重複する。

12.5.4　J2EEアプリケーションへのプロパティの設定

J2EEアプリケーションのプロパティ設定には，サーバ管理コマンドを使用します。

なお，ここでは，アーカイブ形式のJ2EEアプリケーション（EAR形式／ZIP形式）や展開ディレクトリ形式のJ2EEアプリケーションが作成済みであることを前提に，J2EEアプリケーションの設定方法について説明します。J2EEアプリケーションは，MyEclipseなどを使用して，アプリケーション開発時に作成しておいてください。アプリケーションの作成については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション開発ガイド」の「14.4　アーカイブ形式のJ2EEアプリケーションの作成」を参照してください。

参考

サーバ管理コマンドでは，作成済みのEJB-JARファイルやWARファイルから，アーカイブ形式のJ2EEアプリケーションを作成することもできます。サーバ管理コマンドでのアーカイブ形式のJ2EEアプリケーションの作成については，「12.3　アーカイブ形式のJ2EEアプリケーション」を参照してください。

J2EEアプリケーションの設定の流れを次の図に示します。

図12-6　J2EEアプリケーションの設定の流れ

図中の1.～3.について説明します。

サーバ管理コマンドを使用してJ2EEアプリケーションをインポートします。
cjimportappコマンドを使用して，J2EEアプリケーションをインポートします。

アーカイブ形式のJ2EEアプリケーションをインポートする場合には，-fオプションにEAR形式／ZIP形式のファイルを指定します。

展開ディレクトリ形式のJ2EEアプリケーションをインポートする場合には，-aオプションにアプリケーションディレクトリを指定します。

EAR形式／ZIP形式のファイルを展開ディレクトリ形式でインポートする場合には，-fオプションにEAR形式／ZIP形式のファイルを，-dオプションにアプリケーションディレクトリとなる展開先のディレクトリを指定します。

サーバ管理コマンドを使用してJ2EEアプリケーションにサーブレットフィルタを追加します。
サーブレットフィルタを追加する場合は，WARファイルにフィルタを登録したあと，フィルタのマッピングを定義します。サーブレットフィルタの追加については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「9.9　フィルタの設定」を参照してください。

サーバ管理コマンドを使用してJ2EEアプリケーションのプロパティを定義します。
cjgetapppropコマンドで各属性ファイルを取得し，ファイル編集後に，cjsetapppropコマンドで編集内容を反映させます。プロパティの設定内容については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「9.1　J2EEアプリケーションのプロパティ設定の概要」を参照してください。

サーバ管理コマンドでの操作については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「3.　サーバ管理コマンドの基本操作」を参照してください。また，コマンドについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「2.3　J2EEアプリケーションで使用するコマンド」を参照してください。属性ファイルについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)」の「3.　J2EEアプリケーションの設定で使用する属性ファイル」を参照してください。

参考

次のような場合，実行時情報を含んだJ2EEアプリケーションをエクスポート・インポートすることで，効率良くJ2EEアプリケーションを設定できます。

開発環境で作成したJ2EEアプリケーションをエクスポートして，運用環境にインポートして使用する場合

運用環境ですでに動いているJ2EEアプリケーションをエクスポートして，増設したJ2EEサーバにインポートして使用する場合

なお，アプリケーションサーバのバージョンやプラットフォームが異なるホスト間では，J2EEアプリケーションをエクスポート・インポートして使用することはできません。J2EEアプリケーションをエクスポートするホストと，Application Serverのバージョンやプラットフォームが異なるホストでJ2EEアプリケーションを設定する場合は，J2EEアプリケーションを新規に作成および設定してください。

12.6　J2EEアプリケーションの入れ替え

システムの運用を開始したあとで，J2EEアプリケーションのバージョンアップやメンテナンスを実施するために，J2EEアプリケーションを入れ替えることがあります。

通常，J2EEアプリケーションを入れ替える場合には，J2EEサーバ上で動作しているJ2EEアプリケーションを停止したあと削除し，新しいJ2EEアプリケーションをインポート，デプロイする必要があります。

通常のJ2EEアプリケーションの入れ替え手順については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 運用／監視／連携編」の「5.6　J2EEアプリケーションの入れ替え」を参照してください。

12.7　J2EEアプリケーションのリデプロイ

リデプロイとは，少ない手順で高速にJ2EEアプリケーションを入れ替えられるデプロイ方法です。この節では，リデプロイ機能を使用したJ2EEアプリケーションの入れ替えについて説明します。

この節の構成を次の表に示します。

表12-7　この節の構成（J2EEアプリケーションのリデプロイ）

分類 | タイトル | 参照先
解説 | リデプロイによるJ2EEアプリケーションの入れ替え | 12.7.1
J2EEアプリケーションの状態と入れ替え | 12.7.2
注意事項 | リデプロイによるJ2EEアプリケーションの入れ替えの注意事項 | 12.7.3

注　「実装」，「設定」，および「運用」について，この機能固有の説明はありません。

リデプロイ機能を使用したJ2EEアプリケーションの入れ替えでは，J2EEアプリケーションのすべての属性の情報を引き継ぐことができます。リデプロイ機能でのJ2EEアプリケーションの入れ替えは，次のような場合に利用できます。

J2EEアプリケーションのテスト時のロジックの修正による入れ替え

テスト実施中，J2EEアプリケーション内のロジックに問題を発見してJ2EEアプリケーション内のEJB-JARファイルやWARファイルなどを修正した場合に，テスト中のアプリケーションを修正後のJ2EEアプリケーションと入れ替えるときに使用できます。

運用中のJ2EEアプリケーションと開発環境でテストしたJ2EEアプリケーションとの入れ替え

開発環境にあるJ2EEアプリケーションを，すでに運用中のJ2EEアプリケーションと入れ替えるときに使用できます。

ただし，運用環境と開発環境のアプリケーションの構成は同じで，ロジックだけが異なるJ2EEアプリケーションの場合に入れ替えできます。

リデプロイ機能を使用する場合には，通常のJ2EEアプリケーションの入れ替えを実施するときに必要となる，入れ替え前のJ2EEアプリケーションの停止と削除，入れ替えるJ2EEアプリケーションのインポートとデプロイなどの手順が不要になります。このため，通常のJ2EEアプリケーションの入れ替えに比べて，少ない手順で入れ替えができるようになります。

なお，リデプロイ機能を使用したJ2EEアプリケーションの入れ替えができるのは，アーカイブ形式のJ2EEアプリケーションです。展開ディレクトリ形式のJ2EEアプリケーションでは，リデプロイ機能は使用できません。

参考

リデプロイを実行する前に，JSP事前コンパイル機能を実行しておくことをお勧めします。JSP事前コンパイル機能は，Webアプリケーションに含まれるJSPファイルをデプロイ前にコンパイルし，クラスファイルを生成する機能です。あらかじめ，クラスファイルの生成までを実施しておくので，JSPに最初にリクエストが到着したときのレスポンスタイムおよびWebアプリケーションの開始時間を短縮できます。JSP事前コンパイル機能については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(Webコンテナ)」の「2.5　JSP事前コンパイル機能とコンパイル結果の保持」を参照してください。

＜この節の構成＞

12.7.1　リデプロイによるJ2EEアプリケーションの入れ替え

12.7.2　J2EEアプリケーションの状態と入れ替え

12.7.3　リデプロイによるJ2EEアプリケーションの入れ替えの注意事項

12.7.1　リデプロイによるJ2EEアプリケーションの入れ替え

ここでは，リデプロイによるJ2EEアプリケーションの入れ替えについて説明します。

リデプロイとは，アーカイブ形式のJ2EEアプリケーションを入れ替える場合に，少ない手順で高速に入れ替えられるデプロイ方法です。ロジックだけを変更したJ2EEアプリケーションを入れ替えたい場合などに利用できます。リデプロイは，サーバ管理コマンドを使用して実行できます。

リデプロイを実行できる条件を次に示します。

リデプロイを実行できる条件

入れ替えられるのは，実行時情報を含まないJ2EEアプリケーション（EARファイル）だけです。実行時情報を含むJ2EEアプリケーション（ZIPファイル）はリデプロイできません。

入れ替え前と入れ替え後のJ2EEアプリケーションの構成が同じである必要があります。J2EEアプリケーションに含まれるEJB-JAR，リソースアダプタおよびWARの数が異なったり，それらのファイル名称が異なったりする場合は，リデプロイはできません。また，J2EEアプリケーションの名称も同じである必要があります。

入れ替え前と入れ替え後のJ2EEアプリケーションに含まれるEJB-JAR内のホームインタフェース（ローカル，リモート），コンポーネントインタフェース（ローカル，リモート），ビジネスインタフェース（ローカル，リモート）のメソッド定義，およびアノテーションの値が同じである必要があります。

ランタイム属性だけを引き継ぐ設定をしている場合に，アプリケーション開発環境で設定済みのDDファイル（application.xml，ejb-jar.xml，ra.xmlおよびweb.xml）の定義内容が同じである必要があります。

また，J2EEアプリケーションを入れ替える時に，入れ替え前のJ2EEアプリケーションを別な名称に変更して退避しておくと，名称によるJ2EEアプリケーションの世代管理が実現できます。ここでは，J2EEアプリケーションの名称変更についてもあわせて説明します。

参考

通常の入れ替えまたはリデプロイによる入れ替えによってJ2EEアプリケーションを入れ替える場合，入れ替え後のJ2EEアプリケーションをテストモードで運用できます。テストモードを使用すると，実運用に入る前に，実際の運用環境でのJ2EEアプリケーションの動作を確認できます。テストモードによる運用については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 運用／監視／連携編」の「5.7　J2EEアプリケーションのテスト機能」を参照してください。

リデプロイでは，入れ替え前のJ2EEアプリケーションの情報を，入れ替え後のJ2EEアプリケーションに引き継げます。次の情報が引き継げます。

Application Serverのバージョンが06-70以降の場合

デフォルトの設定の場合，入れ替え後のJ2EEアプリケーションには，入れ替え前のJ2EEアプリケーションのすべての属性が引き継がれます。06-70よりも前のバージョンと同じように，ランタイム属性だけを引き継ぎたい場合は，オプションを指定してcjreplaceappコマンドを実行する必要があります。コマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjreplaceapp（アプリケーションの入れ替え）」を参照してください。

Application Serverのバージョンが06-70より前の場合

入れ替え前のJ2EEアプリケーションの属性ファイルに設定したランタイム属性※が引き継がれます。

注※　属性ファイルには，DD(application.xml，ejb-jar.xml，ra.xml，web.xml)の定義と属性ファイル独自の定義が設定できます。属性ファイル独自の定義のことを，ランタイム属性といいます。

注意

入れ替えるJ2EEアプリケーションにcosminexus.xmlが含まれている場合，入れ替える前のアプリケーションサーバ独自の定義情報をいったんデフォルト値に戻してから，cosminexus.xmlの定義情報を読み込みます。入れ替えるアプリケーションにcosminexus.xmlが含まれていない場合，入れ替え前のcosminexus.xmlの定義情報を引き継ぎます。

リデプロイを実行するとき，J2EEアプリケーションは開始，停止どちらの状態でもかまいません。開始状態のJ2EEアプリケーションを入れ替えた場合，J2EEアプリケーションは入れ替え後に自動的に開始されます。ただし，プールやキャッシュに格納されていたJ2EEアプリケーション関連のオブジェクトは破棄されます。停止状態のJ2EEアプリケーションを入れ替えた場合は，入れ替え後のJ2EEアプリケーションも停止した状態になります。J2EEアプリケーションの状態とリデプロイの関係については，「12.7.2　J2EEアプリケーションの状態と入れ替え」を参照してください。

ポイント

J2EEアプリケーションが開始されている状態でリデプロイを実行した場合，リデプロイ処理の中でJ2EEアプリケーションは停止され，入れ替え後に再開始されます。このとき，停止処理の実行時間がサーバ管理コマンド（cjreplaceapp）で設定したタイムアウト時間を超過した場合，J2EEアプリケーションの強制停止が実行されます。タイムアウト時間を指定しなかった場合は，デフォルトのタイムアウト時間である60秒を超過すると，強制停止が実行されます。強制停止実行後にさらにタイムアウト時間を超過した場合は，コマンドが異常終了します。

また，入れ替え後にJ2EEアプリケーションを再開始するとき，開始処理の実行時間がサーバ管理コマンド用のusrconf.propertiesのejbserver.rmi.request.timeoutキーに指定したタイムアウト時間を超過した場合も，コマンドが異常終了します。

入れ替え作業の実行形式と実行例を次に示します。

実行形式

cjreplaceapp <J2EEサーバ名> -name <J2EEアプリケーション名> -f <入れ替えるEARファイルのパス>

実行例

cjreplaceapp MyServer -name App1 -f App1.ear

12.7.2　J2EEアプリケーションの状態と入れ替え

リデプロイ機能では，J2EEアプリケーションが開始・停止の状態に関係なく入れ替えできます。

開始状態のアプリケーションを入れ替えた場合，および停止状態のアプリケーションを入れ替えた場合について説明します。

＜この項の構成＞

(1)　開始状態のJ2EEアプリケーションを入れ替えた場合

(2)　停止状態のJ2EEアプリケーションを入れ替えた場合

(1)　開始状態のJ2EEアプリケーションを入れ替えた場合

開始状態のJ2EEアプリケーションを入れ替えた場合，入れ替え後のJ2EEアプリケーションも開始状態になります。

開始状態のJ2EEアプリケーションをリデプロイすると，次のような流れで入れ替え処理が実施されます。

J2EEアプリケーションを停止する

J2EEアプリケーションを入れ替える

J2EEアプリケーションを開始する

それぞれの処理については，タイムアウトがあります。

停止時のタイムアウト

J2EEアプリケーションの停止処理の実行時間が，サーバ管理コマンドでタイムアウトとして設定した時間を超えた場合，J2EEアプリケーションは強制停止されます。強制停止を実施後，強制停止で設定したタイムアウト値の時間を超えてもJ2EEアプリケーションが停止しない場合は，サーバ管理コマンドは異常終了します。

タイムアウトの設定については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjreplaceapp（アプリケーションの入れ替え）」を参照してください。

なお，タイムアウトの時間には，次に示す順序で，最初に取得できた値が適用されます。

サーバ管理コマンドに設定されたタイムアウト値

デフォルト値（60秒）

入れ替え時および開始時のタイムアウト

入れ替え処理，および開始処理の実行時間でタイムアウト値として設定した時間を超えた場合，サーバ管理コマンドは異常終了します。なお，タイムアウト値は，RMI-IIOP通信のタイムアウトに設定した時間が適用されます。RMI-IIOP通信のタイムアウトについては，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.11.5　RMI-IIOP通信のタイムアウト」を参照してください。

(2)　停止状態のJ2EEアプリケーションを入れ替えた場合

停止状態のJ2EEアプリケーションを入れ替えた場合，入れ替え後のJ2EEアプリケーションも停止状態になります。停止状態のJ2EEアプリケーションのリデプロイでは，アプリケーションの入れ替え処理だけが実施されます。

12.7.3　リデプロイによるJ2EEアプリケーションの入れ替えの注意事項

リデプロイによるJ2EEアプリケーションの入れ替えの注意事項について説明します。

入れ替え処理実行時に，J2EEサーバ上に同じ名称のJ2EEアプリケーションがない場合は，エラーになります。入れ替えはできません。

リデプロイによるJ2EEアプリケーションの入れ替えでは，入れ替え前のJ2EEアプリケーションの実行時情報を，入れ替え後のJ2EEアプリケーション（新しいJ2EEアプリケーション）に引き継ぐため，入れ替え後のJ2EEアプリケーションに実行時情報が含まれていると入れ替えができません。入れ替えをしようとすると，エラー終了します。

デフォルトの設定の場合，入れ替え後のJ2EEアプリケーションには，入れ替え前のJ2EEアプリケーションのすべての属性が引き継がれます。06-70よりも前のバージョンと同じように，ランタイム属性※だけを引き継ぐ場合は，オプションを指定してcjreplaceappコマンドを実行する必要があります。コマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「cjreplaceapp（アプリケーションの入れ替え）」を参照してください。

J2EEアプリケーションについて，入れ替え前と入れ替え後で次に示す内容に差異があると，入れ替え処理でエラー終了します。

J2EEアプリケーション内のEJB-JARファイルの数，リソースアダプタの数，およびWARの数が異なる。

J2EEアプリケーション内のEJB-JARファイル名，RARファイル名，およびWARファイル名が，入れ替え前と入れ替え後とで異なる。

EJB-JARファイル内のホームインタフェース（ローカル／リモート），コンポーネントインタフェース（ローカル／リモート），およびビジネスインタフェース（ローカル／リモート）のメソッド定義が異なる。

ランタイム属性※だけを引き継ぐ設定をしている場合に，DD（application.xml，ejb-jar.xml，ra.xml，web.xml）の定義が異なる。

設定しているアノテーションの値を変更した。

また，-replaceDDオプションを指定した場合に，DDファイル（application.xml，ejb-jar.xml，ra.xml，web.xml）も入れ替えるときには，さらに次の条件に一致するとエラーとなります。

DDファイル（application.xml，ejb-jar.xml，ra.xml，web.xml）のタグが異なる。

DDファイル（application.xml，ejb-jar.xml，web.xml）が存在しなくなる。または存在しなかったDDファイルが存在するようになる。

開始状態のJ2EEアプリケーションを入れ替えした場合，プールやキャッシュに格納されたJ2EEアプリケーション関連のオブジェクトは破棄されます。

application.xmlのバージョンが1.4以前の場合と，Java EE 5の場合とではライブラリJARと判断する条件が異なります。ライブラリJARなどのモジュールの決定規則については「10.4.3　application.xmlがある場合のモジュールの決定規則」を参照してください。

入れ替え後のJ2EEアプリケーションが，cosminexus.xmlを含んでいて，CMP2.0を利用する場合，cjreplaceappコマンドはJ2EEアプリケーションが停止状態の時に実行する必要があります。また，このコマンドを実行したあと，デプロイ前にcjgencmpsqlコマンドを実行する必要があります。

注※

属性ファイルには，DD（application.xml，ejb-jar.xml，ra.xml，web.xml）の定義と属性ファイル独自の定義が設定できます。属性ファイル独自の定義のことをランタイム属性といいます。

12.8　J2EEアプリケーションの更新検知とリロード

展開ディレクトリ形式のJ2EEアプリケーションの場合，構成するファイルを更新すると，更新したJ2EEアプリケーションをリロードできます。リロード機能を使用することで，J2EEサーバを再起動することなく，デプロイ済みのサーブレット，JSPやEJB-JARを動的に入れ替えられるようになります。

また，リロード機能を使用する場合には，通常のJ2EEアプリケーションの入れ替えで必要となる，入れ替え前のJ2EEアプリケーションの停止と削除，入れ替えるJ2EEアプリケーションのインポートとデプロイなどの手順が不要になります。このため，少ない手順でJ2EEアプリケーションを動的に入れ替えられるようになります。

リロード機能は，アプリケーション開発でのテストやシステムの運用中に，修正したJ2EEアプリケーションと動作中のJ2EEアプリケーションを入れ替えたい場合に利用できます。

この節では，J2EEアプリケーションの更新検知とリロードについて説明します。

なお，cosminexus.xmlを含むアプリケーションの場合，J2EEアプリケーションの更新検知とリロードを実行してもcosminexus.xmlの情報は更新されません。

この節の構成を次の表に示します。

表12-8　この節の構成（J2EEアプリケーションの更新検知とリロード）

分類 | タイトル | 参照先
解説 | J2EEアプリケーションのリロード方法 | 12.8.1
リロードの適用範囲 | 12.8.2
リロード時のクラスローダの構成 | 12.8.3
エラー発生時の動作 | 12.8.4
更新検知の対象となるファイル | 12.8.5
J2EEアプリケーションの更新検知インターバル | 12.8.6
J2EEアプリケーションの構成ファイル更新用インターバル | 12.8.7
Webアプリケーションのリロード | 12.8.8
JSPのリロード | 12.8.9
ほかの機能との関係 | 12.8.10
コマンドによるJ2EEアプリケーションのリロード | 12.8.11
設定 | J2EEアプリケーションの更新検知とリロードの設定 | 12.8.12
注意事項 | リロードの注意事項および制限事項 | 12.8.13

注　「実装」および「運用」について，この機能固有の説明はありません。

＜この節の構成＞

12.8.1　J2EEアプリケーションのリロード方法

12.8.2　リロードの適用範囲

12.8.3　リロード時のクラスローダの構成

12.8.4　エラー発生時の動作

12.8.5　更新検知の対象となるファイル

12.8.6　J2EEアプリケーションの更新検知インターバル

12.8.7　J2EEアプリケーションの構成ファイル更新用インターバル

12.8.8　Webアプリケーションのリロード

12.8.9　JSPのリロード

12.8.10　ほかの機能との関係

12.8.11　コマンドによるJ2EEアプリケーションのリロード

12.8.12　J2EEアプリケーションの更新検知とリロードの設定

12.8.13　リロードの注意事項および制限事項

12.8.1　J2EEアプリケーションのリロード方法

J2EEアプリケーションのリロードには，更新検知によるリロードと，コマンドによるリロードの2種類の方法があります。

＜この項の構成＞

(1)　更新検知によるリロード

(2)　コマンドによるリロード

(1)　更新検知によるリロード

更新検知によるリロードは，J2EEアプリケーション開発時のテストを支援する機能として利用できます。更新検知によるリロードを次の図に示します。

図12-7　更新検知によるリロード

展開ディレクトリ形式のJ2EEアプリケーションを構成するEJBアプリケーション（EJB-JAR）やWebアプリケーション（WAR）が更新された場合に，J2EEサーバがJ2EEアプリケーションの更新を検知し，更新後のEJB-JARやWARを自動的にリロードします。

J2EEサーバは，J2EEアプリケーションの構成ファイルを定期的に監視し，構成ファイルの更新を検知すると，J2EEアプリケーションのリロードを実行します。J2EEアプリケーションの更新からリロードまでの処理の流れを次の図に示します。

図12-8　更新検知によるリロードの処理の流れ

図中の1.～10.について説明します。

J2EEアプリケーションの構成ファイルを更新します。
展開ディレクトリ形式のJ2EEアプリケーションを構成するEJB-JARやWARを更新します。

J2EEサーバがJ2EEアプリケーションの構成ファイルの更新を検知します。

J2EEサーバは，J2EEアプリケーションの構成ファイルを定期的に監視していて，構成ファイルが更新されると更新を検知します。J2EEアプリケーションの構成ファイルを監視して更新を検知する間隔は，更新検知インターバルとして設定します。更新検知インターバルについては，「12.8.6　J2EEアプリケーションの更新検知インターバル」を参照してください。

更新を検知したあと，更新するファイルをロードします。このとき，ファイルのコピー中にロードが開始されてしまい，ロードに失敗することがあります。これを回避するため，構成ファイルの更新を検知してから処理中のリクエスト数の監視を開始するまでの時間を構成ファイル更新用インターバルとして設定しておくことができます。構成ファイル更新用インターバルについては，「12.8.7　J2EEアプリケーションの構成ファイル更新用インターバル」を参照してください。

JSPを更新した場合には，JSPの再コンパイル，またはクラスファイルの監視によって更新が検知されます。JSPのリロードについては，「12.8.9　JSPのリロード」を参照してください。

リクエスト処理を閉塞します。
構成ファイルの更新を検知し，構成ファイル更新用インターバルで指定した時間を経過すると，J2EEアプリケーションのリロードを実行するためにリクエスト処理を閉塞します。

EJBアプリケーション（EJB-JAR）の場合
新規リクエストが来たらエラーを返します。処理中のリクエストがある場合には，処理を続行します。ただし，Stateless Session Beanの場合は，CTMを使用することで，新規リクエストを実行待ちにできます。

Webアプリケーション（WAR）の場合
新規リクエストが来たら実行待ちになります。処理中のリクエストがある場合には，処理を続行します。このとき，リロード遅延実行機能を使用すると，リロードの開始処理を遅らせることができます。リロード遅延実行については，「12.8.8(1)　Webアプリケーションのリロード遅延実行」を参照してください。

参考

処理中のリクエストの処理が完了しない場合には，J2EEアプリケーション実行時間の監視のメソッドタイムアウトおよびメソッドキャンセルを実行することで，リロード処理を開始できます。リロードとJ2EEアプリケーション実行時間の監視との関係については，「12.8.10(2)　リロードとJ2EEアプリケーション実行時間の監視との関係」を参照してください。

J2EEアプリケーションの終了処理をします。
リロードを実行するために，J2EEアプリケーションを終了します。終了処理では，次の処理が実施されます。

リロード前のクラスローダにローディングされたサーブレットのインスタンスが破棄されます。サーブレットがdestroyメソッドを実装している場合，destroyメソッドが実行されます。また，JSPファイルから生成されたサーブレットのインスタンスも破棄されます。このとき，JSPファイルがjspDestroyメソッドを実装していると，jspDestroyメソッドが実行されます。

javax.servlet.ServletContextに登録されたオブジェクトは破棄されます。

リロード前のクラスローダにローディングされたEJBのインスタンスが破棄されます。このとき，次のEJBのコールバックメソッドが実行されます。

分類
実行されるメソッド

Stateless Session Beanの場合
ejbRemove
PreDestroy

Stateful Session Beanの場合
ejbRemove
PreDestroy

Entity Beanの場合
unsetEntityContext

Message-driven Beanの場合
ejbRemove

セッション情報をシリアライズし，セッション情報ファイルに出力します。
Webアプリケーションをリロードする場合は，リロード実行前に生成したセッション情報を，リロード後も継続して利用できます。セッション情報の引き継ぎについては，「12.8.8(2)　Webアプリケーションのリロード時のセッション情報の引き継ぎ」を参照してください。

J2EEアプリケーション単位のクラスローダを新規に作成します。
J2EEアプリケーションのリロード処理が実行されると，J2EEアプリケーション単位のクラスローダが新たに作成され，リロード後のリクエスト処理で使用されます。

セッション情報ファイルからセッション情報を読み込み，デシリアライズします。
Webアプリケーションをリロードする場合は，セッション情報ファイルに出力されたセッション情報を新しいクラスローダに読み込みます。

セッション情報ファイルを削除します。

J2EEアプリケーションの開始処理をします。

リロード後は，初回アクセス時に更新後のサーブレットのインスタンスが作成され，initメソッドが実行されます。

開始処理では，プールの最小値分のEJBを生成してプーリングします。このとき，次のEJBのコールバックメソッドが実行されます。

分類
実行されるメソッド

Stateless Session Beanの場合
setSessionContext
ejbCreate
PostConstruct

Entity Beanの場合
setEntityContext

Message-driven Beanの場合
setMessageDrivenContext
ejbCreate

リクエストの閉塞を解除し，リクエストの処理を再開します。
3.で実行待ちにしていたリクエストの処理を再開します。

(2)　コマンドによるリロード

コマンドによるリロードは，J2EEアプリケーション開発時のテストを支援する機能，またはシステムの運用時にJ2EEアプリケーションの入れ替えを支援する機能として利用できます。コマンドによるリロードを次の図に示します。

図12-9　コマンドによるリロード

展開ディレクトリ形式のJ2EEアプリケーションを構成するEJBアプリケーション（EJB-JAR）やWebアプリケーション（WAR）を更新した場合に，ユーザがcjreloadappコマンドを実行します。J2EEサーバは，cjreloadappコマンドを契機にJ2EEアプリケーションの更新を検知し，更新後のEJB-JARやWARを自動的にリロードします。

J2EEアプリケーションの更新からリロードまでの処理の流れを次の図に示します。

図12-10　コマンドによるリロードの処理の流れ

図中の1.～4.について説明します。5.以降の手順については，更新検知によるリロードの場合と同じです。5.以降の手順については，「(1)　更新検知によるリロード」を参照してください。

J2EEアプリケーションの構成ファイルを更新します。
展開ディレクトリ形式のJ2EEアプリケーションを構成するEJB-JARやWARを更新します。

cjreloadappコマンドを実行します。

cjreloadappコマンドを契機に，J2EEサーバがJ2EEアプリケーションの構成ファイルの更新を検知します。

リクエスト処理を閉塞します。
J2EEアプリケーションのリロードを実行するためにリクエスト処理を閉塞します。

EJBアプリケーション（EJB-JAR）の場合
新規リクエストが来たらエラーを返します。処理中のリクエストがある場合には，処理を続行します。ただし，Stateless Session Beanの場合は，CTMを使用することで，新規リクエストを実行待ちにできます。

Webアプリケーション（WAR）の場合
新規リクエストが来たら実行待ちになります。処理中のリクエストがある場合には，処理を続行します。

参考

処理中のリクエストの処理が完了しない場合には，J2EEアプリケーション実行時間の監視のメソッドタイムアウトおよびメソッドキャンセルを実行することで，リロード処理を開始できます。リロードとJ2EEアプリケーション実行時間の監視との関係については，「12.8.10(2)　リロードとJ2EEアプリケーション実行時間の監視との関係」を参照してください。

12.8.2　リロードの適用範囲

リロードの対象として指定できるアプリケーションの種類を次の表に示します。

表12-9　リロードの対象として指定できるアプリケーションの種類

アプリケーションの種類 | 適用の有無 | 制限事項
EJBアプリケーション（EJB-JAR） | Stateless Session Bean | △ | リロード中の新規リクエストはエラーになります。なお，CTMを利用している場合は，リロード中の新規リクエストは実行待ちになります。
Stateful Session Bean | △ | リロード中の新規リクエストはエラーになります。また，リロードするとアプリケーションの状態が破棄されるため，アプリケーション開始前の状態になります。
Entity Bean | △ | リロード中の新規リクエストはエラーになります。
Message-driven Bean | △
Webアプリケーション（WAR） | サーブレット | ○ | －
JSP | ○ | －
ライブラリJAR | － | ○ | －

（凡例）

○：リロードの対象として指定できる

△：リロードの対象として指定できるが，制限事項がある

－：該当しない

リロードの適用範囲は，次の範囲で指定できます。

app：EJBアプリケーション（EJB-JAR）とWebアプリケーション（WAR）をリロードの対象とする。

web：Webアプリケーション（WAR）だけをリロードの対象とする。

jsp：JSPだけをリロードの対象とする。

注　app，web，jspは，usrconf.propertiesのejbserver.deploy.context.reload_scopeキーの指定値です。なお，noneを指定した場合は，リロード機能は無効になります。

appを指定した場合

EJBアプリケーションを更新すると，EJBアプリケーション，サーブレット，およびJSPがリロードされます。

サーブレットを更新するとサーブレットとJSPがリロードされます。

JSPを更新するとJSPがリロードされます。

webを指定した場合

サーブレットを更新するとサーブレットとJSPがリロードされ，JSPを更新するとJSPがリロードされます。

サーブレットがあってJSPがない場合は，サーブレットだけがリロードされます。JSPがあってサーブレットがない場合は，JSPだけがリロードされます。

EJBアプリケーションを更新してもリロードは動作しません。

jspを指定した場合

JSPを更新するとJSPがリロードされます。

EJBアプリケーションまたはサーブレットを更新しても，リロードは動作しません。

なお，リロード機能の有効／無効は，usrconf.propertiesのejbserver.rmi.localinvocation.scopeキーで指定するローカル呼び出し最適化機能の適用範囲と，リロード機能の適用範囲の組み合わせによって決まります。ローカル呼び出し最適化機能の適用範囲とリロード機能の適用範囲の対応を次の表に示します。

表12-10　ローカル呼び出し最適化機能の適用範囲とリロード機能の適用範囲の対応

項目 | ejbserver.rmi.localinvocation.scopeキーの値
all | app | none
ローカル呼び出し最適化の範囲 | 同一J2EEサーバ内となります。 | 同一アプリケーション内となります。 | 範囲はありません。
ejbserver.deploy.context.reload_scopeキーの値 | app | ×※ | ○ | ○
web | ○ | ○ | ○
jsp | ○ | ○ | ○
none | × | × | ×

（凡例）○：リロード機能を使用できる　×：リロード機能を使用できない

注※　設定に誤りがあります。ejbserver.rmi.localinvocation.scope=allの場合にejbserver.deploy.context.reload_scope=appを指定すると，J2EEサーバを起動するときにメッセージが出力されて起動に失敗します。

12.8.3　リロード時のクラスローダの構成

リロード時のクラスローダの構成は，ローカル呼び出し最適化の範囲によって異なります。ローカル呼び出し最適化の範囲とクラスローダの構成の対応を次の表に示します。なお，クラスローダの構成については，「付録B　クラスローダの構成」を参照してください。

表12-11　ローカル呼び出し最適化の範囲とクラスローダの構成の対応

項目 | ejbserver.rmi.localinvocation.scopeキー※の値
all | app | none
ローカル呼び出し最適化の範囲 | 同一J2EEサーバ内となります。 | 同一アプリケーション内となります。 | 範囲はありません。
クラスローダ構成 | ローカル呼び出し最適化時のクラスローダ構成になります。 | デフォルトのクラスローダ構成になります。 | デフォルトのクラスローダ構成になります。

注※　usrconf.propertiesに指定するキーです。

リロード機能では，ApplicationClassLoader以下，またはWebappClassLoader以下のクラスローダを入れ替えます。EJB-JARをリロードする場合，デフォルトのクラスローダ構成で，次のファイルをロードします。

ApplicationClassLoaderでは，J2EEアプリケーションに含まれるEJB-JAR，ライブラリJAR，および参照ライブラリをロードします。

WebappClassLoaderでは，J2EEアプリケーションに含まれるWARをロードします。

JasperLoaderでは，J2EEアプリケーションに含まれるJSPをロードします。

EJB-JARをリロードするためにApplicationClassLoaderを入れ替える場合は，下位にあるWebappClassLoader，およびJasperLoaderも入れ替える必要があります。したがって，EJB-JAR，ライブラリJAR，参照ライブラリをリロードする場合は，WARを含めたリロードになります。

12.8.4　エラー発生時の動作

リロード機能の使用中にエラーが発生した場合の動作を次の表に示します。

表12-12　リロード機能でのエラー発生時の動作

エラーの内容
結果

リロード中（アプリケーション内で処理しているリクエストがない状態）にリクエストがサーバに来た場合
EJB-JARの場合はクライアントにエラーが返ります。WARの場合，新規リクエストはリロードが完了するまで実行待ちとなります。

リロード中に例外が発生した場合（クラスファイルのロードの失敗を含む）
更新検知は停止しないで，アプリケーションを停止します。更新を検知した場合，停止したJ2EEアプリケーションは再び開始されます。

リロード以外の処理（更新チェック中，構成ファイル更新用インターバル中，リロード遅延実行中）で例外が発生した場合
更新検知は停止しないで，J2EEアプリケーションは開始状態のまま監視を続けます。

J2EEアプリケーションのメソッドがハングアップなどで終了しない場合
J2EEアプリケーション実行時間の監視でメソッドをキャンセルしないとリロードできません。また，cjreloadappコマンドを使用しないとリロードできません。
J2EEアプリケーション実行時間の監視については，「12.8.10(2)　リロードとJ2EEアプリケーション実行時間の監視との関係」を参照してください。

12.8.5　更新検知の対象となるファイル

クラスローダによってロードされるファイルのうち，監視対象のファイルが更新されたときに，J2EEサーバが更新を検知してリロードが実行されます。更新検知の対象となるタイミングは，J2EEアプリケーションの開始時です。

ただし，クラスローダでロードされていないファイルは，更新検知の対象になりません。アプリケーションディレクトリ以下にあってもロードされていないファイルや，アプリケーションディレクトリを使用していないJ2EEアプリケーションのファイルは，更新検知の対象になりません。また，DD（ejb-jar.xml，web.xml）は，更新検知の対象になりません。

また，展開ディレクトリ形式で，更新後のJSPファイルの更新日付が古い場合はJSPの再コンパイルが実行されません。

＜この項の構成＞

(1)　更新検知の対象ファイル

(2)　更新検知の対象ファイルの例

(3)　リロードの対象となる操作

(1)　更新検知の対象ファイル

更新検知の対象ファイルを次の表に示します。

表12-13　更新検知の対象ファイル

種別
更新検知の対象ファイル
リロードの適用範囲※1

app
web
jsp

アプリケーションディレクトリ以下のファイル

ライブラリJAR

○
－
－

EJB-JARディレクトリ以下のEJBアプリケーション（EJB-JAR）のファイル

クラスファイル

java.util.ResourceBundleによってロードされたプロパティファイル

○
－
－

WARディレクトリ以下のWebアプリケーション（WAR）のファイル
サーブレット

クラスファイル

JARファイル

java.util.ResourceBundleによってロードされたプロパティファイル

○
○
－

JSP

JSPファイル

○※2
○※2
○※2

タグファイル

タグライブラリ記述子

○※3
○※3
○※3

JSPコンパイル結果

タグファイルコンパイル結果

○※4
○※4
○※4

静的コンテンツ

○※5
○※5
○※5

アプリケーションディレクトリ以外のファイル

参照ライブラリ

○
－
－

（凡例）○：更新検知の対象になる　－：更新検知の対象にならない

注※1　リロードの適用範囲のapp，web，jspは，usrconf.propertiesのejbserver.deploy.context.reload_scopeキーの指定値です。

注※2　JSPの事前コンパイルがされていない状態で，ロード済みの場合に，更新検知の対象になります。

注※3　JSPの事前コンパイルがされていない状態で，ロード済みのJSPファイルまたはタグファイルで使用されている場合に，更新検知の対象になります。

注※4　JSPの事前コンパイルがされている場合に，更新検知の対象になります。

注※5　JSPファイルまたはタグファイルが依存するファイルの場合に，更新検知の対象になります。依存するファイルは，JSPファイルまたはタグファイルのincludeディレクティブでインクルードされるファイルや，web.xmlの<include-prelude>または<include-coda>でインクルードされるファイルのことです。

(2)　更新検知の対象ファイルの例

アプリケーションディレクトリ以下のファイルのうち，更新検知の対象となるファイルの例を次の表に示します。

表12-14　更新検知の対象ファイルの例

ディレクトリ
ディレクトリ下のファイル
更新検知の対象

<アプリケーションディレクトリ>
ライブラリJAR例：MyLibrary.jar
○

META-INF

J2EEアプリケーションのDD（application.xml）

Cosminexusアプリケーション属性ファイル（cosminexus.xml）

－

<EJB-JARディレクトリ>
－
－

META-INF
EJB-JARのDD（ejb-jar.xml）
－

<パッケージ名>
Enterprise Beanクラス
例：MyEJB.class
○

ホームインタフェースクラス
例：MyEJBHome.class
○

コンポーネントインタフェースクラス
例：MyEJBRemote.class
○

ビジネスインタフェースクラス
例：MyBusiness.class
○

EJBから利用されるクラス
例：MyClass.class
○

java.util.ResourceBundleによってロードされたプロパティファイル
例：MyResource.properties
○

<WARディレクトリ>
JSPファイル
例：MyJsp.jsp
○

静的コンテンツ
例：MyStatic.jspf
○

HTMLファイル
例：MyIndex.html
－

META-INF
－
－

WEB-INF
WebアプリケーションのDD（web.xml）
－

タグライブラリ記述子ファイル
例：MyTaglib.tld
○

Webアプリケーションプロパティファイル（hitachi_web.properties）
－

classes
－
－

<パッケージ名>
java.util.ResourceBundleによってロードされたプロパティファイル
例：MyResource.properties
○

サーブレットクラス
例：MyServlet.class
○

lib
JARファイル
例：MyLibrary.jar
○

tags
タグファイル
例：MyTag.tag
○

<JSPワークディレクトリ>
JSPコンパイル結果
例：MyJsp$jsp.class
○

WEB-INF
tags
タグファイルコンパイル結果
例：MyTag$tag.class
○

<アプリケーションディレクトリ以外のディレクトリ>
参照ライブラリ
例：MyRef.jar
○

（凡例）　○：更新検知の対象になる　－：更新検知の対象にならない

(3)　リロードの対象となる操作

監視対象のファイルを変更した場合に，更新が検知されてリロードが実行されるかどうかは，ファイルへの操作によって異なります。リロードの対象となる操作を次の表に示します。

表12-15　リロードの対象となる操作

更新検知の対象ファイル
ファイルへの操作
注意点

追加
削除
更新

アプリケーションディレクトリ以下のファイル
ライブラリJAR
×
×
○

アノテーションも読み込まれます。※1

ライブラリJARの名称は変更できません。

ライブラリJARの構成は変更できます。

Cosminexusアプリケーション属性ファイル
×
×
×

リロードを実行する際，cosminexus.xmlの内容が変更または削除されている場合は，定義情報の再読み込みは実施しません。

EJB-JARディレクトリ以下のEJBアプリケーション（EJB-JAR）のファイル
EJBを構成するクラスファイル
×
×
○

アノテーションも読み込まれます。※1

クラス名の変更はできません。

これまで参照していなかったクラスを参照するように更新した場合，参照先のクラスファイルもリロードの対象となります。

ほかのクラスファイル
×
×
○

アノテーションも読み込まれます。※1

これまで参照していなかったクラスを参照するように更新した場合，参照先のクラスファイルもリロードの対象となります。

WARディレクトリ以下のWebアプリケーション（WAR）のファイル
クラスファイル
△
○
○
－

JARファイル
○
○
○
－

プロパティファイル
△
○
○
－

JSPファイル
△
○※2
○※2
－

タグファイル
△
○※2
○※2

JARファイル内にあるタグファイルは除きます。

JSPファイルまたはタグファイルが依存するファイル
△
○※2
○※2
－

静的コンテンツ
△
×
×

リロード機能を使用した場合には，キャッシュが無効になります。

JSPコンパイル結果（JSP，タグファイルをコンパイルして生成されたクラスファイル）
△
○
○

JSPの事前コンパイル機能が有効である必要があります。

アプリケーションディレクトリ以外のファイル
参照ライブラリ
×
×
○

参照ライブラリの名称は変更できません。

参照ライブラリが指すJARファイルの構成およびクラスパス内のファイルの更新はできます。

スタブおよびコンテナ生成クラスの再生成が必要な場合には，再生成されます。

（凡例）

○：リロードが実行される

△：操作はできるが，リロードは実行されない

×：リロードが実行されない

－：該当しない

注※1　更新できるアノテーションと更新できないアノテーションがあります。アノテーションについては，「11.6.1　アノテーションの更新」を参照してください。

注※2　JSPの事前コンパイル機能が有効な場合は，△になります。

12.8.6　J2EEアプリケーションの更新検知インターバル

J2EEサーバは，J2EEアプリケーションの構成ファイルを定期的に監視していて，構成ファイルが更新されると更新を検知します。J2EEアプリケーションの構成ファイルを監視して更新を検知する間隔は，更新検知インターバルとして設定します。更新検知インターバルを次の図に示します。

図12-11　更新検知インターバル

更新検知インターバルの値を大きくすると，構成ファイルを監視する間隔が長くなり，ファイル更新後のリロードの反映が遅くなります。また，値を小さくすると，リロードの反映が早くなります。

ポイント

更新検知の対象となるファイル数が増えると，更新検知処理のオーバーヘッドが大きくなり，CPU使用率が高くなります。このような場合は，更新検知インターバルを変更することによって，性能への影響が小さくなります。更新検知インターバルの値は大きくすることをお勧めします。

更新検知インターバルは，J2EEアプリケーション，Webアプリケーション，およびJSPでそれぞれ設定できます。設定値の関係を次に示します。

EJBアプリケーションの場合

J2EEアプリケーションの更新検知インターバル（ejbserver.deploy.context.check_interval）が使用されます。なお，J2EEアプリケーションの更新検知インターバルに0を指定している場合，EJBアプリケーションは更新検知されません。

サーブレットの場合

WebアプリケーションまたはJ2EEアプリケーションの更新検知インターバルが使用されます。優先順位を次に示します。

Webアプリケーションの更新検知インターバル（webserver.context.check_interval）

J2EEアプリケーションの更新検知インターバル（ejbserver.deploy.context.check_interval）

なお，Webアプリケーションの更新検知インターバルを指定していない場合には，J2EEアプリケーションの更新検知インターバルが使用されます。

また，Webアプリケーションの更新検知インターバルに0を指定している場合，サーブレットは更新検知されません。

JSPの場合

JSPまたはJ2EEアプリケーションの更新検知インターバルが使用されます。優先順位を次に示します。

JSPの更新検知インターバル（webserver.jsp.check_interval）

J2EEアプリケーションの更新検知インターバル（ejbserver.deploy.context.check_interval）

なお，JSPの更新検知インターバルを指定していない場合には，J2EEアプリケーションの更新検知インターバルが使用されます。

また，JSPの更新検知インターバルに0を指定している場合，JSPは更新検知されません。

12.8.7　J2EEアプリケーションの構成ファイル更新用インターバル

J2EEサーバは，構成ファイルの更新を検知すると処理中のリクエスト数の監視を開始し，処理中のリクエストの処理が完了するとファイルをロードします。ファイルの容量が大きい場合，ネットワークを経由した場合や，ファイルが複数ある場合には，ファイルコピーなどの処理時間が長くなることがあります。このとき，ファイルコピーが完了する前に処理中のリクエストがなくなると，ファイルコピー中にロードが開始されて，ロードに失敗するおそれがあります。これを回避するため，ファイルコピーに掛かる時間を考慮し，コピーが完了してからロードが開始されるように，構成ファイル更新用インターバルを設定しておくことができます。構成ファイル更新用インターバルでは，構成ファイルの更新を検知してから処理中のリクエスト数の監視を開始するまでの時間を設定します。構成ファイル更新用インターバルを次の図に示します。

図12-12　構成ファイル更新用インターバル

ポイント

構成ファイル更新用インターバルには，実際に掛かるコピー時間にゆとりを持たせた時間を設定することをお勧めします。

複数のファイルを同時に更新する場合は，複数のファイルの更新に掛かる時間を算出して，構成ファイル更新用インターバルを設定してください。

構成ファイル更新用インターバルは，J2EEアプリケーション，Webアプリケーション，およびJSPでそれぞれ設定できます。設定値の関係を次に示します。

EJBアプリケーションの場合

J2EEアプリケーションの構成ファイル更新用インターバル（ejbserver.deploy.context.update.interval）が使用されます。

サーブレットの場合

WebアプリケーションまたはJ2EEアプリケーションの構成ファイル更新用インターバルが使用されます。優先順位を次に示します。

Webアプリケーションの構成ファイル更新用インターバル（webserver.context.update.interval）

J2EEアプリケーションの構成ファイル更新用インターバル（ejbserver.deploy.context.update.interval）

Webアプリケーションの構成ファイル更新用インターバルを指定していない場合には，J2EEアプリケーションの構成ファイル更新用インターバルが使用されます。

JSPの場合

JSPまたはJ2EEアプリケーションの構成ファイル更新用インターバルが使用されます。優先順位を次に示します。

JSPの構成ファイル更新用インターバル（webserver.jsp.update.interval）

J2EEアプリケーションの構成ファイル更新用インターバル（ejbserver.deploy.context.update.interval）

JSPの構成ファイル更新用インターバルを指定していない場合には，J2EEアプリケーションの構成ファイル更新用インターバルが使用されます。

12.8.8　Webアプリケーションのリロード

Webアプリケーションをリロードする場合には，リロード遅延実行機能を使用することで，J2EEアプリケーションのサービス停止期間を最小限に抑えることができます。また，Webアプリケーションのリロードでは，リロード実行前に生成したセッション情報を引き継いで，リロード後も継続して利用することができます。ここでは，Webアプリケーションのリロード遅延実行とセッション情報の引き継ぎについて説明します。

＜この項の構成＞

(1)　Webアプリケーションのリロード遅延実行

(2)　Webアプリケーションのリロード時のセッション情報の引き継ぎ

(1)　Webアプリケーションのリロード遅延実行

デフォルトでは，構成ファイルの更新を検知すると，次のような手順でリロード処理を実行します。

Webアプリケーションのリクエスト処理を閉塞します。
構成ファイルの更新を検知して構成ファイル更新用インターバルで指定した時間を経過すると，処理中のリクエスト数の監視を開始し，次のようにリクエストを処理します。

新規リクエスト：実行待ちにします。

処理中のリクエスト：処理を続行します。

処理中のリクエストの処理が完了すると，リロードを実行します。

この場合，処理中のリクエストの処理時間が長くなるほど，新規リクエストの処理開始時間が遅くなり，新規リクエストに対するアプリケーションのサービス停止期間が長くなります。これを回避するために，リロード遅延実行を設定しておくことをお勧めします。リロード遅延実行機能を使用すると，処理中のリクエストの実行待ち時間を減らして，アプリケーションのサービス停止期間を最小限に抑えられます。

リロード遅延実行機能では，この機能を使用するかどうか，およびリロード処理を開始するまでの時間（最大遅延時間）を設定します。リロード遅延実行機能を使用すると，処理中のリクエストの処理が終わるまで，新規リクエストを受け付けることができます。処理中のリクエスト数が0になると，リロード処理を開始して新規リクエストを実行待ちにします。ただし，処理中のリクエスト数が0になるかどうかは，アクセス状況に依存します。リクエストが途切れない場合には，リロード処理を開始できません。このような場合には，構成ファイルの更新を検知してから，新規リクエストを実行待ちにするまでの最大遅延時間を設定します。最大遅延時間を経過すると，それ以降の新規リクエストは実行待ちとなり，処理中のリクエストの処理が完了するのを待ってリロード処理を開始します。

リロード遅延実行を設定した場合と設定しない場合の，アプリケーションのサービス停止期間の違いを，次の図に示します。

図12-13　アプリケーションのサービス停止期間の違い

リロード遅延実行の最大遅延時間を設定している場合には，構成ファイルの更新を検知して構成ファイル更新用インターバルで指定した時間を経過すると，処理中のリクエスト数の監視を開始し，リロード遅延実行の最大遅延時間のカウントを開始します。例えば，最大遅延時間を5分と設定していた場合，アクセス状況によってリロード処理の開始時間が次のように異なります。

最大遅延時間を経過する前に処理中のリクエストが0になった場合
最大遅延時間のカウントを開始してから3分後に，処理中のリクエストが0になった場合には，その時点でリロード処理を開始します。また，新規リクエストを実行待ちにします。

最大遅延時間を経過した場合
リクエストが途切れないため処理中のリクエストが0にならない場合には，最大遅延時間のカウントを開始してから5分後に，新規リクエストを実行待ちにします。処理中のリクエストの処理が完了したら，リロード処理を開始します。

参考

処理中のリクエストの処理が完了しない場合には，J2EEアプリケーション実行時間の監視のメソッドタイムアウトおよびメソッドキャンセルを実行することで，リロード処理を開始できます。J2EEアプリケーション実行時間の監視については，「12.8.10(2)　リロードとJ2EEアプリケーション実行時間の監視との関係」を参照してください。

(2)　Webアプリケーションのリロード時のセッション情報の引き継ぎ

Webアプリケーションをリロードする場合は，リロード実行前に生成したセッション情報を引き継いで，リロード後も継続して利用します。

(a)　セッション情報ファイル

Webアプリケーションをリロードする場合，セッション情報（javax.servlet.http.HttpSessionオブジェクトに登録したオブジェクト）をシリアライズし，セッション情報ファイルに出力します。セッション情報ファイルからセッション情報を読み込み，リロード後のクラスローダ上でデシリアライズします。なお，シリアライズ処理，およびデシリアライズ処理の時間は，リロードを実行しているWebアプリケーション上で生成されたセッション数，javax.servlet.http.HttpSessionオブジェクトに登録したオブジェクトの容量などに依存します。

注意

シリアライズ対象となるセッションに登録したオブジェクトのクラス，およびそこから参照されるオブジェクトのクラスを，デシリアライズできない構成に更新してリロードを実行した場合，セッションのデシリアライズに失敗します。デシリアライズに失敗すると，Webアプリケーション上のすべてのセッション情報が破棄されます。

セッション情報ファイルは，リロード処理開始時に作成され，リロード処理完了時に削除されます。リロード実行時にセッションが存在しない場合でもセッション情報ファイルは作成されます。

セッション情報ファイルには，Webコンテナが自動生成する情報（2キロバイト）とセッション情報が出力されます。セッション情報は，セッション数とセッションに登録したセッション情報（オブジェクト）に依存します。

セッション情報ファイルのファイル容量は，リロード時に出力されるシリアライズ処理完了のメッセージからファイル容量を確認し，セッション数に応じて算出してください。シリアライズ処理完了時のメッセージの出力例を次に示します。

KDJE39168-I The serialization of session objects has finished. (J2EE application = app1, context root = /examples, number of sessions = 10, session information file size(byte) = 12345)

この出力例では，コンテキストルート名が「examples」のWebアプリケーション「app1」上に10個のセッションがあり，セッション情報ファイルのサイズは，12,345バイトです。

(b)　セッション情報を引き継ぐ場合の注意事項

リロード時のセッション引き継ぎ機能を使用する場合，javax.servlet.http.HttpSessionに登録するセッション情報は，シリアライズできるオブジェクトである必要があります。

HttpSessionオブジェクトに登録したオブジェクトから参照するオブジェクトは，transientで宣言されているか，またはシリアライズできるオブジェクトである必要があります。以降，参照するオブジェクトも同様です。シリアライズできるオブジェクトについての詳細は，J2SEの仕様書を参照してください。

セッション情報としてシリアライズできないオブジェクトを登録した場合は，エラーが発生します。エラーの内容はオブジェクトによって異なります。

javax.servlet.http.HttpSessionに登録したオブジェクトの場合
HttpSessionオブジェクトに登録したオブジェクトが，シリアライズできないオブジェクトである場合，該当するオブジェクトだけを破棄します。破棄されたオブジェクトは，リロードが完了したあとに使用することはできません。また，該当するオブジェクトが，javax.servlet.http. HttpSessionBindingListenerインタフェースを実装していても，Webコンテナからアンバインドされたイベントは通知されません。

javax.servlet.http.HttpSessionに登録したオブジェクトから参照されるオブジェクトの場合
HttpSessionに登録したオブジェクトから参照されるオブジェクトがシリアライズできないオブジェクトの場合，すべてのセッション情報が破棄されます。HttpSessionに登録したオブジェクトから参照されるオブジェクトが，HttpSessionに登録したオブジェクトの場合も同様に，すべてのセッション情報が破棄されます。

12.8.9　JSPのリロード

JSPを更新した場合には，JSPの再コンパイル，またはクラスファイルの監視によって更新が検知され，JSPがリロードされます。JSPのリロード方法を次に示します。

JSPの再コンパイルによるリロード
Webコンテナは，ロードされたJSPファイル，タグファイル，JSPファイルまたはタグファイルが依存するファイルが更新されているかどうかをチェックし，更新日時がロード時と異なる場合には，再コンパイルしてJSPをリロードします。
更新を検知してJSPの構成ファイル更新用インターバルを経過したあとに，ファイルを再コンパイルします。コンパイルが完了し，処理中のリクエストがなくなったことを検知したら，リロード処理を開始します。

クラスファイルの監視によるリロード
Webコンテナは，WebコンテナにロードされたJSPファイルから生成されたクラスファイルが更新されているかどうかをチェックし，更新日時がロード時と異なる場合に，JSPをリロードします。
更新を検知してJSPの構成ファイル更新用インターバルを経過したあとに，処理中のリクエストがなくなったことを検知したら，リロード処理を開始します。
クラスファイルの更新のタイミングは次のどちらかです。

JSP事前コンパイルのコマンドを実行し，JSPファイルをコンパイルしてクラスファイルを生成したとき

JSP事前コンパイルでコンパイルされたクラスファイルを，JSPワークディレクトリにコピーして上書きしたとき

JSPの事前コンパイルについては，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(Webコンテナ)」の「2.5　JSP事前コンパイル機能とコンパイル結果の保持」を参照してください。

JSPのリロード方法の差異を次の表に示します。

表12-16　JSPのリロード方法の差異

項目
JSPの再コンパイルによるリロードの場合
クラスファイルの監視によるリロードの場合

JSPの事前コンパイル機能使用の有無
JSP事前コンパイル機能は無効となります。
JSP事前コンパイル機能は有効となります。

更新検知の対象ファイル※

JSPファイル

タグファイル

JSPファイルまたはタグファイルが依存するファイル

JSP事前コンパイルで生成されたクラスファイル

更新検知後の処理
ファイルをコンパイルし，リロードします。
クラスファイルをリロードします。

注※　Webコンテナにロードされていないファイル，または更新検知の対象ではないファイルを更新しても検知されません。

どちらのリロード方法の場合でも，ファイルの更新を検知するために，JSPの更新検知インターバルとJSPの構成ファイル更新用インターバルを指定できます。更新検知インターバルについては，「12.8.6　J2EEアプリケーションの更新検知インターバル」を参照してください。構成ファイル更新用インターバルについては，「12.8.7　J2EEアプリケーションの構成ファイル更新用インターバル」を参照してください。

注意

ロード済みのJSPの破棄のタイミング，およびJSPのリロード機能の監視対象について

Webアプリケーションのリロード機能とJSPのリロード機能を併用した場合にWebアプリケーションのリロード機能が実行されたとき，ロード済みのJSPが破棄されます。また，JSPのリロード機能の監視対象はWebアプリケーションのリロード機能実行時にロードされたJSPファイルだけになります。

WebコンテナおよびWebアプリケーションの再起動をしたとき，ロード済みのJSPが破棄されます。また，JSPのリロード機能の監視対象はWebアプリケーションの開始後にロードされたJSPファイルだけになります。

12.8.10　ほかの機能との関係

リロード機能と次の機能との関係について説明します。

同時実行スレッド数制御

J2EEアプリケーション実行時間の監視

＜この項の構成＞

(1)　リロードと同時実行スレッド数制御との関係

(2)　リロードとJ2EEアプリケーション実行時間の監視との関係

(1)　リロードと同時実行スレッド数制御との関係

Webアプリケーションのリロード機能での新規リクエストの実行待ちと，同時実行スレッド数制御との関係について説明します。なお，同時実行スレッド数の制御については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(Webコンテナ)」の「2.15　同時実行スレッド数の制御の概要」を参照してください。

(a)　Webアプリケーション単位，またはURLグループ単位の同時実行スレッド数制御を使用する場合

リロード機能での新規リクエストの実行待ちは，Webアプリケーション単位，またはURLグループ単位の同時実行スレッド数制御の実行待ちキューとは，別に制御されます。

Webアプリケーション単位，またはURLグループ単位の同時実行スレッド数制御が設定されている場合
Webアプリケーション単位，またはURLグループ単位の同時実行スレッド数制御が設定されているWebアプリケーションをリロードする場合，リロード機能での新規リクエストの実行待ちは次のように制御されます。

リロード機能で実行待ちとなった新規リクエストは，Webアプリケーション単位，またはURLグループ単位の実行待ちキューに登録されません。それらの実行待ちキューのサイズの上限に関係なく，実行待ちとなります。

Webアプリケーション単位，またはURLグループ単位の実行待ちキューに登録されたリクエストがある場合は，それらの実行待ちキューに登録されたリクエストの処理がすべて完了してから，リロードが開始されます。

リロード処理完了後，リロード機能で実行待ちとなった新規リクエストの処理が開始されますが，同時実行スレッド数を超えたリクエストは，Webアプリケーション単位，またはURLグループ単位の実行待ちキューに登録されます。それらの実行待ちキューのサイズの上限を超えたリクエストは，ステータスコード503（Service Unavailable）のエラーを返します。

Webアプリケーション単位の同時実行スレッド数制御が設定されていない場合
Webアプリケーション単位の同時実行スレッド数制御が設定されていないWebアプリケーションをリロードする場合，リロード機能での新規リクエストの実行待ちは次のように制御されます。

リロード機能で実行待ちとなった新規リクエストは，デフォルトの実行待ちキューに登録されません。デフォルトの実行待ちキューサイズの上限に関係なく，実行待ちとなります。

デフォルトの実行待ちキューに登録されたリクエストがある場合は，その実行待ちキューに登録されたリクエストの処理がすべて完了してから，リロードが開始されます。

リロード処理完了後，リロード機能で実行待ちとなった新規リクエストの処理が開始されますが，同時実行スレッド数を超えたリクエストは，デフォルトの実行待ちキューに登録されます。デフォルトの実行待ちキューのサイズの上限を超えたリクエストは，ステータスコード503（Service Unavailable）のエラーを返します。

(b)　Webコンテナ単位の同時実行スレッド数制御を設定する場合

Webコンテナ単位の同時実行スレッド数制御を設定している場合，リロード処理開始後に，Webコンテナ単位の同時実行スレッド数制御で実行できることになった，新規リクエストの処理スレッドが実行待ちとなります。

このため，リロード機能で実行待ちとなった新規リクエスト数がWebコンテナ単位の最大同時実行スレッド数まで達した場合，リロード処理を開始したWebアプリケーション以外のWebアプリケーションへのリクエストも，Webコンテナ単位の同時実行スレッド数制御機能によって実行待ちとなります。

(2)　リロードとJ2EEアプリケーション実行時間の監視との関係

処理中のリクエストの処理が完了しない場合には，cjreloadappコマンドで-tオプションを指定することで，処理中のリクエストを強制的に終了させて，リロード処理を開始できます。ただし，処理中のリクエストを強制的に終了できるのは，J2EEアプリケーション実行時間の監視機能のメソッドタイムアウトの適用対象メソッドだけです。また，メソッドタイムアウトの発生後にメソッドキャンセルが動作するように設定している場合は，タイムアウトの発生によって処理中のリクエストがキャンセルされて，リロードを開始できます。

J2EEアプリケーション実行時間の監視の詳細については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 運用／監視／連携編」の「5.3　J2EEアプリケーションの実行時間の監視とキャンセル」を参照してください。J2EEアプリケーション実行時間の監視の設定については，「12.8.12　J2EEアプリケーションの更新検知とリロードの設定」を参照してください。

(a)　EJBアプリケーションの場合

EJBアプリケーションをリロードする場合について説明します。

構成ファイル更新用インターバルを経過すると，J2EEサーバは，処理中のリクエストの処理が完了するのを待ってリロード処理を開始します。ここで処理中のリクエストの処理が完了しないときは，J2EEアプリケーション実行時間の監視で，一定時間内に終了しなかったメソッド処理をタイムアウトとして通知し，メソッド処理をキャンセルすることで，リロード処理を開始できます。

メソッドキャンセル機能によるリロードを次の図に示します。

図12-14　メソッドキャンセル機能によるリロード（EJBアプリケーションの場合）

構成ファイルの更新検知からリロード処理開始までの時間は次の式で求められます。

構成ファイル更新用インターバル（秒）＋処理中のリクエストの実行待ち時間（秒）

(b)　Webアプリケーションの場合

Webアプリケーションをリロードする場合について説明します。

リロード遅延実行を設定している場合，指定した最大遅延時間を経過すると，J2EEサーバは，新規リクエストを実行待ちにし，処理中のリクエストの処理が完了するのを待ってリロード処理を開始します。ここで処理中のリクエストの処理が完了しないときは，J2EEアプリケーション実行時間の監視で，一定時間内に終了しなかったメソッド処理をタイムアウトとして通知し，メソッド処理をキャンセルすることで，リロード処理を開始できます。

メソッドキャンセル機能によるリロードを次の図に示します。

図12-15　メソッドキャンセル機能によるリロード（Webアプリケーションの場合）

構成ファイルの更新検知からリロード処理開始までの時間は次の式で求められます。

構成ファイル更新用インターバル（秒）＋リロード遅延実行の最大遅延時間（秒）＋処理中のリクエストの実行待ち時間（秒）

12.8.11　コマンドによるJ2EEアプリケーションのリロード

ここでは，リロードによるJ2EEアプリケーションの入れ替え方法について説明します。

リロードとは，少ない手順で展開ディレクトリ形式のJ2EEアプリケーションの入れ替えを実行できる機能です。リロードによるJ2EEアプリケーションの入れ替えでは，既存のJ2EEアプリケーションの停止，削除，入れ替え後のJ2EEアプリケーションのアーカイブ，インポート，再開などの作業が不要です。クラスファイルを更新してリロードを実行するだけでJ2EEアプリケーションを更新できるため，メンテナンスが頻繁に発生するシステムの運用などで特に有効な機能です。

なお，リロードによるJ2EEアプリケーションの入れ替えを実行するには，事前に設定が必要です。設定方法の詳細については，「12.8.12　J2EEアプリケーションの更新検知とリロードの設定」を参照してください。

リロードによるJ2EEアプリケーションの入れ替えは，サーバ管理コマンド（cjreloadappコマンド）を使用して実行できます。cjreloadappコマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド」の「10.6.2　展開ディレクトリ形式のアプリケーション」を参照してください。

リロードは，次の手順で実行します。

メンテナンスの内容に従ってJavaソースファイルを編集，または作成して，クラスファイルにコンパイルします。

J2EEアプリケーションのリロードを実行します。
cjreloadappコマンドを実行します。実行形式と実行例を次に示します。

実行形式

cjreloadapp <J2EEサーバ名> -name <J2EEアプリケーション名>

実行例

cjreloadapp MyServer -name App1

注意

リロードに失敗したアプリケーションを削除するには，リロードの成功後，アプリケーションを停止，削除するか，J2EEサーバを再起動したあとにアプリケーションを削除してください。

12.8.12　J2EEアプリケーションの更新検知とリロードの設定

アプリケーション開発でのテストやシステムの運用中に，修正したJ2EEアプリケーションと動作中のJ2EEアプリケーションを入れ替えたい場合，リロード機能を使用した入れ替えができます。展開ディレクトリ形式のJ2EEアプリケーションを構成するファイルを更新した場合に，更新検知やコマンド実行によって，更新したJ2EEアプリケーションをリロードできます。リロード機能を使用することで，少ない手順でJ2EEアプリケーションを動的に入れ替えられるようになります。

この項では，展開ディレクトリ形式のJ2EEアプリケーションの更新検知とリロードをするための設定について説明します。コマンドやファイルのキーについては，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」，およびマニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」を参照してください。

展開ディレクトリ形式のJ2EEアプリケーションをリロードするために必要な設定は，構成ファイルの更新を検知してリロードするか，コマンドを実行してリロードするかによって異なります。展開ディレクトリ形式のJ2EEアプリケーションをリロードするために必要な設定を次の表に示します。

表12-17　リロードするために必要な設定

設定項目 | 更新検知によるリロードの場合 | コマンドによるリロードの場合
リロード機能の適用範囲の設定 | ○ | ○
更新検知インターバルの設定 | ○ | －
構成ファイル更新用インターバルの設定 | ○ | －
リロード遅延実行の設定 | ○ | －
セッション情報ファイル格納先ディレクトリの変更 | △ | △
JSP事前コンパイルの設定 | △ | △
J2EEアプリケーション実行時間の監視の設定 | △ | △

（凡例）　○：設定する　△：必要に応じて設定する　－：該当しない

＜この項の構成＞

(1)　リロード機能の適用範囲の設定

(2)　更新検知インターバルの設定

(3)　構成ファイル更新用インターバルの設定

(4)　リロード遅延実行の設定

(5)　セッション情報ファイル出力先の変更

(6)　JSP事前コンパイルの設定

(7)　J2EEアプリケーション実行時間の監視の設定

(1)　リロード機能の適用範囲の設定

リロード機能の適用範囲の設定は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。

ejbserver.deploy.context.reload_scope
リロード機能を使用するかどうか，またリロードの対象を指定します。

app：EJBアプリケーション（EJB-JAR）とWebアプリケーション（WAR）をリロードの対象とする。

web：Webアプリケーション（WAR）だけをリロードの対象とする。

jsp：JSPだけをリロードの対象とする。

none：リロード機能を使用しない。

デフォルトの設定では，リロード機能は無効になっています。リロード機能を使用するためには，リロード機能を有効にして，適用範囲を設定する必要があります。

なお，リロード機能の有効／無効は，usrconf.propertiesのejbserver.rmi.localinvocation.scopeパラメタで指定するローカル呼び出し最適化機能の適用範囲と，リロード機能の適用範囲の組み合わせによって決まります。ローカル呼び出し最適化機能の適用範囲とリロード機能の適用範囲の対応については，「12.8.2　リロードの適用範囲」を参照してください。

(2)　更新検知インターバルの設定

更新検知インターバルの設定は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。簡易構築定義ファイルでの更新検知インターバルの設定について次の表に示します。

表12-18　簡易構築定義ファイルでの更新検知インターバルの設定

指定するパラメタ | 設定内容
ejbserver.deploy.context.check_interval | J2EEアプリケーションの構成ファイルを監視して更新を検知する間隔（秒）を指定します。
webserver.context.check_interval | Webアプリケーションの構成ファイルを監視して更新を検知する間隔（秒）を指定します。
webserver.jsp.check_interval | JSPの構成ファイルを監視して更新を検知する間隔（秒）を指定します。

更新検知インターバルの設定値の関係を次に示します。

EJBアプリケーションの場合

ejbserver.deploy.context.check_intervalの値が使用されます。なお，ejbserver.deploy.context.check_intervalに0を指定している場合，EJBアプリケーションは更新検知されません。

サーブレットの場合

webserver.context.check_intervalまたはejbserver.deploy.context.check_intervalの値が使用されます。優先順位を次に示します。

webserver.context.check_intervalの値

ejbserver.deploy.context.check_intervalの値

なお，webserver.context.check_intervalを指定していない場合には，ejbserver.deploy.context.check_intervalの値が使用されます。

また，webserver.context.check_intervalに0を指定している場合，サーブレットは更新検知されません。

JSPの場合

webserver.jsp.check_intervalまたはejbserver.deploy.context.check_intervalの値が使用されます。優先順位を次に示します。

webserver.jsp.check_intervalの値

ejbserver.deploy.context.check_intervalの値

なお，webserver.jsp.check_intervalを指定していない場合には，ejbserver.deploy.context.check_intervalの値が使用されます。

また，webserver.jsp.check_intervalに0を指定している場合，JSPは更新検知されません。

(3)　構成ファイル更新用インターバルの設定

構成ファイル更新用インターバルは，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に指定します。簡易構築定義ファイルでの構成ファイル更新用インターバルの設定について次の表に示します。

表12-19　簡易構築定義ファイルでの構成ファイル更新用インターバルの設定

指定するパラメタ | 設定内容
ejbserver.deploy.context.update.interval | J2EEアプリケーションの構成ファイルのコピーに必要な時間（秒）を指定します。
webserver.context.update.interval | Webアプリケーションの構成ファイルのコピーに必要な時間（秒）を指定します。
webserver.jsp.update.interval | JSPの構成ファイルのコピーに必要な時間（秒）を指定します。

構成ファイル更新用インターバルの設定値の関係を次に示します。

EJBアプリケーションの場合

ejbserver.deploy.context.update.intervalの値が使用されます。

サーブレットの場合

webserver.context.update.intervalまたはejbserver.deploy.context.update.intervalの値が使用されます。優先順位を次に示します。

webserver.context.update.intervalの値

ejbserver.deploy.context.update.intervalの値

webserver.context.update.intervalを指定していない場合には，ejbserver.deploy.context.update.intervalの値が使用されます。

JSPの場合

webserver.jsp.update.intervalまたはejbserver.deploy.context.update.intervalの値が使用されます。優先順位を次に示します。

webserver.jsp.update.intervalの値

ejbserver.deploy.context.update.intervalの値

webserver.jsp.update.intervalを指定していない場合には，ejbserver.deploy.context.update.intervalの値が使用されます。

(4)　リロード遅延実行の設定

リロード遅延実行は，簡易構築定義ファイルの論理J2EEサーバ（j2ee-server）の<configuration>タグ内に次のパラメタを指定します。

webserver.context.reload_delay_timeout
Webアプリケーションをリロードする場合にリロード遅延実行を使用するかどうかを指定します。また，リロード遅延実行を使用する場合に，リロード処理を開始するまでの時間を設定するときは，最大遅延時間（秒）を指定します。

(5)　セッション情報ファイル出力先の変更

Webアプリケーションをリロードする場合は，リロード実行前に生成したセッション情報を引き継いで，リロード後も継続して利用します。セッション情報は，セッション情報ファイルに出力されます。

セッション情報ファイルの出力先

セッション情報ファイルは，デフォルトでは次の場所に出力されます。

Windowsの場合
<Cosminexusのインストールディレクトリ>¥CC¥server¥repository¥<サーバ名>¥web¥<コンテキストルート名>¥cjwebsession.dat

UNIXの場合
/opt/Cosminexus/CC/server/repository/<サーバ名>/web/<コンテキストルート名>/cjwebsession.dat

Webアプリケーション単位のディレクトリ名

Webアプリケーション単位のディレクトリは，コンテキストルート名を基に規則に従ったディレクトリ名となります。コンテキストルート名にスラント（/），ドル記号（$），パーセント（%），プラス記号（+）が含まれる場合は，次に示す文字に変換します。

変換前の文字 | 変換後の文字
/ | $2f
$ | $24
% | $25
+ | $2b

出力先となるコンテキストルート名のディレクトリは，Webアプリケーションの開始時に作成されます。ただし，コンテキストルートがルートコンテキストの場合は，出力先ディレクトリのコンテキストルートは「$2f」として作成されます。作成されたディレクトリは，Webアプリケーションの終了時に削除されます。

セッション情報ファイルの出力先を変更する場合には，簡易構築定義ファイルで設定します。論理J2EEサーバ（j2ee-server）の<configuration>タグ内に，次のパラメタを設定します。

ejbserver.deploy.session.work.directory
Webアプリケーションのセッション情報ファイルの出力先を指定します。
ejbserver.deploy.session.work.directoryパラメタで指定したディレクトリ下に，「web¥<コンテキストルート名>」というディレクトリが作成されて，そのディレクトリ下にセッション情報ファイルが出力されます。

（例）セッション情報ファイルの出力先の設定例

<configuration>
 <logical-server-type>j2ee-server</logical-server-type>
 <param>
   <param-name>ejbserver.deploy.session.work.directory</param-name>
   <param-value>C:¥tmp¥session_work</param-value>
 </param>
 ：
</configuration>

この設定例の場合，コンテキストルート名が「examples」のWebアプリケーションのセッション情報ファイルは，次の場所に出力されます。

C:¥tmp¥session_work¥web¥examples¥cjwebsession.dat

(6)　JSP事前コンパイルの設定

JSP事前コンパイルでJSPファイルから生成されたクラスファイルを更新した場合も，J2EEアプリケーションの構成ファイルの更新を検知し，リロードが実行されます。

cjstartappコマンドに-jspcオプションを指定してJSP事前コンパイルを実行する場合には，usrconf.propertiesでJSPワークディレクトリなどを設定しておく必要があります。JSP事前コンパイルの設定については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(Webコンテナ)」の「2.5.8　実行環境での設定（J2EEサーバの設定）」を参照してください。

なお，アプリケーション開発時にcjjspcコマンドを使用してJSP事前コンパイルを実行する場合には，JSPワークディレクトリなどはコマンドのオプションで指定します。cjjspcコマンドを使用したJSPの事前コンパイルについては，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(Webコンテナ)」の「2.5　JSP事前コンパイル機能とコンパイル結果の保持」を参照してください。

(7)　J2EEアプリケーション実行時間の監視の設定

構成ファイルの更新を検知した場合，処理中のリクエストの処理が完了するとリロード処理を開始しますが，処理中のリクエストの処理が完了しない場合には，J2EEアプリケーション実行時間の監視のメソッドタイムアウトおよびメソッドキャンセルを実施することで，リロード処理を開始できます。

必要に応じて，J2EEアプリケーション実行時間の監視を設定してください。J2EEアプリケーション実行時間の監視の設定については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 運用／監視／連携編」の「5.3.9　実行環境での設定」を参照してください。

12.8.13　リロードの注意事項および制限事項

リロードに関する注意事項および制限事項を次に示します。

＜この項の構成＞

(1)　リロード機能の使用に関する注意事項

(2)　EJBアプリケーション（EJB-JAR）の注意事項

(3)　EJBアプリケーション（EJB-JAR）の制限事項

(4)　Webアプリケーション（WAR）の注意事項

(1)　リロード機能の使用に関する注意事項

J2EEアプリケーションの削除について
リロードに失敗しているJ2EEアプリケーションを削除する場合は，次のどちらかの方法で削除してください。

更新検知によるリロード，またはcjreloadappコマンドによるリロードを再度実行してください。リロードが成功したら，J2EEアプリケーションを停止して削除してください。

J2EEサーバを再起動したあとで，J2EEアプリケーションを削除してください。

削除後，J2EEアプリケーションを再インポートしてください。

メモリ不足の発生について
リロード処理では，クラスローダを再作成してクラスをロードし直すため，メモリを多く消費します（消費するメモリ使用量は，J2EEアプリケーションの実装に依存します）。このため，例えば，複数のWebアプリケーションで同時にリロード処理を繰り返すとメモリ不足が発生する可能性があります。また，リロード処理によって不要となったリソースがJavaVMから解放されるタイミングは，JavaVMのガーベージコレクションの実行タイミングに依存します。リクエストのピーク時など，負荷が高いときにリロードを繰り返すと，ガーベージコレクションを実行するタイミングがなく，メモリ不足が発生する可能性が高くなります。
このため，リクエストのピーク時など負荷が高い場合には，リソースの更新は避けてください。

メソッドキャンセルの実行について
処理中のリクエストの処理が完了しない場合には，J2EEアプリケーション実行時間の監視のメソッドタイムアウトおよびメソッドキャンセルを実行することで，リロード処理を開始できます。メソッドキャンセルを実行しても，処理をキャンセルできない場合には，J2EEサーバを再起動してください。

実行待ちとなっているリクエスト処理の再開について
J2EEアプリケーションのリロードでEJBアプリケーションの開始，または停止に失敗した場合，Webアプリケーションのリロード処理開始以降の新規リクエストは実行待ちとなります。実行待ちとなっているリクエスト処理を再開するためには，EJBアプリケーションを更新してリロードを実行し，リロード処理を成功させてください。Webアプリケーションを更新しても，リロードは実行されません。

J2EEアプリケーションに含まれるRARファイルについて
アプリケーションディレクトリにRARファイルを含めている場合，RARファイルはリロード機能の対象にはなりません。RARファイルを更新した場合は，更新したRARファイルを含むJ2EEアプリケーションを，サーバ管理コマンドを使用して入れ替えてください。サーバ管理コマンドを使用してJ2EEアプリケーションを入れ替える手順については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 運用／監視／連携編」の「5.6　J2EEアプリケーションの入れ替え」を参照してください。

(2)　EJBアプリケーション（EJB-JAR）の注意事項

リロード後にEJBを呼び出す場合には，クライアント側のソースコードでEJBHomeやビジネスインタフェースを取得し直す必要があります。リロード前に取得したインタフェース経由でEJBにアクセスした場合は例外が返ります。また，リロード実行中にEJBにアクセスした場合も例外が返ります。

リモートインタフェースまたはリモートビジネスインタフェースを入れ替えた場合，クライアント側ではスタブを取得し直す必要があります。

リロードを実行すると，Stateful Session Beanのクライアントとのセッションの状態は失われます。

(3)　EJBアプリケーション（EJB-JAR）の制限事項

これまでjavax.ejb.TimedObjectインタフェースを実装していなかったEJBで，javax.ejb.TimedObjectインタフェースを実装するように変更して，リロードすることはできません。リロードした場合には，次のようになります。

更新検知スレッドは停止させないで，J2EEアプリケーションを停止します。

更新を検知した場合，停止したJ2EEアプリケーションは再び開始されます。

CMRを使用したアプリケーションはリロードできません。

(4)　Webアプリケーション（WAR）の注意事項

タグライブラリ記述子ファイルのlistenerタグの変更内容は，リロード後に反映されません。

リロード時に利用できるサーブレットとJSPは，リロード後も状態を継続して利用できます。永久的に利用できないとされている場合は，リロード後も永久的に利用できません。一時的に利用できない場合は，リロードの実行とは関係なく，指定した期間後に利用できるようになります。

Webアプリケーションでリロード監視対象になっているファイルを削除した場合，そのファイルは監視対象外となります。このため，再度ファイルを追加しても更新検知によるリロードは実行されません。ただし，/WEB-INF/lib下にJARファイルを追加した場合は，そのJARファイルが削除後に再度追加されたかどうかに関係なく，コマンドによるリロードまたは更新検知によるリロードを実行できます。

JSPのリロード処理中にJ2EEアプリケーションを停止した場合，またはWebアプリケーションをリロードした場合，JSPのリロード処理は中止されます。

JSPのリロード処理開始時，ログの出力レベルがErrorの場合は，メッセージKDJE39310-Iに，更新されたファイル名とリロードを実行するJSPファイルのファイル数が出力されます。ログの出力レベルがWarningの場合は，メッセージKDJE39312-Iに，リロードを実行するすべてのJSPファイル名が出力されます。

リスナクラスのロード，インスタンス生成時に例外が発生した場合，Webコンテナは例外が発生したリスナを無効としてリロード処理を続行します。例外が発生したリスナを有効にするには，該当のリスナを修正して再度リロードを実行してください。

フィルタクラスのロード，インスタンス生成，initメソッド実行で例外が発生した場合，Webコンテナは例外が発生したフィルタを無効としてリロード処理を続行します。例外が発生したフィルタを有効にするには，該当のフィルタを修正して再度リロードを実行してください。

Webアプリケーションのリロード処理を実行すると，次の表に示すリスナインタフェースのメソッドが実行されます。

表12-20　Webアプリケーションのリロード処理で実行されるリスナのメソッド

インタフェース名 | メソッド名
javax.servlet.ServletContextListener | contextDestroyed()
contextInitialized()
javax.servlet.ServletContextAttributeListener | attributeRemoved()
attributeAdded()
javax.servlet.http.HttpSessionActivationListener※ | sessionWillPassivate()
sessionDidActivate()

注※　javax.servlet.http.HttpSessionオブジェクトが存在しないときは実行しません。

リロード処理時間は，Webアプリケーションの実装に大きく依存します。このため，次の点に注意が必要です。

セッション情報の容量は，シリアライズ処理時間，デシリアライズ処理時間に大きく影響します。シリアライズ対象となるセッション情報は，必要十分な容量にしてください。

リロード処理では，Webアプリケーションの終了処理，初期化処理が実行されます。終了処理，初期化処理が長い場合，リロードの処理時間も長くなり，Webアプリケーションのサービス停止期間にも影響があるため注意してください。ただし，リロード処理で初期化処理が実行されるのは，web.xmlの<load-on-startup>タグを設定したサーブレットやJSPだけです。<load-on-startup>タグを設定していないサーブレットやJSPの初期化処理は，リロード完了後の初回アクセス時に実行されます。

Webアプリケーションのリロード機能は，Webアプリケーション単位のクラスローダを入れ替えることによって，サーバ起動中のWebアプリケーションの入れ替えを実現しています。そのため，リロード後にリロード前のWebアプリケーション単位のクラスローダ，またはWebアプリケーション単位のクラスローダでロードされたクラスが参照されるとメモリリークが発生します。
次に，該当する場合を示します。リロード機能を使用する場合は，Webアプリケーション内でこれらのことをしないでください。

スレッドの生成
スレッドはコンテキストクラスローダを保持しますが，デフォルトでは親スレッドのコンテキストクラスローダを保持します。Webアプリケーション実行時のスレッドは，Webアプリケーション単位のクラスローダをコンテキストクラスローダとしているため，生成されたスレッドはWebアプリケーション単位のクラスローダをコンテキストクラスローダとします。そのため，リロード後も該当スレッドが存在すると，リロード前のWebアプリケーション単位のクラスローダが解放されないでメモリリークが発生します。

java.lang.Threadクラスまたはその派生クラスのインスタンス生成
java.lang.Threadクラスまたはその派生クラス（以降，スレッドクラス）のインスタンスを作成すると，所属するスレッドグループから該当スレッドクラスのインスタンスが参照されます。スレッドグループからの参照は，スレッドの実行を終了（runメソッドの完了）すると解放されます。そのため，Webアプリケーション内でスレッドクラスのインスタンスを生成し，runメソッドを実行しなかった場合は，該当スレッドクラスのインスタンスが解放されません。また，スレッドはコンテキストクラスローダとしてWebアプリケーション単位のクラスローダを保持しているため，Webアプリケーション単位のクラスローダが解放されないでメモリリークが発生します。

スレッドローカル変数の使用
Webコンテナではリクエストを処理するスレッドはプールされていて，Webコンテナ終了時まで終了しません。そのため，スレッドローカル変数にWebアプリケーションに含まれるクラスのインスタンスを格納すると，メモリリークが発生します。

JSP事前コンパイル機能を使用している場合，JSPファイルまたはタグファイルが依存するファイルは更新検知対象となったあと，次のどれかの条件を満たすときに更新検知対象から除外されます。

JSPファイルまたはタグファイルを，依存するファイルを使用しないように変更したクラスファイルに更新し，依存するファイルを使用するJSPファイルまたはタグファイルがほかにはない場合

JSPファイルまたはJSPファイルが依存するファイルから生成されたクラスファイルを更新し，JSPファイルから生成されたクラスのロードでエラーが発生した際，依存するファイルを使用するJSPファイルまたはタグファイルがほかにはない場合

該当するファイルが更新検知対象から除外された場合，メッセージログにKDJE39319-Iが出力されます。
なお，cjjspcコマンドを実行すると依存するファイルを使用しているJSPファイルまたはタグファイルも再度コンパイルされます。クラスファイルを展開ディレクトリ以外で作成したあとに更新する場合は，cjjspcコマンドで生成されたクラスファイルをすべて更新してください。

JSP事前コンパイル機能を使用していない場合，JSPファイルまたはタグファイルが依存するファイルは更新検知対象となったあと，次のどれかの条件を満たすときに更新検知対象から除外されます。

JSPファイルまたはタグファイルを，依存するファイルを使用しないように修正し，コンパイルが正常に完了した際，依存するファイルを使用するJSPファイルまたはタグファイルがほかにはない場合

JSPファイル，またはJSPファイルが依存するファイルを更新し，JSPファイルのコンパイルエラーが発生した際，依存するファイルを使用するJSPファイルまたはタグファイルがほかにはない場合

該当するファイルが更新検知対象から除外された場合，メッセージログにKDJE39318-Iが出力されます。また，JSPファイルのコンパイルエラーが発生し，かつ次の条件を満たすときは，更新検知対象から除外されたファイルだけを修正することで，コンパイルエラーとなったJSPファイルを修正しないで，JSPのリロードを実行できます。

依存するファイルがタグファイルの場合
タグファイルの記述内容とタグファイルを使用するファイルの記述内容が矛盾している。タグファイルの次の属性のどれかが不正である。
tagディレクティブに定義した属性：body-content，またはdynamic-attributes
attributeディレクティブに定義した属性：name，required，fragment，rtexprvalue，またはtype
variableディレクティブに定義した属性：name-given，variable-class，declare，またはscope

依存するファイルがweb.xmlの<include-prelude>，または<include-coda>に指定した暗黙的にincludeされるファイルの場合
暗黙的にincludeされたファイルの記述内容が，includeするJSPファイルの記述内容と矛盾している。

依存するファイルがincludeディレクティブに指定したファイルの場合
includeディレクティブに指定されたファイルの記述内容が，includeディレクティブを指定したJSPファイルまたはタグファイルの内容と矛盾している。

依存するファイルがタグライブラリ・ディスクリプタ（TLD）ファイルの場合
TLDファイルの記述内容とJSPファイルの記述内容が矛盾している。

この場合，該当するファイルは更新検知の対象外となっているため，依存するファイルを更新したあと，次のどれかを実行しJSPのリロードを実行する必要があります。

依存するファイルを使用するJSPファイルにブラウザなどからアクセスする。

依存するファイルを使用するJSPファイルまたはタグファイルの更新日時を更新する。

implicit.tldは更新検知対象ファイルではありません。implicit.tldとは，Servlet2.5仕様で定義されたタグファイルのバージョンを示すTLDファイルです。implicit.tldはJSP，またはタグファイルのリロード時に同時に再読み込みされます。

Webアプリケーションのリロードでは，アノテーション情報は読み込みません。Webアプリケーションのクラスに定義したアノテーション情報だけを更新した場合，その更新情報を反映するには，J2EEアプリケーションをいったん停止して再度開始してください。

13.　コンテナ拡張ライブラリ

この章では，コンテナ拡張ライブラリの機能について説明します。

アプリケーションサーバでは，Enterprise Beanやサーブレットから共通して使用するライブラリを，コンテナ拡張ライブラリとして利用できます。

＜この章の構成＞

13.1　この章の構成

13.2　コンテナ拡張ライブラリの利用

13.3　コンテナ拡張ライブラリの機能

13.4　サーバ起動・停止フック機能

13.5　スマートエージェント経由でのCORBAオブジェクトの呼び出し

13.6　コンテナ拡張ライブラリおよびサーバ起動・停止フック機能利用時の制限事項

13.1　この章の構成

コンテナ拡張ライブラリの機能と参照先を次の表に示します。

表13-1　コンテナ拡張ライブラリの機能と参照先

機能 | 参照先
コンテナ拡張ライブラリの利用 | 13.2
コンテナ拡張ライブラリの機能 | 13.3
サーバ起動・停止フック機能 | 13.4
スマートエージェント経由でのCORBAオブジェクトの呼び出し | 13.5
コンテナ拡張ライブラリおよびサーバ起動・停止フック機能利用時の制限事項 | 13.6

13.2　コンテナ拡張ライブラリの利用

この節では，コンテナ拡張ライブラリおよびサーバ起動・停止フック機能の概要について説明します。

アプリケーションサーバでは，EJB-JARとWAR間で共通に利用したい処理がある場合や，異なるEAR間で共通に利用したい処理がある場合に，ユーザ作成のライブラリを利用できます。ユーザ作成のライブラリを利用することで，サーブレット，JSP，およびEnterprise Beanの機能を拡張できます。

サーブレット，JSP，およびEnterprise Beanが共通に利用できるライブラリをコンテナ拡張ライブラリといいます。このライブラリを利用することで，Enterprise Bean，サーブレット，JSPから共通して，ユーザ作成のライブラリを呼び出せるようになります。

また，サーバ起動・停止フック機能を利用することで，サーバの起動，終了時にコンテナ拡張ライブラリが呼び出されるようにできます。また，コンテナ拡張ライブラリで使用するJNI機能の初期化などを行うことができます。

コンテナ拡張ライブラリを使用するためには，ライブラリを一つのJARファイルにまとめ，コンテナ拡張ライブラリを使用するための設定をusrconf.cfgで定義します。また，コンテナ拡張ライブラリがJNIを利用する場合は，サーバ起動・停止フック機能を使用するための設定も必要です。

コンテナ拡張ライブラリの設定については，「13.3.3　コンテナ拡張ライブラリの機能を使用するための設定」を参照してください。

13.3　コンテナ拡張ライブラリの機能

この節では，コンテナ拡張ライブラリの機能について説明します。

この節の構成を次の表に示します。

表13-2　この節の構成（コンテナ拡張ライブラリの機能）

分類 | タイトル | 参照先
解説 | コンテナ拡張ライブラリ利用の検討 | 13.3.1
コンテナ拡張ライブラリの作成と利用の流れ | 13.3.2
設定 | コンテナ拡張ライブラリの機能を使用するための設定 | 13.3.3

注1　「実装」および「運用」について，この機能固有の説明はありません。

注2　コンテナ拡張ライブラリを利用する場合の制限事項については，「13.6　コンテナ拡張ライブラリおよびサーバ起動・停止フック機能利用時の制限事項」を参照してください。

＜この節の構成＞

13.3.1　コンテナ拡張ライブラリ利用の検討

13.3.2　コンテナ拡張ライブラリの作成と利用の流れ

13.3.3　コンテナ拡張ライブラリの機能を使用するための設定

13.3.1　コンテナ拡張ライブラリ利用の検討

処理の種類に応じて検討する方法と，処理の内容に応じて検討する方法について説明します。

＜この項の構成＞

(1)　処理の種類による検討

(2)　処理の内容による検討

(1)　処理の種類による検討

まず，処理を次の3種類に分類し，コンテナ拡張ライブラリを利用するかどうかを検討します。コンテナ拡張ライブラリを利用しない場合は，EJB-JARファイル，WARファイル，またはライブラリJARに共通のライブラリを含めます。

業務処理
業務ごとに処理が異なるため，EJB-JARファイル，またはWARファイルに含めます。コンテナ拡張ライブラリを利用する必要はありません。

EJB-JARファイルおよびWARファイル間の共通処理
複数のEJB-JARファイルやWARファイルに含まれる，Enterprise Bean，サーブレット，JSP，業務処理が共通に利用できる処理がある場合，ライブラリJARを利用します。ライブラリJARを利用できない場合は，共通処理のクラスを作成して，コンテナ拡張ライブラリを利用します。

EAR間の共通処理
複数のEARに含まれる，EJB-JAR，WARが共通に利用できる処理がある場合，ライブラリJARを利用します。ライブラリJARを利用できない場合は，共通処理のクラスを作成して，コンテナ拡張ライブラリを利用します。

(2)　処理の内容による検討

Enterprise Bean，サーブレット，JSPでの操作内容を次のように分類し，それぞれコンテナ拡張ライブラリを使用するかどうかを検討します。コンテナ拡張ライブラリを利用するかどうかの指針を次の表に示します。

表13-3　操作内容ごとのコンテナ拡張ライブラリの利用の指針

操作内容 | コンテナ拡張ライブラリ | EJB-JARファイルまたはWARファイル | ライブラリJAR
ファイルやディレクトリへのアクセス操作 | ○ | × | ×
JNIの利用による操作※ | ○ | × | ×
スマートエージェント経由のCORBAオブジェクトの呼び出し | ○ | × | ×
J2EEコンテナ機能の操作 | × | ○ | ×
EJB-JARファイルおよびWARファイル内のクラス参照 | × | － | ×

（凡例）　○：含める　　×：含めない　　－：該当しない

注※　J2EEアプリケーションまたはWebアプリケーションで同一のネイティブライブラリをロードしようとした場合，JNIの仕様によってUnsatisfiedLinkErrorがスローされます。これは，アプリケーションで共通に使用するネイティブライブラリをコンテナ拡張ライブラリとして登録することで，回避できます。

注意

コンテナ拡張ライブラリには，次のアクセス権が付与されます。アクセス権は変更できません。

java.security.AllPermission

ただし，java.lang.RuntimePermissionのsetSecurityManagerアクセス権は付与されません。

13.3.2　コンテナ拡張ライブラリの作成と利用の流れ

コンテナ拡張ライブラリの作成と利用の流れを次に示します。

ユーザ作成のクラスを実装，コンパイルします。
サーバ起動・停止フック機能を使用する場合は，<Cosminexusのインストールディレクトリ>¥CC¥lib¥ejbserver.jarをクラスパスに指定してコンパイルします。なお，サーバ起動・停止フック機能を使用する場合は，IDEを使用しない方法で実装，コンパイルしてください。IDEを使用しないアプリケーションの開発方法については，マニュアル「Cosminexus アプリケーションサーバ アプリケーション開発ガイド」の「14.　Eclipseを使用しないJ2EEアプリケーションの開発」を参照してください。
また，サーバ起動・停止フック機能では，Cosminexus TPBrokerが提供するスマートエージェント経由のCORBAオブジェクトを呼び出す処理を実装することもできます。

作成したクラスを，JARファイルにアーカイブします。
ユーザが作成したクラスを，コンテナ拡張ライブラリ用のJARファイルにアーカイブします。EJB-JARファイルやWARファイルには含めないでください。

アーカイブしたJARファイルを，J2EEサーバまたはWebコンテナサーバのシステムクラスパスに指定します。

コンテナ拡張ライブラリを利用する場合，この手順のほかにJ2EEサーバまたはWebコンテナサーバでの設定（定義ファイルの指定など）が必要になります。

J2EEサーバでの設定については，「13.3.3　コンテナ拡張ライブラリの機能を使用するための設定」を参照してください。

Webコンテナサーバでの設定については，マニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「10.6.3　Webコンテナサーバの動作設定のカスタマイズ」を参照してください。

13.3.3　コンテナ拡張ライブラリの機能を使用するための設定

ここでは，コンテナ拡張ライブラリを使用するための設定について説明します。なお，コンテナ拡張ライブラリがJNIを利用する場合は，サーバ起動・停止フック機能を使用します。

コンテナ拡張ライブラリを使用するためには，次の設定が必要です。

コンテナ拡張ライブラリ用のJARファイルを作成します。
コンテナ拡張ライブラリの利用については，「13.2　コンテナ拡張ライブラリの利用」を参照してください。

簡易構築定義ファイルで，論理J2EEサーバ（j2ee-server）の<configuration>タグ内に，次のパラメタを指定します。

add.class.path
add.class.pathの設定値には，手順1.で作成したJARファイルのパスをJ2EEサーバのシステムクラスパスを指定します。

add.class.pathは，簡易構築定義ファイルのJ2EEサーバの拡張パラメタに設定します。

コンテナ拡張ライブラリからJNI機能を使用する場合は，簡易構築定義ファイルで，論理J2EEサーバ（j2ee-server）の<configuration>タグ内に，次のパラメタを指定します。

add.library.path
add.library.pathの設定値には，JNI用ライブラリの検索パスを指定します。

ejbserver.application.InitTermProcessClasses
ejbserver.application.InitTermProcessClassesの設定値には，サーバ起動・停止フック機能のクラス名を指定します。

add.library.pathおよびejbserver.application.InitTermProcessClassesは，簡易構築定義ファイルの，J2EEサーバの拡張パラメタに設定します。

サーバ管理コマンド用のファイルのキーにコンテナ拡張ライブラリ用のJARファイルを指定します。
指定するファイルおよびキーは，OSによって異なります。

Windowsの場合
usrconf.batのUSRCONF_JVM_CLASSPATHキー

UNIXの場合
usrconfのUSRCONF_JVM_CLPATHキー

コンテナ拡張ライブラリからJNI機能を使用する場合は，サーバ管理コマンド用のファイルのキーで，JNI用ライブラリの検索パスを指定します。
複数指定する場合は，セミコロン（;）で区切ってください。
指定するファイルは，OSによって異なります（キーは共通です）。

Windowsの場合
usrconf.batのUSRCONF_JVM_LIBPATHキー

UNIXの場合
usrconfのUSRCONF_JVM_LIBPATHキー

ファイルの詳細については，マニュアル「Cosminexus アプリケーションサーバ システム構築・運用ガイド」の「8.4　システムの構成定義」およびマニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「5.3　usrconf.bat（サーバ管理コマンド用オプション定義ファイル）」を参照してください。

簡易構築定義ファイルおよびユーザ定義ファイルの設定例を次に示します。この例では，コンテナ拡張ライブラリのJARファイルは「extended_container.jar」で，そのコンテナ拡張ライブラリがJNIを使用して「extended_container.dll」（UNIXの場合，extended_container）を呼び出します。

Windowsの場合

簡易構築定義ファイルの設定例

<configuration>
 <logical-server-type>j2ee-server</logical-server-type>
 <param>
   <param-name>add.class.path</param-name>
   <param-value>c:¥jar¥extended_container.jar</param-value>
   <param-name>add.library.path</param-name>
   <param-value>c:¥lib</param-value>
 </param>
 ：
</configuration>

サーバ管理コマンド用のusrconf.batの設定例

rem system classpath
set USRCONF_JVM_CLASSPATH=c:¥jar¥extended_container.jar

rem library path
set USRCONF_JVM_LIBPATH=c:¥lib

UNIXの場合

簡易構築定義ファイルの設定例

<configuration>
 <logical-server-type>j2ee-server</logical-server-type>
 <param>
   <param-name>add.class.path</param-name>
   <param-value>/work/classes/extended_container.jar</param-value>
   <param-name>add.library.path</param-name>
   <param-value>/work/lib</param-value>
 </param>
 ：
</configuration>

サーバ管理コマンド用のusrconfの設定例

#!/bin/csh -f
# system classpath
set USRCONF_JVM_CLPATH=/work/classes/extended_container.jar

# library path
set USRCONF_JVM_LIBPATH=/work/lib

13.4　サーバ起動・停止フック機能

この節では，サーバ起動・停止フック機能について説明します。

この節の構成を次の表に示します。

表13-4　この節の構成（サーバ起動・停止フック機能）

分類 | タイトル | 参照先
解説 | サーバ起動・停止フック処理の呼び出し順序 | 13.4.1
実装 | サーバ起動・停止フック機能の実装方法 | 13.4.2
設定 | サーバ起動・停止フック機能利用時のクラスパスの指定 | 13.4.3

注1　「運用」について，この機能固有の説明はありません。

注2　サーバ起動・停止フック機能を利用する場合の制限事項については，「13.6　コンテナ拡張ライブラリおよびサーバ起動・停止フック機能利用時の制限事項」を参照してください。

＜この節の構成＞

13.4.1　サーバ起動・停止フック処理の呼び出し順序

13.4.2　サーバ起動・停止フック機能の実装方法

13.4.3　サーバ起動・停止フック機能利用時のクラスパスの指定

13.4.1　サーバ起動・停止フック処理の呼び出し順序

サーバ起動・停止フック機能を複数登録した場合の，サーバ起動・停止フック処理の呼び出し順序について説明します。

＜この項の構成＞

(1)　正常に起動，停止した場合

(2)　サーバ起動フック処理中に例外が発生した場合

(3)　サーバ起動フック処理後に例外が発生した場合

(1)　正常に起動，停止した場合

J2EEサーバ，およびWebコンテナサーバ起動時には，登録されたクラス順にサーバ起動フック処理を行うserverInitializingメソッドが呼び出されます。また，J2EEサーバ，およびWebコンテナサーバ停止時には，登録された逆順にサーバ停止フック処理を行うserverTerminatingメソッドが呼び出されます。

J2EEサーバが正常起動した場合の，サーバ起動・停止フック機能の呼び出し順序を次の図に示します。なお，Webコンテナサーバの場合も，次の図と同様の順序で呼び出されます。

図13-1　サーバ起動・停止フック処理の呼び出し順序（正常起動時）

サーバ起動・停止フック処理を実装したA，B，Cの三つのクラスがあり，クラスA，クラスB，クラスCの順でクラスが登録されていることとします。サーバ起動フック処理では，正常に呼び出されると，クラスA，クラスB，クラスCの順でクラスが呼び出されます。サーバ停止フック処理では，クラスC，クラスB，クラスAの順でクラスが呼び出されます。

(2)　サーバ起動フック処理中に例外が発生した場合

サーバ起動フック処理の実行中に例外が発生した場合の，サーバ起動・停止フック機能の呼び出し順序を次の図に示します。なお，Webコンテナサーバの場合も，次の図と同様の順序で呼び出されます。

図13-2　サーバ起動・停止フック処理の呼び出し順序（起動フック処理中の例外発生時）

サーバ起動・停止フック処理を実装したA，B，Cの三つのクラスがあり，クラスA，クラスB，クラスCの順でクラスが登録されていることとします。クラスBのサーバ起動フック処理（serverInitializingメソッド）の実行中に例外が発生した場合は，クラスCのサーバ起動フック処理は呼び出されません。また，クラスCのサーバ停止フック処理（serverTerminatingメソッド）は呼び出されないで，クラスB，クラスAの順序でサーバ停止フック処理が呼び出されます。

(3)　サーバ起動フック処理後に例外が発生した場合

サーバ起動フック処理の実行後に例外が発生した場合の，サーバ起動・停止フック機能の呼び出し順序を次の図に示します。なお，Webコンテナサーバの場合も，次の図と同様の順序で呼び出されます。

図13-3　サーバ起動・停止フック処理の呼び出し順序（起動フック処理後の例外発生時）

サーバ起動・停止フック処理を実装したA，B，Cの三つのクラスがあり，クラスA，クラスB，クラスCの順でクラスが登録されていることとします。クラスBのサーバ起動フック処理（serverInitializingメソッド）の実行後に例外が発生した場合は，クラスCのサーバ起動フック処理は呼び出されません。また，サーバ停止フック処理は呼び出されません。

13.4.2　サーバ起動・停止フック機能の実装方法

サーバ起動・停止フック機能は，com.hitachi.software.ejb.application.InitTermProcessインタフェースを実装することで利用できます。サーバ起動フック処理はserverInitializingメソッド，停止フック処理はserverTerminatingメソッドに実装します。次に，InitTermProcessインタフェースの実装例を示します。

package sample;

import com.hitachi.software.ejb.application.InitTermProcess;
import com.hitachi.software.ejb.application.InitTermException;

public class AppInitTerm implements InitTermProcess {
   public void serverInitializing() throws InitTermException {
       try {
           // サーバ起動フック処理
       } catch (Exception e) {
           throw new InitTermException("詳細メッセージ");
       }
   }
   public void serverTerminating() throws InitTermException {
       try {
           // サーバ停止フック処理
       } catch (Exception e) {
           throw new InitTermException("詳細メッセージ");
       }
   }
}

J2EEサーバ，Webコンテナサーバは，起動時にデフォルトコンストラクタを使用してサーバ起動・停止フック機能のインスタンスを生成します。このため，クラスおよびデフォルトコンストラクタのアクセス指定子には，publicを指定してください。

サーバ停止フック処理が呼び出されるタイミングは，アプリケーションの停止処理後になります。J2EEサーバおよびWebコンテナサーバでは，スレッドの停止処理を行っていないため，処理スレッドは残りますが，サーバ停止フック処理後に，新たにアプリケーションは実行されません。

ユーザ定義ファイル（usrconf.properties）のサーバ起動・停止フック機能用のプロパティキー（ejbserver.application.InitTermProcessClasses）に，サーバ起動・停止フックのクラス名を指定します。また，サーバ起動・停止フックのクラス名は複数指定できます。ユーザ定義ファイル（usrconf.properties）については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」を参照してください。

13.4.3　サーバ起動・停止フック機能利用時のクラスパスの指定

サーバ起動・停止フック機能を利用する場合，JARファイルのパスを，J2EEサーバおよびWebコンテナサーバのシステムクラスパスに追加する必要があります。システムクラスパスの追加は，ユーザ定義ファイル（usrconf.cfg）に指定します。

システムクラスパスの追加の方法については，「13.3.3　コンテナ拡張ライブラリの機能を使用するための設定」，およびマニュアル「Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編」の「10.6.3　Webコンテナサーバの動作設定のカスタマイズ」を参照してください。また，ユーザ定義ファイル（usrconf.cfg）については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」を参照してください。

13.5　スマートエージェント経由でのCORBAオブジェクトの呼び出し

コンテナ拡張ライブラリを利用することで，J2EEアプリケーションまたはWebアプリケーションがCosminexus TPBrokerを使用して，スマートエージェント経由でCORBAオブジェクトを呼び出すことができます。スマートエージェントを利用してCORBAオブジェクトのオブジェクトリファレンスを取得し，メソッドを呼び出すときには，スマートエージェントが起動済みとなっており，スマートエージェントに，該当するCORBAオブジェクトのオブジェクトリファレンスが登録されている必要があります。また，コンテナ拡張ライブラリには，J2EEアプリケーションまたはWebアプリケーションからCORBAオブジェクトを呼び出す処理を含めます。

この節では，スマートエージェント経由でのCORBAオブジェクトの呼び出しについて説明します。

この節の構成を次の表に示します。

表13-5　この節の構成（スマートエージェント経由でのCORBAオブジェクトの呼び出し）

分類 | タイトル | 参照先
実装 | CORBAオブジェクト呼び出し処理の実装時の注意事項 | 13.5.1
CORBAオブジェクト呼び出し処理のパッケージ化の注意事項 | 13.5.2

注　「解説」，「設定」，および「運用」について，この機能固有の説明はありません。

次に，CORBAオブジェクト呼び出し処理の実装時の注意事項，およびCORBAオブジェクト呼び出し処理のパッケージ化の注意事項を示します。

＜この節の構成＞

13.5.1　CORBAオブジェクト呼び出し処理の実装時の注意事項

13.5.2　CORBAオブジェクト呼び出し処理のパッケージ化の注意事項

13.5.1　CORBAオブジェクト呼び出し処理の実装時の注意事項

CORBAオブジェクトの呼び出し処理を実装するときには，次の点に注意してください。

プロパティを使用して，org.omg.ORBをカスタマイズするには，org ORB init(String[] args, Properties props)メソッドのpropsパラメタにプロパティを指定してください。
なお，J2EEサーバおよびWebコンテナサーバのシステムプロパティに指定できるのキーは，vbroker.agent.port，vbroker.agent.enableLocator，およびvbroker.agent.addrキーだけです。

Cosminexus TPBrokerのサーバ機能は利用できません。また，J2EEサーバおよびWebコンテナサーバ上で，CORBAオブジェクトを活性化することはできません。

Cosminexus TPBrokerのインターセプタは利用できません。

Cosminexus TPBrokerのDII機能は利用できません。

13.5.2　CORBAオブジェクト呼び出し処理のパッケージ化の注意事項

CORBAオブジェクトの呼び出し処理をパッケージ化するときには，次の点に注意してください。

org.omg.CORBA配下のパッケージにあるインタフェース，クラスを利用するクラスは，EJB-JARファイルまたはWARファイルには含めないでください。これらのクラスは，コンテナ拡張ライブラリ用のJARファイルに含めます。

IDL定義から生成されたインタフェース，クラス，およびそれらを利用するクラスは，EJB-JARファイルまたはWARファイルには含めないでください。これらのクラスは，コンテナ拡張ライブラリ用のJARファイルに含めます。

13.6　コンテナ拡張ライブラリおよびサーバ起動・停止フック機能利用時の制限事項

コンテナ拡張ライブラリおよびサーバ起動・停止フック機能を利用する場合の制限事項を示します。

アプリケーションのポータビリティについて
コンテナ拡張ライブラリはJ2EEの仕様外の機能です。したがって，コンテナ拡張ライブラリを使用した場合は，アプリケーションとしての移行性は低下します。

コンテナ拡張ライブラリの呼び出しについて
コンテナ拡張ライブラリは，サーブレット，JSP，およびEnterprise Beanから呼び出されることを前提としています。次に示す利用形態は適用できないので，注意してください。

コンテナ拡張ライブラリおよびサーバ起動・停止フック機能から，EJB-JARファイル，WARファイルを参照する（EJB-JARファイル，WARファイルのクラスが，コンテナ拡張ライブラリのクラスを継承することも含む）。

コンテナ拡張ライブラリおよびサーバ起動・停止フック機能から，J2EEコンテナの機能を利用する（Enterprise Bean，JNDI，JDBCなどのAPIを呼び出す）。

EJB-JARファイルおよびWARファイルのクラスから，直接サーバ起動・停止フック機能を参照する（コンテナ拡張ライブラリのクラスが，EJB-JARファイル，WARファイルのクラスを継承することも含む）。

ファイル，ディレクトリのアクセスについて
コンテナ拡張ライブラリおよびサーバ起動・停止フック機能から，次に示すファイルやディレクトリを操作しないでください。

Cosminexusのインストールディレクトリ以下のファイルやディレクトリ

J2EEサーバおよびWebコンテナサーバの作業ディレクトリ以下のファイルやディレクトリ

JNI機能の利用について
コンテナ拡張ライブラリおよびサーバ起動・停止フック機能からJNI機能を利用する場合，J2EEサーバおよびWebコンテナサーバでは，ネイティブメソッドでの処理を管理できません。例えば，ネイティブメソッドでメモリアクセス違反があった場合，J2EEサーバおよびWebコンテナサーバは，JavaVMのプロセスごと異常終了します。

Cosminexus TPBrokerの利用について

コンテナ拡張ライブラリおよびサーバ起動・停止フック機能では，Cosminexus TPBrokerのサーバ機能を利用できません。これは，J2EEサーバおよびWebコンテナサーバ上にCosminexus TPBrokerのCORBAオブジェクトを活性化できないためです。

Cosminexus TPBrokerのDII機能は利用できません。

インストール型オプションパッケージの使用について
コンテナ拡張ライブラリおよびサーバ起動・停止フック機能は，インストール型オプションパッケージとして使用してはいけません。インストール型オプションパッケージとは，次のディレクトリに置かれたファイルです。

<Cosminexusのインストールディレクトリ>¥jdk¥jre¥lib¥extに置かれたJARファイル

<Cosminexusのインストールディレクトリ>¥jdk¥jre¥binに置かれたネイティブコードバイナリ

シャットダウンフックの登録について
コンテナ拡張ライブラリおよびサーバ起動・停止フック機能では，シャットダウンフックを登録しないでください。

14.　アプリケーション実装時の注意事項

この章では，アプリケーション実装時の注意事項について説明します。

＜この章の構成＞

14.1　スレッドローカル変数使用時の注意事項

14.1　スレッドローカル変数使用時の注意事項

java.lang.ThreadLocal.remove()メソッドでスレッドローカル変数に格納したJ2EEアプリケーションのクラスのインスタンスは，J2EEアプリケーションの停止までに削除してください。

スレッドローカル変数に格納したJ2EEアプリケーションのクラスのインスタンスをJ2EEアプリケーションの停止までに削除しないと，J2EEアプリケーションを停止してもクラスローダへの参照が残ることになり，メモリリークが発生します。

フレームワークなどが格納したインスタンスをJ2EEアプリケーションで削除できない場合は，J2EEアプリケーションの開始および停止を繰り返さないでください。J2EEアプリケーションの開始および停止を繰り返す場合は，J2EEサーバを再起動してください。

付録

＜この付録の構成＞

付録A　文字コード

付録B　クラスローダの構成

付録C　JPAプロバイダとEJBコンテナ間の規約

付録D　JPQLのBNF

付録E　Cosminexus JMSプロバイダのユースケース

付録F　各バージョンでの主な機能変更

付録G　このマニュアルの参考情報

付録H　用語解説

付録A　文字コード

HTTPは，主にWebサーバからブラウザへデータをダウンロードするために用いられるプロトコルですが，HTMLのフォームの場合などではデータのアップロードにも使われます。

ダウンロードするコンテンツの文字コードをWebサーバからブラウザに伝えるための規格は，Servlet APIでも明確に規定されています。しかし，過去のServlet API（Servlet API 2.2以前）では，HTTPクエリ文字列とHTTPリクエストボディの文字コードの扱いが明確ではなかったため，ベンダによって扱いが異なっていました。

Servlet API 2.3からは，Servlet APIを通してHTTPクエリ文字列やHTTPリクエストボディを参照するときに，文字コードを指定できるようになりました（ただし，エンコードタイプがmultipart/form-dataのHTTPリクエストボディを除きます）。これらのデータは，指定された文字コードのデータと見なされてJavaの内部表現であるUnicodeに変換されてからアプリケーションに渡されます。リソースの文字コードやUnicodeへの文字コード変換が間違っていると，「文字化け」を引き起こす原因になるため，アプリケーション開発時には，実行プロセスやリソースの文字コードを考慮する必要があります。

ここでは，アプリケーションで使用する文字コードと注意事項を示します。また，ブラウザおよびデータベースとデータをやり取りする場合の，文字コード変換の注意事項についても示します。

＜この節の構成＞

付録A.1　アプリケーションで扱う文字コード

付録A.2　ブラウザとアプリケーション間の文字コード変換

付録A.3　データベースとアプリケーション間の文字コード変換

付録A.1　アプリケーションで扱う文字コード

アプリケーションの構成を基に，文字コード変換の流れを示します。

図A-1　アプリケーションの文字コード変換の流れ

図中の番号（（1）～（5））は，文字コードを考慮する必要のあるプログラムやリソースを表します。また，図中の英字（A～E）は文字コード変換時のデータの流れを示します。プログラム，リソースで扱う文字コードと注意事項，および文字コード変換の動作と注意事項を，それぞれ表に示します。

表A-1　プログラム，リソースで扱う文字コードと注意事項

プログラム，リソース名
項目
扱う文字コードおよび注意事項

（1）入力ページ
URLのパス
URLのパスの文字コードは，ISO-8859-1である必要があります。シフトJISなどの非ASCII文字は記述できません。

クエリ文字列
HTMLの<FORM>タグを使用して送信される文字は，フォームを表示しているHTMLページと同じ文字コードでURLエンコードされて送出されます。

POSTデータ

（2）JSP
JSP
任意の文字コードで作成できます。
Webアプリケーションのバージョン2.4以降（JSP 2.0仕様以降）で，JSPドキュメントの文字エンコードを指定する場合は，XML宣言で文字エンコードを指定してください。
JSP 1.2仕様では，JSPの文字コードは，pageディレクティブのpageEncoding属性に記述する必要があります。

（3）HTML
HTML
任意の文字コードで作成できます。

（4）データベース
データベース
データベースに格納するデータの文字コードは，ブラウザに表示する文字コードを考慮して決定してください。

（5）出力ページ
レスポンスヘッダ
ISO-8859-1である必要があります。非ASCII文字を使用する場合は，URLエンコードする必要があります。

レスポンスボディ
ユーザプログラムで任意の文字コードを使用できます。

注意

Webコンテナでは英数字を2バイトで表現する文字コードは使用できません。英数字に2バイト使用する文字コードを次に示します。

UCS-2（ISO/IEC 10646）

UCS-4（ISO/IEC 10646-1）

UTF-16

表A-2　文字コード変換の動作と注意事項

変換個所
対象
文字コード変換時の動作および注意事項

A　ブラウザ～J2EEサーバ
URLのパス
Webコンテナでは，URLのパスの文字コードはISO-8859-1として処理されます。

クエリ文字列
クエリ文字列またはPOSTデータの文字コードは，アプリケーションで任意に決められます。サーブレット，JSPではUnicodeで扱われるので，アプリケーション内で矛盾のないように文字コードを変換してください。

POSTデータ

B　J2EEサーバ内
JSPファイル
pageディレクティブのpageEncoding属性に記述されたエンコーディングでファイルが読み込まれます。pageEncoding属性が省略されている場合は，contentType属性が使用されます。

HTMLファイル
HTMLファイルの文字コードのままブラウザに送信されます。

C　J2EEサーバ～データベース
データベース
JDBCドライバによって，Unicodeがデータベース格納文字コードに変換されます。

D　データベース～J2EEサーバ
データベース
JDBCドライバによって，データベース格納文字コードがUnicodeに変換されます。

E　J2EEサーバ～ブラウザ
レスポンスヘッダ
Webコンテナによって，レスポンスヘッダの文字コードがISO-8859-1に変換されます。

レスポンスボディ

サーブレットの場合

ServletResponseクラスのsetContentTypeメソッドによって文字コードを指定します。

JSPの場合

pageディレクティブのcontentType属性で文字コードを指定します。

参考

「文字化け」について

アプリケーションの実行環境では，文字コードはUnicodeとして扱われます。このため，ブラウザから送信された文字列は一度Unicodeに変換されます。また，データベースへのアクセス時にはUnicodeとデータベース格納文字コード間の文字コード変換，レスポンス時にはUnicodeからレスポンスの文字コードへの変換をする必要があります。これらの文字コード変換時に適切な変換をしないと，文字化けする原因になります。

これはシフトJISと呼ばれる文字コードに機種依存文字が含まれることや，同じ文字でもUnicodeへの変換結果がほかの文字コードと異なっているもの※があるために発生します。例えば，ブラウザから機種依存文字を含んだ文字データが送信され，これをUnicodeに変換した場合，レスポンス時にこの文字列をシフトJISに変換すると，文字化けする結果となります。

クライアントのOSをWindowsに限定できる場合は，文字コードをシフトJISではなくMS932またはWindows-31Jと指定することで，文字化けを避けられます。

注※

－，～，∥，￠，￡，￢などの文字が該当します。

付録A.2　ブラウザとアプリケーション間の文字コード変換

ブラウザとアプリケーション間で文字コード変換をするときに使用するメソッド，およびJSPとJavaScriptの実装時の注意事項について説明します。

＜この項の構成＞

(1)　ブラウザとアプリケーション間の文字コード変換で使用するメソッド

(2)　JSPのファイルインクルード時の注意事項

(3)　JavaScriptを使用してクエリ文字列を作成する場合の注意事項

(1)　ブラウザとアプリケーション間の文字コード変換で使用するメソッド

ブラウザを使用して送信されたクエリ文字列，POSTデータは，HttpServletRequestクラスのメソッドを使用して取得します。HttpServletRequestクラスのうち，文字コード変換に関係のあるメソッドと使用時の注意事項を示します。

(a)　setCharacterEncodingメソッド

リクエストのメッセージボディで使われている文字コードを設定します。このメソッドは，getParameterメソッドや，getReaderメソッドを使って入力ストリームから読み込む前に実行されなければなりません。

(a) setCharacterEncodingメソッド

リクエストのメッセージボディ，およびGETリクエストのクエリで送信されたパラメタに使われている文字コードを設定します。このメソッドは，getParameterメソッドや，getReaderメソッドを使って入力ストリームから読み込む前に実行されなければなりません。

setCharacterEncodingメソッドで設定した文字コードが使用される範囲を次の表に示します。

表A-3　setCharacterEncodingメソッドで設定した文字コードが使用される範囲

メソッド | HTMLのフォームから送信されたデータ（クエリも含む） | 左記以外のメッセージボディ
getParameter | ○ | －
getParameterNames | ○ | －
getParameterValues | ○ | －
getParameterMap | ○ | －
getInputStream | × | ×
getReader | × | △
getQueryString | × | －

（凡例）

○：取得した値はsetCharacterEncodingメソッドで設定した文字コードとしてUnicodeに変換される。

△：文字データはsetCharacterEncodingメソッドで設定した文字コードに変換される。

×：エンコードされたままの文字列が取得される。

－：取得できない。

(b)　getParameterメソッド

パラメタの名称を指定して，リクエストに含まれるパラメタの値を取得します。取得した値はURLデコードされ，Unicodeに変換されます。パラメタの名称やパラメタの値を取得する前に，setCharacterEncodingメソッドを用いて文字コードを指定する必要があります。指定しなかった場合，ISO-8859-1としてUnicodeに変換されます。HttpServletRequestクラスのgetParameterNamesメソッド，getParameterValuesメソッド，getParameterMapメソッドも同様です。

(c)　getInputStreamメソッド

リクエストのメッセージボディに含まれているバイナリデータを読み込むためのストリームを取得します。HTMLのフォームから送信されたデータからはエンコードされたままの文字列が取得されるので，取得した文字列を適切な文字コードでデコードする必要があります

(d)　getReaderメソッド

リクエストのメッセージボディにBufferedReaderクラスを使い，文字データとして取り出します。文字データはメッセージボディと同じ文字コードに変換されます。HTMLのフォームから送信されたデータからはエンコードされたままの文字列が取得されるので，取得した文字列を適切な文字コードでデコードする必要があります。

(e)　getQueryStringメソッド

リクエストされたURLのパスの後ろに含まれているクエリ文字列を返します。HTMLのフォームから送信されたデータからはエンコードされたままの文字列が取得されるので，取得した文字列を適切な文字コードでデコードする必要があります。

(2)　JSPのファイルインクルード時の注意事項

JSPファイルのincludeディレクティブでファイルをインクルードする場合には，インクルード元となるJSPファイルでcontentType属性を使用してエンコードを指定してください。また，JSPファイルの文字コードはpageEncoding属性に指定してください。指定しない場合はインクルード先の文字が正常に表示されない場合があります。

(3)　JavaScriptを使用してクエリ文字列を作成する場合の注意事項

JavaScriptのencodeURI関数およびencodeURIComponent関数※を使用すると，UTF-8でURLエンコードできます。この関数を用いて変換した文字列をクエリ文字列として使用してください。この場合，J2EEサーバ側でUTF-8としてUnicodeに変換すると，日本語の文字列データを取得できます。

注※

encodeURI関数とencodeURIComponent関数の相違は，「,/?:@&=+$,#」などの特殊文字を変換するかどうかです。encodeURI関数は「,/?:@&=+$,#」などの特殊文字を変換しません。

JavaScriptのescape関数はブラウザの種類やバージョンによって動作が異なります。escape関数で変換された文字列は，サーバ側で正常に扱えないため，escape関数を使用しないで，encodeURI関数またはencodeURIComponent関数を使用するようにしてください。

付録A.3　データベースとアプリケーション間の文字コード変換

アプリケーションからデータベースに文字データを格納するときには，Unicodeからデータベースに設定されている文字コードに変換して格納する必要があります。文字コード変換はJDBCドライバによって行われますが，次に示す内容に従って，あらかじめJDBCドライバに使用する文字コードを設定しておく必要があります。

J2EEサーバモードの場合，1.4モードでは，Connector属性ファイルのencodLangプロパティで指定します。ベーシックモードでは，ejbserver.jdbc.propertyInfo.ENCODELANGプロパティに使用する文字コードを指定してください。

サーブレットエンジンモードの場合，JDBCコネクションを取得するとき，ENCODELANGキーに該当値を設定したプロパティを作成し，JDBCドライバのjava.sql.Driver.connectメソッドまたはjava.sql.DriverManager.getConnectionメソッドの引数に渡してください。

付録B　クラスローダの構成

アプリケーションサーバのクラスローダ構成には，デフォルトのクラスローダ構成，ローカル呼び出し最適化機能を使用したときのクラスローダ構成，および下位互換用のクラスローダ構成の3種類があります。それぞれのクラスローダ構成およびクラスローダに設定されるクラスパスについて説明します。

＜この節の構成＞

付録B.1　デフォルトのクラスローダ構成

付録B.2　ローカル呼び出し最適化時のクラスローダ構成

付録B.3　下位互換用のクラスローダ構成

付録B.4　クラスローダに設定されるクラスパス

付録B.1　デフォルトのクラスローダ構成

新規インストール後のデフォルトのクラスローダ構成を次に示します。

図B-1　デフォルトのクラスローダ構成

各クラスローダの内容を次に示します。

システムクラスローダ
Cosminexusのコンポーネントが提供するクラスをロードします。

コネクタクラスローダ
単体デプロイされたリソースアダプタに含まれるクラスをロードします。J2EEサーバ内に一つだけ存在します。

JavaBeansクラスローダ
JavaBeansリソースのクラスをロードします。

アプリケーションクラスローダ
アプリケーション内のEJB-JAR，ライブラリJAR，リソースアダプタに含まれるクラスをロードします。アプリケーションごとに存在します。

Webアプリケーションクラスローダ
J2EEアプリケーション内のWARファイルに含まれるクラスをロードします。WARファイルごとに存在します。

JSPクラスローダ
JSPファイルおよびタグファイルをコンパイルしたときに生成されたクラスをロードします。JSPごとに存在します。

ポイント

リソースアダプタのロードについて

J2EEリソースアダプタとしてデプロイしたリソースアダプタは，コネクタクラスローダでロードされます。J2EEアプリケーションに含めて使用するリソースアダプタは，アプリケーションクラスローダでロードされます。

付録B.2　ローカル呼び出し最適化時のクラスローダ構成

ローカル呼び出し最適化機能を利用する場合，デフォルトのクラスローダとはクラスローダ構成が異なります。ローカル呼び出し最適化機能は，別のアプリケーションのEnterprise Beanを高速で呼び出すことができる機能です。

ローカル呼び出し最適化機能を使用するには，J2EEサーバ用ユーザ定義ファイル（<Cosminexusのインストールディレクトリ>¥CC¥server¥usrconf¥ejb¥<サーバ名称>¥usrconf.properties）に次の設定をします。

ejbserver.rmi.localinvocation.scope=all

ローカル呼び出し最適化時のクラスローダ構成を次に示します。

図B-2　ローカル呼び出し最適化時のクラスローダ構成

各クラスローダの内容を次に示します。

システムクラスローダ
Cosminexusのコンポーネントが提供するクラスをロードします。

コネクタクラスローダ
単体デプロイされたリソースアダプタに含まれるクラスをロードします。J2EEサーバ内に一つだけ存在します。

JavaBeansクラスローダ
JavaBeansリソースのクラスをロードします。

J2EEコンテナクラスローダ
すべてのアプリケーションクラスローダの親クラスローダとなり，すべてのアプリケーションクラスローダが持つクラスパスが設定されます。J2EEコンテナクラスローダは，J2EEサーバ内に一つだけ存在します。

アプリケーションクラスローダ
アプリケーション内のEJB-JAR，ライブラリJAR，およびリソースアダプタに含まれるクラスをクラスパスに持ちます。アプリケーションごとに存在します。ローカル呼び出し最適化時には親クラスローダであるJ2EEコンテナクラスローダにも，アプリケーションクラスローダが持つクラスパスが設定されているため，このクラスローダでは何もロードされません。

Webアプリケーションクラスローダ
J2EEアプリケーション内のWARファイルに含まれるクラスをロードします。WARファイルごとに存在します。

JSPクラスローダ
JSPファイルおよびタグファイルをコンパイルしたときに生成されたクラスをロードします。JSPごとに存在します。

ポイント

リソースアダプタのロードについて

J2EEリソースアダプタとしてデプロイしたリソースアダプタは，コネクタクラスローダでロードされます。J2EEアプリケーションに含めて使用するリソースアダプタは，アプリケーションクラスローダでロードされます。

注意

プロパティにejbserver.rmi.localinvocation.scope=allを設定して実行するときには，次の点に注意してください。

J2EEアプリケーションが持つEJB-JARやライブラリJARは同一のクラスローダでロードされるため，同名のクラスはJ2EEアプリケーション間で共有されます。内容の異なる同名クラスが存在する場合は，Javaの仕様上，先にロードされたクラスだけが有効となります。なお，WAR内のクラスはWAR単位に存在するクラスローダによってロードされますので共有の対象外となります。

J2EEアプリケーションのEJB-JARやライブラリJARを入れ替える場合は，J2EEアプリケーションを停止したあとにJ2EEサーバを再起動してください。再起動後に有効となります。

付録B.3　下位互換用のクラスローダ構成

デフォルトのクラスローダ構成と，Cosminexus Version 5（05-01）以前のクラスローダ構成では内容が異なります。このため，下位互換用にクラスローダ構成を変更するためのオプションがあります。Cosminexus Version 5（05-01）以前のバージョンからアップグレードインストールした場合は，自動的に下位互換用のクラスローダ構成になります。

下位互換用のクラスローダ構成に変更するには，J2EEサーバ用ユーザ定義ファイル（<Cosminexusのインストールディレクトリ>¥CC¥server¥usrconf¥ejb¥<サーバ名称>¥usrconf.properties）に次の設定をします。

動作モードをベーシックモードに設定

ejbserver.server.j2ee.feature=1.3basic

ローカル呼び出し最適化機能の適用範囲をなしに設定

ejbserver.rmi.localinvocation.scope=none

下位互換用のクラスローダ構成を次に示します。

図B-3　下位互換用のクラスローダ構成

各クラスローダの内容を次に示します。

システムクラスローダ
Cosminexusのコンポーネントが提供するクラスをロードします。

コネクタクラスローダ
下位互換用クラスローダ構成のときには，リソースアダプタを使用することはできないため，このクラスローダでは何もロードされません。

JavaBeansクラスローダ
JavaBeansリソースのクラスをロードします。

アプリケーションクラスローダ
アプリケーション内のEJB-JARおよびライブラリJARに含まれるクラスをロードします。アプリケーションごとに存在します。

Webアプリケーションクラスローダ
J2EEアプリケーション内のWARに含まれるクラスをロードします。WARごとに存在します。WARからJ2EEアプリケーション内のEJB呼び出しができるように，スタブ関連のクラスもロードします。

JSPクラスローダ
JSPファイルおよびタグファイルをコンパイルしたときに生成されたクラスをロードします。JSPごとに存在します。

付録B.4　クラスローダに設定されるクラスパス

クラスローダに設定されるクラスパス，およびクラスローダがクラスをロードするときのクラスの検索順序を示します。

コネクタクラスローダ
コネクタクラスローダは単体RARのクラスをロードするクラスローダです。単体デプロイ済みRARファイルに含まれているJARファイルを，クラスパスに設定します。

J2EEコンテナクラスローダ
J2EEコンテナクラスローダは，ejbserver.rmi.localinvocation.scope=all（ローカル呼び出し最適化機能を使用する）を指定したときに有効になるクラスローダです。すべてのアプリケーションクラスローダの親クラスローダとなり，開始状態にあるすべてのアプリケーションクラスローダのクラスパスを自分のクラスパスに持ちます。

アプリケーションクラスローダ
アプリケーションクラスローダは，J2EEアプリケーション内のEJB-JAR，ライブラリJAR，およびコンテナ生成クラスをロードします。設定されるクラスパスの順序を次に示します。

J2EEアプリケーションに含まれるRARに含まれているJARファイル

J2EEアプリケーションに含まれるEJB-JAR

参照方式のライブラリ

J2EEアプリケーションに含まれるライブラリJAR

Naming切り替え機能によって参照している別アプリケーションのEJB-JARファイル（参照先のアプリケーションが同一J2EEサーバに存在する場合）

付録C　JPAプロバイダとEJBコンテナ間の規約

ここでは，JPAプロバイダとEJBコンテナ間の規約について説明します。

＜この節の構成＞

付録C.1　ランタイムに関する規約

付録C.2　デプロイメントに関する規約

付録C.1　ランタイムに関する規約

ランタイムに関する規約には，コンテナ側の責任とJPAプロバイダ側の責任があります。

＜この項の構成＞

(1)　コンテナ側の責任

(2)　JPAプロバイダ側の責任

(3)　javax.transaction.TransactionSynchronizationRegistryインタフェース

(1)　コンテナ側の責任

トランザクションスコープの永続化コンテキストに関する規約
トランザクションスコープの永続化コンテキストが使用されている場合に，JTAトランザクションにエンティティマネージャが関連づいていないときには，コンテナは次の処理を実行します。

コンテナは次の場合に，EntityManagerFactory.createEntityManagerを呼び出して新しいエンティティマネージャを作成します。
JTAトランザクションのスコープ内のビジネスメソッドで，トランザクションスコープの永続化コンテキストを使用するエンティティマネージャのメソッドが初めて呼び出された場合

JTAトランザクションが決着（コミットまたはロールバック）したあとに，コンテナはEntityManager.closeを呼び出して，エンティティマネージャをクローズします。

また，コンテナは次の条件をすべて満たすと，TransactionRequiredExceptionをスローします。

トランザクションスコープの永続化コンテキストが使用されている場合

トランザクションがアクティブでない場合

アプリケーションからEntityManagerのpersist，remove，merge，refreshメソッドが呼び出された場合

拡張永続化コンテキストに関する規約
拡張永続化コンテキストが使用されている場合は，コンテナは次の処理を行います。

コンテナは次の場合に，EntityManagerFactory.createEntityManagerを呼び出して新しいエンティティマネージャを作成します。
Stateful Session Beanのインスタンスが作成された際に，拡張永続化コンテキストを使用するエンティティマネージャへの参照が定義されている場合

コンテナは次のタイミングで，EntityManager.closeを呼び出してエンティティマネージャをクローズします。
エンティティマネージャを作成したStateful Session Bean，および同じ永続化コンテキストを引き継いだStateful Session Beanが削除されたとき

コンテナ管理のトランザクションを使用するStateful Session Beanのビジネスメソッドの呼び出し時に，エンティティマネージャがJTAトランザクションと関連づけられていない場合には，コンテナはエンティティマネージャをJTAトランザクションに関連づけ，EntityManager.joinTransactionを呼び出します。JTAトランザクションにすでに別のエンティティマネージャが関連づけられている場合には，コンテナはEJBExceptionをスローします。

ビーン管理のトランザクションを使用するStateful Session Beanのビジネスメソッド内でUserTransaction.beginが呼び出された場合には，コンテナはエンティティマネージャをJTAトランザクションと関連づけ，EntityManager.joinTransactionを呼び出します。なお，ビーン管理のトランザクションについては，マニュアル「Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.7.2　BMT」を参照してください。

コンテナ管理のエンティティマネージャに関する規約
コンテナ管理のエンティティマネージャを使用している場合に，アプリケーションがEntityManager.closeを呼び出すと，コンテナはIllegalStateExceptionをスローします。
@PersistenceCotnextまたはDDの<persistence-context-ref>タグで，プロパティが指定された場合には，コンテナはEntityManagerFactory.createEntityManager(Map map)メソッドを使用してエンティティマネージャを作成し，指定されたプロパティをmap引数に含めてJPAプロバイダに渡します。

コネクションの自動クローズ機能について
アプリケーションサーバの場合，Session BeanやWebコンポーネントの延長でJPAプロバイダが取得したコネクションは，コンテナの自動クローズ機能によって自動的にクローズされることがあります。コネクションの自動クローズ機能とは，コネクションのリークを防止するための機能です。
コネクションは，次の条件を満たすと自動クローズの対象となります。

Stateless Session Beanで取得したコネクションは，ビジネスメソッドからリターンするときに，自動クローズの対象となります。

Stateful Session Beanで取得したコネクションは，Stateful Session Beanが破棄されるときに，自動クローズの対象となります。

Webコンポーネントで取得したコネクションは，サービスメソッドからリターンするときに，自動クローズの対象となります。

ただし，これらの条件に当てはまる場合でも，コネクションがJTAトランザクションに参加しているときには，JTAトランザクションがコミットするまで自動クローズが保留されます。

(2)　JPAプロバイダ側の責任

アプリケーションで使用するエンティティマネージャが，トランザクションスコープの永続化コンテキストを使用するように定義されているか，拡張永続化コンテキストを使用するように定義されているかは，JPAプロバイダには伝わりません。JPAプロバイダでの責任は，コンテナが要求したときにエンティティマネージャを作成し，トランザクションからトランザクションの決着の通知を受け取るためのSynchronizationをトランザクションに登録することです。

コンテナがEntityManagerFactory.createEntityManagerを呼び出したときには，JPAプロバイダは新しいエンティティマネージャを作成し，それをコンテナに返す必要があります。JTAトランザクションがアクティブである場合は，JPAプロバイダはSynchronizationをJTAトランザクションに登録する必要があります。

コンテナがEntityManager.joinTransactionを呼び出したときには，JPAプロバイダはSynchronizationをJTAトランザクションに登録する必要があります。ただし，以前にjoinTransactionが呼び出されていて，JTAトランザクションにSynchronizationを登録済みの場合には，何もする必要はありません。

JTAトランザクションがコミットされるときには，JPAプロバイダはすべての変更されたエンティティの状態を，データベースにフラッシュする必要があります。

JTAトランザクションがロールバックされるときには，JPAプロバイダは，すべてのmanaged状態のエンティティをデタッチする必要があります。

JPAプロバイダがトランザクションのロールバックの原因になる例外をスローする場合には，JPAプロバイダがトランザクションをロールバックにマークする必要があります。

コンテナがEntityManager.closeを呼び出した場合，そのエンティティマネージャが関係したすべての未解決トランザクションが決着されたあとに，JPAプロバイダはすべての確保したリソースを解放する必要があります。エンティティマネージャがすでにクローズされている場合には，JPAプロバイダはIllegalStateExceptionをスローする必要があります。

コンテナがEntityManager.clearを呼び出した場合，JPAプロバイダはすべてのmanaged状態のエンティティをデタッチする必要があります。

(3)　javax.transaction.TransactionSynchronizationRegistryインタフェース

JPAプロバイダは，トランザクションにSynchronizationを登録したり，トランザクションをロールバックにマークしたりするために，TransactionSynchronizationRegistryインタフェースを使用できます。TransactionSynchronizationRegistryのインスタンスは，JNDIを使用して「java:comp/TransactionSynchronizationRegistry」という名前でルックアップできます。

インタフェース定義を次に示します。

package javax.transaction;

/**
* このインタフェースは，JPAプロバイダやリソースアダプタなど，
* アプリケーションサーバのシステムレベルのコンポーネントから使用する
* ためのものです。
* このインタフェースを使って，
* 特別な順序で呼ばれるシンクロナイゼーションの登録，
* 現在のトランザクションへのリソースオブジェクトの登録，
* 現在のトランザクションのコンテキストの取得，
* 現在のトランザクションのステータスの取得，
* 現在のトランザクションをロールバックにマークできます。
*
* このインタフェースはステートレスなサービスオブジェクトとして，
* アプリケーションサーバによって実装されます。
* 同じオブジェクトを複数のコンポーネントからマルチスレッドセーフに
* 使用できます。
*
* 標準的なアプリケーションサーバでは，このインタフェースを実装した
* インスタンスは，JNDIを使用して標準的な名前でルックアップできます。
* 標準的な名前は
* 「java:comp/TransactionSynchronizationRegistry」です。
*/
public interface TransactionSynchronizationRegistry {

   /**
    * このメソッドを呼び出した時に現在のスレッドに関連づいている
    * トランザクションを表現する一意のオブジェクトを返します。
    * このオブジェクトのhashCodeとequalsメソッドは
    * オーバーライドされており，
    * ハッシュマップのキーとして使用できます。
    * トランザクションが存在しない場合には，nullを返します。
    *
    * 同じアプリケーションサーバの同じトランザクションコンテキスト内で
    * このメソッドが呼ばれて返されたオブジェクトは，すべて同じhashCodeを
    * 持ち，equalメソッドでの比較結果はtrueとなります。
    *
    * toStringメソッドは，トランザクションコンテキストの情報を人が
    * 読みやすい形の文字列として返します。
    * ただし，toStringで返される文字列のフォーマットは規定されていません。
    * また，toStringの結果に関して，バージョン間での互換性は
    * 保障されていません。
    *
    * 取得したオブジェクトがシリアライズできる保障はなく，
    * JavaVMの外に出したときの動作は規定されていません。
    *
    * @return このメソッドが呼ばれたときにスレッドに関連づいている
    * トランザクションを一意に表現するオブジェクト
    */
   Object getTransactionKey();

   /**
    * このメソッドを呼び出した時のスレッドに関連づいているトランザクション
    * のリソースマップに，オブジェクトを追加またはリプレースします。
    * マップのキーは，コンフリクトが発生しないように，
    * このメソッドを呼び出す側で定義されたクラスである必要があります。
    * キーとして使用するクラスは，マップのキーとして適切なhashCodeとequals
    * メソッドを持っている必要があります。
    * マップのキーや値が，このクラスによって評価されたり，使用されたりする
    * ことはありません。
    * このメソッドの一般的な規約は，Mapのputメソッドと同じで，
    * キーはnull以外にする必要がありますが，値はnullにすることもできます。
    * すでにキーに関連づいた値が存在する場合，その値は置き換えられます。
    *
    * @param key マップのエントリのキー
    * @param value マップのエントリの値
    * @exception IllegalStateException アクティブなトランザクションが
    * 存在しない場合
    * @exception NullPointerException 引数のキーがnullである場合
    */
   void putResource(Object key, Object value);

   /**
    * このメソッドを呼び出した時のスレッドに関連づいているトランザクション
    * のリソースマップから，オブジェクトを取り出します。
    * キーは，同じトランザクション内で，事前にputResourceメソッドに
    * 指定したオブジェクトと同じである必要があります。
    * 指定されたキーが現在のリソースマップに存在しない場合は，
    * nullを返します。
    * このメソッドの一般的な規約は，Mapのputメソッドと同じで，
    * キーはnull以外にする必要がありますが，値はnullにすることもできます。
    * マップにキーが格納されていない場合や，キーに対してnullが格納
    * されている場合には，返り値はnullになります。
    * @param key マップのエントリのキー
    * @return キーに関連づけられた値
    * @exception IllegalStateException アクティブなトランザクションが
    * 存在しない場合
    * @exception NullPointerException 引数のキーがnullである場合
    */
   Object getResource(Object key);

   /**
    * 特別な順序で呼ばれるシンクロナイゼーションのインスタンスを登録します。
    * このメソッドで登録したSynchronizationのbeforeCompletionは，
    * すべてのSessionSynchronization.beforeCompletionや，
    * トランザクションに直接登録された
    * Synchronization.beforeCompletionが呼ばれたあとで，
    * 2フェーズコミット処理が開始される前に呼び出されます。
    * 同じように，このメソッドで登録した
    * SynchronizationのafterCompletionは，
    * 2フェーズコミット処理が完了したあとで，
    * すべてのSessionSynchronization.afterCompletionや，
    * トランザクションに直接登録されたSynchronization.afterCompletionが
    * 呼ばれる前に呼び出されます。
    *
    * beforeCompletionは，このメソッドを呼び出した時にスレッドに
    * 関連づいていたトランザクションのコンテキストで呼び出されます。
    * beforeCompletionでは，コネクタなどのリソースへのアクセスは
    * 許可されていますが，タイマーサービスやビーンのメソッドなどの
    * ユーザコンポーネントへのアクセスは許可されていません。
    * これは，呼び出し側によって管理されているデータや，
    * registerInterposedSynchronizationで登録された
    * ほかのSynchronizationによって
    * すでにフラッシュされたデータを変更してしまうおそれがあるためです。
    * 一般的なコンテキストは，registerInterposedSynchronizationを
    * 呼び出したコンポーネントのコンテキストになります。
    *
    * afterCompletionが呼び出される時のコンテキストは定義されていません。
    * なお，ユーザコンポーネントへのアクセスは許可されていません。
    * また，リソースをクローズすることはできますが，
    * リソースに対するトランザクショナルな操作はできません。
    *
    *トランザクションがアクティブでない場合にこのメソッドが呼び出されたとき，
    * IllegalStateExceptionがスローされます。
    *
    * このメソッドが2フェーズコミット処理の開始後に呼び出された場合は，
    * IllegalStateExceptionがスローされます。
    *
    * @param sync 登録するSynchronizationのインスタンス
    * @exception IllegalStateException アクティブなトランザクションが
    * 存在しない場合
    */
   void registerInterposedSynchronization(Synchronization sync);

   /**
    * このメソッドを呼んだ時にスレッドに関連づいているトランザクション
    * のステータスを返します。
    * このメソッドの返り値は，
    * TransactionManager.getStatus()の結果と同じです。
    *
    * @return このメソッドを呼んだときにスレッドに関連づいている
    * トランザクションのステータス
    */
   int getTransactionStatus();

   /**
    * このメソッドを呼んだ時にスレッドに関連づいているトランザクション
    * がロールバックされるようにマークします。
    *
    * @exception IllegalStateException アクティブなトランザクションが
    * 存在しない場合
    */
   void setRollbackOnly();

   /**
    * このメソッドを呼んだ時にスレッドに関連づいているトランザクション
    * がロールバックするようにマークされているかどうかを返します。
    *
    * @return ロールバックするようにマークされている場合はtrue
    * @exception IllegalStateException アクティブなトランザクションが
    * 存在しない場合
    */
   boolean getRollbackOnly();
}

付録C.2　デプロイメントに関する規約

デプロイメントに関する規約には，コンテナ側の責任とJPAプロバイダ側の責任があります。

＜この項の構成＞

(1)　コンテナ側の責任

(2)　JPAプロバイダ側の責任

(3)　javax.persistence.spi.PersistenceProviderインタフェース

(4)　javax.persistence.spi.PersistenceUnitInfoインタフェース

(1)　コンテナ側の責任

デプロイメント時に，コンテナはアプリケーション内の決められた場所にパッケージングされたpersistence.xmlを検索します。アプリケーション内にpersistence.xmlが存在する場合には，コンテナはpersistence.xmlに定義された永続化ユニットの定義を処理します。なお，コンテナが検索する場所については，「5.8　persistence.xmlでの定義」を参照してください。

コンテナはpersistence.xmlファイルをpersistence_1_0.xsdで検証します。検証の結果，エラーが発生した場合にはユーザに通知します。persistence.xmlにプロバイダやデータソースの情報が指定されていない場合には，デフォルト値が使用されます。使用されるデフォルト値については，「5.8　persistence.xmlでの定義」を参照してください。コンテナが永続化ユニットのエンティティマネージャファクトリを作成するときには，JPAプロバイダにプロパティを渡すことがあります。

コンテナは，persistence.xmlで永続化ユニットごとに定義されたjavax.persistence.spi.PersistenceProviderの実装クラスのインスタンスを作成し，createContainerEntityManagerFactoryメソッドを呼び出して，コンテナ管理のエンティティマネージャを作成するためのEntityManagerFactoryを取得します。永続化ユニットのメタデータは，PersistenceUnitInfoオブジェクトとして，createContainerEntityManagerFactoryメソッドの引数でJPAプロバイダに渡されます。コンテナは一つの永続化ユニット定義に対して，一つだけEntityManagerFactoryを作成し，そのEntityManagerFactoryから複数のEntityManagerを作成します。

永続化ユニットが再デプロイされる場合には，コンテナはすでに取得したEntityManagerFactoryのcloseメソッドを呼び出したあと，createContainerEntityManagerFactoryを新しいPersistenceUnitInfoとともに呼び出します。

(2)　JPAプロバイダ側の責任

JPAプロバイダはPersistenceProvider SPIを実装し，PersistenceProviderのcreateContainerEntityManagerFactoryメソッドが呼ばれたときに，引数で渡される永続化ユニットのメタデータ（PersisetnceUnitInfo）を使用して，EntityManagerFactoryを作成し，コンテナに返す必要があります。

JPAプロバイダは，永続化ユニットに含まれるマネージドクラス（エンティティクラスなど）のメタデータアノテーションを処理します。また，永続化ユニットでO/Rマッピングファイルが使用されている場合には，JPAプロバイダが解釈する必要があります。このとき，O/Rマッピングファイルをorm_1_0.xsdを使用して検証し，エラーが発生した場合はユーザに通知する必要があります。

(3)　javax.persistence.spi.PersistenceProviderインタフェース

JPAプロバイダは，javax.persistence.spi.PersistenceProviderインタフェースを実装する必要があります。このインタフェースはコンテナによって呼び出されるものであり，アプリケーションから呼び出すものではありません。PersistenceProviderの実装クラスは，publicで引数のないコンストラクタを持っている必要があります。

javax.persistence.spi.PersistenceProviderインタフェースを次に示します。

package javax.persistence.spi;

/**
* JPAプロバイダによって実装されるインタフェースです。
* このインタフェースはEntityManagerFactoryを作成するために使用されます。
* Java EE環境ではコンテナによって呼び出され，
* JavaSE環境ではPersistenceクラスによって呼び出されます。
*/
public interface PersistenceProvider {

 /**
 * PersistenceクラスがEntityManagerFactoryを作成する時に呼び出されます。
 *
 * @param emName 永続化ユニットの名前
 * @param map JPAプロバイダによって使用されるプロパティのMap。
 * ここに指定されたプロパティは，persistence.xmlファイルの対応する
 * プロパティを上書きするため，またはpersistence.xmlファイルに
 * 指定されていないプロパティを指定するために使用されます。
 *（プロパティを指定する必要がない場合はnullが渡されます）
 * @return 永続化ユニットのEntityManagerFactory
 * JPAプロバイダが正しくない場合は，nullを返します。
 */
 public EntityManagerFactory createEntityManagerFactory(String
 emName, Map map);

 /**
 * コンテナがEntityManagerFactoryを作成する時に呼びだされます。
 *
 * @param info JPAプロバイダが使用するためのメタデータ
 * @param map JPAプロバイダが使用するためのインテグレーションレベルの
 * プロパティ（指定しない場合はnullが渡されます）
 * @return メタデータで指定された永続化ユニットのEntityManagerFactory
 */
 public EntityManagerFactory createContainerEntityManagerFactory(
 PersistenceUnitInfo info, Map map);
}

(4)　javax.persistence.spi.PersistenceUnitInfoインタフェース

javax.persistence.spi.PersistenceUnitInfoインタフェースの定義を次に示します。

import javax.sql.DataSource;
/**
* このインタフェースはコンテナによって実装され，
* EntityManagerFactoryを作成する時にJPAプロバイダに渡されて使用される。
*/
public interface PersistenceUnitInfo {

 /**
 * @return persistence.xmlで定義された永続化ユニット名
 */
 public String getPersistenceUnitName();

 /**
 * @return persistence.xmlの<provider>エレメントに定義された，
 * JPAプロバイダ実装クラスの完全修飾クラス名
 */
 public String getPersistenceProviderClassName();

 /**
 * @return EntityManagerFactoryによって作成されるEntityManagerの
 * トランザクションのタイプを返す。
 * persistence.xmlのtransaction-type属性に指定されたタイプである。
 */
 public PersistenceUnitTransactionType getTransactionType();

 /**
 * @return JPAプロバイダが使用するためのJTAが有効な
 * データソースを返す。
 * persistence.xmlの<jta-data-source>エレメントで指定されたデータソースか，
 * デプロイメント時にコンテナによって決定されたデータソースである。
 */
 public DataSource getJtaDataSource();

 /**
 * @return JPAプロバイダがJTAトランザクションの外で
 * データにアクセスするための，JTAが無効なデータソースを返す。
 * persistence.xmlの<non-jta-data-source>エレメントで指定された
 * データソースか，デプロイメント時にコンテナによって決定された
 * データソースである。
 */
 public DataSource getNonJtaDataSource();

 /**
 * @return JPAプロバイダがエンティティクラスのマッピングを
 * 決定するためにロードする必要のある，マッピングファイル名のリスト
 * マッピングファイルは，標準的なXML形式のマッピングフォーマット
 * でなければならない。
 * 一意の名前を持ち，アプリケーションのクラスパスからリソースとして
 * ロードできるものでなければならない。
 * それぞれのマッピングファイル名は，persistence.xmlの<mapping-file>タグ
 * に指定されたものである。
 */
 public List<String> getMappingFileNames();

 /**
 * JPAプロバイダが，永続化ユニットのマネージドクラスを検索する必要のある，
 * JARファイルまたはJARファイルを展開したディレクトリのURLのリストを返す。
 * それぞれのURLはpersistence.xmlファイルの<jar-file>タグに指定された
 * ものである。
 * URLはJARファイルまたはJARファイルを展開したディレクトリを指す
 * ファイルURLか，またはJARのフォーマットのInputStreamを取得できる
 * そのほかのURL形式である。
 *
 * @return JARファイルまたはディレクトリを指すURLオブジェクトのリスト
 */
 public List<URL> getJarFileUrls();

 /**
 * 永続化ユニットルートであるJARファイルまたはディレクトリのURLを返す。
 * （永続化ユニットルートがWEB-INF/classesディレクトリである場合，
 * WEB-INF/classesディレクトリのURLを返す）
 * URLはJARファイルまたはJARファイルを展開したディレクトリを指す
 * ファイルURLか，またはJARのフォーマットのInputStreamを取得できる
 * そのほかのURL形式である。
 *
 * @return JARファイルまたはディレクトリを指すURLオブジェクト
 */
 public URL getPersistenceUnitRootUrl();

 /**
 * @return JPAプロバイダがマネージドクラスとして扱わなくてはならない
 * クラス名のリスト。
 * それぞれのクラス名はpersistence.xmlファイルの<class>タグに指定された
 * ものである。
 */
 public List<String> getManagedClassNames();

 /**
 * @return 永続化ユニットルートに配置されていて，
 * 明示的にマネージドクラスであると指定されていないクラスを，
 * マネージドクラスとして扱うかどうかを返す。
 * この値は，persistence.xmlファイルの<exclude-unlisted-classes>タグに
 * 指定されたものである。
 */
 public boolean excludeUnlistedClasses();

 /**
 * @return Propertiesオブジェクト。
 * それぞれのプロパティはpersistence.xmlファイルの<property>タグに
 * 指定されたものである。
 */
 public Properties getProperties();

 /**
 * @return JPAプロバイダがクラスやリソースをロードしたり，
 * URLをオープンしたりするために使用できるClassLoader。
 */
 public ClassLoader getClassLoader();

 /**
 * PersistenceUnitInfo.getClassLoaderメソッドによって返されるクラスローダで，
 * 新しいクラスの定義や，クラスの再定義のたびに呼ばれる，
 * JPAプロバイダのトランスフォーマーを登録する。
 * このトランスフォーマーは，PersistenceUnitInfo.getNewTempClassLoaderメソッドで返される
 * クラスローダでロードされるクラスには影響を与えない。
 * クラスローディングのスコープ内で永続化ユニットが幾つ定義されていても，
 * 同じクラスローディングのスコープ内でクラスが変換されるのは一度だけである。
 *
 * @param transformer コンテナがクラスの定義（再定義）時に呼び出す，
 * JPAプロバイダのトランスフォーマー
 */
 public void addTransformer(ClassTransformer transformer);

 /**
 * JPAプロバイダが一時的にクラスやリソースをロードしたり，
 * URLをオープンしたりするために使用できるクラスローダの
 * 新しいインスタンスを返す。
 * このクラスローダのスコープやクラスパスは，
 * PersistenceUnitInfo.getClassLoaderで返される
 * クラスローダと完全に同じである。
 * このクラスローダでロードしたクラスが，
 * アプリケーションのコンポーネントから参照できるようになることはない。
 * JPAプロバイダは，createContainerEntityManagerFactoryの
 * 呼び出しの延長でだけ，このクラスローダを使用できる。
 *
 * @return 現在のクラスローダと同じスコープ・クラスパスを持つ一時的な
 * クラスローダ
 */
 public ClassLoader getNewTempClassLoader();

}

参考

アプリケーションサーバでは，永続化ユニットでJTAデータソース，非JTAデータソースが定義されていない場合には，getJtaDataSource()またはgetNonJtaDataSource()はnullを返します。永続化ユニットでJTAデータソース，非JTAデータソースが定義されていない場合とは，次の状態を指します。

persistence.xmlで<jta-data-source>，<non-jta-data-source>が省略されていて，かつデフォルト値がシステムプロパティejbserver.jpa.defaultJtaDsName，ejbserver.jpa.defaultNonJtaDsNameで定義されていない場合

システムプロパティejbserver.jpa.overrideJtaDsName，ejbserver.jpa.overrideNonJtaDsNameも定義されていない場合

付録D　JPQLのBNF

ここでは，JPA1.0仕様で規定されているJPQLのBNFについて示します。

表D-1　BNF表記の規則

表記 | 内容
{　} | グループを表します。
[　] | オプションの構文を表します。
* | 0以上を表します。
A|B | AまたはBを表します。

なお，太字部分はキーワードを表します。

次に，BNFを示します。

QL_statement ::= select_statement | update_statement | delete_statement
select_statement ::= select_clause from_clause [where_clause] [groupby_clause]
[having_clause] [orderby_clause]
update_statement ::= update_clause [where_clause]
delete_statement ::= delete_clause [where_clause]
from_clause ::=
FROM identification_variable_declaration
{, {identification_variable_declaration | collection_member_declaration}}*
identification_variable_declaration ::= range_variable_declaration { join | fetch_join }*
range_variable_declaration ::= abstract_schema_name [AS] identification_variable
join ::= join_spec join_association_path_expression [AS] identification_variable
fetch_join ::= join_spec FETCH join_association_path_expression
association_path_expression ::=
collection_valued_path_expression | single_valued_association_path_expression
join_spec::= [ LEFT [OUTER] | INNER ] JOIN
join_association_path_expression ::= join_collection_valued_path_expression |
join_single_valued_association_path_expression
join_collection_valued_path_expression::=
identification_variable.collection_valued_association_field
join_single_valued_association_path_expression::=
identification_variable.single_valued_association_field
collection_member_declaration ::=
IN (collection_valued_path_expression) [AS] identification_variable
single_valued_path_expression ::=
state_field_path_expression | single_valued_association_path_expression
state_field_path_expression ::=
{identification_variable | single_valued_association_path_expression}.state_field
single_valued_association_path_expression ::=
identification_variable.{single_valued_association_field.}* single_valued_association_field
collection_valued_path_expression ::=
identification_variable.{single_valued_association_field.}*collection_valued_association_field
state_field ::= {embedded_class_state_field.}*simple_state_field
update_clause ::= UPDATE abstract_schema_name [[AS] identification_variable]
SET update_item {, update_item}*
update_item ::= [identification_variable.]{state_field | single_valued_association_field} =
new_value
new_value ::=
simple_arithmetic_expression |
string_primary |
datetime_primary |
boolean_primary |
enum_primary
simple_entity_expression |
NULL
delete_clause ::= DELETE FROM abstract_schema_name [[AS] identification_variable]
select_clause ::= SELECT [DISTINCT] select_expression {, select_expression}*
select_expression ::=
single_valued_path_expression |
aggregate_expression |
identification_variable |
OBJECT(identification_variable) |
constructor_expression
constructor_expression ::=
NEW constructor_name ( constructor_item {, constructor_item}* )
constructor_item ::= single_valued_path_expression | aggregate_expression
aggregate_expression ::=
{ AVG | MAX | MIN | SUM } ([DISTINCT] state_field_path_expression) |
COUNT ([DISTINCT] identification_variable | state_field_path_expression |
single_valued_association_path_expression)
where_clause ::= WHERE conditional_expression
groupby_clause ::= GROUP BY groupby_item {, groupby_item}*
groupby_item ::= single_valued_path_expression | identification_variable
having_clause ::= HAVING conditional_expression
orderby_clause ::= ORDER BY orderby_item {, orderby_item}*
orderby_item ::= state_field_path_expression [ ASC | DESC ]
subquery ::= simple_select_clause subquery_from_clause [where_clause]
[groupby_clause] [having_clause]
subquery_from_clause ::=
FROM subselect_identification_variable_declaration
{, subselect_identification_variable_declaration}*
subselect_identification_variable_declaration ::=
identification_variable_declaration |
association_path_expression [AS] identification_variable |
collection_member_declaration
simple_select_clause ::= SELECT [DISTINCT] simple_select_expression
simple_select_expression::=
single_valued_path_expression |
aggregate_expression |
identification_variable
conditional_expression ::= conditional_term | conditional_expression OR conditional_term
conditional_term ::= conditional_factor | conditional_term AND conditional_factor
conditional_factor ::= [ NOT ] conditional_primary
conditional_primary ::= simple_cond_expression | (conditional_expression)
simple_cond_expression ::=
comparison_expression |
between_expression |
like_expression |
in_expression |
null_comparison_expression |
empty_collection_comparison_expression |
collection_member_expression |
exists_expression
between_expression ::=
arithmetic_expression [NOT] BETWEEN
arithmetic_expression AND arithmetic_expression |
string_expression [NOT] BETWEEN string_expression AND string_expression |
datetime_expression [NOT] BETWEEN
datetime_expression AND datetime_expression
in_expression ::=
state_field_path_expression [NOT] IN ( in_item {, in_item}* | subquery)
in_item ::= literal | input_parameter
like_expression ::=
string_expression [NOT] LIKE pattern_value [ESCAPE escape_character]
null_comparison_expression ::=
{single_valued_path_expression | input_parameter} IS [NOT] NULL
empty_collection_comparison_expression ::=
collection_valued_path_expression IS [NOT] EMPTY
collection_member_expression ::= entity_expression
[NOT] MEMBER [OF] collection_valued_path_expression
exists_expression::= [NOT] EXISTS (subquery)
all_or_any_expression ::= { ALL | ANY | SOME} (subquery)
comparison_expression ::=
string_expression comparison_operator {string_expression | all_or_any_expression} |
boolean_expression { =|<>} {boolean_expression | all_or_any_expression} |
enum_expression { =|<>} {enum_expression | all_or_any_expression} |
datetime_expression comparison_operator
{datetime_expression | all_or_any_expression} |
entity_expression { = | <> } {entity_expression | all_or_any_expression} |
arithmetic_expression comparison_operator
{arithmetic_expression | all_or_any_expression}
comparison_operator ::= = | > | >= | < | <= | <>
arithmetic_expression ::= simple_arithmetic_expression | (subquery)
simple_arithmetic_expression ::=
arithmetic_term | simple_arithmetic_expression { + | - } arithmetic_term
arithmetic_term ::= arithmetic_factor | arithmetic_term { * | / } arithmetic_factor
arithmetic_factor ::= [{ + | - }] arithmetic_primary
arithmetic_primary ::=
state_field_path_expression |
numeric_literal |
(simple_arithmetic_expression) |
input_parameter |
functions_returning_numerics |
aggregate_expression
string_expression ::= string_primary | (subquery)
string_primary ::=
state_field_path_expression |
string_literal |
input_parameter |
functions_returning_strings |
aggregate_expression
datetime_expression ::= datetime_primary | (subquery)
datetime_primary ::=
state_field_path_expression |
input_parameter |
functions_returning_datetime |
aggregate_expression
boolean_expression ::= boolean_primary | (subquery)
boolean_primary ::=
state_field_path_expression |
boolean_literal |
input_parameter |
enum_expression ::= enum_primary | (subquery)
enum_primary ::=
state_field_path_expression |
enum_literal |
input_parameter |
entity_expression ::=
single_valued_association_path_expression | simple_entity_expression
simple_entity_expression ::=
identification_variable |
input_parameter
functions_returning_numerics::=
LENGTH(string_primary) |
LOCATE(string_primary, string_primary[, simple_arithmetic_expression]) |
ABS(simple_arithmetic_expression) |
SQRT(simple_arithmetic_expression) |
MOD(simple_arithmetic_expression, simple_arithmetic_expression) |
SIZE(collection_valued_path_expression)
functions_returning_datetime ::=
CURRENT_DATE|
CURRENT_TIME |
CURRENT_TIMESTAMP
functions_returning_strings ::=
CONCAT(string_primary, string_primary) |
SUBSTRING(string_primary,
simple_arithmetic_expression, simple_arithmetic_expression)|
TRIM([[trim_specification] [trim_character] FROM] string_primary) |
LOWER(string_primary) |
UPPER(string_primary)
trim_specification ::= LEADING | TRAILING | BOTH

付録E　Cosminexus JMSプロバイダのユースケース

ここでは，Cosminexus JMSプロバイダを使用する場合のユースケースについて説明します。

Cosminexus JMSプロバイダを使用する場合は，ここで説明する手順に従って，環境構築および運用を実行してください。ここで示す以外の手順での構築・運用を実行した場合，Cosminexus JMSプロバイダが正しく動作しないおそれがあります。

説明するユースケースの種類を次の表に示します。

表E-1　Cosminexus JMSプロバイダのユースケースの種類

分類 | 作業 | 作業内容 | 作業詳細 | 参照先
構築 | 新規環境構築 | 新規に環境を構築します。 | Cosminexus JMSプロバイダを使用する場合の環境構築 | 付録E.3
環境再構築 | 環境を再構築します。 | Cosminexus JMSプロバイダを使用するアプリケーションの追加 | 付録E.4
Cosminexus JMSプロバイダを使用するアプリケーションの削除 | 付録E.5
運用 | 定期運用 | Cosminexus JMSプロバイダを使用する場合に定期的（日々またはその他の運用タイミング）で必要となる運用を実行します。 | Cosminexus JMSプロバイダサービスの開始（初回起動時） | 付録E.6
Cosminexus JMSプロバイダサービスの開始（稼働中システムの再起動時） | 付録E.7
CJMSPリソースアダプタとCJMSPブローカーの状態確認 | 付録E.8
メッセージ配信状況の確認と滞留時の対処（CJMSPブローカーを一時停止する方法） | 付録E.9
メッセージ配信状況の確認と滞留時の対処（アプリケーションを停止する方法） | 付録E.10
Cosminexus JMSプロバイダサービスの終了 | 付録E.11
非定期運用 | Cosminexus JMSプロバイダを使用する場合に非定期で必要となる運用を実行します。 | 送信先の圧縮 | 付録E.12
送信先サイズの変更 | 付録E.13
永続化サブスクライバーの削除 | 付録E.14
監視作業 | Cosminexus JMSプロバイダで使用されるリソースを監視します。 | CJMSPブローカーの状態監視 | 付録E.15
CJMSPブローカーの詳細情報確認 | 付録E.16
送信先の状態確認 | 付録E.17
永続化サブスクライバーの状態確認 | 付録E.18
障害編 | 障害解析手順 | Cosminexus JMSプロバイダを使用中に障害が発生した場合に障害要因を解析します。 | CJMSPリソースアダプタに問題が発生した場合の解析 | 付録E.19
CJMSPブローカーが障害によって停止したときの解析 | 付録E.20
Cosminexus JMSプロバイダサービス無応答時の解析 | 付録E.21
障害回復手順 | Cosminexus JMSプロバイダを使用中に障害が発生した場合に回復します。 | CJMSPリソースアダプタに問題が発生した場合の回復 | 付録E.22
CJMSPブローカーが障害によって停止したときの回復 | 付録E.23
Cosminexus JMSプロバイダサービス無応答時の回復 | 付録E.24
削除 | 環境削除 | Cosminexus JMSプロバイダの環境を削除します。 | Cosminexus JMSプロバイダサービスインスタンスの削除 | 付録E.25

＜この節の構成＞

付録E.1　すべてのユースケースに共通の前提条件

付録E.2　前提とするプロセスモデル

付録E.3　Cosminexus JMSプロバイダを使用する場合の環境構築

付録E.4　Cosminexus JMSプロバイダを使用するアプリケーションの追加

付録E.5　Cosminexus JMSプロバイダを使用するアプリケーションの削除

付録E.6　Cosminexus JMSプロバイダサービスの開始（初回起動時）

付録E.7　Cosminexus JMSプロバイダサービスの開始（稼働中システムの再起動時）

付録E.8　CJMSPリソースアダプタとCJMSPブローカーの状態確認

付録E.9　メッセージ配信状況の確認と滞留時の対処（CJMSPブローカーを一時停止する方法）

付録E.10　メッセージ配信状況の確認と滞留時の対処（アプリケーションを停止する方法）

付録E.11　Cosminexus JMSプロバイダサービスの終了

付録E.12　送信先の圧縮

付録E.13　送信先サイズの変更

付録E.14　永続化サブスクライバーの削除

付録E.15　CJMSPブローカーの状態監視

付録E.16　CJMSPブローカーの詳細情報確認

付録E.17　送信先の状態確認

付録E.18　永続化サブスクライバーの状態確認

付録E.19　CJMSPリソースアダプタに問題が発生した場合の解析

付録E.20　CJMSPブローカーが障害によって停止したときの解析

付録E.21　Cosminexus JMSプロバイダサービス無応答時の解析

付録E.22　CJMSPリソースアダプタに問題が発生した場合の回復

付録E.23　CJMSPブローカーが障害によって停止したときの回復

付録E.24　Cosminexus JMSプロバイダサービス無応答時の回復

付録E.25　Cosminexus JMSプロバイダサービスインスタンスの削除

付録E.1　すべてのユースケースに共通の前提条件

すべてのユースケースに共通の前提条件を次に示します。

Cosminexus JMSプロバイダに関連するコマンドの操作でユーザ確認をしないで強制的に実行したい場合，cjmsbrokerコマンドの場合は-forceオプション，cjmsicmdコマンドの場合は-fオプションを指定してください。

Cosminexus JMSプロバイダに関連するコマンドの操作はCJMSPブローカーが起動しているマシンで実行してください。

Cosminexus JMSプロバイダを使用する場合には，ユーザ権限にAdministrator権限が必要となります。

Cosminexus JMSプロバイダに関連するコマンドの操作は複数同時に実行しないでください。

Cosminexus JMSプロバイダのコマンドラインツール（cjmsbroker，cjmsicmd）に関するヘルプを表示するには，-hオプションまたは-helpオプションを指定してください。

J2EEサーバの起動オプションはセキュリティマネージャを使用しない設定にしてください。使用するに設定した場合，CJMSPリソースアダプタからリソースアクセスした際に権限不正のエラーが発生します。

J2EEサーバで使用するコマンドの操作でプロバイダURLを指定する場合は，次の例に従ってください。

実行形式

cjlistrar <サーバ名称> -nameserver <プロバイダURL>

実行例

cjlistrar MyServer -nameserver corbaname::localhost:900

<プロバイダURL>には，<プロトコル名称>::<ホスト名称>:<ポート番号>を指定します。

説明中に記述されているコマンドの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」を参照してください。

付録E.2　前提とするプロセスモデル

ユースケースが前提とするプロセスモデルを次の図に示します。

図E-1　ユースケースが前提とするプロセスモデル

一つのCJMSPブローカーに対して，複数のJ2EEサーバからアクセスできます。

一つのJ2EEサーバに定義できるCJMSPリソースアダプタは一つとします。

付録E.3　Cosminexus JMSプロバイダを使用する場合の環境構築

Cosminexus JMSプロバイダを使用する場合の環境構築手順を次の図に示します。

図E-2　Cosminexus JMSプロバイダを使用する場合の環境構築手順

＜この項の構成＞

(1)　前提条件

(2)　プロセス前提条件

(3)　実行に必要な情報および補足説明

(1)　前提条件

運用管理ポータル（Management Server）によって，CosminexusのインストールおよびJ2EEサーバの構築が完了していること。

Cosminexus JMSプロバイダは，アプリケーションサーバのインストール完了後，次のディレクトリにインストールされていること。

<COSMINEXUS_HOME>/CC/cjmsp

手順実行前に，このディレクトリがあることを確認してください。

(2)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが未起動（インポートされていない状態）であること。

CJMSPブローカープロセスが未起動であること。

アプリケーションが未起動（インポートされていない状態）であること。

(3)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

<インスタンス名>

省略した場合は，デフォルトで「cjmsbroker」を使用します。

複数インスタンスを使用したい場合には名称が重ならないように注意する必要があります。重なる場合には-nameオプションを指定し，存在しない任意の名称を付与してください。

(A2)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略可能です。

CJMSPブローカーの状態が「OPERATING」であることを必ず確認してください。

注意

CJMSPブローカーが正常に起動されていない状態でCJMSPリソースアダプタを開始すると，例外が発生してCosminexus JMSプロバイダを使用することができません。

(A3)

<Queue名>，<Topic名>

Queue名またはTopic名

<最大メッセージ数>

QueueまたはTopicに格納できる最大メッセージ数

<メッセージトータルバイト数>

QueueまたはTopicの最大トータルメッセージバイト数

<最大プロデューサー数>

送信先の最大プロデューサー数

<最大コンシューマーフローリミット数>

一つの処理単位でコンシューマーに配送可能な最大メッセージ数

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略可能です。

(A4)

<Queue名>，<Topic名>

Queue名またはTopic名

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略可能です。

(A3)で作成した送信先が，指定したプロパティで正しく作られていることを確認してください。(A3)で指定した各引数と，表示内容の対応は次のとおりです。

maxNumMsgs → Max Number of Messages

maxNumProducers → Max Number of Producers

maxTotalMsgBytes → Max Total Message Bytes

consumerFlowLimit → Consumer Flow Limit

プロパティの表示例を次に示します。この例は，Queueを作成した場合の実行例です。

Destination Name                      TestQueue
Destination Type                      Queue
Destination State                     RUNNING
Created Administratively              true

Current Number of Messages
   Actual                            0
   Held in Transaction               0
Current Message Bytes
   Actual                            0
   Held in Transaction               0
Current Number of Producers           0
Current Number of Active Consumers    0

Max Number of Messages                unlimited (-1)
Max Total Message Bytes               unlimited (-1)
Max Number of Producers               unlimited (-1)

Consumer Flow Limit                   100

KDAN34151-I Successfully queried the destination.

(A5)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSP_HOME>

<Cosminexusのインストールディレクトリ>/CC/cjmsp

(A6)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタ表示名>

CJMSPリソースアダプタの表示名

Cosminexus JMSプロバイダの場合は，デフォルトで「Cosminexus_JMS_Provider_RA」が設定されています。

(A7)

Connector属性ファイルは，テンプレートファイルをコピーして編集します。テンプレートファイルは，<CJMSP_HOME>/lib/templates/Cosminexus_JMS_Provider_RA_cfg.xmlを使用します。

送信先を使用するため，CJMSPリソースアダプタが提供する管理対象オブジェクトについての定義を行います。

設定例を次に示します。番号を振っているタグを指定してください（番号は実際の定義には含まれません）。

   <config-property>
     <description xml:lang="en"></description>
     <config-property-name>ConnectionURL</config-property-name>
     <config-property-type>java.lang.String</config-property-type>
(1)    <config-property-value>mq://localhost:7676/</config-property-value>
   </config-property>

    <config-property>
         <description xml:lang="en"></description>
         <config-property-name>clientId</config-property-name>
         <config-property-type>java.lang.String</config-property-type>
(2)      <config-property-value>Test</config-property-value>
    </config-property>

   <adminobject>
(3)  <adminobject-name>myQueue</adminobject-name>
(4)  <adminobject-interface>javax.jms.Queue</adminobject-interface>
(5)  <adminobject-class>com.cosminexus.jmsprovider.messaging.Queue</adminobject-class>
     <config-property>
       <description xml:lang="en"></description>
       <config-property-name>Name</config-property-name>
       <config-property-type>java.lang.String</config-property-type>
(6)    <config-property-value>TestQueue</config-property-value>
     </config-property>
     <config-property>
       <description xml:lang="en"></description>
       <config-property-name>Description</config-property-name>
       <config-property-type>java.lang.String</config-property-type>
       <config-property-value></config-property-value>
     </config-property>
   </adminobject>

各番号の指定内容を示します。

CJMSPブローカーを起動するホスト名およびポート番号を指定します。

クライアント識別子を指定します。永続化サブスクライバーを使用する場合に必要になります。

<adminobject-name>に管理対象オブジェクト名を指定します。CJMSPリソースアダプタ内でユニークである必要があります。

<adminobject-interface>に管理対象オブジェクトのクラスが実装するインタフェースを指定します。
Queueを使用する場合は，javax.jms.Queueを設定します。
Topicを使用する場合は，javax.jms.Topicを設定します。

<adminobject-class>に管理対象オブジェクトのクラスを設定します。
Queueを使用する場合は，com.cosminexus.jmsprovider.messaging.Queueを設定します。
Topicを使用する場合は，com.cosminexus.jmsprovider.messaging.Topicを設定します。

(A3)で指定した送信先の名前を設定します。

使用する送信先数分，<adminobject>タグを作成します。

注意

Message-driven Beanを使用する場合は，次の2点を設定してください。

次に示す(a)の値が(b)の値以上になるように設定してください。

デプロイしているすべてのMessage-driven Beanの(a)の合計数の値が，次に示す(c)の値以下になるように設定してください

アプリケーションプロパティファイルのMessage-driven Beanのインスタンスプール最大数
<pooled-instance>
<minimum>1</minimum>
(a) <maximum>2</maximum>
</pooled-instance>

アプリケーションプロパティファイルのEndpointのインスタンスプール最大数
<activation-config-property>
<activation-config-property-name>endpointPoolMaxSize</activation-config-property-name>
(b) <activation-config-property-value>1</activation-config-property-value>
</activation-config-property>

CJMSPリソースアダプタのConnector属性ファイルのWorkManagerのスレッドプール最大数
<property>
<property-name>MaxTPoolSize</property-name>
<property-type>int</property-type>
(c) <property-value>10</property-value>
<property-default-value>10</property-default-value>
</property>

(A8)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタ表示名>

CJMSPリソースアダプタの表示名

Cosminexus JMSプロバイダの場合は，デフォルトで「Cosminexus_JMS_Provider_RA」が設定されています。

<Connector属性ファイルパス>

属性ファイルの入力元パス

(A9)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタ表示名>

CJMSPリソースアダプタの表示名

Cosminexus JMSプロバイダの場合は，デフォルトで「Cosminexus_JMS_Provider_RA」が設定されています。

CJMSPリソースアダプタの接続テストでは，次の2点を確認しています。

動作モードが1.4モードであること。

CJMSPブローカーとの接続を確立できること。

(A10)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタ表示名>

CJMSPリソースアダプタの表示名

Cosminexus JMSプロバイダの場合は，デフォルトでCosminexus_JMS_Provider_RAが設定されています。

(A11)

<サーバ名>

Management Serverで構築したサーバ名

「running <CJMSPリソースアダプタ表示名>」と表示されていることを確認します。

(A12)

アプリケーションのプロパティに，CJMSPリソースアダプタのコネクションファクトリ，管理対象オブジェクトを関連づける設定をします。

設定例を次に示します。番号を振っているタグを編集してください（番号は実際の定義には含まれません）。

  <resource-ref>
(1)  <res-ref-name>jms/qcf</res-ref-name>
(2)  <res-type>javax.jms.QueueConnectionFactory</res-type>
(3)  <res-auth>Container</res-auth>
(4)  <res-sharing-scope>Unshareable</res-sharing-scope>
(5)  <linked-to>Cosminexus_JMS_Provider_RA!javax.jms.QueueConnectionFactory</linked-to>
  </resource-ref>
  <resource-env-ref>
(6)  <resource-env-ref-name>jms/TestQueue</resource-env-ref-name>
(7)  <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
       <linked-adminobject>
(8)  <resourceadapter-name>Cosminexus_JMS_Provider_RA</resourceadapter-name>
(9)  <adminobject-name>myQueue</adminobject-name>
       </linked-adminobject>
  </resource-env-ref>

各番号の指定内容を示します。

<res-ref-name>にリソース参照の名称を指定します。

<res-type>にリソース参照のタイプを指定します。コネクションファクトリの種類を指定します。

<res-auth>にリソースを使用するための認証をアプリケーション上で行うか，コンテナに任せるかを指定します。指定できる文字列を次に示します。
Application
Container

<res-sharing-scope>にリソース接続を共有するかどうかを指定します。指定できる文字列を次に示します。
Shareable
Unshareable

<linked-to>に対応するCJMSPリソースアダプタの表示名を指定します。次の文字列を指定します。
<CJMSPリソースアダプタ表示名>!<コネクション定義識別子>

<resource-env-ref-name>にリソース環境変数参照の名称を指定します。

<resource-env-ref-type>に管理対象オブジェクトの型として，送信先のインタフェースの種類を指定します。

<resourceadapter-name>にCJMSPリソースアダプタの表示名を指定します。

<adminobject-name>に(A7)の(3)で設定した，管理対象オブジェクト名を指定します。

(A13)

特にありません。

(A14)

特にありません。

付録E.4　Cosminexus JMSプロバイダを使用するアプリケーションの追加

稼働中のシステムに対して新規にアプリケーションを追加する場合の手順を次の図に示します。

図E-3　稼働中のシステムに対して新規にアプリケーションを追加する手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが未起動（インポートされていない状態）であること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

運用管理ポータル（Management Server）機能でアプリケーションを停止します。

(A2)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタ表示名>

CJMSPリソースアダプタの表示名

Cosminexus JMSプロバイダの場合は，デフォルトで「Cosminexus_JMS_Provider_RA」が設定されています。

(A3)

Connector属性ファイルは，テンプレートファイルをコピーし，編集します。

テンプレートファイルは，<CJMSP_HOME>/lib/templates/Cosminexus_JMS_Provider_RA_cfg.xmlを使用します。

送信先を使用するため，CJMSPリソースアダプタが提供する管理対象オブジェクトについての定義を行います。

設定例を次に示します。番号を振っているタグを指定してください（番号は実際の定義には含まれません）。

   <config-property>
     <description xml:lang="en"></description>
     <config-property-name>ConnectionURL</config-property-name>
     <config-property-type>java.lang.String</config-property-type>
(1)   <config-property-value>mq://localhost:7676/</config-property-value>
   </config-property>
    <config-property>
         <description xml:lang="en"></description>
         <config-property-name>clientId</config-property-name>
         <config-property-type>java.lang.String</config-property-type>
(2)   <config-property-value>Test</config-property-value>
   </config-property>

  <adminobject>
(3)    <adminobject-name>myQueue</adminobject-name>
(4)    <adminobject-interface>javax.jms.Queue</adminobject-interface>
(5)    <adminobject-class>com.cosminexus.jmsprovider.messaging.Queue</adminobject-class>
   <config-property>
     <description xml:lang="en"></description>
     <config-property-name>Name</config-property-name>
     <config-property-type>java.lang.String</config-property-type>
(6)    <config-property-value>TestQueue</config-property-value>
   </config-property>
   <config-property>
    <description xml:lang="en"></description>
    <config-property-name>Description</config-property-name>
    <config-property-type>java.lang.String</config-property-type>
   <config-property-value></config-property-value>
   </config-property>
  </adminobject>

各番号の指定内容を示します。

CJMSPブローカーを起動するホスト名およびポート番号を指定します。

クライアント識別子を指定します。永続化サブスクライバーを使用する場合に必要になります。

<adminobject-name>に管理対象オブジェクト名を指定します。CJMSPリソースアダプタ内でユニークである必要があります。

<adminobject-interface>に管理対象オブジェクトのクラスが実装するインタフェースを指定します。
Queueを使用する場合は，javax.jms.Queueを設定します。
Topicを使用する場合は，javax.jms.Topicを設定します。

<adminobject-class>に管理対象オブジェクトのクラスを設定します。
Queueを使用する場合は，com.cosminexus.jmsprovider.messaging.Queueを設定します。
Topicを使用する場合は，com.cosminexus.jmsprovider.messaging.Topicを設定します。

送信先の名前を設定します。
使用する送信先数分，<adminobject>タグを作成します。

注意

Message-driven Beanを使用する場合は下記の2点を設定してください。

次に示す(a)の値が(b)の値以上になるように設定してください。

デプロイしているすべてのMessage-driven Beanの(a)の合計数の値が，次に示す(c)の値以下になるように設定してください

アプリケーションプロパティファイルのMessage-driven Beanのインスタンスプール最大数
<pooled-instance>
<minimum>1</minimum>
(a) <maximum>2</maximum>
</pooled-instance>

アプリケーションプロパティファイルのEndpointのインスタンスプール最大数
<activation-config-property>
<activation-config-property-name>endpointPoolMaxSize</activation-config-property-name>
(b) <activation-config-property-value>1</activation-config-property-value>
</activation-config-property>

CJMSPリソースアダプタのConnector属性ファイルのWorkManagerのスレッドプール最大数
<property>
<property-name>MaxTPoolSize</property-name>
<property-type>int</property-type>
(c) <property-value>10</property-value>
<property-default-value>10</property-default-value>
</property>

(A4)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタ表示名>

CJMSPリソースアダプタの表示名

Cosminexus JMSプロバイダの場合は，デフォルトで「Cosminexus_JMS_Provider_RA」が設定されています。

<Connector属性ファイルパス>

属性ファイルの入力元パス

(A5)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタ表示名>

CJMSPリソースアダプタの表示名

Cosminexus JMSプロバイダの場合は，デフォルトで「Cosminexus_JMS_Provider_RA」が設定されています。

CJMSPリソースアダプタの接続テストでは，次の2点を確認しています。

動作モードが1.4モードであること。

CJMSPブローカーとの接続を確立できること。

(A6)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタ表示名>

CJMSPリソースアダプタの表示名

Cosminexus JMSプロバイダの場合は，デフォルトで「Cosminexus_JMS_Provider_RA」が設定されています。

(A7)

<Queue名>，<Topic名>

Queue名またはTopic名

<最大メッセージ数>

QueueまたはTopicに格納できる最大メッセージ数

<メッセージトータルバイト数>

QueueまたはTopicの最大トータルメッセージバイト数

<最大プロデューサー数>

送信先の最大プロデューサー数

<最大コンシューマーフローリミット数>

一つの処理単位でコンシューマーに配送できる最大メッセージ数

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

<Queue名> または<Topic名>には，(A3)の(6)で設定した，送信先の名前を入力する。

(A8)

<Queue名>，<Topic名>

Queue名またはTopic名

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A7)で作成した送信先が指定したプロパティで正しく作られていることを確認してください。(A7)で指定した各引数と，表示内容の対応は次のとおりです。

maxNumMsgs → Max Number of Messages

maxNumProducers → Max Number of Producers

maxTotalMsgBytes → Max Total Message Bytes

consumerFlowLimit → Consumer Flow Limit

指定したプロパティは次の表示で出力されます。この例は，Queueを作成した場合の実行例です。

Destination Name                      TestQueue
Destination Type                      Queue
Destination State                     RUNNING
Created Administratively              true

Current Number of Messages
   Actual                            0
   Held in Transaction               0
Current Message Bytes
   Actual                            0
   Held in Transaction               0
Current Number of Producers           0
Current Number of Active Consumers    0

Max Number of Messages                unlimited (-1)
Max Total Message Bytes               unlimited (-1)
Max Number of Producers               unlimited (-1)

Consumer Flow Limit                   100

KDAN34151-I Successfully queried the destination.

(A9)

アプリケーションのプロパティに，CJMSPリソースアダプタのコネクションファクトリ，管理対象オブジェクトを関連づける設定をします。

設定例を次に示します。番号を振っているタグを指定してください（番号は実際の定義には含まれません）。

  <resource-ref>
(1)     <res-ref-name>jms/qcf</res-ref-name>
(2)     <res-type>javax.jms.QueueConnectionFactory</res-type>
(3)     <res-auth>Container</res-auth>
(4)     <res-sharing-scope>Unshareable</res-sharing-scope>
(5)     <linked-to>Cosminexus_JMS_Provider_RA!javax.jms.QueueConnectionFactory</linked-to>
  </resource-ref>
  <resource-env-ref>
(6)     <resource-env-ref-name>jms/TestQueue</resource-env-ref-name>
(7)     <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
       <linked-adminobject>
(8)       <resourceadapter-name>Cosminexus_JMS_Provider_RA</resourceadapter-name>
(9)       <adminobject-name>myQueue</adminobject-name>
       </linked-adminobject>
  </resource-env-ref>

各番号の指定内容を示します。

<res-ref-name>にリソース参照の名称を指定します。

<res-type>にリソース参照のタイプを指定します。コネクションファクトリの種類を指定します。

<res-auth>にリソースを使用するための認証元を，アプリケーション上で行うか，コンテナに任せるかを指定します。
指定できる文字列を次に示します。
Application
Container

<res-sharing-scope>にリソース接続を共有するかどうかを指定します。
指定できる文字列を次に示します。
Shareable
Unshareable

<linked-to>に対応するCJMSPリソースアダプタ表示名を指定します。
次の文字列を指定します。
<CJMSPリソースアダプタ表示名>!<コネクション定義識別子>

<resource-env-ref-name>にリソース環境変数参照の名称を指定します。

<resource-env-ref-type>に管理対象オブジェクトの型をします。送信先のインタフェースの種類を指定します。

<resourceadapter-name>にCJMSPリソースアダプタの表示名を指定します。

<adminobject-name>に(A3)の(3)で設定した，管理対象オブジェクト名を指定します。

(A10)

特にありません。

(A11)

特にありません。

付録E.5　Cosminexus JMSプロバイダを使用するアプリケーションの削除

稼働中のシステムからアプリケーションを削除する場合の手順を次の図に示します。

図E-4　稼働中のシステムからアプリケーションを削除する場合の手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

特にありません。

(A2)

運用管理ポータル（Management Server）機能によってアプリケーションを削除します。

(A3)

<種別>

q(Queue)またはt(Topic)

<送信先名>

Queue名またはTopic名

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A4)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A3)で削除した送信先が正しく削除されていることを確認してください。

(A5)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタ表示名>

CJMSPリソースアダプタの表示名

Cosminexus JMSプロバイダの場合は，デフォルトで「Cosminexus_JMS_Provider_RA」が設定されています。

(A6)

特にありません。

(A7)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタの表示名>

CJMSPリソースアダプタ表示名

Cosminexus JMSプロバイダの場合は，デフォルトで「Cosminexus_JMS_Provider_RA」が設定されています。

(A8)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタ表示名>

CJMSPリソースアダプタの表示名

Cosminexus JMSプロバイダの場合は，デフォルトで「Cosminexus_JMS_Provider_RA」が設定されています。

付録E.6　Cosminexus JMSプロバイダサービスの開始（初回起動時）

システム構築直後など，初回起動時にCosminexus JMSプロバイダのサービスを起動する手順について説明します。この手順で開始した場合は，「付録E.11　Cosminexus JMSプロバイダサービスの終了」で終了できます。

この手順に従って，CJMSPリソースアダプタの起動とアプリケーションの起動をした場合，J2EEサーバを再起動したときにはCJMSPリソースアダプタおよびアプリケーションはどちらも起動状態となります（ただし，前提条件としてCJMSPブローカーが先に起動されていることが必須条件となります）。

Cosminexus JMSプロバイダサービスの開始手順（初回起動時）を次の図に示します。

図E-5　Cosminexus JMSプロバイダサービスの開始手順（初回起動時）

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが未起動であること。

CJMSPブローカープロセスが未起動であること。

アプリケーションが未起動であること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

管理コマンドプロパティファイルは，<CJMSP_HOME>/var/admin/config/admin.propertiesに格納されています。

設定できるプロパティ名と説明を次に記述します。ファイルの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「7.2　admin.properties（管理コマンドプロパティファイル）」を参照してください。

admin.logger.MessageLogFile.trace.level

管理コマンドのメッセージログレベルを指定します。

admin.logger.MessageLogFile.filepath

管理コマンドのメッセージログを出力するファイルパスを指定します。

admin.logger.MessageLogFile.filenum

管理コマンドで作成される最大メッセージログファイル数を指定します。

admin.logger.MessageLogFile.filesize

管理コマンドのメッセージログファイルの最大サイズを指定します。

admin.logger.ExceptionLogFile.filepath

管理コマンドの例外ログを出力するファイルパスを指定します。

admin.logger.ExceptionLogFile.filenum

管理コマンドで作成される最大例外ログファイル数を指定します。

admin.logger.ExceptionLogFile.filesize

管理コマンドの例外ログファイルの最大サイズを指定します。

(A2)

<インスタンス名>

省略した場合は，デフォルトで「cjmsbroker」を使用します。

複数インスタンスを使用したい場合には名称が重ならないように注意する必要があります。

重なる場合には-nameオプションを指定し存在しない任意の名称を付与してください。

<ディレクトリパス>

VAR_HOMEを出力したいパスを指定します。

モードによるオプションの違い

通常モード
オプション指定は行いません（状態をリセットしないで，継続状態でCosminexus JMSプロバイダのサービスを起動します）。

永続データストアリセットモード
永続化メッセージ，永続化サブスクライバーが消去されます。

永続メッセージクリアモード
すべての永続化メッセージが消去されます。

永続サブスクリプションクリアモード
すべての永続化サブスクライバーが消去されます。

(A3)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号を指定します。

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A4)

CJMSPブローカープロパティファイルは，<VAR_HOME>/instances/<インスタンス名>/props/config.propertiesに格納されています。

このファイルは初めてCJMSPブローカーを起動した時に作成されます。そのため，(A2)(A3)の手順が必要になります。

設定できるプロパティ名と説明を次に記述します。ファイルの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「7.4　config.properties（CJMSPブローカー個別プロパティファイル）」を参照してください。

一時送信先を作成した場合，imq.autocreate.queue.consumerFlowLimitまたはimq.autocreate.topic.consumerFlowLimitの値が送信先のプロパティとして設定されます。

imq.hostname

すべての接続サービスのデフォルトのホスト名，またはIPアドレスを指定します。

imq.portmapper.port

CJMSPブローカーのポートマッパー用のポート番号を指定します。

imq.jms.tcp.port

jmsサービスのポート番号を指定します。

imq.admin.tcp.port

adminサービスのポート番号を指定します。

imq.persist.file.sync.enabled

ディスク書き込み操作を同期にするか，または非同期にするかのフラグを指定します。

imq.autocreate.queue.consumerFlowLimit

一つの処理単位でQueueのコンシューマーに配送可能な最大メッセージ数を指定します。

imq.autocreate.topic.consumerFlowLimit

一つの処理単位でTopicのコンシューマーに配送可能な最大メッセージ数を指定します。

imq.metrics.interval

メトリクス情報をログとコンソールに出力する時間間隔を秒単位で指定します。

broker.logger.MessageLogFile.trace.level

CJMSPブローカーのメッセージログレベルを指定します。

broker.logger.MessageLogFile.filenum

CJMSPブローカーで作成される最大メッセージログファイル数を指定します。

broker.logger.MessageLogFile.filesize

CJMSPブローカーのメッセージログファイルの最大サイズを指定します。

broker.logger.ExceptionLogFile.filenum

CJMSPブローカーで作成される最大例外ログファイル数を指定します。

broker.logger.ExceptionLogFile.filesize

CJMSPブローカーの例外ログファイルの最大サイズを指定します。

imq.instanceconfig.version

コンフィグプロパティのバージョンを指定します。

(A5)

<インスタンス名>

省略した場合は，デフォルトで「cjmsbroker」を使用します。

複数インスタンスを使用したい場合には名称が重ならないように注意する必要があります。

重なる場合には-nameオプションを指定し存在しない任意の名称を付与してください。

<ディレクトリパス>

VAR_HOMEを出力したいパスを指定します。

<引数>

-Xms（最大ヒープサイズ），-Xmx（最小ヒープサイズ），-XX:+HitachiVerboseGC（ガーベージコレクションが発生したときの拡張verbosegc情報を出力するオプション）などJavaVMオプションを指定します。

(A6)

Stateが「OPERATING」であることを確認します。

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A7)

<サーバ名>

Management Serverで構築したサーバ名

(A8)

特にありません。

付録E.7　Cosminexus JMSプロバイダサービスの開始（稼働中システムの再起動時）

稼働中システムの再起動時にCosminexus JMSプロバイダのサービスを起動する手順について説明します。この手順で開始した場合は，「付録E.11　Cosminexus JMSプロバイダサービスの終了」で終了できます。

Cosminexus JMSプロバイダサービスの開始手順（稼働中システムの再起動時）を次の図に示します。

図E-6　Cosminexus JMSプロバイダサービスの開始手順（稼働中システムの再起動時）

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが未起動であること。

CJMSPリソースアダプタが未起動であること。

CJMSPブローカープロセスが未起動であること。

アプリケーションが未起動であること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

管理コマンドプロパティファイルは，<CJMSP_HOME>/var/admin/config/admin.propertiesに格納されています。

設定できるプロパティ名と説明を次に記述します。ファイルの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「7.2　admin.properties（管理コマンドプロパティファイル）」を参照してください。

admin.logger.MessageLogFile.trace.level

管理コマンドのメッセージログレベルを指定します。

admin.logger.MessageLogFile.filepath

管理コマンドのメッセージログを出力するファイルパスを指定します。

admin.logger.MessageLogFile.filenum

管理コマンドで作成される最大メッセージログファイル数を指定します。

admin.logger.MessageLogFile.filesize

管理コマンドのメッセージログファイルの最大サイズを指定します。

admin.logger.ExceptionLogFile.filepath

管理コマンドの例外ログを出力するファイルパスを指定します。

admin.logger.ExceptionLogFile.filenum

管理コマンドで作成される最大例外ログファイル数を指定します。

admin.logger.ExceptionLogFile.filesize

管理コマンドの例外ログファイルの最大サイズを指定します。

(A2)

CJMSPブローカーのプロパティファイルは，<VAR_HOME>/instances/<インスタンス名>/props/config.propertiesに格納されています。

設定できるプロパティ名と説明を次に記述します。ファイルの詳細については，マニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「7.4　config.properties（CJMSPブローカー個別プロパティファイル）」を参照してください。

一時送信先を作成した場合，imq.autocreate.queue.consumerFlowLimitまたはimq.autocreate.topic.consumerFlowLimitの値が送信先のプロパティとして設定されます。

imq.hostname

すべての接続サービスのデフォルトのホスト名，またはIPアドレスを指定します。

imq.portmapper.port

CJMSPブローカーのポートマッパー用のポート番号を指定します。

imq.jms.tcp.port

jmsサービスのポート番号を指定します。

imq.admin.tcp.port

adminサービスのポート番号を指定します。

imq.persist.file.sync.enabled

ディスク書き込み操作を同期にするか，または非同期にするかのフラグを指定します。

imq.autocreate.queue.consumerFlowLimit

一つの処理単位でQueueのコンシューマーに配送可能な最大メッセージ数を指定します。

imq.autocreate.topic.consumerFlowLimit

一つの処理単位でTopicのコンシューマーに配送可能な最大メッセージ数を指定します。

imq.metrics.interval

メトリクス情報をログとコンソールに出力する時間間隔を秒単位で指定します。

broker.logger.MessageLogFile.trace.level

CJMSPブローカーのメッセージログレベルを指定します。

broker.logger.MessageLogFile.filenum

CJMSPブローカーで作成される最大メッセージログファイル数を指定します。

broker.logger.MessageLogFile.filesize

CJMSPブローカーのメッセージログファイルの最大サイズを指定します。

broker.logger.ExceptionLogFile.filenum

CJMSPブローカーで作成される最大例外ログファイル数を指定します。

broker.logger.ExceptionLogFile.filesize

CJMSPブローカーの例外ログファイルの最大サイズを指定します。

imq.instanceconfig.version

コンフィグプロパティのバージョンを指定します。

(A3)

<インスタンス名>

省略した場合は，デフォルトで「cjmsbroker」を使用します。

複数インスタンスを使用したい場合には名称が重ならないように注意する必要があります。

重なる場合には-nameオプションを指定し存在しない任意の名称を付与してください。

<ディレクトリパス>

VAR_HOMEを出力したいパスを指定します。

<引数>

-Xms（最大ヒープサイズ），-Xmx（最小ヒープサイズ），-XX:+HitachiVerboseGC（ガーベージコレクションが発生したときの拡張verbosegc情報を出力するオプション）などJavaVMのオプションを指定します。

モードによるオプションの違い

通常モード
オプション指定は行いません（状態をリセットしないで，継続状態でCosminexus JMSプロバイダのサービスを起動します）。

永続データストアリセットモード
永続化メッセージ，永続化サブスクライバーが消去されます。

永続メッセージクリアモード
すべての永続化メッセージが消去されます。

永続サブスクリプションクリアモード
すべての永続化サブスクライバーが消去されます。

(A4)

Stateが「OPERATING」であることを確認します。

(A5)

運用管理ポータル（Management Server）機能によってJ2EEサーバを起動します。

CJMSPリソースアダプタとアプリケーションはJ2EEサーバ起動時に開始されます。

付録E.8　CJMSPリソースアダプタとCJMSPブローカーの状態確認

Cosminexus JMSプロバイダのサービスが使用できる状態であるかどうかを確認する手順について説明します。

J2EEサーバとアプリケーションの状態については運用管理ポータル（Management Server）機能で確認してください。

CJMSPリソースアダプタとCJMSPブローカーの状態確認手順を次の図に示します。

図E-7　CJMSPリソースアダプタとCJMSPブローカーの状態確認手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A2)

<サーバ名>

Management Serverで構築したサーバ名

CJMSPサービス起動状態

CJMSPブローカーが「OPERATING」かつCJMSPリソースアダプタが「running」の場合にCosminexus JMSプロバイダのサービスは開始されている状態です。

(A1)の結果例を次に示します。

----------------------
Address       State
----------------------
localhost:7676   OPERATING

(A2)の結果例を次に示します。

running Cosminexus_JMS_Provider_RA

付録E.9　メッセージ配信状況の確認と滞留時の対処（CJMSPブローカーを一時停止する方法）

Cosminexus JMSプロバイダのメッセージ配信状況を確認するとともに，メッセージが滞留していた場合は対処する手順について説明します。

この方法では，CJMSPブローカーの一時停止後にアプリケーションでタイムアウトが発生することによって例外が発生する場合があります。

安全にメッセージを削除したい場合は，「付録E.10　メッセージ配信状況の確認と滞留時の対処（アプリケーションを停止する方法）」を参照してください。

メッセージ配信状況の確認と滞留時の対処手順（CJMSPブローカーを一時停止する方法）を次の図に示します。

図E-8　メッセージ配信状況の確認と滞留時の対処手順（CJMSPブローカーを一時停止する方法）

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

送信先（または永続化サブスクライバー）名とメッセージ数を確認します。

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

<Topic名>

確認しようとしている永続化サブスクライバーが存在するTopic名

(A2)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A3)

jmsサービスが「PAUSED」の状態になっているか確認します。

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

出力例を次に示します。

-----------------------------------------------
Service Name    Port Number       Service State
-----------------------------------------------
admin           1248 (dynamic)         RUNNING
jms                0 (dynamic)         PAUSED

KDAN34113-I Successfully listed services.

(A4)

<種別>

q(Queue)またはt(Topic)

<名称>

Queue名またはTopic名

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

<初期タイムアウト値>

デフォルトの初期タイムアウト値は10秒に設定されています。デフォルト値で処理がタイムアウトしてしまう場合には値を調節してください。

<永続化サブスクライバー名>

(A1)で確認した永続化サブスクライバー名

<クライアントID>

(A1)で確認したクライアントID

(A5)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A6)

jmsサービスが「RUNNING」の状態になっているかを確認します。

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

出力例を次に示します。

-----------------------------------------------
Service Name    Port Number       Service State
-----------------------------------------------
admin           1248 (dynamic)         RUNNING
jms             1337 (dynamic)         RUNNING

KDAN34113-I Successfully listed services.

付録E.10　メッセージ配信状況の確認と滞留時の対処（アプリケーションを停止する方法）

Cosminexus JMSプロバイダのメッセージ配信状況を確認するとともに，メッセージが滞留していた場合に対処する手順について説明します。

アプリケーションを停止したくない場合は，「付録E.9　メッセージ配信状況の確認と滞留時の対処（CJMSPブローカーを一時停止する方法）」を参照してください。

メッセージ配信状況の確認と滞留時の対処手順（アプリケーションを停止する方法）を次の図に示します。

図E-9　メッセージ配信状況の確認と滞留時の対処手順（アプリケーションを停止する方法）

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

送信先（または永続化サブスクライバー）名とメッセージ数を確認します。

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

<Topic名>

確認しようとしている永続化サブスクライバーが存在するTopic名

(A2)

特にありません。

(A3)

<種別>

q(Queue)またはt(Topic)

<名称>

Queue名またはTopic名

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

<初期タイムアウト値>

デフォルトの初期タイムアウト値は10秒に設定されています。デフォルト値で処理がタイムアウトしてしまう場合には値を調節してください。

<永続化サブスクライバー名>

(A1)で確認した永続化サブスクライバー名

<クライアントID>

(A1)で確認したクライアントID

付録E.11　Cosminexus JMSプロバイダサービスの終了

Cosminexus JMSプロバイダのサービスの終了の手順について説明します。

この手順で停止した場合は，「付録E.7　Cosminexus JMSプロバイダサービスの開始（稼働中システムの再起動時）」の手順によって再起動できます。

Cosminexus JMSプロバイダのサービスの終了手順を次の図に示します。

図E-10　Cosminexus JMSプロバイダのサービスの終了手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

特にありません。

(A2)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

付録E.12　送信先の圧縮

Cosminexus JMSプロバイダで使用する送信先の圧縮手順について説明します。

送信先の圧縮手順を次の図に示します。

図E-11　送信先の圧縮手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

送信先名とメッセージ数を確認します。

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A2)

特にありません。

(A3)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A4)

<種別>

q(Queue)またはt(Topic)

<名称>

Queue名またはTopic名

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

<初期タイムアウト値>

デフォルトの初期タイムアウト値は10秒に設定されています。デフォルト値で処理がタイムアウトしてしまう場合には値を調節してください。

(A5)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

付録E.13　送信先サイズの変更

Cosminexus JMSプロバイダで使用する送信先のサイズ変更手順について説明します。

送信先サイズの変更手順を次の図に示します。

図E-12　送信先サイズの変更手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

特にありません。

(A2)

<種別>

q(Queue)またはt(Topic)

<送信先名>

削除するQueue名またはTopic名

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A3)

<種別>

q(Queue)またはt(Topic)

<送信先名>

再作成するQueue名またはTopic名

<最大メッセージ数>

QueueまたはTopicに格納される最大メッセージ数

<メッセージトータルバイト数>

QueueまたはTopicに格納されるメッセージのトータルバイト数

<最大プロデューサー数>

送信先の最大プロデューサー数

<最大コンシューマーフローリミット数>

一つの処理単位でコンシューマーに配送可能な最大メッセージ数

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

実行結果の例を示します。

例：メッセージ最大数を100000，メッセージのトータルバイト数を12メガバイト，最大プロデューサー数を1000，最大コンシューマーフローリミット数を1000でQueueを作成した場合の例

C:¥>cjmsicmd create dst -t q -n Queue1 -o "maxNumMsgs=100000" -o "maxTotalMsgBytes=12m" -o "maxNumProducers=1000" -o "consumerFlowLimit=1000" -b localhost:7676
KDAN34140-I Successfully created the destination.

(A4)

特にありません。

付録E.14　永続化サブスクライバーの削除

Cosminexus JMSプロバイダで使用する，永続化サブスクライバーの削除手順について説明します。

永続化サブスクライバーの削除手順を次の図に示します。

図E-13　永続化サブスクライバーの削除手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

<Topic名>

確認しようとしている永続化サブスクライバーが存在するTopic名

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

表示例を次に示します。

-----------------------------------------------------------------------
Durable Sub. Name   Client ID   Number of Messages   Durable Sub. State
-----------------------------------------------------------------------
DurableSUB1         clientId    9998                 INACTIVE
KDAN34323-I Successfully listed durable subscriptions.

(A2)

特にありません。

(A3)

<永続化サブスクライバー名>

(A1)で確認した永続化サブスクライバー名

<クライアントID>

(A1)で確認したクライアントID

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

付録E.15　CJMSPブローカーの状態監視

デバッグ，障害解析などによって，CJMSPブローカーを監視モードで起動する場合の手順について説明します。

この手順でCJMSPブローカーを再起動することによって，CJMSPブローカーを実行したコマンドプロンプト上にメトリクス情報が出力されます。

この監視状態を終了する場合には，「付録E.7　Cosminexus JMSプロバイダサービスの開始（稼働中システムの再起動時）」を参照して，通常モードでCJMSPブローカーを再起動してください。

CJMSPブローカーの状態監視手順を次の図に示します。

図E-14　CJMSPブローカーの状態監視手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

特にありません。

(A2)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A3)

CJMSPブローカーのプロパティファイルは，<VAR_HOME>/instances/<インスタンス名>/props/config.propertiesに格納されています。

状態監視モードでCJMSPブローカーを起動する場合は，次のプロパティを設定してください。

なお，詳細はマニュアル「Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「7.4　config.properties（CJMSPブローカー個別プロパティファイル）」を参照してください。

imq.metrics.interval

メトリクス情報をログとコンソールに出力する時間間隔を秒単位で指定します。

(A4)

<インスタンス名>

省略した場合は，デフォルトで「cjmsbroker」を使用します。

複数インスタンスを使用したい場合には，名称が重ならないように注意する必要があります。

重なる場合には，-nameオプションを指定し存在しない任意の名称を付与してください。

状態監視モードの表示例を次に示します。

Connections: 0    JVM Heap: 2932736 bytes (731352 free) Threads: 0 (14-1010)
     In: 0 msgs (0 bytes)  0 pkts (0 bytes)
    Out: 0 msgs (0 bytes)  0 pkts (0 bytes)
Rate In: 0 msgs/sec (0 bytes/sec)  0 pkts/sec (0 bytes/sec)
Rate Out: 0 msgs/sec (0 bytes/sec)  0 pkts/sec (0 bytes/sec)

(A5)

特にありません。

付録E.16　CJMSPブローカーの詳細情報確認

CJMSPブローカーの最新の詳細情報を確認する手順について，次の図に示します。

図E-15　CJMSPブローカーの詳細情報確認手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

表示例を次に示します。

Instance Name                                                                    cjmsbroker
Primary Port                                                                       7676
Broker is Embedded                                                            false
Instance Configuration/Data Root Directory                     D:¥Hitachi¥CC¥cjmsp¥var
Current Number of Messages in System                           843
Current Total Message Bytes in System                           177030
Current Number of Messages in Dead Message Queue    0
Current Total Message Bytes in Dead Message Queue     0
KDAN34295-I Successfully queried the broker.

付録E.17　送信先の状態確認

送信先の最新状態を確認する手順について，次の図に示します。

図E-16　送信先の状態確認手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略可能です。

-tmpオプションを使用すると，一時送信先の状態を確認できます。

一時送信先の状態の確認はアプリケーションを開始して，一時送信先が有効になっている期間だけ可能です。

-tmpオプション使用時の表示例を次に示します。

------------------------------------------------------------------------
  Name     Type    State   Producers  Consumers           Msgs
                                        Total    Count  UnAck  Avg Size
------------------------------------------------------------------------
Queue1         Queue  RUNNING  0          0          0      0      0.0
mq.sys.dmq  Queue  RUNNING  0          0          0      0      0.0
temporary_destination://queue/10.209.10.192/2139/1  Queue (temporary) 0          1          0      0      0.0
KDAN34110-I Successfully listed destinations.

付録E.18　永続化サブスクライバーの状態確認

永続化サブスクライバーの最新状態を確認する手順について，次の図に示します。

図E-17　永続化サブスクライバーの状態確認手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

<Topic名>

確認しようとしている永続化サブスクライバーが存在するTopic名

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

表示例を次に示します。

-----------------------------------------------------------------------
Durable Sub. Name   Client ID   Number of Messages   Durable Sub. State
-----------------------------------------------------------------------
DurableSUB1         clientId    9998                 INACTIVE
KDAN34323-I Successfully listed durable subscriptions.

付録E.19　CJMSPリソースアダプタに問題が発生した場合の解析

CJMSPリソースアダプタで問題が発生した状態からの解析手順について，次の図に示します。

図E-18　CJMSPリソースアダプタに問題が発生した場合の解析手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

<Cosminexusのインストールディレクトリ>/CC/server/public/ejb/<サーバ名>/logs/cjms/<コネクタ名>下のログを確認し，問題の解析を行います。

(A2)

「付録E.22　CJMSPリソースアダプタに問題が発生した場合の回復」の手順に従って，Cosminexus JMSプロバイダのサービスを回復してください。

付録E.20　CJMSPブローカーが障害によって停止したときの解析

CJMSPブローカーが障害によって停止した状態からの解析手順について，次の図に示します。

図E-19　CJMSPブローカーが障害によって停止した状態からの解析手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

<Cosminexusのインストールディレクトリ>/CC/cjmsp/var/instances/<インスタンス名>/log下のログを確認し，問題の解析を行います。

(A2)

「付録E.23　CJMSPブローカーが障害によって停止したときの回復」の手順に従って，Cosminexus JMSプロバイダのサービスを回復します。

付録E.21　Cosminexus JMSプロバイダサービス無応答時の解析

Cosminexus JMSプロバイダのサービス無応答時の解析手順を次の図に示します。

図E-20　Cosminexus JMSプロバイダサービス無応答時の解析手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

PRFトレースを採取します。

(A2)

J2EEサーバのスレッドダンプを採取します。

(A3)

<Cosminexusのインストールディレクトリ>/CC/server/public/ejb/<サーバ名>/logs下のログを確認し，障害を切り分けます。

(A4)

CJMSPブローカーのスレッドダンプを採取します。

Windowsの場合

CJMSPブローカーのスレッドダンプの取得方法は二つあります。

日立のJavaVMのコマンドjheapprofを使用します。
このコマンドの使用方法については，マニュアル「Cosminexus アプリケーションサーバ リファレンス コマンド編」の「jheapprof（日立クラス別統計情報付き拡張スレッドダンプの出力）」を参照してください。

CJMSPブローカーを起動しているコマンドプロンプト上で［Ctrl］+［Break］キーを入力します。
この場合，スレッドダンプを取得したあとにCJMSPブローカーを停止すると，「バッチジョブを終了しますか(Y/N)?」と表示されます。その際，「N」を指定してください。

UNIXの場合

killコマンドを使用します。

実行例

kill -3 <プロセスID>

(A5)

<Cosminexusのインストールディレクトリ>/CC/server/public/ejb/<サーバ名>/logs/cjms/<コネクタ名>下のログを確認して，障害を切り分けます。

(A6)

<VAR_HOME>/instances/<インスタンス名>/log下のログを確認して，障害を切り分けます。

(A7)

「付録E.24　Cosminexus JMSプロバイダサービス無応答時の回復」の手順に従って，Cosminexus JMSプロバイダのサービスを回復します。

付録E.22　CJMSPリソースアダプタに問題が発生した場合の回復

CJMSPリソースアダプタに問題が発生した場合の回復手順を次の図に示します。

図E-21　CJMSPリソースアダプタに問題が発生した場合の回復手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動中であること。

アプリケーションが未起動であること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

「付録E.19　CJMSPリソースアダプタに問題が発生した場合の解析」を参照して，障害を解析します。

(A2)

特にありません。

(A3)

特にありません。

(A4)

<サーバ名>

Management Serverで構築したサーバ名

「running <CJMSPリソースアダプタ表示名>」と表示されていることを確認します。

付録E.23　CJMSPブローカーが障害によって停止したときの回復

CJMSPブローカーが障害によって停止したときの回復手順を次の図に示します。

図E-22　CJMSPブローカーが障害によって停止したときの回復手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが未起動であること。

アプリケーションが起動済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

「付録E.20　CJMSPブローカーが障害によって停止したときの解析」を参照して，障害を解析します。

(A2)

特にありません。

(A3)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタ表示名>

CJMSPリソースアダプタの表示名

Cosminexus JMSプロバイダの場合は，デフォルトで「Cosminexus_JMS_Provider_RA」が設定されています。

(A4)

<インスタンス名>

省略した場合は，デフォルトで「cjmsbroker」を使用します。

複数インスタンスを使用したい場合には名称が重ならないように注意する必要があります。

重なる場合には-nameオプションを指定し存在しない任意の名称を付与してください。

(A5)

Stateが「OPERATING」であることを確認します。

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A6)

<サーバ名>

Management Serverで構築したサーバ名

<CJMSPリソースアダプタ表示名>

CJMSPリソースアダプタの表示名

Cosminexus JMSプロバイダの場合は，デフォルトで「Cosminexus_JMS_Provider_RA」が設定されています。

(A7)

<サーバ名>

Management Serverで構築したサーバ名

「running <CJMSPリソースアダプタ表示名>」と表示されていることを確認します。

(A8)

特にありません。

付録E.24　Cosminexus JMSプロバイダサービス無応答時の回復

Cosminexus JMSプロバイダのサービス無応答状態からの回復手順について説明します。

Cosminexus JMSプロバイダサービス無応答時の回復手順を次の図に示します。

図E-23　Cosminexus JMSプロバイダサービス無応答時の回復手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが起動済みであること。

CJMSPリソースアダプタが開始済みであること。

CJMSPブローカープロセスが起動済みであること。

アプリケーションが開始済みであること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

「付録E.21　Cosminexus JMSプロバイダサービス無応答時の解析」を参照して，障害を解析します。

(A2)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

(A3)

<インスタンス名>

省略した場合は，デフォルトで「cjmsbroker」を使用します。

複数インスタンスを使用したい場合には名称が重ならないように注意する必要があります。

重なる場合には-nameオプションを指定して存在しない任意の名称を付与してください。

(A4)

特にありません。

(A5)

<ホスト名>:<ポート番号>

CJMSPブローカーを起動しているホスト名およびポート番号

CJMSPブローカーの起動時にポート番号を省略した場合にはデフォルトの7676が使用されています。その場合，-bオプションの指定は省略できます。

Stateが「OPERATING」であることを確認します。

(A6)

<サーバ名>

Management Serverで構築したサーバ名

「running <CJMSPリソースアダプタ表示名>」と表示されていることを確認します。

付録E.25　Cosminexus JMSプロバイダサービスインスタンスの削除

Cosminexus JMSプロバイダのサービスの稼働中のインスタンスを削除する手順について説明します。

インスタンス名を変更したために以前のインスタンスが不要になった場合などに行います。

注意

この操作によって，送信先に存在するすべての情報が削除されます。

この操作を実行する前に，未処理の永続メッセージおよび永続サブスクライバーの情報が存在しないことを確認してください。

Cosminexus JMSプロバイダのサービスインスタンス削除手順を次の図に示します。

図E-24　Cosminexus JMSプロバイダのサービスインスタンス削除手順

＜この項の構成＞

(1)　プロセス前提条件

(2)　実行に必要な情報および補足説明

(1)　プロセス前提条件

J2EEサーバプロセスが未起動であること。

CJMSPリソースアダプタが未起動であること。

CJMSPブローカープロセスが未起動であること。

アプリケーションが未起動であること。

(2)　実行に必要な情報および補足説明

(A1)などの記述は，図中の記述と対応しています。

(A1)

<インスタンス名>

省略した場合は，デフォルトで「cjmsbroker」を使用します。

複数インスタンスを使用したい場合には名称が重ならないように注意する必要があります。

重なる場合には-nameオプションを指定し存在しない任意の名称を付与してください。

<ディレクトリパス>

削除したいインスタンスが存在するVAR_HOMEのパス

CJMSPブローカーインスタンス名に該当するディレクトリ（デフォルト名はcjmsbroker）を削除します。

この処理を行うと，propとlogディレクトリ以外，すべてのインスタンスに関連するファイルとディレクトリを削除します。

インスタンスのディレクトリ自体が不要な場合，エクスプローラなどで次のディレクトリへ移動して，手動で削除してください。

<VAR_HOME>/instances

次回CJMSPブローカー起動時に削除したインスタンス名を使用して再度CJMSPブローカーを起動した場合には，インスタンスが再作成されます。

付録F　各バージョンでの主な機能変更

ここでは，08-70よりも前のアプリケーションサーバの各バージョンでの主な機能の変更について，変更目的ごとに説明します。08-70での主な機能変更については，「1.4　アプリケーションサーバ 08-70での主な機能変更」を参照してください。

説明内容は次のとおりです。

アプリケーションサーバの各バージョンで変更になった主な機能と，その概要を説明しています。機能の詳細については，「参照先マニュアル」の「参照個所」の記述を確認してください。「参照先マニュアル」および「参照個所」には，その機能についての主な記載個所を記載しています。

「参照先マニュアル」に示したマニュアル名の「Cosminexus アプリケーションサーバ」または「Cosminexus アプリケーションサーバ V8」は省略しています。

＜この節の構成＞

付録F.1　08-53での主な機能変更

付録F.2　08-50での主な機能変更

付録F.3　08-00での主な機能変更

付録F.1　08-53での主な機能変更

＜この項の構成＞

(1)　導入・構築の容易性強化

(2)　標準機能・既存機能への対応

(3)　信頼性の維持・向上

(4)　運用性の維持・向上

(5)　そのほかの目的

(1)　導入・構築の容易性強化

導入・構築の容易性強化を目的として変更した項目を次の表に示します。

表F-1　導入・構築の容易性強化を目的とした変更

項目
変更の概要
参照先マニュアル
参照個所

さまざまなハイパーバイザに対応した仮想化環境の構築
さまざまなハイパーバイザを使用して実現する仮想サーバ上に，アプリケーションサーバを構築できるようになりました。
また，複数のハイパーバイザが混在する環境にも対応しました。
仮想化システム構築・運用ガイド
2章，3章，5章

(2)　標準機能・既存機能への対応

標準機能・既存機能への対応を目的として変更した項目を次の表に示します。

表F-2　標準機能・既存機能への対応を目的とした変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
トランザクション連携に対応したOpenTP1からの呼び出し | OpenTP1からアプリケーションサーバ上で動作するMessage-driven Beanを呼び出すときに，トランザクション連携ができるようになりました。 | このマニュアル | 4章
JavaMail | POP3に準拠したメールサーバと連携して，JavaMail 1.3に準拠したAPIを使用したメール受信機能を利用できるようになりました。 | このマニュアル | 8章

(3)　信頼性の維持・向上

信頼性の維持・向上を目的として変更した項目を次の表に示します。

表F-3　信頼性の維持・向上を目的とした変更

項目
変更の概要
参照先マニュアル
参照個所

JavaVMのトラブルシュート機能強化
JavaVMのトラブルシュート機能として，次の機能が使用できるようになりました。

OutOfMemoryError発生時の動作を変更できるようになりました。

JITコンパイル時に，Cヒープ確保量の上限値を設定できるようになりました。

スレッド数の上限値を設定できるようになりました。

拡張verbosegc情報の出力項目を拡張しました。

機能解説 保守／移行／互換編
4章，5章，8章

(4)　運用性の維持・向上

運用性の維持・向上を目的として変更した項目を次の表に示します。

表F-4　運用性の維持・向上を目的とした変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
JP1/ITRMへの対応 | ITリソースを一元管理する製品であるJP1/ITRMに対応しました。 | 仮想化システム構築・運用ガイド | 1.3，2.1

(5)　そのほかの目的

そのほかの目的で変更した項目を次の表に示します。

表F-5　そのほかの目的による変更

項目
変更の概要
参照先マニュアル
参照個所

Microsoft IIS 7.0およびMicrosoft IIS 7.5への対応
WebサーバとしてMicrosoft IIS 7.0およびMicrosoft IIS 7.5に対応しました。
－
－

HiRDB Version 9およびSQL Server 2008への対応
データベースとして次の製品に対応しました。

HiRDB Server Version 9

HiRDB/Developer's Kit Version 9

HiRDB/Run Time Version 9

SQL Server 2008

また，SQL Server 2008に対応するJDBCドライバとして，SQL Server JDBC Driverに対応しました。
このマニュアル
3章

（凡例）－：該当なし。

付録F.2　08-50での主な機能変更

＜この項の構成＞

(1)　導入・構築の容易性強化

(2)　標準機能・既存機能への対応

(3)　信頼性の維持・向上

(4)　運用性の維持・向上

(5)　そのほかの目的

(1)　導入・構築の容易性強化

導入・構築の容易性強化を目的として変更した項目を次の表に示します。

表F-6　導入・構築の容易性強化を目的とした変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
Webサービスプロバイダ側でのweb.xmlの指定必須タグの変更 | Webサービスプロバイダ側でのweb.xmlで，listenerタグ，servletタグおよびservlet-mappingタグの指定を必須から任意に変更しました。 | リファレンス 定義編(サーバ定義) | 2.4
論理サーバのネットワークリソース使用 | J2EEアプリケーションからほかのホスト上にあるネットワークリソースやネットワークドライブにアクセスするための機能を追加しました。 | 機能解説 運用／監視／連携編 | 1.2.3，5.2，5.8
サンプルプログラムの実行手順の簡略化 | 一部のサンプルプログラムをEAR形式で提供することによって，サンプルプログラムの実行手順を簡略化しました。 | ファーストステップガイド | 3.4.1
システム構築・運用ガイド | 付録F
運用管理ポータルの画面動作の改善 | 画面の更新間隔のデフォルトを「更新しない」から「3秒」に変更しました。 | 運用管理ポータル操作ガイド | 7.4.1
セットアップウィザードの完了画面の改善 | セットアップウィザード完了時の画面に，セットアップで使用した簡易構築定義ファイルおよびConnector属性ファイルが表示されるようになりました。 | システム構築・運用ガイド | 2.2.12，3.3
仮想化環境の構築 | ハイパーバイザを使用して実現する仮想サーバ上に，アプリケーションサーバを構築する手順を追加しました。※ | 仮想化システム構築・運用ガイド | 3章，5章

注※

08-50モードで構築する場合は，マニュアル「Cosminexus アプリケーションサーバ 仮想化システム構築・運用ガイド」の「付録D　08-50モードの仮想サーバマネージャを利用する場合の設定」を参照してください。

(2)　標準機能・既存機能への対応

標準機能・既存機能への対応を目的として変更した項目を次の表に示します。

表F-7　標準機能・既存機能への対応を目的とした変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
OpenTP1からの呼び出しへの対応 | OpenTP1からアプリケーションサーバ上で動作するMessage-driven Beanを呼び出せるようになりました。 | このマニュアル | 4章
JMSへの対応 | JMS1.1仕様に対応したCosminexus JMSプロバイダ機能を使用できるようになりました。 | このマニュアル | 7章
Java SE 6への対応 | Java SE 6の機能が使用できるようになりました。 | 機能解説 保守／移行／互換編 | 5.5，5.8.1
ジェネリクスの使用への対応 | EJBでジェネリクスを使用できるようになりました。 | 機能解説 基本・開発編(EJBコンテナ) | 4.2.17

(3)　信頼性の維持・向上

信頼性の維持・向上を目的として変更した項目を次の表に示します。

表F-8　信頼性の維持・向上を目的とした変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
明示管理ヒープ機能の使用性向上 | 自動配置設定ファイルを使用して，明示管理ヒープ機能を容易に使用できるようになりました。 | システム設計ガイド | 7.1.1，7.6.3，7.10.5，7.11.1
機能解説 拡張編 | 8章
データベースセッションフェイルオーバ機能のURI単位での抑止 | データベースセッションフェイルオーバ機能を使用する場合に，機能の対象外にするリクエストをURI単位で指定できるようになりました。 | 機能解説 拡張編 | 6.6
仮想化環境での障害監視 | 仮想化システムで，仮想サーバ監視し，障害の発生を検知できるようになりました。 | 仮想化システム構築・運用ガイド | 付録D

(4)　運用性の維持・向上

運用性の維持・向上を目的として変更した項目を次の表に示します。

表F-9　運用性の維持・向上を目的とした変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
管理ユーザアカウントの省略 | 運用管理ポータル，Management Serverのコマンド，またはSmart Composer機能のコマンドで，ユーザのログインIDおよびパスワードの入力を省略できるようになりました。 | システム構築・運用ガイド | 7.6.1，7.6.2，7.6.5
運用管理ポータル操作ガイド | 2.2，7.1.1，7.1.2，7.1.3，8.1，8.2.1，付録G.2
リファレンス コマンド編 | 1.4，mngsvrctl（Management Serverの起動／停止／セットアップ），mngsvrutil（Management Serverの運用管理コマンド），8.3，cmx_admin_passwd（Management Serverの管理ユーザアカウントの設定）
仮想化環境の運用 | 仮想化システムで，複数の仮想サーバを対象にした一括起動・一括停止，スケールイン・スケールアウトなどを実行する手順を追加しました。※ | 仮想化システム構築・運用ガイド | 4章，6章

注※

08-50モードで運用する場合は，マニュアル「Cosminexus アプリケーションサーバ 仮想化システム構築・運用ガイド」の「付録D　08-50モードの仮想サーバマネージャを利用する場合の設定」を参照してください。

(5)　そのほかの目的

そのほかの目的で変更した項目を次の表に示します。

表F-10　そのほかの目的による変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
Tenured領域内不要オブジェクト統計機能 | Tenured領域内で不要となったオブジェクトだけを特定できるようになりました。 | 機能解説 保守／移行／互換編 | 8.8
Tenured増加要因の基点オブジェクトリスト出力機能 | Tenured領域内不要オブジェクト統計機能を使って特定した，不要オブジェクトの基点となるオブジェクトの情報を出力できるようになりました。 | 8.9
クラス別統計情報解析機能 | クラス別統計情報をCSV形式で出力できるようになりました。 | 8.10
論理サーバの自動再起動回数オーバー検知によるクラスタ系切り替え | Management Serverを系切り替えの監視対象としているクラスタ構成の場合，論理サーバが異常停止状態(自動再起動回数をオーバーした状態，または自動再起動回数の設定が0のときに障害を検知した状態)になったタイミングでの系切り替えができるようになりました。 | 機能解説 運用／監視／連携編 | 20.4.3，20.5.3，22.2.2，22.3.3，22.3.4
ホスト単位管理モデルを対象とした系切り替えシステム | クラスタソフトウェアと連携したシステム運用で，ホスト単位管理モデルを対象にした系切り替えができるようになりました。 | 22章
ACOS（AX2000，BS320）のサポート | 使用できる負荷分散機の種類にACOS（AX2000，BS320）が追加になりました。 | システム構築・運用ガイド | 4.3.1，8.2，8.3，8.11.6，付録A，付録A.2
リファレンス 定義編(サーバ定義) | 4.5，4.6.2，4.6.4，4.6.5，4.6.6，4.10.1
CMTでトランザクション管理をする場合にStateful Session Bean（SessionSynchronization）に指定できるトランザクション属性の追加 | CMTでトランザクション管理をする場合に，Stateful Session Bean（SessionSynchronization）にトランザクション属性としてSupports，NotSupportedおよびNeverを指定できるようになりました。 | 機能解説 基本・開発編(EJBコンテナ) | 2.7.3
OutOfMemoryError発生時の運用管理エージェントの強制終了 | JavaVMでOutOfMemoryErrorが発生したときに，運用管理エージェントが強制終了するようになりました。 | 機能解説 保守／移行／互換編 | 2.5.7
スレッドの非同期並行処理 | TimerManagerおよびWorkManagerを使用して，非同期タイマ処理および非同期スレッド処理を実現できるようになりました。 | 機能解説 拡張編 | 13章

付録F.3　08-00での主な機能変更

＜この項の構成＞

(1)　開発生産性の向上

(2)　標準機能への対応

(3)　信頼性の維持・向上

(4)　運用性の維持・向上

(5)　そのほかの目的

(1)　開発生産性の向上

開発生産性の向上を目的として変更した項目を次の表に示します。

表F-11　開発生産性の向上を目的とした変更

項目
変更の概要
参照先マニュアル
参照個所

ほかのアプリケーションサーバ製品からの移行容易化
ほかのアプリケーションサーバ製品からの移行を円滑に実施するため，次の機能を使用できるようになりました。

HTTPセッションの上限が例外で判定できるようになりました。

JavaBeansのIDが重複している場合や，カスタムタグの属性名とTLDの定義で大文字・小文字が異なる場合に，トランスレーションエラーが発生することを抑止できるようになりました。

機能解説 基本・開発編(Webコンテナ)
2.3，2.7.5

cosminexus.xmlの提供
Cosminexus アプリケーションサーバ独自の属性をcosminexus.xmlに記載することによって，J2EEアプリケーションをJ2EEサーバにインポート後，プロパティの設定をしないで開始できるようになりました。
このマニュアル
10.3

(2)　標準機能への対応

標準機能への対応を目的として変更した項目を次の表に示します。

表F-12　標準機能への対応を目的とした変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
Servlet 2.5への対応 | Servlet 2.5に対応しました。 | 機能解説 基本・開発編(Webコンテナ) | 2.2，2.5.4，2.6，5章
JSP 2.1への対応 | JSP 2.1に対応しました。 | 機能解説 基本・開発編(Webコンテナ) | 2.3.1，2.3.3，2.5，2.6，5章
JSPデバッグ | MyEclipseを使用した開発環境でJSPデバッグができるようになりました。 | 機能解説 基本・開発編(Webコンテナ) | 2.4
タグライブラリのライブラリJARへの格納とTLDのマッピング | タグライブラリをライブラリJARに格納した場合に，Webアプリケーション開始時にWebコンテナによってライブラリJAR内のTLDファイルを検索し，自動的にマッピングできるようになりました。 | 機能解説 基本・開発編(Webコンテナ) | 2.3.4
application.xmlの省略 | J2EEアプリケーションでapplication.xmlが省略できるようになりました。 | このマニュアル | 10.4
アノテーションとDDの併用 | アノテーションとDDを併用できるようになり，アノテーションで指定した内容をDDで更新できるようになりました。 | このマニュアル | 11.5
アノテーションのJava EE 5標準準拠（デフォルトインターセプタ） | デフォルトインターセプタをライブラリJARに格納できるようになりました。また，デフォルトインターセプタからDIできるようになりました。 | このマニュアル | 10.4
@Resourceの参照解決 | @Resourceでリソースの参照解決ができるようになりました。 | このマニュアル | 11.4
JPAへの対応 | JPA仕様に対応しました。 | このマニュアル | 5章，6章

(3)　信頼性の維持・向上

信頼性の維持・向上を目的として変更された項目を次の表に示します。

表F-13　信頼性の維持・向上を目的とした変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
セッション情報の永続化 | HTTPセッションのセッション情報をデータベースに保存して引き継げるようになりました。 | 機能解説 拡張編 | 5章，6章
フルガーベージコレクションの抑止 | フルガーベージコレクションの要因となるオブジェクトをJavaヒープ外に配置することで，フルガーベージコレクション発生を抑止できるようになりました。 | 機能解説 拡張編 | 8章
クライアント性能モニタ | クライアント処理に掛かった時間を調査・分析できるようになりました。 | 機能解説 拡張編 | 9章

(4)　運用性の維持・向上

運用性の維持・向上を目的として変更された項目を次の表に示します。

表F-14　運用性の維持・向上を目的とした変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
運用管理ポータルでのアプリケーション操作性向上 | アプリケーションおよびリソースの操作について，サーバ管理コマンドと運用管理ポータルの相互運用ができるようになりました。 | 運用管理ポータル操作ガイド | 1.1.4

(5)　そのほかの目的

そのほかの目的で変更された項目を次の表に示します。

表F-15　そのほかの目的による変更

項目 | 変更の概要 | 参照先マニュアル | 参照個所
無効なHTTP Cookieの削除 | 無効なHTTP Cookieを削除できるようになりました。 | 機能解説 基本・開発編(Webコンテナ) | 2.7.4
ネーミングサービスの障害検知 | ネーミングサービスの障害が発生した場合に，EJBクライアントが，より早くエラーを検知できるようになりました。 | このマニュアル | 2.7
コネクション障害検知タイムアウト | コネクション障害検知タイムアウトのタイムアウト時間を指定できるようになりました。 | このマニュアル | 3.15.1
Oracle11gへの対応 | データベースとしてOracle11gが使用できるようになりました。 | このマニュアル | 3章
バッチ処理のスケジューリング | バッチアプリケーションの実行をCTMによってスケジューリングできるようになりました。 | 機能解説 拡張編 | 4章
バッチ処理のログ | バッチ実行コマンドのログファイルのサイズ，面数，ログの排他処理失敗時のリトライ回数とリトライ間隔を指定できるようになりました。 | リファレンス 定義編(サーバ定義) | 3.6
snapshotログ | snapshotログの収集内容が変更されました。 | 機能解説 保守／移行／互換編 | 付録A.1，付録A.2
メソッドキャンセルの保護区公開 | メソッドキャンセルの対象外となる保護区リストの内容を公開しました。 | 機能解説 運用／監視／連携編 | 付録C
統計前のガーベージコレクション選択機能 | クラス別統計情報を出力する前に，ガーベージコレクションを実行するかどうかを選択できるようになりました。 | 機能解説 保守／移行／互換編 | 8.7
Survivor領域の年齢分布情報出力機能 | Survivor領域のJavaオブジェクトの年齢分布情報を日立JavaVMログファイルに出力できるようになりました。 | 機能解説 保守／移行／互換編 | 8.11
ファイナライズ滞留解消機能 | JavaVMのファイナライズ処理の状態を監視して，処理の滞留を解消できるようになりました。 | 機能解説 保守／移行／互換編 | 8.12
サーバ管理コマンドの最大ヒープサイズの変更 | サーバ管理コマンドが使用する最大ヒープサイズが変更されました。 | リファレンス 定義編(サーバ定義) | 5.2，5.3
推奨しない表示名を指定された場合の対応 | J2EEアプリケーションで推奨しない表示名を指定された場合にメッセージが出力されるようになりました。 | メッセージ 2 | KDJE42374-W

付録G　このマニュアルの参考情報

このマニュアルを読むに当たっての参考情報を示します。

＜この節の構成＞

付録G.1　関連マニュアル

付録G.2　マニュアル体系の変更について

付録G.3　このマニュアルでの表記

付録G.4　英略語

付録G.5　KB（キロバイト）などの単位表記について

付録G.1　関連マニュアル

アプリケーションサーバのマニュアルについて次に示します。

Cosminexus アプリケーションサーバ V8 概説（3020-3-U01）
アプリケーションサーバの概要について説明しています。

Cosminexus アプリケーションサーバ V8 ファーストステップガイド（3020-3-U02）
Application ServerまたはDeveloperを使用して，サンプルプログラムを動かすためのシステムを構築する手順について説明しています。

Cosminexus アプリケーションサーバ V8 システム設計ガイド（3020-3-U03）
システム設計時に，システムの目的に応じたシステム構成や運用方法を検討するための指針について説明しています。また，チューニングの方法についても説明しています。

Cosminexus アプリケーションサーバ V8 システム構築・運用ガイド（3020-3-U04）
セットアップウィザードおよびSmart Composer機能を使用したシステムの構築・運用の手順について説明しています。

Cosminexus アプリケーションサーバ V8 機能解説 基本・開発編(Webコンテナ)（3020-3-U05）
アプリケーションサーバで提供するWebコンテナの機能，およびWebコンテナに関連する機能（Webサーバ，サーブレット／JSPなど）について説明しています。

Cosminexus アプリケーションサーバ V8 機能解説 基本・開発編(EJBコンテナ)（3020-3-U06）
アプリケーションサーバで提供するEJBコンテナの機能，およびEJBコンテナに関連する機能（EJB，EJBクライアントなど）について説明しています。

Cosminexus アプリケーションサーバ V8 機能解説 拡張編（3020-3-U08）
アプリケーションサーバで提供する拡張機能（セッションフェイルオーバ機能，バッチサーバ，CTMなど）について説明しています。

Cosminexus アプリケーションサーバ V8 機能解説 運用／監視／連携編（3020-3-U09）
アプリケーションサーバで提供する運用・監視機能，およびほかのプログラムとの連携について説明しています。

Cosminexus アプリケーションサーバ V8 機能解説 保守／移行／互換編（3020-3-U10）
アプリケーションサーバで構築したシステムの保守に関する機能，移行情報，および互換用機能について説明しています。

Cosminexus アプリケーションサーバ V8 アプリケーション設定操作ガイド（3020-3-U12）
アプリケーションサーバで動作するアプリケーションの操作方法について説明しています。

Cosminexus アプリケーションサーバ V8 運用管理ポータル操作ガイド（3020-3-U13）
運用管理ポータルの使用方法について説明しています。

Cosminexus アプリケーションサーバ V8 リファレンス コマンド編（3020-3-U14）
アプリケーションサーバを構築・運用するときに使用するコマンドについて説明しています。

Cosminexus アプリケーションサーバ V8 リファレンス 定義編(サーバ定義)（3020-3-U15）
アプリケーションサーバを構築・運用するとき，またはアプリケーションを開発するときに，使用するファイルのうち，J2EEサーバやManagement Serverなどのサーバの定義に使用するファイルの形式について説明しています。

Cosminexus アプリケーションサーバ V8 リファレンス 定義編(アプリケーション／リソース定義)（3020-3-U16）
アプリケーションサーバを構築・運用するとき，またはアプリケーションを開発するときに使用するファイルのうち，アプリケーションやリソースの属性設定に使用するファイルの形式について説明しています。

Cosminexus アプリケーションサーバ V8 仮想化システム構築・運用ガイド（3020-3-U18）
アプリケーションサーバを仮想化したサーバ上に構築する場合の設計，構築，運用の手順について説明しています。

Cosminexus アプリケーションサーバ V8 アプリケーション開発ガイド（3020-3-U25）
アプリケーションサーバで動作させるアプリケーションの開発方法について説明しています。

Cosminexus アプリケーションサーバ V8 リファレンス API編（3020-3-U26）
アプリケーションを開発するときに使用するAPIの形式について説明しています。

Cosminexus アプリケーションサーバ V8 メッセージ 1 KDAL-KDCGおよびHitachi Web Server編（3020-3-U41）
アプリケーションサーバで出力されるKDALからKDCGまでのメッセージ，およびHitachi Web Serverのメッセージについて説明しています。

Cosminexus アプリケーションサーバ V8 メッセージ 2 KDJE-KDJW編（3020-3-U42）
アプリケーションサーバで出力されるKDJEからKDJWまでのメッセージについて説明しています。

Cosminexus アプリケーションサーバ V8 メッセージ 3 KECX-KEDT／KEOS02000-29999／KEUC-KFRM編（3020-3-U43）
アプリケーションサーバで出力されるKECXからKEDTまでのメッセージ，KEOS02000からKEOS29999までのメッセージ，およびKEUCからKFRMまでのメッセージについて説明しています。

Cosminexus アプリケーションサーバ V8 メッセージ 4 監査ログ編（3020-3-U44）
アプリケーションサーバで出力される監査ログメッセージについて説明しています。

また，このマニュアルと関連するこのほかのマニュアルを次に示します。必要に応じてお読みください。

Hitachi Web Server（3020-3-U17）

TPBroker Version 5 トランザクショナル分散オブジェクト基盤TPBroker ユーザーズガイド（3020-3-U19）

Cosminexus アプリケーションサーバ V8 Cosminexus Reliable Messaging（3020-3-U21）

VisiBroker Version 5 Borland(R) Enterprise Server VisiBroker(R) デベロッパーズガイド（3020-3-U28）

スケーラブルデータベースサーバ HiRDB Version 8 システム定義（UNIX(R)用）（3000-6-353）

スケーラブルデータベースサーバ HiRDB Version 8 コマンドリファレンス(UNIX(R)用)（3000-6-355）

HiRDB Version 9 システム定義（UNIX(R)用）（3000-6-453）

HiRDB Version 9 コマンドリファレンス(UNIX(R)用)（3000-6-455）

スケーラブルデータベースサーバ HiRDB Version 8 システム定義（Windows(R)用）（3020-6-353）

HiRDB Version 9 システム定義（Windows(R)用）（3020-6-453）

OpenTP1 Version 7 分散トランザクション処理機能 OpenTP1 解説（3000-3-D50）

OpenTP1 Version 7 分散トランザクション処理機能 OpenTP1 プログラム作成の手引（3000-3-D51）

OpenTP1 Version 7 分散トランザクション処理機能 OpenTP1 システム定義（3000-3-D52）

OpenTP1 Version 7 分散トランザクション処理機能 OpenTP1 クライアント使用の手引 TP1/Client/J編（3000-3-D59）

OpenTP1 Version 7 メッセージキューイングアクセス機能 TP1/Message Queue - Access 使用の手引（3000-3-D94）

OpenTP1 Version 6 分散トランザクション処理機能 OpenTP1 クライアント使用の手引 TP1/Client/J編（3000-3-950）

なお，このマニュアルでは，次のマニュアルについて，対象OSおよびバージョン番号を省略して表記しています。マニュアルの正式名称とこのマニュアルでの表記を次の表に示します。

正式名称 | このマニュアルでの表記
Cosminexus アプリケーションサーバ V8 システム設計ガイド | Cosminexus アプリケーションサーバ システム設計ガイド
Cosminexus アプリケーションサーバ V8 システム構築・運用ガイド | Cosminexus アプリケーションサーバ システム構築・運用ガイド
Cosminexus アプリケーションサーバ V8 機能解説 基本・開発編(Webコンテナ) | Cosminexus アプリケーションサーバ 機能解説 基本・開発編(Webコンテナ)
Cosminexus アプリケーションサーバ V8 機能解説 基本・開発編(EJBコンテナ) | Cosminexus アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)
Cosminexus アプリケーションサーバ V8 機能解説 拡張編 | Cosminexus アプリケーションサーバ 機能解説 拡張編
Cosminexus アプリケーションサーバ V8 機能解説 運用／監視／連携編 | Cosminexus アプリケーションサーバ 機能解説 運用／監視／連携編
Cosminexus アプリケーションサーバ V8 機能解説 保守／移行／互換編 | Cosminexus アプリケーションサーバ 機能解説 保守／移行／互換編
Cosminexus アプリケーションサーバ V8 アプリケーション設定操作ガイド | Cosminexus アプリケーションサーバ アプリケーション設定操作ガイド
Cosminexus アプリケーションサーバ V8 リファレンス コマンド編 | Cosminexus アプリケーションサーバ リファレンス コマンド編
Cosminexus アプリケーションサーバ V8 リファレンス 定義編(サーバ定義) | Cosminexus アプリケーションサーバ リファレンス 定義編(サーバ定義)
Cosminexus アプリケーションサーバ V8 リファレンス 定義編(アプリケーション／リソース定義) | Cosminexus アプリケーションサーバ リファレンス 定義編(アプリケーション／リソース定義)
Cosminexus アプリケーションサーバ V8 仮想化システム構築・運用ガイド | Cosminexus アプリケーションサーバ 仮想化システム構築・運用ガイド
Cosminexus アプリケーションサーバ V8 アプリケーション開発ガイド | Cosminexus アプリケーションサーバ アプリケーション開発ガイド
Cosminexus アプリケーションサーバ V8 リファレンス API編 | Cosminexus アプリケーションサーバ リファレンス API編
Cosminexus アプリケーションサーバ V8 メッセージ 1 KDAL-KDCGおよびHitachi Web Server編 | Cosminexus アプリケーションサーバ メッセージ 1
Cosminexus アプリケーションサーバ V8 メッセージ 2 KDJE-KDJW編 | Cosminexus アプリケーションサーバ メッセージ 2
Cosminexus アプリケーションサーバ V8 Cosminexus Reliable Messaging | Cosminexus Reliable Messaging
VisiBroker Version 5 Borland(R) Enterprise Server VisiBroker(R) デベロッパーズガイド | Borland(R) Enterprise Server VisiBroker(R) デベロッパーズガイド
HiRDB Version 9 システム定義（UNIX(R)用） | HiRDB システム定義
HiRDB Version 9 システム定義（Windows(R)用）
スケーラブルデータベースサーバ HiRDB Version 8 システム定義（UNIX(R)用）
スケーラブルデータベースサーバ HiRDB Version 8 システム定義（Windows(R)用）
OpenTP1 Version 7 分散トランザクション処理機能 OpenTP1 解説 | OpenTP1 解説
OpenTP1 Version 7 分散トランザクション処理機能 OpenTP1 プログラム作成の手引 | OpenTP1 プログラム作成の手引
OpenTP1 Version 7 分散トランザクション処理機能 OpenTP1 システム定義 | OpenTP1 システム定義
OpenTP1 Version 7 分散トランザクション処理機能 OpenTP1 クライアント使用の手引 TP1/Client/J編 | OpenTP1 クライアント使用の手引 TP1/Client/J編
OpenTP1 Version 6 分散トランザクション処理機能 OpenTP1 クライアント使用の手引 TP1/Client/J編

付録G.2　マニュアル体系の変更について

08-00では，07-60のマニュアル「Cosminexus　機能解説」，マニュアル「Cosminexus　システム構築ガイド」およびマニュアル「Cosminexus　システム運用ガイド」の内容を6分冊して，マニュアル体系を変更しました。変更後のマニュアル体系については，「1.1　機能の分類」を参照してください。

付録G.3　このマニュアルでの表記

このマニュアルで使用している表記と，対応する製品名を次に示します。

表記 | 製品名
ACOS | AX2000 | AX2000
AX2500 | AX2500
BS320 | BS320ロードバランサブレード
Application Server | Application Server Enterprise | uCosminexus Application Server Enterprise
Application Server Standard | uCosminexus Application Server Standard
Developer | Developer Professional | uCosminexus Developer Professional
Developer Standard | uCosminexus Developer Standard
Eclipse | Eclipse 3.6.1
HiRDBまたはHiRDBサーバ | HiRDB Server | HiRDB Server Version 9
HiRDB/Parallel Server | HiRDB/Parallel Server Version 8
HiRDB/Single Server | HiRDB/Single Server Version 8
HiRDB Run TimeまたはHiRDBクライアント | HiRDB/Developer's Kit Version 8
HiRDB/Developer's Kit Version 9
HiRDB/Run Time Version 8
HiRDB/Run Time Version 9
IPF | Itanium(R) Processor Family
JP1/AJS | JP1/AJS - Agent | JP1/Automatic Job Management System 2 - Agent※
JP1/Automatic Job Management System 3 - Agent
JP1/AJS - Manager | JP1/Automatic Job Management System 2 - Manager※
JP1/Automatic Job Management System 3 - Manager
JP1/AJS - View | JP1/Automatic Job Management System 2 - View※
JP1/Automatic Job Management System 3 - View
JP1/AJS2 - SO | JP1/AJS2 - SO Manager | JP1/Automatic Job Management System 2 - Scenario Operation Manager
JP1/AJS2 - SO View | JP1/Automatic Job Management System 2 - Scenario Operation View
JP1/IM | JP1/IM - CM | JP1/Integrated Management - Central Information Master
JP1/IM - Manager | JP1/Integrated Management - Manager
JP1/IM - View | JP1/Integrated Management - View
JP1/NETM/Audit | JP1/NETM/Audit - Manager
Oracle | Oracle10g | Oracle 10g
Oracle 10g R2
Oracle Database 10g
Oracle11g | Oracle Database 11g
Oracle Database 11g R2
Oracle9i | Oracle9i
Oracle9i R2
TP1/Client | uCosminexus TP1/Client/J
uCosminexus TP1/Client/P
uCosminexus TP1/Client/W
UNIX | AIX | AIX 5L V5.3
AIX V6.1
AIX V7.1
HP-UXまたはHP-UX（IPF） | HP-UX 11i V2（IPF）
HP-UX 11i V3（IPF）
Linux | Linux（IPF） | Red Hat Enterprise Linux(R) AS 4（IPF）
Red Hat Enterprise Linux(R) 5 Advanced Platform（Intel Itanium）
Red Hat Enterprise Linux(R) 5（Intel Itanium）
Linux（x86/AMD64 & Intel EM64T） | Red Hat Enterprise Linux(R) AS 4（x86）
Red Hat Enterprise Linux(R) ES 4（x86）
Red Hat Enterprise Linux(R) AS 4（AMD64 & Intel EM64T）
Red Hat Enterprise Linux(R) ES 4（AMD64 & Intel EM64T）
Red Hat Enterprise Linux(R) 5 Advanced Platform（x86）
Red Hat Enterprise Linux(R) 5（x86）
Red Hat Enterprise Linux(R) 5 Advanced Platform（AMD/Intel 64）
Red Hat Enterprise Linux(R) 5（AMD/Intel 64）
Red Hat Enterprise Linux(R) Server 6（32-bit x86）
Red Hat Enterprise Linux(R) Server 6（64-bit x86_64）
Red Hat Enterprise Linux(R) ES 4（x86）
Solaris | Solaris 10（SPARC）
Solaris 10（x64）
Solaris 9（SPARC）
Web Redirector | uCosminexus Web Redirector
XDM/RD E2 | VOS3 XDM/RD E2

注※　総称して，JP1/AJS2と表記することがあります。

なお，Application ServerおよびDeveloperを総称して，アプリケーションサーバと表記します。

また，Linuxに関しては，バージョンごとに次のように表記することがあります。

表記 | OS名
Red Hat Enterprise Linux 4 | Red Hat Enterprise Linux(R) AS 4（IPF）
Red Hat Enterprise Linux(R) AS 4（x86）
Red Hat Enterprise Linux(R) ES 4（x86）
Red Hat Enterprise Linux(R) AS 4（AMD64 & Intel EM64T）
Red Hat Enterprise Linux(R) ES 4（AMD64 & Intel EM64T）
Red Hat Enterprise Linux 5 | Red Hat Enterprise Linux(R) 5 Advanced Platform（Intel Itanium）
Red Hat Enterprise Linux(R) 5（Intel Itanium）
Red Hat Enterprise Linux(R) 5 Advanced Platform（x86）
Red Hat Enterprise Linux(R) 5（x86）
Red Hat Enterprise Linux(R) 5 Advanced Platform（AMD/Intel 64）
Red Hat Enterprise Linux(R) 5（AMD/Intel 64）
Red Hat Enterprise Linux Server 6 | Red Hat Enterprise Linux(R) Server 6（32-bit x86）
Red Hat Enterprise Linux(R) Server 6（64-bit x86_64）

このマニュアルで使用している表記と，対応するアプリケーションサーバの機能名を次に示します。

表記 | アプリケーションサーバの機能名
CJMSPブローカー | Cosminexus JMSプロバイダのブローカー機能
CJMSPリソースアダプタ | Cosminexus JMSプロバイダのリソースアダプタ
Cosminexus Developer's Kit for Java | Cosminexus Developer's Kit for JavaTM
Cosminexus RM | Cosminexus Reliable Messaging
CTM | Cosminexus Component Transaction Monitor
Management Server | Cosminexus Management Server
MyEclipse | MyEclipse for Cosminexus
PRF | Cosminexus Performance Tracer
Smart Composer | Cosminexus Smart Composer

このマニュアルで使用している表記と，対応するJava関連用語を次に示します。

表記 | Java関連用語
Connector 1.0 | J2EETM Connector Architecture 1.0
Connector 1.5 | J2EETM Connector Architecture 1.5
DI | Dependency Injection
EAR | Enterprise ARchive
EJBまたはEnterprise JavaBeans | Enterprise JavaBeansTM
EJB QL | EJBTM Query Language
J2EEまたはJava 2 Platform, Enterprise Edition | J2EETM
JavaTM 2 Platform, Enterprise Edition
J2SE | JavaTM 2 Platform, Standard Edition
JAAS | JavaTM Authentication and Authorization Service
JAR | JavaTM Archive
Java | JavaTM
Java 2 Runtime Environment, Standard Edition | JavaTM 2 Runtime Environment, Standard Edition
Java 2 SDK, Standard Edition | JavaTM 2 Software Development Kit, Standard Edition
JavaBeans | JavaBeansTM
Java EEまたはJava Platform, Enterprise Edition | JavaTM Platform, Enterprise Edition
Java SE | JavaTM Platform, Standard Edition
JavaMail | JavaMailTM
Java SE | JavaTM Platform, Standard Edition
JavaVM | JavaTM Virtual Machine
JAXP | JavaTM API for XML Processing
JCA | J2EETM Connector Architecture
JCE | JavaTM Cryptography Extension
JDBC | JDBCTM
JavaTM Database Connectivity
JDK | JDKTM
JavaTM Development Kit
JMS | JavaTM Message Service
JNDI | Java Naming and Directory InterfaceTM
JNI | JavaTM Native Interface
JPA | Java Persistence API
JPQL | Java Persistence Query Language
JSP | JSPTM
JavaServer PagesTM
JTA | JavaTM Transaction API
JTS | JavaTM Transaction Service
Servletまたはサーブレット | JavaTM Servlet
SMAP | Source Map

付録G.4　英略語

このマニュアルで使用している英略語を次に示します。

英略語 | 英字での表記
ACOS | Advanced Core Operating System
API | Application Programming Interface
ASCII | American Standard Code for Information Interchange
BMP | Bean-Managed Persistence
BMT | Bean-Managed Transaction
CMP | Container-Managed Persistence
CMT | Container-Managed Transaction
CoC | Convention over Configuration
CORBA | Common Object Request Broker Architecture
CUI | Character User Interface
DAO | Data Access Object
DB | Database
DBMS | Database Management System
DD | Deployment Descriptor
DN | Distinguished Name
DTD | Document Type Definition
DTO | Data Transfer Object
EIS | Enterprise Information System
FIFO | First-In First-Out
HTML | Hyper Text Markup Language
HTTP | Hyper Text Transfer Protocol
HTTPS | Hyper Text Transfer Protocol Security
IIOP | Internet Inter-Orb Protocol
IP | Internet Protocol
MHP | Message Handling Program
MTU | Maximum Transmission Unit
OS | Operating System
OTS | Object Transaction Service
POP3 | Post Office Protocol - Version 3
RAC | Real Application Clusters
RDB | Relational Database
RMI | Remote Method Invocation
RPC | Remote Procedure Call
SMTP | Simple Mail Transfer Protocol
SPP | Service Providing Program
SSL | Secure Sockets Layer
SUP | Service Using Program
TCP | Transmission Control Protocol
UAP | User Application Program
URL | Uniform Resource Locator
VM | Virtual Machine
XML | Extensible Markup Language

付録G.5　KB（キロバイト）などの単位表記について

1KB（キロバイト），1MB（メガバイト），1GB（ギガバイト），1TB（テラバイト）はそれぞれ1,024バイト，1,024²バイト，1,024³バイト，1,024⁴バイトです。

付録H　用語解説

アプリケーションサーバで使用する用語について説明します。

（数字）

1.4モード

サーバの動作モードです。J2EE 1.4以降の機能を使用できます。データベースを含む複数のリソースのトランザクション管理ができます。

（英字）

Application Server

アプリケーションサーバの実行環境を構築する基盤製品です。Application Server Standardと，Application Server Enterpriseの総称です。

CJMSPブローカー

Cosminexus JMSプロバイダで使用するプロセスです。メッセージの送信先を管理します。

CJMSPリソースアダプタ

Cosminexus JMSプロバイダで使用するリソースアダプタです。

J2EEサーバからCJMSPブローカーに接続するために使用します。Connector 1.5仕様に準拠しています。

CORBAネーミングサービス

CORBAの仕様に準拠した，リモートオブジェクトの格納場所を管理するためのネーミングサービスです。アプリケーションサーバの構成ソフトウェアであるCosminexus TPBrokerによって提供される機能です。

cosminexus.xml

Cosminexus アプリケーションサーバ独自の情報を定義するための属性ファイルです。

Cosminexus Component Transaction Monitor

クライアントからのリクエストのスケジューリングを実現するための構成ソフトウェアです。

Cosminexus JMSプロバイダ

アプリケーションサーバで提供しているJMSプロバイダです。JMS1.1仕様に基づいた機能を提供しています。CJMSPブローカーとCJMSPリソースアダプタによって構成されています。

Cosminexus JPAプロバイダ

アプリケーションサーバで提供しているJPAプロバイダです。JPA1.0仕様に基づいた機能のほかに，エンティティオブジェクトのキャッシュ機能や悲観的ロック機能を提供しています。

Cosminexus Performance Tracer

リクエストが処理されるときに，決められたポイントごとに各機能が出力する性能解析情報をファイルに出力するための構成ソフトウェアです。

Cosminexus Reliable Messaging

アプリケーションサーバで構築したシステム上のJ2EEアプリケーションが，メッセージを使用して非同期に通信するための構成ソフトウェアです。JMSインタフェースでのメッセージ通信機能をJ2EEアプリケーションに提供します。

Cosminexusアプリケーションサーバ

アプリケーションサーバを中核とした，性能および信頼性の高いアプリケーションを実行および開発するためのシステム構築基盤製品です。

DB Connector

データベースに接続するためのリソースアダプタです。

DD

アプリケーションを運用環境に配置するときの定義情報を記述したものです。

Dependency Injection

EJBやインターセプタクラスのフィールドやsetterメソッドに，EJBやResourceアノテーションを指定することで，EJBやリソースへの参照をEJBコンテナが自動的にセットする機能です。Dependency Injectionを使用すると，EJBやリソースへの参照をJNDIを使用してルックアップする必要がなくなります。

DIターゲット

Dependency Injection機能を使用して参照を注入する対象のことです。DIターゲット名と名前が一致するフィールド，またはDIターゲット名をプロパティとして持つsetterメソッドに対して，Dependency Injectionが実行されます。

EARファイル

J2EEアプリケーションを構成する複数のEJB-JARファイル，WARファイル，およびDDをEARファイル形式でパッケージ化したものです。

EJB（Enterprise JavaBeans）

業務ロジックをプログラムとして記述したビジネスロジック，および永続的データを格納するオブジェクトであるエンティティをJavaコンポーネント化したものです。

EJBクライアント

J2EEサーバ上で開始されているEnterprise Beanを呼び出すクライアントプログラムです。次の3種類があります。

EJBクライアントアプリケーション

サーブレットまたはJSPなどのWebアプリケーション

ほかのEnterprise Bean

EJBクライアントアプリケーション

Enterprise Beanを呼び出すJavaアプリケーションです。

EJBコンテナ

Enterprise Beanを制御する実行環境です。また，通信，トランザクション管理などのシステムレベルのサービスも提供します。Enterprise Beanの実体は，EJBコンテナの中で実行されます。

Inbound

Connector 1.5仕様で定められたJ2EEサーバとリソースアダプタ間の通信モデルの一つです。リソースアダプタからJ2EEサーバにアクセスする通信モデルです。

J2EEアプリケーション

JSP，サーブレット，Enterprise Beanなどで構成されるアプリケーションです。アプリケーションサーバで扱うJ2EEアプリケーションの形式には，EARファイル形式でパッケージ化されたアーカイブ形式のアプリケーションと，アーカイブ化しない展開ディレクトリ形式のアプリケーションがあります。EARファイル形式でパッケージ化されたアプリケーションの場合，複数のEJB-JARファイル，複数のWARファイル，および一つのDDから構成されます。

J2EEコンテナ

J2EEアプリケーションを実行するためのサーバ基盤です。

J2EEコンポーネントへ各種APIを提供する，Webコンテナ，EJBコンテナから構成されます。

J2EEコンポーネント

サーブレット，JSP，Enterprise Beanなどのユーザアプリケーションプログラムのことです。

J2EEサーバ

J2EEコンテナを生成，実行する環境です。

J2EEサービス

J2EEコンテナの部品機能として利用されます。J2EEコンポーネントにJNDI，JDBC，JTA，RMI-IIOPおよびJavaMailのAPIを提供します。

J2EEリソース

サーバから利用できるリソースです。J2EEサーバの場合，データベース，OpenTP1，SMTPサーバなどを利用できます。また，バッチサーバの場合，データベースを利用できます。

J2EEリソースアダプタ

J2EEサーバに共有スタンドアロンモジュールとして配備したリソースアダプタのことです。

JCAコンテナ

J2EEサーバやバッチサーバと，EISを接続するためのシステムレベルのプラグイン機能を提供するコンテナです。

JNDI（Java Naming and Directory Interface）

Javaプラットフォーム用の標準拡張機能で，Java テクノロジに対応したアプリケーションに，企業内の複数のネーミングおよびディレクトリサービスへの統一したインタフェースを提供します。

アプリケーションサーバでは，Cosminexus TPBrokerのCORBAネーミングサービスを利用して，JNDIの機能を実現しています。

JNDI名前空間

JNDIによってアクセスする名前情報が管理されている名前空間です。Application Serverでは，J2EEアプリケーションをデプロイした時に，EJBオブジェクトリファレンスがJNDI名前空間の名前にバインドされます。

アプリケーションサーバで使用するJNDI名前空間の名前には，別名を付けることができます。これによって，Enterprise BeanやJ2EEリソースを別名でルックアップできるようになります。

JPA

データベース関連処理の設計およびコーディングの簡略化を目的として，Javaのオブジェクトとリレーショナルデータベースとのマッピング（O/Rマッピング）に関して定められた仕様です。アプリケーションサーバでは，JPAを利用したアプリケーションを実行できます。

JPAプロバイダ

Javaオブジェクトとデータベースのマッピング機能やデータベースへの処理をカプセル化したAPIを提供するJPA実装です。アプリケーションサーバでは，JPAプロバイダとしてCosminexus JPAプロバイダを提供しています。

JPQL

JPA仕様で定義されているクエリ言語です。データベースに依存しない言語で，エンティティクラスを対象に操作します。アプリケーションサーバでは，JPQLを使用したデータベース操作ができます。

Oracle RAC

Oracleデータベースのクラスタ機能です。アプリケーションサーバでは，Oracle RAC機能を使用してクラスタ化されたOracleデータベースに接続できます。

OTS（Object Transaction Service）

1.4モードで，TPBroker OTSによる分散トランザクションを使用するために必要なサービスです。

Outbound

Connector 1.5仕様で定められたJ2EEサーバとリソースアダプタ間の通信モデルの一つです。J2EEサーバからリソースアダプタにアクセスする通信モデルです。

SecurityManager

セキュリティポリシーに基づいたWebコンテナの実行時保護をするJ2EEサーバの機能です。

TP1インバウンドアダプタ

TP1インバウンド連携機能で使用するリソースアダプタです。Connector 1.5仕様に準拠しています。

TP1インバウンド連携機能

TP1インバウンドアダプタを使用して，OpenTP1システムのSUPからアプリケーションサーバ上のMessage-driven BeanをInboundで呼び出す機能です。

Webアプリケーション

Webブラウザを備えたクライアントを対象に作成されたアプリケーションです。具体的には，サーブレットプログラム，JSPファイル，HTML/XMLドキュメントなどの集合体です。

Webコンテナ

Webアプリケーションを制御する実行環境です。また，セキュリティ，トランザクションなどの各種サービスも提供します。Webアプリケーションは，Webコンテナ上で動作します。

Java Servlet2.5仕様，およびJavaServer Pages Specification v2.1仕様に準拠したWebアプリケーションを実行できます。

Webサーバ

Webブラウザからのリクエスト受信およびWebブラウザへのデータ送信に関連する処理を実行するプログラムです。アプリケーションサーバでは，Hitachi Web Server，Microsoft IIS，またはインプロセスHTTPサーバを使用できます。インプロセスHTTPサーバは，J2EEサーバプロセス内で動作するWebサーバです。

なお，Management Serverを利用する場合，Hitachi Web Serverは論理サーバとして扱えます。

Webサーバ連携

アプリケーションサーバで使用するWebサーバとして，Hitachi Web ServerまたはMicrosoft IISを使用する方法です。

Hitachi Web ServerまたはMicrosoft IISにCosminexus Component Containerが提供するリダイレクタモジュールを組み込んで使用します。

（ア行）

アーカイブ形式

EJBやサーブレットなどのアプリケーションの実体をJ2EEサーバの作業ディレクトリに持つJ2EEアプリケーションの形式です。

アウトプロセス

プロセスの起動のしかたです。アウトプロセスで起動させると，J2EEサーバのプロセス外で実行します。アウトプロセスでネーミングサービスを使用する場合，CORBAネーミングサービスはユーザが起動する必要があります。

アノテーション

ソースコードにクラスやメソッドの付加情報などを埋め込むための記述方式です。

アプリケーションサーバ

情報システムの中間に位置し，ユーザの要求（プレゼンテーション層）とデータベースなどの業務システム（データ層）の処理を橋渡しするためのアプリケーション層を構築するためのミドルウェアです。

一時クローズ処理

OpenTP1とTP1インバウンドアダプタ間のコネクション数がしきい値に達した場合に，コネクションを切断する処理のことです。

（カ行）

管理対象オブジェクト（AdminObject）

Connector 1.5仕様で定義された，キューやトピックなどを使用したメッセージの送受信で使用するオブジェクトです。メッセージ送信や，同期または非同期でのメッセージ受信でのメッセージ変換で使用します。

管理対象オブジェクトは，メッセージプロバイダごとに特有のオブジェクトです。リソースアダプタが使用する管理対象オブジェクトは，リソースアダプタのDD（ra.xml）の<adminobject>タグで指定します。

グローバルCORBAネーミングサービス

CTMによってリクエストをスケジューリングする場合に，CTMドメイン内に含まれる複数のJ2EEサーバに登録されている業務処理プログラム（Stateless Session Bean）の情報を共有管理するネーミングサービスです。

グローバルトランザクション

J2EEサーバが提供するトランザクションマネージャによって管理されるトランザクションです。2フェーズコミットプロトコルを使用できるので，トランザクションに複数のリソースを参加させることができます。

コネクションスイーパ

一定の間隔でコネクションプール内の未使用コネクションを破棄する機能です。

コネクションプーリング

サーブレット，JSP，Enterprise BeanなどのJ2EEコンポーネントや，バッチアプリケーションからリソースへのアクセス量に応じて，リソースコネクションをメモリ上にプーリングする機能です。リソースコネクションには，JDBCコネクション，リソースアダプタのコネクションなどがあります。コネクションをプーリングしておくことで，アプリケーションからのリソース接続要求を高速に処理できます。

コンテナ拡張ライブラリ

ユーザ作成ライブラリのインタフェースおよび機能を，J2EEコンテナ，Webコンテナ，またはバッチサーバから利用できるように拡張したライブラリです。Enterprise Bean，サーブレットおよびJSPから共通して利用できます。

（サ行）

サーバ管理コマンド

サーバで管理しているアプリケーションおよびリソースの設定をするためのコマンド群です。

サーバ起動・停止フック機能

J2EEサーバ，バッチサーバまたはWebサーバの起動・停止時に，コンテナ拡張ライブラリを使用するための初期化処理および停止処理を自動的に呼び出す機能です。J2EEサーバまたはWebサーバが異常終了した場合には機能しません。

サーブレットおよびJSPのサービスメソッド

javax.servlet.Servletのserviceメソッド，およびserviceメソッドから呼び出すメソッドです。serviceメソッドから呼び出すメソッドは， サーブレットの場合はdo*メソッド（doGet，doDeleteなど），JSPの場合は_jspServiceメソッドです。

セッション

Webアプリケーションに対する一連の作業を示す単位です。セッションは通常，WebクライアントからWebサーバへの複数のリクエストの集合から構成されます。

（タ行）

通常モード

J2EEアプリケーションの動作モードです。通常モードは，本番稼働するJ2EEアプリケーションを動作させるためのモードです。

データソース

JDBCを使用してデータベースに接続する機能です。

テストモード

J2EEアプリケーションの動作モードです。テストモードは，テスト用のJ2EEアプリケーションを本番環境と同じように動作させるためのモードです。

デプロイ

J2EEアプリケーションの場合，J2EEサーバ内にインポートしたJ2EEアプリケーションを，クライアントから実行可能な状態にすることです。

J2EEリソースアダプタの場合，J2EEサーバ内にインポートしたJ2EEリソースアダプタを，そのJ2EEサーバ上で動作するすべてのJ2EEアプリケーションから使用可能な状態にすることです。

展開ディレクトリ形式

EJBやサーブレットなどのアプリケーションの実体を，J2EEサーバの外部にある一定のルールに従ったファイル／ディレクトリに持つJ2EEアプリケーションの形式です。

同期点処理

OpenTP1が，トランザクションブランチに対してトランザクションを決着させるために実行する処理のことです。

同期点電文

OpenTP1が，トランザクションブランチに対してトランザクションを決着させるための指示を格納した電文のことです。

トランザクショングローバル識別子

システムノードIDとグローバルトランザクション番号（グローバルトランザクションを管理するためにシステムで一意に付けた番号）を合わせた識別子のことです。

トランザクションサービス

グローバルトランザクションを使用する場合に，トランザクションを管理するサービスです。TPBroker OTSによって提供されるサービス全体を表します。トランザクションサービスは，J2EEサーバのインプロセスで起動されます。

トランザクション識別子

トランザクションを一意に識別するための識別子のことです。

トランザクションマネージャ

トランザクションを管理する機能です。アプリケーションサーバが提供しています。グローバルトランザクションの場合は，トランザクションマネージャのバックエンドでTPBroker OTSが使用されています。

（ナ行）

ネーミング切り替え

JNDIを介してEJBホームオブジェクトの登録，削除，検索をする時に，JNDIが接続するCORBAネーミングサービスを切り替えることです。

ネーミングサービス

オブジェクトに名前を付けて格納場所を管理しておくことで，格納先を知らなくても名前からそのオブジェクトを利用できるようにするサービスです。アプリケーションサーバではCORBAネーミングサービスを利用します。

Management Serverでは，ネーミングサービスを論理サーバとして扱えます。

（ハ行）

非保護区

メソッドキャンセルができる領域を指します。ユーザプログラムのコードが非保護区に該当します。メソッドキャンセルとは，J2EEアプリケーション実行時間の監視で提供される機能の一つです。また，バッチ強制停止コマンドでも使用されます。

物理コネクション

接続先リソースのコネクションです。通常はJ2EEコンテナが操作します。リソースアダプタの場合は，javax.resource.spi.ManagedConnection，JDBCの場合はjavax.sql.XAConnectionに該当します。

別名

JNDI名前空間に登録するEJBホームオブジェクトリファレンスや，J2EEリソースに付けられる任意の名前です。ユーザ指定名前空間機能を使用している場合，別名を付けられます。Optional Nameともいいます。

保護区

メソッドキャンセルができない領域を指します。J2EEサービスのソースなどが保護区に該当します。メソッドキャンセルとは，J2EEアプリケーション実行時間の監視で提供される機能の一つです。また，バッチ強制停止コマンドでも使用されます。

（マ行）

未決着トランザクション

決着していない，仕掛かり中のトランザクションです。

メソッドキャンセル機能

J2EEアプリケーション実行時間の監視機能の機能の一つです。メソッドタイムアウト機能でタイムアウトが通知されたあと，メソッドのキャンセルを実施する機能です。キャンセル時にデータベースにアクセスしている場合は，トランザクションの強制決着もします。

また，メソッドキャンセル機能は，バッチ強制停止コマンド実行時にも使用されます。

メソッドタイムアウト機能

J2EEアプリケーション実行時間の監視機能の機能の一つです。監視基盤にあるリクエストのうち，一定時間内に終了しなかったメソッド処理を，タイムアウトとしてユーザに通知します。

メッセージインフロー

メッセージプロバイダがアプリケーションサーバ上のメッセージエンドポイントにメッセージを配送する場合の規約です。Connector 1.5のInboundの通信モデルを使用する場合に使用できる機能です。

メッセージプロバイダにはEISなどが該当します。アプリケーションサーバ上のメッセージエンドポイントにはMessage-driven Beanが該当します。

メンバリソースアダプタ

コネクションプールをクラスタ構成にしている場合に，データベースノードに接続するリソースアダプタです。メンバリソースアダプタは，必ずルートリソースアダプタを経由してアクセスされます。

（ヤ行）

ユーザ指定名前空間機能

JNDI名前空間に登録するEJBホームオブジェクトリファレンスやJ2EEリソースの名前に，ユーザが任意の別名を付けられる機能です。別名を付与することによって，CTMによってリクエストを振り分けたり，負荷分散機やロードバランサによって負荷分散したりする場合に，サーバ名やアプリケーション名に依存しない名前でルックアップできるようになります。

（ラ行）

ライトトランザクション

ローカルトランザクションを最適化した状態で使用できる機能です。

ライブラリJAR

JARファイル形式でパッケージされた，共通ライブラリです。J2EEアプリケーション内のJ2EEコンポーネントから共通に使用できます。

ラウンドロビン検索

複数のCORBAネーミングサービス上にある同一名称のEJBホームオブジェクトを，ラウンドロビンポリシーに従ってルックアップする検索機能のことです。

ラウンドロビンポリシー

複数のCORBAネーミングサービス上にある同一名称のEJBホームオブジェクトをルックアップする場合に適用されるポリシーです。

EJBホームオブジェクトリファレンスをラウンドロビン検索によって取得できるので，EJBクライアントでは意識しないでJ2EEサーバに送信するリクエストの負荷分散を実現できます。

リソースアダプタ

J2EE Connector Architectureによって，J2EEサーバまたはバッチサーバと，EISを接続するための接続機能です。

アプリケーションサーバで構築したシステムでは，データベースに接続するためのリソースアダプタであるDB ConnectorおよびDB Connector for Cosminexus RMを提供しています。また，OpenTP1のSPPと接続するためのリソースアダプタであるuCosminexus TP1 Connector，TP1/Message Queueと接続するためのリソースアダプタであるTP1/Message Queue - Access，データベース上に実現したキューに接続するためのリソースアダプタであるCosminexus RMも使用できます。

リソースマネジャ

リソースを管理する機能です。DBMSなどが該当します。

リデプロイ機能

J2EEアプリケーションを入れ替えるときに使用する機能です。リデプロイ機能による入れ替えは，J2EEアプリケーションのテスト時などに，修正したJ2EEアプリケーションと動作中のJ2EEアプリケーションを入れ替えたいときに使用します。

リロード機能

開始状態にあるアプリケーションを停止させないで，アプリケーションを構成するクラスやJSPを，少ない手順で動的に入れ替える機能です。

ルートリソースアダプタ

コネクションプールをクラスタ構成にしている場合に，メンバリソースアダプタを束ね，ユーザプログラムからのリクエストを受け付けるアダプタのことです。

ローカルトランザクション

接続先のリソースマネジャによって管理されるトランザクションです。単一のリソースだけがトランザクションに参加できます。

ロール

コンテキストに対し，アクセス制御するときに使用される単位です。ロールはグループごとに定義されます。また，アクセス制御するコンテキストについては，そのコンテキストにアクセスするのに必要なロールが定義されます。アクセスしたユーザの持つロールがコンテキストに定義されたロールと一致した場合，そのコンテキストへのアクセスは成功します。

論理コネクション

サーブレットやEnterprise BeanなどのJ2EEコンポーネントが直接操作するコネクションです。

リソースアダプタの場合はjavax.resource.cci.Connection，JDBCの場合はjava.sql.Connectionに該当します。

索引

[記号]
[数字]
[Ａ][Ｂ][Ｃ][Ｄ][Ｅ][Ｆ][Ｇ][Ｈ][Ｉ][Ｊ][Ｌ][Ｍ][Ｎ][Ｏ][Ｐ][Ｑ][Ｒ][Ｓ][Ｔ][Ｕ][Ｖ][Ｗ][Ｘ]
[ア行][カ行][サ行][タ行][ナ行][ハ行][マ行][ヤ行][ラ行][ワ行]

(記号)

-dオプションの使い方

<persistence-unit>タグに指定する属性

@IdClassを利用する方法

@OneToOneおよび@ManyToOneでのLAZYフェッチ

@Resourceアノテーションで指定できるリソースのタイプ

@ResourceアノテーションのmappedName属性で指定する方法

@Resourceアノテーションのname属性で指定する方法

@Resourceアノテーションを使用したリソースの参照解決

(数字)

1.4モード

(英字)

(Ａ)

ActivationSpecの設定

adminサービス

afterDeliveryメソッド

APIで作成される一時的な送信先

application.xmlがある場合のモジュールの決定規則

application.xmlがない場合のモジュールの決定規則

application.xmlの有無による機能の違い

application.xmlを省略した場合にapplication.xmlが作成される操作

application.xmlを省略した場合にJ2EEアプリケーションにリソースを追加するときの注意

Application Server

(Ｂ)

beforeDeliveryメソッド

(Ｃ)

CallableStatementのプールサイズ

CJMSPブローカー

CJMSPブローカー

CJMSPリソースアダプタ

CJMSPリソースアダプタ

cjreloadappコマンド

Connector 1.0仕様とConnector 1.5仕様のリソースアダプタのスキーマの違い

Connector 1.0仕様に準拠したリソースアダプタ

Connector 1.5仕様に準拠したリソースアダプタ

Connector 1.5仕様に準拠したリソースアダプタを使用する場合の設定

Connector 1.5仕様に準拠したリソースアダプタを使用する場合の注意事項

CORBAオブジェクト呼び出し処理の実装時の注意事項

CORBAオブジェクト呼び出し処理のパッケージ化の注意事項

CORBAネーミングサービス

CORBAネーミングサービス

CORBAネーミングサービスの切り替え

cosminexus.xml

cosminexus.xmlとは

cosminexus.xmlの作成

cosminexus.xmlの作成例

cosminexus.xmlまたはそれ以外の属性ファイルで指定する方法

cosminexus.xmlを含まないアプリケーションから移行する手順

cosminexus.xmlを含むアプリケーション

cosminexus.xmlを含むアプリケーションの運用

cosminexus.xmlを含むアプリケーションの作成

cosminexus.xmlを含むアプリケーションを使用する利点

Cosminexus Component Transaction Monitor

Cosminexus JMSプロバイダ

Cosminexus JMSプロバイダ

Cosminexus JMSプロバイダの機能

Cosminexus JPAプロバイダ

Cosminexus JPAプロバイダ

Cosminexus JPAプロバイダが提供する機能

Cosminexus JPAプロバイダでの処理

Cosminexus JPAプロバイダとは

Cosminexus JPAプロバイダの機能

Cosminexus JPAプロバイダを使用するための前提条件

Cosminexus Performance Tracer

Cosminexus Reliable Messaging

Cosminexus RM

Cosminexusアプリケーションサーバ

createEndpointメソッド

(Ｄ)

DataSourceオブジェクトのキャッシング

DataSourceオブジェクトのキャッシング

DB Connector

DB Connector（RARファイル）の種類

DB Connector for Cosminexus RM

DB Connector for Cosminexus RM（RARファイル）の種類

DB Connector for Cosminexus RMとCosminexus RMによる接続

DB Connector for Cosminexus RMとCosminexus RMによる接続の特徴

DB Connector for Cosminexus RMとCosminexus RMによるデータベース接続の構成

DB Connector for Cosminexus RMとCosminexus RMを使用する場合

DB ConnectorがサポートするJDBC仕様

DB Connectorによる接続

DB ConnectorのselectMethodプロパティ設定時の注意

DB Connectorのコネクション数の見積もり

DB Connectorのコンテナ管理でのサインオンの最適化

DB Connectorのコンテナ管理でのサインオンの最適化

DD

DDでの定義（モジュール単位の設定）

DDによる@PersistenceUnit定義のオーバーライド

DDによるアノテーションの上書き

DDの省略

DDの定義内容（JavaBeansリソース）

DDを省略した場合に設定される表示名

Dependency Injection

detached

detached状態のエンティティへのアクセス

DI

DI失敗時の動作

DIターゲット

DIの使用

DIを使用してリソースへの参照を取得する方法

(Ｅ)

EARファイル

EARファイル／ZIPファイルの展開

EARファイル／ZIPファイルの展開ディレクトリ形式でのデプロイ

EJB（Enterprise JavaBeans）

ejbserver.client.transaction.clientName

ejbserver.client.transaction.enabled

ejbserver.connectionpool.applicationAuthentication.disabled

ejbserver.connectionpool.association.enabled

ejbserver.connectionpool.association.enabledDespiteUnshareableSetting

ejbserver.connectionpool.sharingOutsideTransactionScope.enabled

ejbserver.connector.statementpool.clear.backcompat

ejbserver.container.ejbhome.sessionbean.reconnect.enabled

ejbserver.cui.optionalname.enabled

ejbserver.cui.optionalname.enabled

ejbserver.deploy.applications.metadata_complete

ejbserver.deploy.context.check_interval

ejbserver.deploy.context.reload_scope

ejbserver.deploy.context.update.interval

ejbserver.deploy.session.work.directory

ejbserver.distributedtx.ots.status.directory1

ejbserver.distributedtx.ots.status.directory1

ejbserver.distributedtx.ots.status.directory2

ejbserver.distributedtx.ots.status.directory2

ejbserver.distributedtx.recovery.completionCheckOnStopping.timeout

ejbserver.distributedtx.recovery.port

ejbserver.distributedtx.recovery.port

ejbserver.distributedtx.recovery.port

ejbserver.distributedtx.rollbackClientTxOnSystemException

ejbserver.distributedtx.XATransaction.enabled

ejbserver.jca.adapter.tp1.bind_host

ejbserver.jndi.cache

ejbserver.jndi.cache.interval

ejbserver.jndi.cache.interval.clear.option

ejbserver.jndi.cache.reference

ejbserver.jndi.namingservice.group.<Specify group name>.providerurls

ejbserver.jndi.namingservice.group.list

ejbserver.jndi.request.timeout

ejbserver.jta.TransactionManager.defaultTimeOut

ejbserver.jta.TransactionManager.defaultTimeOut

ejbserver.naming.host

ejbserver.naming.host

ejbserver.naming.port

ejbserver.naming.port

ejbserver.naming.protocol

ejbserver.naming.startupMode

ejbserver.webj2ee.connectionAutoClose.enabled

EJBアプリケーションの場合

EJBクライアント

EJBクライアントアプリケーション

EJBクライアントアプリケーションでトランザクションを開始する場合の注意事項

EJBコンテナ

EJBコンテナによるコネクション自動クローズ

EJBのリファレンスが自動的にバインドされる名称

EJBホームオブジェクトリファレンスの再利用（EJBホームオブジェクトへの再接続機能）

EJBホームオブジェクトリファレンスの別名付与

EJBホームオブジェクトリファレンスを再利用する場合の注意事項

Enterprise Beanで指定できるアノテーション

Enterprise Beanに対する別名

Enterprise Beanの検索

Enterprise Beanの別名の設定

Enterprise Beanを参照する仕組みと使い方（ejb-ref）

EntityManagerおよびEntityManagerFactoryの設定方法

EntityManagerで提供するメソッド

EntityManagerでのエンティティのライフサイクル管理

EntityManagerと永続化コンテキスト

EntityManagerとは

EntityManager内のクエリ関連インタフェースのAPIで発生する例外

EntityManagerによるエンティティの操作

EntityManagerのAPIに関する注意事項

EntityManagerの種類

EntityManagerのライフサイクルの管理

(Ｆ)

FetchType.EAGER

FetchType.LAZY

flush操作またはトランザクションの決着時のバージョンチェック

FROM節

Full

(Ｇ)

getInputStreamメソッド

getParameterメソッド

getQueryStringメソッド

getReaderメソッド

GROUP BY節

(Ｈ)

HardWeak

HAVING節

HiRDB Version 8の場合の前提条件

HiRDB Version 8の場合の前提条件

HiRDB Version 9の場合の前提条件

HiRDB Version 9の場合の前提条件

HiRDBでJPQLを使用する場合の注意事項

HiRDBと接続するときの注意事項

HiRDBと接続する場合の前提条件と注意事項

HiRDBのキューに接続する場合の前提条件

Hitachi Web ServerのSSLによる認証，暗号化の設定

Hitachi Web ServerのSSLによる認証，暗号化の設定

Hitachi Web ServerのSSLの設定

Hitachi Web ServerのSSLの設定（Webリダイレクタ環境の場合）

(Ｉ)

Inbound

Inbound

Inboundで使用できる機能

isDeliveryTransactedメソッド

(Ｊ)

J2EEアプリケーション

J2EEアプリケーション実行時間の監視の設定

J2EEアプリケーションに含めて使用する

J2EEアプリケーションの入れ替え

J2EEアプリケーションの形式とデプロイ

J2EEアプリケーションの形式とデプロイの機能

J2EEアプリケーションの更新検知インターバル

J2EEアプリケーションの更新検知とリロード

J2EEアプリケーションの更新検知とリロードの設定

J2EEアプリケーションの構成ファイル更新用インターバル

J2EEアプリケーションの状態と入れ替え

J2EEアプリケーションのデプロイとアンデプロイ

J2EEアプリケーションのリデプロイ

J2EEアプリケーションのリロード方法

J2EEアプリケーションへのプロパティの設定

J2EEコンテナ

J2EEコンポーネント

J2EEサーバ

J2EEサービス

J2EEリソース

J2EEリソースアダプタ

J2EEリソースアダプタ

J2EEリソースアダプタ

J2EEリソースアダプタとしてデプロイして使用する

J2EEリソースに対する別名

J2EEリソースの検索

J2EEリソースの別名が登録または削除されるタイミング

J2EEリソースの別名の設定

J2EEリソースの別名付与

java.naming.factory.initial

java:comp/envを使用した名称でのルックアップ

JavaBeansリソース属性ファイルの設定

JavaBeansリソースの入れ替え

JavaBeansリソースの入れ替えの流れ

JavaBeansリソースの開始処理の流れ

JavaBeansリソースの機能

JavaBeansリソースの実装

JavaBeansリソースの実装クラスの作成

JavaBeansリソースの新規設定の流れ

JavaBeansリソースの設定

JavaBeansリソースの設定変更の流れ

JavaBeansリソースのプロパティ定義で設定できること

JavaBeansリソースの利用

JavaMailの機能

JavaScriptを使用してクエリ文字列を作成する場合の注意事項

javax.jms.MessageListenerインタフェースを使用したMessage-driven Beanおよびリソースアダプタの場合

javax.persistence.EntityManagerインタフェース

javax.resource.spi.endpoint.MessageEndpointFactoryインタフェース

javax.resource.spi.endpoint.MessageEndpointインタフェース

JCAコンテナ

JMSアプリケーション

JMSインタフェースだけを使用する場合

JMSインタフェースとJDBCインタフェースで異なるデータベースにアクセスする場合

JMSインタフェースとJDBCインタフェースで同一データベースにアクセスする場合

jmsサービス

JNDI

JNDI

JNDI（Java Naming and Directory Interface）

JNDI名前空間

JNDI名前空間の確認方法

JNDI名前空間のマッピングとルックアップ

JNDI名前空間へのオブジェクトのバインドとルックアップ

JOINED戦略

Joins式

JPA

JPAの特長

JPAプロバイダ

JPAプロバイダとEJBコンテナ間の規約

JPAプロバイダとは

JPAを使用したアプリケーションの利点

JPAを使用した場合のデータアクセスモデル

JPAを使用しない場合のデータアクセスモデル

JPQL

JPQL使用時の注意事項

JPQLでのデータベースの参照および更新方法

JPQLでの悲観的ロック

JPQLとキャッシュの関係

JPQLのBNF

JPQLの記述方法

JPQLの構文

JSP事前コンパイルの設定

JSPのファイルインクルード時の注意事項

JSPのリロード

JTAによるトランザクション実装時の注意事項

(Ｌ)

lookupの実装（JavaBeansリソース）

(Ｍ)

managed

managed状態のエンティティ

Message-driven Bean（サービス）

Message-driven Bean（サービス）実行制御スレッド

Message-driven Bean（サービス）呼び出しスレッド

Message-driven Beanが使用するインタフェースの設定

Message-driven Beanとリソースアダプタの対応づけの設定

Microsoft IISの設定（Webリダイレクタ環境の場合）

(Ｎ)

new

NONE

(Ｏ)

O/Rマッピングファイルでのコールバックリスナの指定

OpenTP1からのアプリケーションサーバの呼び出し（TP1インバウンド連携機能）の機能

OpenTP1とOutboundで接続するための設定

OpenTP1とのInboundでの接続

OpenTP1のSPP

Oracle10gおよびOracle11gの場合の前提条件

Oracle10gの場合の前提条件

Oracle11gの場合の前提条件

Oracle9iの場合の前提条件

Oracle9iの場合の前提条件

Oracle RAC

Oracle RACを使用したOracleへの接続

Oracleと接続する場合の前提条件と注意事項

Oracleと接続する場合の注意事項

Oracleのキューに接続する場合の前提条件

ORDER BY節

OTS（Object Transaction Service）

Outbound

Outbound

Outboundで使用できる機能

(Ｐ)

Path式の注意事項

persistence.xmlの定義

PreparedStatementのプールサイズ

PTPメッセージングモデル

Pub/Subメッセージングモデル

(Ｑ)

QueryインタフェースのAPIで発生する例外

Queryオブジェクトの取得方法

Queryオブジェクトの取得方法

(Ｒ)

releaseメソッド

removed

RPC通信機能

RPC通信機能

Run as機能

(Ｓ)

SecurityManager

SecurityManagerによるWebコンテナの実行時の保護

SecurityManagerを解除する場合

SELECT節

SELECT節の実行結果

SELECT文

setCharacterEncodingメソッド

setFirstResultメソッド

setMaxResultsメソッド

SINGLE TABLE戦略

SMTPサーバとの接続

SoftWeak

SQL Serverと接続する場合の前提条件と注意事項

SQL Serverと接続する場合の注意事項

SQL Serverの場合の前提条件

SSL使用による認証情報とデータの暗号化

SSLで使用された証明書情報の取得

Synchronizationを使用する場合の注意事項

(Ｔ)

TP1/Message Queue

TP1/Message Queue - Accessによる接続

TP1インバウンドアダプタ

TP1インバウンドアダプタ

TP1インバウンド連携機能

TP1インバウンド連携機能

(Ｕ)

uCosminexus TP1 Connectorによる接続

UserTransactionインタフェースを使用する場合の処理概要と留意点

USRCONF_JVM_CLASSPATH

USRCONF_JVM_CLPATH

USRCONF_JVM_LIBPATH

USRCONF_JVM_LIBPATH

(Ｖ)

vbroker.agent.port

(Ｗ)

Weak

web.xmlを省略したWebアプリケーションに対する操作

webserver.connector.redirect_https.port

webserver.context.check_interval

webserver.context.reload_delay_timeout

webserver.context.update.interval

webserver.jsp.check_interval

webserver.jsp.update.interval

Webアプリケーション

Webアプリケーション単位，またはURLグループ単位の同時実行スレッド数制御を使用する場合

Webアプリケーションで指定できるアノテーション

Webアプリケーションの場合

Webアプリケーションのリロード

Webアプリケーションのリロード時のセッション情報の引き継ぎ

Webアプリケーションのリロード遅延実行

Webコンテナ

Webコンテナ単位の同時実行スレッド数制御を設定する場合

Webコンテナによるコネクション自動クローズ

Webサーバ

Webサーバの認証機能

Webサーバ連携

WHERE節

WHERE節で使用できる条件式

(Ｘ)

XDM/RD E2と接続する場合の前提条件と注意事項

(ア行)

(あ)

アーカイブ形式

アーカイブ形式のJ2EEアプリケーション

アーカイブ形式のJ2EEアプリケーション

アーカイブ形式のJ2EEアプリケーションのデプロイとアンデプロイ

アウトプロセス

アクセサメソッドの作成

アクセサメソッドのメソッドシグネチャ規則

アクセサメソッドへのビジネスロジックの追加

アノテーション

アノテーション

アノテーション参照抑止機能の設定変更

アノテーション参照抑止機能の目的と適用範囲

アノテーション使用時の注意事項

アノテーションで定義した内容の更新

アノテーションでのコールバックメソッドの指定

アノテーションの機能

アノテーションの更新

アノテーションの参照抑止

アノテーションの参照抑止機能

アノテーションの指定

アノテーションの使用

アノテーションを参照するタイミング

アノテーションを指定する場合のEnterprise Beanの実装

アノテーションを使用するメリットと指定できるアノテーション

アノテーションを宣言したライブラリJARのクラスの使用

アプリケーション開発時の注意事項

アプリケーションからEntityManagerFactoryをルックアップする方法

アプリケーションからEntityManagerをルックアップする方法

アプリケーション管理のEntityManagerを取得する方法

アプリケーション管理のEntityManagerを使用する場合の永続化コンテキスト

アプリケーションサーバ

アプリケーションサーバ 08-70での主な機能変更

アプリケーションサーバが管理するトランザクション

アプリケーションサーバが管理するトランザクションの外でコネクションシェアリングの有効化

アプリケーションサーバでJPAを使用するときの注意事項

アプリケーションサーバで実行できるアプリケーションの構成

アプリケーションサーバで使用するJPAの機能

アプリケーションサーバで使用できるJPAの機能

アプリケーションサーバ独自のConnector 1.5 API仕様

アプリケーションで扱う文字コード

アプリケーションディレクトリ

アプリケーションディレクトリの構成

アプリケーションディレクトリの作成例

アプリケーションディレクトリの変更

アプリケーションにEntityManagerFactoryをインジェクトする方法

アプリケーションにEntityManagerをインジェクトする方法

アプリケーションの実行基盤としての機能

アプリケーションの実行基盤を運用・保守するための機能

アプリケーションの属性管理

アプリケーションの属性管理

アプリケーションのデプロイ時にチェックされる項目

(い)

一時クローズ処理

一時クローズ処理によるコネクション数の調整

インプロセストランザクションサービス

インポート済みのJ2EEアプリケーションにリソースアダプタを追加する方法

(う)

埋め込み型クラス

埋め込み型クラスを利用する方法

(え)

永続化コンテキストからのエンティティの切り離しとmerge操作

永続化コンテキストの種類

永続化サブスクライバー

永続化フィールド

永続化フィールドおよび永続化プロパティのデフォルトマッピング規則

永続化フィールドおよびリレーションシップのバージョンチェック

永続化プロパティ

永続化ユニットとは

永続化ユニット名の参照スコープ

エラー発生時の動作

演算子の優先順位

エンティティオブジェクトのキャッシュ機能

エンティティクラスとデータベースの対応の定義

エンティティクラスとは

エンティティクラスの継承方法

エンティティクラスの作成

エンティティクラスの作成要件

エンティティクラスのフィールドに対するアクセス方法の指定

エンティティ継承階層構造の非エンティティのクラス

エンティティでのプライマリキーの指定

エンティティに対するpersist操作

エンティティに対するremove操作

エンティティに対する操作

エンティティに対する操作と状態遷移

エンティティに対する操作の伝播

エンティティのmerge処理

エンティティの永続化フィールドおよび永続プロパティの型

エンティティの状態の種類

エンティティのリレーションシップ

エンティティを使用したデータベースの更新

(お)

オブジェクトの自動クローズ

(カ行)

(か)

下位互換用のクラスローダ構成

開始状態のJ2EEアプリケーションを入れ替えた場合

稼働情報およびリソース枯渇監視情報を出力する場合の留意事項

稼働中のトランザクションの確認

関数式

管理対象オブジェクト（AdminObject）

管理対象オブジェクトの設定

管理対象オブジェクトのルックアップ

(き)

キー

機能とマニュアルの対応

機能の分類

キャッシュ機能の処理

キャッシュ機能の処理の流れ

キャッシュ機能の有効範囲

キャッシュ機能を使用するときの注意事項

キャッシュクリアのタイミング

キャッシュクリアの範囲

キャッシュのクリア

キャッシュの更新処理の流れ

キャッシュの参照形態とキャッシュタイプ

キャッシュの登録および更新のタイミング

キャッシュを使用する永続化コンテキストが複数ある場合の注意

キャッシング機能を使用するための設定

キャッシングの流れ

キュー

強参照

(く)

クエリ結果件数の範囲指定

クエリ結果の取得および実行

クエリ言語によるデータベース操作

クエリ言語を利用したデータベースの参照および更新方法

クエリ使用時に発生する例外

クエリでデータを更新または削除した場合の注意

クエリの実行時の注意事項

クエリのドメイン

クエリヒントの指定

クライアントからの検索

クライアント証明書と認証局（CA）の証明書の取得

クライアント証明書と認証局（CA）の証明書の取得

クライアント認証〔Webサーバの機能〕

クライアント認証の設定

クライアント認証の設定

クライアントのソースと検索先オブジェクトの設定の関係

クラスタコネクションプールの概要

クラスタコネクションプールの動作

クラスローダに設定されるクラスパス

クラスローダの構成

グローバルCORBAネーミングサービス

グローバルトランザクション

グローバルトランザクション

(け)

継承階層内での呼び出し順序

継承クラスの種類

継承マッピング戦略

結果セットマッピング

(こ)

更新検知インターバルの設定

更新検知によるリロード

更新検知の対象となるファイル

更新検知の対象ファイル

更新検知の対象ファイルの例

構成ファイル更新用インターバルの設定

コールバックメソッド使用時の注意事項

コールバックメソッドに適用されるルール

コールバックメソッドの実装

コールバックメソッドの指定個所

コールバックメソッドの指定方法

コールバックメソッドの除外について

コールバックメソッドの呼び出し順序

コネクションアソシエーション

コネクションアソシエーション

コネクションアソシエーションの条件

コネクションアソシエーションの定義

コネクション管理機能

コネクション管理機能

コネクション管理スレッド

コネクション管理スレッド

コネクション枯渇時のコネクション取得待ち

コネクション枯渇時のコネクション取得待ち

コネクションシェアリング

コネクションシェアリング・アソシエーション

コネクションシェアリングの条件

コネクションシェアリングの定義

コネクション自動クローズが実行されたことを確認する方法

コネクション障害検知のタイムアウトを有効にした場合の注意事項

コネクションスイーパ

コネクションスイーパ

コネクションスイーパ

コネクションスイーパの動作

コネクション数調節機能

コネクション数調節機能

コネクション定義識別子

コネクション定義に指定できる要素と指定個所

コネクション定義の複数指定

コネクションの最小値と最大値

コネクションの自動クローズ

コネクションの自動クローズ

コネクションの取得リトライ

コネクションの取得リトライ

コネクションの障害検知

コネクションの障害検知

コネクションプーリング

コネクションプーリング

コネクションプーリングで使用できる機能

コネクションプーリングの動作

コネクションプールの一時停止

コネクションプールのウォーミングアップ

コネクションプールのウォーミングアップ

コネクションプールのクラスタ化機能

コネクションプールのクリア

コネクションプールの再開

コネクションプールの終了処理

コネクションプールの状態によるコマンド実行の可否

コネクションプールの状態の確認

コネクションプールの情報表示

コネクションプールの生成および初期化

コネクションプール利用上の注意事項

コネクションプールをクラスタ化するために必要な設定

コネクションプールを使用する場合の留意事項

コマンドで作成する送信先

コマンドによるJ2EEアプリケーションのリロード

コマンドによるリロード

コレクションメンバの宣言

コンシューマー

コンストラクタ式

コンテナ拡張ライブラリ

コンテナ拡張ライブラリ

コンテナ拡張ライブラリ

コンテナ拡張ライブラリおよびサーバ起動・停止フック機能利用時の制限事項

コンテナ拡張ライブラリの機能

コンテナ拡張ライブラリの機能

コンテナ拡張ライブラリの機能を使用するための設定

コンテナ拡張ライブラリの作成と利用の流れ

コンテナ拡張ライブラリの利用

コンテナ拡張ライブラリ利用の検討

コンテナ管理サインオン

コンテナ管理でのサインオン

コンテナ管理のEntityManager

コンテナ管理のEntityManagerを取得する方法

コンテナ管理のEntityManagerを使用する場合の永続化コンテキスト

コンテナ管理のトランザクション（CMT）を使用する場合の処理概要と留意点

コンテナセキュリティとアクセス権管理

コンポーネント管理サインオン

コンポーネント管理でのサインオン

(サ行)

(さ)

サーバ管理コマンド

サーバ管理コマンドを使用した定義の参照と更新

サーバ起動・停止フック機能

サーバ起動・停止フック機能

サーバ起動・停止フック機能

サーバ起動・停止フック機能の実装方法

サーバ起動・停止フック機能利用時のクラスパスの指定

サーバ起動・停止フック処理の呼び出し順序

サーバ認証〔Webサーバの機能〕

サーブレットおよびJSPのサービスメソッド

サブスクライバー

サポートするアプリケーションの形式

サポートするクラスローダ構成

参照解決方法の優先順位

(し)

システム運用時の注意事項

システム構築時の注意事項

システムでの文字コード変換時の注意

システムの目的と機能の対応

システム例外発生時のクライアントトランザクションの動作

システム例外発生時のトランザクションの動作

実行できるJ2EEアプリケーションの形式

自動的にバインドされる名称でのルックアップ

弱参照

集合関数

受信タイマ監視スレッド

手動によるコネクションプールの停止・開始の流れ

障害検知のタイムアウト

障害検知を実施するタイミング

障害調査用SQL

障害調査用SQLの出力

使用するリソースアダプタ

使用できるJ2EEコンポーネントおよび機能

使用できるJPAプロバイダ

使用できる機能

使用できるコンポーネント

使用できるリソースアダプタ

使用方法ごとに使用できるリソースアダプタ

(す)

スケジュール機能

スケジュール機能

スケジュールキュー

ステータスファイルの格納ディレクトリ

ステートメントキャンセル

ステートメントキャンセル

ステートメントキャンセル

ステートメントプーリング

ステートメントプーリング機能のステートメントの初期化

ステートメントプーリング機能を使用する場合の注意事項

ステートメントプーリングの動作

スマートエージェントが使用する通信ポート

スマートエージェントが使用する通信ポート

スマートエージェント経由でのCORBAオブジェクトの呼び出し

スレッドプーリング

スレッドプール

(せ)

セキュリティアイデンティティ

セキュリティアイデンティティの機能

セキュリティアイデンティティを使用した認証

セキュリティアイデンティティを使用した認証の設定

セキュリティ管理

セキュリティ管理の機能

セキュリティポリシーの設定を変更する場合

セッション

セッション情報ファイル

セッション情報ファイル

セッション情報ファイル出力先の変更

セッション情報を引き継ぐ場合の注意事項

接続できるデータベース

接続できるデータベース

接続できるデータベース

接続テスト機能

接続にリソースアダプタを使用しないリソース

接続にリソースアダプタを使用するリソース

センダー

(そ)

送信先

双方向のManyToManyリレーションシップ

双方向のManyToOne/OneToManyリレーションシップ

双方向のOneToOneリレーションシップ

属性の管理

属性ファイルの指定例

そのほかのリソースアダプタの機能（Connector 1.5仕様に準拠するリソースアダプタの場合）

そのほかのリソースとの接続

そのほかのリソースとの接続で使用できる機能

そのほかのリソースとの接続に使用するリソースアダプタ

ソフト参照

(タ行)

(た)

単方向のManyToManyリレーションシップ

単方向のManyToOneリレーションシップ

単方向のMulti-Valuedリレーションシップ

単方向のOneToManyリレーションシップ

単方向のOneToOneリレーションシップ

単方向のSingle-Valuedリレーションシップ

(ち)

抽象エンティティクラス

抽象スキーマ型

抽象スキーマ名

(つ)

通常モード

通信に使用するIPアドレス

通信路のセキュリティレベルの要請

(て)

停止状態のJ2EEアプリケーションを入れ替えた場合

停止中のトランザクションの確認

データ更新の有無のチェック方法

データソース

データソースの指定の注意

データベースからのエンティティ情報の読み込み

データベースからのエンティティ情報を読み込むタイミング

データベースからのエンティティの取得

データベースコネクション確立までの待ち時間

データベース上のキューとの接続

データベースとアプリケーション間の文字コード変換

データベースとの同期

データベースへのエンティティ情報の書き込み

データベースへの接続

テストモード

デッドメッセージ

デッドメッセージキュー

デフォルトのクラスローダ構成

デフォルトマッピング（双方向のリレーションシップ）

デフォルトマッピング（単方向のリレーションシップ）

デプロイ

デプロイメントに関する規約

展開ディレクトリ形式

展開ディレクトリ形式のJ2EEアプリケーション

展開ディレクトリ形式のJ2EEアプリケーション

展開ディレクトリ形式のJ2EEアプリケーションのデプロイとアンデプロイ

展開ディレクトリ形式のJ2EEアプリケーションを使用するための設定（セキュリティの設定変更）

展開ディレクトリ形式の概要

展開ディレクトリ形式を使用する場合の注意事項

電文組み立てリスト

(と)

同期点処理

同期点電文

トピック

トランザクショナルRPC

トランザクションインフロー

トランザクション管理

トランザクショングローバル識別子

トランザクションサービス

トランザクションサービスで提供する機能

トランザクションサポートレベル

トランザクションサポートレベル

トランザクション識別子

トランザクション情報の確認

トランザクションタイムアウト

トランザクションタイムアウト（J2EEサーバ単位）

トランザクションタイムアウトの設定単位

トランザクションの種類

トランザクションの種類

トランザクションの制御とEntityManager

トランザクションのリカバリ

トランザクションのリカバリ

トランザクションマネージャ

トランザクションマネージャの取得

トランザクションマネージャを使用する場合の注意事項

トランザクションリカバリ

トランザクションリカバリ用通信ポート

トランザクションリカバリをする場合の留意事項

トランザクション連携機能

トランザクションを使用しない場合の処理概要と留意点

(ナ行)

(に)

任意のメッセージリスナインタフェースを使用したMessage-driven Beanおよびリソースアダプタの場合

認証機能を併用するときの注意

(ね)

ネイティブクエリ結果の取得および実行

ネイティブクエリでのデータベースの参照および更新方法

ネーミング管理

ネーミング管理

ネーミング管理機能でのキャッシング

ネーミング管理の概要

ネーミング管理の機能

ネーミング管理の機能

ネーミング切り替え

ネーミングサービス

ネーミングサービス

ネーミングサービス

ネーミングサービスの障害検知

ネーミングサービスの障害検知機能とは

ネーミングサービスの障害検知機能の挙動

ネーミングサービスの障害検知機能の注意事項

ネーミングサービスの通信タイムアウト

ネーミングでのキャッシングの注意事項

(ハ行)

(は)

パス式

パフォーマンスチューニングのための機能

パブリッシャー

バルクDELETE文

バルクUPDATE文

範囲変数宣言と識別変数

(ひ)

非保護区

秘密鍵の作成と認証局が発行した証明書の取得

秘密鍵の作成と認証局が発行した証明書の取得

(ふ)

ファイアウォール環境での運用のための機能

ファイアウォール環境での運用のための設定

フォールトトレランスのための機能

複合型のプライマリキー

複数のJ2EEサーバでのアプリケーションディレクトリの共有

物理コネクション

物理コネクション

プライマリキー値の自動採番

プライマリキーの型

ブラウザとアプリケーション間の文字コード変換

ブラウザとアプリケーション間の文字コード変換で使用するメソッド

フラッシュモードの指定

フリーファイル

プログラムセキュリティ

プロデューサー

(へ)

別名

別名が登録または削除されるタイミング

別名の重複

別名の付与規則

別名を付けられる対象

(ほ)

保護区

(マ行)

(ま)

マップドスーパークラス

(み)

未決着トランザクション

未決着トランザクションの確認時間のタイムアウト

(め)

メソッドキャンセル機能

メソッドタイムアウト機能

メッセージインフロー

メッセージインフロー

メッセージインフローの制御の流れ（Non-Transacted Deliveryの場合）

メッセージインフローの制御の流れ（Transacted Deliveryの場合）

メッセージエンドポイントのアンデプロイ

メッセージエンドポイントのデプロイ

メッセージセレクター

メッセージ配送をするときのリソースアダプタの処理

メッセージリスナのメソッド

メンバコネクションプールの状態

メンバコネクションプールの状態遷移（自動で一時停止が実行される場合）

メンバコネクションプールの状態遷移（手動で一時停止を実行する場合）

メンバリソースアダプタ

(も)

文字コード

(ヤ行)

(ゆ)

ユーザが直接管理するトランザクション（アプリケーションサーバが管理しないトランザクション）

ユーザサービスネットワーク定義によるスケジューラダイレクト機能

ユーザ指定名前空間機能

ユーザ指定名前空間機能

ユーザ指定名前空間機能

ユーザ指定名前空間機能

ユーザ指定名前空間機能

ユーザ指定名前空間機能を使用する場合の注意事項

ユーザ指定名前空間機能を利用して付与した別名でのルックアップ

(よ)

用語解説

(ラ行)

(ら)

ライトトランザクション

ライトトランザクション

ライトトランザクション機能

ライフサイクル管理機能を使用するときの注意

ライフサイクル管理に使用するクラス

ライブラリJAR

ラウンドロビン検索

ラウンドロビン検索

ラウンドロビン検索機能との併用

ラウンドロビン検索機能を使用する場合の推奨する設定

ラウンドロビン検索の動作

ラウンドロビン検索の範囲

ラウンドロビン検索をするために必要な設定

ラウンドロビン検索をする場合の注意事項

ラウンドロビンポリシー

ラウンドロビンポリシーによるCORBAネーミングサービスの検索

楽観的ロック

楽観的ロックに失敗した場合の例外処理

楽観的ロックの処理

楽観的ロックを使用する際の注意事項

ランタイムに関する規約

(り)

リクエスト受け付けスレッド

リソースアダプタ

リソースアダプタ以外の機能

リソースアダプタ以外を使用する接続の設定

リソースアダプタごとのRARファイルの種類

リソースアダプタ固有のトランザクション管理インタフェースを使用する場合の処理概要と留意点

リソースアダプタについての注意事項

リソースアダプタの入れ替えの流れ

リソースアダプタの機能

リソースアダプタの種類

リソースアダプタの使用方法

リソースアダプタの新規設定の流れ

リソースアダプタの設定の流れ（Inboundで使用する場合）

リソースアダプタの設定の流れ（J2EEアプリケーションに含めて使用する場合）

リソースアダプタの設定の流れ（J2EEリソースアダプタとしてデプロイして使用する場合）

リソースアダプタの設定の流れ（コネクションプールのクラスタ化をする場合）

リソースアダプタの設定変更の流れ

リソースアダプタの設定方法

リソースアダプタのライフサイクル管理

リソースアダプタのライフサイクル管理

リソースアダプタの利用方法とトランザクションレベルの対応

リソースアダプタのワーク管理

リソースアダプタのワーク管理

リソースアダプタをJ2EEアプリケーションに含めて使用する場合

リソースアダプタをJ2EEサーバに直接デプロイして使用する場合

リソースアダプタを含めたJ2EEアプリケーションをJ2EEサーバにインポートする方法

リソース接続

リソース接続でのトランザクション管理の方法

リソース接続とトランザクション管理

リソース接続とトランザクション管理の概要

リソース接続とトランザクション管理の機能

リソースに接続するための実装

リソースへのサインオン方式

リソースへの接続テスト

リソースへの接続テストをする場合の留意事項

リソースへの接続方法

リソースマネジャ

リソースを参照する仕組みと使い方（resource-ref）

リデプロイ

リデプロイ機能

リデプロイによるJ2EEアプリケーションの入れ替え

リデプロイによるJ2EEアプリケーションの入れ替えの注意事項

リテラルの注意事項

リモートインタフェース

リレーションシップのアノテーション

リレーションシップの種類

リレーションシップの方向

リロード

リロード機能

リロード機能の適用範囲の設定

リロード時のクラスローダの構成

リロード遅延実行の設定

リロードとJ2EEアプリケーション実行時間の監視との関係

リロードと同時実行スレッド数制御との関係

リロードの対象となる操作

リロードの注意事項および制限事項

リロードの適用範囲

(る)

ルートリソースアダプタ

ルックアップで使用する名称の種類

ルックアップの対象にする管理対象オブジェクトの設定

(れ)

例外が発生したコネクションの破棄

レシーバー

(ろ)

ローカルインタフェース

ローカルトランザクション

ローカルトランザクション

ローカル呼び出し最適化時のクラスローダ構成

ロード対象のクラスとロード時に必要なクラスパス

ロール

ロールに基づくWebコンテナのユーザ認証

ロールに基づくWebコンテナのユーザ認証の機能

論理コネクション

論理コネクション

論理ネーミングサービス

(ワ行)

(わ)

ワーク管理機能を使用するときの注意

ワーク管理の開始処理と終了処理

■ 商標類

Active Directoryは，米国Microsoft Corporationの，米国およびその他の国における登録商標または商標です。
AIXは，米国およびその他の国におけるInternational Business Machines Corporationの商標です。
AIX 5Lは，米国およびその他の国におけるInternational Business Machines Corporationの商標です。
AMDは，Advanced Micro Devices, Inc.の商標です。
AX2000は，A10 Networks, Inc.の商品名称です。
Borlandのブランド名および製品名はすべて，米国Borland Software Corporationの米国およびその他の国における商標または登録商標です。
CORBAは，Object Management Groupが提唱する分散処理環境アーキテクチャの名称です。
HP-UXは，Hewlett-Packard Companyのオペレーティングシステムの名称です。
IIOPは，OMG仕様によるORB(Object Request Broker)間通信のネットワークプロトコルの名称です。
Internet Explorerは，米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
Itaniumは，アメリカ合衆国およびその他の国におけるIntel Corporationの商標です。
J2EEは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Javaは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
JavaScriptは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
JDBCは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
JDKは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
JSPは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Linuxは，Linus Torvalds氏の日本およびその他の国における登録商標または商標です。
Microsoftは，米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
Microsoft Internet Information Servicesは，米国Microsoft Corporationの商品名称です。
MyEclipseは，米国Genuitec社の商品名称です。
OMG，CORBA，IIOP，UML，Unified Modeling Language，MDA，Model　Driven　Architectureは，Object Management Group, Inc.の米国及びその他の国における登録商標または商標です。
ORACLEは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Oracle及びOracle 10gは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Oracle及びOracle9iは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Oracle及びOracle Database 10gは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Oracle及びOracle Database 11gは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Red Hatは，米国およびその他の国でRed Hat, Inc. の登録商標もしくは商標です。
Solarisは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
すべてのSPARC商標は，米国SPARC International, Inc. のライセンスを受けて使用している同社の米国およびその他の国における商標または登録商標です。SPARC商標がついた製品は，米国Sun Microsystems, Inc. が開発したアーキテクチャに基づくものです。
SQL Serverは，米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
Sunは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
Sun Microsystemsは，Oracle Corporation 及びその子会社，関連会社の米国 及びその他の国における登録商標または商標です。
UNIXは，The Open Groupの米国ならびに他の国における登録商標です。
Windowsは，米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
Windows Serverは，米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
Windows Vistaは，米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
X/Openは，The Open Groupの英国ならびに他の国における登録商標です。
Eclipseは，開発ツールプロバイダのオープンコミュニティであるEclipse Foundation, Inc.により構築された開発ツール統合のためのオープンプラットフォームです。
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).