リソースアダプタの開発

ResourceAdapter インタフェースは、WebLogic Integration 8.1 の新しい機能です。これは、イベントおよびサービス処理を統合する単一のオブジェクトとして機能します。WebLogic Integration の以前のリリースでは、イベントアダプタとサービスアダプタは、別々のアダプタコンポーネントとして扱われました。また、各アダプタを個別にデプロイおよびコンフィグレーションできました。

WebLogic Integration 8.1 では、イベントアダプタとサービスアダプタが ResourceAdapter インタフェースおよびアダプタのそのインタフェースの実装下で統合されています。このインタフェースにより、イベントアダプタが作成する 0 または 1 つのイベント接続、およびサービスアダプタが作成し、接続ファクトリと呼ばれることもある 0 以上のサービス接続にアクセスできます。

イベント接続とサービス接続のコンフィグレーションは、ResourceAdapter インタフェースの下で実行されます。Application Integration Design Console で使用される用語「リソースアダプタ」は、イベント接続とサービス接続のコンテナを意味します。

WebLogic Integration では、(WLIResourceAdapter と呼ばれる) 汎用的な ResourceAdapter インタフェースの拡張機能を定義します。このインタフェースにはユーザビリティを向上させる拡張機能が用意されており、イベントアダプタのオプション機能のサポートに必要なメソッドを追加します。これらの追加メソッドにより有効になるオプション機能は以下のとおりです。

アダプタを WebLogic Integration 8.1 内で動作させるためには、各アダプタで具象クラスに WLIResourceAdapter を実装する必要があります。ADK には、com.bea.adapter.spi.AbstractWLIResourceAdapter で WLIResourceAdapter クラスの抽象ベース実装が用意されています。WebLogic Integration には、既存のアダプタを WebLogic Integration 8.1 で利用できるようにするアダプタ再パッケージユーティリティも用意されています。このユーティリティコードにより、再パッケージされた任意のアダプタに必要な WLIResourceAdapter 実装が生成されます。

WLIResourceAdapter 実装は、JavaBeans 仕様に従って実装する必要があります。これは、WebLogic Integration で WLIResourceAdapter 実装のインスタンスをインスタンス化し、そのインスタンスのプロパティを、メソッドの単純なセッターおよびゲッターの組み合わせ (プロパティごとに 1 つの組み合わせ) を介して設定できる必要があることを意味します。WLIResourceAdapter 実装用に定義されたプロパティは、イベント接続、サービス接続、またはその両方のサポートに使用できます。ただし、ほとんどの場合、WLIResourceAdapter 実装のプロパティはイベント接続のサポートに使用されますが、通常、サービス接続はサービスアダプタでの ManagedConnectionFactory 実装のプロパティによりサポートされます。

イベントのフローは、サービスアダプタの開発のフローとほぼ同じです。

実行時環境のリソースアダプタ

実行時環境でのリソースアダプタの動作を、図 8-1 に示します。

手順 1 : アダプタの定義

開発を開始する前に、リソースアダプタの要件を定義する必要があります。そのために必要な情報の完全なリストについては、「アダプタ設定ワークシート」を参照してください。この節では、手順 1 に重要なタスクの概要を説明します。

アダプタでイベント、サービス、またはその両方をサポートするかを決定します。

サービスは EIS インスタンス内で機能する。
イベントにより、EIS インスタンスでの作業が完了したことがリスナに通知される。

WLIResourceAdapter 実装のプロパティを定義します。

イベント接続のサポートに使用される各プロパティの WLIResourceAdapter 実装で、プロパティごとに 1 つのセッターメソッドと 1 つのゲッターメソッドを定義する。
サービス接続のサポートに使用される各プロパティの WLIResourceAdapter 実装で、プロパティごとに 1 つのセッターメソッドと 1 つのゲッターメソッドを定義する。この手順では、サービスアダプタの ManagedConnectionFactory 実装上に直接格納するように設計されているサービス接続に必要なプロパティを考慮する必要があります。通常は、特定の 1 つのプロパティを 1 つの場所に格納します。

定義したプロパティで必要なすべての検証ロジックを定義します。

一部のプロパティは、他のプロパティに依存したり、関連付けられている。
場合によっては、リソースアダプタインスタンスのすべてのプロパティの最終チェックを行うために、internalValidate メソッドを実装することもできる。

手順 2 : 開発環境のコンフィグレーション

この手順では 5 つの作業を行い、コンピュータでアダプタ開発を行う準備をします。

手順 2a : ファイル構造の設定

イベント接続の開発環境に必要なファイル構造は、サービス接続の開発に必要な構造と同じです。ファイル構造の詳細については、「手順 2a : ディレクトリ構造の設定」を参照してください。

手順 2b : アダプタへの論理名の割り当て

使用するアダプタに論理名を割り当てます。通常は、ベンダ名、アダプタに接続する EIS のタイプ、EIS のバージョン番号を並べて「ベンダ名_EIS のタイプ_EIS のバージョン」のように指定します。以下に例を示します。

手順 2c : ビルドプロセスの設定

WebLogic Integration では、100% Pure Java ベースのビルドツールである Ant をベースとするビルドプロセスが採用されます。Ant の機能の詳細については、「Ant ベースのビルドプロセス」を参照してください。Ant の使用方法の詳細については、以下を参照してください。

WebLogic Integration に付属のサンプルアダプタには、以下の場所に Ant ビルドファイルが用意されています。WLI_HOME/adapters/sample/project/build.xml。このファイルには、J2EE 準拠アダプタのビルドに必要なタスクが指定されています。GenerateAdapterTemplate ユーティリティを実行してアダプタの開発ツリーのクローンを作成すると、そのアダプタ専用の build.xml が作成されます。このファイルは自動的に生成されるため、サンプルの build.xml ファイルをカスタマイズする必要はなく、コードに問題はありません。GenerateAdapterTemplate ユーティリティの使用方法の詳細については、「カスタム開発環境の作成」を参照してください。

手順 2d : メッセージバンドルの作成

エンドユーザ向けに設計されたあらゆるメッセージは、メッセージバンドル、つまりメッセージのインターナショナライズを可能にする key=value の組み合わせを含む .properties テキストファイルに配置する必要があります。実行時に地理的ロケールと地域言語が指定されると、メッセージの内容が key=value の組み合わせに基づいて解釈され、メッセージが指定された言語で表示されます。

メッセージバンドルの作成方法の詳細については、以下のサイトの JavaSoft チュートリアルでインターナショナライゼーションについて参照してください。

手順 2e : ロギングのコンフィグレーション

ロギングは、Apache Jakarta プロジェクトの一環として開発された Log4j というロギングツールで実行されます。

イベント生成のロギングカテゴリの作成

イベント接続を使用する場合は、イベント生成専用のロギングカテゴリを作成する必要があります。ロギングカテゴリの詳細については、「メッセージカテゴリ」を参照してください。特定のアダプタのロギングコンフィグレーションファイル (WLI_HOME/adapters/YOUR_ADAPTER/src/adapter_logical_name.xml) を編集するには、以下のリストに示すコードを追加する必要があります。

BEA_WLS_SAMPLE_ADK は、使用するアダプタの論理名で置き換えてください。

このカテゴリにパラメータを設定しない場合は、親カテゴリから適切なすべての設定が継承されます。この例では、親カテゴリは BEA_WLS_SAMPLE_ADK です。ルートカテゴリにアダプタ論理名を使用する必要はありませんが、複数アダプタ環境で使用する他のアダプタに影響しないユニークな識別子を使用する必要があります。

手順 3 : アダプタの実装

リソースアダプタを実装するには、以下の 2 つの手順を行う必要があります。

WLIResourceAdapter 実装を作成します。このプロセスでは、統合されたリソースアダプタ実装と WLIResourceAdapter インタフェースを実装します (後者のインタフェースは、リソースアダプタのライフサイクルを管理するために、Application Integration エンジンで使用される)。この手順は「手順 3a : リソースアダプタの作成」で説明します。
プロパティセッターおよびゲッターメソッドを実装します。この手順は、「手順 3b : リソースアダプタのプロパティの実装」で説明します。

手順 3a : リソースアダプタの作成

GenerateAdapterTemplate ユーティリティにより、リソースアダプタクラスの実装に必要な作業のほとんどが行われます。残る作業は、WLIResourceAdapter 実装で定義する各プロパティのセッターおよびゲッターメソッドの実装です。例として、以下にサンプルアダプタの WLIResourceAdapter 実装のリストを紹介します。このコードは、現在アダプタ開発プロジェクトで使用しているコードとほぼ同じです。このプロジェクトで異なる点は、アダプタ論理名やパッケージ名などの識別子に GenerateAdapterTemplate ユーティリティで指定した値が含まれることです。

package sample.spi;

import com.bea.adapter.spi.AbstractWLIResourceAdapter;
import javax.resource.ResourceException;

// リソース アダプタ実装のサンプル

public class ResourceAdapterImpl
    extends AbstractWLIResourceAdapter
{
    // 注意 : ここで示されているクラスで ISuspendableEventGenerator を実装する場合、
    //       AbstractWLIResourceAdapter 実装により、
    //       この WLIResourceAdapter インスタンスの公開がサスペンド可能として処理され、
    //       EventGenerator でのサスペンドおよび再開の呼び出しが処理される

public static String EVENT_GENERATOR_CLASS_NAME =     "sample.event.EventGenerator";

    // サンプル アダプタ固有のメンバー

    private String m_userName = null;
    private String m_password = null;
    private String m_sleepCount = "4000";

    public ResourceAdapterImpl()
        throws ResourceException
    {
        super();

        // AbstractWLIResourceAdapter に使用中の EventGenerator を通知する
        setEventGeneratorClassName(EVENT_GENERATOR_CLASS_NAME);

    // 決して変更しないプロパティを設定する

        setAdapterName("BEA_WLS_SAMPLE_ADK Adapter");
        setAdapterDescription("__BEA_Sample_Description__");
        setAdapterVersion("__MAJOR_V__.__MINOR_V__");
        setAdapterVendorName("__BEA__");

        // 標準のプロパティのデフォルト値を設定する
        setRootLogContext("BEA_WLS_SAMPLE_ADK");

        setLogConfigFile("BEA_WLS_SAMPLE_ADK.xml");
        setMessageBundleBase("BEA_WLS_SAMPLE_ADK");
        setLogLevel("WARN");
    }

    public String getUserName()
    {
        return m_userName;
    }

    public void setUserName(String userName)
    {
        m_userName = userName;
    }

    public String getPassword()
    {
        return m_password;
    }

    public void setPassword(String password)
    {
        m_password = password;
}
    
    public String getSleepCount()
    {
        return m_sleepCount;
    }

    public void setSleepCount(String sleepCount)
    {
        m_sleepCount = sleepCount;
    }

    /**
    * 作業 : 使用するアダプタのプロパティを正しくチェックできるように、
    *       このメソッドを変更する。このメソッドは、ユーザーから ResourceAdapter インスタンスの
    *       有効なコンフィグレーションを強制的に得るためには必須。
    */
    protected void internalValidate()
        throws ResourceException
    {
        if (m_userName == null || m_userName.trim().length() < 1 ||
            m_sleepCount == null || m_sleepCount.trim().length() < 1)
    {
        throw new ResourceException("UserName and SleepCount properties are
            required");
    }

    try
    {
        int sleepCount = Integer.parseInt(m_sleepCount);
        if (sleepCount < 1)
    {
        throw new IllegalArgumentException("sleepCount");
        }
    }
    catch (Exception e)
        {
        throw new ResourceException("SleepCount '" + m_sleepCount + "' is
            invalid");
        }
    }
}

ResourceAdapterImpl のコンストラクタにより、AbstractWLIResourceAdapter 基本クラスから、いくつかのセッターメソッドが呼び出されます。これらのセッターにより、WebLogic Integration で定義された標準プロパティのデフォルト値が設定されます。この標準のプロパティは以下のとおりです。プロパティのロギングの詳細については、「ロギングツールキットの使い方」を参照してください。

EventGeneratorClassName - イベントアダプタのイベントジェネレータを実装するために定義するクラスの名前 (省略可能)。イベントアダプタを実装しない場合は、このプロパティ設定を省略できます。その場合、値はデフォルトの NULL のままにします。
AdapterName - アダプタの表示名
AdapterVersion - 表示するアダプタのバージョン
AdapterVendorName - このアダプタのベンダの名前
RootLogContext - ロギングコンフィグレーション
LogConfigFile - ロギングコンフィグレーション
MessageBundleBase - ロギングコンフィグレーション
LogLevel - ロギングコンフィグレーション

手順 3b : リソースアダプタのプロパティの実装

このように、サンプルアダプタの ResourceAdapterImpl クラスは、シンプルなコンストラクタとセッターおよびゲッターメソッドから構成されており、以下のプロパティを定義します。

これら 3 つのプロパティは、サンプルアダプタでイベント接続をサポートするために使用されます。このため、ResourceAdapterImpl クラスにより、メソッドの setUserName と getUserName の組み合わせ、メソッドの setPassword と getPassword のセット、およびメソッドの setSleepCount と getSleepCount のセットが定義されます。メソッドのこれらの各セットが、1 つのプロパティで使用されます。これらのメソッドでは、整数値が設定されている最小値または最大値を超えていないかの確認や、文字列プロパティが構文規則違反となる最大長を超えていないかの確認など、単純な有効性チェックを実行できます。

ただし、個々のプロパティを同じオブジェクト上の他のプロパティと比較する必要がある場合もあります。個々のセッターおよびゲッターメソッドの場合、プロパティが設定された順序を考慮したり、有効な値が提供されていないプロパティを判断する必要があるため、比較が難しくなることがあります。

このため、WLIResourceAdapter インタフェースにより、WLIResourceAdapter インスタンス上ですべてのプロパティが設定された後に呼び出されるプロパティ検証メソッドを定義します。このメソッドを使用すると、一度にすべてのプロパティの値を検査および検証できます。(WLIResourceAdapter を実装する) AbstractWLIResourceAdapter 基本クラスでは、検証メソッドを定義し、また internalValidate というメソッドを呼び出して、サブクラスで検証プロセスへのフックを実行できるようにします。internalValidate を実装して、すべてのプロパティの有効性をチェックし、無効なプロパティがある場合は ResourceException を送出するようにします。

手順 4 : イベントおよびサービスアダプタの実装

イベントアダプタの開発方法の詳細については、「イベントアダプタの開発」を参照してください。サービスアダプタの開発方法の詳細については、「サービスアダプタの開発」を参照してください。

手順 5 : アダプタのデプロイ

新しいアダプタを再構築したら、そのアダプタを WebLogic Integration 環境にデプロイします。アダプタのデプロイは、手動でも WebLogic Server Administration Console からでも実行できます。詳細については、「アダプタのデプロイ」を参照してください。

アダプタの開発

リソース アダプタの開発

リソース アダプタの概要

実行時環境のリソース アダプタ

手順 1 : アダプタの定義

手順 2 : 開発環境のコンフィグレーション

手順 2a : ファイル構造の設定

手順 2b : アダプタへの論理名の割り当て

手順 2c : ビルド プロセスの設定

手順 2d : メッセージ バンドルの作成

手順 2e : ロギングのコンフィグレーション

イベント生成のロギング カテゴリの作成