Oracle® Fusion Middleware Oracle WebLogic Serverリソース・アダプタのプログラミング 11g リリース1(10.3.5) B60996-03 |
|
![]() 前 |
![]() 次 |
次の項では、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>
詳細は、第4章「プログラミング・タスク」を参照してください。
標準コンパイラを使用して、インタフェースと実装の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管理コンソールを使用するか、XMLエディタまたはテキスト・エディタを使用して手動で行います。デプロイメント記述子の編集の詳細は、weblogic-ra.xmlファイルの構成および『Oracle Fusion Middleware Oracle WebLogic Server管理コンソール・ヘルプ』のリソース・アダプタのプロパティの構成に関する項を参照してください。デプロイメント記述子の要素の詳細は、付録A「weblogic-ra.xmlスキーマ」も参照してください。
RARリソース・アダプタ・アーカイブ・ファイルをWebLogic Serverにデプロイするか、またはエンタープライズ・アプリケーションの一部としてデプロイするエンタープライズ・アーカイブ(EAR)ファイルに含めます。
この手順の詳細は、第9章「リソース・アダプタのパッケージ化とデプロイ」を参照してください。コンポーネントとアプリケーションのデプロイメントの詳細は、『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にリソース・アダプタをデプロイします。リソース・アダプタのパッケージ化とデプロイの詳細は、第9章「リソース・アダプタのパッケージ化とデプロイ」および『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管理コンソールでも編集できます。
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 拡張子を持つファイルの内容を表示できない場合があります。その場合にスキーマの内容を見るには、リンクをテキスト・ファイルとして保存し、テキスト・エディタで表示します。 |
管理コンソールを使用して、デプロイメント記述子の要素を表示、変更、(必要な場合には)永続化できます。一部の記述子要素の変更は、リソース・アダプタを再デプロイしなくても、実行時に動的に行われます。それ以外の記述子要素は、変更後に再デプロイメントが必要です。管理コンソールを使用してリソース・アダプタを構成するには、「デプロイメント」を開いて、デプロイ済みリソース・アダプタの名前をクリックします。リソース・アダプタの構成を変更するには、「構成」タブを使用します。他のタブを使用して、リソース・アダプタの制御、テスト、またはモニターを行います。管理コンソールの使用方法については、『Oracle Fusion Middleware Oracle WebLogic Server管理コンソール・ヘルプ』の「リソース・アダプタのプロパティの構成」を参照してください。
管理コンソールを使用して、リソース・アダプタの再デプロイを行わずに次の構成パラメータを動的に変更できます。
アダプタの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 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スキーマ」を参照してください。