Oracle® Fusion Middleware Oracle WebLogic Serverリソース・アダプタの開発

12c (12.1.2)

E48055-01(原本部品番号:E28112-01)

目次

タイトルおよび著作権情報

はじめに

- ドキュメントのアクセシビリティについて

- 表記規則

1 概要とロードマップ

- ドキュメントのスコープと対象読者

- このドキュメントの手引き

- 関連ドキュメント

- リソース・アダプタ開発者向けのサンプル

- このリリースでの新機能と変更点

2 リソース・アダプタの理解

- リソース・アダプタの概要

- WebLogic ServerとWebLogic Integrationのリソース・アダプタの比較

- インバウンド、アウトバウンド、および双方向のリソース・アダプタ

- 1.0リソース・アダプタと1.5および1.6との比較

- コネクタ・アーキテクチャ1.6のサポート

- WebLogic Serverコネクタ・コンテナによって提供される追加サポート

- Java EEコネクタ・アーキテクチャ

- Java EEコネクタ・アーキテクチャの図とコンポーネント

- システム・レベル規約

- リソース・アダプタ・デプロイメント記述子

3 リソース・アダプタの作成と構成

- リソース・アダプタの作成と構成:主な手順

- 既存のリソース・アダプタの変更

- ra.xmlファイルの構成

- ra.xmlファイルの手動作成

- デプロイメント情報を指定するメタデータ注釈の使用

- リソース・アダプタのXMLスキーマ定義

- weblogic-ra.xmlファイルの構成

- リソース・アダプタ・デプロイメント記述子の編集

- 編集の考慮事項

- スキーマ・ヘッダー情報

- デプロイメント記述子ファイルのスキーマへの準拠

- 動的な記述子の更新:コンソールの「構成」タブ

- 動的に再構成できる構成プロパティ

- 動的な構成パラメータ

- 動的なプール・パラメータ

- 動的なロギング・パラメータ

- weblogic-ra.xmlファイルの自動生成

- (非推奨) Link-Refメカニズムの構成

- Bean検証の構成ファイル

- 長時間実行するWorkのサポート

- ツールのサポート

- リソース・アダプタのヘルス監視

- リソース・アダプタのヘルス状態の取得

- ヘルス監視に関するデプロイ要件

4 プログラミング・タスク

- リソース・アダプタに必要なクラス

- 汎用ワーク・コンテキスト

- 汎用ワーク・コンテキストをサポートするために追加されたインタフェース、クラスおよびメソッド

- 汎用ワーク・コンテキストをサポートするために追加されたデプロイメント記述子要素

- 起動クラスとして実行するためのリソース・アダプタのプログラミング

- リソース・アダプタの最小限のコンテンツ

- Workインスタンスの送信

- Work送信の再試行

- リソース・アダプタのアクティビティの中断と再開

- 拡張されたBootstrapContext

- 診断コンテキストID

- 仕分けビット

- コールバック機能

- Beanの検証

- BeanManager

- 管理対象オブジェクトの一意性

5 リソース・アダプタでのContexts and Dependency Injectionの使用

- 概要

- リソース・アダプタBeanの検出

- リソース・アダプタBeanのコンテキスト参照の取得

- 他のアプリケーション・タイプからのリソース・アダプタBeanの呼出し

- CDI Beanアーカイブとしてデプロイされたリソース・アダプタの使用

- BeanManagerのサポート

- インジェクション・ポイント

- リソース・アダプタ・コンポーネントBeanでのCDIの使用

- リソース・アダプタ・コンポーネントBeanを管理対象Beanにしない

- 依存関係インジェクションの使用

- インジェクションの使用に関する注意事項

- 例

6 接続管理

- 接続管理規約

- 接続ファクトリと接続

- JNDIツリーにバインドされたリソース・アダプタ

- Connectionfactoryの取得(クライアントとJNDI間の対話)

- トランザクション・サポート・レベルの指定および取得

- 共有不可能なManagedConnectionFactoryの指定

- アウトバウンド接続の構成

- 接続プールの構成レベル

- 接続の再試行

- アダプタの再デプロイなしの、アウトバウンド接続プール・エラーの
分離、トラブルシューティングおよび修正

- deploy-as-a-wholeオプションの使用

- 失敗した接続プールのトラブルシューティング

- 接続プールの回復手順

- 失敗した接続プールを回復するためのその他のオプション

- 複数のアウトバウンド接続の例

- インバウンド接続の構成

- 接続プール・パラメータの構成

- initial-capacity : ManagedConnectionの初期数の設定

- max-capacity : ManagedConnectionの最大数の設定

- capacity-increment : ManagedConnectionの数の制御

- shrinking-enabled :システム・リソースの使用量の制御

- shrink-frequency-seconds :未使用のManagedConnectionの再利用を試みるまで
待機する時間の設定

- highest-num-waiters:接続を待機するクライアントの数
の制御

- highest-num-unavailable :使用できない接続の数の制御

- connection-creation-retry-frequency-seconds :接続の再作成

- match-connections-supported :接続のマッチング

- test-frequency-seconds :接続の有効性のテスト

- test-connections-on-create :作成時の接続のテスト

- test-connections-on-release: 接続プールへの解放時の
接続のテスト

- test-connections-on-reserve :予約時の接続のテスト

- deploy-as-a-whole: アダプタ・デプロイメント全体からの
アウトバウンド接続プール・エラーの分離

- 接続プロキシ・ラッパー - 1.0リソース・アダプタ

- 発生する可能性のあるClassCastException

- プロキシ生成の有効化および無効化

- 接続プールのリセット

- 接続のテスト

- 接続のテストの構成

- 管理コンソールでの接続のテスト

7 トランザクション管理

- サポートされているトランザクション・レベル

- XAトランザクションのサポート

- ローカル・トランザクションのサポート

- トランザクション・サポートなし

- 実行時トランザクション・サポート・レベルの仕様

- トランザクション・レベルの構成

- XAトランザクション・リカバリの資格証明マッピングの構成

8 メッセージ・インフローとトランザクション・インフロー

- メッセージ・インフローとトランザクション・インフローの概要

- アーキテクチャのコンポーネント

- インバウンド通信のシナリオ

- メッセージ・インフローの仕組み

- インバウンド・メッセージの処理

- 独自の通信チャネルとプロトコル

- メッセージ・エンドポイント(メッセージドリブンBean)へのメッセージ・インフロー

- MDBとリソース・アダプタのデプロイメント時のバインド

- MDBとリソース・アダプタのバインド

- メッセージのディスパッチ

- アクティブ化仕様

- 管理対象オブジェクト

- トランザクション・インフロー

- ローカルで管理されるトランザクションでのトランザクション・インフロー・モデルの使用

- 長時間実行するWorkの構成および管理

- 同時に長時間実行するWorkインスタンスの最大数の設定

- 長時間実行するWorkの監視

9 セキュリティ

- コンテナ管理およびアプリケーション管理によるサインオン

- アプリケーション管理によるサインオン

- コンテナ管理によるサインオン

- アウトバウンド接続のための資格証明マッピング

- 認証メカニズム

- アウトバウンド資格証明マッピング

- 非初期接続: アプリケーションのリクエストに応じて、アダプタからの
ManagedConnectionが必要

- 初期接続: アプリケーションのリクエストがない場合、アダプタからの
ManagedConnectionが必要

- 特殊なユーザー

- コンソールを使用したアウトバウンド資格証明マッピングの作成

- セキュリティ・インフロー

- インバウンド・プリンシパル・マッピング

- セキュリティ・インフロー・コールバック要件

- コネクタ・アーキテクチャ1.5および1.0に対する下位互換性

- セキュリティ・ポリシーの処理

- リソース・アダプタのセキュリティIDの構成

- default-principal-name :デフォルトID

- manage-as-principal-name :管理タスク実行用のID

- run-as-principal-name: コネクタ・コンテナからリソース・アダプタへの接続呼出しに
使用されるID

- run-work-as-principal-name: リソース・アダプタの管理タスクを
実行するためのID

- 接続ファクトリに固有の認証および再認証メカニズムの
構成

10 リソース・アダプタのパッケージ化とデプロイ

- リソース・アダプタのパッケージ化

- ディレクトリ構造のパッケージ化

- パッケージ化の考慮事項

- パッケージ化の制限

- リソース・アダプタ・アーカイブ(RAR)のパッケージ化

- リソース・アダプタのデプロイ

- デプロイメント・オプション

- リソース・アダプタのデプロイメント名

- 本番再デプロイメント

- Suspendableインタフェースと本番再デプロイメント

- 本番再デプロイメントの要件

- 本番再デプロイメントのプロセス

- 複数のアウトバウンド接続プールで構成されたリソース・アダプタの
デプロイ

A weblogic-ra.xmlスキーマ

- weblogic-connector

- work-manager

- connector-work-manager

- security

- default-principal-name

- manage-as-principal-name

- run-as-principal-name

- run-work-as-principal-name

- security-work-context

- caller-principal-default-mapped

- caller-principal-mapping

- group-principal-mapping

- properties

- admin-objects

- admin-object-group

- admin-object-instance

- outbound-resource-adapter

- default-connection-properties

- pool-params

- logging

- connection-definition-group

- connection-instance

B リソース・アダプタのベスト・プラクティス

- リソース・アダプタのクラスローディングの最適化

- 接続の最適化

- スレッド管理

- InteractionSpecインタフェース

- javax.jms.ConnectionFactoryの使用

Oracle® Fusion Middleware

Oracle WebLogic Serverリソース・アダプタの開発

12c (12.1.2)

E48055-01(原本部品番号:E28112-01)

2013年6月

リソース・アダプタのユーザー、デプロイヤ、ソフトウェア開発者を対象としたマニュアル。WebLogic ServerにデプロイされるJava EEリソース・アダプタを含むアプリケーションの開発方法を説明しています。

Oracle Fusion Middleware Oracle WebLogic Serverリソース・アダプタの開発, 12c (12.1.2)

E48055-01

Copyright © 2007, 2013, Oracle and/or its affiliates.All rights reserved.

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations.As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.

このソフトウェアもしくはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアもしくはハードウェアは、危険が伴うアプリケーション(人的傷害を発生させる可能性があるアプリケーションを含む)への用途を目的として開発されていません。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性(redundancy)、その他の対策を講じることは使用者の責任となります。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

OracleおよびJavaはOracle Corporationおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

はじめに

ここでは、このガイド『Oracle WebLogic Serverリソース・アダプタの開発』で使用されるドキュメントのアクセシビリティ機能と表記規則について説明します。

ドキュメントのアクセシビリティについて

Oracleのアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWebサイトhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=docaccを参照してください。

Oracleサポートへのアクセス

Oracleのお客様は、My Oracle Supportから電子サポートにアクセスできます。詳細情報はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=infoか、聴覚に障害のあるお客様はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trsを参照してください。

表記規則

このドキュメントでは次の表記規則を使用します。

規則

意味

太字

太字は、操作に関連するGraphical User Interface要素、または本文中で定義されている用語および用語集に記載されている用語を示します。

斜体

イタリックは、ユーザーが特定の値を指定するプレースホルダー変数を示します。

固定幅フォント

固定幅フォントは、段落内のコマンド、URL、サンプル内のコード、画面に表示されるテキスト、または入力するテキストを示します。

1 概要とロードマップ

このマニュアルでは、Java EEリソース・アダプタを含むアプリケーションの開発方法とWebLogic Serverへのデプロイ方法について説明します。これは、リソース・アダプタのユーザー、デプロイヤおよびソフトウェア開発者を対象としています。また、WebLogic Serverを評価するビジネス・アナリストや、特定のアプリケーションでWebLogic Serverリソース・アダプタの使用を考えているシステム設計者にとって便利な情報も掲載されています。

次の項では、『Oracle WebLogic Serverリソース・アダプタの開発』の内容と構成について説明します。

- ドキュメントのスコープと対象読者

- このドキュメントの手引き

- 関連ドキュメント

- リソース・アダプタ開発者向けのサンプル

- このリリースでの新機能と変更点

ドキュメントのスコープと対象読者

このドキュメントのトピックでは、ソフトウェア・プロジェクトの設計および開発段階に関連する情報を提供します。また、プロジェクトのテストおよび本番前の段階で見つかるアプリケーションの問題を解決するうえで便利なトピックもあります。

このドキュメントでは、本番段階での管理、モニター、パフォーマンス・チューニングについては扱いません。これらのトピックに関するWebLogic Serverのドキュメントとリソースへのリンクについては、「関連ドキュメント」を参照してください。

このマニュアルは、Java EEおよびリソース・アダプタの概念に精通している読者を対象としています。リソース・アダプタ開発の基礎となるドキュメントは、『JSR 322: Java EE Connector Architecture 1.6 (Final Release)』です。http://jcp.org/aboutJava/communityprocess/final/jsr322/index.htmlを参照してください。リソース・アダプタの開発者は、Java EEコネクタ・アーキテクチャ1.6仕様をよく理解する必要があります。このドキュメント『Oracle WebLogic Serverリソース・アダプタの開発』では、WebLogic Serverリソース・アダプタの付加価値機能と、WebLogic Server機能を使用してリソース・アダプタを起動および実行する方法についての主要な情報を重点的に扱います。

このドキュメントの手引き

- この項、第1章「概要とロードマップ」では、このドキュメントの構成を紹介します。

- 第2章「リソース・アダプタの理解」では、Java EEコネクタ・アーキテクチャのOracle WebLogic Server実装と、リソース・アダプタの種類やXMLスキーマについて紹介します。

- 第3章「リソース・アダプタの作成と構成」では、Java EEコネクタ・アーキテクチャのOracle WebLogic Server実装を使用してリソース・アダプタを作成する方法について説明します。

- 第4章「プログラミング・タスク」では、リソース・アダプタのプログラミング・タスクについて説明します。

- 第5章「リソース・アダプタでのContexts and Dependency Injectionの使用」では、リソース・アダプタBeanでのContexts and Dependency Injection (CDI)に対するWebLogic Serverのサポートについて説明します。

- 第6章「接続管理」では、リソース・アダプタの接続管理について紹介します。

- 第7章「トランザクション管理」では、リソース・アダプタのトランザクション管理について紹介します。

- 第8章「メッセージ・インフローとトランザクション・インフロー」では、リソース・アダプタのメッセージング・インフローとトランザクション・インフローについて説明します。

- 第9章「セキュリティ」では、リソース・アダプタのセキュリティの構成方法について説明します。

- 第10章「リソース・アダプタのパッケージ化とデプロイ」では、リソース・アダプタのパッケージ化とデプロイの要件について説明し、これらのタスクを実行する手順を示します。

- 付録A「weblogic-ra.xmlスキーマ」は、WebLogic Server固有のデプロイメント記述子weblogic-ra.xmlのスキーマに関する詳細なリファレンスです。

- 付録B「リソース・アダプタのベスト・プラクティス」では、リソース・アダプタ開発者向けのベスト・プラクティスを示します。

関連ドキュメント

リソース・アダプタ開発の基礎となるドキュメントは、『JSR 322: Java EE Connector Architecture 1.6』です。『Oracle WebLogic Serverリソース・アダプタの開発』では、読者がJava EEコネクタ・アーキテクチャ仕様を理解していることが前提です。この仕様には、WebLogic Serverリソース・アダプタの開発に固有の設計や開発の情報が含まれます。

WebLogic Serverアプリケーションを開発、デプロイ、およびモニターするための包括的なガイドラインについては、以下のドキュメントを参照してください。

- 『Oracle WebLogic Serverアプリケーションの開発』は、WebLogic Serverアプリケーションの開発ガイドです。

- 『Oracle WebLogic Serverへのアプリケーションのデプロイ』は、WebLogic Serverアプリケーションのデプロイメントについての主要な情報源です。

- 『Oracle WebLogic Serverのパフォーマンスのチューニング』は、WebLogic Serverアプリケーションのパフォーマンスをモニターして改善するための情報を提供します。

リソース・アダプタ開発者向けのサンプル

このマニュアルに加えて、ソフトウェア開発者向けにリソース・アダプタのサンプルが用意されています。WebLogic Serverでは、必要に応じてAPIサンプル・コードをEXAMPLES_HOME/wl_server/examples/src/examplesにインストールできます。EXAMPLES_HOMEは、WebLogic Serverのサンプル・コードがインストールされている最上位ディレクトリです。WebLogic Serverのサンプル・コードの詳細は、『Oracle WebLogic Serverの理解』のサンプル・アプリケーションとサンプル・コードに関する項を参照してください。

このリリースのWebLogic Serverではリソース・アダプタのサンプルが2セット提供されています。1つは1.5コネクタ・アーキテクチャに準拠し、もう1つは1.6コネクタ・アーキテクチャに準拠します(Java EE 6サンプルに含まれます)。独自のリソース・アダプタを開発する前に、このリソース・アダプタ・サンプルを検討および実行して理解しておくことをお薦めします。

このリリースでの新機能と変更点

複数の接続プールで構成されているリソース・アダプタには、このリリースで、デプロイ時に正常な接続プールから失敗した接続プールを分離する機能が追加されました。これにより、リソース・アダプタを再デプロイすることなく、失敗した接続プールを修正できます。詳細は、「リソース・アダプタのヘルス監視」を参照してください。

WebLogic Serverのこのリリースに追加された新機能の一覧については、『Oracle WebLogic Serverの新機能』を参照してください。

2 リソース・アダプタの理解

この章では、エンタープライズ情報システム(EIS)に接続するためのWebLogic Serverリソース・アダプタや、リソース・アダプタが基づいているJava EEコネクタ・アーキテクチャについて説明します。また、WebLogic Serverにデプロイされるリソース・アダプタの構造や実行時の動作を定義するデプロイメント記述子についても説明します。

この章の内容は以下のとおりです。

- リソース・アダプタの概要

- Java EEコネクタ・アーキテクチャ

- リソース・アダプタ・デプロイメント記述子

リソース・アダプタの概要

リソース・アダプタは、エンタープライズ情報システム(EIS)に固有のシステム・ライブラリであり、EISへの接続を提供します。リソース・アダプタはデータベース管理システムへの接続を提供するJDBCドライバに似ています。リソース・アダプタとEIS間のインタフェースは基底のEISに固有のものであり、ネイティブ・インタフェースの場合もあります。リソース・アダプタはWebLogic Serverなどのアプリケーション・サーバーに接続し、EIS、アプリケーション・サーバー、およびエンタープライズ・アプリケーションの間にシームレスな接続を提供します。

1つのアプリケーション・サーバーに複数のリソース・アダプタを接続できます。それによって、アプリケーション・サーバーにデプロイされたアプリケーション・コンポーネントが基底のEISにアクセスできます。すべてのシステム・レベルのメカニズム(トランザクション、セキュリティ、接続管理など)がアプリケーション・コンポーネントからは意識されないように、アプリケーション・サーバーとEISが共同で作業を行います。したがって、アプリケーション・コンポーネント・プロバイダは、アプリケーション・コンポーネントのビジネス・ロジックやプレゼンテーション・ロジックの開発に専念でき、EISの統合に関連したシステム・レベルの問題に関わる必要はありません。複数のEISと接続する必要のある、スケーラブルでセキュアなトランザクション対応のエンタープライズ・アプリケーションを、より簡単に短期間で開発できるようになります。

WebLogic ServerとWebLogic Integrationのリソース・アダプタの比較

WebLogic Integration (WLI)リソース・アダプタとWebLogic Serverリソース・アダプタの違いに注意することが重要です。WebLogic Integrationリソース・アダプタはWebLogic Server用に記述されるもので、通常は他のアプリケーション・サーバーにはデプロイできません。一方、WLIの拡張機能を利用せずに記述されたWebLogic Serverリソース・アダプタは、Java EEに準拠したアプリケーション・サーバーにデプロイできます。このドキュメントでは、非WLIリソース・アダプタの設計と実装について説明します。

インバウンド、アウトバウンド、および双方向のリソース・アダプタ

WebLogic Serverは3種類のリソース・アダプタをサポートしています。

- アウトバウンド・リソース・アダプタ — アプリケーションがEISシステムに接続して、作業を行えるようになります。すべての通信はアプリケーションによって開始されます。この場合、リソース・アダプタはEISに接続するためのパッシブなライブラリとして機能し、アプリケーション・スレッドのコンテキストで実行されます。
Java EEコネクタ・アーキテクチャ1.5および1.6に基づいたアウトバウンド・リソース・アダプタは、複数の同時アウトバウンド接続を行うように構成できます。WebLogic Server固有の認証やトランザクションのサポートを利用するように、各アウトバウンド接続を構成することもできます。「アウトバウンド接続の構成」を参照してください。

Java EEコネクタ・アーキテクチャ1.0に基づいたアウトバウンド・リソース・アダプタもサポートされています。1.0のリソース・アダプタでは、アウトバウンド接続は1つだけ行うことができます。

- インバウンド・リソース・アダプタ(1.5および1.6のみ) - EISはアプリケーションを呼び出して作業を行えるようになります。すべての通信はEISによって開始されます。リソース・アダプタはWebLogic Serverのスレッドをリクエストしたり、独自のスレッドを生成したりできますが、この方法はお薦めしません。リソース・アダプタからワーク・マネージャを経由して作業を送信することをお薦めします。第8章「メッセージ・インフローとトランザクション・インフロー」を参照してください。

注意:

WebLogic Serverシン・クライアントJARは、ワーク・マネージャ規約をサポートしているので、非管理対象リソース・アダプタ(WebLogic Serverで実行されないリソース・アダプタ)として使用することもできます。

- 双方向リソース・アダプタ(1.5および1.6のみ) - アウトバウンドとインバウンドの両方の通信をサポートします。

1.0リソース・アダプタと1.5および1.6との比較

WebLogic Serverでは、Java EEコネクタ・アーキテクチャのバージョン1.0、1.5および1.6に基づいて開発されたリソース・アダプタをサポートしています。Java EEコネクタ・アーキテクチャ1.0では、一方向のアウトバウンド通信を使用した、リソース・アダプタから1つの外部システムへの通信のみに制限されています。Java EEコネクタ・アーキテクチャ1.5ではこの制限がなくなりました。1.5と1.6のリソース・アダプタで提供される他の機能で、1.0リソース・アダプタに適用されないものは、以下のとおりです。

- アプリケーションから、エンタープライズ情報システム(EIS)やデータベースなどの複数のシステムへのアウトバウンド通信。「インバウンド、アウトバウンド、および双方向のリソース・アダプタ」を参照してください。

- EISなどの1つまたは複数の外部システムからリソース・アダプタへのインバウンド通信。「インバウンド・メッセージの処理」を参照してください。

- トランザクション・インフロー。Java EEアプリケーション・サーバーは、リソース・アダプタを経由して、外部トランザクション・マネージャが制御するXAトランザクションに関与できるようになります。「トランザクション・インフロー」を参照してください。

- WebLogic Serverが提供するワーク・マネージャ。リソース・アダプタはWorkインスタンスを介してスレッドを作成できるようになります。「work-manager」を参照してください。

- アプリケーション・サーバーによってリソース・アダプタのstart()およびstop()メソッドを呼び出すためのライフサイクル規約。「起動クラスとして実行するためのリソース・アダプタのプログラミング」を参照してください。

1.0リソース・アダプタと1.5および1.6リソース・アダプタのもう1つの重要な相違点は接続プールに関連しています。1.5および1.6リソース・アダプタの場合、接続ファクトリにつき1つの接続プールが自動的に取得されることはありません。接続インスタンスを構成する必要があります。それには、weblogic-ra.xmlデプロイメント記述子のconnection-instance要素を設定します。

WebLogic Server Full Platformは現在『JSR 322: Java EE Connector Architecture 1.6』に準拠していますが、バージョン1.0および1.5も引続き完全にサポートしています。WebLogic Serverは、コネクタ・アーキテクチャ1.6に従って、スキーマに基づいたデプロイメント記述子をサポートしています。Java EEコネクタ・アーキテクチャ1.0に基づいて開発されたリソース・アダプタでは、文書型定義(DTD)に基づいたデプロイメント記述子を使用します。DTDに基づくデプロイメント記述子で構築されたリソース・アダプタも引続きサポートされます。

このドキュメントでは、1.6リソース・アダプタの開発と使用について説明します。

コネクタ・アーキテクチャ1.6のサポート

WebLogic Server Full Platformでサポートされるコネクタ・アーキテクチャ1.6の主な内容は次のとおりです。

- 開発容易性に関する機能
コネクタ・アーキテクチャ1.6では、開発プロセスを単純化するためにいくつかの機能(メタデータの注釈や「まばらな」デプロイメント記述子のサポートなど)が追加されています。メタデータの注釈をリソース・アダプタ・クラス・ファイルに埋め込んで、デプロイメント情報を指定できます。これにより、ra.xmlファイルを手動で作成する必要性が最小限に抑えられます。場合によっては必要性がなくなります。「デプロイメント情報を指定するメタデータ注釈の使用」を参照してください。

- 汎用ワーク・コンテキスト
汎用ワーク・コンテキストは、リソース・アダプタが、コンテキスト情報(トランザクション・コンテキストやセキュリティ・コンテキスト)をEISからWebLogic Serverに伝播するためにメッセージの配信またはWorkインスタンスの発行の際に使用するメカニズムです。詳細は、「汎用ワーク・コンテキスト」を参照してください。

- セキュリティ・コンテキスト
コネクタ・アーキテクチャ1.6で定義される標準の汎用セキュリティ・コンテキストは、『JSR 196: Java Authentication Service Provider Interface for Containers』の仕様を活用しています。詳細は、「セキュリティ・インフロー」を参照してください。

- その他の改善点:

- 『JSR 303: Bean Validation』との統合

- 動的に再構成できる構成プロパティ
リソース・アダプタ・コンポーネントBeanの、動的に構成できるプロパティを指定する機能です。これらのプロパティは実行時に再構成できるようになり、アダプタの再起動や再デプロイは必要ありません。「動的に再構成できる構成プロパティ」を参照してください。

- リソース・アダプタが、実行時に提供できるトランザクション・サポート・レベルを決定および分類できる機能。「トランザクション・サポート・レベルの指定および取得」を参照してください。

- オプションの分散Work処理。アプリケーション・サーバー・インスタンスのWorkManagerが、リソース・アダプタで発行されたWorkインスタンスを、別のアプリケーション・サーバー・インスタンスにある別のWorkManagerに分散するかどうかを選択できます。

WebLogic Serverコネクタ・コンテナによって提供される追加サポート

WebLogic Server では、『JSR 322: Java EE Connector Architecture 1.6』を補足するために次のような機能がコネクタ・コンテナで提供されます。

- 埋込みリソース・アダプタおよびグローバル・リソース・アダプタでの『JSR 299: Contexts and Dependency Injection for the Java EE Platform』(CDI)のサポート。CDIは、インジェクションを使用してアプリケーションに依存関係を指定するための一連のサービスを定義します。詳細は、第5章「リソース・アダプタでのContexts and Dependency Injectionの使用」を参照してください。

- 追加の実行時トランザクション・レベル指定。WebLogic Serverは、ConnectorConnectionPoolRuntimeMBean.RuntimeTransactionSupport MBean属性および管理コンソールで、実行時トランザクション・レベルの情報を公開しています。詳細は、「サポートされているトランザクション・レベル」を参照してください。

- java:comp/TransactionSynchronizationRegistryの標準名を使用してJNDIのTransactionSynchronizationRegistryオブジェクトをルックアップする機能。Oracleでは、このサポートを拡張するため、2つのグローバルJNDI名(javax/transaction/TransactionSynchronizationRegistryとweblogic/transaction/TransactionSynchronizationRegistry)を追加しました。詳細は、javax.transaction.TransactionSynchronizationRegistryを参照してください。

- 長時間実行しているWorkインスタンスの管理と監視。これには、現在アクティブな作業リクエストの数と完了した作業リクエストの数などが含まれます。これらは、WebLogic ServerによってConnectorWorkManagerRuntimeMBeanおよび管理コンソールで公開されます。「長時間実行するWorkのサポート」を参照してください。

- javax.resource.spi.RetryableException例外をアウトバウンド接続プールに拡張することで、この例外をサポートします。一時停止された接続のプールから接続を取得しようとすると、WebLogic Serverは、RetryableExceptionインタフェースを実装するRetryableApplicationServerInternalExceptionをスローします。RetryableExceptionインスタンスを使用して、障害が一過性かどうかを判別できます。

- 管理コンソールでのセキュリティ・コンテキストの補足サポート。EISからWebLogicへのインバウンド・プリンシパル・マッピングを作成する手段が提供されます。これにより、EISプリンシパル(EISセキュリティ・ドメインに定義されたユーザーやグループなど)がWebLogicドメインの対応するプリンシパルにマッピングされます。詳細は、「インバウンド・プリンシパル・マッピング」を参照してください。

- モジュールレベルの『JSR 303: Bean Validation』構成のサポート。WebLogic ServerによってJava EE 6が拡張されます。リソース・アダプタ・モジュールを検証するために、このBean構成ファイルをオプションで使用できます。

- weblogic.connector.extensions.ExtendedBootstrapContextの新しいメソッド:

- リソース・アダプタが検証のために独自のBeanのValidatorおよびValidatorFactoryインスタンスをルックアップする手段が提供されます。「Beanの検証」を参照してください。

- リソース・アダプタのBeanManagerインスタンスを返して、CDIインジェクションをサポートします。「BeanManager」および「CDI Beanアーカイブとしてデプロイされたリソース・アダプタの使用」を参照してください。

- Work名のヒント — Workインスタンスの名前になります。これは、長時間実行するWorkインスタンスに割り当てられるスレッド名の一部として使用されます。nameHintはスレッド名の一部を構成しますが、長時間実行するWorkのみで使用されます。詳細は、「長時間実行するWorkのサポート」を参照してください。

- リソース・アダプタに複数の接続プールが構成されている場合に、デプロイ中に正常な接続プールから失敗した接続プールを分離する機能。これにより、リソース・アダプタを再デプロイすることなく、失敗した接続プールの検出、診断、修正、およびアダプタ・デプロイメントの動的更新を行えます。
アウトバウンド接続プールの障害検出機能は、ヘルス監視機能から使用できます。これは、リソース・アダプタにまで拡張されています。リソース・アダプタ・デプロイメントのヘルス状態の確認は、WLSTまたはWebLogic Server管理コンソールを使用して行えます。詳細は、「リソース・アダプタのヘルス監視」および「複数のアウトバウンド接続プールで構成されたリソース・アダプタのデプロイ」を参照してください。

Java EEコネクタ・アーキテクチャ

Java EEコネクタ・アーキテクチャでは、Java EEプラットフォームを、エンタープライズ・リソース・プランニング(ERP)システム、メインフレーム・トランザクション処理(TP)、データベース・システムなどの異種のエンタープライズ情報システム(EIS)に接続するための、標準アーキテクチャを定義しています。

リソース・アダプタは、任意のEIS通信プロトコルを接続に使用できるようにするプロトコル・アダプタとして機能します。アプリケーション・サーバー・ベンダーは、Java EEコネクタ・アーキテクチャをサポートするためにシステムを一度拡張すれば、複数のEISとのシームレスな接続を確保できます。同様に、EISベンダーは1つの標準リソース・アダプタを提供すると、そのアダプタでJava EEコネクタ・アーキテクチャをサポートするどのアプリケーション・サーバーにも接続できます。

コネクタ・アーキテクチャの詳細は、『JSR 322: Java EE Connector Architecture 1.6』の3項「The Connector Architecture」を参照してください。

また、『The Java EE 6 Tutorial』の「Resource Adapters and Contracts」も参照してください。

Java EEコネクタ・アーキテクチャの図とコンポーネント

図2-1とその下の解説では、コネクタ・アーキテクチャ1.6のWebLogic Server実装について説明します。

図2-1 コネクタ・アーキテクチャの概要

「図2-1 コネクタ・アーキテクチャの概要」の説明

図2-1のコネクタ・アーキテクチャの概要では、双方向のリソース・アダプタを例示しています。アウトバウンド接続処理では以下のコンポーネントが使用されます。

- クライアント・アプリケーション。WebLogic Serverに接続し、EISとも対話する必要があります。

- アプリケーション・コンポーネント(EJBまたはサーブレット)。クライアント・アプリケーションがリソース・アダプタを介してアウトバウンド・リクエストをEISにアウトバウンドするために使用します。

- WebLogic Serverコネクタ・コンテナ。この中にリソース・アダプタがデプロイされます。この例のコンテナには以下のものが含まれています。

- EISとの双方向(インバウンドおよびアウトバウンド)通信を提供する、デプロイされたリソース・アダプタ。

- コンテナが保持する1つまたは複数の接続プール。特定のManagedConnectionFactoryに対応し、アウトバウンドの管理対象接続を管理するために使用されます(この例ではMCF-2。1つのEISとの接続や様々なEISとの接続など、接続の種類に応じて他にも存在する場合があります)。

- 複数の管理対象接続(MC1、MCn)。リソース・アダプタからEISへの物理的なアウトバウンド接続を表現するオブジェクトです。

- 接続ハンドル(C-handle)。リソース・アダプタの接続ファクトリからアプリケーション・コンポーネントに返されます。アプリケーション・コンポーネントがEISとの通信に使用します。

インバウンド接続処理では以下のコンポーネントが使用されます。

- 1つまたは複数の外部メッセージ・ソース(MS1、MS2)。WebLogic Serverへのインバウンド・メッセージを送信する、エンタープライズ情報システム(EIS)またはメッセージ・プロバイダです。

- 1つまたは複数のActivationSpec (Act Spec)。それぞれが1つのMessageListener型(MLT-i)に相当します。

- MessageEndpointFactory。EJBコンテナが作成し、インバウンド・メッセージング用リソース・アダプタがMessageEndpointインスタンス(MDBプールのMDBインスタンス)のプロキシを作成するために使用します。

- メッセージ・エンドポイント・アプリケーション(メッセージドリブンBean (MDB)やその他のJava EEコンポーネント)。リソース・アダプタを介してEISからインバウンド・メッセージをインバウンドして処理します。

システム・レベル規約

WebLogic ServerとEISの間に標準のシステム・レベルのプラガブル性を実現するために、WebLogic Serverでは、Java EEコネクタ・アーキテクチャで定義されたシステム・レベル規約の標準を実装しました。この規約は、2つのシステムが協調して作業できるように、アプリケーション・サーバーとEISで実装する必要のあるSPIクラスとインタフェースで構成されています。システム・レベル規約のEIS側は、リソース・アダプタのJavaクラスで実装されます。以下の標準規約がサポートされます。

- 接続管理規約 — WebLogic Serverは基底のEISへの接続をプールし、アプリケーション・コンポーネントはEISに接続することができます。リソースの共有を通じて接続を効率的に使用したり、接続ハンドルとEIS接続の関連付けおよび関連付けの解除を制御したりできます。

- トランザクション管理規約 — トランザクション・マネージャと、EISリソース・マネージャへのトランザクション・アクセスをサポートするEISとの間の規約。WebLogic Serverはトランザクション・マネージャを使用して、複数のリソース・マネージャにわたるトランザクションを管理できます。

- トランザクション・インフロー規約 — リソース・アダプタはインポートされたトランザクションをWebLogic Serverに伝播できます。リソース・アダプタは、EISによって開始されたトランザクション完了呼出しやクラッシュ・リカバリ呼出しを流入させることができます。トランザクション・インフローでは、トランザクションを調整するために外部トランザクション・マネージャも使用されます。

- セキュリティ規約 - 接続管理規約を拡張した規約です。EISへのセキュアなアクセスを提供し、EISに対するセキュリティの脅威を小さくするセキュアなアプリケーション環境をサポートします。また、EISによって管理される貴重な情報リソースを保護します。

- ライフサイクル管理規約 — WebLogic Serverはリソース・アダプタのライフサイクルを管理できます。デプロイメント時またはアプリケーション・サーバーの起動時にリソース・アダプタ・インスタンスのブート・ストラップを行ったり、アンデプロイ時やアプリケーション・サーバーの停止時にリソース・アダプタ・インスタンスに通知したりできます。

- 作業管理規約 — リソース・アダプタは、実行用にWebLogic ServerにWorkインスタンスを送信することで、作業(ネットワーク・エンドポイントのモニター、アプリケーション・コンポーネントの呼び出しなど)を行うことができます。

- 汎用ワーク・コンテキスト規約 — リソース・アダプタがコンテキスト(すなわち、発行するWorkインスタンスが、WebLogic ServerのWorkManagerによって実行されるコンテキスト)を制御できるようになります。また、汎用ワーク・コンテキスト・メカニズムにより、WebLogic Serverは新しいメッセージ・インフローおよび配信方法をサポートできるようになります。同時実行アクティビティを管理する機能も含まれる堅牢なコンテキストWork実行環境が、リソース・アダプタにもたらされます。
汎用ワーク・コンテキスト規約によって、トランザクション・コンテキストとセキュリティ・コンテキストが標準化されます。『JSR 322: Java EE Connector Architecture 1.6』では、リソース・アダプタとアプリケーション・サーバーの間のこの規約が詳しく定義されています。インタフェースやクラス、スレッド・モデル、コンテキストの確認や確立のための規則、エラー処理、イベント通知などが含まれます。

- メッセージ・インフロー規約 — リソース・アダプタは、メッセージの配信に使用される特定のメッセージング・スタイル、メッセージング・セマンティクス、およびメッセージング・インフラストラクチャとは独立して、WebLogic Server内のメッセージ・エンドポイントに、メッセージを非同期または同期的に配信できます。また、この規約は標準のメッセージ・プロバイダのプラガブル性規約としても機能し、リソース・アダプタを介して様々なメッセージ・プロバイダ(Java Message ServiceやJava API for XML Messagingなど)をWebLogic Serverにプラグインできます。

このようなシステムレベルの規約は『JSR 322: Java EE Connector Architecture 1.6』で詳しく説明されています。

リソース・アダプタ・デプロイメント記述子

リソース・アダプタの構造と実行時の動作はデプロイメント記述子で定義されます。プログラマはパッケージ化のプロセスでデプロイメント記述子を作成します。そのデプロイメント記述子は、アプリケーションのコンパイル時にアプリケーションの一部になります。

WebLogic Serverリソース・アダプタには2つのデプロイメント記述子があり、それぞれにXMLスキーマがあります。

- ra.xml - 標準のJava EEデプロイメント記述子。すべてのリソース・アダプタをra.xmlデプロイメント記述子ファイルに指定する必要があります。ra.xmlのスキーマはhttp://java.sun.com/xml/ns/javaee/connector_1_6.xsdです。

注意:

コネクタ・アーキテクチャ1.6ではメタデータの注釈が導入されています。これを使用すると、リソース・アダプタ・クラス・ファイルのデプロイメント情報を指定できます。これにより、ra.xmlファイルを手動で作成する必要性が最小限に抑えられます。場合によっては必要性がなくなります。

- weblogic-ra.xml - トランザクション管理、接続管理、セキュリティなどのWebLogic Serverの機能に関連する要素を格納するWebLogic Server固有のデプロイメント記述子。リソース・アダプタをWebLogic Serverにデプロイするにはこのファイルが必要です。weblogic-ra.xmlデプロイメント記述子ファイルのスキーマはhttp://xmlns.oracle.com/weblogic/weblogic-connector/1.4/weblogic-connector.xsdです。weblogic-ra.xmlデプロイメント記述子のリファレンスについては、付録A「weblogic-ra.xmlスキーマ」を参照してください。

3 リソース・アダプタの作成と構成

この章では、WebLogic Serverリソース・アダプタを作成および構成する方法、さらにデプロイメントのためにリソース・アダプタを準備する方法について説明します。

この章の内容は以下のとおりです。

- リソース・アダプタの作成と構成:主な手順

- 既存のリソース・アダプタの変更

- ra.xmlファイルの構成

- weblogic-ra.xmlファイルの構成

- Bean検証の構成ファイル

- 長時間実行するWorkのサポート

- ツールのサポート

- リソース・アダプタのヘルス監視

リソース・アダプタの作成と構成:主な手順

この項では、新しいWebLogicリソース・アダプタを作成する方法について説明します。次の項「既存のリソース・アダプタの変更」では、既存のリソース・アダプタをWebLogic Serverにデプロイメントできるように準備する方法について説明します。

WebLogicリソース・アダプタを作成するには、特定のリソース・アダプタのクラス(ConnectionFactory、Connectionなど)を作成し、リソース・アダプタのデプロイメント記述子を記述して、それらをWebLogic Serverにデプロイされるアーカイブ・ファイルにパッケージ化する必要があります。

リソース・アダプタを作成する主な手順は以下のとおりです。

1. 『JSR 322: Java EE Connector Architecture 1.6』に従って、リソース・アダプタで必要な様々なクラス(ConnectionFactory、Connectionなど)のJavaコードを記述します。これらのクラスをra.xmlファイルに指定します。例:

<managedconnectionfactory-class>
com.sun.connector.blackbox.LocalTxManagedConnectionFactory
</managedconnectionfactory-class>

<connectionfactory-interface>
javax.sql.DataSource
</connectionfactory-interface>

<connectionfactory-impl-class>
com.sun.connector.blackbox.JdbcDataSource
</connectionfactory-impl-class>

<connection-interface>
java.sql.Connection
</connection-interface>

<connection-impl-class>
com.sun.connector.blackbox.JdbcConnection
</connection-impl-class>

1.6アダプタではメタデータの注釈をリソース・アダプタ・クラス・ファイルに埋め込んで、デプロイメント情報を指定できます。これにより、ra.xmlファイルを手動で作成する必要性がなくなります。詳細は、「ra.xmlファイルの構成」を参照してください。

注意:

コネクタ・アーキテクチャ1.6のWebLogic Server実装には、Contexts and Dependency Injectionのサポートが含まれます。リソース・アダプタのコンポーネントBeanで使用できる注釈のセットも暗黙にサポートされます。これらのBeanは、コネクタ・コンテナで管理される特殊なコンポーネントを定義し、ライフ・サイクルが特別です。詳細については、以下を参照:

リソース・アダプタのプログラミングの詳細は、第4章「プログラミング・タスク」を参照してください。

2. 標準コンパイラを使用して、インタフェースと実装のJavaコードをクラス・ファイルにコンパイルします。

3. リソース・アダプタのデプロイメント記述子を作成します。WebLogicリソース・アダプタでは2つのデプロイメント記述子を使用します。

- ra.xmlでは、Java EEコネクタ・アーキテクチャ仕様で指定された標準のXMLスキーマを使用して、リソース・アダプタに関連する属性タイプとそのデプロイメント・プロパティを記述します。

注意:

Java EEコネクタ・アーキテクチャ1.6では、ra.xmlファイルを手動で作成する必要はありません。かわりにデプロイメント情報をメタデータ注釈に指定できます。「ra.xmlファイルの構成」を参照してください。

- weblogic-ra.xmlでは、接続や接続プールのプロパティ、セキュリティID、ワーク・マネージャのプロパティ、ロギングなど、WebLogic Serverに固有のデプロイメント情報を追加します。

リソース・アダプタのWeblogic Server固有のデプロイメント記述子を作成する詳細は、「weblogic-ra.xmlファイルの構成」および付録A「weblogic-ra.xmlスキーマ」を参照してください。

4. Javaクラスを.rar拡張子の付いたJavaアーカイブ(JAR)ファイルにパッケージ化します。
ステージング・ディレクトリをハード・ディスクの任意の場所に作成します。JARファイルをステージング・ディレクトリに置き、デプロイメント記述子をMETA-INFというサブディレクトリに置きます。

次に、ステージング・ディレクトリで次のようにjarコマンドを実行して、リソース・アダプタ・アーカイブを作成します。

jar cvf myRAR.rar *

オプションで、Bean検証構成ファイルMETA-INF/validation.xmlをJARファイルに含めることができます。WebLogic ServerはBean検証構成ファイルを使用して、リソース・アダプタ・モジュールを検証できます。

5. リソース・アダプタ・アーカイブ(RAR)ファイルをテスト環境のWebLogic Serverにデプロイして、テストします。
テスト中に、リソース・アダプタ・デプロイメント記述子の編集が必要になる場合があります。それには、WebLogic Server管理コンソールを使用するか、XMLエディタまたはテキスト・エディタを使用して手動で行います。デプロイメント記述子の編集の詳細は、「weblogic-ra.xmlファイルの構成」およびOracle WebLogic Server管理コンソール・オンライン・ヘルプのリソース・アダプタのプロパティの構成に関する項を参照してください。デプロイメント記述子の要素の詳細は、付録A「weblogic-ra.xmlスキーマ」も参照してください。

6. RARリソース・アダプタ・アーカイブ・ファイルをWebLogic Serverにデプロイするか、またはエンタープライズ・アプリケーションの一部としてデプロイするエンタープライズ・アーカイブ(EAR)ファイルに含めます。
この手順の詳細は、第10章「リソース・アダプタのパッケージ化とデプロイ」を参照してください。コンポーネントとアプリケーションのデプロイメントの詳細は、『Oracle WebLogic Serverへのアプリケーションのデプロイ』も参照してください。

既存のリソース・アダプタの変更

WebLogic Serverのデプロイメントとして利用できるリソース・アダプタがすでにある場合もあります。この項では、RARファイルにパッケージ化されている既存のリソース・アダプタを、WebLogic Serverのデプロイメント用に変更します。それには、weblogic-ra.xmlデプロイメント記述子を追加して、リソース・アダプタを再パッケージ化します。以下の手順では、blackbox-notx.rarというRARファイルにパッケージ化された既存のリソース・アダプタがあると仮定しています。

1. ハード・ディスクの任意の場所にリソース・アダプタのステージング用の一時ディレクトリを作成します。

mkdir c:/stagedir

2. リソース・アダプタ・アーカイブの内容を展開します。

cd c:/stagedir
jar xf blackbox-notx.rar

ステージング・ディレクトリには、以下のものが格納されます。

- リソース・アダプタを実装するJavaクラスが入ったJARファイル

- Manifest.mfおよびra.xmlファイルが入ったMETA-INFディレクトリ

以下のコマンドを実行してこれらのファイルを確認します。

c:/stagedir> ls
blackbox-notx.rar
META-INF
c:/stagedir> ls META-INF
Manifest.mf
ra.xml

3. weblogic-ra.xmlファイルを作成します。このファイルは、リソース・アダプタのWebLogic固有のデプロイメント記述子です。このファイルには、接続ファクトリ、接続プール、およびセキュリティ設定のパラメータを指定します。
詳細は、「weblogic-ra.xmlファイルの構成」を参照してください。weblogic-ra.xmlに適用するXMLスキーマの詳細は、付録A「weblogic-ra.xmlスキーマ」も参照してください。

4. weblogic-ra.xmlファイルを一時ディレクトリのMETA-INFサブディレクトリにコピーします。META-INFディレクトリは、RARファイルを展開した一時ディレクトリ、またはリソース・アダプタが展開ディレクトリ形式で格納されているディレクトリ内にあります。以下のコマンドを使用します。

cp weblogic-ra.xml c:/stagedir/META-INF
c:/stagedir> ls META-INF
Manifest.mf
ra.xml
weblogic-ra.xml

5. リソース・アダプタ・アーカイブを作成します。

jar cvf blackbox-notx.rar -C c:/stagedir

6. WebLogic Serverにリソース・アダプタをデプロイします。リソース・アダプタのパッケージ化とデプロイの詳細は、第10章「リソース・アダプタのパッケージ化とデプロイ」および『Oracle WebLogic Serverへのアプリケーションのデプロイ』を参照してください。

ra.xmlファイルの構成

すべてのリソース・アダプタをra.xmlデプロイメント記述子ファイルに指定する必要があります。1.0または1.5のリソース・アダプタでは、このファイルを手動で作成する必要があります。1.6リソース・アダプタを作成している場合は、メタデータの注釈をオプションでリソース・アダプタ・クラスに指定できます。これにより、ra.xmlファイルを手動で作成する必要性がなくなります。次の項では、ra.xmlファイルの構成方法について説明します。

- ra.xmlファイルの手動作成

- デプロイメント情報を指定するメタデータ注釈の使用

- リソース・アダプタのXMLスキーマ定義

ra.xmlファイルの作成の詳細は、『JSR 322: Java EE Connector Architecture 1.6』も参照してください。

ra.xmlファイルの手動作成

リソース・アダプタにra.xmlファイルがなく、1.0または1.5リソース・アダプタを作成している場合は、手動で作成するか、または既存のファイルを編集して、リソース・アダプタに必要なデプロイメント・プロパティを設定する必要があります。プロパティの編集には、テキスト・エディタまたはXMLエディタを使用できます。

デプロイメント情報を指定するメタデータ注釈の使用

Java EEコネクタ・アーキテクチャ1.6では、ra.xmlファイルを手動で作成する必要はありません。かわりに、メタデータ注釈をリソース・アダプタのクラスに含めると、ra.xmlファイルに指定するのと同じ機能を提供できます。

すべてのデプロイメント情報をra.xmlファイルに指定することを選択した場合、Java EEコネクタ・アーキテクチャ1.6がmetadata-complete要素を含みます。これをra.xmlファイルに含めて、trueに設定します。metadata-complete要素をtrueに設定すると、リソース・アダプタのクラスに含まれるすべてのメタデータ注釈が無視されます。metadata-complete要素を指定しない、またはfalseに設定すると、WebLogic Serverは、注釈に指定された情報とra.xmlファイルに指定された情報を実行時にマージし、マージした情報を使用してリソース・アダプタのデプロイと管理を行います。

デプロイメント記述子と注釈の詳細は、『JSR 322: Java EE Connector Architecture 1.6』の第18章「Metadata Annotations」を参照してください。また、『The Java EE 6 Tutorial』の「Metadata Annotations」も参照してください。

リソース・アダプタのXMLスキーマ定義

Java EEコネクタ・アーキテクチャ1.6では、主に開発容易性の機能(メタデータ注釈など)をサポートするためにra.xmlファイル・スキーマが変更されています。スキーマ定義の変更の詳細は、『JSR 322: Java EE Connector Architecture 1.6』の第20.7項「Resource Adapter XML Schema Definition」を参照してください。

1.0および1.5リソース・アダプタのra-xmlファイルのスキーマは、http://java.sun.com/xml/ns/j2ee/connector_1_5.xsdです。1.6のアダプタでは、スキーマはhttp://java.sun.com/xml/ns/javaee/connector_1_6.xsdです。

weblogic-ra.xmlファイルの構成

標準リソース・アダプタ構成のra.xmlファイルの機能をサポートする他に、WebLogic Serverでは追加のデプロイメント記述子ファイルであるweblogic-ra.xmlファイルを定義しています。このファイルには、リソース・アダプタをWebLogic Serverで構成し、デプロイするための固有のパラメータが含まれます。このファイルは、WebLogic ServerのEJBやWebアプリケーション用の同等の拡張機能(weblogic-*.xml)と整合性があり、WebLogic固有のデプロイメント記述子をデプロイ可能なアーカイブに追加するものです。基本のRARまたはデプロイメント・ディレクトリは、weblogic-ra.xmlファイルがなくてもWebLogic Serverにデプロイできます。weblogic-ra.xmlファイルを使用せずにリソース・アダプタをWebLogic Serverにデプロイすると、デフォルトの要素値が含まれたweblogic-ra.xmlのテンプレート・ファイルが自動的にリソース・アダプタ・アーカイブに追加されます。ただし、この自動生成されたweblogic-ra.xmlファイルはRARに永続化されないので、RARは変更されないままです。

weblogic-ra.xmlデプロイメント記述子ファイルで構成できる重要な機能について、以下で簡単に説明します。

- 接続ファクトリの説明用テキスト。

- 接続ファクトリにバインドされるJNDI名(『JSR 322: Java EE Connector Architecture 1.6』に基づいて開発されたリソース・アダプタは、ConnectionFactoryオブジェクトとは関係なく、オブジェクトとしてJNDIにバインドされます)。

- 現在のリソース・アダプタと共有可能なリソース・アダプタ・コンポーネントを含み、別にデプロイされた接続ファクトリへの参照。

- 以下の動作を設定する接続プール・パラメータ。

- WebLogic Serverがデプロイメント時に割り当てようとするManagedConnectionの初期数。

- WebLogic Serverが一度に割当可能なManagedConnectionの最大数。

- WebLogic Serverが新規接続のリクエストに応じるときに割り当てようとするManagedConnectionの数。

- システム・リソースを節約するためにWebLogic Serverが未使用のManagedConnectionを再利用しようとするかどうか。

- 未使用のManagedConnectionの再利用を試みるまでWebLogic Serverが待機する時間。

- ManagedConnectionFactoryまたはManagedConnectionに対するWebLogic Serverロギングを構成するロギング・プロパティ。

- トランザクション・サポート・レベル(XA、ローカル、またはトランザクションのサポートなし)。

- セキュリティIDとして使用するプリンシパル名。

weblogic-ra.xmlデプロイメント記述子ファイルの構成の詳細は、付録A「weblogic-ra.xmlスキーマ」のリファレンス情報を参照してください。次の項の構成情報も参照してください。

- 第6章「接続管理」

- 第7章「トランザクション管理」

- 第8章「メッセージ・インフローとトランザクション・インフロー」

- 第9章「セキュリティ」

リソース・アダプタ・デプロイメント記述子の編集

WebLogic Serverのリソース・アダプタ・アーカイブで使用されるXML記述子を定義または変更するには、weblogic-ra.xmlおよびra.xmlデプロイメント記述子ファイルでXML要素を定義または編集する必要があります。デプロイメント記述子ファイルは任意のテキスト・エディタで編集できます。ただし、エラーが起きないように、XML編集用に設計されたツールを使用してください。ファイルのほとんどの要素はWebLogic管理コンソールでも編集できます。

編集の考慮事項

XML要素を手動で編集する場合、以下のことを考慮します。

- ASCIIテキスト・エディタを使用する場合は、そのエディタによって、XMLの形式が変更されたり、ファイルを無効にする可能性のある文字が挿入されないようにします。

- 使用しているオペレーティング・システムで大文字小文字が区別されない場合でも、ファイル名やディレクトリ名の大文字小文字は正確に指定します。

- 省略可能な要素のデフォルト値を使用する場合は、要素の定義全体を省略するか、または次のように空白値を指定することができます。例: <max-config-property></max-config-property>

スキーマ・ヘッダー情報

XMLデプロイメント・ファイルを編集または作成するときに、各デプロイメント・ファイルの正しいスキーマ・ヘッダーを指定することが重要です。ヘッダーでは、デプロイメント記述子のスキーマの場所とバージョンが示されます。

このヘッダーは外部URLのjava.sun.comを参照していますが、WebLogic Serverにはスキーマの独自のコピーが用意されているので、ホスト・サーバーがインターネットにアクセスする必要はありません。ただし、<?xml version...>要素にあるスキーマのバージョンはデプロイメント記述子のバージョンの識別に使用されるので、この要素をra.xmlファイルに含めて、外部URLを参照させる必要があります。

表3-1に、ra.xmlおよびweblogic-ra.xmlファイルのスキーマ・ヘッダー全体を示します。

表3-1 スキーマ・ヘッダー

XMLファイル

スキーマ・ヘッダー

ra.xml

<?xml version="1.0" encoding="UTF-8"?>
<connector 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/connector_1_6.xsd"
version="1.6">

weblogic-ra.xml

<?xml version = "1.3">
<weblogic-connector xmlns="http://xmlns.oracle.com/weblogic/weblogic-connector">

XMLの解析ユーティリティ(ejbcなど)でヘッダー情報が不正なXMLファイルを解析すると、次のようなエラー・メッセージが表示されることがあります。

SAXException: This document may not have the identifier 'identifier_name'

デプロイメント記述子ファイルのスキーマへの準拠

デプロイメント記述子ファイルの内容と要素の配置は、使用する各ファイルのスキーマに従っている必要があります。以下のリンクでは、WebLogic Serverで使用されるデプロイメント記述子ファイル用のスキーマの場所が示されています。

- connector_1_6.xsdには、すべてのリソース・アダプタに必要な標準ra.xmlデプロイメント・ファイルのスキーマが含まれています。このスキーマは『JSR 322: Java EE Connector Architecture 1.6』の一部として管理され、http://java.sun.com/xml/ns/javaee/connector_1_6.xsdにあります。

- weblogic-ra.xsdには、WebLogic Serverにデプロイメントする際に使用されるリソース・アダプタ・プロパティを定義するweblogic-ra.xmlを作成するためのスキーマが含まれています。このスキーマはhttp://xmlns.oracle.com/weblogic/weblogic-connector/1.4/weblogic-connector.xsdにあります。

注意:

ブラウザによっては、.xsd拡張子を持つファイルの内容を表示できない場合があります。その場合にスキーマの内容を見るには、リンクをテキスト・ファイルとして保存し、テキスト・エディタで表示します。

動的な記述子の更新:コンソールの「構成」タブ

管理コンソールを使用して、デプロイメント記述子の要素を表示、変更、(必要な場合には)永続化できます。一部の記述子要素の変更は、リソース・アダプタを再デプロイしなくても、実行時に動的に行われます。それ以外の記述子要素は、変更後に再デプロイメントが必要です。管理コンソールを使用してリソース・アダプタを構成するには、「デプロイメント」を開いて、デプロイ済みリソース・アダプタの名前をクリックします。リソース・アダプタの構成を変更するには、「構成」タブを使用します。他のタブを使用して、リソース・アダプタの制御、テスト、またはモニターを行います。

管理コンソールの使用方法は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプのリソース・アダプタのプロパティの構成に関する項を参照してください。

動的に再構成できる構成プロパティ

動的に再構成できる構成プロパティについては、『JSR 322: Java EE Connector Architecture 1.6』の5.3.7.6項に説明があります。1.6リソース・アダプタの場合、WebLogic Serverでは、次のアダプタ・コンポーネントBeanに関して動的に再構成できる構成プロパティをサポートします。

- ResourceAdapter Bean

- ManagedConnectionFactory Bean

- 管理対象オブジェクトBean

実行時に、これらのアダプタ・コンポーネントBeanのいずれかで動的に構成できるプロパティを更新した後では、変更を有効にするためにアダプタを更新する必要があります。アダプタの更新は比較的負荷の軽い操作です。このとき、WebLogic Serverは実行時Beanインスタンスを変更します。構成が更新されていない、アクティブな接続プールや管理オブジェクトに干渉することはありません。アダプタをすぐに更新する必要はありません。ただし、アダプタ・コンポーネントBeanが動的に更新されるか、リソース・アダプタが再起動されない限り、Beanのプロパティの変更は有効になりません。

リソース・アダプタは、実行時のプロパティに対する動的変更のサポートに関して、注意して設計する必要があります。リソース・アダプタで提供するサービスによって異なりますが、一部のプロパティはアダプタの実行中に決して再構成しないでください。たとえば、EIS接続に使用されるリソース・アダプタのリスニング・アドレスとポート番号です(このようなプロパティを再構成すると、アダプタを停止して再起動する必要が生じます)。WebLogic Serverでは、特定のプロパティを動的に再構成可能として設計するかどうかについて、アダプタ・コンポーネントBeanに関する要件はありません。動的更新をサポートするアダプタ・コンポーネントBeanの決定は、アダプタの開発者にすべて任されています。

動的な構成パラメータ

1.6アダプタの場合、WebLogic Serverでは、Resource Adapter、ManagedConnectionFactoryおよび管理オブジェクトBeanのプロパティでの動的更新をサポートします。管理コンソールを使用して、リソース・アダプタの再デプロイを行わずに、これらのBeanの次の構成パラメータを動的に変更できます。

- アダプタのJNDI名の編集

- アウトバウンド接続プールの作成と削除

- 接続プールのJNDI名の編集

- 管理オブジェクトの作成と削除

- 管理オブジェクトのJNDI名の編集

動的なプール・パラメータ

管理コンソールを使用して、weblogic-ra.xmlの以下のプール・パラメータを動的に変更できます。リソース・アダプタの再デプロイは必要ありません。

- initial-capacity

- max-capacity

- capacity-increment

- shrink-frequency-seconds

- highest-num-waiters

- highest-num-unavailable

- connection-creation-retry-frequency-seconds

- connection-reserve-timeout-seconds

- test-frequency-seconds

動的なロギング・パラメータ

管理コンソールを使用して、weblogic-ra.xmlの以下のロギング・パラメータを動的に変更できます。リソース・アダプタの再デプロイは必要ありません。

- log-filename

- file-count

- file-size-limit

- log-file-rotation-dir

- rotation-time

- file-time-span

weblogic-ra.xmlファイルの自動生成

WebLogic Serverにデプロイされるリソース・アダプタ・アーカイブ(RAR)には、『JSR 322: Java EE Connector Architecture 1.6』で指定されたra.xmlデプロイメント記述子ファイルに加えて、weblogic-ra.xmlデプロイメント記述子ファイルが必要です。

weblogic-ra.xmlファイルを使用せずにリソース・アダプタをWebLogic Serverにデプロイすると、デフォルトの要素値が含まれたweblogic-ra.xmlのテンプレート・ファイルが自動的にリソース・アダプタ・アーカイブに追加されます。ただし、この自動生成されたweblogic-ra.xmlファイルはRARに永続化されないので、RARは変更されないままです。代わりにWebLogic Serverでは、weblogic-ra.xmlファイルのデフォルト情報に相当する内部データ構造が生成されます。

接続ファクトリの定義が1つだけの1.0リソース・アダプタの場合、JNDI名はeis/ModuleNameになります。たとえば、RARの名前がMySpecialRA.rarである場合、接続ファクトリのJNDI名はeis/MySpecialRAになります。

ResourceAdapter Beanクラスを指定した1.5リソース・アダプタの場合、そのBeanのJNDI名はMySpecialRAになります。また、各接続ファクトリに対応するインスタンスがeis/ModuleName、eis/ModuleName_1、eis/ModuleName_2などのJNDI名で作成されます。

(非推奨) Link-Refメカニズムの構成

Link-RefメカニズムはWebLogic Serverリリース8.1で導入されました。基本アダプタを1つデプロイメントし、そのコードを、さまざまな構成プロパティを持つ複数の論理的なアダプタで共有できるようにするものです。現在のリリースの1.5リソース・アダプタでは、Link-Refメカニズムは非推奨となり、新しいJava EEライブラリ機能で置き換えられています。ただし、1.0リソース・アダプタの場合は、このリリースでもLink-Refメカニズムがサポートされています。Java EEライブラリの詳細は、『Oracle WebLogic Serverアプリケーションの開発』の共有Java EEライブラリおよびオプション・パッケージの作成に関する項を参照してください。Link-Refメカニズムを使用するには、リソース・アダプタのweblogic-ra.xmlファイルでra-link-ref要素を使用します。

非推奨の省略可能なra-link-ref要素を使用すると、デプロイ済みの複数のリソース・アダプタを1つのデプロイ済みリソース・アダプタに関連付けられます。つまり、属性のサブセットを変更するだけで、基本リソース・アダプタで構成されているリソースを別のリソース・アダプタにリンク(再利用)できます。ra-link-ref要素を使用すると、可能な場合、リソース(クラス、JAR、イメージ・ファイルなど)の重複を防げます。デプロイ済みの基本リソース・アダプタ・デプロイメントで定義されている値はすべて、ra-link-ref要素でそれ以外の値が指定されていない限り、リンク先のリソース・アダプタで継承されます。

省略可能なra-link-ref要素を使用する場合は、pool-params要素のすべての値を指定するか、まったく指定しないかのどちらかにします。pool-params要素は、基本リソース・アダプタからリンク先のリソース・アダプタに部分的には継承されません。

以下のいずれか1つを実行します。

- max-capacity要素に0 (ゼロ)を割り当てます。これにより、リンク先のリソース・アダプタは基本リソース・アダプタからpool-params要素の値を継承できます。

- max-capacity要素に0 (ゼロ)以外の値を割り当てます。リンク先リソース・アダプタは、基本リソース・アダプタから値を継承しなくなります。これを選択する場合は、リンク先リソース・アダプタのpool-params要素のすべての値を指定する必要があります。

weblogic-ra.xmlファイルの編集の詳細は、付録A「weblogic-ra.xmlスキーマ」を参照してください。

Bean検証の構成ファイル

『JSR 303: Bean Validation』をサポートするため、WebLogic ServerはモジュールレベルのBean検証構成ファイルを提供してJava EE 6を拡張します。WebLogic Serverでは、リソース・アダプタ・モジュールを検証するためにこのファイルのオプションでの使用がサポートされます。

Bean検証構成ファイルはリソース・アダプタ・モジュールに指定できます。リソース・アダプタが独立してデプロイされているか(スタンドアロンのRARとして)、エンタープライズ・アプリケーション(EAR)の一部としてデプロイされているかは関係ありません。Bean検証構成ファイルがアダプタ・モジュールに対して指定されない場合、WebLogic ServerはデフォルトのBean検証構成を使用してリソース・アダプタ・モジュールを検証します。

Bean検証構成ファイルにはvalidation.xmlという名前を付けて、デプロイメント記述子と一緒にRARのMETA-INFサブディレクトリに含めます。

Bean検証の詳細は、「Beanの検証」を参照してください。

長時間実行するWorkのサポート

『JSR 322: Java EE Connector Architecture 1.6』の11.7項では、WorkManagerによって提供されるサービスの品質(QoS)特性を制御する2つの標準ヒントが定義されます。

- Work名のヒント — Workインスタンスの名前になります。これは、長時間実行するWorkインスタンスに割り当てられるスレッド名の一部として使用されます。

- 長時間実行するWorkインスタンスのヒント — WebLogic Server拡張機能の注釈@LongRunningと同じ機能を実行します。これにより、Workインスタンスを別のスレッドにスケジュールすることができます。また、長時間実行するWorkインスタンスの制御と監視の機能が強化されます。
WebLogic Serverを使用して、長時間実行するWorkインスタンス数(同時に実行するためにリソース・アダプタで発行できる数)の制限を構成できます。デフォルトの制限は10です。この制限の値を増やすことができますが、システム・リソースの負荷が高くならないように注意する必要があります。

制限を指定するには、weblogic-ra.xmlファイルのmax-concurrent-long-running-requests要素を使用するか、ConnectorWorkManagerRuntimeMBean.ActiveLongRunningRequests属性(管理コンソールで公開される)を設定します。ConnectorWorkManagerRuntimeMBeanには、ActiveLongRunningRequests属性とCompletedLongRunningRequests属性のgetterメソッドとsetterメソッドが含まれます。これらを使用すると、長時間実行するWorkインスタンスに関する情報を構成および監視できます。

詳細は、「長時間実行するWorkの構成および管理」を参照してください。

ツールのサポート

WebLogic Serverでは、リソース・アダプタの開発とデプロイメントに役立つ次のツールをサポートしています。

- weblogic.appmerge
検証チェックのメタデータ注釈を実行します。-writeInferredDescriptorsオプションとともに使用すると、weblogic.appmergeでは、注釈に指定されたデプロイメント情報と既存のra.xmlファイルの内容を融合する、マージされたra.xmlが生成されます。

注意:

weblogic.appmergeツールを実行した後、マージされたra.xmlでmetadata-complete要素がtrueに設定されているか確認してください。これによってデプロイヤが注釈を再処理することを回避できるため、全体的なデプロイメント・パフォーマンスが向上し、デプロイメント時間が短縮されます。

詳細は、『Oracle WebLogic Serverアプリケーションの開発のweblogic.appmergeの使用によるライブラリのマージに関する項を参照してください。

- appc
注釈、Beanクラス、ra.xml、weblogic-ra.xml、およびリソース・アダプタ・デプロイメント・プランにおける広範囲の検証チェックを実行します(weblogic.appmergeは注釈のみを検証します)。

appcツールには次の機能もあります。

- 警告とエラーの両方を含む豊富なレポートが提供されます。

- リソース・アダプタの検証と、その構成の正確さをデプロイを実行せずに確認する場合に特に有効です。

詳細は、『Oracle WebLogic Server Enterprise JavaBeansバージョン2.1の開発』のappcリファレンスに関する項を参照してください。

リソース・アダプタのヘルス監視

WebLogic Serverには、スタンドアロン・リソース・アダプタおよび埋込みリソース・アダプタのヘルス・ステータスを監視する機能が用意されています。デフォルトでは、スタンドアロンまたは埋込みリソース・アダプタにデプロイメント・エラーが発生すると、ヘルス・ステータスがHEALTH_FAILEDになり、アダプタのデプロイメント全体が失敗します。ただし、リソース・アダプタに複数のアウトバンド接続プールが設定されており、そのdeploy-as-a-wholeフラグがfalseに設定されている場合は、1つ以上のアウトバウンド接続プール・エラーが発生した場合でもアダプタのデプロイメントは成功します。このヘルス監視機能を使用すると、アダプタを再デプロイすることなく、接続プール・エラーを検出してプールを修復できます。

次の項では、WebLogic Serverでリソース・アダプタのヘルス・ステータス監視機能を使用可能にする方法を説明します。

- リソース・アダプタのヘルス状態の取得

- ヘルス監視に関するデプロイ要件

リソース・アダプタのヘルス状態の取得

スタンドアロン・リソース・アダプタと埋込みリソース・アダプタの両方でヘルス監視をサポートするために、WebLogic Serverには、次のMBean属性が用意されています。これらの値は、WebLogic Server管理コンソール、WLSTまたはJMXを使用して取得できます。

- ConnectorComponentRuntimeMBean.HealthState: スタンドアロン・リソース・アダプタまたは埋込みリソース・アダプタのいずれかの全体的なヘルス状態を返します。アウトバウンド接続プールにデプロイメント・エラーがある場合は、リソース・アダプタのヘルス状態はHEALTH_CRITICALになります。

- ApplicationRuntimeMBean.OverallHealthState: アプリケーションの集計されたヘルス状態を返します。これには、ヘルス状態を報告する埋込みコンポーネントのヘルス状態が含まれます。埋込みリソース・アダプタに、失敗したアウトバウンド接続プールがある場合は、その接続プールのヘルス状態がアプリケーションの全体的なヘルス状態に反映されます。

- ConnectorConnectionPoolRuntimeMBean.HealthState: リソース・アダプタの個々のアウトバウンド接続プールのヘルス状態を返します。

ヘルス監視に関するデプロイ要件

失敗した接続プールが原因でアダプタ・デプロイメント全体が失敗することがないように、複数のアウトバウンド接続プールで構成されるリソース・アダプタをデプロイするには、weblogic-ra.xmlファイルのdeploy-as-a-whole要素をfalseに設定する必要があります。(デフォルトでは、この要素はtrueに設定されます。)このデプロイメント・オプションの設定の詳細は、「複数のアウトバウンド接続プールで構成されたリソース・アダプタのデプロイ」を参照してください。

4 プログラミング・タスク

この章では、WebLogic Serverリソース・アダプタを実装するためのプログラミング・タスクについて説明します。Java EEコネクタ・アーキテクチャで必要なJavaクラスを示します。起動クラスとして実行するリソース・アダプタのプログラミング方法、リソース・アダプタの一時停止と再開の方法、さらにExtendedBootstrapContextクラスについて説明します。

この章の内容は以下のとおりです。

- リソース・アダプタに必要なクラス

- 汎用ワーク・コンテキスト

- 起動クラスとして実行するためのリソース・アダプタのプログラミング

- リソース・アダプタのアクティビティの中断と再開

- 拡張されたBootstrapContext

- 管理対象オブジェクトの一意性

リソース・アダプタに必要なクラス

コネクタ・アーキテクチャ1.6に準拠するリソース・アダプタでは次のJavaクラスが必要です。

- ManagedConnectionFactory

- ConnectionFactoryインタフェース

- ConnectionFactory実装

- Connectionインタフェース

- Connection実装

これらのクラスをra.xmlファイルに指定します。例:

<managedconnectionfactory-class>
com.sun.connector.blackbox.LocalTxManagedConnectionFactory
</managedconnectionfactory-class>

<connectionfactory-interface>
javax.sql.DataSource
</connectionfactory-interface>

<connectionfactory-impl-class>
com.sun.connector.blackbox.JdbcDataSource
</connectionfactory-impl-class>

<connection-interface>
java.sql.Connection
</connection-interface>

<connection-impl-class>
com.sun.connector.blackbox.JdbcConnection
</connection-impl-class>

また、リソース・アダプタでインバウンド・メッセージングをサポートする場合は、サポートするインバウンド・メッセージのタイプごとにActivationSpecクラスが必要になります。第8章「メッセージ・インフローとトランザクション・インフロー」を参照してください。

これらのリソース・アダプタ・クラスの詳細は、開発するリソース・アダプタの性質によって異なります。

汎用ワーク・コンテキスト

コネクタ・アーキテクチャ1.6では汎用ワーク・コンテキストが定義されます。これは、リソース・アダプタが、メッセージの配信またはWorkインスタンスの発行の際に、コンテキスト情報をEISからWebLogic Serverに伝播するために使用するメカニズムです。汎用ワーク・コンテキストは、一連のクラス、インタフェースおよびメソッドで構成されます。また、WebLogic Serverでサポートされる新しいスキーマ要素を含みます。

以下の項では、汎用ワーク・コンテキストをサポートするために追加されたこれらのエンティティについて説明します。

- 汎用ワーク・コンテキストをサポートするために追加されたインタフェース、クラスおよびメソッド

- 汎用ワーク・コンテキストをサポートするために追加されたデプロイメント記述子要素

汎用ワーク・コンテキストをサポートするために追加されたインタフェース、クラスおよびメソッド

汎用ワーク・コンテキストをサポートするために以下のインタフェースが追加されています。

インタフェース

説明

javax.resource.spi.work.WorkContext

リソース・アダプタがEISからインポートしたコンテキストをアプリケーション・サーバーに伝播するための、標準メカニズムとして使用されます。

javax.resource.spi.work.WorkContextLifecycleListener

Workインスタンスに関連付けられたWorkContextの処理中に発生する様々なイベントをモデル化します。WorkContextが、関連付けられているWorkインスタンスの実行コンテキストとして設定されると、WorkManagerからの通知を受け取るために、このインタフェースがWorkContextインスタンスによって実装されることがあります。

javax.resource.spi.work.WorkContextProvider

WorkインスタンスがWorkManagerによって実行されるとき、設定されるWorkContextインスタンスのListを関連付けるために、Workインスタンスが使用するメソッドを指定します。

汎用ワーク・コンテキストをサポートするために以下のクラスが追加されています。

クラス

説明

javax.resource.spi.work.WorkContextErrorCodes

WorkContextをWorkインスタンスに関連付けているときに発生する可能性があるエラー条件をモデル化します。

汎用ワーク・コンテキストをサポートするために以下のメソッドがBootstrapContextインタフェースに追加されています。

メソッド

説明

isContextSupported

リソース・アダプタは、このメソッドを使用して特定のWorkContextタイプに関するアプリケーション・サーバーのサポートを確認します。このメカニズムを使用すると、リソース・アダプタ開発者が、アプリケーション・サーバーで提供されるサポートに基づいてWorkインスタンスで発行されたWorkContextを動的に変更できるようになります。

汎用ワーク・コンテキストをサポートするために追加されたデプロイメント記述子要素

汎用ワーク・コンテキストをサポートするために、required-work-context要素がra.xmlファイル・スキーマに追加されています。この要素は、WebLogic Serverがサポートするリソース・アダプタで必要なWorkContextクラスを表します。必要なWorkContextクラスごとに個別のrequired-work-context要素が指定されます。

このデプロイメント記述子情報を指定するために@Connectorメタデータ注釈をリソース・アダプタのソース・ファイルで使用できることに注意してください。詳細は、『JSR 322: Java EE Connector Architecture 1.6』の18.4項「@Connector」を参照してください。

起動クラスとして実行するためのリソース・アダプタのプログラミング

次の項では、起動クラスとして実行するためのリソース・アダプタのプログラミングについて説明します。

- リソース・アダプタの最小限のコンテンツ

- Workインスタンスの送信

- Work送信の再試行

リソース・アダプタの最小限のコンテンツ

WebLogic Server起動クラスを使用する代わりに、javax.resource.ResourceAdapterを実装した最小限のリソース・アダプタ・クラスを持つリソース・アダプタをプログラミングし、そのクラスでstart()およびstop()メソッドを定義することができます。

注意:

ResourceAdapterインタフェースの定義のために、endpointActivation()、Deactivation()、およびgetXAResource()メソッドも定義する必要があります。

リソース・アダプタがデプロイされるときに、start()メソッドが呼び出されます。アンデプロイされるときに、stop()メソッドが呼び出されます。WebLogic Server起動クラスと同様に、リソース・アダプタが開始する作業はstart()メソッドの中で実行できます。

例4-1は、最小限のリソース・アダプタ・クラスを持つリソース・アダプタを示しています。これは、(println文を除けば)開発できる最小限のリソース・アダプタです。この例では、start()メソッドで実行される作業はstdout (標準出力)へのメッセージの出力のみです。

例4-1 最小限のリソース・アダプタ

import javax.resource.spi.ResourceAdapter;
import javax.resource.spi.endpoint.MessageEndpointFactory;
import javax.resource.spi.ActivationSpec;
import javax.resource.ResourceException;
import javax.transaction.xa.XAResource;
import javax.resource.NotSupportedException;
import javax.resource.spi.BootstrapContext;
/**
* This resource adapter is the absolute minimal resource adapter that anyone can build (other than removing the println's.)
*/
public class ResourceAdapterImpl implements ResourceAdapter
{
public void start( BootstrapContext bsCtx )
{
System.out.println( "ResourceAdapterImpl started" );
}
public void stop()
{
System.out.println( "ResourceAdapterImpl stopped" );
}
public void endpointActivation(MessageEndpointFactory messageendpointfactory, ActivationSpec activationspec)
throws ResourceException
{
throw new NotSupportedException();
}
public void endpointDeactivation(MessageEndpointFactory messageendpointfactory, ActivationSpec activationspec)
{
}
public XAResource[] getXAResources(ActivationSpec aactivationspec[])
throws ResourceException
{
throw new NotSupportedException();
}
}

Workインスタンスの送信

リソース・アダプタでは、start()メソッド内でBootstrapContextを介してワーク・マネージャにアクセスするため、直接的なスレッド管理は使用しないで、Workインスタンスを送信する必要があります。それによって、WebLogic Serverは自動チューニングのワーク・マネージャを通じて、スレッドを効率的に管理できます。

実行用にWorkインスタンスが送信されたら、リソース・アダプタの完全なデプロイメントに干渉しないように、start()メソッドはすぐに復帰する必要があります。そのため、ワーク・マネージャでは、doWork()メソッドではなく、scheduleWork()またはstartWork()メソッドを呼び出す必要があります。

例4-2は、Workインスタンスをワーク・マネージャに送信するリソース・アダプタを示しています。リソース・アダプタはstart()メソッド内で作業を開始します。したがって、Java EEに準拠した起動クラスとして機能します。

例4-2 ワーク・マネージャを使用し、Workインスタンスを送信するリソース・アダプタ

import javax.resource.NotSupportedException;
import javax.resource.ResourceException;
import javax.resource.spi.ActivationSpec;
import javax.resource.spi.BootstrapContext;
import javax.resource.spi.ResourceAdapter;
import javax.resource.spi.endpoint.MessageEndpointFactory;
import javax.resource.spi.work.Work;
import javax.resource.spi.work.WorkException;
import javax.resource.spi.work.WorkManager;
import javax.transaction.xa.XAResource;
/**
* This Resource Adapter starts some work in the start() method,
* thus serving as a Java EE compliant "startup class"
*/
public class ResourceAdapterWorker implements ResourceAdapter
{
private WorkManager wm;
private MyWork someWork;
public void start( BootstrapContext bsCtx )
{
System.out.println( "ResourceAdapterWorker started" );
wm = bsCtx.getWorkManager();
try
{
someWork = new MyWork();
wm.startWork( someWork );
}
catch (WorkException ex)
{
System.err.println( "Unable to start work: " + ex );
}
}
public void stop()
{
// stop work that was started in the start() method
someWork.release();
System.out.println( "ResourceAdapterImpl stopped" );
}
public void endpointActivation(MessageEndpointFactory messageendpointfactory,
ActivationSpec activationspec)
throws ResourceException
{
throw new NotSupportedException();
}
public void endpointDeactivation(MessageEndpointFactory
messageendpointfactory, ActivationSpec activationspec)
{
}
public XAResource[] getXAResources(ActivationSpec activationspec[])
throws ResourceException
{
throw new NotSupportedException();
}
// Work class
private class MyWork implements Work
{
private boolean isRunning;
public void run()
{
isRunning = true;
while (isRunning)
{
// do a unit of work (e.g. listen on a socket, wait for an inbound msg,
// check the status of something)
System.out.println( "Doing some work" );
// perhaps wait some amount of time or for some event
try
{
Thread.sleep( 60000 ); // wait a minute
}
catch (InterruptedException ex)
{}
}
}
public void release()
{
// signal the run() loop to stop
isRunning = false;
}
}
}

Work送信の再試行

リソース・アダプタによるWorkインスタンスの送信が、一過性の失敗を経験するような場合があります。たとえば、『JSR 322: Java EE Connector Architecture 1.6』には、オプションのstartTimeoutパラメータをWorkManagerインタフェース実装で使用して、Workインスタンスの実行を開始する時間間隔を指定する方法が記述されています。Work送信がタイムアウトすると、Work送信エラーが発生し、WorkRejectedExceptionが生成されます。

『JSR 322: Java EE Connector Architecture 1.6』によれば、アプリケーション・サーバーがRetryableWorkRejectedExceptionをスローするのは、Work送信の失敗の原因が一過性であると判断された場合です。RetryableWorkRejectedExceptionを受け取ると、リソース・アダプタはWorkインスタンスの送信を再試行する場合があります。WebLogic Serverでは、次のような一過性の失敗の状況でRetryableWorkRejectedExceptionがサポートされます。

- Workインスタンスが一時停止中のワーク・マネージャに送信されたとき。

- Work送信がタイムアウトしたとき。

注意:

WebLogic Serverでは、接続インスタンスが一時停止中の接続プールに接続しようとすると、再試行可能な例外サポートがアウトバウンド接続プールまで拡張されます。詳細は、「接続の再試行」を参照してください。

リソース・アダプタのアクティビティの中断と再開

suspend()メソッドを使用するようにリソース・アダプタをプログラミングすると、アクティビティを中断するためのカスタムの動作を行えます。たとえば、suspend()メソッドを使用すると、進行中のトランザクションが完了するまでの間、すべての着信メッセージをキューに入れたり、メッセージの受信が一時的にブロックされていることをエンタープライズ情報システム(EIS)に通知したりできます。

その後でresume()メソッドを呼び出して、インバウンド・キューを排出してメッセージを配信するように指示したり、EISにメッセージのインバウンドが再び可能になったことを通知したりします。基本的に、resume()メソッドによってリソース・アダプタは通常の処理を続行できるようになります。

suspend()およびresume()メソッドを開始するには、WebLogic Scripting Toolを使用して、またはWebLogic Server管理コンソールから、リソース・アダプタのランタイムMBeanをプログラム的に呼び出します。詳細は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプのリソース・アダプタの起動と停止に関する項を参照してください。

Suspendable.supportsSuspend()メソッドでは、リソース・アダプタが特定の種類の中断をサポートしているかどうかを判断します。Suspendable.isSuspended()メソッドでは、リソース・アダプタが現在中断されているかどうかを判断します。

suspend()、resume()、または本番再デプロイメントをサポートするリソース・アダプタでは、Suspendableインタフェースを実装して、これらの操作がサポートされることをWebLogic Serverに知らせる必要があります。これらの操作は、以下のことが行われた場合にWebLogic Serverによって呼び出されます。

- コネクタ・コンポーネントMBeanのsuspend()メソッドによって中断が呼び出された場合。

- (リソース・アダプタを含むアプリケーションの新しいバージョンがデプロイされるときに)本番再デプロイメント・シーケンスが呼び出された場合。「Suspendableインタフェースと本番再デプロイメント」を参照してください。

例4-3では、リソース・アダプタのSuspendableインタフェースを示しています。

例4-3 Suspendableインタフェース

package weblogic.connector.extensions;
import java.util.Properties;
import javax.resource.ResourceException;
import javax.resource.spi.ResourceAdapter;
/**
* Suspendable may be implemented by a ResourceAdapter JavaBean if it
* supports suspend, resume or side-by-side versioning
* @author Copyright (c) 2002 by BEA Systems, Inc. All Rights Reserved.
* @since November 14, 2003
*/
public interface Suspendable
{
/**
* Used to indicate that inbound communication is to be suspended/resumed
*/
int INBOUND = 1;
/**
* Used to indicate that outbound communication is to be suspended/resumed
*/
int OUTBOUND = 2;
/**
* Used to indicate that submission of Work is to be suspended/resumed
*/
int WORK = 4;
/**
* Used to indicate that INBOUND, OUTBOUND & WORK are to be suspended/resumed
*/
int ALL = 7;
/**
* May be used to indicate a suspend() operation
*/
int SUSPEND = 1;
/**
* May be used to indicate a resume() operation
*/
int RESUME = 2;
/**
* Request to suspend the activity specified. The properties may be null or
* specified according to RA-specific needs
* @param type An int from 1 to 7 specifying the type of suspension being
* requested (i.e. Suspendable.INBOUND, .OUTBOUND, .WORK or the sum of one
* or more of these, or the value Suspendable.ALL )
* @param props Optional Properties (or null) to be used for ResourceAdapter
* specific purposes
* @exception ResourceException If the resource adapter can't complete the
* request
*/
void suspend( int type, Properties props ) throws ResourceException;
/**
* Request to resume the activity specified. The Properties may be null or
* specified according to RA-specific needs
*
* @param type An int from 1 to 7 specifying the type of resume being
* requested (i.e. Suspendable.INBOUND, .OUTBOUND, .WORK or the sum of
* one or more of these, or the value Suspendable.ALL )
* @param props Optional Properties (or null) to be used for ResourceAdapter
* specific purposes
* @exception ResourceException If the resource adapter can't complete the
* request
*/
void resume( int type, Properties props ) throws ResourceException;
/**
*
* @param type An int from 1 to 7 specifying the type of suspend this inquiry
* is about (i.e. Suspendable.INBOUND, .OUTBOUND, .WORK or the sum of
* one or more of these, or the value Suspendable.ALL )
* @return true iff the specified type of suspend is supported
*/
boolean supportsSuspend( int type );
/**
*
* Used to determine whether the specified type of activity is
* currently suspended.
*
* @param type An int from 1 to 7 specifying the type of activity
* requested (i.e. Suspendable.INBOUND, .OUTBOUND, .WORK or the sum of
* one or more of these, or the value Suspendable.ALL )
* @return true iff the specified type of activity is suspened by this
* resource adapter
*/
boolean isSuspended( int type );
/**
* Used to determine if this resource adapter supports the init() method used for
* resource adapter versioning (side-by-side deployment)
*
* @return true iff this resource adapter supports the init() method
*/
boolean supportsInit();
/**
* Used to determine if this resource adapter supports the startVersioning()
* method used for
* resource adapter versioning (side-by-side deployment)
*
* @return true iff this resource adapter supports the startVersioning() method
*/
boolean supportsVersioning();
/**
* Used by WLS to indicate to the current version of this resource adapter that
* a new version of the resource adapter is being deployed. This method can
* be used by the old RA to communicate with the new RA and migrate services
* from the old to the new.
* After being called, the ResourceAdapter is responsible for notifying the
* Connector container via the ExtendedBootstrapContext.complete() method, that
* it is safe to be undeployed.
*
* @param ra The new ResourceAdapter JavaBean
* @param props Properties associated with the versioning
* when it can be undeployed
* @exception ResourceException If something goes wrong
*/
void startVersioning( ResourceAdapter ra,
Properties props ) throws ResourceException;
/**
* Used by WLS to inform a ResourceAdapter that it is a new version of an already
* deployed resource adapter. This method is called prior to start() so that
* the new resource adapter may coordinate its startup with the resource adapter
* it is replacing.
* @param ra The old version of the resource adapter that is currently running
* @param props Properties associated with the versioning operation
* @exception ResourceException If the init() fails.
*/
void init( ResourceAdapter ra, Properties props ) throws ResourceException;
}

拡張されたBootstrapContext

リソース・アダプタをデプロイするときに、そのアダプタのra.xml記述子のresource-adapter-class要素でリソース・アダプタJavaBeanが指定されている場合、Weblogic Serverコネクタ・コンテナでは、『JSR 322: Java EE Connector Architecture 1.6』に従って、そのリソース・アダプタBeanのstart()メソッドを呼び出します。リソース・アダプタのコードでは、start()メソッドによって渡されるBootstrapContextオブジェクトを、次のような目的に使用できます。

- Workインスタンスを送信するためにWorkManagerオブジェクトを取得する

- Timerを作成する

- トランザクション・インフローで使用するためのXATerminatorを取得する

このような機能はすべてコネクタ・アーキテクチャ1.6に規定されています。

必須のjavax.resource.spi.BootstrapContextの実装に加えて、リソース・アダプタのstart()メソッドに渡されるBootstrapContextオブジェクトでは、weblogic.connector.extensions.ExtendedBootstrapContextも実装します。それによって、診断機能を提供し、Contexts and Dependency Injection (CDI)もサポートするWebLogic Server固有の拡張機能に、リソース・アダプタがアクセスできます。以下の節ではこれらの拡張機能について説明します。

- 診断コンテキストID

- 仕分けビット

- コールバック機能

- Beanの検証

- BeanManager

診断コンテキストID

WebLogic Server診断フレームワークでは、スレッドに診断コンテキストを関連付けることができます。スレッド上のリクエストは、実行パスに従って進行するように、その診断コンテキストを存続期間中に伝達し続けます。ExtendedBootstrapContextによって、リソース・アダプタ開発者は、EISからメッセージのエンドポイントに至るリクエストの実行のトレースなどに使用できるStringから構成される診断コンテキストのペイロードを設定できるようになります。

この容量によって、様々な診断プロセスが提供されます。たとえば、EISからのインバウンド・メッセージ上でクライアントIDまたはセッションIDにStringを設定できます。メッセージのディスパッチ中、各種診断が収集されてシステムからリクエスト・フローが表示されます。リソース・アダプタ・クラスの開発時に、setDiagnosticContextID()およびgetDiagnosticContextID()メソッドをこの目的で利用できます。

次の診断コンテキスト・ペイロードのコンテンツに関してご注意ください。

- ペイロードは、同一の実行コンテキストの他のコードによって表示でき、またWorkインスタンスに従ってプロセスからフローできます。このため、たとえばgetDiagnosticContextID()メソッドによって返される可能性があるペイロードには、アプリケーションが一切の機密データを含めていないことを確認する必要があります。

- ペイロードは同一の実行コンテキストで他のコードによって上書きできます。このため、アプリケーションには、ペイロードで使用可能な固有のコンテキストIDへの依存性は含めません。また、アプリケーションはペイロードのコンテキストIDが使用前に期待される値に一致することを検証する必要もあります。

診断コンテキストの詳細は、『Oracle WebLogic Server診断フレームワークの構成と使用』を参照してください。

仕分けビット

WebLogic Server診断フレームワークは、リクエストを仕分けする機能も備えています。ExtendedBootstrapContextを使用すると、リソース・アダプタ開発者がどの目的で診断を行う場合でも、現在のスレッド上で4つの仕分けビットを設定し、取得できます。たとえば、仕分けビットを使用してリクエストの優先度を設定できます。リクエスト仕分けの詳細は、『Oracle WebLogic Server診断フレームワークの構成と使用』を参照してください。

コールバック機能

ExtendedBootstrapContext.complete()メソッドをコネクタ・コンテナへのコールバックとして使用できます。この機能の詳細は、『Oracle WebLogic Serverへのアプリケーションのデプロイ』の本番環境でのアプリケーションの再デプロイに関する項を参照してください。

Beanの検証

『JSR 303: Bean Validation』をサポートするため、WebLogic ServerはモジュールレベルのBean検証構成ファイルを提供してJava EE 6を拡張します。WebLogic Serverはこれを使用してリソース・アダプタ・モジュールを検証します。

場合によっては、リソース・アダプタによって管理される他のBeanインスタンスの検証を、リソース・アダプタで実行する必要があります。リソース・アダプタには独自のJNDIネームスペースがないため、JNDIを使用して独自のValidatorインスタンスとValidatorFactoryインスタンスをルックアップできません。かわりに、リソース・アダプタはCDIを使用してこれらのBeanをインジェクトできます。または、ExtendedBootstrapContextインタフェースで次のメソッドを使用して、それらのBeanのインスタンスを取得できます。

- getValidator()

- getValidatorFactory()

BeanManager

『JSR 299: Contexts and Dependency Injection for the Java EE Platform』(CDI)をサポートするために、WebLogic ServerはExtendedBootstrapContextインタフェースにgetBeanManagerメソッドを実装します。リソース・アダプタはこのメソッドを呼び出して、独自のBeanManagerインスタンスを取得し、リソース・アダプタ内で管理対象BeanのCDI形式のインジェクションを実行できます。

注意:

以下の制限に注意してください。

- 別の呼出し元スレッドによるリソース・アダプタのBeanManagerインスタンスの使用はサポートされません。

- BeanManagerインスタンスを使用して、リソース・アダプタ・コンポーネントBeanのライフ・サイクルを管理することはできません。

CDIを使用するためのExtendedBootstrapContextインタフェースでのgetBeanManagerメソッドの使用の詳細は、第5章「リソース・アダプタでのContexts and Dependency Injectionの使用」を参照してください。

管理対象オブジェクトの一意性

コネクタ・アーキテクチャ1.6によってリソース・アダプタでは、同じインタフェースを実装する複数の管理対象オブジェクト・クラスを持つことができます。ただし、同じインタフェースおよびクラス名の組合せの管理対象オブジェクト定義が多くとも1つ必要です(『JSR 322: Java EE Connector Architecture 1.6』の20.4.1項「Resource Adapter Provider」を参照)。adminobject-type-uniqueness制約がadminobject-interfaceおよびadminobject-classの組合せを定義するために、ra.xmlファイルのスキーマ定義に追加されています。

以前のリリースのWebLogic Serverでは、weblogic-ra.xmlで定義された管理オブジェクト・グループの、ra.xmlで定義された対応する管理オブジェクトへのマッピングは、管理オブジェクト・インタフェースのみに基づいていました。ただし、同じインタフェースを持つ複数の管理オブジェクト・クラスをサポートするため、WebLogic Serverにはweblogic-ra.xmlのadmin-object-group要素に対するオプションのadmin-object-classサブ要素が含まれています。admin-object-classサブ要素を使用して、管理オブジェクトのインタフェースおよびクラスの組合せを定義できます。WebLogic Serverではこれをra.xmlで定義された対応する管理オブジェクトへマッピングできます。

管理オブジェクト・グループをマッピングする際、WebLogic Serverでは次のルールが使用され、これによっても1.0および1.5のアダプタとの下位互換性が保証されます。

- weblogic-ra.xmlで定義された管理オブジェクト・グループに管理オブジェクト・インタフェースおよびクラスの両方が含まれる場合、WebLogic Serverはそのインタフェースおよびクラスを、ra.xml内の対応する管理オブジェクト定義に照合しようとします。

- weblogic-ra.xmlで定義された管理オブジェクト・グループに管理オブジェクト・インタフェースが1つだけ含まれ、照合する管理オブジェクト・インタフェースがra.xmlで複数定義されている場合、WebLogic Serverではエラーが発生します。

- weblogic-ra.xmlで定義された管理オブジェクト・グループに管理オブジェクト・インタフェースが1つだけ含まれ、照合する管理オブジェクト・インタフェースがra.xmlで1つだけ定義されている場合、その特定の管理オブジェクト・インタフェースが使用されます。

5 リソース・アダプタでのContexts and Dependency Injectionの使用

この章では、WebLogic Serverのコネクタ・アーキテクチャ1.6の実装における『JSR 299: Contexts and Dependency Injection for the Java EE Platform』(CDI)のサポートについて説明します。

この章の内容は以下のとおりです。

- 概要

- リソース・アダプタBeanの検出

- リソース・アダプタBeanのコンテキスト参照の取得

- 他のアプリケーション・タイプからのリソース・アダプタBeanの呼出し

- CDI Beanアーカイブとしてデプロイされたリソース・アダプタの使用

- リソース・アダプタ・コンポーネントBeanでのCDIの使用

概要

CDI仕様は、インジェクションを使用してアプリケーションに依存関係を指定するための一連のサービスを定義します。CDIでは、コンテキストによるBeanのライフ・サイクル管理、型保証のインジェクション・ポイント、疎結合のイベント・フレームワーク、疎結合のインターセプタとデコレータ、Beanの代替実装、Unified Expression Language (EL)でのBeanナビゲーション、およびCDI拡張機能がサードパーティのフレームワークまたは将来のJava EEコンポーネントをサポートできるようにするサービス・プロバイダ・インタフェース(SPI)が提供されます。

コネクタ・アーキテクチャ1.6のWebLogic Server実装でのCDIサポートは、以下の関連する仕様に基づいています。

- 『JSR 299: Contexts and Dependency Injection for the Java EE Platform』(http://www.jcp.org/en/jsr/summary?id=299)

- 『JSR 330: Dependency Injection for Java』(http://jcp.org/en/jsr/summary?id=330)

CDIのこの他の一般的な情報は、以下を参照してください。

- 『Oracle WebLogic Serverアプリケーションの開発』のJava EEプラットフォームのContexts and Dependency Injectionの使用に関する項

- 『Java EE 6 Tutorial』の「Introduction to Contexts and Dependency Injection for the Java EE Platform」

リソース・アダプタBeanの検出

リソース・アダプタRARがBeanアーカイブの場合、WebLogic ServerはRAR内のすべてのJARファイルを、検出できるBeanアーカイブとして扱います。これは、それらのJARにMETA-INF/beans.xmlファイルが含まれるかどうかに関係ありません。アーカイブ記述子ファイルbeans.xmlがMETA-INFディレクトリにある場合、リソース・アダプタRARはBeanアーカイブです。

WebLogic Serverでは、RAR内のネストされたJARに存在するbeans.xmlファイルは無視されます。

アプリケーションがリソース・アダプタRAR Beanアーカイブとしてデプロイされると、WebLogic Serverコネクタ・コンテナは、BeanとBean参照を以下の場所で検索します。

- リソース・アダプタRAR

- リソース・アダプタRAR内に直接パッケージ化されたすべてのクラス

- アダプタRARで参照されるすべてのBeanアーカイブ

リソース・アダプタBeanのコンテキスト参照の取得

リソース・アダプタは、独自のJNDIネームスペースがない点が、WebアプリケーションまたはEJBとは異なります。つまり、リソース・アダプタ・モジュールには、java:comp、java:moduleまたはjava:appネームスペースがありません。したがって、名前付き管理対象Beanをリソース・アダプタのJNDIネームスペースにバインドできません。また、リソース・アダプタのJNDIネームスペースからルックアップを実行したり(Java EE 6管理対象Bean仕様の指定)、Java EE 6 @Resource注釈を使用して事前定義済Beanをインジェクトしたりすることもできません。

ただし、WebLogic ServerではExtendedBootstrapContext.getBeanManager()メソッドが提供されます。リソース・アダプタはgetBeanManagerメソッドを呼び出して、アダプタ・モジュールのBeanManagerインスタンスを公開できます。

他のアプリケーション・タイプからのリソース・アダプタBeanの呼出し

WebLogic Serverコネクタ・コンテナでは、リソース・アダプタRAR Beanアーカイブに含まれるCDI Beanクラスを、他のWebアプリケーションまたはEJBにインジェクトすることはサポートされません。WebLogic Serverのサポートには制限があり、アダプタRAR Beanアーカイブ内のCDI Beanを、他の呼出し元WebアプリケーションまたはEJBから使用するか呼び出すことだけが認められています。これは、CDI Beanがクライアント・プロキシではないことが条件です。

CDI Beanアーカイブとしてデプロイされたリソース・アダプタの使用

リソース・アダプタがCDI Beanアーカイブとしてデプロイされる場合、WebLogic Serverコネクタ・コンテナはリソース・アダプタ内でCDI Beanに次のサポートを提供します。

- デプロイされたリソース・アダプタ内の管理対象Bean、デコレータ、インターセプタ、イベントなどを検出する機能

- サードパーティの移植可能な拡張機能のサポート(『JSR 299: Contexts and Dependency Injection for the Java EE Platform』の第11章「Portable Extensions」で定義)

- BeanManagerによって公開されるCDI機能のサポート

- リソース・アダプタ内の管理対象BeanでのBeanのインスタンス化、インジェクション、デコレータ、インターセプタ、イベントなどのサポート

次の点に注意してください。

- リソース・アダプタのBeanManagerインスタンスは、ExtendedBootstrapContextオブジェクトのgetBeanManagerメソッドによって公開されます。

- WebLogic ServerでアダプタのBeanManagerの使用がサポートされるのは、そのアダプタ独自のスレッドにおいてのみです。アダプタのBeanManagerは、別のアプリケーションのスレッドでは使用できません。

- WebLogic Serverコネクタ・コンテナは、リソース・アダプタ・モジュール内の組込みBeanManager Beanタイプのインジェクションをサポートします。たとえば、ResourceAdapter Beanに対するインジェクトがサポートされます。

- リソース・アダプタの管理対象BeanでのResourceインジェクション注釈の使用はサポートされません。

BeanManagerのサポート

リソース・アダプタのBeanManagerは次のいずれかの状況で使用できます。

- ResourceAdapter.startメソッドの呼出しなど、アダプタのデプロイメント・プロセス

- リソース・アダプタのWorkManagerインスタンスによってスケジュールされるWork.runメソッド内

WebLogic Serverコネクタ・コンテナは、リソース・アダプタ・モジュール内で組込みBeanManager Beanタイプのインジェクションをサポートします。ただし、呼出し元スレッドによるリソース・アダプタのBeanManagerインスタンスの使用はサポートされません。

インジェクション・ポイント

WebLogic Serverコネクタ・コンテナは、CDI Beanアーカイブとしてデプロイされたリソース・アダプタ内で以下のBeanのインジェクション・ポイントをサポートします。

- 『JSR 299: Contexts and Dependency Injection for the Java EE Platform』によりJava EEコンテナへの提供が求めれられる以下の組込みBean

- UserTransaction — WebLogic JTAによって提供されます。

- Principal — WebLogic Serverコネクタ・コンテナによって設定される呼出し側プリンシパル。この値は、インジェクトの時点ではなく、このインスタンスが使用される時点でスレッドのプリンシパルです。

- ValidationFactory — リソース・アダプタ・モジュール自体のValidationFactoryインスタンス。ExtendedBootstrapContext.getValidatorFactoryメソッドからもアクセスできます。

- Validator — リソース・アダプタ・モジュール自体のValidatorインスタンス。ExtendedBootstrapContext.getValidatorメソッドからもアクセスできます。

- リソース・アダプタ・モジュールそのもののBeanManagerインスタンス(『JSR 299: Contexts and Dependency Injection for the Java EE Platform』の11.3項で定義)。ExtendedBootstrapContext.getBeanManagerメソッドからアクセスできます。

- 『JSR 299: Contexts and Dependency Injection for the Java EE Platform』およびJava EE 6管理対象Bean仕様(『JSR 316: Java Platform, Enterprise Edition 6 (Java EE 6) Specification』に含まれる)に準拠する、すべての管理対象Bean。

- 現在のリソース・アダプタ・モジュールに含まれる、以下のタイプの特別なコネクタ・アーキテクチャ1.6組込みBean。

- 現在のリソース・アダプタBeanへの参照のインジェクションを行うことができるjavax.resource.spi.ResourceAdapter。常に、現在のアダプタ・モジュールのResourceAdapter Beanインスタンスまたはnull (ResourceAdapter Beanが現在のリソース・アダプタ・モジュールに定義されていない場合)を参照します。

- javax.resource.spi.BootstrapContextまたはweblogic.connector.extensions.ExtendedBootstrapContext。現在のリソース・アダプタのBootstrapContext Beanインスタンスまたはnull (ResourceAdapter Beanが現在のリソース・アダプタ・モジュールに定義されていない場合)のいずれかへの参照のインジェクションが可能です。このBeanタイプは、ResourceAdapter.start(BootstrapContext ctx)メソッドの呼出しのパラメータでも使用できます。

- javax.resource.spi.work.WorkManager。現在のリソース・アダプタのWorkManagerインスタンス(BootstrapContext.getWorkManager()メソッドからも使用できる)またはnull (ResourceAdapter Beanが現在のリソース・アダプタ・モジュールで定義されていない場合)のいずれかへの参照のインジェクションが可能です。

- javax.resource.spi.XATerminator。現在のリソース・アダプタのXATerminatorインスタンス(BootstrapContext.getXATerminatorメソッドからも使用できる)またはnull (ResourceAdapter Beanが現在のリソース・アダプタ・モジュールで定義されていない場合)のいずれかへの参照のインジェクションが可能です。

- javax.transaction.TransactionSynchronizationRegistry。JTA TransactionSynchronizationRegistryインスタンス(BootstrapContext.getTransactionSynchronizationRegistryメソッドからも使用できる)への参照のインジェクションが可能です。

リソース・アダプタ・コンポーネントBeanでのCDIの使用

WebLogic Serverは、リソース・アダプタ・コンポーネントBeanと呼ばれる4種類のBeanをサポートしています。これらによって、WebLogic Serverコネクタ・コンテナで管理される特別なコンポーネントが定義されます。リソース・アダプタ・コンポーネントBeanはPOJO (Plain Old Java Object)です。リソース・アダプタ・コンテナによって作成および管理され、ライフ・サイクルが特殊です。

アダプタ・コンポーネントBeanのタイプは以下のとおりです。

- ResourceAdapter Bean — javax.resource.spi.ResourceAdapterインタフェースを実装するリソース・アダプタ・クラス。ライフ・サイクル管理とメッセージ・エンドポイント設定の処理が含まれます。

- ManagedConnectionFactory Bean — javax.resource.spi.ManagedConnectionFactoryインタフェースを実装するJavaBeanクラス。これは、ManagedConnectionおよびEIS固有の接続ファクトリ・インスタンス両方のファクトリです。このインタフェースは、ManagedConnectionインスタンスの照合と作成のためのメソッドを提供して、接続プーリングをサポートします。

- ActivationSpec Bean — javax.resource.spi.ActivationSpecインタフェースを実装するJavaBeanクラス。メッセージ・エンドポイントのアクティブ化構成情報を保持します。

- 管理対象オブジェクトまたは管理オブジェクト — メッセージング・スタイルまたはメッセージ・プロバイダに固有のオブジェクトを表すJavaBeanクラスのオプション・セット。

リソース・アダプタ・コンポーネントBeanでは以下のメタデータ注釈を使用できます。

- @Connector

- @Activation

- @ConnectionDefinition

- @ConnectionDefinitions

- @AdministeredObject

注意:

先行注釈はコネクタ・アーキテクチャ1.6に新たに追加されました。ra.xmlの対応する要素のかわりに使用することをお薦めします。

以下の項では、リソース・アダプタ・コンポーネントBeanのプログラミング要件の重要な情報を説明します。

- リソース・アダプタ・コンポーネントBeanを管理対象Beanにしない

- 依存関係インジェクションの使用

動的に構成可能なプロパティをリソース・アダプタ・コンポーネントBeanに設定する方法の詳細は、「動的に再構成できる構成プロパティ」を参照してください。

リソース・アダプタ・コンポーネントBeanを管理対象Beanにしない

リソース・アダプタ・コンポーネントBeanを管理対象Beanにしてはいけません。ただし、『JSR 299: Contexts and Dependency Injection for the Java EE Platform』に定義されているように、WebLogic Serverコネクタ・コンテナでは、リソース・アダプタ・コンポーネントBeanへの管理対象BeanのCDIインジェクションがサポートされます。WebLogic Serverでは、アダプタ・コンポーネントBeanでのPostConstructとPreDestroyの注釈もサポートされます。

注意:

次の点に注意してください。

- WebLogic Serverコネクタ・コンテナでは、『JSR 316: Java Platform, Enterprise Edition 6 (Java EE 6) Specification』に含まれるJava EE 6管理対象Bean仕様に準拠する管理対象Beanはサポートされません。

- JSR 299で必要な条件を満たす管理対象Beanの設計の詳細は、『The Java EE 6 Tutorial』の「About Managed Beans」を参照してください。

リソース・アダプタ・コンポーネントBeanが管理対象Beanとして扱われないようにするために、次のいずれかのクラスレベル注釈がアダプタ・コンポーネントBean内で使用されていると、WebLogic Serverではアダプタのデプロイができません。

- javax.annotation.ManagedBean注釈

- すべてのスコープ注釈

- すべての修飾子注釈

- すべてのステレオタイプ注釈

- javax.inject.Named注釈

- javax.enterprise.inject.Alternative注釈

- javax.enterprise.inject.Specializes注釈

- javax.enterprise.inject.Typed注釈

- javax.decorator.Decorator注釈

- javax.decorator.Delegate注釈

依存関係インジェクションの使用

CDI Beanアーカイブとしてデプロイされるリソース・アダプタでは、アダプタ・コンポーネントBeanが作成されて初期化されると、WebLogic Serverコネクタ・コンテナはアダプタ・コンポーネントBeanのCDIをサポートします。

『Java Platform, Enterprise Edition (Java EE) Specification, Version 6』のEE.5.20項「Support for Dependency Injection (JSR-330)」に準拠するリソース・アダプタ・コンポーネントBeanの依存関係インジェクションをサポートするために、WebLogicコネクタ・コンテナはそれらのBeanを初期化するときに次の処理を実行します。

1. デプロイメント記述子の値を使用して、リソース・アダプタ・コンポーネントBean構成プロパティを初期化します。

2. 依存関係インジェクションによって初期化を実行した後で、PostConstruct注釈を使用します。

3. 『JSR 303: Bean Validation』に従ってBean検証を実行し、ActivationSpec Beanについてvalidate()メソッドを呼び出します。

4. ResourceAdapter Beanについてstart()メソッドを呼び出します。

5. すべてのリソース・アダプタ・コンポーネントBeanを、JNDIにバインドするか、エンドポイント・アプリケーションに公開して、使用できるようにします。

インジェクションの使用に関する注意事項

リソース・アダプタ・コンポーネントBeanは、標準の管理対象Beanではないため、リソース・アダプタ・モジュールの外部の他のBeanにインジェクトすることはできません。つまり、『JSR 299: Contexts and Dependency Injection for the Java EE Platform』に準拠している場合のようにリソース・アダプタ・モジュールの外部で認識されることはありません。インジェクションをサポートするようにアダプタ・コンポーネントBeanを設計できますが、管理対象Beanとして扱われないようにすることが重要です。リクエスト・スコープまたはセッション・スコープの概念は、リソース・アダプタ・コンポーネントBeanでは意味がないためです。

インジェクションは以下のようにサポートされます。

- フィールドとメソッドのインジェクションは、javax.inject.Inject注釈を使用してサポートされますが、コンストラクタのインジェクションはサポートされません。

- インジェクト済フィールド(『JSR 299: Contexts and Dependency Injection for the Java EE Platform』の3.8項の定義)はサポートされます。

- 「インジェクション・ポイント」のすべてのインジェクション・ポイント(weblogic.transaction.UserTransactionやjavax.resource.spi.BootstrapContextなど)がサポートされます。

- PostConstructおよびPreDestroyインジェクション注釈は以下のようにサポートされます。

- ResourceAdapter Beanタイプでは、構成プロパティが初期化された後でstart()メソッドが呼び出される前に、@PostConstructメソッドが呼び出されます。また、@PreDestroyメソッドはstop()のメソッドの後に続きます。

- 他のBeanタイプでは、構成プロパティが初期化された後でBeanがJNDIにバインドされる前に、@PostConstructメソッドが呼び出されます。また、@PreDestroyメソッドは、リソース・アダプタがアンデプロイされるときか、サーバーが停止されるときに呼び出されます。

- すべてのBeanで、WebLogic Serverは『JSR 303: Bean Validation』のサポートに基づいてBean検証を実行します。また、該当する場合には、@PostConstructメソッドを呼び出した後でvalidate()メソッドも呼び出します。

- イベント(『JSR 299: Contexts and Dependency Injection for the Java EE Platform』の第10章「Events」で定義)はサポートされます。

Resourceインジェクション注釈はリソース・アダプタ・モジュールではサポートされません。

例

次の例は、リソース・アダプタのデプロイ時に、WebLogic ServerがCDIに対応するMyResourceAdapterインスタンスを最初にインスタンス化するところです。MyResourceAdapterは、Connector注釈が付いているため、この例に示すリソース・アダプタ・モジュールのResourceAdapterコンポーネントBeanです。また、WebLogic Serverではデプロイ時に次の処理も行われます。

- MyBeanをインスタンス化し、javax.inject.Inject注釈を使用してMyResourceAdapterインスタンスにインジェクトします。

- このアダプタ・モジュールのValidatorインスタンスをMyResourceAdapterインスタンスにインジェクトします。

- このアダプタ・モジュールのWorkManagerインスタンスとUserTransactionインスタンスをMyBeanにインジェクトします。

@Connector
public class MyResourceAdapter implements ResourceAdapter{
private @Inject MyBean bean;
private @Validator v;

public void start(BootstrapContext ctx){
v.validate(this, AnotherGroup.class);
bean.do();
.
.
.
}
.
.
.
}

public class MyBean{
private String name;
private @WorkManager wm;
private @UserTransaction ut;

public String  getName(){
return name;
}

public void setName(String name) {
this.name = name;
}

public void do(){
Work w = …
wm.scheduleWork(w);
}
}

6 接続管理

この章では、コネクタ・アーキテクチャ1.6の要件に従って、WebLogic Serverとリソース・アダプタの間の接続管理規約について説明します。アウトバウンド接続とインバウンド接続、接続プール・パラメータ、および接続のテスト方法についても説明します。

この章の内容は以下のとおりです。

- 接続管理規約

- アウトバウンド接続の構成

- インバウンド接続の構成

- 接続プール・パラメータの構成

- 接続プロキシ・ラッパー - 1.0リソース・アダプタ

- 接続プールのリセット

- 接続のテスト

接続管理規約の詳細は、『JSR 322: Java EE Connector Architecture 1.6』の第6章「Connection Management」を参照してください。

接続管理規約

コネクタ・アーキテクチャ1.6の要件の1つは接続管理規約です。WebLogic Serverとリソース・アダプタの間の接続管理規約は以下のとおりです。

- 管理対象と非管理対象(2層)の両方のアプリケーションに対して、接続の取得に関する一貫性のあるアプリケーション・プログラミング・モデルを提供します。

- リソース・アダプタが、リソース・アダプタのタイプとEISに固有のCCI (common client interface)に基づいた接続ファクトリと接続インタフェースを提供できるようにします。これにより、既存のJDBC APIへの影響を最小限に抑えながら、JDBCドライバとJava EEコネクタ・アーキテクチャ1.6を協調させることができます。

- アプリケーション・サーバーが、構成されたリソース・アダプタに対して様々なサービス(トランザクション、セキュリティ、高機能なプール、エラーの追跡とロギングなど)を提供できるようにします。

- 接続プールをサポートします。

リソース・アダプタ側の接続管理規約は、リソース・アダプタのConnection、ConnectionFactory、ManagedConnectionおよびManagedConnectionFactoryクラスで具体化されます。

接続ファクトリと接続

Java EEアプリケーション・コンポーネントは、接続ファクトリと呼ばれるパブリック・インタフェースを使用して接続インスタンスにアクセスし、そのインスタンスを使用して基底のEISに接続します。接続の例には、データベース接続やJMS (Java Message Service)接続があります。

リソース・アダプタは接続と接続ファクトリを提供して、EIS接続の接続ファクトリとして機能します。たとえば、javax.sql.DataSourceおよびjava.sql.Connectionインタフェースは、リレーショナル・データベースに接続するためのJDBCベースのインタフェースです。

アプリケーションは、Java Naming and Directory Interface (JNDI)ネームスペースで接続ファクトリ・インスタンスをルックアップし、そのインスタンスを使用してEIS接続を取得します。ConnectionFactoryの取得(クライアントとJNDI間の対話)を参照してください。

JNDIツリーにバインドされたリソース・アダプタ

バージョン1.5および1.6のリソース・アダプタは、独立したオブジェクトとしてJNDIツリーにバインドされるので、独立したシステム・リソースとして、またはメッセージドリブンBean (MDB)のメッセージ・ソースとして使用できます。一方、バージョン1.0のリソース・アダプタは、JNDIツリーにバインドされたConnectionFactoryオブジェクトによって識別されます。

バージョン1.5または1.6のリソース・アダプタでは、デプロイメント時に、ResourceAdapter Beanがある場合は、weblogic-ra.xmlファイルのjndi-name要素の値を使用してJNDIツリーにバインドされます。その結果、管理者はリソース・アダプタを1つのデプロイ可能エンティティとして参照し、リソース・アダプタ・プロバイダによって公開されたリソース・アダプタの機能とやり取りすることができます。詳細は、付録A「weblogic-ra.xmlスキーマ」のjndi-nameを参照してください。

ConnectionFactoryの取得(クライアントとJNDI間の対話)

アプリケーション・アセンブラまたはコンポーネント・プロバイダは、アプリケーションのデプロイメント記述子で、そのアプリケーション・コンポーネントの接続ファクトリの要件を構成します。例:

res-ref-name: eis/myEIS
res-type: javax.resource.cci.ConnectionFactory
res-auth: Application or Container

リソース・アダプタ・デプロイヤは、リソース・アダプタの構成情報を提供します。

アプリケーションは、Java Naming and Directory Interface (JNDI)ネームスペースでConnectionFactoryインスタンスをルックアップし、そのインスタンスを使用してEIS接続を取得します。管理対象の環境にあるアプリケーションが、res-type変数で指定された接続ファクトリからEISインスタンスとの接続を取得すると、以下のようなイベントが発生します。

注意:

管理対象のアプリケーションの環境によって、EISにアクセスするJava EEベースのWeb対応多層アプリケーションの操作環境が定義されます。

1. アプリケーション・サーバーは、構成済みのリソース・アダプタを使用して、基底のEISとの物理接続を作成します。

2. アプリケーション・コンポーネントは、JNDIインタフェースを使用して、コンポーネントの環境でConnectionFactoryインスタンスをルックアップします(例6-1を参照)。

例6-1 JNDIルックアップ

//obtain the initial JNDI Naming context
Context initctx = new InitialContext();

// perform JNDI lookup to obtain the connection factory
javax.resource.cci.ConnectionFactory cxf =
(javax.resource.cci.ConnectionFactory)
initctx.lookup("java:comp/env/eis/MyEIS");

メソッドNamingContext.lookupで渡されるJNDI名は、デプロイメント記述子のres-ref-name要素で指定されているものと同じです。JNDIルックアップによって、res-type要素で指定されたjava.resource.cci.ConnectionFactory型のインスタンスが取得されます。

3. アプリケーション・コンポーネントは、返された接続を使用して基底のEISにアクセスします。

4. アプリケーション・コンポーネントは、ConnectionFactoryのgetConnectionメソッドを呼び出してEIS接続を取得します。返された接続インスタンスは、基底の物理接続へのアプリケーション・レベルのハンドルを表します。アプリケーション・コンポーネントは、接続ファクトリのgetConnectionメソッドを複数回呼び出して、複数の接続を取得します。

javax.resource.cci.Connection cx = cxf.getConnection();

5. 接続を使い終わると、コンポーネントはConnectionインタフェースのcloseメソッドを使用して接続を閉じます。

cx.close();

アプリケーション・コンポーネントが割り当てられた接続を使用後に閉じなかった場合、その接続は未使用の接続と見なされます。未使用の接続のクリーン・アップはアプリケーション・サーバーによって管理されます。

トランザクション・サポート・レベルの指定および取得

『JSR 322: Java EE Connector Architecture 1.6』の7.13項では、リソース・アダプタが実行時に提供するトランザクション・サポートのレベルを決定および分類できると指定されています。トランザクション・サポートのレベルを指定できるようにするには、リソース・アダプタのManagedConnectionFactoryクラスでTransactionSupportインタフェースを実装する必要があります。このインタフェースが実装されないと、リソース・アダプタのra.xmlファイルとConnector注釈のマージ結果に指定されたトランザクション・サポートがコネクタ・コンテナによって使用されます。

『JSR 322: Java EE Connector Architecture 1.6』では、ra.xmlファイル、Connector注釈およびTransactionSupportインタフェースで決定されるトランザクション・サポート・レベルの規則と優先度も定義されます。

WebLogic Serverは、次の2つのメソッドをConnectorConnectionPoolRuntimeMBeanで公開することで、トランザクション・サポート・レベルを取得するためのサポートを補完します。

- ConnectorConnectionPoolRuntimeMBean.getRuntimeTransactionSupport() — このコネクタ接続プールに対して使用中の実際のトランザクション・サポート・レベルを返します。
この値は、WebLogic Server管理コンソールの「リソース・アダプタ」>「監視」>「アウトバウンド接続プール」ページでも参照できます。

- ConnectorConnectionPoolRuntimeMBean.getTransactionSupport() — このコネクタ接続プールのリソース・アダプタに対する、ra.xmlまたは@Connector注釈の使用によって構成されている、静的なトランザクション・サポート・レベルを返します。

共有不可能なManagedConnectionFactoryの指定

大半の場合、アダプタのManagedConnectionFactoryは、『JSR 322: Java EE Connector Architecture 1.6』の7.9項で定義されるように、接続の共有をサポートします。また、この仕様では、コール元アプリケーションのデプロイメント記述子または注釈でres-sharing-scopeを共有不可に設定することによって、接続が共有不可能にできると説明しています。

ただし、コール元アプリケーションで共有不可能なリソースの参照を定義するのには不都合がある可能性があります。たとえば、コール元アプリケーションはWebLogicのグローバルJNDIから直接にConnectionFactoryプールへの参照を実行できますが、アプリケーションはこのプールへの共有不可能なリソースの参照を定義しません。WebLogic Serverは、このようなプールの使用をデフォルトで共有不可能として処理します。その結果、アダプタが接続の共有をサポートしない場合、アダプタは機能しません。

この問題を回避するため、WebLogic Serverはweblogic.connector.extensions.Unshareableというパブリック注釈をサポートします。この注釈は、ManagedConnectionFactoryが共有をサポートしない場合にManagedConnectionFactoryクラスで使用できます。このようなアダプタがデプロイされると、WebLogic ServerはManagedConnectionFactoryクラスをチェックし、ManagedConnectionFactoryおよび関連プールを共有不可能として処理します。WebアプリケーションまたはEnterprise Java Beanでこの共有不可能なプールへの共有可能なリソースの参照を構成する場合、WebLogic Serverは警告メッセージを表示しますが、それでもWebアプリケーションまたはEJBはプールを共有不可能として処理します。weblogic-ra.xmlまたは管理コンソールでは何も構成する必要がありません。

ManagedConnectionFactoryが共有可能な場合、アダプタのコードでは何も変更する必要はありません。すべてのManagedConnectionFactoryインスタンスおよびプールは、ManagedConnectionFactoryに共有不可注釈が含まれない場合でも、デフォルトでは共有可能とみなされます。

アウトバウンド接続の構成

コネクタ・アーキテクチャ1.6に基づいたアウトバウンド・リソース・アダプタでは、1つまたは複数のアウトバウンド接続を用意し、各接続でWebLogic Server固有の認証やトランザクションをサポートするように構成できます。ra.xmlおよびweblogic-ra.xmlデプロイメント記述子ファイルでアウトバウンド接続のプロパティを構成します。

接続プールの構成レベル

weblogic-ra.xmlデプロイメント記述子のoutbound-resource-adapter要素とそのサブ要素を使用して、リソース・アダプタのアウトバウンド・コンポーネントについて記述します。

アウトバウンド接続プールは以下の3つのレベルで定義できます。

- グローバル - default-connection-properties要素を使用して、リソース・アダプタのすべてのアウトバウンド接続グループに適用するパラメータを指定します。「default-connection-properties」を参照してください。

- グループ - connection-definition-group要素を使用して、ra.xmlデプロイメント記述子で指定された特定の接続ファクトリに属する、すべてのアウトバウンド接続インスタンスに適用するパラメータを指定します。ra.xmlの接続ファクトリとweblogic-ra.xmlの接続定義グループの間には、1対1の対応関係があります。グループで指定されたプロパティは、グローバル・レベルで指定されたパラメータをオーバーライドします。「connection-definition-group」を参照してください。
connection-factory-interface要素(connection-definition-group要素のサブ要素)は、各connection-definition-groupに必須の一意の要素(キー)として機能します。weblogic-ra.xmlのconnection-definition-interface要素とra.xmlのconnectiondefinition-interface要素の間には1対1の関係がなければなりません。

- インスタンス - weblogic-ra.xmlデプロイメント記述子のconnection-instance要素を使用して、各接続定義グループの下で接続インスタンスを指定できます。これは、リソース・アダプタに対する個別の接続プールに相当します。connection-propertiesのサブ要素を使用して、インスタンス・レベルでプロパティを指定することもできます。インスタンス・レベルで指定されたプロパティは、グループ・レベルやグローバル・レベルで指定されたプロパティをオーバーライドします。「connection-instance」を参照してください。

接続の再試行

アプリケーション・コンポーネントが、ConnectionFactoryにおけるgetConnection()メソッドを使用して接続プールから接続インスタンスを取得しようと試みても、プールが一時的に停止している場合は、WebLogic Serverでjavax.resource.spi.RetryableExceptionを実装する例外が発生します。アプリケーション・コンポーネントはRetryableExceptionのインスタンスを使用して、接続の失敗が一過性かどうかを判別できます。

アダプタの再デプロイなしの、アウトバウンド接続プール・エラーの
分離、トラブルシューティングおよび修正

デフォルトでは、リソース・アダプタに複数のアウトバウンド接続プールがある場合に、いずれかの接続プールでエラーが発生すると、リソース・アダプタ・デプロイメント全体が失敗します。ただし、deploy-as-a-wholeデプロイメント・オプションを使用できるため、これを設定して、個々のアウトバウンド接続プール・エラーをリソース・アダプタ・デプロイメントから分離できます。このデプロイメント・オプションを使用すると、アダプタのヘルス監視機能を使用して接続プール・エラーを識別できます。これにより、リソース・アダプタを再デプロイすることなく、トラブルシューティングと修復が行えます。

リソース・アダプタのヘルス監視機能の全般的な情報については、「リソース・アダプタのヘルス監視」を参照してください。weblogic-ra.xmlファイルのdeploy-as-a-whole要素の設定については、次のトピックを参照してください。

- deploy-as-a-whole: アダプタ・デプロイメント全体からのアウトバウンド接続プール・エラーの分離

- 複数のアウトバウンド接続プールで構成されたリソース・アダプタのデプロイ

次の項では、deploy-as-a-wholeデプロイメント・オプションの使用方法およびアウトバウンド接続プール・エラーの診断方法と回復方法について説明します。

deploy-as-a-wholeオプションの使用

個々のアウトバウンド接続プールのエラーが原因でアダプタ・デプロイメント全体が失敗することがないように、リソース・アダプタをデプロイするには、weblogic-ra.xmlファイルのdeploy-as-whole要素をfalseに設定する必要があります(デフォルトでは、この要素はtrueに設定されます)。このデプロイメント・オプションの設定の詳細は、「複数のアウトバウンド接続プールで構成されたリソース・アダプタのデプロイ」を参照してください。

deploy-as-a-wholeオプションがfalseに設定されている場合は、次のことに注意してください。

- デプロイメント中にエラーが発生しなかった場合は、リソース・アダプタのデプロイメントが成功してアクティブ状態になります(ヘルス状態はHEALTH_OK)。

- 少なくとも1つのアウトバウンド接続プールを作成中または構成中にエラーが発生した場合は、アダプタ・デプロイメントのヘルス状態がHEALTH_CRITICALに設定されます。

- 次のようなその他のエラーが発生した場合は、アダプタのデプロイメントは失敗します。

- ra.xmlファイル、weblogic-ra.xmlファイルまたはデプロイメント・プランの解析エラーまたは検証エラー。

- リソース・アダプタや管理オブジェクトBeanの作成中または構成中に発生するエラー。

- 静的に検出可能な、『JSR 322: Java EE Connector Architecture 1.6』で定義された基本要件に合致しないプール関連のクラス。たとえば、必須の標準インタフェースjavax.resource.spi.ManagedConnectionFactoryを実装していないアダプタのManagedConnectionFactoryクラスなどがあります。

失敗した接続プールのトラブルシューティング

接続プールの状態がHEALTH_CRITICALである場合、ConnectorConnectionPoolRuntimeMBeanのほとんどのメソッド(testPoolなど)では、起動してもIllegalStateExceptionがスローされます。起動できるのは次のメソッドのみです。これらは、静的情報を提供し、接続プール・エラーの影響は受けません。

- getKey()

- getPoolName()

- getState()(失敗したプールには常にShutdownが返されます)

- getHealthState()

- getManagedConnectionFactoryClassName()

- getMCFClassName()(getManagedConnectionFactoryClassName()と同様)

- getConnectionFactoryClassName()(接続プールのConnectionFactoryNameが返されます)

- reset()

- forceReset()

次の点に注意してください。

- 次のいずれかのアクションの実行後は、リソース・アダプタ・モジュールのヘルス状態はHEALTH_OKからHEALTH_CRITICALに変わる可能性があります。

- 動的更新の実行

- アウトバウンド接続プールのresetまたはforce resetのいずれかの実行

- リソース・アダプタの停止と再起動

- アダプタの再デプロイ

- 接続プールの状態がHEALTH_CRITICALである場合は、そのプールに対するsuspendおよびresumeアクションは効果がありません。

接続プールの回復手順

接続プールが失敗してHEALTH_CRITICAL状態になった場合は、失敗の理由を確認して、エラーを修正します。たとえば、プールの各プロパティの更新された値が有効で、適切に割り当てられていることを確認します。

不適切な構成により引き起こされたエラーのほとんどについて、次の手順を実行することをお薦めします。

1. 必要に応じて、失敗した各プールの構成を変更します。

2. 新しい構成をアダプタのデプロイメント・プランに保存します。

3. 更新済のアダプタのデプロイメント・プランを使用して、リソース・アダプタの動的更新を実行します。

前述の手順では、正常に機能している使用中の接続プールには影響を与えることなく、失敗したプールを回復できます。動的更新プロセスでは、失敗した接続プールはすべて、新しい構成データを使用して再作成されます。プールの構成変更が新しいデプロイメント・プランで行われたのかどうか、構成変更が動的に更新可能なのかどうかは関係ありません。正常に機能している既存の接続プールについては、動的でない構成変更は無視されます。ただし、失敗した接続プールの場合、構成の更新は動的更新プロセスから有効になります。

失敗した接続プールを回復するためのその他のオプション

失敗した接続プールを動的更新を実行して回復するかわりに、次のいずれかの方法を実行できます。失敗の原因が無効なプール構成以外の場合は、次のいずれかの方法が適しています。

- 「接続プールのリセット」に記載されているように、失敗した接続プールをリセットまたは強制リセットします。失敗の理由によっては、これらのアクションを実行しても、失敗したプールを回復できない場合があります。ただし、失敗したプールとの接続はアクティブでないため、リセットと強制リセットの効果は同じです。次の点に注意してください。

- プール・エラーの原因が無効な構成でない場合は、リセットすると、プールを回復できる可能性があります。この場合は、既存の構成データが使用されます。たとえば、エラーの原因がJNDIの競合である場合は、JNDIツリーからの競合するオブジェクトを削除すると、プールを回復できます。このシナリオでは、接続プールのリセットをお薦めします。

- 接続プールの失敗の原因が無効な構成にある場合は、接続プールのリセットはお薦めしません。リセットでは、既存のデプロイメント・プランまたは既存のデプロイメント記述子情報が使用されるため、無効な構成データが含まれるからです。

- アダプタを再デプロイします。このアクションは、正常に機能しているものも含めて、リソース・アダプタ内のすべてのアウトバウンド接続プールに影響します。

- リソース・アダプタを停止してから再起動します。このアクションも、アダプタ内のすべてのアウトバウンド接続プールに影響します。この方法には、resetやforce resetアクションを実行する場合と同じような短所があります。この方法でも、最初に動的更新を実行することなく、既存の構成データを使用するからです。また、修正はされたものの、動的更新で使用可能になっていない構成データは使用されません。こうした理由から、リソース・アダプタの停止と再起動は、ほとんどの場合、失敗した接続プールの回復で推奨されるオプションではありません。

複数のアウトバウンド接続の例

例6-2は、複数のアウトバウンド接続を構成したweblogic-ra.xmlデプロイメント記述子の例です。

例6-2 weblogic-ra.xmlデプロイメント記述子:複数のアウトバウンド接続

<?xml version="1.0" ?>
<weblogic-connector xmlns="http://xmlns.oracle.com/weblogic/weblogic-connector">
<jndi-name>900eisaNameOfBlackBoxXATx</jndi-name>
<outbound-resource-adapter>
<connection-definition-group>
<connection-factory-interface>javax.sql.DataSource
</connection-factory-interface>
<connection-instance>
<jndi-name>eis/900eisaBlackBoxXATxConnectorJNDINAME1
</jndi-name>
<connection-properties>
<pool-params>
<initial-capacity>2</initial-capacity>
<max-capacity>10</max-capacity>
<capacity-increment>1</capacity-increment>
<shrinking-enabled>true</shrinking-enabled>
<shrink-frequency-seconds>60</shrink-frequency-seconds>
</pool-params>
<properties>
<property>
<name>ConnectionURL</name>
<value>
jdbc:oracle:thin:@bcpdb:1531:bay920;create=true;autocommit=false
</value>
</property>
<property>
<name>XADataSourceName</name>
<value>OracleXAPool</value>
</property>
<property>
<name>TestClassPath</name>
<value>HelloFromsetTestClassPathGoodDay</value>
</property>
<property>
<name>unique_ra_id</name>
<value>eisablackbox-xa.oracle.900</value>
</property>
</properties>
</connection-properties>
</connection-instance>
<connection-instance>
<jndi-name>eis/900eisaBlackBoxXATxConnectorJNDINAME2
</jndi-name>
<connection-properties>
<pool-params>
<initial-capacity>2</initial-capacity>
<max-capacity>10</max-capacity>
<capacity-increment>1</capacity-increment>
<shrinking-enabled>true</shrinking-enabled>
<shrink-frequency-seconds>60
</shrink-frequency-seconds>
</pool-params>
<properties>
<property>
<name>ConnectionURL</name>
<value>
jdbc:oracle:thin:@bcpdb:1531:bay920;create=true;autocommit=false
</value>
</property>
<property>
<name>XADataSourceName</name>
<value>OracleXAPool</value>
</property>
<property>
<name>TestClassPath</name>
<value>HelloFromsetTestClassPathGoodDay</value>
</property>
<property>
<name>unique_ra_id</name>
<value>eisablackbox-xa.oracle.900</value>
</property>
</properties>
</connection-properties>
</connection-instance>
</connection-definition-group>
<connection-definition-group>
<connection-factory-interface>javax.sql.DataSourceCopy
</connection-factory-interface>
<connection-instance>
<jndi-name>eis/900eisaBlackBoxXATxConnectorJNDINAME3</jndi-name>
<connection-properties>
<pool-params>
<initial-capacity>2</initial-capacity>
<max-capacity>10</max-capacity>
<capacity-increment>1</capacity-increment>
<shrinking-enabled>true</shrinking-enabled>
<shrink-frequency-seconds>60</shrink-frequency-seconds>
</pool-params>
<properties>
<property>
<name>ConnectionURL</name>
<value>jdbc:oracle:thin:@bcpdb:1531:bay920;create=true;autocommit=false</value>
</property>
<property>
<name>XADataSourceName</name>
<value>OracleXAPoolB</value>
</property>
<property>
<name>TestClassPath</name>
<value>HelloFromsetTestClassPathGoodDay</value>
</property>
<property>
<name>unique_ra_id</name>
<value>eisablackbox-xa-two.oracle.900</value>
</property>
</properties>
</connection-properties>
</connection-instance>
</connection-definition-group>
</outbound-resource-adapter>
</weblogic-connector>

インバウンド接続の構成

コネクタ・アーキテクチャ1.6では、インバウンド・メッセージ接続をサポートするリソース・アダプタを構成できます。インバウンド接続を構成する主な手順は以下のとおりです。

1. weblogic-ra.xmlデプロイメント記述子でリソース・アダプタのJNDI名を指定します。「表A-1 Weblogic-connectorのサブ要素」の「jndi-name」を参照してください。

2. ra.xmlデプロイメント記述子で、サポートされるインバウンド・メッセージ・タイプごとに、メッセージ・リスナーとActivationSpecを構成します。ActivationSpecクラスの要件の詳細は、『JSR 322: Java EE Connector Architecture 1.6』の第13章「Message Inflow」を参照してください。

3. パッケージ化されるエンタープライズ・アプリケーションの中に、構成済みのEJBメッセージドリブンBean (MDB)を含めます。weblogic-ejb-jar.xmlデプロイメント記述子のresource-adapter-jndi-name要素で、上記の手順でリソース・アダプタに割り当てた同じJNDI名を指定します。この値を設定すると、MDBとリソース・アダプタが互いに通信できるようになります。

4. リソース・アダプタがインバウンド接続で使用するセキュリティIDを構成します。リソース・アダプタがメッセージを受信するとき、その作業は特定のセキュリティIDで実行される必要があります。「リソース・アダプタのセキュリティIDの構成」を参照してください。

5. 『Oracle WebLogic Serverへのアプリケーションのデプロイ』の説明に従ってリソース・アダプタをデプロイします。

6. MDBをデプロイします。詳細は、『Oracle WebLogic Server Enterprise JavaBeansバージョン2.1の開発』のメッセージドリブンEJBに関する項および『Oracle WebLogic Serverへのアプリケーションのデプロイ』を参照してください。

例6-3では、ra.xmlデプロイメント記述子で、2つのメッセージ・リスナーおよびアクティブ化仕様を持つインバウンド接続を構成する方法を示しています。

例6-3 インバウンド接続の構成の例

<inbound-resourceadapter>
<messageadapter>
<messagelistener>
<messagelistener-type>
weblogic.qa.tests.connector.adapters.flex.InboundMsgListener
</messagelistener-type>
<activationspec>
<activationspec-class>
weblogic.qa.tests.connector.adapters.flex.ActivationSpecImpl
</activationspec-class>
</activationspec>
</messagelistener>
<messagelistener>
<messagelistener-type>
weblogic.qa.tests.connector.adapters.flex.ServiceRequestMsgListener
</messagelistener-type>
<activationspec>
<activationspec-class>
weblogic.qa.tests.connector.adapters.flex.ServiceRequestActivationSpec
</activationspec-class>
</activationspec>
</messagelistener>
</messageadapter>
</inbound-resourceadapter>

接続プール・パラメータの構成

この項では、weblogic-ra.xmlデプロイメント記述子で、WebLogic Serverリソース・アダプタの接続プール・パラメータを構成する方法について説明します。詳細は、付録A「weblogic-ra.xmlスキーマ」を参照してください。

initial-capacity : ManagedConnectionの初期数の設定

ManagedConnectionが表すエンタープライズ情報システム(EIS)の複雑さによっては、ManagedConnectionの作成にコストがかかる可能性があります。WebLogic Serverの起動時に、接続プールに初期数のManagedConnectionを登録し、実行時には作成しないようにすることができます。この設定は、weblogic-ra.xml記述子ファイルのinitial-capacity要素を使用して構成します。この要素のデフォルト値は、1 ManagedConnectionです。

WebLogic Serverの起動時には開始セキュリティ・プリンシパルまたはリクエスト・コンテキスト情報が不明なので、サーバー・インスタンスは初期接続用の特別な資格証明マッピングをルックアップすることにより、セキュリティ・サブジェクトを使用して、初期接続を作成します。「初期接続: アプリケーションのリクエストがない場合、アダプタからのManagedConnectionが必要」を参照してください。

注意:

マッピングが見つからない場合は、WebLogic Serverはサブジェクトとしてnullを使用します。

max-capacity : ManagedConnectionの最大数の設定

作成されるManagedConnectionの数が増えるほど、メモリーやディスク容量などのシステム・リソースが多く消費されます。エンタープライズ情報システム(EIS)によっては、この消費がシステム全般のパフォーマンスに影響します。システム・リソースに対するManagedConnectionの影響を制御するために、weblogic-ra.xmlデプロイメント記述子のmax-capacity要素で、割り当てるManagedConnectionの最大数を指定できます。

接続リクエスト中にManagedConnection (capacity-incrementが2以上の場合は複数のManagedConnection)を新規作成する必要がある場合、WebLogic Serverが最大許容数を超えてManagedConnectionを作成することはありません。この制限を超えてManagedConnectionの割当をリクエストすると、呼出し側にResourceAllocationExceptionが返されます。

capacity-increment : ManagedConnectionの数の制御

コネクタ・アーキテクチャ1.6に従って、アプリケーション・コンポーネントがリソース・アダプタを介してEISとの接続を要求すると、WebLogic Serverはまず、接続プール内の既存で利用可能なManagedConnectionの中に、要求されている接続の種類と一致するものがないか探します。しかし、一致するものが見つからない場合には、新規のManagedConnectionを作成して接続リクエストに応じます。

weblogic-ra.xml記述子ファイルのcapacity-increment要素を使用して、一致するものが見つからない場合に作成される追加のManagedConnectionの数を指定できます。この機能により、時間の経過と共に増加する接続プールのサイズとサイズが増加するたびに低下するサーバーのパフォーマンスを柔軟に制御できます。

shrinking-enabled :システム・リソースの使用量の制御

ManagedConnectionの最大数を設定すると、処理能力を超えた数のManagedConnectionが割り当てられてサーバーが過負荷になることはありませんが、常に必要に応じてシステム・リソースの量が効率的に制御されるわけではありません。WebLogic Serverでは、リソース・アダプタの接続プール内のManagedConnectionの動作状況をモニターするサービスを利用できます。使用量が減少しそのレベルで一定期間とどまっている場合、接続プールのサイズは初期容量まで、またはできる限りそれに近く、継続的な接続リクエストを十分満たせる大きさにまで縮小されます。

このシステム・リソース使用量サービスはデフォルトで有効です。ただし、weblogic-ra.xml記述子ファイルのshrinking-enabled要素をfalseに設定すると、このサービスを無効にできます。

shrink-frequency-seconds: 未使用のManagedConnectionの再利用を試みるまで
待機する時間の設定

weblogic-ra.xml記述子ファイルのshrink-frequency-seconds要素を使用すると、接続プール・マネージャが未使用のManagedConnectionを再利用しようとする間隔(秒単位)を指定できます。この要素のデフォルト値は、900秒です。

highest-num-waiters: 接続を待機するクライアントの数
の制御

接続の最大数に達していて、利用可能な接続がない場合、WebLogic Serverは呼出しがタイムアウトするまで再試行します。highest-num-waiters要素は、同時に接続を待機するクライアントの数を制御します。

highest-num-unavailable :使用できない接続の数の制御

接続が作成されて失敗した場合、その接続は使用不可リストに置かれます。WebLogic Serverは使用不可リストにある失敗した接続を再作成しようとします。highest-num-unavailable要素は、使用不可リストに同時に存在できる使用不可接続の数を制御します。

connection-creation-retry-frequency-seconds :接続の再作成

追加のManagedConnectionの作成中に、失敗した接続を再作成するようにWebLogic Serverを構成するには、connection-creation-retry-frequency-seconds要素を有効にします。デフォルトでは、この機能は無効です。

match-connections-supported :接続のマッチング

接続リクエストにはパラメータ情報が含まれています。デフォルトでは、コネクタ・コンテナはManagedConnectionFactoryのmatchManagedConnections()メソッドを呼び出して、プール内の使用可能な接続をリクエスト内のパラメータと一致させます。一致に成功した接続が返されます。

ManagedConnectionFactoryがmatchManagedConnections()の呼出しをサポートしていない場合もあります。その場合、matchManagedConnections()メソッドの呼出しはjavax.resource.NotSupportedExceptionを返します。この例外が捕捉された場合、コネクタ・コンテナはManagedConnectionFactoryのmatchManagedConnections()メソッドの呼出しを自動的に停止します。

match-connections-supported要素を設定して、リソース・アダプタが接続のマッチングをサポートするかどうかを指定できます。デフォルトでは、この要素はtrueに設定されており、matchManagedConnections()メソッドは少なくとも1回呼び出されます。falseに設定されている場合、このメソッドは呼び出されません。

接続のマッチングがサポートされていない場合は、リソースの最大数にまだ達していなければ、新しいリソースが作成されて返されます。最大数に達しているときは、最も古い使用不可のリソースがリフレッシュされて返されます。

test-frequency-seconds :接続の有効性のテスト

test-frequency-seconds要素を使用すると、プール内の接続の有効性をテストする頻度(秒単位)を指定できます。

test-connections-on-create :作成時の接続のテスト

test-connections-on-create要素を設定して、接続が作成されるときの接続のテストを有効にすることができます。デフォルト値はfalseです。

test-connections-on-release: 接続プールへの解放時の
接続のテスト

test-connections-on-release要素を設定して、接続が接続プールに解放されるときの接続のテストを有効にすることができます。デフォルト値はfalseです。

test-connections-on-reserve :予約時の接続のテスト

test-connections-on-reserve要素を設定して、接続が接続プールから予約されるときの接続のテストを有効にすることができます。デフォルト値はfalseです。

deploy-as-a-whole: アダプタ・デプロイメント全体からの
アウトバウンド接続プール・エラーの分離

deploy-as-a-whole要素を設定して、複数のアウトバウンド接続プールを含むリソース・アダプタのデプロイメントが、いずれかの接続プールにエラーが発生した場合に失敗になるかどうかを決定できます。デフォルト値はtrueです。この設定では、(接続プールのエラーのみならず)なんらかのエラーが発生した場合にリソース・アダプタ・デプロイメント全体が失敗します。

この要素をfalseに設定すると、少なくとも1つのアウトバウンド接続プールが正常であるかぎり、リソース・アダプタ・デプロイメントは成功し、再デプロイすることなく、リソース・アダプタの分離、診断、修復および動的更新が行えます。

接続プロキシ・ラッパー - 1.0リソース・アダプタ

接続プロキシ・ラッパー機能は、Java EEコネクタ・アーキテクチャ1.0に基づいて作成されたリソース・アダプタでのみ有効です。接続がリクエストされると、WebLogic Serverは、接続オブジェクトをラップするプロキシ・オブジェクトを(リソース・アダプタを介して)クライアントに返します。WebLogic Serverはこのプロキシを使用して以下の機能を提供します。

- 接続リーク検出機能

- 接続を使用するグローバル・トランザクションの開始前に接続がリクエストされた場合のXAResourceの遅延登録

発生する可能性のあるClassCastException

接続リクエストで返された接続オブジェクトが(Connectionクラスによって実装されたインタフェースではなく) Connection実装クラスとしてキャストされた場合、ClassCastExceptionが発生することがあります。この例外は、以下のいずれかの原因で発生します。

- リソース・アダプタがキャストを実行した

- 接続リクエストでクライアントがキャストを実行した

WebLogic Serverは、リソース・アダプタが原因のClassCastExceptionを検出しようとします。リソース・アダプタからのキャストが失敗したことが検出された場合は、プロキシ・ラッパー機能が無効にされ、接続リクエスト時のラップされていない接続オブジェクトを戻すことで処理が進められます。サーバーは、プロキシ生成が無効になったことを示す警告メッセージをログに記録します。この状況が発生すると、接続リーク検出機能とXAResourceの遅延登録機能も無効になります。

WebLogic Serverは、コンテナ管理によるセキュリティを使用するクライアントとして動作し、リソース・アダプタのデプロイメント時にテストを実行することで、ClassCastExceptionを検出しようとします。そのためには、セキュリティ資格証明を定義してリソース・アダプタをデプロイする必要があります。

クライアントがキャストを実行し、ClassCastExceptionを受け取った場合は、クライアント・コードを以下の例のように変更します。

クライアントが接続オブジェクトをMyConnectionにキャストするものとします。

1. MyConnectionをリソース・アダプタのConnectionインタフェースを実装するクラスとするのではなく、Connectionを拡張するインタフェースとなるようにMyConnectionを変更します。

2. MyConnectionインタフェースを実装するMyConnectionImplクラスを実装します。

プロキシ生成の有効化および無効化

リソース・アダプタで接続プロキシを使用できるかどうかわかっている場合は、WebLogic Server 8.1のweblogic-ra.xmlにあるuse-connection-proxies要素をtrueまたはfalseに明示的に設定することで、プロキシ・テストを避けることができます。

注意:

WebLogic ServerではJava EEコネクタ・アーキテクチャ1.0のリソース・アダプタが引続きサポートされます。1.0リソース・アダプタの場合は、weblogic-ra.xmlにあるWebLogic Server 8.1デプロイメント記述子を引き続き使用します。この記述子には1.0リソース・アダプタに対応する要素が含まれています。

trueに設定した場合、プロキシ・テストは実行されず、接続プロパティが生成されます。

falseに設定した場合、プロキシ・テストは実行されず、接続プロキシが生成されます。

use-connection-proxiesが指定されていない場合、プロキシ・テストが実行されて、テストに合格するとプロキシが生成されます。(リソース・アダプタからClassCastExceptionがスローされなければ、テストに合格します)。

注意:

テストでは、クライアント・コードによって発生したClassCastExceptionは検出できません。

接続プールのリセット

次の場合には、接続プールをリセットする必要があります。

- 他の実行中の接続プールに影響を与えずに接続プールを異常な状態から回復します。

- 更新操作により有効にならない、動的でない構成変更を行います。たとえば、ManagedConnectionFactoryのプロパティを変更するか、接続のトランザクション・サポートを変更します。

次のいずれかの方法で接続プールをリセットできます。

- リセット: プール内の接続が使用中でない場合、プールが作成されます。新しいプールは、リセットする前に行われた構成の変更をすべて含みます。使用中の接続がある場合、プールはリセットされません。

- 強制リセット: すべての使用接続と未使用接続をすぐに廃棄し、プールが再作成されます。新しいプールは、リセットする前に行われた構成の変更をすべて含みます。

管理コンソールから接続プールをリセットするには、次の手順に従います。

1. 「デプロイメント」表のサマリーから「リソース・アダプタ」を選択します。

2. 「制御」>「アウトバウンド接続プール」を選択します。

3. リセットする接続プールを選択します。

4. リセットまたは、強制リセットをクリックします。

接続のテスト

リソース・アダプタのManagedConnectionFactoryがValidatingインタフェースを実装している場合、アプリケーション・サーバーでは既存の接続の有効性をテストできます。特定のManagedConnectionFactoryで、特定のアウトバウンド接続またはアウトバウンド接続のプール全体をテストすることができます。プール全体のテストでは、プール内の各接続が個々にテストされます。この機能の詳細は、『JSR 322: Java EE Connector Architecture 1.6』の6.5.3.4項「Detecting Invalid Connections」を参照してください。

接続のテストの構成

weblogic-ra.xmlデプロイメント記述子で以下の省略可能な要素を使用すると、プール内の接続のテストを制御できます。

- test-frequency-seconds: コネクタ・コンテナは、プール内のすべての空き接続を定期的にテストします。この要素を使用して、接続がテストされる頻度を指定します。デフォルトは0で、接続がテストされないことを意味します。

- test-connections-on-create: 作成時に接続をテストするかどうかを決定します。デフォルトはfalseです。

- test-connections-on-release: 解放時に接続をテストするかどうかを決定します。デフォルトはfalseです。

- test-connections-on-reserve: 予約時に接続をテストするかどうかを決定します。デフォルトはfalseです。

管理コンソールでの接続のテスト

リソース・アダプタの接続プールをテストするには:

1. 管理コンソールで、「デプロイメント」ページを開いて、「デプロイメント」表でリソース・アダプタを選択します。

2. 「テスト」タブを選択します。
そのリソース・アダプタの接続プールの表と、各プールのテスト・ステータスが表示されています。

3. テストする接続プールを選択して、「テスト」をクリックします。

Oracle WebLogic Server管理コンソール・オンライン・ヘルプのアウトバウンド接続のテストに関する項を参照してください。

7 トランザクション管理

この章では、WebLogic Serverからエンタープライズ情報システムへのアウトバウンド通信に使用されるシステム・レベルのトランザクション管理規約について説明します。

この章の内容は以下のとおりです。

- サポートされているトランザクション・レベル

- トランザクション・レベルの構成

トランザクション管理の詳細は、『JSR 322: Java EE Connector Architecture 1.6』の第7章「Transaction Management」を参照してください。EISからWebLogic Serverへのインバウンド通信におけるトランザクション管理の詳細は、「トランザクション・インフロー」を参照してください。

サポートされているトランザクション・レベル

トランザクションとは、データの一貫性と整合性を維持するために、すべてのデータに関して必ず一斉にコミットするか、またはまったくコミットしないかのどちらかの一連の処理のことです。EISへのトランザクション・アクセスは、ビジネス・アプリケーションにとって重要な要件です。Java EEコネクタ・アーキテクチャ1.6では、トランザクションの使用をサポートしています。

WebLogic Serverでは、WebLogic Serverのトランザクション・マネージャ実装を利用して、XAやローカルのトランザクションに対応するリソース・アダプタ、またはトランザクションなしのリソース・アダプタをサポートしています。ra.xmlファイルのtransaction-support要素でトランザクション・サポートの種類を定義します。リソース・アダプタでサポートできるのは1種類のみです。weblogic-ra.xmlデプロイメント記述子のtransaction-support要素を使用すると、ra.xmlで指定された値をオーバーライドできます。詳細は、「表A-18 default-connection-propertiesのサブ要素」の「トランザクション・レベルの構成」および「transaction-support」を参照してください。

Java EEコネクタ・アーキテクチャ1.6に準拠するリソース・アダプタは、トランザクション・サポートのレベルをオプションで実行時に指定できます。これにはTransactionSupportインタフェースの実装が必要です。詳細は、「トランザクション・サポート・レベルの指定および取得」を参照してください。

XAトランザクションのサポート

XAトランザクションのサポートを使用すると、リソース・アダプタの外部(したがってEISの外部)のトランザクション・マネージャによってトランザクションを管理できるようになります。アプリケーション・コンポーネントがEIS接続リクエストをトランザクションの一部として境界設定する場合、アプリケーション・サーバーはXAリソースをトランザクション・マネージャに登録します。アプリケーション・コンポーネントがその接続を閉じると、アプリケーション・サーバーは、トランザクションが完了した時点でEIS接続をクリーン・アップします。

パフォーマンスを向上するにはXAトランザクション対応のリソース・アダプタのためにLocalTransactionアウトバウンド接続プールを作成することをお薦めします。

ローカル・トランザクションのサポート

ローカル・トランザクションのサポートを使用すると、WebLogic Serverはリソース・アダプタのローカルにあるリソースを管理できます。XAトランザクションとは異なり、通常、ローカル・トランザクションは2フェーズ・コミット・プロトコル(2PC)には関与できません。ローカル・トランザクションのリソース・アダプタが2PCトランザクションに関与できるのは、トランザクションに関わるのがローカル・トランザクション・リソースだけで、WebLogic Serverコネクタ・コンテナがラスト・リソース・コミットによる最適化を利用している場合のみです。その場合、トランザクションの結果はリソース・アダプタのローカル・トランザクションによって制御されます。

通常、ローカル・トランザクションは、そのリソース・アダプタに固有のAPIまたはCCIインタフェース(そのアダプタがサポートしている場合)を使用して開始されます。ローカル・トランザクションのサポートを使用するように構成されたリソース・アダプタ接続を作成し、XAトランザクションのコンテキスト内で使用する場合、WebLogic Serverは、この接続用のローカル・トランザクションを自動的に開始します。XAトランザクションが終了し、コミットの準備が整うと、XAトランザクションの一部のXAリソースに対してprepareがまず呼び出されます。次に、ローカル・トランザクションがコミットされます。

ローカル・トランザクションでコミットが失敗した場合、XAトランザクションとすべてのXAリソースはロールバックされます。コミットが成功した場合、XAトランザクションのすべてのXAリソースはコミットされます。アプリケーション・コンポーネントがその接続を閉じると、WebLogic Serverは、トランザクションが終了した時点で接続をクリーン・アップします。

トランザクション・サポートなし

トランザクションのサポートを使用しないようにリソース・アダプタが構成されている場合でも、そのリソース・アダプタをトランザクションのコンテキストで使用することができます。ただし、その場合、そのリソース・アダプタで使用する接続はトランザクションに関与しないので、トランザクションがないかのように動作します。つまり、これらの接続を使用して実行される操作は、基底のEISに対して直ちに行われるので、トランザクションがロールバックされた場合、これらの接続による変更は元に戻りません。

実行時トランザクション・サポート・レベルの仕様

『JSR 322: Java EE Connector Architecture 1.6』では、リソース・アダプタが実行時に提供するトランザクション・サポートのレベルをオプションで決定および分類できると指定されています。実行時のトランザクション・サポートのレベルに関する情報を公開するには、ManagedConnectionFactoryがTransactionSupportインタフェースを実装する必要があります。『JSR 322: Java EE Connector Architecture 1.6』では、記述子、注釈およびTransactionSupportインタフェースで設定されるトランザクション・サポート・レベルの規則と優先度も定義されます。たとえば、WebLogic ServerはgetTransactionSupportメソッドによって返される値を使用し、リソース・アダプタのデプロイメント記述子や@Connectorメタデータ注釈によって指定される値は無視します。

WebLogic Serverは、ConnectorConnectionPoolRuntimeMBean.RuntimeTransactionSupport MBean属性および管理コンソールで、実行時トランザクション・サポート・レベルの情報を公開しています。

管理コンソールで実行時トランザクション・レベル・サポートを確認するには、次の手順を実行します。

1. 「デプロイメントのサマリー」ページでリソース・アダプタを選択します。

2. 「監視」→「アウトバウンド接続プール」をクリックし、「実行時トランザクションのサポート」列の項目を確認します。

トランザクション・レベルの構成

リソース・アダプタのトランザクション・サポート・レベルは、Java EE標準のリソース・アダプタ・デプロイメント記述子ra.xmlで指定します。トランザクション・サポート・レベルを指定するには:

- トランザクションをサポートしない場合、次のエントリをra.xmlデプロイメント記述子ファイルに追加します。<transaction-support>NoTransaction</transaction-support>

- XAトランザクションの場合、次のエントリをra.xmlデプロイメント記述子ファイルに追加します。<transaction-support>XATransaction</transaction-support>

- ローカル・トランザクションの場合、次のエントリをra.xmlデプロイメント記述子ファイルに追加します。<transaction-support>LocalTransaction</transaction-support>

Java EEコネクタ・アーキテクチャ1.6に準拠するリソース・アダプタは、トランザクション・サポートのレベルをオプションで実行時に指定できます。これにはTransactionSupportインタフェースの実装が必要です。詳細は、「トランザクション・サポート・レベルの指定および取得」を参照してください。

ra.xmlデプロイメント記述子で指定されたトランザクション・サポートの値は、リソース・アダプタのすべての接続ファクトリのデフォルト値になります。weblogic-ra.xmlデプロイメント記述子のtransaction-support要素で値を指定すると、特定の接続ファクトリについてこの値をオーバーライドできます。

transaction-supportの値は次のいずれかです。

- NoTransaction

- LocalTransaction

- XATransaction

ra.xmlデプロイメント記述子でのトランザクション・レベルの指定の詳細は、『JSR 322: Java EE Connector Architecture 1.6』の20.7項「Resource Adapter XML Schema Definition」を参照してください。weblogic-ra.xmlデプロイメント記述子でのトランザクション・レベルの指定の詳細は、付録A「weblogic-ra.xmlスキーマ」を参照してください。

XAトランザクション・リカバリの資格証明マッピングの構成

XAトランザクションをサポートしているプールに対して、サーバーの起動時にプールで保留中のトランザクションが見つかった場合は、WebLogic Serverは、Java EEコネクタ・アーキテクチャ接続プールのトランザクションをリカバリしようとします。保留中のトランザクションが見つかった場合は、WebLogic Serverはリカバリ時に、ManagedConnectionFactory.createManagedConnection(javax.security.auth.Subject subject、ConnectionRequestInfo cxRequestInfo)を使用して、EISへのManagedConnectionを取得します。

EISがサインオンするために明示的な資格証明(ユーザー名とパスワードなど)が必要な場合は、最初期接続に対して、特別な資格証明マッピングを構成して、適切な資格証明でWebLogic Serverを構成する必要があります。「初期接続:アプリケーションのリクエストがない場合、アダプタからのManagedConnectionが必要」を参照してください。WebLogic Serverでは、マッピングが見つからない場合にnullがSubjectとして使用されます。

注意:

EISで明示的な資格証明が必要でない場合、この特別な資格証明マッピングを構成する必要はありません。

8 メッセージ・インフローとトランザクション・インフロー

この章では、WebLogicリソース・アダプタでインバウンド接続を使用してメッセージ・インフローとトランザクション・インフローを扱う方法について説明します。

この章の内容は以下のとおりです。

- メッセージ・インフローとトランザクション・インフローの概要

- メッセージ・インフローの仕組み

- メッセージ・エンドポイント(メッセージドリブンBean)へのメッセージ・インフロー

- トランザクション・インフロー

- 長時間実行するWorkの構成および管理

メッセージ・インフローとトランザクション・インフローの概要

メッセージ・インフローとは、リソース・アダプタを使用した、EISからアプリケーション・サーバーへのインバウンド通信のことです。「トランザクション・インフロー」で説明するように、インバウンド・メッセージは、WebLogic Serverとリソース・アダプタの外部にあるトランザクション・マネージャが制御しているトランザクションの一部である場合もあります。

以下の図は、リソース・アダプタにおけるメッセージング・インフローとトランザクション・インフローの仕組みの概要と、ワーク・マネージャが果たす役割を示したものです。

図8-1 メッセージ・インフローとトランザクション・インフローのアーキテクチャ

「図8-1 メッセージ・インフローとトランザクション・インフローのアーキテクチャ」の説明

アーキテクチャのコンポーネント

図8-1には以下のコンポーネントが含まれています。

- クライアント・アプリケーション。WebLogic Server上で動作するアプリケーションへ接続しますが、EISにも接続する必要があります。

- 外部システム。この場合は、EIS (エンタープライズ情報システム)です。

- アプリケーション・コンポーネント(EJB)。クライアント・アプリケーションがリソース・アダプタを介してアウトバウンド・リクエストをEISにアウトバウンドするために使用します。

- メッセージ・エンドポイント・アプリケーション(メッセージドリブンBeanやその他のJava EEコンポーネント)。リソース・アダプタを介してEISからインバウンド・メッセージをインバウンドするために使用されます。

- WebLogic Serverワーク・マネージャとそれに関連付けられた1つまたは複数のスレッド。リソース・アダプタはWorkインスタンスをワーク・マネージャに送信して、インバウンド・メッセージの処理やその他のアクションを行います。

- 外部のトランザクション・マネージャ。EISからのメッセージのトランザクション・インフローでは、WebLogic Serverトランザクション・マネージャが外部のトランザクション・マネージャに従属します。

- WebLogic Serverコネクタ・コンテナ。この中にリソース・アダプタがデプロイされます。コンテナでは以下のものを管理します。

- EISとの双方向(インバウンドおよびアウトバウンド)通信を提供する、デプロイされたリソース・アダプタ。

- アクティブなWorkインスタンス。

- 複数の管理対象接続(MC1、...、MCn)。リソース・アダプタからEISへの物理的なアウトバウンド接続を表現するオブジェクトです。

- 接続ハンドル(C-handle)。リソース・アダプタの接続ファクトリからアプリケーション・コンポーネントに返されます。アプリケーション・コンポーネントがEISとの通信に使用します。

- 複数のアクティブ化仕様のうちの1つ。ここでは、特定のメッセージ・リスナー・タイプMLT-jに対応するアクティブ化仕様(ActivationSpec)があります。ActivationSpecクラスの要件の詳細は、『JSR 322: Java EE Connector Architecture 1.6』の第13章「Message Inflow」を参照してください。

- コンテナが保持している接続プールの1つ。特定のManagedConnectionFactoryに対応し、管理対象接続を管理するために使用されます(この場合はMCF-2。コネクタ・コンテナには、1つのEISとの接続やさまざまなEISとの接続など、各種の接続に対応する複数の接続プールを含めることができます)。

- MessageEndpointFactory。EJBコンテナが作成し、リソース・アダプタがMessageEndpointインスタンス(MDBプールのMDBインスタンス)のプロキシを作成するために使用します。

- 外部のメッセージ・ソース。EISまたはメッセージ・プロバイダです。

インバウンド通信のシナリオ

この節では、図に示されている基本的なインバウンド通信のシナリオについて説明します。インバウンド・メッセージがEISで発生し、リソース・アダプタに流入して、メッセージドリブンBeanによって処理される仕組みを紹介します。関連情報については、「図2-1」を参照してください。

一般的で簡略化されたインバウンド・シーケンスの手順は次のとおりです。

1. EISはメッセージをリソース・アダプタに送信します。

2. リソース・アダプタはメッセージを検査して、メッセージのタイプを判断します。

3. リソース・アダプタはWorkオブジェクトを作成してワーク・マネージャに送信できます。ワーク・マネージャは以降の作業を別のスレッドで実行し、その間にリソース・アダプタは他の着信メッセージを待機し続けることができます。

4. メッセージ・タイプに基づいて、リソース・アダプタは(直接またはWorkインスタンスの一環として)、メッセージの送信先となる正しいメッセージ・エンドポイントをルックアップします。

5. 必要なメッセージ・エンドポイントの種類に応じたメッセージ・エンドポイント・ファクトリを使用して、リソース・アダプタはメッセージ・エンドポイントを作成します(このエンドポイントは、MDBプールのメッセージドリブンBeanインスタンスへのプロキシです)。

6. リソース・アダプタはエンドポイントのメッセージ・リスナー・メソッドを呼び出して、EISから受信したメッセージに基づくメッセージ・コンテンツをエンドポイントに渡します。

7. メッセージは以下のいずれかの方法でMDBによって処理されます。

1. MDBがメッセージを直接処理して、その結果をリソース・アダプタ経由でEISに戻します。

2. MDBが他のアプリケーション・コンポーネントにメッセージを配信します。

3. クライアントが取り出せるようにMDBがメッセージをキューに入れます。

4. MDBがクライアント・アプリケーションと直接通信します。

メッセージ・インフローの仕組み

EISからアプリケーション・サーバーへのインバウンド通信をサポートするリソース・アダプタは、通常以下のものを備えています。

- EISに接続および通信するための独自の通信チャネルとプロトコル。通信チャネルとプロトコルは、リソース・アダプタがデプロイされているアプリケーション・サーバーからは見えません。付録8「独自の通信チャネルとプロトコル」を参照してください。

- リソース・アダプタが認識する1つまたは複数のメッセージ・タイプ。

- 特定のタイプのメッセージをアプリケーション・サーバー内の別のコンポーネントにディスパッチするためのディスパッチ・メカニズム。

インバウンド・メッセージの処理

リソース・アダプタでは、様々な方法でインバウンド・メッセージを処理できます。たとえば、次のような方法があります。

- メッセージをローカルで、つまり、他のコンポーネントを呼び出さずにResourceAdapter Beanの内部で処理します。

- 別のアプリケーション・コンポーネントにメッセージを渡します。たとえば、EJBをルックアップしてそのEJBのメソッドを呼び出すことができます。

- メッセージ・エンドポイントにメッセージを送信します。通常、メッセージ・エンドポイントはメッセージドリブンBean (MDB)です。詳細は、付録8「メッセージ・エンドポイント(メッセージドリブンBean)へのメッセージ・インフロー」を参照してください。

インバウンド・メッセージは、メッセージを送信しているEISに結果を戻すことができます。レスポンスをすぐに必要とするメッセージのことを同期的と呼びます(送信側システムはレスポンスを待機します)。また、これはリクエスト/レスポンス・メッセージングとも呼ばれます。リソース・アダプタとの同じやり取りの一部としてレスポンスを期待しないメッセージは、非同期的または通知ベースの通信と呼ばれます。リソース・アダプタでは、上記の3つの宛先のすべてについて、同期または非同期の通信をサポートできます。

リソース・アダプタとEISのトランザクションの機能に応じて、インバウンド・メッセージをトランザクション(XA)の一部とすることも、トランザクション非対応にすることもできます。メッセージがXAである場合、トランザクションの制御は、外部トランザクション・マネージャ(トランザクション・インフロー)またはアプリケーション・サーバーのトランザクション・マネージャによって管理されます。付録8「トランザクション・インフロー」を参照してください。

ほとんどの場合、リソース・アダプタ内のインバウンド・メッセージは、Workインスタンスを介して、別のスレッドでディスパッチされます。リソース・アダプタは、行うべき作業をWorkインスタンスにラップし、そのインスタンスをアプリケーション・サーバーのワーク・マネージャに送信して実行と管理を委ねます。リソース・アダプタは、作業のスケジューリング要件に応じて、doWork()、startWork()、またはscheduleWork()メソッドを使用してWorkインスタンスを送信できます。

独自の通信チャネルとプロトコル

リソース・アダプタでは、接続の構成情報を、ResourceAdapter beanのプロパティとして、またはActivationSpecオブジェクトのプロパティとしてなど、様々な手段でデプロイヤに公開できます。または、アウトバウンド・トラフィックと同じ通信チャネルをインバウンドにも使用する方法があります。こうすると、構成情報をアウトバウンド接続プールにも設定できます。

メッセージ・エンドポイント(メッセージドリブンBean)へのメッセージ・インフロー

EJB 2.1より前のメッセージドリブンBean (MDB)はJava Message Service (JMS)のメッセージングのみをサポートしていました。つまり、MDBではonMessage(javax.jms.Message)メッセージ・リスナー・メソッドを含むjavax.jms.MessageListenerインタフェースを実装する必要がありました。MDBはJMSコンポーネントにバインドされ、JMSサブシステムがMDBのインスタンスのonMessage()メソッドを呼び出すことで、メッセージをMDBに配信していました。

EJB 2.1では、インバウンド・リソース・アダプタからのメッセージ配信に対応するため、JMSのみのMDBの制限はなくなりました。リソース・アダプタを介したMDBへのメッセージ配信に関する主な要素は以下のとおりです。

- (リソース・アダプタ/EISの規約により決定される)特定のタイプのインバウンド・メッセージ

- リソース・アダプタが実装するActivationSpecオブジェクト

- メッセージ・タイプとメッセージ・リスナー・インタフェース間のマッピング

- 特定のメッセージ・リスナー・インタフェースを実装するMDB

- MDBとリソース・アダプタのデプロイメント時のバインド

メッセージドリブンBeanの詳細は、『Oracle WebLogic Server Enterprise JavaBeansバージョン2.1の開発』のメッセージドリブンEJBに関する項を参照してください。

MDBとリソース・アダプタのデプロイメント時のバインド

リソース・アダプタは、(スタンドアロンのRARとして)独立してデプロイすることも、エンタープライズ・アプリケーション(EAR)の一部としてデプロイすることもできます。MDBも、(スタンドアロンのJARとして)独立して、またはエンタープライズ・アプリケーション(EAR)の一部としてデプロイできます。どちらの場合でも、リソース・アダプタからメッセージが配信されるMDBを、リソース・アダプタにバインドする必要があります。次の項では、MDBとリソース・アダプタのバインドと、その後のメッセージング処理について説明します。

MDBとリソース・アダプタのバインド

MDBとリソース・アダプタをバインドするには、次を行う必要があります:

1. リソース・アダプタのweblogic-ra.xmlデプロイメント記述子でjndi-name要素を設定します。付録A「weblogic-ra.xmlスキーマ」の「jndi-name」を参照してください。

2. リソース・アダプタの対応するjndi-name要素で設定された値と一致するように、weblogic-ejb-jar.xmlデプロイメント記述子のadapter-jndi-name要素を設定します。

3. リソース・アダプタがMDBより先にデプロイされるとします(リソース・アダプタをデプロイする前にMDBをデプロイすることもできます。その場合、デプロイされたMDBはリソース・アダプタがデプロイされるまでポーリングします)。リソース・アダプタがデプロイされるときに、ResourceAdapter Beanは指定された名前でJNDIにバインドされます。

4. MDBがデプロイされます。MDBコンテナは、リソース・アダプタをそのJNDI名でルックアップする、アプリケーション・サーバー固有のAPIを呼び出し、仕様で規定されているリソース・アダプタのendpointActivation(MessageEndpointFactory, ActivationSpec)メソッドを呼び出します。

5. MDBコンテナはリソース・アダプタに、構成済みのActivationSpec (構成情報を含む)と、メッセージ・エンドポイント・インスタンスを作成するためのファクトリを提供します。

6. リソース・アダプタは、後でメッセージ配信に使用するためにこの情報を保存します。それによって、リソース・アダプタは、MDBが実装しているメッセージ・リスナー・インタフェースを知ることができます。この情報は、MDBに配信されるメッセージの種類を判断するために重要です。

メッセージのディスパッチ

メッセージがEISからリソース・アダプタに届くと、リソース・アダプタはそのディスパッチ先を判断します。イベントのシーケンスは次のようになります。

1. メッセージがEISからリソース・アダプタに届きます。

2. リソース・アダプタはメッセージを調べて、内部の表を検索することでそのタイプを判断します。リソース・アダプタは、メッセージ・タイプが特定のペア(MessageEndpointFactory、ActivationSpec)に対応していることを判断します。

3. リソース・アダプタは、メッセージをMDBにディスパッチすべきかどうかを判断します。

4. (MDBにディスパッチされる)メッセージ・エンドポイントのタイプのMessageEndpointFactoryを使用し、そのファクトリのcreateEndpoint()を呼び出すことで、リソース・アダプタはMDBインスタンスを作成します。

5. リソース・アダプタはMDBインスタンスのメッセージ・リスナー・メソッドを呼び出し、必要な情報(着信メッセージの本文など)をMDBに渡します。

6. メッセージ・リスナーが値を返さない場合、メッセージのディスパッチ・プロセスは完了します。

7. メッセージ・リスナーが値を戻す場合、リソース・アダプタはその値の処理方法を判断します。EISとの規約に応じて、EISとさらに通信する場合、またはしない場合があります。

アクティブ化仕様

リソース・アダプタに、メッセージ・タイプとアクティブ化仕様とのマッピングを構成します。アクティブ化仕様は、javax.resource.spi.ActivationSpecを実装するJavaBeanです。リソース・アダプタでは、サポートするメッセージ・タイプごとにActivationSpecクラスを用意します。「インバウンド接続の構成」で説明するように、メッセージ・タイプとアクティブ化仕様のマッピングはra.xmlデプロイメント記述子で構成します。ActivationSpecsの詳細は、『JSR 322: Java EE Connector Architecture 1.6』の第13章「Message Inflow」を参照してください。

管理対象オブジェクト

『JSR 322: Java EE Connector Architecture 1.6』の13.4.2.3項で説明されているように、リソース・アダプタでは、メッセージング・スタイルやメッセージ・プロバイダに固有の管理対象オブジェクトを表す、オプションのJavaBeanクラスのJavaクラス名とインタフェース型を提供することができます。ra.xmlおよびweblogic-ra.xmlデプロイメント記述子ファイルのadmin-objects要素で、管理対象オブジェクトを構成します。アウトバウンド接続や他のWebLogicリソース・アダプタの構成要素と同じように、次の3つのレベルで管理対象オブジェクトを定義できます。

- グローバル - default-properties要素を使用して、リソース・アダプタのすべての管理対象オブジェクトに適用するパラメータを指定します。「表A-15 admin-object-group」の「default-properties」を参照してください。

- グループ - admin-object-group要素を使用して、ra.xmlデプロイメント記述子で指定された特定の管理対象オブジェクト・グループに属する、すべての管理対象オブジェクトに適用するパラメータを指定します。グループで指定されたプロパティは、グローバル・レベルで指定されたパラメータをオーバーライドします。「admin-object-group」を参照してください。
admin-object-interface要素(admin-object-group要素のサブ要素)は、各admin-object-groupに必須の一意の要素(キー)として機能します。weblogic-ra.xmlのadmin-object-interface要素とra.xmlのadmin-object-interface要素の間には1対1の関係がなければなりません。

- インスタンス - weblogic-ra.xmlデプロイメント記述子のadmin-object-instance要素を使用して、各管理対象オブジェクト・グループの下に管理対象オブジェクト・インスタンスを指定できます。これは、リソース・アダプタに対する個別の管理対象オブジェクトに相当します。admin-object-propertiesのサブ要素を使用して、インスタンス・レベルでプロパティを指定することもできます。インスタンス・レベルで指定されたプロパティは、グループ・レベルやグローバル・レベルで指定されたプロパティをオーバーライドします。「admin-object-instance」を参照してください。

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

この項では、EISおよびリソース・アダプタからWebLogic Serverにトランザクションが流入する仕組みについて説明します。トランザクション・インフロー規約によって、リソース・アダプタは、EISが開始したトランザクション完了呼出しやクラッシュ・リカバリ呼出しを処理することができます。また、インポートされるトランザクションのACIDプロパティも維持されます。トランザクション・インフローの詳細は、『JSR 322: Java EE Connector Architecture 1.6』の第15章「Transaction Inflow」を参照してください。

EISは、リソース・アダプタを介してアプリケーション・サーバーにメッセージを渡すときに、メッセージの配信や作業を実行するためのトランザクション・コンテキストを渡すことができます。インバウンド・トランザクションは、リソース・アダプタおよびアプリケーション・サーバーの外部にあるトランザクション・マネージャによって制御されます。「メッセージ・エンドポイント(メッセージドリブンBean)へのメッセージ・インフロー」を参照してください。

リソース・アダプタは、トランザクション制御において、EISとアプリケーション・サーバー間のブリッジとして機能することもできます。つまり、リソース・アダプタはメッセージを受信し、そのメッセージを、外部トランザクション・マネージャとのトランザクションに参加するためにXAコールバックとして解釈します。

WebLogic Serverは、介在トランザクション・マネージャを通じて、外部トランザクション・マネージャのXAリソースとして機能できます。WebLogic Serverトランザクション・マネージャは、そのようなトランザクションの場合、外部トランザクションIDをWebLogic Server固有のトランザクションIDにマップします。

WebLogic Serverトランザクション・マネージャは、外部トランザクション・マネージャに従属しています。つまり、外部トランザクション・マネージャが、トランザクションが成功するかロールバックされるかを最終的に判断します。『Oracle WebLogic Server JTAアプリケーションの開発』のサード・パーティ・トランザクション・マネージャで管理されるトランザクションへの参加に関する項を参照してください。リソース・アダプタがそのようなトランザクションに参加する機能は、Java EEコネクタ・アーキテクチャ1.6の一部として、Java EE標準APIで公開されています。

リソース・アダプタが外部のトランザクションに参加する仕組みを次の手順で示します。詳細は、『JSR 322: Java EE Connector Architecture 1.6』の15.4項「Transaction Inflow Model,」を参照してください。

1. リソース・アダプタはインバウンド・メッセージを、着信メッセージとともに到着したトランザクション・コンテキストとともに受信します。

2. リソース・アダプタはjavax.transaction.xa.Xidインスタンスを使用してトランザクション・コンテキストを表します。

3. リソース・アダプタは、着信メッセージを処理してメッセージ・エンドポイントに配信するために新しいWorkインスタンスを作成します。また、ExecutionContext (javax.resource.spi.work.ExecutionContext)のインスタンスを作成して、作成済みのXidおよびトランザクション・タイムアウト値を設定します。コネクタ・アーキテクチャのバージョン1.6は標準クラス、TransactionContextを定義します。このクラスは、EISのトランザクション・コンテキストをアプリケーション・サーバーに伝播するため、ExecutionContextのかわりにリソース・アダプタで使用される場合があります。

4. リソース・アダプタはWorkオブジェクトとTransactionContext (またはExecutionContext)をワーク・マネージャに送信して処理を委ねます。ここで、ワーク・マネージャは、トランザクションを登録してWebLogic Serverトランザクション・マネージャでトランザクションを開始するために必要な作業を実行します。
TransactionContextを使用するため、Workクラスでは次の処理が必要です。

1. javax.resource.spi.work.WorkContextProviderインタフェースを実装します。

2. getWorkContexts()メソッドでTransactionContextインスタンスを作成して返します。

注意:

リソース・アダプタがTransactionContextを使用する場合、アダプタではExecutionContextを使用しないでください。

5. 外部トランザクション・マネージャからの以降のXA呼出しは、リソース・アダプタを介して送信されて、WebLogic Serverトランザクション・マネージャに伝達されます。このように、リソース・アダプタは、外部トランザクション・マネージャと、リソース・マネージャとして機能するWebLogic Serverトランザクション・マネージャとの間で、XA呼出しのブリッジの役割を果たします。

ローカルで管理されるトランザクションでのトランザクション・インフロー・モデルの使用

リソース・アダプタが、リソース・アダプタと同じサーバー・インスタンス内で動作するアプリケーション・コンポーネントからリクエストを受け取り、そのリクエストが、リソース・アダプタ・リクエストと同じトランザクションの一部としてMDBに配信される必要がある場合、現在のスレッドのトランザクションからトランザクションIDを取得してTransactionContext (またはExecutionContext)に格納する必要があります。

この場合、WebLogic Serverは介在トランザクション・マネージャは使用しないで、MDBへのメッセージ配信に使用される作業スレッドにトランザクションを渡します。

長時間実行するWorkの構成および管理

「長時間実行するWorkのサポート」に記述されているように、WebLogic ServerではHintsContext.LONGRUNNING_HINTの使用がサポートされています。リソース・アダプタのWorkクラスでtrueに設定されている場合、LONGRUNNING_HINTによってWorkインスタンスが、WebLogic Serverでワーク・スレッドではなく別のデーモン・スレッドでスケジューリングされる、長時間実行するワーク・アイテムとして設定されます。LONGRUNNING_HINTは、WebLogic Serverの拡張注釈@LongRunningと同じ機能を実行します。

WebLogic ServerはConnectorWorkManagerRuntimeMBeanを提供することでコネクタ・アーキテクチャ1.6を拡張し、この中には長時間実行するWorkインスタンスを構成および監視するための属性が含まれます。この属性も、次の項で説明するとおり、WebLogic Server管理コンソールで公開されます。

- 同時に長時間実行するWorkインスタンスの最大数の設定

- 長時間実行するWorkの監視

@LongRunning拡張注釈の詳細は、Oracle WebLogic Server Java APIリファレンスのLongRunningに関する項を参照してください。

同時に長時間実行するWorkインスタンスの最大数の設定

長時間実行するワークはそれぞれ固有のデーモン・スレッドで実行されるため、同時に長時間実行するWorkインスタンスの数は最小限にすることをお薦めします。同時に長時間実行するWorkインスタンスの数が多すぎると、WebLogic Serverのスレッド・リソースを使い果たすおそれがあり、サーバーのパフォーマンスと安定性に悪影響を及ぼします。WebLogic Serverは、将来のリリースで、許可されている同時長期間の作業の最大数に関する制限事項を導入する可能性があります。

WebLogic Server管理コンソールを使用して、同時Workインスタンス・リクエストの最大許容数を次のように設定できます。

1. 「デプロイメントのサマリー」>「制御」ページでリソース・アダプタを選択します。

2. 「構成」>「ワークロード」を選択します。

3. 必要に応じて「同時長時間実行リクエストの最大数」に新しい値を入力し、「保存」をクリックします。
新しい値を保存すると、「デプロイメント・プラン保存アシスタント」が表示され、デプロイメント・プラン・ファイルのパスの選択または入力が求められます。デプロイメント・プランの操作の詳細は、『Oracle WebLogic Serverへのアプリケーションのデプロイ』のWebLogic Serverデプロイメントに関する項を参照してください。

次の点に注意してください。

- 同時Workインスタンス・リクエストの最大許容数は、「長時間実行するWorkの監視」に記述されているように、管理コンソールの「リソース・アダプタ」>「監視」>「ワークロード」ページでも参照できます。

- 管理コンソールを使用するかわりに、weblogic-ra.xmlファイルでmax-concurrent-long-running-requests要素を使用して、同時Workインスタンス・リクエストの最大許容数を設定することもできます。詳細は、「connector-work-manager」を参照してください。

長時間実行するWorkの監視

ConnectorWorkManagerRuntimeMBeanは、リソース・アダプタの固有のワーク・マネージャに関する長時間実行ランタイム情報を次のMBean属性で公開します。

- ConnectorWorkManagerRuntimeMBean.ActiveLongRunningRequests — 現在アクティブな長時間実行Workインスタンス・リクエストの数を返します。

- ConnectorWorkManagerRuntimeMBean.CompletedLongRunningRequests — 完了した長時間実行Workインスタンス・リクエストの数を返します。

- ConnectorWorkManagerRuntimeMBean.MaxConcurrentLongRunningRequests — 同時Workインスタンス・リクエストの最大許容数を返します。

現在アクティブな、または完了した長時間実行Workインスタンス・リクエストの情報を、WebLogic Server管理コンソールを使用して表示する手順:

1. 「デプロイメントのサマリー」>「制御」ページでリソース・アダプタを選択します。

2. 「監視」>「ワークロード」を選択します。
長時間実行Workインスタンス・リクエストに関する次の情報は、「長時間実行ワーク・マネージャ」表から得られます。

列のラベル名

内容

アクティブなリクエスト

現在アクティブな長時間実行Workインスタンス・リクエストの数

完了したリクエスト

完了した長時間実行Workインスタンス・リクエストの数

許可された最大同時リクエスト数

同時Workインスタンス・リクエストの最大許容数

9 セキュリティ

この章では、インバウンド通信とアウトバウンド通信でのWebLogic Serverリソース・アダプタのセキュリティについて説明します。リソース・アダプタが外部システムとの接続を確立できるようにするには、認証および他の必要なセキュリティ情報を構成する必要があります。

この章の内容は以下のとおりです。

- コンテナ管理およびアプリケーション管理によるサインオン

- アウトバウンド接続のための資格証明マッピング

- セキュリティ・インフロー

- セキュリティ・ポリシーの処理

- リソース・アダプタのセキュリティIDの構成

- 接続ファクトリに固有の認証および再認証メカニズムの構成

WebLogicセキュリティの詳細は、『Oracle WebLogic Serverセキュリティの理解』および『Oracle WebLogic Server ロールおよびポリシーによるリソースの保護』を参照してください。

コンテナ管理およびアプリケーション管理によるサインオン

リソース・アダプタはエンタープライズ情報システム(EIS)へのアウトバウンド接続を行うときに、有効なセキュリティ資格証明を使用してサインオンする必要があります。『JSR 322: Java EE Connector Architecture 1.6』に従って、WebLogic Serverでは、アウトバウンド接続に関するコンテナ管理およびアプリケーション管理によるサインオンをサポートしています。実行時にWebLogic Serverは、呼出し側クライアント・コンポーネントのデプロイメント記述子、またはリソース・アダプタ・デプロイメント記述子のres-auth要素で指定された情報に基づいて、選択されたサインオン・メカニズムを判断します。リソース・アダプタのデプロイメント記述子で指定されたサインオン・メカニズムは、呼出し側クライアント・コンポーネントのデプロイメント記述子で指定されたメカニズムに優先します。コンテナ管理によるサインオンを使用する場合でも、クライアント・コンポーネントで明示的に指定されたセキュリティ情報があれば、接続を取得する呼出しの際に提示されます。

WebLogic Server Java EE 1.6コネクタ・アーキテクチャの実装で、クライアント・コンポーネントがリクエストしているサインオン・メカニズムを判断できない場合、コネクタ・コンテナはコンテナ管理によるサインオンを試行します。

アプリケーション管理によるサインオン

アプリケーション管理によるサインオンの場合、クライアント・コンポーネントは、EISに接続するための呼出しを実行するときに、必要なセキュリティ資格証明(通常はユーザー名とパスワード)を提示します。この場合、アプリケーション・サーバーは、接続リクエストでこの情報を渡す以外にセキュリティ関連の処理を行いません。

コンテナ管理によるサインオン

WebLogic ServerとEISはそれぞれ独立したセキュリティ・レルムを保持しています。コンテナ管理によるサインオンの目的は、ユーザーにWebLogic Serverへのサインオンを許可することと、EISに別にサインオンしなくても、リソース・アダプタを介してEISにアクセスするアプリケーションを使用できるようにすることです。Weblogic Serverのコンテナ管理によるサインオンでは、アウトバウンド資格証明マッピングを使用します。資格証明マッピングとは、WebLogicセキュリティ・プリンシパル(認証を受ける個々のユーザーまたはクライアント・アプリケーション)の資格証明(ユーザー名とパスワードのペアまたはセキュリティ・トークン)を、EISへのアクセスに必要な、対応する資格証明にマップしたものです。デプロイ済みのリソース・アダプタに対して、適切なセキュリティ・プリンシパルのアウトバウンド資格証明マッピングを構成できます。関連情報は、「アウトバウンド資格証明マッピング」を参照してください。

アウトバウンド接続のための資格証明マッピング

『JSR 322: Java EE Connector Architecture 1.6』では、javax.security.auth.Subjectに資格証明を格納することが必要です。資格証明はManagedConnectionFactoryオブジェクトのcreateManagedConnection()またはmatchManagedConnection()メソッドに渡されます。アウトバウンド資格証明のマッピング情報はWebLogic Serverの組込みLDAPサーバーに格納されます。アウトバウンド資格証明マッピングはアウトバウンド・リソース・アダプタに固有のものです。

WebLogic Serverユーザーのアウトバウンド資格証明マッピングを、リソース・アダプタを使用して接続するEISのユーザー名に対して作成する場合、次の点に注意してください。

- WebLogic Serverはデフォルト・セキュリティ・レルムのみに定義したWebLogic Serverユーザーのアウトバウンド資格証明マッピングの作成をサポートします。カスタマイズしたデフォルト・セキュリティ・レルムを使用している場合、リソース・アダプタのアウトバウンド資格証明マッピングを構成する前に、それをデフォルトのセキュリティ・レルムとして定義する必要があります。詳細は、『Oracle WebLogic Serverセキュリティの管理』のデフォルト・セキュリティ構成のカスタマイズに関する項およびOracle WebLogic Server管理コンソール・オンライン・ヘルプのデフォルト・セキュリティ・レルムの変更に関する項を参照してください。

- 次のいずれかのデプロイメント記述子ファイルに接続プールの認証メカニズム要素を定義する必要があります。

- リソース・アダプタのすべての接続プールのために機能するra.xmlファイル

- 各接続プール用のweblogic-ra.xmlファイル

有効なauthentication-mechanism要素が定義されていない場合、「認証メカニズム」項の説明どおりにアウトバウンド資格証明マッピングは有効になりません。ra.xmlファイル・スニペットの例を次に示します。

<authentication-mechanism>
<authentication-mechanism-type>BasicPassword</authentication-mechanism-type>
<credential-interface>javax.resource.spi.security.PasswordCredential</credential-interface>
</authentication-mechanism>

認証メカニズム

WebLogic Serverユーザーは、保護されているWebLogic Serverリソースへのアクセスをリクエストする場合、必ず認証を受けなければなりません。このため、各ユーザーは資格証明(ユーザー名/パスワードの組み合わせまたはデジタル証明書)をWebLogic Serverに提示する必要があります。

パスワード認証は、WebLogic Serverがデフォルトでサポートしている唯一の認証メカニズムです。パスワード認証は、ユーザーIDとパスワードからなります。構成済みのマッピングに基づいて、ユーザーがリソース・アダプタへの接続をリクエストすると、そのユーザーの適切な資格証明がリソース・アダプタに提供されます。

SSL (またはHTTPS)プロトコルを使用すると、パスワード認証にさらに高度なレベルのセキュリティを提供できます。SSLプロトコルは、クライアントとWebLogic Serverとの間で転送されるデータを暗号化するので、ユーザーIDとパスワードはクリア・テキストでは転送されません。SSLを使用すると、WebLogic Serverは、ユーザーのIDとパスワードの機密性を保持しながらユーザーを認証することができます。詳細は、『Oracle WebLogic Serverセキュリティの管理』のSSLの構成に関する項を参照してください。

アウトバウンド資格証明マッピング

アウトバウンド資格証明マッピングはアウトバウンド・リソース・アダプタに固有のものです。アウトバウンド資格証明マッピングを構成するには、WebLogic Server管理コンソールを使用します。資格証明マッピングを構成する前に、リソース・アダプタを正常にデプロイしておく必要があります。

注意:

リソース・アダプタを最初にデプロイしたとき、アウトバウンド資格証明マッピングは構成されていません。アウトバウンド資格証明マッピングが構成されるまで、初期接続は失敗します。

このため、リソース・アダプタが資格証明を要求し、デプロイメント時に接続を作成するよう構成されている(つまりweblogic-ra.xml内のinitial-capacity要素が0より大きな値に設定されている)場合、初期接続が失敗することがあります。初期接続の失敗を回避するには、このリソース・アダプタの初期インストールおよびデプロイメント時には、接続プールのinitial-capacity要素を0に設定することをお薦めします。リソース・アダプタが初回にデプロイされるときに、initial-capacity要素の値が変更できます。詳細は、「initial-capacity : ManagedConnectionの初期数の設定」を参照してください。

アウトバウンド資格証明マッピングは、個々のアウトバウンド接続プールに対して、またはリソース・アダプタのすべての接続プールに対して構成できます。リソース・アダプタが接続リクエストを受信すると、WebLogic Serverは、特定の接続プールに対して構成されているアウトバウンド資格証明マッピングを検索してから、リソース・アダプタに対してグローバルに構成されているマッピングをチェックします。

次の項に記載されている状況を確認します。

- 非初期接続:アプリケーションのリクエストに応じて、アダプタからのManagedConnectionが必要

- 初期接続:アプリケーションのリクエストがない場合、アダプタからのManagedConnectionが必要

- 特殊なユーザー

非初期接続: アプリケーションのリクエストに応じて、アダプタからの
ManagedConnectionが必要

WebLogic Serverは、アプリケーションのリクエストに応じて、アダプタからのManagedConnectionが必要です。たとえば、アプリケーションはプールからの接続を必要となりますが、ManagedConnectionがプールにない場合、WebLogic Serverは、アダプタに新しいManagedConnectionを作成するようにリクエストする必要があります。

注意:

コンテナ管理によるサインオンにのみ適用されます。

サーバーは以下の順序でアウトバウンド・マッピングを検索します。

1. 接続ファクトリ・レベルの特定のマッピング(または、未認証の場合、匿名マッピング)。

2. グローバル・レベルの特定のマッピング(または、未認証の場合、匿名マッピング)。

3. 接続ファクトリ・レベルのデフォルトのマッピング。

4. グローバル・レベルのデフォルトのマッピング。

たとえば、例9-1に、次のような2つの接続プールとアウトバウンド資格証明マッピングがあるとします。

例9-1 アウトバウンド資格証明マッピングの例

poolA
system user name: admin
system password: admin_password
default user name: guest1
default password: guest1_password

poolB
wlsjoe user name: harry
wlsjoe password: harry_password

global
system user name: sysman
system password: sysman_password
wlsjoe user name: scott
wlsjoe password: scott_password
default user name: viewer
default password: viewer_password
anonymous user name: foo
anonymous password: foo_password

例9-1の例の場合に、あるアプリケーションがsystemとして認証を受け、poolAに対して接続リクエストをします。poolAではsystemに対する特定のアウトバウンド資格証明マッピングが定義されているので、リソース・アダプタはこのマッピング(admin/admin_password)を使用します。

アプリケーションがsystemとして、同じリクエストをpoolBに対して行うと、systemに対する特定のアウトバウンド資格証明マッピングがありません。そのため、サーバーはglobalレベルで資格証明マッピングを検索して、マッピング(sysman/sysman_password)を見つけます。

別のアプリケーションがwlsjoeとして認証を受け、poolAに対してリクエストを行った場合、poolAにはwlsjoeに対して定義されたマッピングがないことがわかります。その後、グローバル・レベルで検索して、wlsjoeに対するマッピング(scott/scott_password)を見つけます。poolBに対してリクエストを行った場合、このアプリケーションはpoolBに対して定義されたマッピング(harry/happy_password)を見つけます。

アプリケーションがuser1として認証を受け、poolAに対してリクエストを行った場合、poolAにはuser1に対して定義されたマッピングがないことがわかります。次のシーケンスが発生します。

1. アプリケーションはグローバル・レベルで検索します。グローバル・レベルでもuser1に対するマッピングはありません。

2. アプリケーションはpoolAアウトバウンド・マッピングでデフォルト・マッピングがないか検索し、デフォルト・マッピングを見つけます。

アプリケーションはWebLogic Serverに認証されていなくてもpoolAに対してリクエストを行った場合、poolAには匿名ユーザーに対して定義されたアウトバウンド・マッピングがないことがわかります。グローバル・レベルで検索して、匿名ユーザー(foo/foo_password)に対するマッピングを見つけます。

初期接続: アプリケーションのリクエストがない場合、アダプタからの
ManagedConnectionが必要

WebLogic Serverは、アプリケーションのリクエストがない場合にアダプタからのManagedConnectionが必要です。これは、WebLogic Serverがデプロイメント時に初期接続を作成する(つまり、weblogic-ra.xml内のinitial-capacity要素が0より大きい値に設定されている)場合か、WebLogicが特にXAリカバリのためにManagedConnectionを取得する必要がある場合です。

注意:

コンテナ管理によるサインオンおよびアプリケーション管理によるサインオンに適用されます。

WebLogic Serverは以下の順序でアウトバウンド・マッピングを検索します。

1. 接続ファクトリ・レベルの初期マッピング。

2. グローバル・レベルの初期マッピング。

3. 接続ファクトリ・レベルのデフォルトのマッピング。

4. グローバル・レベルのデフォルトのマッピング。

初期マッピングとデフォルト・マッピングのどちらも定義していない場合、WebLogic Serverは、ManagedConnectionを作成するためにアダプタを呼び出す時に、Subjectとしてnullを使用します。

たとえば、次のような2つの接続プールとアウトバウンド資格証明マッピングがあるとします。

例9-2 資格証明マッピングの例

poolA
initial user name: admin
initial password: admin_password

poolB
default user name: harry
default password: harry_password

global
initial user name: sysman
initial password: sysman_password

例9-2で示したように、WebLogic Serverは、poolAのXAリカバリを実行し、poolAに対して接続リクエストをします。poolAではsystemに対する初期のアウトバウンド資格証明マッピングが定義されているので、リソース・アダプタはこのマッピング(admin/admin_password)を使用します。

WebLogic ServerはpoolBに対しても同じリクエストを行うと、poolBに対応する初期のアウトバウンド資格証明マッピングはありません。WebLogic Serverはグローバル・レベルで初期の資格証明マッピングを検索して、マッピング(sysman/sysman_password)を見つけます。

特殊なユーザー

リソース・アダプタで使用できる3つの特殊なユーザーが提供されます。

- 初期ユーザー(初期接続を作成するユーザー) - このユーザーに対してアウトバウンド資格証明マッピングを定義すると、指定した資格証明は以下の状態で作成された初期接続のために使用されます。

- このリソース・アダプタ用の接続プールの起動

- 接続プール用のXAトランザクションのリカバリ

プールのInitialCapacityパラメータは、初期接続の数を指定します。このユーザーに対して、マッピングを定義しない場合は、デフォルトのマッピング(提供している場合)が使用されます。それ以外の場合、初期接続に対して資格証明は提供されません。

- 匿名ユーザー(認証されていないWebLogic Serverユーザー) — このユーザーに対してマッピングを定義すると、リソース・アダプタ上の接続リクエストのためにユーザーが認証していない場合、特別な資格証明が使用されます。

- デフォルトのユーザー - このユーザーに対してマッピングを定義すると、以下の場合に、指定した資格証明が使用されます。

- その他のマッピングは現在のユーザーに対して適用されません。

- 認証済みユーザーがない場合、匿名のマッピングは提供されていません。

コンソールを使用したアウトバウンド資格証明マッピングの作成

WebLogic Server管理コンソールを使用してアウトバウンド資格証明マップを作成できます。WebLogic資格証明マッピング・プロバイダを使用している場合、アウトバウンド資格証明のマッピングは組込みLDAPサーバーに格納されます。アウトバウンド資格証明マッピングの作成方法の詳細は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプのアウトバウンド資格証明マッピングの作成に関する項を参照してください。

セキュリティ・インフロー

『JSR 322: Java EE Connector Architecture 1.6』では、EIS/リソース・アダプタとアプリケーション・サーバー間の標準の汎用セキュリティ・コンテキストが定義されます。これは『JSR 196: Java Authentication Service Provider Interface for Containers』の仕様を活用しています。セキュリティ・コンテキストを使用して、リソース・アダプタがセキュリティ情報を確立します。この情報は、実行するWorkインスタンスを発行するときや、WebLogic Serverでホストされるメッセージ・エンドポイントにメッセージを配信するときに使用されます。

『JSR 322: Java EE Connector Architecture 1.6』:

- リソース・アダプタとアプリケーション・サーバー間の規約として、抽象クラスSecurityContextを定義します。

- フローされたIDがアプリケーション・サーバーのセキュリティ・ドメインに含まれるかどうかに応じて、IDを処理する方法に関して2つのシナリオを定義します。

- ケース1 (『JSR 322: Java EE Connector Architecture 1.6』の16.4.3項「Case 1: Identity in the Container Security Domain」を参照)

- ケース2 (16.4.4項「Case 2: Identity Translated Between Security Domains」)

- 『JSR 196: Java Authentication Service Provider Interface for Containers』で定義されたCallbackHandlerを使用します。

- 『JSR 196: CallerPrincipalCallback, GroupPrincipalCallback, and PasswordValidationCallback』のコールバックを使用します。

注意:

WebLogic Serverコネクタ・コンテナが、リソース・アダプタで提供されるSecurityContext実装のsetupSecurityContextメソッドを呼び出すとき、アダプタに渡されるserviceSubjectは常にnullです。

インバウンド・プリンシパル・マッピング

WebLogicコネクタ・コンテナにデプロイされるリソース・アダプタは、ID (呼出し側プリンシパル、グループ・プリンシパルまたは両方)をコンテナにフローできます。IDは、WebLogicドメイン(ケース1のシナリオ)またはEISセキュリティ・ドメイン(ケース2のシナリオ)で定義されます。

IDがEISセキュリティ・ドメインで定義される場合、WebLogicコンテナ・ドメインは、フローされたプリンシパルをWebLogicドメインに定義されたプリンシパルにマップできることが必要です。このシナリオをサポートするため、WebLogic Serverでは、EISプリンシパルと対応するWebLogicドメインの間のインバウンド・プリンシパル・マッピングを作成することができます。

以下のマッピングを作成できます。

- EISユーザー名から特定のWebLogicユーザーまたはWebLogicユーザーanonymousへのデフォルト・マッピング

- 特定のEISユーザー名から特定のWebLogicユーザーまたはWebLogicユーザーanonymousへ

- EISグループ名からWebLogicグループ名へのデフォルト・マッピング

- 特定のEISグループ名からWebLogicグループ名へ

インバウンド・プリンシパル・マッピング構成に定義するプリンシパル名は、空白以外の文字を少なくとも1つ含む必要があります。空白文字のみの文字列は有効なプリンシパル名になりません(WebLogic Server管理コンソールで指定できません)。

インバウンド・プリンシパル・マッピングに関する以下の動作に注意してください。

- 『JSR 322: Java EE Connector Architecture 1.6』によればリソース・アダプタはユーザーおよびグループのあらゆる組合せをコンテナに渡すことができますが、コネクタ・アーキテクチャ1.6ではセキュリティ制約をコンテナに適用することもできます。WebLogic Serverの場合、ユーザーおよびグループのすべての組合せが有効なわけではありません。マッピングで指定されたWebLogicプリンシパルはWebLogicセキュリティ・レルムで現在定義されている必要があり、ユーザーはマッピングで指定されたグループの有効なメンバーとしてWebLogicセキュリティ・レルムで定義されている必要があります。これはWebLogic Serverによって課される要件です。
たとえば、マッピングが特定のユーザーおよびグループの組合せを指定する場合に、そのユーザーまたはグループのいずれかがWebLogic Serverセキュリティ・レルムで定義されていないと、マッピングは無効になります。また、ユーザーおよびグループの両方がセキュリティ・レルムで定義されていても、そのユーザーがマッピングで指定された特定のグループのメンバーではない場合も、マッピングは無効です。WebLogic Serverでマッピングが有効ではないと判断されると、例外がスローされます。

また、インバウンド・プリンシパル・マッピングが構成される際に、WebLogic Serverによるユーザーまたはグループの検証は行われないことに注意してください。セキュリティ・レルムは、リソース・アダプタがデプロイされた後で変更できるため、インバウンド・プリンシパル・マッピングに指定されるWebLogicプリンシパルが検証されるのは実行時のみです。

- フローされたIDは、管理者ロール(Admin、AdminChannelUser、Deployer、OperatorまたはMonitorなど)にマッピングされたプリンシパル(ユーザーまたはグループ)として実行できません。

- デフォルトのインバウンド・マッピングがEISユーザー・プリンシパルに構成されず、そのEISユーザーに固有のマッピングも構成されない場合、そのユーザーは未認証ユーザーにマッピングされます。

- デフォルトのインバウンド・マッピングがEISグループ・プリンシパルに構成されず、そのEISグループに固有のマッピングも構成されない場合、そのグループ・プリンシパルは無視されます。

- インバウンド・プリンシパル・マッピングは、リソース・アダプタがデプロイされた後で構成できます。

WebLogic Server管理コンソールを使用してインバウンド・プリンシパル・マッピングを作成する方法の詳細は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプのインバウンド・プリンシパル・マッピングの作成に関する項を参照してください。

セキュリティ・インフロー・コールバック要件

リソース・アダプタがフローしたIDがCallerPrincipalCallback、GroupPrincipalCallbackおよびPasswordValidationCallbackを介してアプリケーション・サーバーで使用される場合、『JSR 322: Java EE Connector Architecture 1.6』ではコールバックの組合せの制限は指定されていません。ただし、WebLogic Serverコネクタ・アーキテクチャ1.6ではすべての組合せが有効なわけではありません。WebLogicコネクタ・コンテナは、この項で説明する要件に基づいてこれらのコールバックを検証します。コールバックをWebLogicコネクタ・コンテナに渡すときは、これらの要件を満たすようにリソース・アダプタを設計する必要があります。そのようにしないとコールバックは拒否されます。

WebLogic Serverでは、コネクタ・コンテナに渡すコールバックに関して次の要件があります。

- リソース・アダプタがPasswordValidationCallbackを扱うとき、アダプタはCallerPrincipalCallbackも扱う必要があります。WebLogicセキュリティ・サービスでは、CallerPrincipalCallbackによって確立された呼出し側プリンシパルが、PasswordValidationCallBackによって認証されたユーザー名と一致する必要があります。

- リソース・アダプタがGroupPrincipalCallbackを扱うとき、アダプタはCallerPrincipalCallbackも扱う必要があります。

- ケース2 (『JSR 322: Java EE Connector Architecture 1.6』の16.4.4項「Case 2: Identity Translated Between Security Domains」を参照)ではリソース・アダプタはPasswordValidationCallbackを扱ってはいけません。PasswordValidationCallbackのユーザー名とパスワードはEISセキュリティ・ドメインに含まれるため、アプリケーション・サーバー(すなわちWebLogic Server)がそれらを認証できません。

コネクタ・アーキテクチャ1.5および1.0に対する下位互換性

WebLogic Serverでは、リソース・アダプタは構成されたプリンシパルを使用してWork.run()メソッドを実行できます。このプリンシパルは、WebLogic Server管理コンソール(Oracle WebLogic Server管理コンソール・オンライン・ヘルプのセキュリティ・プリンシパルの構成に関する項を参照)か、run-work-as-principal-nameおよびdefault-principal-nameを使用してweblogic-ra.xmlファイル内で構成できます。

この後、Work.run()メソッドが実行するときには、このプリンシパル(構成されている場合)またはデフォルトのanonymous (このプリンシパルが構成されていない場合)を使用します。

このメカニズムでアダプタ・レベルの基本のセキュリティ構成が提供され、そのアダプタによって発行されるすべてのWorkインスタンスに適用されます。ただし、様々なWorkインスタンスで他のセキュリティ・プリンシパルを選択して使用することはできません。

コネクタ・アーキテクチャ1.6のセキュリティ・コンテキスト機能は柔軟性が向上しており、各Workインスタンスが独自のSecurityContextを提供したり、各Workインスタンスが様々なセキュリティ・プリンシパルで実行したりできます。

WebLogic Serverコネクタ・コンテナには1.0および1.5のアダプタとの下位互換性があるため、リソース・アダプタがWorkインスタンスを発行するときは次の動作に注意してください。

- WorkインスタンスがSecurityContextなしで発行されると、Workインスタンスはweblogic-ra.xmlファイルのrun-work-as-principal-name要素とdefault-principal-name要素に定義されたプリンシパルを使用します。

- WorkインスタンスがSecurityContextを使用して発行されると、Workインスタンスは、『JSR 322: Java EE Connector Architecture 1.6』のSecurityContextクラスの記述に従って定義されたセキュリティ・プリンシパルで実行します。run-work-as-principal-name要素とdefault-principal-name要素に定義されるプリンシパルは存在していても無視されます。

セキュリティ・ポリシーの処理

セキュリティ・ポリシーは、権限のないアクセスからWebLogicリソースを保護するための、WebLogicリソースと1つまたは複数のユーザー、グループ、セキュリティ・ロールとの関連付けです。『JSR 322: Java EE Connector Architecture 1.6』では、アプリケーション・サーバーで実行されるリソース・アダプタのデフォルト・セキュリティ・ポリシーを定義しています。リソース・アダプタが、デフォルトをオーバーライドする独自のセキュリティ・ポリシーを提供する方法も定義されています。WebLogic Serverに同梱されているweblogic.policyファイルでは、Java EEコネクタ・アーキテクチャ仕様に従ってデフォルト・セキュリティ・ポリシーを規定しています。

リソース・アダプタで固有のセキュリティ・ポリシーを定義していない場合、WebLogic Serverは、weblogic.policyファイルで指定されたデフォルト・セキュリティ・ポリシーを使用して、リソース・アダプタの実行時環境を確立します。weblogic.policyファイルはJava EEコネクタ・アーキテクチャ仕様で規定されたデフォルトに準拠しています。リソース・アダプタで固有のセキュリティ・ポリシーが定義されている場合、Weblogic Serverは、リソース・アダプタのデフォルト・セキュリティ・ポリシーとリソース・アダプタに定義された固有のポリシーを併用して、リソース・アダプタの実行時環境を確立します。リソース・アダプタの固有のセキュリティ・ポリシーを定義するには、ra.xmlデプロイメント記述子ファイルのsecurity-permission-spec要素を使用します。

セキュリティ・ポリシーの処理の要件は、『JSR 322: Java EE Connector Architecture 1.6』の第21章「Runtime Environment」の項「Security Permissions」を参照してください。セキュリティ・ポリシーとWebLogicセキュリティ・フレームワークの詳細は、『Oracle WebLogic Serverロールおよびポリシーによるリソースの保護』のセキュリティ・ポリシーに関する項を参照してください。

リソース・アダプタのセキュリティIDの構成

この項では、weblogic-ra.xmlデプロイメント記述子でWebLogic Serverリソース・アダプタの様々なセキュリティIDを構成する方法について説明します。セキュリティIDによって、リソース・アダプタの特定の機能を実行できるセキュリティ・プリンシパルが決まります。WebLogicリソース・アダプタでは、1つのセキュリティIDですべての機能を実行することも、機能の個々のクラスごとに別々のIDを使用することもできます。次の4種類のセキュリティIDをweblogic-ra.xmlデプロイメント記述子に定義できます。

- デフォルト・プリンシパル - リソース・アダプタのすべてのタスクを実行できるセキュリティ・プリンシパル。

- run-asプリンシパル - 接続リクエスト時にコネクタ・コンテナからリソース・アダプタ・コードへの呼出しで使用されるセキュリティ・プリンシパル。

- run-work-asプリンシパル - リソース・アダプタによって起動されたWorkインスタンスで使用されるセキュリティ・プリンシパル。

- manage-asプリンシパル - 起動、停止、テスト、トランザクション管理などのリソース・アダプタの管理タスクに使用されるセキュリティ・プリンシパル。

例9-3は、weblogic-ra.xmlデプロイメント記述子の抜粋です。様々なリソース・アダプタのタスクを実行するためにこれらの4つのセキュリティIDをすべて構成する方法を示しています。

例9-3 リソース・アダプタのすべてのセキュリティIDの構成

<weblogic-connector xmlns="http://xmlns.oracle.com/weblogic/weblogic-connector">
<jndi-name>900blackbox-notx</jndi-name>
<security>
<default-principal-name>
<principal-name>system</principal-name>
</default-principal-name>
<run-as-principal-name>
<principal-name>raruser</principal-name>
</run-as-principal-name>
<run-work-as-principal-name>
<principal-name>workuser</principal-name>
</run-work-as-principal-name>
<manage-as-principal-name>
<principal-name>raruser</principal-name>
</manage-as-principal-name>
</security>
</weblogic-connector>

例9-4は、default-principal-name要素を使用して、リソース・アダプタのすべてのタスクを実行する1つのデフォルト・プリンシパルのセキュリティIDを構成する方法を示しています。

例9-4 リソース・アダプタの1つのデフォルト・プリンシパルIDの構成

<weblogic-connector xmlns="http://xmlns.oracle.com/weblogic/weblogic-connector">
<jndi-name>900blackbox-notx</jndi-name>
<security>
<default-principal-name>
<principal-name>system</principal-name>
</default-principal-name>
</security>
</weblogic-connector>

セキュリティIDのプロパティの設定の詳細は、「security」を参照してください。

default-principal-name :デフォルトID

default-principal-name要素を使用して、リソース・アダプタのすべての目的に使用できる1つのセキュリティIDを定義できます。run-as-principal-name、manage-as-principal-name、およびrun-work-as-principal-nameに値が指定されていない場合、default-principal-nameに設定した値がデフォルトになります。

default-principal-nameの値は、systemなどの定義済みのWebLogic Serverユーザー名を設定することも、匿名のIDを使用するように設定することもできます(匿名IDの場合は、セキュリティIDがないのと同じことになります)。

たとえば、次の例9-6で示すように、デフォルトのsystem IDを使用して、WebLogic Serverからリソース・アダプタへのすべての呼出しを行い、リソース・アダプタのすべての管理タスクを行う、1つのセキュリティIDを作成することができます。

例9-5 定義済みのWebLogic Server名の使用

<security>
<default-principal-name>
<principal-name>system</principal-name>
</default-principal-name>
</security>

次のように、default-principal-name要素をanonymousに設定できます。

例9-6 匿名IDの設定

<security>
<default-principal-name>
<use-anonymous-identity>true</use-anonymous-identity>
</default-principal-name>
</security>

manage-as-principal-name :管理タスク実行用のID

manage-as-principal-name要素を使用して、起動、停止、テスト、縮小、トランザクション管理などの、リソース・アダプタの様々な管理タスクの実行に使用される管理IDを定義できます。

default-principal-nameと同様に、manage-as-principal-nameの値としてsystemなど定義済みのWebLogic Serverユーザー名を設定することも、匿名のIDを使用するように設定することもできます(匿名IDの場合は、セキュリティIDがないのと同じことになります)。manage-as-principal-name要素の値を設定しない場合、default-principal-nameで設定した値がデフォルトとして使用されます。default-principal-nameに値が設定されていない場合、匿名IDがデフォルトになります。

例9-7は、リソース・アダプタが、WebLogic Serverで定義されたユーザー名systemを使用して管理呼出しを実行するように構成する方法を示しています。

例9-7 定義済みのWebLogic Server名の使用

<security>
<manage-as-principal-name>
<principal-name>system</principal-name>
</manage-as-principal-name>
</security>

例9-8は、リソース・アダプタが匿名のIDを使用して管理呼出しを実行するように構成する方法を示しています。

例9-8 匿名IDの設定

<security>
<manage-as-principal-name>
<use-anonymous-identity>true</use-anonymous-identity>
</manage-as-principal-name>
</security>

run-as-principal-name: コネクタ・コンテナからリソース・アダプタへの接続呼出しに
使用されるID

run-as-principal-name要素では、接続リクエスト時にコネクタ・コンテナからリソース・アダプタ・コードへのすべての呼出しで使用されるプリンシパル名を定義できます。このプリンシパル名は、たとえば、ManagedConnectionFactoryなどのリソース・アダプタ・オブジェクトがインスタンス化されるときに使用されます。つまり、WebLogic Serverコネクタ・コンテナがリソース・アダプタに呼出しを行うときに、run-as-principal-name要素で定義されたIDが使用されます。この呼出しには、インバウンドまたはアウトバウンドのリクエストや設定に含まれる呼出しや、インバウンドまたはアウトバウンド・リソース・アダプタの初期化に含まれる呼出し(ResourceAdapter.start()など)があります。

run-as-principal-name要素の値は、次の3通りのいずれかで設定できます。

- 定義済みのWebLogic Server名を設定する

- 匿名のIDを使用する

- 呼出し側コードのセキュリティIDを使用する

run-as-principal-name要素の値が定義されていない場合は、default-principal-name要素の値がデフォルトになります。default-principal-name要素が定義されていない場合は、リクエストする呼出し側のIDがデフォルトになります。

run-work-as-principal-name: リソース・アダプタの管理タスクを
実行するためのID

インバウンド・リソース・アダプタの場合は、Workインスタンスを使用してインバウンド・リクエストを実行することをお薦めします。リソース・アダプタによって起動されるWorkインスタンスのセキュリティIDを設定するには、run-work-as-principal-name要素を使用して値を指定します。ただし、Workインスタンスは、アウトバウンド・リクエストを実行するために、アウトバウンド・リソース・アダプタの一部として作成されることもあります。アダプタでインバウンド・リクエストを処理するためにWorkインスタンスを使用しない場合、インバウンド・リクエストは、セキュリティ・コンテキストを確立せずに(匿名で)実行されます。または、リソース・アダプタがWebLogic Server固有の呼出しを行って、WebLogic Serverユーザーとして認証を受けることもできます。その場合は、WebLogic Serverユーザーのセキュリティ・コンテキストが使用されます。

run-work-as-principal-name要素の値は、次の3通りのいずれかで設定できます。

- 定義済みのWebLogic Server名を設定する

- 匿名のIDを使用する

- 呼出し側コードのセキュリティIDを使用する

run-work-as-principal-name要素の値が定義されていない場合は、default-principal-name要素の値がデフォルトになります。default-principal-name要素が定義されていない場合は、リクエストする呼出し側のIDがデフォルトになります。

リクエストする呼出し側のIDを使用して作業を実行するには、run-work-as-principal-name要素を例9-9に示すように指定します。

例9-9 リクエストする呼出し側のIDの使用

<security>
<run-work-as-principal-name>
<use-caller-identity>true</use-caller-identity>
</run-work-as-principal-name>
</security>

接続ファクトリに固有の認証および再認証メカニズムの
構成

Java EE標準リソース・アダプタのデプロイメント記述子ra.xmlで、リソース・アダプタの認証および再認証メカニズムを指定できます。この設定はすべてのアウトバウンド接続ファクトリに適用されます。

- authentication-mechanism要素では、すべてのアウトバウンド接続ファクトリで使用される認証メカニズムを指定します。

- reauthentication-support要素では、アウトバウンド接続ファクトリが既存のManaged-Connectionインスタンスの再認証をサポートするかどうかを指定します。これは、リソース・アダプタのすべての接続ファクトリのデフォルト値となります。

ra.xmlデプロイメント記述子のauthentication-mechanismとreauthentication-supportの値は、weblogic-ra.xmlデプロイメント記述子で値を指定するとオーバーライドできます。それにより、これらの設定を、すべての接続ファクトリではなく、特定の接続ファクトリに適用することができます。「表A-18 default-connection-propertiesのサブ要素」の「authentication-mechanism」および「reauthentication-support」を参照してください。

10 リソース・アダプタのパッケージ化とデプロイ

この章では、WebLogicリソース・アダプタ(RAR)をパッケージ化して、展開ディレクトリ形式でデプロイ、またはアーカイブ・ファイルとしてデプロイする方法について説明します。

この章の内容は以下のとおりです。

- リソース・アダプタのパッケージ化

- リソース・アダプタのデプロイ

WebLogic Serverへのアプリケーションのデプロイは、『Oracle WebLogic Serverアプリケーションの開発』の分割開発ディレクトリからのデプロイメントとパッケージ化に関する項で詳細に説明されています。

リソース・アダプタのパッケージ化

本番および開発目的では、アセンブル済みのリソース・アダプタ(RAR)をエンタープライズ・アプリケーション(EAR)の一部としてパッケージ化することをお薦めします。

ディレクトリ構造のパッケージ化

リソース・アダプタは、applications/ディレクトリ内のリソース・アダプタ・アーカイブ(RAR)に含まれるWebLogic Serverコンポーネントです。デプロイメント・プロセスは、リソース・アダプタ・プロバイダによって作成されたコンパイル済みリソース・アダプタ・インタフェースと実装クラスを格納するRARまたはデプロイメント・ディレクトリで開始されます。RARとデプロイメント・ディレクトリは、どちらがコンパイル済みクラスを格納している場合でも、Javaパッケージ構造と一致するサブディレクトリに入っている必要があります。

リソース・アダプタでは、展開ディレクトリ形式またはRARのどちらにパッケージ化される場合でも、同じディレクトリ形式を使用します。リソース・アダプタの一般的なディレクトリ構造を例10-1に示します。

例10-1 リソース・アダプタのディレクトリ構造

/META-INF/ra.xml
/META-INF/weblogic-ra.xml
/META-INF/MANIFEST.MF (optional)
/images/ra.jpg
/readme.html
/eis.jar
/utilities.jar
/windows.dll
/unix.so

パッケージ化の考慮事項

リソース・アダプタに関するパッケージ化の要件は以下のとおりです。

- デプロイメント記述子(ra.xmlとweblogic-ra.xml)は、META-INFというディレクトリにある必要があります。

- 省略可能なMANIFEST.MFもMETA-INFサブディレクトリに入っています。マニフェスト・ファイルはJARツールによって自動的に生成され、常にJARファイルの最初のエントリとなります。マニフェスト・ファイルのデフォルト名はMETA-INF/MANIFEST.MFです。マニフェスト・ファイルには、そのアーカイブのメタ情報が格納されます。

- WebLogic Serverにデプロイされたリソース・アダプタは、クラスまたはリソースをプロパティとして参照するMANIFEST.MF内のclass-pathエントリをサポートします。

- リソース・アダプタには、リソース・アダプタが使用するJavaクラスおよびインタフェースを格納する複数のJARを含めることができます。(たとえば、eis.jarやutilities.jar。)プラットフォーム固有のネイティブ・ライブラリについて、リソース・アダプタの依存関係がすべて解決されることを確認してください。

- リソース・アダプタには、EISとの対話用にリソース・アダプタが必要とするネイティブ・ライブラリを含めることができます。(たとえば、windows.dllやunix.so。)

- リソース・アダプタには、リソース・アダプタが直接的に使用しないドキュメントや関連ファイルを含めることができます。(たとえば、readme.htmlや/images/ra.jpg。)

- スタンドアロンのリソース・アダプタRARをデプロイする場合、リソース・アダプタはアプリケーション・サーバー内のすべてのJava EEアプリケーションで使用可能にする必要があります。

- Java EEアプリケーションのEAR内にリソース・アダプタのRARをパッケージ化してデプロイする場合、リソース・アダプタはそのパッケージ化されているJava EEアプリケーションでのみ使用可能にする必要があります。この仕様に準拠した動作は必要に応じてオーバーライドできます。

パッケージ化の制限

スタンドアロンのリソース・アダプタを再ロードするときに、そのリソース・アダプタを使用するクライアントを再ロードしない場合、クライアントは正常に機能しなくなる可能性があります。この制限事項は、リモート可用性のあるインタフェースを許可しないという『JSR 322: Java EE Connector Architecture 1.6』の制限によるものです。

リソース・アダプタ・アーカイブ(RAR)のパッケージ化

1つまたは複数のリソース・アダプタをディレクトリにステージングしたら、.rarファイル拡張子の付いたJavaアーカイブ(JAR)にパッケージ化します。

注意:

リソース・アダプタをアセンブルした後は、エンタープライズ・アプリケーションの一部としてパッケージ化することをお薦めします。これにより、従来の単一ディレクトリ構造に比べていくつかの利点がある分割開発ディレクトリ構造を利用できるようになります。『Oracle WebLogic Serverアプリケーションの開発』の分割開発ディレクトリ環境の作成に関する項を参照してください。

リソース・アダプタをステージングおよびパッケージ化するには、次の手順に従います。

1. 一時ステージング・ディレクトリをハード・ディスクの任意の場所に作成します。

2. リソース・アダプタのJavaクラスをステージング・ディレクトリにコンパイルまたはコピーします。

3. リソース・アダプタのJavaクラスを入れるJARを作成します。このJARをステージング・ディレクトリの最上位に追加します。

4. ステージング・ディレクトリにMETA-INFサブディレクトリを作成します。

5. META-INFサブディレクトリにra.xmlデプロイメント記述子を作成して、そのリソース・アダプタのエントリを追加します。

注意:

ra.xmlの文書型定義の詳細は、http://java.sun.com/xml/ns/javaee/connector_1_6.xsdを参照してください。

6. META-INFサブディレクトリにweblogic-ra.xmlデプロイメント記述子を作成して、そのリソース・アダプタのエントリを追加します。

注意:

weblogic-ra.xmlファイルの内容については、付録A「weblogic-ra.xmlスキーマ」を参照してください。

7. リソース・アダプタ・クラスとデプロイメント記述子をステージング・ディレクトリに配置すると、次のようなJARコマンドを使用してRARを作成できます。

jar cvf jar-file.rar -C staging-dir

このコマンドによって作成されたRARは、WebLogic Serverにデプロイすることも、アプリケーション・アーカイブ(EAR)にパッケージ化することもできます。

-C staging-dirオプションを指定すると、JARコマンドはディレクトリをstaging-dirに変更します。これにより、JARに記録されるディレクトリ・パスがリソース・アダプタのステージング・ディレクトリを基準にした相対パスとなります。

このトピックの詳細は、「リソース・アダプタの作成と構成:主な手順」を参照してください。

リソース・アダプタのデプロイ

リソース・アダプタのデプロイメントは、Webアプリケーション、EJB、およびエンタープライズ・アプリケーションのデプロイメントとほぼ同じです。これらのデプロイメント・ユニットと同様、リソース・アダプタも展開ディレクトリ形式でデプロイしたり、アーカイブ・ファイルとしてデプロイしたりすることができます。

デプロイメント・オプション

次のツールのいずれかを使用して、スタンドアロンのリソース・アダプタ(またはエンタープライズ・アプリケーションの一部としてパッケージ化されたリソース・アダプタ)をデプロイできます。

- WebLogic Server管理コンソール

- weblogic.Deployerツール

- wldeploy Antタスク

- WebLogic Scripting Tool (WLST)

これらのアプリケーションのデプロイメント方法の詳細は、『Oracle WebLogic Serverへのアプリケーションのデプロイ』のweblogic.deployerによるアプリケーションおよびモジュールのデプロイに関する項を参照してください。

デプロイメント・プランを使用してリソース・アダプタ・デプロイメントをデプロイできます。リソース・アダプタの場合、WebLogic Serverデプロイメント・プランは、RARの外部にあるオプションのXMLドキュメントであり、特定のWebLogic Server環境のデプロイメントとしてリソース・アダプタが構成されます。デプロイメント・プランでは、リソース・アダプタのデプロイメント記述子で通常定義するようなデプロイメント・プロパティ値を設定したり、デプロイメント記述子ですでに定義されているプロパティ値をオーバーライドしたりします。デプロイメント・プランの詳細は、『Oracle WebLogic Serverへのアプリケーションのデプロイ』の本番デプロイメントのためのアプリケーションの構成に関する項を参照してください。

自動デプロイメントを使用してリソース・アダプタをデプロイすることもできます。この方法は開発時や初期テスト時に便利です。詳細は、『Oracle WebLogic Serverへのアプリケーションのデプロイ』の開発ドメインでのアプリケーションの自動デプロイに関する項を参照してください。

リソース・アダプタのデプロイメント名

リソース・アダプタ・アーカイブ(RAR)またはデプロイメント・ディレクトリをデプロイする場合は、myResourceAdapterのように、デプロイメント・ユニットの名前を指定する必要があります。この名前を使用すると、後でリソース・アダプタをアンデプロイしたり更新したりする場合に、リソース・アダプタのデプロイメントを簡単に参照できます。

リソース・アダプタをデプロイする場合は、WebLogic Serverが、RARまたはデプロイメント・ディレクトリのパスおよびファイル名と一致するデプロイメント名を暗黙的に割り当てます。この名前を使用すると、サーバーが起動した後にリソース・アダプタをアンデプロイまたは更新できます。

リソース・アダプタのデプロイメント名は、サーバーが再起動されるまで、WebLogic Server内でアクティブなままです。リソース・アダプタをアンデプロイしても、関連付けられたデプロイメント名は削除されません。したがって、後でその名前を使用してリソース・アダプタを再デプロイできます。

本番再デプロイメント

WebLogic Serverの本番再デプロイメント機能を使用すると、同じアプリケーションの古いバージョンと一緒に、WebLogic Serverアプリケーションの新しいバージョンを再デプロイできます。デフォルトでは、WebLogic Serverは直ちに新しいクライアントリクエストを新しいバージョンのアプリケーションにルーティングする一方で、既存のクライアント接続は古いバージョンにルーティングします。古いバージョンのアプリケーションを使用するすべてのクライアントが作業を完了したら、WebLogic Serverは、新しいバージョンだけがアクティブになるように、古いバージョンを廃止します。

Suspendableインタフェースと本番再デプロイメント

一般に、リソース・アダプタbeanはjavax.resource.spi.ResourceAdapterインタフェースを実装します。このインタフェースではstart()およびstop()メソッドを定義しています。このタイプのリソース・アダプタでは本番再デプロイメントを行うことはできません。リソース・アダプタは着信/発信通信で1つまたは複数のEISに接続します。すべての通信は、アプリケーション・サーバーの知識を使用せずに、リソース・アダプタ独自の方法で実行されます。実行時に本番再デプロイメントが試行された場合、アプリケーション・サーバーは、既存のリソース・アダプタから新しいインスタンスへの接続の移行を管理できるように、リソース・アダプタに通知を提供するだけです。ただし、リソース・アダプタはSuspendableインタフェースを実装できます。このインタフェースは、リソース・アダプタが本番再デプロイメントに参加するための機能を提供します。Suspendableインタフェースの実装の詳細は、「リソース・アダプタのアクティビティの中断と再開」を参照してください。

本番再デプロイメントの要件

本番再デプロイメントが機能するためには、リソース・アダプタの古いバージョンと新しいバージョンの両方で、以下の要件をすべて満たしている必要があります。満たされていない場合、再デプロイメントは失敗します。

- リソース・アダプタはコネクタ・アーキテクチャ1.6に対応する必要があります。(1.0リソース・アダプタでは本番再デプロイメントは利用できません。)

- リソース・アダプタは、Suspendableインタフェースを実装する必要があります(例4-3)を参照してください。

- リソース・アダプタはエンタープライズ・アプリケーション(EARファイル)の内部にパッケージ化されている必要があります。スタンドアロンのリソース・アダプタの本番再デプロイメントはサポートされていません。

- WebLogic Serverに呼び出された場合、Suspendable.supportsVersioning()メソッドはtrueを戻す必要があります。

- weblogic-ra.xml記述子のenable-access-outside-app要素をfalseに設定する必要があります。

本番再デプロイメントのプロセス

以下のプロセスでは、リソース・アダプタの古いバージョンがデプロイされて実行中であると仮定しています。また、古いバージョン(「old」)と新しいバージョン(「new」)の両方のリソース・アダプタが、「本番再デプロイメントの要件」で述べた要件をすべて満たしており、『Oracle WebLogic Serverへのアプリケーションのデプロイ』の本番環境でのアプリケーションの再デプロイメントに関する項で示されたアプリケーションの要件も満たしていることとします。

本番再デプロイメント時に、リソース・アダプタに以下のような呼出しが行われます。

1. WebLogic Serverはnew.init(old, null)を呼び出して、新しいリソース・アダプタに古いリソース・アダプタと交代することを通知します。

2. WebLogic Serverはold.startVersioning(new, null)を呼び出して、古いリソース・アダプタに、新しいリソース・アダプタと共に本番再デプロイメント処理を開始することを通知します。

3. WebLogic Serverはnew.start(extendedBootstrapContext)を呼び出します。「拡張されたBootstrapContext」を参照してください。

4. 古いリソース・アダプタは、「終了」すると(つまり、すべてのクライアントおよびインバウンド接続を新しいリソース・アダプタに正常に移行し終えると)、(ExtendedBootstrapContext)bsCtx.complete()を呼び出します。これは、WebLogic Serverに、古いリソース・アダプタをアンデプロイしてもよいことを通知するものです。

5. アンデプロイメントが行われると、WebLogic Serverがold.stop()を呼び出して、本番再デプロイメントは完了します。

new.init()とold.startVersioning()の呼出しによって、新旧のリソース・アダプタは、インバウンドまたはアウトバウンドの通信を古いリソース・アダプタから新しいリソース・アダプタに移行することができます。この処理方法は個々のリソース・アダプタ開発者の裁量に任されています。

複数のアウトバウンド接続プールで構成されたリソース・アダプタの
デプロイ

デフォルトでは、複数のアウトバウンド接続プールで構成されたリソース・アダプタをデプロイする際に、いずれかの接続プールにエラーが発生すると、アダプタのデプロイメントが失敗します。ただし、失敗した接続プールを正常なプールから分離することにより、デプロイメントの成功を可能にするオプションを使用できます。このオプションを使用すると、アダプタ全体を再デプロイすることなく、失敗した接続プールの分離、診断、修復、およびデプロイメントの動的更新を行えます。

アウトバウンド接続プールにエラーが発生した場合でもリソース・アダプタ・デプロイメントが成功するように構成するには、次のいずれかを実行します。

- WebLogic Server管理コンソールを使用して、「全体としてデプロイ」フラグが選択されていないことを確認します。このオプションは、「リソース・アダプタ」→「構成」→「全般」ページから使用できます。詳細は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプのリソース・アダプタのプロパティの構成に関する項を参照してください。

- weblogic-ra.xmlファイルのdeploy-as-a-whole要素をfalseに設定します。

A weblogic-ra.xmlスキーマ

この付録の次の項では、WebLogic Server固有のデプロイメント記述子weblogic-ra.xmlで定義できるデプロイメント記述子要素について説明します。weblogic-ra.xmlのスキーマはhttp://xmlns.oracle.com/weblogic/weblogic-connector/1.4/weblogic-connector.xsdです。リソース・アダプタ・アーカイブ(RAR)にweblogic-ra.xmlデプロイメント記述子が含まれていない場合、WebLogic Serverはデプロイメント記述子要素のデフォルト値を自動的に選択します。

この付録の内容は次のとおりです。

- weblogic-connector

- work-manager

- connector-work-manager

- security

- properties

- admin-objects

- outbound-resource-adapter

weblogic-connector

weblogic-connector要素は、デプロイされるリソース・アダプタ用の、WebLogic固有のデプロイメント記述子のルート要素です。weblogic-connector要素の内部に以下の要素を定義できます。

表A-1 weblogic-connectorのサブ要素

要素

必須/省略可能

説明

native-libdir

ネイティブ・ライブラリがある場合は必須

リソース・アダプタで必要なすべてのネイティブ・ライブラリが存在するディレクトリを指定します。

jndi-name

リソース・アダプタBeanが指定されている場合にのみ必須

リソース・アダプタのJNDI名を指定します。リソース・アダプタBeanはこの名前でJNDIツリーに登録されます。リソース・アダプタBeanが指定されていない場合は必須の要素とはなりません。リソース・アダプタBeanのないリソース・アダプタのJNDI名を指定すると、要素は機能しなくなります。

enable-access-outside-app

省略可能

『JSR 322: Java EE Connector Architecture 1.6』で規定されているように、リソース・アダプタがアプリケーション(つまりEAR)の内部にパッケージ化されている場合、そのアプリケーション内のコンポーネントのみがリソース・アダプタにアクセスできます。この要素を使用すると、この機能をオーバーライドできます。

注意: この要素はスタンドアロンのリソース・アダプタには適用されません。

デフォルト値: false

注意: falseに設定した場合、リソース・アダプタと同じアプリケーション内のクライアントのみが、リソース・アダプタにアクセスできます。

(このリリースでサポートされる)バージョン1.0リソース・アダプタでは、この要素のデフォルト値はtrueに設定されます。

enable-global-access-to-classes

省略可能

trueに指定した場合、リソース・アダプタのクラスにグローバル・アクセスできます。また、すべてのアプリケーションがこれらのクラスにアクセスできるように、アダプタのクラスがWebLogic Serverのシステム・クラスパスclassloaderによって直接ロードされます。

デフォルト値はfalseです。この場合、アダプタのクラスがEARアプリケーションclassloaderの子であるclassloaderによりロードされます。

この値は通常、スタンドアロン・アダプタの場合trueに設定する必要があります。

trueに設定したとき、アダプタのクラスを変更してアダプタを再デプロイする場合、WebLogic Serverを再起動する必要があります。

deploy-as-a-whole

省略可能

trueに設定すると、アウトバウンド接続プールや管理オブジェクトBeanでのエラーなど、なんらかのエラーが発生した場合に、リソース・アダプタのデプロイメントが失敗します。

falseに設定すると、少なくとも1つのアウトバウンド接続プールの作成時または構成時にエラーが発生しても、リソース・アダプタ・デプロイメントは成功します。ただし、状態はHEALTH_CRITICALになります。この設定により、リソース・アダプタを再デプロイすることなく、失敗したアウトバウンド接続プールを分離、診断および修正できます。ra.xmlやweblogic-ra.xmlファイルを解析または検証できないエラー、ResourceAdapter Beanエラーまたは管理オブジェクトBeanエラーなどの、その他のエラーがデプロイメント中に発生した場合は、リソース・アダプタのデプロイメントは失敗します。

デフォルト値: true

work-manager

省略可能

この複合要素では、リソース・アダプタBeanで使用されるワーク・マネージャを作成するための、すべての構成可能な要素を指定します。work-manager要素はweblogic-javaee.xsdスキーマからインポートされます。

ワーク・マネージャは、デッドロックを回避し、同時実行性の制約を受けながら最適なスループットを実現するために、作業スレッドの数を動的に調整します。レスポンス時間の目標値、シェア、優先度などの目標も達成します。

work-managerのサブ要素については、「work-manager」を参照してください。

connector-work-manager

省略可能

この複合要素では、このアダプタ・モジュールそのもののコネクタ・ワーク・マネージャのすべての構成可能な要素を指定します。

この要素を使用する構成は、標準のワーク・マネージャではサポートされません。

connector-work-managerのサブ要素については、「connector-work-manager」を参照してください。

security

省略可能

この複合要素では、リソース・アダプタの処理に関するすべてのセキュリティ・パラメータを指定します。

コネクタ・コンテナが使用するセキュリティのデフォルトについては、「security」を参照してください。

properties

省略可能

この複合要素は、ra.xmlファイルでリソース・アダプタBeanに対して指定されたプロパティをオーバーライドするのに使用します。

propertiesのサブ要素については、「properties」を参照してください。

admin-objects

省略可能

この複合要素では、リソース・アダプタのすべての管理オブジェクトを定義します。outbound-resource-adapter複合要素と同様に、(「outbound-resource-adapter」を参照)、admin-objects複合要素には、構成のスコープを指定する4つの階層的なプロパティ・レベルがあります。

1. グローバル・レベル - このレベルでは、リソース・アダプタのすべての管理オブジェクトに適用するパラメータを指定します。それには、default-properties要素を使用します。「表A-14 admin-objectsのサブ要素」の「default-properties」を参照してください。

2. グループ・レベル - このレベルでは、ra.xmlデプロイメント記述子で指定された特定の管理オブジェクト・グループに属する、すべての管理オブジェクトに適用されるパラメータを指定します。それには、admin-object-group要素を使用します。グループで指定されたプロパティは、グローバル・レベルで指定されたパラメータをオーバーライドします。「admin-object-group」を参照してください。

3. インスタンス・レベル - 各管理オブジェクト・グループの下で、admin-object-instance要素を使用して、管理オブジェクト・インスタンスを指定できます。これらはリソース・アダプタの管理オブジェクト・インスタンスに相当します。インスタンス・レベルでプロパティを指定すると、グループ・レベルやグローバル・レベルで指定された同じプロパティをオーバーライドできます。「admin-object-instance」を参照してください。

admin-objectsのサブ要素については、「admin-objects」を参照してください。

outbound-resource-adapter

省略可能

この複合要素では、リソース・アダプタのアウトバウンド・コンポーネントについて記述します。admin-objects複合要素と同様に、この複合要素には、アウトバウンド接続プールを定義するための構成のスコープを指定する3つの階層的なプロパティ・レベルがあります。

1. グローバル・レベル - このレベルでは、default-connection-properties要素を使用して、リソース・アダプタのすべてのアウトバウンド接続プールに適用するパラメータを指定します。「default-connection-properties」を参照してください。

2. グループ・レベル - このレベルでは、connection-definition-group要素を使用して、ra.xmlデプロイメント記述子で指定された特定の接続ファクトリに属する、すべてのアウトバウンド接続に適用されるパラメータを指定します。ra.xmlの接続ファクトリとweblogic-ra.xmlの接続定義グループの間には、1対1の対応関係があります。グループで指定されたプロパティは、グローバル・レベルで指定されたパラメータをオーバーライドします。「connection-definition-group」を参照してください。

3. インスタンス・レベル - 各接続定義グループの下に、接続インスタンスを指定できます。これは、リソース・アダプタに対する個別の接続プールに相当します。このレベルでパラメータを指定すると、グループ・レベルやグローバル・レベルで指定された同じパラメータをオーバーライドできます。「connection-instance」を参照してください。

outbound-resource-adapterのサブ要素については、「outbound-resource-adapter」を参照してください。

work-manager

work-manager要素は、リソース・アダプタBeanで使用されるワーク・マネージャを作成するときに構成可能な、すべての要素の指定に使用する複合要素です。work-manager要素はweblogic-javaee.xsdスキーマからインポートされます。work-manager要素の中に以下のサブ要素を構成できます。

表A-2 work-managerのサブ要素

要素

必須/省略可能

説明

name

必須

ワーク・マネージャの名前を指定します。

『JSR 322: Java EE Connector Architecture 1.6』では、リソース・アダプタがアプリケーション・サーバーに作業スレッドを発行する方法が指定されています。この作業スレッドはWebLogic Serverワーク・マネージャによって管理されます。ワーク・マネージャは、デッドロックを回避し、同時実行性の制約を受けながら最適なスループットを実現するために、作業スレッドの数を動的に調整します。レスポンス時間の目標値、シェア、優先度などの目標も達成します。

response-time-request-class
fair-share-request-class
context-request-class
request-class-name

省略可能

work-manager要素には、以下の4つの要素のうち1つだけ含めることができます。

response-time-request-class - アプリケーションのレスポンス時間リクエスト・クラスを定義します。レスポンス時間はgoal-ms属性にミリ秒単位で定義します。増分は((目標値 - T) Cr)/R。Tは平均スレッド使用時間、Rは到着率、Crはフェア・シェアよりもレスポンス時間目標値を優先させるための係数。

fair-share-request-class - フェア・シェア・リクエスト・クラスを定義します。フェア・シェアは、デフォルト・シェアに対する属性値の割合で定義されます。したがって、デフォルトは100になります。増分はCf/(P R T)。Pは割合、Rは到着率、Tは平均スレッド使用時間、Cfはフェア・シェアの優先度をレスポンス時間目標値よりも低くするための係数。

context-request-class - コンテキスト・クラスを定義します。コンテキスト情報(現在のユーザーまたはそのロール、Cookie、作業領域などのフィールド)をサービス・クラス名にマッピングした複数のケースを指定して、コンテキストを定義します。

request-class-name - リクエスト・クラス名を定義します。

min-threads-constraint
min-threads-constraint-name

省略可能

以下の2つの要素から選択できます。

min-threads-constraint - 制約対象の作業セットのリクエストに割り当てられるスレッドの数を確保して、デッドロックを回避するために使用します。デフォルトはゼロ。min-threadsの値を1に設定すると、ピアから同期的に呼び出されるレプリケーション更新リクエストなどの場合に便利。

min-threads-constraint-name - min-threads-constraint要素の名前を定義します。

max-threads-constraint
max-threads-constraint-name

省略可能

以下の2つの要素から選択できます。

max-threads-constraint - 制約対象の作業セットからのリクエストを実行する同時スレッドの数を制限します。デフォルトは無制限。たとえば、最大スレッド数が10に定義された制約を3つのエントリ・ポイントで共有するとします。このスケジューリング・ロジックでは、統合された3つのエントリ・ポイントからのリクエストを10個以下のスレッドで実行します。

max-threads-constraint-name - max-threads-constraint要素の名前を定義します。

capacity
capacity-name

省略可能

以下の2つの要素から選択できます。

capacity - 制約を定義して、「制約対象の作業セット」と呼ばれるエントリ・ポイントのセットに適用できます。この容量に達した場合にのみ、サーバーはリクエストの拒否を開始します。デフォルトはゼロ。容量には、制約対象の作業セットからのすべてのリクエスト(キューにあるリクエストと実行中のリクエスト)が含まれます。この制約は、独自にフロー制御を行うJMSのようなサブシステムを主な対象としています。この制約は、グローバル・キューのしきい値とは無関係。

capacity-name - capacity要素の名前を定義します。

connector-work-manager

connector-work-manager要素は、リソース・アダプタ・モジュールに対するコネクタ・ワーク・マネージャのすべての構成可能な要素を指定するために使用される複合要素です。この要素を使用する構成は、標準のWebLogicワーク・マネージャではサポートされません。次のサブ要素をconnector-work-manager要素で構成できます。

表A-3 connector-work-managerのサブ要素

要素

必須/省略可能

説明

max-concurrent-long-running-requests

省略可能

リソース・アダプタ・インスタンスに対して、同時に長時間実行するWorkインスタンス・リクエストの最大許容数を指定します。

長時間実行する各Workインスタンス・リクエストは固有のスレッドで実行されるため、長時間実行Workリクエストの数が多すぎると、サーバーのパフォーマンスと安定性に悪影響を及ぼします。リソース・アダプタで一般的に必要とされるのは、ソケットを定期的にリスニングする、または他のWorkインスタンスをスケジューリングするような、少数の長時間実行Workリクエストです。新しい長時間実行Workリクエスト送信は、現在アクティブな長時間実行Workリクエストの数が指定された制限を超えると、拒否されます。

デフォルト値: 10

security

security複合要素には、コネクタ・コンテナに対して構成可能なデフォルトのセキュリティ情報が含まれます。詳細は、「リソース・アダプタのセキュリティIDの構成」を参照してください。

表A-4 securityのサブ要素

要素

必須/省略可能

説明

default-principal-name

省略可能

リソース・アダプタへの呼出しに使用されるデフォルトのセキュアIDを指定します。

この値を指定しない場合、デフォルトは匿名IDになります。その場合は、セキュリティIDがないのと同じことになります。

この要素のサブ要素については、「default-principal-name」を参照してください。

manage-as-principal-name

省略可能

起動、停止、テスト、縮小、トランザクション管理などの、リソース・アダプタの様々な管理タスクの実行に使用されるセキュアIDを指定します。

指定しない場合、デフォルトはdefault-principal-nameの値になります。default-principal-nameが指定されていない場合、匿名IDがデフォルトになります。

この要素のサブ要素については、「manage-as-principal-name」を参照してください。

run-as-principal-name

省略可能

接続リクエスト時にコネクタ・コンテナからリソース・アダプタ・コードへのすべての呼出しで使用されるセキュアIDを指定します。この要素は現在、アウトバウンド機能にのみ適用されます。

指定しない場合、デフォルトはdefault-principal-nameの値になります。default-principal-nameが指定されていない場合、リクエストする呼出し側のIDが使用されます。

この要素のサブ要素については、「run-as-principal-name」を参照してください。

run-work-as-principal-name

省略可能

リソース・アダプタによって開始されたすべてのWorkインスタンスの実行に使用されるセキュアIDを指定します。

指定しない場合、デフォルトはdefault-principal-nameの値になります。default-principal-nameが指定されていない場合、作業の開始に使用されたIDが使用されます。

この要素のサブ要素については、「run-work-as-principal-name」を参照してください。

security-work-context

省略可能

この複合要素では、WorkContextのすべてのセキュリティ・コンテキスト・パラメータを指定します。

『JSR 322: Java EE Connector Architecture 1.6』に記述されている、Workインスタンスの呼出し側のIDの確立に関連する2つの選択肢は次のとおりです。

- ケース1: リソース・アダプタが、アプリケーション・サーバーのセキュリティ・ポリシー・ドメインにIDをフローします。このケースでは、アプリケーション・サーバーは、リソース・アダプタからフローされた開始元プリンシパルを、Workインスタンスが実行するセキュリティ・コンテキストの呼出し側プリンシパルとして使用するだけです。

- ケース2: リソース・アダプタが、EISセキュリティ・ドメインに属すIDをフローします。リソース・アダプタはEISへの接続を確立し、WorkインスタンスをEIS IDのコンテキストで実行します。このケースでは、開始元プリンシパルまたは呼出し側プリンシパルがアプリケーション・サーバーのセキュリティ・ドメインに存在しません。あるドメインから他のドメインへの変換は、実行が求められます。つまり、EISセキュリティ・ドメイン内のユーザーまたはグループ名が、アプリケーション・サーバーのセキュリティ・ドメイン内の対応するユーザーまたはグループ名にマッピングされます。該当するユーザーまたはグループのマッピングが見つからない場合、デフォルト・マッピングが適用されます。

要素inbound-mapping-requiredは、EISセキュリティ・ドメインからアプリケーション・サーバーのセキュリティ・ドメインへのフローされたID変換が、必須かどうかを指定します。

この要素のサブ要素については、「security-work-context」を参照してください。

default-principal-name

default-principal-name要素には以下のサブ要素が含まれます。

表A-5 default-principal-nameのサブ要素

要素

必須/省略可能

説明

use-anonymous-identity

必須

匿名IDを使用することを指定します。

principal-name

必須

プリンシパル名を使用することを指定します。定義済みのWebLogic Serverユーザー名と一致しなければなりません。

manage-as-principal-name

manage-as-principal-name要素には以下のサブ要素が含まれます。

表A-6 manage-as-principal-nameのサブ要素

要素

必須/省略可能

説明

use-anonymous-identity

必須

匿名IDを使用することを指定します。

principal-name

必須

プリンシパル名を使用することを指定します。定義済みのWebLogic Serverユーザー名と一致しなければなりません。

run-as-principal-name

run-as-principal-name要素には以下のサブ要素が含まれます。

表A-7 run-as-principal-nameのサブ要素

要素

必須/省略可能

説明

use-anonymous-identity

必須

匿名IDを使用することを指定します。

principal-name

必須

プリンシパル名を使用することを指定します。定義済みのWebLogic Serverユーザー名と一致しなければなりません。

use-caller-identity

必須

呼出し側のIDを使用することを指定します。

run-work-as-principal-name

run-work-as-principal-name要素には以下のサブ要素が含まれます。

表A-8 run-work-as-principal-nameのサブ要素

要素

必須/省略可能

説明

use-anonymous-identity

必須

匿名IDを使用することを指定します。

principal-name

必須

プリンシパル名を使用することを指定します。定義済みのWebLogic Serverユーザー名と一致しなければなりません。

use-caller-identity

必須

呼出し側のIDを使用することを指定します。

security-work-context

security-work-context要素には以下のサブ要素が含まれます。

表A-9 security-work-contextのサブ要素

要素

必須/省略可能

説明

inbound-mapping-required

省略可能

デフォルト値はfalseで、これはケース1を意味します。caller-principal-mappingおよびgroup-principal-mappingのサブ要素すべてが無視されます。

trueに設定されている場合、ケース2を意味します。caller-principal-mappingおよびgroup-principal-mappingのすべての要素が、EISセキュリティ・ドメインからWebLogicドメインへの正しいマッピングの判断に使用されます。

デフォルト値: false

caller-principal-default-mapped

省略可能

EISユーザー名から、特定のWebLogicユーザー名またはWebLogicユーザーanonymousへのデフォルト・マッピングを指定します。

つまり、EISユーザーに対するWebLogicユーザー名が見つからない場合、このデフォルト・マッピングが使用されます。この要素のサブ要素については、「caller-principal-default-mapped」を参照してください。

caller-principal-mapping

省略可能

EISユーザー名から、特定のWebLogicユーザー名またはWebLogicのanonymous IDへのマッピングを指定します。ゼロまたはそれ以上のcaller-principal-mapping要素がweblogic-ra.xmlで指定される場合があります。

この要素のサブ要素については、「caller-principal-mapping」を参照してください。

group-principal-default-mapped

省略可能

EISグループ名から、特定のWebLogicグループ名へのデフォルト・マッピングを指定します。

つまり、EISグループに対するWebLogicグループ名が見つからない場合、このデフォルト・マッピングが使用されます。

group-principal-mapping

省略可能

EISグループ名から、特定のWebLogicグループ名へのマッピングを指定します。ゼロまたはそれ以上のgroup-principal-mapping要素がweblogic-ra.xmlで指定される場合があります。

このマッピングのサブ要素については、「group-principal-mapping」を参照してください。

caller-principal-default-mapped

caller-principal-default-mapped要素には以下のサブ要素が含まれます。

表A-10 caller-principal-default-mappedのサブ要素

要素

必須/省略可能

説明

use-anonymous-identity

必須

WebLogic anonymousユーザーIDを使用することを指定します。use-anonymous-identityまたはprincipal-nameのどちらを選択することもできますが、両方は選択できません。

principal-name

必須

プリンシパル名を使用することを指定します。これはWebLogicセキュリティ・レルムで定義されたWebLogicユーザー名に一致する必要があります。

caller-principal-mapping

caller-principal-mapping複合要素は、EISグループ名からWebLogicグループ名へのマッピングの指定に使用されます。次のサブ要素が含まれます。

表A-11 caller-principal-mappingのサブ要素

要素

必須/省略可能

説明

eis-caller-principal

必須

EISユーザー・プリンシパル名を指定します。

mapped-caller-principal

必須

マッピングされたWebLogicユーザー・プリンシパル名、またはanonymousユーザーID (ただし両方ではない)を指定します。

group-principal-mapping

group-principal-mapping要素には以下のサブ要素が含まれます。

表A-12 group-principal-mappingのサブ要素

要素

必須/省略可能

説明

eis-group-principal

必須

EISグループ・プリンシパル名を指定します。

mapped-group-principal

必須

マッピングされたWebLogicグループ・プリンシパル名を指定します。

properties

properties要素はweblogic-connector要素のサブ要素であり、ra.xmlでリソース・アダプタBeanに対して指定されたプロパティのコンテナです。1つまたは複数のproperty要素を保持します。

properties要素の内部にproperty要素を次のように定義します。

表A-13 propertiesのサブ要素

要素

必須/省略可能

説明

property

必須

property要素は、ra.xmlファイルでリソース・アダプタBeanに対して指定されたプロパティをオーバーライドするのに使用します。

2つのサブ要素があります。

name - config-property-name要素(ra.xmlデプロイメント記述子のconfig-propertyのサブ要素)と同じ名前を指定します。このパラメータを設定すると、ra.xmlの関連するconfig-property-value要素はオーバーライドされます。これは必須要素です。

value - config-property-value要素(ra.xmlデプロイメント記述子のconfig-propertyのサブ要素)をオーバーライドする値を指定します。この要素は省略可能です。

admin-objects

admin-objects複合要素では、リソース・アダプタのすべての管理オブジェクトを定義します。outbound-resource-adapter複合要素と同様に、admin-objects複合要素には、指定できる3つの階層的なプロパティ・レベルがあります。

admin-objects要素はweblogic-connector要素のサブ要素です。admin-objects要素の内部に以下の要素を定義できます。

表A-14 admin-objectsのサブ要素

要素

必須/省略可能

説明

default-properties

省略可能

リソース・アダプタのすべての管理オブジェクトに適用されるデフォルト・プロパティを(グローバル・レベルで)指定します。

default-properties要素には1つまたは複数のproperty要素を含めることができ、それぞれにはnameとvalueのペアが入ります。「properties」を参照してください。

admin-object-group

1つまたは複数

ra.xmlデプロイメント記述子で指定された特定の管理オブジェクト・グループに属する、すべての管理オブジェクトに適用されるデフォルト・パラメータを指定します。グループで指定されたプロパティは、グローバル・レベルで指定されたパラメータをオーバーライドします。

admin-object-groupのサブ要素については、「admin-object-group」を参照してください。

admin-object-group

admin-object-group要素は管理オブジェクト・グループの定義に使用されます。グループ・レベルでは、ra.xmlデプロイメント記述子で指定された特定の管理オブジェクト・グループに属する、すべての管理オブジェクトに適用されるパラメータを指定します。グループで指定されたプロパティは、グローバル・レベルで指定されたパラメータをオーバーライドします。

admin-object-interface要素(admin-object-group要素のサブ要素)は、各admin-object-groupに必須の一意の要素(キー)として機能します。weblogic-ra.xml admin-object-interface要素とra.xml adminobject-interface要素間には、1対1の関係が必要です。

admin-object-group要素はweblogic-connector要素のサブ要素です。admin-object-group要素の内部に以下の要素を定義できます。

表A-15 admin-object-group

要素

必須/省略可能

説明

admin-object-interface

必須

admin-object-interface要素は、各admin-object-groupに必須の一意の要素(キー)として機能します。weblogic-ra.xmlのadmin-object-interface要素とra.xmlのadminobject-interface要素の間は、1対1の関係である必要があります。

admin-object-class

1.6アダプタで必須

admin-object-interface要素とadmin-object-class要素の組合せは、各admin-object-groupに必須の一意の要素(キー)として機能します。次の2つのペアには1対1の関係があることが必要です。

- weblogic-ra.xmlに定義されているadmin-object-interface要素とadmin-object-class要素のペア

- ra.xmlに定義されているadmin-object-interface要素とadmin-object-class要素のペア

default-properties

省略可能

この管理オブジェクト・グループ内のすべての管理オブジェクトに適用される、すべてのデフォルト・プロパティを指定します。

default-properties要素には1つまたは複数のproperty要素を含めることができ、それぞれにはnameとvalueのペアが入ります。「properties」を参照してください。

admin-object-instance

1つまたは複数

管理オブジェクト・グループ内の1つまたは複数のオブジェクト・インスタンス(リソース・アダプタの管理オブジェクト・インスタンスに相当する)を指定します。インスタンス・レベルでプロパティを指定すると、グループ・レベルやグローバル・レベルで指定された同じプロパティをオーバーライドできます。サブ要素については、「admin-object-instance」を参照してください。

admin-object-instance

admin-object-instanceの下に以下のサブ要素を定義できます。

表A-16 admin-object-instanceのサブ要素

要素

必須/省略可能

説明

jndi-name

必須

接続インスタンスの参照名を定義するJNDI名。

接続プールは、アプリケーション外部のクライアントが表示できるJNDIにバインドされます。

注意: enable-access-outside-app要素をtrueに設定する必要があります。

properties

省略可能

管理オブジェクト・インスタンスに適用されるすべてのプロパティを定義します。

properties要素には1つまたは複数のproperty要素を含めることができ、それぞれにはnameとvalueのペアが入ります。「properties」を参照してください。

outbound-resource-adapter

outbound-resource-adapter要素はweblogic-connector要素のサブ要素です。outbound-resource-adapter要素の内部に以下の要素を定義できます。

表A-17 outbound-resource-adapterのサブ要素

要素

必須/省略可能

説明

default-connection-properties

省略可能

この複合要素を使用して、プロパティをグローバル・レベルで指定します。このレベルで、ユーザーはリソース・アダプタのすべてのアウトバウンド接続プールに適用されるパラメータを指定できます。

サブ要素については、「default-connection-properties」を参照してください。

connection-definition-group

1つまたは複数

この要素を使用して、すべての接続定義グループを指定します。ra.xmlデプロイメント記述子内の接続ファクトリとweblogic-ra.xmlデプロイメント記述子内のグループとの間には、1対1の対応関係が必要です。ra.xml内のすべての接続ファクトリに対して、weblogic-ra.xmlデプロイメント記述子にグループが存在していなくてもかまいません。ただし、グループが存在する場合は、そのグループに少なくとも1つの接続インスタンスが含まれている必要があります。

グループで指定されたプロパティは、default-connection-propertiesを使用してグローバル・レベルで指定されたパラメータをオーバーライドします。

サブ要素については、「connection-definition-group」を参照してください。

default-connection-properties

default-connection-properties要素はoutbound-resource-adapter要素のサブ要素です。default-connection-properties要素の内部に以下の要素を定義できます。

表A-18 default-connection-propertiesのサブ要素

要素

必須/省略可能

説明

pool-params

省略可能

この接続ファクトリの接続プール固有のパラメータを指定するための親要素となります。WebLogic Serverはここでの指定を使用して、ManagedConnectionのプールの動作を制御します。

この要素は省略可能です。この要素またはこの要素の特定の項目を指定しない場合は、デフォルト値が割り当てられます。指定されているデフォルト値については、それぞれの要素の説明を参照してください。

サブ要素については、「pool-params」を参照してください。

logging

省略可能

リソース・アダプタのManagedConnectionFactoryおよびManagedConnectionオブジェクトのロギングを構成するパラメータが含まれます。

サブ要素については、「logging」を参照してください。

transaction-support

省略可能

特定の接続ファクトリのトランザクション・サポートのレベルを指定します。ra.xmlデプロイメント記述子で指定されたtransaction-support値(リソース・アダプタのすべての接続ファクトリのデフォルトとなる値)をオーバーライドできます。

transaction-supportの値は以下のいずれか。

NoTransaction
LocalTransaction
XATransaction

関連情報については、第6章「接続管理」を参照してください。

authentication-mechanism

省略可能

authentication-mechanism要素では、リソース・アダプタの特定の接続ファクトリでサポートされる認証メカニズムを指定します。ra.xmlデプロイメント記述子で指定されたauthentication-mechanism値(リソース・アダプタのすべての接続ファクトリのデフォルトとなる値)をオーバーライドできます。

BasicPasswordメカニズム・タイプではjavax.resource.spi.security.PasswordCredentialインタフェースをサポートする必要があります。

reauthentication-support

省略可能

特定の接続ファクトリで、既存のManagedConnectionインスタンスの再認証をサポートするかどうかを指定するブール値。ra.xmlデプロイメント記述子で指定されたreauthentication-support値(リソース・アダプタのすべての接続ファクトリのデフォルトとなる値)をオーバーライドできます。

properties

省略可能

properties要素には1つまたは複数のproperty要素を含めます。この要素では、デフォルト接続に適用されるnameおよびvalueサブ要素を定義します。

res-auth

省略可能

コンテナ管理によるセキュリティまたはアプリケーション管理によるセキュリティのどちらを使用するかを指定します。この要素の値はApplicationまたはContainerです。デフォルト値はContainerです。

pool-params

pool-params要素はdefault-connection-properties要素のサブ要素です。pool-params要素の内部に以下の要素を定義できます。

表A-19 pool-paramsのサブ要素

要素

必須/省略可能

説明

initial-capacity

省略可能

ManagedConnectionの初期数を指定します。WebLogic Serverはデプロイメント中にこの数の接続を作成しようとします。

デフォルト値: 1

max-capacity

省略可能

WebLogic Serverが許容するManagedConnectionの最大数を指定します。この制限を超えてManagedConnectionの割当をリクエストすると、呼出し側にResourceAllocationExceptionが返されます。

デフォルト値: 10

capacity-increment

省略可能

追加のManagedConnectionの最大数を指定します。WebLogic Serverは、保持している接続プールのサイズを変更する際にこの数の接続を作成しようとします。

デフォルト値: 1

shrinking-enabled

省略可能

システム・リソースを制御する手段として、未使用のManagedConnectionを破棄して接続プールから削除するかどうかを指定します。

デフォルト値: true

shrink-frequency-seconds

省略可能

接続プール・マネージャが未使用のManagedConnectionを破棄しようとする間隔(秒単位)を指定します。

デフォルト値: 900秒

highest-num-waiters

省略可能

接続プールの接続を予約するのを待ちながら、同時にブロックできるスレッドの最大数を指定します。

デフォルト値: 0

highest-num-unavailable

省略可能

接続のリフレッシュなどの目的でアプリケーションから使用できなくなる、プール内のManagedConnectionの最大数を指定します。

バックエンド・システムが使用できなくなった場合などに、接続プールの制御以外の要因で、指定値を超えることもあります。

デフォルト値: 0

connection-creation-retry-frequency-seconds

省略可能

プールが接続を作成しようとする再試行の間隔。

デフォルト値: 0

connection-reserve-timeout-seconds

省略可能

プールの接続を予約する呼出しがタイムアウトするまでの秒数を指定します。

デフォルト値: -1 (リソースを予約する場合はブロックしません)

test-frequency-seconds

省略可能

プールの接続をテストする頻度。

デフォルト値: 0

test-connections-on-create

省略可能

新しく作成された接続のテストを有効にします。

デフォルト値: false

test-connections-on-release

省略可能

解放されてプールに戻されるときの接続のテストを有効にします。

デフォルト値: false

test-connections-on-reserve

省略可能

予約時の接続のテストを有効にします。

デフォルト値: false

profile-harvest-frequency-seconds

省略可能

接続プールのプロファイルを収集する頻度を指定します。

ignore-in-use-connections-enabled

省略可能

この要素を使用して、接続プールが停止されるときに、その時点で使用中の接続を無視するかどうかを指定します。

match-connections-supported

省略可能

リソース・アダプタがManagedConnectionFactory.matchManagedConnections()メソッドをサポートするかどうかを示します。リソース・アダプタがこのメソッドをサポートしない(このメソッドに対して常にnullを戻す)場合、WebLogic Serverは接続リクエストのこのメソッド呼出しを無視します。

デフォルト値: true

logging

logging要素はdefault-connection-properties要素のサブ要素です。logging要素の内部には以下の要素を定義できます。

表A-20 loggingのサブ要素

要素

必須/省略可能

説明

log-filename

省略可能

ManagedConnectionFactoryまたはManagedConnectionから生成された出力を送るログ・ファイルの名前を指定します。

ファイル名は絶対アドレスで指定する必要があります。

logging-enabled

省略可能

ManagedConnectionFactoryまたはManagedConnectionに対してログ・ライターが設定されているかどうかを示します。この要素をtrueに設定すると、ManagedConnectionFactoryまたはManagedConnectionから生成された出力は、log-filename要素で指定したファイルに送られます。

デフォルト値: false

rotation-type

省略可能

ファイルのローテーション・タイプを設定します。

可能な値はbySize、ObyNameO、noneです。

bySize - ログ・ファイルがfile-size-limitに指定したサイズに達すると、ファイル名がFileName.nに変更されます。

ObyNameO - file-time-spanに指定した間隔で、ファイル名がFileName.nに変更されます。ファイル名が変更されると、以後のメッセージはlog-filenameに指定した名前の新しいファイルに蓄積されます。

none - メッセージは1つのファイルに蓄積されます。ログのサイズが大きくなった場合、ファイルの内容を消去する必要があります。

デフォルト値: bySize

number-of-files-limited

省略可能

古いログ・メッセージを保存するためにこのサーバー・インスタンスが作成するファイルの数を制限するかどうかを指定します。(rotation-typeでbySizeを指定する必要があります。)この制限に達すると、最も古いファイルが上書きされます。このオプションを有効にしない場合、新しいファイルが無限に作成されていくため、必要に応じてこれらのファイルを削除する必要があります。

number-of-files-limitedをtrueに設定して有効にした場合、サーバーはrotationType変数を参照してログ・ファイルのローテーション方法を判断します。ローテーションでは、新しいファイルを作成するのではなく、既存のファイルがオーバーライドされます。number-of-files-limitedをfalseに設定すると、サーバーは同じログ・ファイルをオーバーライドしないで、多数のログ・ファイルを作成します。

デフォルト値: false

file-count

省略可能

サーバーがログをローテーションする際に作成するログ・ファイルの最大数。この数には、現在のメッセージを格納するためにサーバーで使用されているファイルは含まれません。(number-of-files-limitedを有効にする必要があります。)

デフォルト値: 7

file-size-limit

省略可能

サーバーがログ・メッセージを別のファイルに移動する処理をトリガーするサイズ。(rotation-typeでbySizeを指定する必要があります。)ログ・ファイルが指定の最小サイズに到達すると、以後サーバーは、ファイル・サイズをチェックする際に、現在のログ・ファイルの名前をFileName.nに変更し、それ以降のメッセージを保存するための新規ログ・ファイルを作成します。

デフォルト値: 500

rotate-log-on-startup

省略可能

起動サイクル中にサーバーがログ・ファイルをローテーションするかどうかを指定します。

デフォルト値: true

log-file-rotation-dir

省略可能

ローテーションされたログ・ファイルが格納されるディレクトリ・パスを指定します。

rotation-time

省略可能

ログ・ファイルの時間ベースのローテーション・シーケンスの開始時間で、フォーマットはk:mm(ここでkは1 - 24)です。(rotation-typeでbyTimeを指定する必要があります。)指定された時間に、現在のログ・ファイル名が変更されます。以後、file-time-spanで指定した間隔でログ・ファイル名が変更されます。

指定した時間がすでに過ぎている場合、サーバーは直ちにファイルのローテーションを開始します。

デフォルトでは、ローテーション・サイクルは直ちに開始されます。

file-time-span

省略可能

古いログ・メッセージが別のファイルに移される間隔(単位は時間)。rotation-typeでbyTimeを指定する必要があります。

デフォルト値: 24

connection-definition-group

connection-definition-group要素は接続定義グループを定義するのに使用します。connection-definition-group要素を使用して、ra.xmlデプロイメント記述子で指定された特定の接続ファクトリに属する、すべてのアウトバウンド接続に適用されるパラメータを、グループ・レベルで指定します。ra.xmlの接続ファクトリとweblogic-ra.xmlの接続定義グループの間には、1対1の対応関係があります。グループで指定されたプロパティは、グローバル・レベルで指定されたパラメータをオーバーライドします。

connection-factory-interface要素(connection-definition-group要素のサブ要素)は、各connection-definition-groupに必須の一意の要素(キー)として機能します。weblogic-ra.xml connection-definition-interface要素とra.xml connectiondefinition-interface要素間には、1対1の関係がなければなりません。

connection-definition-group要素はoutbound-resource-adapter要素のサブ要素です。connection-definition-group要素の内部に以下の要素を定義できます。

表A-21 connection-definition-groupのサブ要素

要素

説明

connection-factory-interface

すべての接続定義グループにはキー(必須の一意の要素)があります。このキーはconnection-factory-interfaceです。

connection-factory-interfaceに指定する値は、ra.xmlのconnection-factory-interfaceに指定された値と同じである必要があります。

default-connection-properties

この複合要素を使用して、アウトバウンド接続のプロパティをグループ・レベルで定義します。

「default-connection-properties」を参照してください。

connection-instance

各接続定義グループの下に、接続インスタンスを指定できます。これは、リソース・アダプタに対する個別の接続プールに相当します。このレベルでパラメータを指定すると、グループ・レベルやグローバル・レベルで指定された同じパラメータをオーバーライドできます。

この要素では、接続プールの説明を指定します。(接続インスタンスは接続プールに相当します。)接続プールの説明に使用されます。

「connection-instance」を参照してください。

connection-instance

connection-instanceの下に以下のサブ要素を定義できます。

表A-22 connection-instanceのサブ要素

要素

必須/省略可能

説明

description

省略可能

接続インスタンスの説明を指定します。

jndi-name

必須

接続インスタンスの参照名を定義するJNDI名。

connection-properties

省略可能

接続インスタンスに適用されるすべてのプロパティを定義します。

connection-properties要素には1つまたは複数のproperty要素を含めることができ、それぞれにはnameとvalueのペアが入ります。「properties」を参照してください。

B リソース・アダプタのベスト・プラクティス

この付録では、リソース・アダプタ開発者向けのベスト・プラクティスについて説明します。この節の内容は以下のとおりです。

- リソース・アダプタのクラスローディングの最適化

- 接続の最適化

- スレッド管理

- InteractionSpecインタフェース

- javax.jms.ConnectionFactoryの使用

リソース・アダプタのクラスローディングの最適化

リソース・アダプタ・クラスを1つまたは複数のJARファイルにパッケージ化してから、そのJARファイルをRARファイル内に配置することができます。これをネストされたJARと呼びます。JARファイルをRARファイル内にネストしていて、クラスがクラスローダーによってロードされる必要がある場合、RARファイル内のJARは、ロードする必要のある各クラスごとに、開いて閉じて繰返し処理されることになります。

RARファイル内のJARの数が少なく、JARのサイズが比較的小さい場合は、パフォーマンスに大きな影響は与えません。一方、多数のJARがあり、JARのサイズが大きい場合は、パフォーマンスへの影響が大きくなります。

そのようなパフォーマンスの問題を避けるには、次のいずれかを行います。

1. リソース・アダプタを展開形式でデプロイします。この場合、JARのネストは不要になるため、クラスの検索に関わるパフォーマンスの影響は小さくなります。

2. リソース・アダプタを展開形式でデプロイできない場合は、RARファイルの内部でJARを展開できます。この場合もJARのネストは不要になるため、クラスローディングのパフォーマンスが大幅に向上します。

接続の最適化

リソース・アダプタで、『JSR 322: Java EE Connector Architecture 1.6』の7.16.1および7.16.2項で述べられているオプションの機能を実装することをお薦めします。これらの機能を実装すると、WebLogic Serverでは、通常は利用できない機能を提供できます。

怠惰な接続の関連付けの最適化(7.16.1項に記載)を利用すると、サーバーは未使用の接続を自動的にクリーン・アップして、アプリケーションによるリソースの占有を防ぐことができます。怠惰なトランザクション登録の最適化(7.16.2項に記載)を利用すると、アプリケーションは、接続がすでに開かれた後で、トランザクションを開始できます。

スレッド管理

リソース・アダプタの実装でWorkManagerを使用して(『JSR 322: Java EE Connector Architecture 1.6』の第10章「Work Management」に記載)、新しいスレッドで実行する必要がある処理を、新しいスレッドを直接作成しないで起動するようにしてください。WebLogic Serverはこれらのスレッドの管理やモニターを行えるようになります。

InteractionSpecインタフェース

『JSR 322: Java EE Connector Architecture 1.6』の第17章「Common Client Interface」に従って、WebLogic ServerはEISのアクセスでCommon Client Interface (CCI)をサポートしています。CCIでは、アプリケーション・コンポーネント用の標準クライアントAPIを定義しています。アプリケーション・コンポーネントおよびEAIフレームワークは、CCIを使用することにより、異種EIS間の対話を制御できます。

ベスト・プラクティスとしては、CCIリソース・アダプタをRARファイル内に実装しなければならないInteractionSpecクラスは格納しないでください。代わりに、RARファイルの外部にある別のJARファイルにパッケージ化してください。そうすると、一般的なCLASSPATHにInteractionSpecインタフェース・クラスを入れないでも、クライアントがアクセスできるようになります。

InteractionSpecインタフェースについては、すべてのアプリケーション・コンポーネント(EJB、リソース・アダプタ、Webアプリケーション)がEARファイルにパッケージ化されている場合、すべての共通クラスをAPP-INF/libディレクトリに配置できることに留意してください。これが最も簡単なシナリオです。

このことは、スタンドアロンのリソース・アダプタ(RARファイルにパッケージ化)には当てはまりません。(InteractionSpecと同様に)インタフェースがシリアライズ可能である場合、クライアントとリソース・アダプタの両方が、実装クラスだけでなくInteractionSpecインタフェースにアクセスする必要があります。ただし、インタフェースがjava.io.Remoteを拡張している場合、クライアントがアクセスする必要があるのはインタフェース・クラスのみです。

javax.jms.ConnectionFactoryの使用

EJBまたはサーブレットを使用して、XAトランザクションを使用してJMSプロバイダを支援するJCAアダプタを使用するメッセージを送信する際、resource-refはjava.lang.objectである必要があります。

WebLogic Server環境で、javax.jms.ConnectionFactoryを指定すると、このJCAアダプタ構成と互換性がないWebLogic JMSラッパーが実装されます。『Oracle WebLogic Server JMSアプリケーションの開発』のEJBやサーブレットと組み合せたWebLogic JMSの使用に対する拡張サポートに関する項を参照してください。

Copyright © 2007, 2013, Oracle and/or its affiliates. All rights reserved.