Oracle WebLogic ServerでのOracle Joltの使用

WebLogic用のJoltの実装

WebLogicアプリケーションまたはサーブレットからTuxedoに接続するようにJoltを設定するには、次の手順を実行する必要があります。

付録Bには、HTTPサーブレットから接続を確立し、Tuxedoサービスにアクセスする方法を示す単純なサンプル・プログラムがありますので参考にしてください。

パッケージをインポートする

Jolt Javaクラス・パッケージは、Jolt for WebLogic Serverのインストール時に自動的にインストールされます。Oracle Jolt for Oracle WebLogic Serverを使用するには、Joltと共にインストールされた次のクラス・パッケージをサーブレットにインポートします。

bea.jolt.pool.*

bea.jolt.pool.servlet.*

このほかにも、サーブレットにインポートする必要のあるクラスがあります。Javaサーブレットの作成方法については、『WebLogic HTTPサーブレットのプログラミング』ガイドを参照してください。

セッション・プールを構成する

セッション・プールにはSessionPoolManagerクラスからアクセスできます。WebLogic Serverでは、サーブレット・セッション・プールと呼ばれるセッション・プールを使用します。サーブレット・セッション・プールによって、HTTPサーブレット内で使用できる様々な機能を追加することができます。

WebLogic管理コンソールを使用してサーブレット・セッション・プールを構成すると、次の情報がconfig.xml構成ファイルに追加されます。

<StartupClass
ClassName="bea.jolt.pool.servlet.weblogic.PoolManagerStartUp"
FailureIsFatal="false"
Name="MyStartup Class"
Targets="myserver"
/>
<JoltConnectionPool
ApplicationPassword="tuxedo"
MaximumPoolSize="5"
MinimumPoolSize="3"
Name="MyJolt Connection Pool"
PrimaryAddresses="//TUXSERVER:6309"
RecvTimeout="300"
SecurityContextEnabled="true"
Targets="myserver"
UserName="joltuser"
UserPassword="jolttest"
UserRole="clt"
/>

WebLogicを起動(または再起動)すると、PoolManagerStartUpクラスとそれと関連付けられたstartupArgsを呼び出します。最初の呼出し時には、PoolManagerStartUpクラスがServletSessionPoolManagerオブジェクトを作成します。このオブジェクトには、config.xml構成ファイルで構成されたすべてのServletSessionPoolが含まれます。

以降の呼出しでは、同じServletSessionPoolManagerに別のServletSessionPoolが追加されます。前の例に示すように、セッション・プールごとに一意の仮想名をバインディングしてエントリを追加する必要があります。WebLogic Serverは、config.xmlファイルの定義に応じて新しいServletSessionPoolを作成します。

プロパティ設定と定義の一覧については、「Joltスタートアップ・クラスおよび接続プール」を参照してください。

サーブレット・セッション・プールにアクセスする

WebLogic Serverの起動時にJoltセッション・プールを設定するように構成すると、JavaアプリケーションまたはサーブレットからJoltセッション・プールにアクセスして使用することができます。すでに説明したとおり、WebLogic ServerではすべてのServletSessionPoolオブジェクトが同じServletSessionPoolManagerによって管理されます。

  ServletSessionPoolManager poolMgr = (ServletSessionPoolManager) 

    SessionPoolManager.poolmanager;

WebLogic Serverは、SessionPoolManagerから呼び出されたServletSessionPoolManagerクラスを使用します。ServletSessionPoolManagerクラスは、HTTPサーブレット・メソッドを追加するServletSessionPoolオブジェクトを管理します。

SessionPoolManagerは、セッション・プールを管理するためのいくつかのメソッドを提供します。次の例では、SessionPoolManagerを使用して、joltpoolnameという名前のSessionPoolを取得します。

  SessionPool sPool = poolMgr.getSessionPool("joltpoolname");

WebLogic ServerはサブクラスServletSessionPoolManagerを使用するので、上の例では、SessionPoolのかわりに実際にはServletSessionPoolオブジェクトが返されます。

次のサンプル・コードに示すように、SessionPoolをServletSessionPoolにキャストする必要があります。

  ServletSessionPool ssPool =

    (ServletSessionPool) poolMgr.getSessionPool("joltpoolname");

WebLogic ServerはServletSessionPoolManagerを作成して構成するため、ユーザーはこのクラスのみを使用する可能性が高くなります。SessionPoolManagerメソッドを使用すると、管理対象のセッション・プールを個別または全体として作成、中断、停止、またはシャットダウンできます。WebLogic config.xml構成ファイルを使用し、セッション・プールの構成と管理を行うことで、管理オペレーションをWebLogic Serverに委ねることをお薦めします。

サーブレット・セッション・プールを使用する

プール・マネージャから指定したServletSessionPoolへの参照は、TuxedoのJolt Serverに対するセッション(または接続)のプールを表します。このプールのサイズと接続先のTuxedoシステムはアプリケーション・コードから抽出され、WebLogicのconfig.xml構成ファイルで定義されます。リクエストが発行されると、SessionPoolは使用可能な接続で、最も負荷の低い接続を使用します。

Tuxedoサービスを呼び出す

Joltリクエストは、通常SessionPoolのcall()メソッドを使用するTuxedoサービスに対する1つの呼出しで構成されています。Tuxedoサービスに名前を付けて、call()メソッドに一連のパラメータを設定すると、Tuxedoサービスから結果が返されます。1つのトランザクションで複数の呼出しを行うことにより、サーブレットがTuxedoアプリケーションのトランザクション要求に対応したり、データベース間の整合性を維持することができます。このトランザクションの詳細は、「トランザクションを使用する」で説明します。

ServletDataSetを送信する

ServletSessionPoolでは、オーバーロードしたcall()メソッドをHTTPサーブレット内で使用できます。これらのメソッドは、HttpServletRequestオブジェクトによって入力パラメータを受け取るので、HTTPサーブレットのdoPost()またはdoGet()メソッドに渡されたHttpServletRequestオブジェクトと同じオブジェクトを受け取ることができます。ただし、この場合、HTTPでポストされたname=valueの組合せが、Tuxedoサービスが要求する名前と一致している必要があります。これらのデータは最終的にJava Hashtableに変換されるので、名前の順序は識別されません。HttpServletRequestに含まれるその他のデータによってTuxedoサービスが中断されることはありません。

Tuxedoサービスは、次のメソッドを使用してHTTPサーブレットから呼び出されます。

    ssPool.call("serviceName", request);

ここで、ssPoolはServletSessionPoolに対する参照、"serviceName"は呼び出すTuxedoサービスの名前、request引数はサーブレットに関連付けられたHttpServletRequestオブジェクトを示します。

ServletSessionPool.call()メソッドは、HttpServletRequestを内部でServletDataSet (通常のSessionPoolに送信可能)に変換します。

データ・セットにパラメータを追加する

Tuxedoサービスを呼び出す前に、パラメータ・セットにデータを追加することができます。たとえば、リクエストの日時を表すパラメータを追加する必要があるとします。HttpServletRequestのFORMデータからこのパラメータを受信するとは期待しません。そのかわり、サーブレットに追加してから、拡張データセットをTuxedoサービスに送信します。次のサンプル・プログラムでこの手順を説明します。

  // Create a new dataset

  ServletDataSet dataset = new ServletDataSet();

  // Import the HttpServletRequest into the dataset.

  dataset.importRequest(request);

  // Insert an extra parameter into the dataset.

  dataset.setValue("REQUEST_TIME", (new Date()).toString());

  // Send the dataset to the named service.

  ssPool.call("service_name", dataset, null);

このサンプル・コードは、HttpServletRequestオブジェクトをServletDataSetオブジェクトに手動で変換する方法を示しています。この新しい形式では、setValue()メソッドを使用してパラメータを追加することができます。新しい値は、文字列で表されるキーに関連付けられています。次に、SessionPoolから継承されるcall()メソッドが呼び出されます。このメソッドはServletDataSetクラスを受け付けますが、トランザクションで使用するその他の引数を要求します。この最後のパラメータにnullを指定すると、トランザクションを使用して複数のセッション呼出しをグループ化していないことを示します。詳細は、「トランザクションを使用する」を参照してください。

Joltを使用してTuxedoサービスにアクセスする

Joltを使用して既存のTuxedoサービスにアクセスするには、Joltリポジトリでサービスを定義してエクスポートする必要があります。詳細は、『Oracle Joltの使用』の「Joltリポジトリ・エディタの使用」および「Oracle Joltサービスのバルク・ロード」の項を参照してください。Joltサービス定義では、Tuxedoアプリケーション・サービスによって要求されるパラメータを指定します。

Javaのデータ型をTuxedoのデータ型に変換する

次の表に、Javaのデータ型と、Tuxedoサービスで要求されるパラメータの型の対応を示します。DataSetまたはServletDataSetの値には、適切なJavaのデータ型を使用してください。JavaのString型としてパラメータを指定すると、Joltリポジトリのサービス定義に応じて適切なデータ型に自動的に変換されます。

リクエストに関連付けられているすべてのパラメータは文字列形式で表されるので、この機能を使用して、HttpServletRequestオブジェクト内のすべてのデータを変換することもできます。それ以外の場合は、下の表に示すデータ型を使用します。適切なデータ型を使用すると、文字列を変換するためのルックアップが不要になるので、効率が向上します。

TuxedoのCARRAY型は、Java文字列では各バイトが2桁の16進数で表されます。これらの16進数を連結して、複数のバイトを指定します。たとえば、文字列FF0A20は、Tuxedoのデータ型ではCARRAY { 255, 10, 32 }で表されます。

サービスから結果を受信する

ServletSessionPool.call()メソッドは、Tuxedoサービスの結果を含むServletResultオブジェクトを返します。サービス呼出しが失敗すると、例外がスローされます。このような例外を迅速に取得し、適切な処理を行う必要があります。発生する可能性のある例外については、『Oracle Joltの使用』の付録A「Oracle Joltの例外」を参照してください。

次の例では、HTTPサーブレットのServletSessionPool.call()メソッドを使用してServletResultオブジェクトを取得します。

  ServletResult sResult = ssPool.call("service_name", request);

この例では、ssPoolはServletSessionPool、requestはHttpServletRequestになります。

ServletSessionPool.call()メソッドは、Resultオブジェクトを返します。このオブジェクトは、ServletResultオブジェクトとしてキャストする必要があります。ServletResultオブジェクトによって、Java Stringとしてデータを取得するための追加メソッドが提供されます。

呼出しが成功したら、様々な形式のgetValue()メソッドを使用してResultまたはServletResultオブジェクトから個々のパラメータを取り出すことができます。

Result.getValue()メソッドを使用する

Joltリポジトリの定義に応じて、Tuxedoサービスのパラメータに対応するキーを指定することにより、ServletResultからデータが取り出されます。適切なgetValue()メソッドにキーを指定すると、対応する値のオブジェクトが返されます。

また、Result.getValue()メソッドは、キーのルックアップが失敗すると、デフォルト値のオブジェクトを返します。返されたオブジェクトは、Tuxedoサービスの定義に応じて適切なデータ型にキャストする必要があります。たとえば、次のコードでは、

  Integer answer = (Integer) resultSet.getValue("Age", null);

キー"Age"を指定してServletResultで返された値に整数answerを設定するか、ServletResultにこのキーが存在しない場合はnullを返します。TuxedoとJavaのデータ型の対応については、「Javaのデータ型をTuxedoのデータ型に変換する」の表を参照してください。

キーに関連付けられた値の配列を指定することができます。この場合、getValue()メソッドによって、そのインスタンスにある配列の最初の要素が返されます。次のコードでは、

  public Object getValue(String name, int index, Object defVal)

このメソッドのシグネチャを使用して、配列内の特定の索引指定要素を参照します。

ServletResult.getStringValue()メソッドを使用する

ServletResultはResultの機能を拡張し、追加のメソッドを提供します。

  public String getStringValue(String name,

                               int index,

                               String defVal)

  public String getStringValue(String name,

                               String defVal)

これらのメソッドは、ResultクラスのgetValue()メソッドと同様に動作しますが、該当する値のオブジェクトをJava文字列型で返します。CARRAYは、「Javaのデータ型をTuxedoのデータ型に変換する」で説明したように、2桁の10進数の文字列に変換されます。

トランザクションを使用する

トランザクション・オブジェクトを使用して、複数のサービス呼出しを1つのアクションにグループ化し、アプリケーション・ロジック内でデータの整合性を維持することができます。次のメソッドを使用してセッション・プールからトランザクションを取得します。

  Transaction trans = ssPool.startTransaction(timeout);

トランザクション・オブジェクトtransは、トランザクションに対する参照を保持します。ssPoolはSessionPoolまたはServletSessionPoolオブジェクトになり、トランザクションのtimeout引数は秒単位で指定します。

トランザクションによってセッションが取得されると、そのトランザクションがコミットまたは中断されるか、タイムアウトになるまで、ほかのトランザクションはそのセッションを使用できません。ただし、トランザクションには含まれない単独のリクエストによって使用することはできます。トランザクションがプールからセッションを取得できなかった場合、このメソッドはbea.jolt.pool.TransactionExceptionをスローします。セッション・プールが中断されると、メソッドはbea.jolt.pool.SessionPoolExceptionをスローします。

アプリケーションでcall()メソッドを使用するごとに、最後のパラメータでトランザクション・オブジェクトを指定する必要があります。例:

  ssPool.call("svcName", request, trans);

1つのトランザクションで複数の呼出しを行うことができます。この呼出しは、トランザクション・オブジェクトのメソッドを使用してトランザクションをコミットまたはロールバックするまで完了しません。trans.commit()メソッドによってトランザクションが完了します。このメソッドは、コミットが成功した場合は0を返し、失敗した場合はTransactionExceptionをスローします。

トランザクションを中止する必要がある場合は、Transaction.rollback()メソッドを使用します。このメソッドは、トランザクションの中止を試みます。中止に成功した場合は0を返し、失敗した場合はTransactionExceptionをスローします。

例外の処理

JoltによるTuxedoサービスの呼出し開始時にエラーや障害が発生した場合、Javaの例外を使用してアプリケーションに報告されます。常にtry / catchブロックにcall()メソッドを入れ、例外が発生した場合は適切な処理を行う必要があります。call()メソッドがスローする可能性のある例外とその理由を以下に示します。