プログラミング ガイド

Oracle SALT プラグインの使用

この節では、以下のトピックを取り上げます。

Oracle SALT プラグインについて

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

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

プラグイン要素

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

プラグイン ID

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

Oracle SALT 2.0 では、プラグイン ID として P_CUSTOM_TYPE と P_CREDENMAP をサポートしています。これは、カスタム タイプ バッファ データを処理するためのプラグイン インタフェースを定義するために使用します。

プラグイン名

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

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

プラグイン実装関数

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

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

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

プラグイン登録関数

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

情報記載関数

この関数は省略可能。この関数を使用すると、GWWS サーバの起動中、プラグイン共有ライブラリのロード後すぐに呼び出されます。1 つのプラグイン ライブラリに 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 のカテゴリによって異なる場合があります。Oracle SALT 2.0 リリース版では、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); /* HTTP 基本認証のために使用する */
/* 将来に使用する */
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 のデプロイメント ファイルで設定する必要があります。詳細については、『管理ガイド』の「Oracle SALT アプリケーションのコンフィグレーション」を参照してください。

Oracle 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>

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

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

この節では、以下のトピックが含まれています。

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

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

/* 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 メッセージ ペイロードを Tuxedo バッファに変換するカスタマイズした関数を指しています。

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

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

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

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

(ここに図を追加する)

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

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

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

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

(ここに図を追加する)

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

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

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

表 5-1 は、メッセージ変換プラグインの使用例を示します。

上記の表からメッセージ変換プラグインの使用の次の一般なルールを抽象できます。

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

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

SOAP XML ペイロードを 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 バッファを解析して、具体的なデータ項目を Tuxedo カスタム タイプ バッファ インスタンスに変換できなければなりません。

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

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

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

診断

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

失敗した場合は、NULL を返します。

CustomerBuffer * myxml2buffer (void * xercesDOM, CustomerBuffer *a, CustType_Ext * extinfo)
{
	// void * xercesDOM を DOMDocument オブジェクト クラスにキャストする
	DOMDocument * DOMTree = 

	// tpalloc を介してカスタム タイプ バッファを割り当てる
	a->buf = tpalloc("MYTYPE", "MYSUBTYPE", 1024);
	a->len = 1024;

	// DOMTree からデータを取得し、カスタム タイプ バッファに設定する
	DOMTree ==> a->buf;
	if ( error ) {
		release ( DOMTree );
		tpfree(a->buf);
		a->buf = NULL;
		a->len = 0;
		return NULL;
	}

	release ( DOMTree );

	return a;
}

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 を返します。

失敗した場合は -1 を返します。

int mybuffer2xml (void ** xercesDom, CustomerBuffer *a, CustType_Ext * extinfo)
{
	// xml payload を作成するには DOM 実装を使用する
	DOMTree = CreateDOMTree( );
	
	if ( error )
		return -1;

	// カスタム タイプ バッファ インスタンスからデータを取得し、
	// クライアント側で必要な XML 形式によって DOMTree へ
	// 追加する

	a->buf ==> DOMTree;

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

	// DOMDocument を void * ポインタにキャストして返す
	DOMTree >> (* xmlbuf);
	if ( error ) {
		release ( DOMTree );
		free ( (* xmlbuf) );
		return -1;
	}

	return 0;
}

メッセージ変換プラグイン インスタンスの SALT エクスポーズ サービスへの関連付け

今後追加予定

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

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

次の表では、SALT 2.0 メッセージ変換プラグインと SALT 1.1 カスタム バッファ タイプ変換プラグインの比較を示します。

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

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

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

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

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

Tuxedo クライアントは Web サービスを呼び出す時に、実際に Web サービスを Tuxedo サービスとして宣言する GWWS サーバを呼び出します。ユーザ ID とグループ ID (tpusr および tpgrp ファイルで定義されている) は GWWS に送信します。Web サービスで <Realm> コンフィグレーション項目があるかどうかを GWWS によりチェックされます。コンフィグレーション項目が存在する場合、GWWS は次のように動作します。

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

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

Oracle 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>

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」関数名は、必要に応じて有効な文字列で指定できます。

説明

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

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

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

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

診断

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

int Credmap_HTTP_Basic(char * domain, char * realm, char * t_uid, char * t_gid, Cred_UserPass * credential)
{
	// スコープを決定するためにドメインとレルムを使用する 
	credentialList = FindAllCredentialForDomainAndRealm(domain, realm);
	
	if ( error happens )
		return -1;

	// スコープの適切な資格を検索する

	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;
}