プログラミング・ガイド

SALTプラグインの使用

この章には次のトピックが含まれます:

SALTプラグインの理解

SALT GWWSサーバーは構成に基づくプロセスで、ほとんどの基本的なWebサービス・アプリケーションではプログラミングの必要はありません。ただし、カスタム型付きバッファ・データとカスタマイズした共有ライブラリを利用してGWWSサーバーを拡張するプラグイン・インタフェースを開発すると、SALTの機能を拡張できます。

プラグイン・インタフェースは、共有ライブラリによってエクスポートされた一連の機能です。共有ライブラリは、GWWSプロセスから特別な機能を実行するためにロードしたり呼び出したりできます。SALTには、プラグイン・インタフェースを定義して実装するための共通インタフェースとして、プラグイン・フレームワークが用意されています。プラグインを実装するには、実際の関数が含まれている共有ライブラリを使用します。プラグイン実装ライブラリはSALTのデプロイメント・ファイルで設定し、GWWSサーバーの起動中に動的にロードします。

プラグイン要素

プラグイン・インタフェースを定義するには、次の4つのプラグイン要素が必要です。

プラグインID

プラグインID要素は、特定のプラグイン・インタフェース関数を識別するための文字列です。同じような機能に同じプラグインIDを使用して、複数のプラグイン・インタフェースをグループ化できます。プラグインIDの値は、SALTによって事前に定義されています。任意の文字列を定義することはできません。

SALT 10gR3では、プラグインIDとしてP_CUSTOM_TYPEおよびP_CREDENMAPをサポートしています。これは、カスタム型付きバッファ・データを処理するためのプラグイン・インタフェースを定義し、Oracle TuxedoユーザーIDとグループIDをHTTP基本認証が必要とするユーザー名/パスワードにマップするために使用します。

プラグイン名

プラグイン名は、同じプラグインIDカテゴリ内のプラグイン実装を別のプラグイン実装と区別するために使用します。

プラグインIDがP_CUSTOM_TYPEの場合、プラグイン名を使用して実際のカスタム・バッファ・タイプ名を示します。GWWSサーバーがOracle Tuxedoのカスタム・タイプ・バッファとXMLドキュメント間でデータを変換しようとするときに、プラグイン名を主な要素として、適切なプラグイン・インタフェースが検索されます。

プラグイン実装関数

実際のビジネス・ロジックでは、必要な関数をプラグインのvtable構造体に追加する必要があります。必要な関数は、プラグインIDのカテゴリによって異なる場合があります。

P_CREDENMAP IDのカテゴリでは、次の1つの関数を実装する必要があります。

詳細については、「発信認証プラグインのプログラミング」を参照してください。

プラグイン登録関数

プラグイン登録関数は、GWWSサーバーがプラグイン実装を呼び出すことができるようにプラグイン・インタフェースで実装する必要がある、一連の共通関数(またはルール)です。各プラグイン・インタフェースで次の3つの登録関数を実装する必要があります。

情報記載関数

この関数は省略可能です。これを使用すると、GWWSサーバーの起動中、プラグイン共有ライブラリのロード後すぐに呼び出されます。1つのプラグイン・ライブラリに複数のインタフェースを実装する場合、この関数を実装し、ライブラリにインタフェースの数、IDおよび名前を返す必要があります。

0が返された場合は、関数が正常に実行されたことを意味します。0以外の値が返された場合は、実行に失敗したことを意味します。この関数は失敗した場合は、プラグインがロードされなくGWWSサーバーは起動しません。

関数は以下の構文が使用されます。

int _ws_pi_get_Id_and_Names(int * count, char **ids, char **names);

ライブラリ内のcount引数に実装のカウントの総数を返す必要があります。IDsおよびnamesの引数には、「;」セミコロンで区切られているすべての実装されたインタフェースIDsおよびnamesを含む必要があります。

開始関数

開始関数は、プラグイン共有ライブラリに実装されたすべてのインタフェースを決定した後に呼び出されます。データ構造を初期化して、プラグインで使用できるグローバル環境を設定できます。

0が返された場合は、開始関数が正常に実行されたことを意味します。0以外の値が返された場合は、プラグイン・インタフェースの開始に失敗したことを意味します。開始に失敗すると、GWWSサーバーは起動されません。

開始関数の構文は次のとおりです。

int _ws_pi_init_@ID@_@Name@(char * params, void **priv_ptr);

@ID@は、実際のプラグインIDの値です。 @Name@は、実際のプラグイン名です。たとえば、プラグインIDがP_CUSTOM_TYPEでプラグイン名がMyTypeであるプラグインの開始関数は、_ws_pi_init_P_CUSTOM_TYPE_MyType (char * params, void **priv_ptr)です。

終了関数

終了関数は、GWWSサーバーのシャットダウン中、プラグイン共有ライブラリの終了前に呼び出されます。予約されているすべてのプラグイン・リソースを解放する必要があります。

終了関数の構文は次のとおりです。

int _ws_pi_exit_@ID@_@Name@(void * priv);

@ID@は、実際のプラグインIDの値です。 @Name@は、実際のプラグイン名です。たとえば、プラグインIDがP_CUSTOM_TYPEでプラグイン名がMyTypeであるプラグインの終了関数は、_ws_pi_exit_P_CUSTOM_TYPE_MyType(void * priv)です。

vtable設定関数

vtableは、プラグイン・インタフェースの実際のビジネス・ロジックに必要な関数ポインタが格納されるC構造体です。つまり、有効なプラグイン・インタフェースでは、対応するvtableで定義されているすべての関数を実装する必要があります。

vtable設定関数の構文は次のとおりです。

int _ws_pi_set_vtbl_@ID@_@Name@(void * priv);

@ID@は、実際のプラグインIDの値です。 @Name@は、実際のプラグイン名です。たとえば、プラグインIDがP_CUSTOM_TYPEでプラグイン名がMyTypeであるプラグインのvtable設定関数は、_ws_pi_set_vtbl_P_CUSTOM_TYPE_MyType(void * priv)です。

vtable構造体は、プラグインIDのカテゴリによって異なる場合があります。SALT 10gR3リリースでは、P_CUSTOM_TYPE およびP_CREDENMAPが唯一の有効なプラグインIDです。

使用可能なプラグイン・インタフェースのvtable構造体をコード リスト5-1に示します。

struct credmap_vtable {
       int (* gwws_pi_map_http_basic) (char * domain, char * realm, char * t_userid, char * t_grpid, Cred_UserPass * credential); /* used for HTTP Basic Authentication */
       /* for future use */
       void * unused_1;
       void * unused_2;		
       void * unused_3;
};

struct credmap_vtableは、P_CREDENMAPプラグイン・インタフェースに対し1つの関数を実装する必要があることを示します。詳細については、「発信認証プラグインのプログラミング」を参照してください。

関数の入力パラメータvoid * privは、具体的なvtableインスタンスを指しています。vtable設定関数内の実際の関数を使用してvtable構造体を設定する必要があります。

vtable設定関数内の実際の関数を使用してvtable構造体を設定する例をリスト5-2に示します。

int _DLLEXPORT_ _ws_pi_set_vtbl_P_CREDENMAP_TEST (void * vtbl)

{
       struct credmap_vtable * vtable;
       if ( ! vtbl )
              return -1;

       vtable = (struct credmap_vtable *) vtbl;

       vtable->gwws_pi_map_http_basic = Credmap_HTTP_Basic;
       return 0;
}

プラグイン・インタフェースの開発

プラグイン・インタフェースを開発するには、次の手順に従います。

プラグイン共有ライブラリの開発

プラグイン共有ライブラリを開発するには、次の手順に従います。

SALT構成ファイルでのプラグイン・インタフェースの定義

GWWSサーバーがロードするプラグイン共有ライブラリを定義するには、対応するプラグイン・ライブラリのパスをSALTのデプロイメント・ファイルで設定する必要があります。詳細は、『SALT構成ガイド』のSALTデプロイメント・ファイルの作成に関する項を参照してください。

SALTデプロイメント・ファイルでプラグイン情報を定義する例をリスト5-3に示します。

<?xml version="1.0" encoding="UTF-8"?>
<Deployment xmlns="http://www.bea.com/Tuxedo/SALTDEPLOY/2007">
       . . . . . . .
       . . . . . . .
       <System>
              <Plugin>
                     <Interface 
                            id=”P_CREDENMAP”
                            name=”TEST”
                            library=”credmap_plugin.dll” />
              </Plugin>
       </System>
</Deployment>

メッセージ変換プラグインのプログラミング

SALTでは、Oracle TuxedoバッファとSOAPメッセージ・ペイロード間のデータを変換するデフォルト・データ型の変換ルールの完全なセットが定義されています。ただし、デフォルト・データ型の変換ルールによって、SOAPメッセージをOracle Tuxedo型付きバッファに変換(またはその逆)するすべての要件を満たさないことがあります。特定のアプリケーション要件に対応するために、SALTでは、デフォルト・メッセージの変換を拡張するためにカスタマイズされたメッセージ・レベルの変換プラグインの開発をサポートしています。

この項には次のトピックが含まれます:

メッセージ変換プラグインの動作

メッセージ変換プラグインは、SALTがサポートされる1つのプラグインであり、SALTプラグイン・フレームワークで定義されています。すべてのメッセージ変換プラグイン・インスタンスには、「P_CUSTOM_TYPE」と同じプラグインIDがあります。特定の各メッセージ変換プラグイン・インスタンスでは、SOAPメッセージ・ペイロードをOracle Tuxedoバッファに変換する関数およびOracle TuxedoバッファをSOAPメッセージ・ペイロードに変換する関数という2つの関数を実装できます。これらの2つの関数のプロトタイプは、リスト5-4で定義します。

/* custtype_pi_ex.h */
struct custtype_vtable {
       CustomerBuffer * (* soap_in_tuxedo__CUSTBUF) (void * xercesDOMTree, CustomerBuffer * tuxbuf, CustType_Ext * extinfo)
       int (* soap_out_tuxedo__CUSTBUF) (void ** xercesDOMTree, CustomerBuffer * tuxbuf, CustType_Ext * extinfo)
       ......
}

関数のポインタ(* soap_in_tuxedo__CUSTBUF)は、SOAPメッセージ・ペイロードをOracle Tuxedo型付きバッファに変換するカスタマイズされた関数を指しています。

関数のポインタ(* soap_out_tuxedo__CUSTBUF)は、Oracle Tuxedo型付きバッファをSOAPメッセージ・ペイロードに変換するカスタマイズされた関数を指しています。

必要に応じて、メッセージ・プラグインのvtable構造体で定義された両方の関数を実装できます。1つの関数を実装して、他の関数をNULLポインタで設定することもできます。

着信呼出しシナリオでのメッセージ変換プラグインの動作

着信呼出しシナリオは、外部Webサービス・プログラムを示し、SALTゲートウェイを介してOracle Tuxedoサービスを呼び出します。図5-1は、Webサービス・クライアントとOracle Tuxedoドメイン間におけるメッセージの流れを示したものです。

SOAPリクエスト・メッセージをGWWSサーバーに配信する場合、GWWSはターゲット・サービスの入力メッセージの変換に関連付けられたメッセージ変換プラグイン・インスタンスが存在しているかどうかを確認します。関連付けられたインスタンスが存在する場合、GWWSはプラグイン・インスタンスで実装したカスタマイズされた(*soap_in_tuxedo__CUSTBUF)関数を呼び出します。

Oracle Tuxedoレスポンス・バッファがOracle Tuxedoサービスから返された場合、GWWSはターゲット・サービスの出力メッセージの変換に関連付けられたメッセージ変換プラグイン・インスタンスが存在しているかどうかを確認します。関連付けられたインスタンスが存在する場合、GWWSはプラグイン・インスタンスで実装したカスタマイズされた(*soap_out_tuxedo__CUSTBUF)関数を呼び出します。

発信呼出しシナリオでのメッセージ変換プラグインの動作

発信呼出しシナリオは、SALTゲートウェイを介して外部Webサービスを呼び出すOracle Tuxedoプログラムです。図5-2は、Oracle TuxedoドメインとWebサービス・アプリケーション間におけるメッセージの流れを示したものです。

Oracle Tuxedoリクエスト・バッファをGWWSサーバーに配信する場合、GWWSはターゲット・サービスの入力メッセージの変換に関連付けられたメッセージ変換プラグイン・インスタンスが存在しているかどうかを確認します。関連付けられたインスタンスが存在する場合、GWWSはプラグイン・インスタンスで実装したカスタマイズされた(*soap_out_tuxedo__CUSTBUF)関数を呼び出します。

SOAPレスポンス・メッセージが外部Webサービス・アプリケーションから返された場合、GWWSはターゲット・サービスの出力メッセージの変換に関連付けられたメッセージ変換プラグイン・インスタンスが存在しているかどうかを確認します。関連付けられたインスタンスが存在する場合、GWWSはプラグイン・インスタンスで実装したカスタマイズされた(*soap_in_tuxedo__CUSTBUF)関数を呼び出します。

メッセージ変換プラグインの必要性

表5-1には、メッセージ変換プラグインのユース・ケースを示します。

表5-1から、次のメッセージ変換プラグインの一般的なルールが適用されます。

メッセージ変換プラグイン・インスタンスの開発

SOAPメッセージ・ペイロードのOracle Tuxedoバッファへの変換

SOAP XMLペイロードをOracle Tuxedoバッファに変換するには、次の関数を実装する必要があります。

CustomerBuffer * (* soap_in_tuxedo__CUSTBUF) (void * xercesDOM, CustomerBuffer *a, CustType_Ext * extinfo);

形式

#include <custtype_pi_ex.h>

CustomerBuffer * myxml2buffer (void * xercesDOM, CustomerBuffer *a, CustType_Ext * extinfo);

myxml2bufferは任意のカスタマイズした関数名です。

説明

実装した関数では、指定されたXMLバッファを解析して、具体的なデータ項目をOracle Tuxedoカスタム・タイプ・バッファ・インスタンスに変換できる必要があります。

入力パラメータchar * xmlbufは、XML形式のデータ・ストリームを表すNULLで終わる文字列です。XMLデータはカスタム・タイプ・バッファの実際のXMLペイロードであって、SOAPエンベロープ全体でもSOAP本文全体でもありません。

入力パラメータchar * typeは、カスタム・タイプ・バッファのタイプ名です。このパラメータは、GWWSサーバーに必要なカスタム・タイプ・バッファ・ハンドラが現在のプラグイン関数に一致しているかどうかを確認するために使用されます。

出力パラメータCustomerBuffer *aは、割り当てられたカスタム・タイプ・バッファ・インスタンスを格納するために使用されます。Oracle Tuxedoカスタム・タイプ・バッファは、このプラグイン関数からATMI関数tpalloc()を呼び出して割り当てる必要があります。割り当てられたカスタム・タイプ・バッファをプラグイン・コードで解放する必要はありません。使用されていないバッファはGWWSサーバーによって自動的に破棄されます。

診断

この関数は、成功した場合に入力パラメータCustomerBuffer * aのポインタ値を返す必要があります。

リスト5-5に示すように、失敗した場合、この関数はNULLを返します。

CustomerBuffer * myxml2buffer (void * xercesDOM, CustomerBuffer *a, CustType_Ext * extinfo)
{
       // casting the input void * xercesDOM to class DOMDocument object
       DOMDocument * DOMTree = 

       // allocate custom typed buffer via tpalloc
       a->buf = tpalloc("MYTYPE", "MYSUBTYPE", 1024);
       a->len = 1024;

       // fetch data from DOMTree and set it into custom typed buffer
       DOMTree ==> a->buf;
       if ( error ) {
              release ( DOMTree );
              tpfree(a->buf);
              a->buf = NULL;
              a->len = 0;
              return NULL;
       }

       release ( DOMTree );

       return a;
}

Oracle TuxedoバッファのSOAPメッセージ・ペイロードへの変換

カスタム・タイプ・バッファをSOAP XMLペイロードに変換するには、次の関数を実装する必要があります。

int (*soap_out_tuxedo__CUSTBUF)(char ** xmlbuf, CustomerBuffer * a, char * type);

形式

#include <custtype_pi_ex.h>

int * mybuffer2xml (char ** xmlbuf, CustomerBuffer *a, char * type);

"mybuffer2xml"は関数名で、必要に応じて有効な文字列を指定できます。

説明

実装した関数は、指定されたカスタム・タイプ・バッファ・インスタンスをSOAPメッセージで使用するシングル・ルートのXML文書に変換します。

入力パラメータCustomerBuffer *aは、カスタム・タイプ・バッファ応答インスタンスを格納するために使用されます。割り当てられたカスタム・タイプ・バッファをプラグイン・コードで解放する必要はありません。使用されていないバッファはGWWSサーバーによって自動的に破棄されます。

入力パラメータchar * typeは、カスタム・タイプ・バッファのタイプ名です。このパラメータは、SALT GWWSサーバーに必要なカスタム・タイプ・バッファ・ハンドラが現在のプラグイン関数に一致しているかどうかを確認するために使用されます。

出力パラメータchar ** xmlbufは、新しく変換されたXMLペイロードを示すポインタです。XMLペイロード・バッファは、この関数でmalloc ()システムAPIを呼び出して割り当てる必要があります。割り当てられたXMLペイロード・バッファをプラグイン・コードで解放する必要はありません。使用されていないバッファはGWWSサーバーによって自動的に破棄されます。

診断

この関数は、成功した場合に0を返します。

リスト5-6に示すように、失敗した場合、この関数は-1を返す必要があります。

int mybuffer2xml (void ** xercesDom, CustomerBuffer *a, CustType_Ext * extinfo)
{
       // Use DOM implementation to create the xml payload
       DOMTree = CreateDOMTree( );
       
       if ( error )
              return -1;

       // fetch data from custom typed buffer instance,
       // and add data to DOMTree according to the client side needed
       // XML format

       a->buf ==> DOMTree;

       // allocate xmlbuf buffer via malloc
	* xmlbuf = malloc( expected_len(DOMTree) );
       if ( error ) {
              release ( DOMTree );
              return -1;
       }

       // casting the DOMDocument to void * pointer and returned
       DOMTree >> (* xmlbuf);
       if ( error ) {
              release ( DOMTree );
              free ( (* xmlbuf) );
              return -1;
       }

       return 0;
}

SALT 1.1カスタム・バッファ・タイプ変換プラグインの互換性

SALT 1.1カスタム・バッファ・タイプ変換プラグインには、Oracle Tuxedoカスタム・バッファ・タイプにのみに対してカスタマイズしたメッセージ変換を提供します。

表5-2では、SALTメッセージ変換プラグインとSALT 1.1カスタム・バッファ・タイプ変換プラグインを比較しています。

SALT 1.1カスタム・バッファ・タイプのプラグイン共有ライブラリはSALT 10gR3で直接使用できないことに注意してください。SALT 10gR3メッセージ変換プラグインにアップグレードするには、次の作業を実行する必要があります。

発信認証プラグインのプログラミング

Oracle TuxedoクライアントがSOAP/HTTPを介してWebサービスにアクセスする場合、HTTPの基本認証を行うには、クライアントはユーザー名とパスワードをサーバーに送信する必要がある可能性があります。Oracle Tuxedoクライアントは、Oracle Tuxedoドメインに登録する時にtpinit()を使用してユーザー名とパスワードを送信します。ただし、このユーザー名はOracle Tuxedoに使用されるもので、Webサービスに使用されるユーザー名と異なります(パスワードも異なる可能性があります)。

SALTは、ユーザー名のマッピングを可能にするため、Webサービスに送信するユーザー名とパスワードを選択できるプラグイン・インタフェース(資格証明マッピング・インタフェース)を備えています。

発信認証プラグインの動作

Oracle TuxedoクライアントがWebサービスを呼び出す際、実際に呼び出されるのは、WebサービスをOracle Tuxedoサービスとして宣言しているGWWSサーバーです。ユーザーIDおよびグループID (tpusrおよびtpgrpの各ファイルで定義済)がGWWSに送信されます。次にGWWSでは、Webサービスに構成項目<Realm>があるかどうか確認されます。この項目がある場合、GWWSでは次のようになります。

サーバーのHTTP Realmに対してOracle TuxedoユーザーIDをユーザー名およびパスワードにマップするには、vtable gwws_pi_map_http_basic関数の呼出しを試行します。

資格マッピング・インタフェース・プラグインの実装

次のシナリオを使用します。

SALTプラグイン・インタフェースを実装するには、次の手順を実行します。

リスト 5-7に示すように、プラグイン・インタフェースを設定します。

<?xml version="1.0" encoding="UTF-8"?>

<Deployment xmlns="http://www.bea.com/Tuxedo/SALTDEPLOY/2007">
       . . . . . . .
       . . . . . . .
       <System>
              <Plugin>
                     <Interface 
                            id=”P_CREDENMAP”
                            name=”TEST”
                            library=”credmap_plugin.dll” />
              </Plugin>
       </System>
</Deployment>

Oracle TuxedoのUIDおよびHTTPユーザー名のマッピング

HTTP基本認証のユーザー名/パスワードを返すには、次の関数を実装する必要があります。

typedef int (* GWWS_PI_CREDMAP_PASSTEXT) (char * domain, char * realm, char * t_userid, char * t_grpid, Cred_UserPass * credential);

形式

#include <credmap_pi_ex.h>

typedef struct Cred_UserPass_s {

char username[UP_USERNAME_LEN];

char password[UP_PASSWORD_LEN];

} Cred_UserPass;

int gwws_pi_map_http_basic (char * domain, char * realm, char * t_uid, char * t_gid, Cred_UserPass * credential);

「gwws_pi_map_http_basic」は関数名で、必要に応じて有効な文字列を指定できます。

説明

実装した関数は、指定したドメインおよびレルムの指定したOracle Tuxedo uidおよびgidでユーザーを許可するために使用される認可資格証明(ユーザー名およびパスワード)を決定できます。

入力パラメータ(char * domainおよびchar * realm)は、Webサービスが属するドメイン名およびHTTP Realmを表します。適切な資格証明を検索するためのスコープを決定するには、プラグイン・コードでこれらを使用する必要があります。

入力パラメータ(char * t_uidおよびchar * t_gid)は、それぞれOracle TuxedoユーザーIDおよびグループIDの数値を含む文字列です。これらの2つのパラメータは、ユーザー名の検索に使用される場合があります。

出力パラメータ(Cred_UserPass * credential)は、返されたユーザー名/パスワードを格納する事前割当て済のバッファを示すポインタです。プラグイン・コードでバッファを割り当てる必要はありません。

診断

成功した場合、この関数は0を返します。失敗した場合は、リスト5-8に示すように-1を返します。

int Credmap_HTTP_Basic(char * domain, char * realm, char * t_uid, char * t_gid, Cred_UserPass * credential)
{
       // Use domain and realm to determine scope 
       credentialList = FindAllCredentialForDomainAndRealm(domain, realm);
       
       if ( error happens )
              return -1;

       // find appropriate credential in the scope

       foreach cred in credentialList {
              if (t_uid and t_gid match) {
                     *credential = cred;
                     return 0;
              }
       }
       if ( not found and no default credential) {
              return -1;
       }

       *credential = default_credential;
       return 0;
}