| Oracle® Fusion Middleware Oracle WebLogic Serverリソース・アダプタの開発 12c (12.2.1.2.0) E82907-02 |
|
 前 |
 次 |
この章の内容は以下のとおりです。
この項では、新しいWebLogicリソース・アダプタを作成する方法について説明します。次の項「既存のリソース・アダプタの変更」では、既存のリソース・アダプタをWebLogic Serverにデプロイメントできるように準備する方法について説明します。
WebLogicリソース・アダプタを作成するには、特定のリソース・アダプタのクラス(ConnectionFactory、Connectionなど)を作成し、リソース・アダプタのデプロイメント記述子を記述して、それらをWebLogic Serverにデプロイされるアーカイブ・ファイルにパッケージ化する必要があります。
リソース・アダプタを作成する主な手順は以下のとおりです。
WebLogic Serverのデプロイメントとして利用できるリソース・アダプタがすでにある場合もあります。この項では、RARファイルにパッケージ化されている既存のリソース・アダプタを、WebLogic Serverのデプロイメント用に変更します。それには、weblogic-ra.xmlデプロイメント記述子を追加して、リソース・アダプタを再パッケージ化します。以下の手順では、blackbox-notx.rarというRARファイルにパッケージ化された既存のリソース・アダプタがあると仮定しています。
すべてのリソース・アダプタをra.xmlデプロイメント記述子ファイルに指定する必要があります。1.0または1.5のリソース・アダプタでは、このファイルを手動で作成する必要があります。1.6リソース・アダプタを作成している場合は、メタデータの注釈をオプションでリソース・アダプタ・クラスに指定できます。これにより、ra.xmlファイルを手動で作成する必要性がなくなります。次の項では、ra.xmlファイルの構成方法について説明します。
ra.xmlファイルの作成の詳細は、『JSR 322: Java EE Connector Architecture 1.6』も参照してください。
リソース・アダプタにra.xmlファイルがなく、リソース・アダプタを作成している場合は、手動で作成するか、または既存のファイルを編集して、リソース・アダプタに必要なデプロイメント・プロパティを設定する必要があります。プロパティの編集には、テキスト・エディタまたはXMLエディタを使用できます。
Java EEコネクタ・アーキテクチャ1.6では、ra.xmlファイルを手動で作成する必要はありません。かわりに、メタデータ注釈をリソース・アダプタのクラスに含めると、ra.xmlファイルに指定するのと同じ機能を提供できます。
すべてのデプロイメント情報をra.xmlファイルに指定することを選択した場合、Java EEコネクタ・アーキテクチャ1.6がmetadata-complete要素を含みます。これをra.xmlファイルに含めて、trueに設定します。metadata-complete要素をtrueに設定すると、リソース・アダプタのクラスに含まれるすべてのメタデータ注釈が無視されます。metadata-complete要素を指定しない、またはfalseに設定すると、WebLogic Serverは、注釈に指定された情報とra.xmlファイルに指定された情報を実行時にマージし、マージした情報を使用してリソース・アダプタのデプロイと管理を行います。
デプロイメント記述子と注釈の詳細は、『JSR 322: Java EE Connector Architecture 1.6』の第18章「Metadata Annotations」を参照してください。また、『The Java EE 6 Tutorial』の「Metadata Annotations」も参照してください。
Java EEコネクタ・アーキテクチャ1.6では、主に開発容易性の機能(メタデータ注釈など)をサポートするためにra.xmlファイル・スキーマが変更されています。スキーマ定義の変更の詳細は、『JSR 322: Java EE Connector Architecture 1.6』の第20.7項「Resource Adapter XML Schema Definition」を参照してください。
1.0および1.5リソース・アダプタのra-xmlファイルのスキーマは、http://java.sun.com/xml/ns/j2ee/connector_1_5.xsdです。1.6および1.7のアダプタ用のスキーマはhttp://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/index.htmlにあります。
標準リソース・アダプタ構成の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名(『JSR 322: Java EE Connector Architecture 1.6』に基づいて開発されたリソース・アダプタは、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デプロイメント記述子ファイルの構成の詳細は、「weblogic-ra.xmlスキーマ」のリファレンス情報を参照してください。次の項の構成情報も参照してください。
WebLogic Serverのリソース・アダプタ・アーカイブで使用されるXML記述子を定義または変更するには、weblogic-ra.xmlおよびra.xmlデプロイメント記述子ファイルでXML要素を定義または編集する必要があります。デプロイメント記述子ファイルは任意のテキスト・エディタで編集できます。ただし、エラーが起きないように、XML編集用に設計されたツールを使用してください。ファイルのほとんどの要素はWebLogic Server管理コンソールでも編集できます。
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://xmlns.jcp.org/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee/connector_1_7.xsd" version="1.7"> |
weblogic-ra.xml |
<?xml version = "1.5"> <weblogic-connector xmlns="http://xmlns.oracle.com/weblogic/weblogic-connector"> |
XMLの解析ユーティリティ(ejbcなど)でヘッダー情報が不正なXMLファイルを解析すると、次のようなエラー・メッセージが表示されることがあります。
SAXException: This document may not have the identifier 'identifier_name'
デプロイメント記述子ファイルの内容と要素の配置は、使用する各ファイルのスキーマに従っている必要があります。以下のリンクでは、で使用されるデプロイメント記述子ファイル用のスキーマの場所が示されています。
connector_1_7.xsdには、すべてのリソース・アダプタに必要な標準ra.xmlデプロイメント・ファイルのスキーマが含まれています。このスキーマはJSR 322: Java EE Connector Architecture 1.7の一部で、http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/index.html#7にあります。
weblogic-ra.xsdには、にデプロイメントする際に使用されるリソース・アダプタ・プロパティを定義するweblogic-ra.xmlを作成するためのスキーマが含まれています。このスキーマはhttp://xmlns.oracle.com/weblogic/weblogic-connector/1.5/weblogic-connector.xsdにあります。
注意:
ブラウザによっては、.xsd拡張子を持つファイルの内容を表示できない場合があります。その場合にスキーマの内容を見るには、リンクをテキスト・ファイルとして保存し、テキスト・エディタで表示します。
WebLogic Server管理コンソールを使用して、デプロイメント記述子の要素を表示、変更および(必要な場合には)永続化できます。一部の記述子要素の変更は、リソース・アダプタを再デプロイしなくても、実行時に動的に行われます。それ以外の記述子要素は、変更後に再デプロイメントが必要です。WebLogic Server管理コンソールを使用してリソース・アダプタを構成するには、「デプロイメント」を開いて、デプロイ済リソース・アダプタの名前をクリックします。リソース・アダプタの構成を変更するには、「構成」タブを使用します。他のタブを使用して、リソース・アダプタの制御、テスト、またはモニターを行います。
WebLogic Server管理コンソールの使用方法は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプのリソース・アダプタのプロパティの構成に関する項を参照してください。
動的に再構成できる構成プロパティについては、『JSR 322: Java EE Connector Architecture 1.6』の5.3.7.6項に説明があります。1.6リソース・アダプタの場合、WebLogic Serverでは、次のアダプタ・コンポーネントBeanに関して動的に再構成できる構成プロパティをサポートします。
ResourceAdapter Bean
ManagedConnectionFactory Bean
管理対象オブジェクトBean
実行時に、これらのアダプタ・コンポーネントBeanのいずれかで動的に構成できるプロパティを更新した後では、変更を有効にするためにアダプタを更新する必要があります。アダプタの更新は比較的負荷の軽い操作です。このとき、WebLogic Serverは実行時Beanインスタンスを変更します。構成が更新されていない、アクティブな接続プールや管理オブジェクトに干渉することはありません。アダプタをすぐに更新する必要はありません。ただし、アダプタ・コンポーネントBeanが動的に更新されるか、リソース・アダプタが再起動されない限り、Beanのプロパティの変更は有効になりません。
リソース・アダプタは、実行時のプロパティに対する動的変更のサポートに関して、注意して設計する必要があります。リソース・アダプタで提供するサービスによって異なりますが、一部のプロパティはアダプタの実行中に決して再構成しないでください。たとえば、EIS接続に使用されるリソース・アダプタのリスニング・アドレスとポート番号です(このようなプロパティを再構成すると、アダプタを停止して再起動する必要が生じます)。WebLogic Serverでは、特定のプロパティを動的に再構成可能として設計するかどうかについて、アダプタ・コンポーネントBeanに関する要件はありません。動的更新をサポートするアダプタ・コンポーネントBeanの決定は、アダプタの開発者にすべて任されています。
1.6アダプタの場合、WebLogic Serverでは、Resource Adapter、ManagedConnectionFactoryおよび管理オブジェクトBeanのプロパティでの動的更新をサポートします。WebLogic Server管理コンソールを使用して、リソース・アダプタの再デプロイを行わずに、これらのBeanの次の構成パラメータを動的に変更できます。
アダプタのJNDI名の編集
アウトバウンド接続プールの作成と削除
接続プールのJNDI名の編集
管理オブジェクトの作成と削除
管理オブジェクトのJNDI名の編集
WebLogic Server管理コンソールを使用して、リソース・アダプタの再デプロイを行わずに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)には、『JSR 322: Java EE Connector Architecture 1.6』で指定された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メカニズムは非推奨となり、新しいJava EEライブラリ機能で置き換えられています。ただし、1.0リソース・アダプタの場合は、このリリースでもLink-Refメカニズムがサポートされています。Java EEライブラリの詳細は、『Oracle WebLogic Serverアプリケーションの開発』の共有Java EEライブラリおよびオプション・パッケージの作成に関する項を参照してください。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ファイルの編集の詳細は、「weblogic-ra.xmlスキーマ」を参照してください。
『JSR 303: Bean Validation』をサポートするため、WebLogic ServerはモジュールレベルのBean検証構成ファイルを提供してJava EE 6を拡張します。WebLogic Serverでは、リソース・アダプタ・モジュールを検証するためにこのファイルのオプションでの使用がサポートされます。
Bean検証構成ファイルはリソース・アダプタ・モジュールに指定できます。リソース・アダプタが独立してデプロイされているか(スタンドアロンのRARとして)、エンタープライズ・アプリケーション(EAR)の一部としてデプロイされているかは関係ありません。Bean検証構成ファイルがアダプタ・モジュールに対して指定されない場合、WebLogic ServerはデフォルトのBean検証構成を使用してリソース・アダプタ・モジュールを検証します。
Bean検証構成ファイルにはvalidation.xmlという名前を付けて、デプロイメント記述子と一緒にRARのMETA-INFサブディレクトリに含めます。
Bean検証の詳細は、「Beanの検証」を参照してください
『JSR 322: Java EE Connector Architecture 1.6』の11.7項では、WorkManagerによって提供されるサービスの品質(QoS)特性を制御する2つの標準ヒントが定義されます。
Work名のヒント — Workインスタンスの名前になります。これは、長時間実行するWorkインスタンスに割り当てられるスレッド名の一部として使用されます。
長時間実行するWorkインスタンスのヒント — WebLogic Server拡張機能の注釈@LongRunningと同じ機能を実行します。これにより、Workインスタンスを別のスレッドにスケジュールすることができます。また、長時間実行するWorkインスタンスの制御と監視の機能が強化されます。
WebLogic Serverを使用して、長時間実行するWorkインスタンス数(同時に実行するためにリソース・アダプタで発行できる数)の制限を構成できます。デフォルトの制限は10です。この制限の値を増やすことができますが、システム・リソースの負荷が高くならないように注意する必要があります。
この制限を指定するには、weblogic-ra.xmlファイルでmax-concurrent-long-running-requests要素を使用するか、ConnectorWorkManagerRuntimeMBean.ActiveLongRunningRequests属性を設定します(これはWebLogic Server管理コンソールで公開されます)。ConnectorWorkManagerRuntimeMBeanには、ActiveLongRunningRequests属性とCompletedLongRunningRequests属性のgetterメソッドとsetterメソッドが含まれます。これらを使用すると、長時間実行するWorkインスタンスに関する情報を構成および監視できます。
詳細は、「長時間実行するWorkの構成および管理」を参照してください
WebLogic Serverでは、リソース・アダプタの開発とデプロイメントに役立つ次のツールをサポートしています。
weblogic.appmerge
検証チェックのメタデータ注釈を実行します。-writeInferredDescriptorsオプションとともに使用すると、weblogic.appmergeでは、注釈に指定されたデプロイメント情報と既存のra.xmlファイルの内容を融合する、マージされたra.xmlが生成されます。
注意:
weblogic.appmergeツールを実行した後、マージされたra.xmlでmetadata-complete要素がtrueに設定されているか確認してください。これによってデプロイヤが注釈を再処理することを回避できるため、全体的なデプロイメント・パフォーマンスが向上し、デプロイメント時間が短縮されます。
詳細は、『Oracle WebLogic Serverアプリケーションの開発のweblogic.appmergeの使用によるライブラリのマージに関する項を参照してください。
appc
注釈、Beanクラス、ra.xml、weblogic-ra.xml、およびリソース・アダプタ・デプロイメント・プランにおける広範囲の検証チェックを実行します(weblogic.appmergeは注釈のみを検証します)。
appcツールには次の機能もあります。
警告とエラーの両方を含む豊富なレポートが提供されます。
リソース・アダプタの検証と、その構成の正確さをデプロイを実行せずに確認する場合に特に有効です。
詳細は、『Oracle WebLogic Server Enterprise JavaBeansバージョン2.1の開発』のappcリファレンスに関する項を参照してください。
WebLogic Serverには、スタンドアロン・リソース・アダプタおよび埋込みリソース・アダプタのヘルス・ステータスを監視する機能が用意されています。デフォルトでは、スタンドアロンまたは埋込みリソース・アダプタにデプロイメント・エラーが発生すると、ヘルス・ステータスがHEALTH_FAILEDになり、アダプタのデプロイメント全体が失敗します。ただし、リソース・アダプタに複数のアウトバンド接続プールが設定されており、そのdeploy-as-a-wholeフラグがfalseに設定されている場合は、1つ以上のアウトバウンド接続プール・エラーが発生した場合でもアダプタのデプロイメントは成功します。このヘルス監視機能を使用すると、アダプタを再デプロイすることなく、接続プール・エラーを検出してプールを修復できます。
次の項では、WebLogic Serverでリソース・アダプタのヘルス・ステータス監視機能を使用可能にする方法を説明します。
スタンドアロン・リソース・アダプタと埋込みリソース・アダプタの両方でヘルス監視をサポートするために、WebLogic Serverには、次のMBean属性が用意されています。これらの値は、WebLogic Server管理コンソール、WLSTまたはJMXを使用して取得できます。
ConnectorComponentRuntimeMBean.HealthState: スタンドアロン・リソース・アダプタまたは埋込みリソース・アダプタのいずれかの全体的なヘルス状態を返します。アウトバウンド接続プールにデプロイメント・エラーがある場合は、リソース・アダプタのヘルス状態はHEALTH_CRITICALになります。
ApplicationRuntimeMBean.OverallHealthState: アプリケーションの集計されたヘルス状態を返します。これには、ヘルス状態を報告する埋込みコンポーネントのヘルス状態が含まれます。埋込みリソース・アダプタに、失敗したアウトバウンド接続プールがある場合は、その接続プールのヘルス状態がアプリケーションの全体的なヘルス状態に反映されます。
ConnectorConnectionPoolRuntimeMBean.HealthState: リソース・アダプタの個々のアウトバウンド接続プールのヘルス状態を返します。
失敗した接続プールが原因でアダプタ・デプロイメント全体が失敗することがないように、複数のアウトバウンド接続プールで構成されるリソース・アダプタをデプロイするには、weblogic-ra.xmlファイルのdeploy-as-a-whole要素をfalseに設定する必要があります。(デフォルトでは、この要素はtrueに設定されます。)このデプロイメント・オプションの設定の詳細は、「複数のアウトバウンド接続プールで構成されたリソース・アダプタのデプロイ」を参照してください。
