Fusion Middlewareとの統合に向けたアダプタ・ランタイム・コンポーネントの開発

4.1 設計全体の理解

Oracle JCA Frameworkは、J2EE Java Connector Architectureバージョン1.5に準拠したアダプタにプラガビリティをもたらします。つまり、Oracle JCA Frameworkで使用されるアダプタは、JCA 1.5仕様に記載されている要件を満たす必要があります。

要件は、「JSR-112, J2EE Connector Architecture 1.5 - Final Release)」を参照してください。

注意:

Oracle JCA Frameworkでは、軽量JCA 1.5コンテナが実装されます。このコンテナでは、インバウンド・エンドポイント(アクティブ化)の動的(コード駆動)デプロイメントが可能になります。これは、JCA 1.5トランザクション・インフローのサポート(つまり、XATerminatorのサポート)を除外することにおいて、小さな短所となっています。

4.2 接続構成

Oracle JCA Frameworkには、J2EE 1.4またはこれ以降に準拠したアプリケーション・サーバー(Oracle WebLogic Serverなど)でデプロイ可能なJCAアダプタが必要です。

Oracle JCA Frameworkで使用するすべてのJCAアダプタで、すべての関連JCA SPI(サービス・プロバイダ)およびCCI(共通クライアント)インタフェースをJCA 1.5の仕様で必須とされているとおりに実装する必要があります。主なインタフェースは次のとおりです。

javax.resource.spi.ManagedConnectionFactory

javax.resource.cci.ConnectionFactory

javax.resource.spi.ManagedConnection

javax.resource.cci.Connection

JCAアダプタでは、必要な接続プロパティをManagedConnectionFactoryで定義して、EIS(企業情報システム、つまりバックエンド)への機能接続を確立する必要があります。

Oracle JCA FrameworkでManagedConnectionFactoryを使用すると、デプロイ済JCAアダプタ経由で接続を取得できるようになります。コードのサンプルを次に示します。

ConnectionFactory cf = initialContext.lookup("eis/Siebel/SiebelApp1-Connection");

Connection c = cf.getConnection();

すべての接続プロパティは、ConnectionFactoryインスタンスに含まれるJNDIルックアップを使用して取得されます。

4.3 実行時インタフェースおよび規定

アダプタは、Oracle JCA Frameworkと正常に相互に作用するように、特定のインタフェースおよび規定に準拠する必要があります。

JCAアダプタでは少なくとも、次のインタフェースを実装する必要があります。

javax.resource.spi.ResourceAdapter
javax.resource.spi.ActivationSpec
javax.resource.spi.work.Work
javax.resource.cci.Interaction
javax.resource.cci.InteractionSpec

これらのSPIインタフェースは、インバウンド・メッセージ・フローを有効にするために実装する必要があり、CCIインタフェースは、アウトバウンド相互作用を有効にするために実装する必要があります。次の各項を参照してください。

4.3.1 インバウンド

J2EE Java Connector Architectureバージョン1.5は、トランザクションの観点から(つまり、アダプタでトランザクション・セマンティクスがサポートされる場合に)明確に定義された方法で、J2EEアプリケーション・サーバーで管理されているエンドポイントに、アダプタからメッセージを非同期にプッシュできるようするインタフェースを提供します。

Oracle JCA Frameworkでは、これらのエンドポイントは、アダプタ・フレームワークで管理されます。

4.3.2 JCA 1.5の規定およびインタフェース

次の各項で、Oracle Fusion Middlewareへのデプロイを可能にするためにJCA 1.5準拠のリソース・アダプタで実装する必要がある各サービス・プロバイダ・インタフェース(SPI)について説明します。

4.3.2.1 Interfacejavax.resource.spi.ResourceAdapter

各JCAアダプタにこのインタフェースを実装する必要があります。アダプタ・フレームワークでは、このインタフェースのアダプタでの実装がシングルトンとして扱われます。つまり、Java仮想マシンごとにこのインタフェースの実装のインスタンスは多くても1つだけ存在することになります。

アダプタが(特定のJVMの)いずれのビジネス・プロセスでも使用されない場合は、そのアダプタでのResourceAdapterの実装はインスタンス化されません。

4.3.2.2 インスタンス化

ResourceAdapterの実装は、対象のアダプタを使用する最初のコンポジット・アプリケーションの開始時にインスタンス化されます。

その後、同じアダプタを使用する他のコンポジットを開始した場合、追加のResourceAdapterインスタンスが作成されることはありませんが、最初の(シングルトン)インスタンスへのハンドルが取得されます。

ResourceAdapterインスタンスの作成直後に、次のメソッドが呼び出されます。

public void start(BootstrapContext ctx)
   throws ResourceAdapterInternalException

アダプタでは、BootstrapContextをキャッシュする必要があります。これには、インバウンド・エンドポイント相互作用の作成およびスケジューリングに必要なファシリティが含まれるためです。

BootstrapContextにも、ロギング・サービス・ハンドルが含まれます。リソース・アダプタでこのハンドルをキャッシュして、インバウンド・メッセージ・フローをサポートするすべてのクラス(つまりjavax.resource.spi.*の下に提供されるクラス)で使用する必要があります。

アウトバウンドでは、ロギング・サービス・ハンドルは、ConnectionFactoryを通して使用できます。

4.3.2.3 stopメソッドおよびエンドポイント・アクティブ化

stopメソッドは、アプリケーション・サーバーの停止時、またはアダプタを参照する最後のコンポジットの終了時に、リソース・インスタンスがアンデプロイされたときに呼び出されます。

public void stop()

アクティブなエンドポイントが存在する場合、サーバーまたはコンポジットの停止時にアダプタ・フレームワークによって呼び出されたstop()メソッドから値が返される前に、これらのエンドポイントを非アクティブ化する必要があります。

その他の割当て済リソースも同様にすぐにリリースする必要があります。

public void endpointActivation(MessageEndpointFactory endpointFactory,
       ActivationSpec spec)

メッセージ・エンドポイントのアクティブ化の際に、エンドポイント・アクティブ化が呼び出されます。

JCAベースの開始または非開始サービス・エントリ・ポイント(つまり、<service>でbinding.jcaを使用するエントリ・ポイント)が含まれる各コンポジットでは、.jcaプロパティ・ファイルのコネクション・ファクトリJNDIによって参照されるResourceAdapterの関連(インバウンド)操作ごとに、endpointActivation()の呼出しが発生します。

4.3.2.4 コネクション・ファクトリ、作業リクエスト、エンドポイント非アクティブ化

アダプタ・フレームワークでは、.jcaプロパティ・ファイルの<connection-factory>要素に定義されているとおりに、MessageEndpointFactoryを使用して、ConnectionFactoryのインスタンスが指定されます。このインスタンスをリソース・アダプタで使用して接続を作成できます。

javax.resource.cci.ConnectionFactory connectionFactory =
    ((ConnectionFactoryAssociation)activationSpec).getConnectionFactory();
javax.resource.cci.Connection connection = connectionFactory.getConnection();

この呼出し時に、リソース・アダプタでは、MessageEndpointFactoryを使用して、インバウンド・エンドポイントを作成し、インバウンドEISエンドポイントを監視するインバウンド・スレッドを構成する作業リクエストを発行する必要があります。

ResourceAdapterInboundWorkerThread workRequest =
    new ResourceAdapterInboundWorkerThread(endpoint, activationSpec, connection);
      workManager.startWork(workRequest);

ここで、ResourceAdapterInboundWorkerThreadは、リソース・アダプタでのjavax.resource.spi.work.Workの実装です。

startWork()から値が返されたらすぐに、アダプタ・フレームワークは、run()メソッドを呼び出すことによって、発行したworkRequestにスレッドを割り当てます。

次のメソッドendpointDeactivationは、メッセージ・エンドポイントが非アクティブ化された際、つまり、そのエンドポイントをアクティブ化したコンポジットの停止時またはアプリケーション・サーバーの停止時に、アダプタ・フレームワークによって呼び出されます。

public void endpointDeactivation(MessageEndpointFactory
  endpointFactory, ActivationSpec spec)

注意:

カスタム・アダプタがOracle Weblogic環境で動作するためには、カスタム・アダプタのコネクション・ファクトリがoracle.tip.adapter.api.OracleConnectionFactoryを実装する必要があります。カスタム・アダプタのコネクション・ファクトリがoracle.tip.adapter.api.OracleConnectionFactoryを実装する必要がある場合、JDeveloperによって生成される.jcaの<connection-factory>に<resource-adapter>要素を追加します。次に例を示します。

<connection-factory location="eis/Custom/CustomAdapter"/>
	<resource-adapter className="com.custom.oracle.fusion.adapter.CustomAdapter"/>
</connection-factory>

4.3.3 Interfacejavax.resource.spi.work.Work

Workインタフェースは、次のとおりです。

public interface Work extends Runnable

Oracle SOAを使用してデプロイしたJCA 1.5準拠のリソース・アダプタは、管理対象モード(つまり、 J2EEコンテナ内)で実行されるため、独自にスレッドを作成することはできません。このため、アダプタは、かわりにWebLogicアプリケーション・サーバーに依存して、スレッドの作成と開始を行う必要があります。

スレッド(たとえば、インバウンド・エンドポイントのポーリングに使用するスレッド)を取得するには、アダプタは、Workインタフェースを実装するクラスのインスタンスをWorkManager(これを受けてBootstrapContextを使用して取得される)に発行する必要があります。

アダプタでは、これはrunメソッドを使用して実行されます。

public void run()

このメソッドは、新規に割り当てられたJ2EE準拠のスレッドを使用して、WorkManagerによって呼び出されます。リソース・アダプタでは、停止を選択するまで(たとえば、リカバリ不能なエラー状態など。ただし、この規則はお薦めしません)、またはより適切な、アダプタが停止のシグナルを受けるまで(release()メソッドによって)、このスレッドを使用できます。

public void release()

アダプタ自体は、アダプタ・フレームワークによって実行されたendpointDeactivationの呼出しを処理する際に、release()を呼び出します。

このアクティビティは、現在Workインスタンスを実行しているスレッド、つまりendpointActivationを呼び出しているシステム・スレッドとは別のスレッドで呼び出されます。

リソース・アダプタで、release()の呼出し後に事前設定されている時間が経過した後に、run()メソッドが終了されない場合、アダプタ・フレームワークでは、スレッドの強制的な停止が試行されます。

4.3.4 Interfacejavax.resource.spi.work.WorkManager

Oracle SOAでは、WorkManagerインタフェースの実装は、アダプタ・フレームワークによって行われます。実装は最小限です。これは、アダプタ・フレームワークでは、拡張スレッド・プーリングや高度なスケジューリングがサポートされないためです。

かわりに、アダプタ・フレームワークでは、6つのパブリック・メソッドのうち1つのメソッドscheduleWork(Work work)のみが実装されます。その他のパブリック・メソッドは、このメソッドにリダイレクトされます。つまり、呼出しのブロッキングはサポートされていません(この例として、呼出しのブロッキングはdoWork()に必要です)。

アダプタ・フレームワークでは、SOAのデフォルトのワーク・マネージャを使用して、完了したWorkインスタンスから解放されたスレッドをWorkの新規発行で再使用できるようにします。

次のメソッドでは、Workインスタンスが処理に向けて受け入れられます。

public void scheduleWork(Work work)

   throws WorkException

この呼出しはブロックされず、Workインスタンスが処理に向けて受け入れられるとすぐに値が返されます。発行されたWorkインスタンスでいつ実行が開始されるかの保証はありません。つまり、実行の開始に時間の制約はありません。

4.3.5 アウトバウンドにおける考慮事項

アウトバウンドおよびインバウンドのシナリオでは、リソース・マネージャはJCA 1.0の仕様に定義されている標準の規定に準拠する必要があります。

アウトバウンドのシナリオでは、アダプタの実行時定義を指定する際に、次の要件を満たす必要があります。

リソース・アダプタのManagedConnectionFactoryで、接続関連のパラメータをすべて定義する必要があります。これによって単にOracle SOAランタイムが実行可能になります。次に例を示します。
```
ConnectionFactory cciConnectionFactory = 
   initialContext.lookup("eis/sample/...");
Connection cciConnection = cciConnectionFactory.getConnection();
```
InteractionSpec実装の標準のInteractionSpecパラメータはすべて、String、int、boolean、short、long、floatおよびdoubleのうちのいずれかの引数タイプを使用して、1つの引数ミューテータ・メソッドによって構成する必要があります。
リソース・アダプタは、管理対象環境で機能できることが必要です。このため、リソース・アダプタは、J2EEアプリケーション・サーバーにデプロイ可能である必要があります。

4.3.6 変換サービス・インタフェース

変換サービス・インタフェースでは、メッセージとネイティブ・フォーマットとの間の変換が処理されます。アダプタ・フレームワークでは、指定のWSDLバインディング操作のInteractionSpecまたはActivationSpecをインスペクトすることによって、操作関連メッセージのネイティブ・フォーマットへの、またはネイティブ・フォーマットからの変換における要件が判別されます。

示された仕様のいずれかで、変換マーカー・インタフェースTranslationAwareが実装されると、アダプタ・フレームワークでは、WSDLのtypesセクションから対応するXSDElementが指定され、これによって入力メッセージ・タイプが定義されます。

具体的には、アダプタ・フレームワークでは、次のステップが実行されます。

jcaInteractionSpec=(InteractionSpec)
  Class.forName(_interactionSpecName).newInstance();
    if (jcaInteractionSpec instanceof TranslationAware)
      {
            oracle.xml.parser.schema.XMLSchema nXsdSchemaRoot =
              getInputMessageSchemaElement();
              ((TranslationAware)jcaInteractionSpec).
                 setNXSDSchemaRoot(nXsdSchemaRoot);
                 }
jcaInteraction.execute(jcaInteractionSpec, ...

4.4 WebLogic JCAリソース・アーカイブRARの作成

デプロイメント・ディスクリプタでは、<outbound-resourceadapter>のインスタンスが定義されるのみです。これは、インバウンドJCAラインタイム・コンテナはOracle WebLogic Serverではなく、Oracle JCA Frameworkによって直接管理されるためです。

WebLogicアプリケーション・サーバーにJCAアダプタをデプロイするには、ユーザーは次のプロパティを定義するデプロイメント・ディスクリプタ・ファイルを作成する必要があります。

表示名
アダプタ・ベンダー
EIS/バックエンド・タイプ
バージョン番号
javax.resource.spi.ManagedConnectionFactoryのアダプタ実装のクラス名
javax.resource.cci.ConnectionFactoryのアダプタ実装のクラス名
javax.resource.cci.Connectionのアダプタ実装のクラス名
ManagedConnectionFactory実装で公開されるすべてのBeanプロパティの名前

デプロイメント・ディスクリプタ・ファイル(ra.xml)をRARファイル(リソース・アーカイブ)にアーカイブする必要があります。RARファイルは、WebLogic Serverコンソールまたはスクリプトを使用してデプロイできます。

ユーザーがデプロイするRARファイルには、次の構造が必要です。

/META-INF/ra.xml
/adapter.jar
/dependencies.jar

adapter.jarファイルには、JCAアダプタの実装が含まれ、dependencies.jarには、WebLogicアプリケーション・サーバーによって暗黙的には提供されないすべての依存Javaライブラリが含まれます。

これらの構成ファイルが前述のディレクトリ構造に配置されると、次のコマンドを使用してRARファイルを作成できます。

$ jar cf myAdapter.rar META-INF/ra.xml adapter.jar dependencies.jar

プロジェクトのコンパイルに必要なjarファイルのリストは、付録を参照してください。

4.5 WebLogicアプリケーション・サーバーへのRARファイルのデプロイ

アダプタのリソース・アーカイブを作成したら、ユーザーは、WLS管理コンソールの「デプロイメント」セクションまたはWLSTツールを使用して、WebLogicアプリケーション・サーバーにアダプタをデプロイする必要があります。

RARファイルをWebLogic Serverドメイン・ディレクトリの下のautodeployディレクトリに直接コピーすることもできます。ここでは、RARファイルは自動的にデプロイされます。

RARをデプロイすると、ユーザーは、WebLogic Server管理コンソールの「デプロイメント」セクションの下に接続ファクトリを作成できます。例として、アウトバウンド接続プール構成表を使用している、次のスクリーンショットを参照してください。

図4-1 WebLogic Server管理コンソールを使用した接続ファクトリの作成

「図4-1 WebLogic Server管理コンソールを使用した接続ファクトリの作成」の説明

4.6 カスタム・アダプタのテスト

サンプルに関する項では、カスタム・アダプタのテストに関連する情報について説明します。

詳細は、「カスタム・アダプタのSDK開発のサンプル」を参照してください。