3 リソースアダプタの作成とコンフィグレーション

以下の節では、WebLogic Server リソースアダプタを作成してコンフィグレーションする方法について説明します。

リソースアダプタの作成とコンフィグレーション : 主な手順
既存のリソースアダプタの変更
ra.xml ファイルのコンフィグレーション
weblogic-ra.xml ファイルのコンフィグレーション

リソースアダプタの作成とコンフィグレーション : 主な手順

この節では、新しい 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 ファイルのコンフィグレーション

リソースアダプタに ra.xml ファイルがない場合は、手動で作成するか、または既存のファイルを編集して、リソースアダプタに必要なデプロイメントプロパティを設定する必要があります。プロパティの編集には、テキストエディタまたは XML エディタを使用できます。ra.xml ファイルの作成については、J2CA 1.5 仕様 (http://java.sun.com/j2ee/connector/) を参照してください。

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 名 (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 ファイル

スキーマヘッダ

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

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

Administration Console を使用して、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) には、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 メカニズムのコンフィグレーション

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 スキーマ」を参照してください。

3 リソース アダプタの作成とコンフィグレーション

リソース アダプタの作成とコンフィグレーション : 主な手順

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