Oracle® Fusion Middleware Oracle WebLogic Server リソース アダプタ プログラマーズ ガイド 11g リリース 1 (10.3.1) B55541-01 |
|
戻る |
次へ |
以下の節では、WebLogic Server リソース アダプタを作成してコンフィグレーションする方法について説明します。
この節では、新しい WebLogic リソース アダプタを作成する方法について説明します。次の節「既存のリソース アダプタの変更」では、既存のリソース アダプタを WebLogic Server にデプロイできるように準備する方法について説明します。
WebLogic リソース アダプタを作成するには、特定のリソース アダプタのクラス (ConnectionFactory
、Connection
など) を作成し、リソース アダプタのデプロイメント記述子を記述して、それらを WebLogic Server にデプロイされるアーカイブ ファイルにパッケージ化する必要があります。
リソース アダプタを作成する主な手順は以下のとおりです。
J2CA 1.5 仕様 (http://java.sun.com/j2ee/connector/
) に従って、リソース アダプタに必要な各種クラス (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>
詳細については、「プログラミング タスク」を参照してください。
標準コンパイラを使用して、インタフェースと実装の Java コードをクラス ファイルにコンパイルします。
リソース アダプタのデプロイメント記述子を作成します。WebLogic リソース アダプタでは 2 つのデプロイメント記述子を使用します。
ra.xml
では、J2CA 1.5 仕様で指定された標準の XML スキーマを使用して、リソース アダプタに関連する属性タイプとそのデプロイメント プロパティを記述します。
weblogic-ra.xml
では、接続や接続プールのプロパティ、セキュリティ ID、ワーク マネージャのプロパティ、ロギングなど、WebLogic Server に固有のデプロイメント情報を追加します。
リソース アダプタの Weblogic Server 固有のデプロイメント記述子を作成する詳細については、「weblogic-ra.xml ファイルのコンフィグレーション」および「A weblogic-ra.xml スキーマ」を参照してください。
Java クラスを .rar
拡張子の付いた Java アーカイブ (JAR) ファイルにパッケージ化します。
ステージング ディレクトリをハード ディスクの任意の場所に作成します。JAR ファイルをステージング ディレクトリに置き、デプロイメント記述子を META-INF
というサブディレクトリに置きます。
次に、ステージング ディレクトリで次のように jar
コマンドを実行して、リソース アダプタ アーカイブを作成します。
jar cvf myRAR.rar *
リソース アダプタ アーカイブ (RAR) ファイルをテスト環境の WebLogic Server にデプロイして、テストします。
テスト中に、リソース アダプタ デプロイメント記述子の編集が必要になる場合があります。それには、WebLogic Server Administration Console を使用するか、XML エディタまたはテキスト エディタを使用して手動で行います。デプロイメント記述子の編集の詳細については、「weblogic-ra.xml ファイルのコンフィグレーション」および『Oracle Fusion Middleware Oracle WebLogic Server Administration Console ヘルプ』の「リソース アダプタのプロパティのコンフィグレーション」を参照してください。デプロイメント記述子の要素の詳細については、「A weblogic-ra.xml スキーマ」も参照してください。
RAR リソース アダプタ アーカイブ ファイルを WebLogic Server にデプロイするか、またはエンタープライズ アプリケーションの一部としてデプロイするエンタープライズ アーカイブ (EAR) ファイルに含めます。
この手順の詳細については、「リソース アダプタのパッケージ化とデプロイ」を参照してください。コンポーネントとアプリケーションのデプロイメントの詳細については、『Oracle Fusion Middleware Oracle WebLogic Server アプリケーションのデプロイメント』も参照してください。
WebLogic Server のデプロイメントとして利用できるリソース アダプタがすでにある場合もあります。この節では、RAR ファイルにパッケージ化されている既存のリソース アダプタを、WebLogic Server のデプロイメント用に変更します。それには、weblogic-ra.xml
デプロイメント記述子を追加して、リソース アダプタを再パッケージ化します。以下の手順では、blackbox-notx.rar
という RAR ファイルにパッケージ化された既存のリソース アダプタがあると仮定しています。
ハード ディスクの任意の場所にリソース アダプタのステージング用の一時ディレクトリを作成します。
mkdir c:/stagedir
リソース アダプタ アーカイブの内容を展開します。
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
weblogic-ra.xml
ファイルを作成します。このファイルは、リソース アダプタの WebLogic 固有のデプロイメント記述子です。このファイルには、接続ファクトリ、接続プール、およびセキュリティ設定のパラメータを指定します。
詳細については、「weblogic-ra.xml ファイルのコンフィグレーション」を参照してください。weblogic-ra.xml
に適用する XML スキーマの詳細については、「A weblogic-ra.xml スキーマ」も参照してください。
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
リソース アダプタ アーカイブを作成します。
jar cvf blackbox-notx.rar -C c:/stagedir
WebLogic Server にリソース アダプタをデプロイします。リソース アダプタのパッケージ化とデプロイの詳細については、「リソース アダプタのパッケージ化とデプロイ」および『Oracle Fusion Middleware Oracle WebLogic Server アプリケーションのデプロイメント』を参照してください。
リソース アダプタに ra.xml
ファイルがない場合は、手動で作成するか、または既存のファイルを編集して、リソース アダプタに必要なデプロイメント プロパティを設定する必要があります。プロパティの編集には、テキスト エディタまたは XML エディタを使用できます。ra.xml
ファイルの作成については、J2CA 1.5 仕様 (http://java.sun.com/j2ee/connector/
) を参照してください。
標準リソース アダプタ コンフィグレーションの 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 名 (J2CA 1.5 仕様に基づいて開発されたリソース アダプタは、(http://java.sun.com/j2ee/connector/
) 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 スキーマ」のリファレンス情報を参照してください。以下の節のコンフィグレーション情報も参照してください。
WebLogic Server のリソース アダプタ アーカイブで使用される XML 記述子を定義または変更するには、weblogic-ra.xml
および ra.xml
デプロイメント記述子ファイルで XML 要素を定義または編集する必要があります。デプロイメント記述子ファイルは任意のテキスト エディタで編集できます。ただし、エラーが起きないように、XML 編集用に設計されたツールを使用してください。ファイルのほとんどの要素は WebLogic Administration Console でも編集できます。
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/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd" version="1.5"> |
weblogic-ra.xml |
<?xml version = "1.0"> <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_5.xsd
には、すべてのリソース アダプタに必要な標準 ra.xml
デプロイメント ファイルのスキーマが含まれています。このスキーマは、J2CA 1.5 仕様の一部です。http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd
にあります。
weblogic-ra.xsd
には、WebLogic Server にデプロイする際に使用されるリソース アダプタ プロパティを定義する weblogic-ra.xml
を作成するためのスキーマが含まれています。このスキーマは http://xmlns.oracle.com/weblogic/weblogic-connector/1.0/weblogic-connector.xsd
にあります。
注意 : ブラウザによっては、.xsd 拡張子を持つファイルの内容を表示できない場合があります。その場合にスキーマの内容を見るには、リンクをテキスト ファイルとして保存し、テキスト エディタで表示します。 |
Administration Console を使用して、デプロイメント記述子の要素を表示、変更、(必要な場合には) 永続化できます。一部の記述子要素の変更は、リソース アダプタを再デプロイしなくても、実行時に動的に行われます。それ以外の記述子要素は、変更後に再デプロイが必要です。Administration Console を使用してリソース アダプタをコンフィグレーションするには、[デプロイメント] を開いて、デプロイ済みリソース アダプタの名前をクリックします。リソース アダプタのコンフィグレーションを変更するには、[コンフィグレーション] タブを使用します。他のタブを使用して、リソース アダプタの制御、テスト、またはモニタを行います。Administration Console の使用方法については、『Oracle Fusion Middleware Oracle WebLogic Server Administration Console ヘルプ』の「リソース アダプタのプロパティのコンフィグレーション」を参照してください。
Administration Console を使用して、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 Server にデプロイされるリソース アダプタ アーカイブ (RAR) には、J2CA 1.5 仕様 (http://java.sun.com/j2ee/connector/
) で指定された 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 メカニズムは WebLogic Server リリース 8.1 で導入されました。基本アダプタを 1 つデプロイし、そのコードを、さまざまなコンフィグレーション プロパティを持つ複数の論理的なアダプタで共有できるようにするものです。現在のリリースの 1.5 リソース アダプタでは、Link-Ref メカニズムは非推奨となり、新しい J2EE ライブラリ機能で置き換えられています。ただし、1.0 リソース アダプタの場合は、このリリースでも Link-Ref メカニズムがサポートされています。J2EE ライブラリの詳細については、『Oracle Fusion Middleware Oracle WebLogic Server アプリケーションの開発』の「共有 J2EE ライブラリおよびオプション パッケージの作成」を参照してください。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 スキーマ」を参照してください。