WebLogic J2EE コネクタ アーキテクチャ
weblogic-ra.xml デプロイメント記述子の要素
以下の節では、WebLogic Server リソース アダプタ アーカイブで使用する WebLogic Server 固有の全 XML 記述子プロパティをリファレンス形式で示し、XML 記述子プロパティを編集する方法について説明します。リソース アダプタ用のデプロイメント記述子を参照する必要がある場合は、これらの節を参考にしてください。
リソース アダプタ アーカイブ (RAR) に weblogic-ra.xml ファイルが含まれない場合、WebLogic Server はこのファイルを自動的に作成します。
XML デプロイメント ファイルの手動による編集
WebLogic Server のリソース アダプタ アーカイブで使用される XML デプロイメント記述子を定義または変更する場合は、weblogic-ra.xml ファイルで XML 要素を手動で定義または編集する必要があります。
基本規約
XML 要素を手動で編集する場合は、
XML の形式の変更や、ファイルを無効にする可能性のある文字の挿入を行わない ASCII テキスト エディタを必ず使用します。
使用しているオペレーティング システムで大文字小文字が区別されない場合であっても、ファイル名やディレクトリ名の大文字小文字は正確に指定します。
省略可能な要素に対してデフォルト値を使用する場合は、要素の定義全体を省略するか、または次のように空白値を指定することができます。次に例を示します。
<max-config-property></max-config-property>
DOCTYPE ヘッダ情報
XML デプロイメント ファイルの編集、作成時に、各デプロイメント ファイルに対して正しい DOCTYPE
ヘッダを指定することが重要です。特に、DOCTYPE
ヘッダ内部に不正な PUBLIC
要素を使用すると、原因究明が困難なパーサ エラーになることがあります。
このヘッダは、デプロイメント記述子の文書型定義 (DTD) ファイルの場所およびバージョンを表します。このヘッダは外部 URL の java.sun.com
を参照していますが、WebLogic Server には独自の DTD ファイルが用意されているので、ホスト サーバがインターネットにアクセスする必要はありません。ただし、この要素の DTD のバージョンはデプロイメント記述子のバージョンの識別に使用されるので、<!DOCTYPE...>
要素を ra.xml
ファイルに含めて、外部 URL を参照させる必要があります。
ra.xml および weblogic-ra.xml ファイルの DOCTYPE
ヘッダ全体は以下のようになります。
XML の解析ユーティリティ (ejbc
など) でヘッダ情報が不正な XML ファイルを解析すると、次のようなエラー メッセージが表示されることがあります。
SAXException: This document may not have the identifier `identifier_name
'
identifier_name
には通常、PUBLIC
要素内の不正な文字列が表示されます。
検証用 DTD (Document Type Definitions : 文書型定義)
XML ファイルの内容および要素の配置は、使用する各ファイルの文書型定義 (DTD) に従っている必要があります。WebLogic Server ユーティリティでは、XML デプロイメント ファイルの DOCTYPE
ヘッダ内部に埋めこまれた DTD は無視され、代わりにサーバと一緒にインストールされた DTD の場所が使用されます。ただし、DOCTYPE ヘッダ情報には、パーサ エラーを避けるために有効な URL 構文を指定する必要があります。
以下のリンクでは、WebLogic Server で使用される XML デプロイメント ファイル用の DTD の場所が示されています。
注意 : ほとんどのブラウザでは、.dtd
ファイルの内容は表示されません。DTD ファイルの内容をブラウザで見るには、リンクをテキスト ファイルとして保存し、テキスト エディタで開いて表示します。
WebLogic Builder を使用したデプロイメント記述子の編集
WebLogic Builder は、アプリケーションのデプロイメント記述子 XML ファイルを編集するためのビジュアルな環境を提供します。WebLogic Builder では、これらの XML ファイルをビジュアルに編集しながら参照できるので、テキストによる編集は必要ありません。
WebLogic Builder は以下の開発作業に使用します。
J2EE モジュール用のデプロイメント記述子ファイルの生成
モジュールのデプロイメント記述子ファイルの編集
デプロイメント記述子ファイルの表示
デプロイメント記述子ファイルのコンパイルおよび検証
モジュールのサーバへのデプロイメント
WebLogic Builder の使い方については、『WebLogic Builder オンライン ヘルプ』を参照してください。
記述子の動的な更新
WebLogic Server のこのリリースでは、Administration Console のデプロイメント記述子エディタは非推奨になりました。代わりに、新しく Administration Console の [記述子] タブが提供されています。[記述子] タブを使うと、リソース アダプタ内の記述子ファイルを表示および変更し、デプロイメント記述子エディタを使った場合と同じようにしてデプロイメント記述子要素の永続化を行えます。
ただし、これらの記述子要素の変更は、リソース アダプタを再デプロイする必要なしに、実行時に動的に行われます。[記述子] タブ内の記述子要素は、実行時に動的に変更され得る記述子要素に限定されています。weblogic-ra.xml の以下の要素がこれに該当します。
initial-capacity
max-capacity
capacity-increment
shrinking-enabled
shrink-frequency-seconds
highest-num-unavailable
highest-num-waiters
inactive-connection-timeout-seconds
connection-reserve-timeout-seconds
test-frequency-seconds
connection-creation-retry-frequency-seconds
weblogic-ra.xml の要素の説明
weblogic-ra.xml ファイルで定義できる各要素について以下の節で説明します。
weblogic-connection-factory-dd
weblogic-connection-factory-dd
要素は WebLogic 固有のデプロイメント記述子のルート要素で、デプロイ済みリソース アダプタ用です。
次の表では、weblogic-connection-factory-dd
要素内で定義できる要素について説明します。
要素
|
必須 省略可能
|
説明
|
<connection-factory-name>
|
必須
|
特定のリソース アダプタのデプロイメントおよび対応する接続ファクトリに関連付けられる論理名を定義する。この要素の値は、ra-link-ref 要素を介して他のデプロイ済みリソース アダプタで使用できる。これにより、複数のデプロイ済み接続ファクトリ間で、指定されているコンフィグレーションを共有するだけでなく、共通のデプロイ済みリソース アダプタを利用することもできる。
|
<description>
|
省略可能
|
親要素について説明するテキストを指定する。この要素には、デプロイヤがデプロイ済みファクトリについて説明するための情報を含める。
|
<jndi-name>
|
必須
|
接続ファクトリ オブジェクトを WebLogic JNDI ネームスペースにバインドするための名前を定義する。クライアント EJB およびサーブレットも、WebLogic 固有のデプロイメント記述子で定義されている Reference Descriptor 要素でこの JNDI を使用する。
|
<ra-link-ref>
|
省略可能
|
複数のデプロイ済み接続ファクトリを 1 つのデプロイ済みリソース アダプタに論理的に関連付けることができる。省略可能な ra-link-ref 要素に別のデプロイ済み接続ファクトリを示す値を指定すると、新しくデプロイされる接続ファクトリが、参照先の接続ファクトリと一緒にデプロイされたリソース アダプタを共有する。また、参照先の接続ファクトリのデプロイメントで定義されているすべての値は、その他の値が指定されていない限り、新しくデプロイされるこの接続ファクトリが継承する。
|
<native-libdir>
|
省略可能
ネイティブ ライブラリがある場合は必須
|
このリソース アダプタ デプロイメントのすべてのネイティブ ライブラリ用に使用するディレクトリの場所を示す。デプロイメント処理の一部として、検出されたネイティブ ライブラリはすべて指定された場所にコピーされる。管理者は、WebLogic Server の実行中にライブラリが見つかるようにプラットフォームのアクションを実行する必要がある。
|
<pool-params>
|
省略可能
|
この接続ファクトリの接続プール固有のパラメータを指定するための親要素。WebLogic Server は、管理対象の接続が保持するプールの動作を制御する際にこれらの指定を使用する。
この要素またはこの要素に固有の項目を指定しないと、デフォルト値が割り当てられる。指定されているデフォルト値については、それぞれの要素の説明を参照。
<pool-params> の要素の詳細については、「pool-params」を参照。
|
<logging-enabled>
|
省略可能
|
ManagedConnectionFactory または ManagedConnection に対してログ ライターが設定されているかどうかを示す。この要素を true に設定すると、ManagedConnectionFactory または ManagedConnection から生成された出力は、log-filename 要素で指定したファイルに送られる。
この値を指定しないと、WebLogic Server は定義されているデフォルト値を使用する。
値の範囲 : true または false。
デフォルト値 : false
|
<log-filename>
|
省略可能
|
ManagedConnectionFactory または ManagedConnection から生成された出力を送るログ ファイルの名前を指定する。
ファイル名は絶対アドレスで指定する必要がある。
|
<map-config-property>
|
省略可能、ゼロまたは 1 つ以上
|
対応する config-property-name 名を持つ ra.xml の config-entry 要素に対応するコンフィグレーション プロパティの名前および値を示す。デプロイメント時には、map-config-property で指定されたすべての値が ManagedConnectionFactory で設定される。map-config-property を介して指定された値は、対応する ra.xml config-entry 要素で指定されたデフォルト値に優先する。
<map-config-property> 要素の詳細については、「map-config-property」を参照。
|
<security-principal-map>
|
省略可能
|
この要素は非推奨。WebLogic 実行時の既知の initiating-principal に基づいて、リソース アダプタおよび EIS の許可処理用の resource-principal 値を定義するためのメカニズムを提供する。このマップにより、管理対象の接続と接続ハンドルを割り当てる際に使用される開始プリンシパルと対応するリソース プリンシパルのユーザ名およびパスワードのセットを指定できる。
デフォルトの resource-principal は、このマップに基づいて接続ファクトリ用に定義できる。initiating-principal 値に「*」を指定し、対応する resource-principal 値を指定した場合、マップ内で現在の ID と一致するものがないときには必ず定義した resource-principal が利用される。
この要素は省略できるが、コンテナ管理によるサインオンがリソース アダプタでサポートされており、いずれかのクライアントで使用される場合は指定する必要がある。
また、定義済みの「デフォルト」リソース プリンシパル (指定されている場合) を使用して、デプロイメント時に管理対象の接続を接続プールに取得するよう試行される。
<security-principal-map> 要素の詳細については、「security-principal-map」を参照。
|
pool-params
次の表では、pool-params
要素内で定義できる要素について説明します。
要素
|
必須 省略可能
|
説明
|
<initial-capacity>
|
省略可能
|
管理対象の接続の初期数を示す。WebLogic Server はデプロイメント中にこの数の接続を取得しようとする。
この値を指定しないと、WebLogic Server は定義されているデフォルト値を使用する。
デフォルト値 : 1
|
<max-capacity>
|
省略可能
|
WebLogic Server が許容する管理対象接続の最大数を指定する。この制限を超えて管理対象の接続の割り当てを要求すると、呼び出し側に ResourceAllocationException が返される。
この値を指定しないと、WebLogic Server は定義されているデフォルト値を使用する。
デフォルト値 : 10
|
<capacity-increment>
|
省略可能
|
管理対象の接続の最大追加数を示す。WebLogic Server は、保持している接続プールのサイズを変更する際にこの数の接続を取得しようとする。
この値を指定しないと、WebLogic Server は定義されているデフォルト値を使用する。
デフォルト値 : 1
|
<shrinking-enabled>
|
省略可能
|
接続プールがシステム リソースの管理手段として未使用の管理対象接続を再利用するかどうかを示す。
この値を指定しないと、WebLogic Server は定義されているデフォルト値を使用する。
値の範囲 : true または false。
デフォルト値 : true
|
<shrink-period-minutes>
|
省略可能
|
この要素は非推奨。shrink-frequency-seconds 要素に置き換えられた。
接続プール マネージャが未使用の管理対象接続を再利用しようとする間隔を示す。
デフォルト値 : 15
|
<connection-cleanup-frequency>
|
省略可能
|
この要素は非推奨。接続プール管理によって設定されている使用時間を超えた接続ハンドルを破棄しようとする間隔を示す。この要素は connection-duration-time と連携して、アプリケーションが使用後の接続を閉じなかった場合に接続リークを防ぐ。
この値を指定しないと、WebLogic は定義されているデフォルト値を使用する。
デフォルト値 : -1 -1
注意 : connection-cleanup-frequency 要素は非推奨。このパラメータを現在コンフィグレーションで使用している場合、デプロイメント機能はまだ使用することができる。しかし、これらの要素はコンフィグレーションに反映されない。
|
<connection-duration-time>
|
省略可能
|
この要素は非推奨。接続がアクティブ状態を保つことができる時間。この要素は connection-cleanup-frequency と連携して、アプリケーションが使用後の接続を閉じなかった場合にリークを防ぐ。
この値を指定しないと、WebLogic は定義されているデフォルト値を使用する。
デフォルト値 : -1 -1
注意 : connection-duration-time 要素は非推奨。このパラメータを現在コンフィグレーションで使用している場合、デプロイメント機能はまだ使用することができる。しかし、これらの要素はコンフィグレーションに反映されない。
|
<connection-maxidle-time>
|
省略可能
|
この要素は非推奨。inactive-connection-timeout-seconds 要素に置き換えられた。
接続ハンドルがアイドル状態を保つことができる時間 (単位 : 秒) を指定する。この要素はアプリケーションが接続の使用を完了後に接続を閉じなかった時にリークを防ぐ。アイドル接続が打ち切られるのは、接続プールが一杯になり、そのために新しい接続リクエストが失敗することが確実な場合のみ。
デフォルト値 : 0
|
<connection-profiling-enabled>
|
省略可能
|
接続プールが各接続の割り当て先コールスタックを格納するかどうかを指定する。有効化すると、この情報をコンソールを通じてアクティブな接続で参照できる。また、これを有効化すると、リークした接続とアイドル接続のスタックが表示され、接続のクローズに失敗するコンポーネントをデバッグする上で役立つ。
この値を指定しないと、WebLogic は定義されているデフォルト値を使用する。
値の範囲 : true または false。
デフォルト値 : false
|
<shrink-frequency-seconds>
|
省略可能
|
接続プール マネージャが未使用の管理対象接続を再利用しようとする間隔 (単位 : 秒) を指定する。
この値を指定しないと、WebLogic は定義されているデフォルト値を使用する。
デフォルト値 : 900 秒
|
<inactive-connection-timeout-seconds>
|
省略可能
|
接続ハンドルが非アクティブ状態を保つことができる時間 (単位 : 秒) を指定する。この要素はアプリケーションが接続の使用の完了後に接続を閉じなかった時にリークを防ぐ。非アクティブな接続は、検出されると直ちに終了される。
この値を指定しないと、WebLogic は定義されているデフォルト値を使用する。
デフォルト値 : 0
|
<highest-num-waiters>
|
省略可能
|
プールの接続を予約するために同時に待機するリクエストの最大数。
デフォルト値 : 0
|
<highest-num-unavailable>
|
省略可能
|
接続の更新などのためにアプリケーションで使用できなくなるプール内の物理接続 (管理対象の接続) の最大数。バックエンド システムが使用できなくなった場合など、プール制御の範囲を越える原因で指定した値を超えることがある。
デフォルト値 : 0
|
<connection-creation-retry-frequency-seconds>
|
省略可能
|
プールが接続を確立しようとする再試行の間隔。
デフォルト値 : 0
|
<connection-reserve-timeout-seconds>
|
省略可能
|
プールからの接続を予約する呼び出しのタイムアウト後の秒数。
デフォルト値 : -1 (リソースを予約する場合はブロックしないこと)
|
<test-frequency-settings>
|
省略可能
|
プールの接続をテストする間隔。
デフォルト値 : 0
|
<match-connections-supported>
|
省略可能
|
リソース アダプタが ManagedConnectionFactory.matchManagedConnections() メソッドをサポートするかどうかを示す。リソース アダプタがこのメソッドをサポートしない (このメソッドに対して常に null を返す) 場合、WebLogic Server は接続リクエストのこのメソッド呼び出しを無視する。
値の範囲 : true または false
デフォルト値 :true
|
map-config-property
次の表では、map-config-property
要素内で定義できる要素について説明します。
要素
|
必須 省略可能
|
説明
|
<map-config-property-name>
|
省略可能
|
対応する config-property-name を持つ ra.xml config-entry に対応する名前を示す。
|
<map-config-property-value>
|
省略可能
|
対応する config-property-name を持つ ra.xml config-entry に対応する値を示す。
|
security-principal-map
次の表では、security-principal-map
要素内で定義できる要素について説明します。
要素
|
必須 省略可能
|
説明
|
<map-entry>
|
省略可能
|
security-principal-map 内のエントリを示す。
initiating-principal (省略可能、ゼロまたは 1 つ以上)
resource-principal (省略可能) - security-principal-map を介して接続ファクトリ向けに定義できる。initiating-principal 値に「*」を指定し、対応する resource-principal 値を指定した場合、マップ内で現在の ID と一致するものがないときには必ず定義した resource-principal が利用される。
resource-username (省略可能) - resource-principal で示されるユーザ名。管理対象の接続および接続ハンドルを割り当てるときに使用される。
resource-password (省略可能) - resource-principal で示されるパスワード。管理対象の接続および接続ハンドルを割り当てるときに使用される。
|