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 ファイル	DOCTYPE ヘッダ
`ra.xml`	`<!DOCTYPE connector PUBLIC`'`-//Sun Microsystems, Inc.//DTD Connector 1.0//EN`' 'http://java.sun.com/dtd/connector_1_0.dtd'`>`
`weblogic-ra.xml`	`<!DOCTYPE weblogic-connection-factory-dd PUBLIC` "`-//BEA Systems, Inc.//DTD WebLogic 8.1.0 Connector//EN`" "http://www.bea.com/servers/wls810/dtd/weblogic810-ra.dtd">

XML ファイル

DOCTYPE ヘッダ

ra.xml

<!DOCTYPE connector PUBLIC'-//Sun Microsystems, Inc.//DTD Connector 1.0//EN'
'http://java.sun.com/dtd/connector_1_0.dtd'>

weblogic-ra.xml

<!DOCTYPE weblogic-connection-factory-dd PUBLIC

"-//BEA Systems, Inc.//DTD WebLogic 8.1.0 Connector//EN" "http://www.bea.com/servers/wls810/dtd/weblogic810-ra.dtd">

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 の場所が示されています。

connector_1_0.dtd には、すべてのリソースアダプタに必要な標準 ra.xml デプロイメントファイルの DTD が含まれています。この DTD は「J2EE コネクタ仕様、バージョン 1.0」の一部として保守されています。connector_1_0.dtd で使用される要素の詳細については、この仕様 (http://java.sun.com/j2ee/download.html#connectorspec) を参照してください。
weblogic-ra.dtd には、WebLogic Server にデプロイする際に使用されるリソースアダプタプロパティを定義する weblogic-ra.xml を作成するための DTD が含まれています。このファイルは、http://www.bea.com/servers/wls810/dtd/weblogic810-ra.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 で示されるパスワード。管理対象の接続および接続ハンドルを割り当てるときに使用される。

要素

必須
省略可能

説明

<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 で示されるパスワード。管理対象の接続および接続ハンドルを割り当てるときに使用される。