目次


IBM Lotus Domino 7 での実用的 Web サービス

単純な Web サービスを作成してテストする

Comments

コンテンツシリーズ

このコンテンツは全#シリーズのパート#です: IBM Lotus Domino 7 での実用的 Web サービス

このシリーズの続きに乞うご期待。

このコンテンツはシリーズの一部分です:IBM Lotus Domino 7 での実用的 Web サービス

このシリーズの続きに乞うご期待。

第 1 回の「Practical Web services in IBM Lotus Domino 7: What are Web services and why are they important?」を読んで、Web サービスが何であるか、なぜ重要なのかを十分に理解したところで、今度は Web サービスを作成してみようという気分になりましたか。IBM Lotus Domino V7.0 の登場によって、他のクライアントやシステムが利用できる独自の Web サービスをごく簡単に作成できるようになっています。ある意味、これはエージェントを作成するくらいに簡単です。

IBM Lotus Domino Designer では、LotusScript または Java のいずれかを使用して Web サービスを作成できますが、この記事の例はすべて LotusScript で作成しています。ただし、この記事に使用できるサンプル・データベース (「ダウンロード」セクションを参照) では、参考として LotusScript と Java の両方で作成したサンプル Web サービスを使用しています。

背景の概略

Lotus Domino V7.0 は、Lotus Domino Designer に新しい Web サービス設計要素を導入しています。Lotus Domino Designer V7.0 クライアントでデータベースを開くと、設計要素ツリーの Shared Code セクションに表示されたおなじみの Agents エントリーの下に、Web Services というエントリーがあることがわかります (図 1 を参照)。

WSDL の作成と SOAP の処理は Lotus Domino がユーザーに代わって行ってくれるので、必要な作業は、エージェントをコーディングするのと同じように Web サービス設計要素にコードを書き込むことだけです。サービスのインターフェース・クラスとして使用するクラスを指定さえすれば、あとは Lotus Domino が WSDL ファイルを公開し、受信した SOAP 要求を指定されたクラスでのメソッド呼び出しに変換し、そしてメソッドの結果 (該当する場合) を SOAP 応答として返してくれます。

コーディングの点で言うと、必要なのは LotusScript または Java クラスの作成だけです。あとのことはすべて、Lotus Domino が引き受けてくれます。

単純な Web サービスを作成する

それでは、簡単な Web サービスを作成してみましょう。新しい Web サービスを作成するには、Lotus Domino Designer でデータベースを開き、データベース設計の Web Services セクションに移動して New Web Service ボタンをクリックします (図 1 を参照)。

図 1. Lotus Domino Designer の Web Service 設計要素セクション
Lotus Domino Designer の Web Service 設計要素セクション
Lotus Domino Designer の Web Service 設計要素セクション

新しいエージェントを開くときに表示されるウィンドウとよく似た画面が開きます (図 2 を参照)。Web Services のプロパティー・ボックスで、新しい Web サービスに名前を付け (この例では、EchoTestService という名前を使用します)、ボックスを閉じます。プロパティー・ボックスの各フィールドについては後で説明します。

図 2. Lotus Domino Designer の Web Service 設計要素
Lotus Domino Designer の Web Service 設計要素
Lotus Domino Designer の Web Service 設計要素

LotusScript エージェントを作成するときと非常によく似た画面が表示されているはずです。クラスを作成するには、LotusScript イベントの Objects タブに表示された (Declarations) をクリックします (クラスは常に、(Declarations) セクションで定義します)。IDE に、以下のコードを入力してください。

リスト 1. ストリングをエコーする極めて単純な Web サービス
Class EchoTest
	Public Function Echo (txt As String) As String
		Echo = txt
	End Function
End Class

このコードの内容は以下のとおりです。

  • EchoTest というクラスを作成します。
  • クラスに Echo というメソッドを定義します。このメソッドは、ストリングをパラメーターとして受け取り、結果としてストリングを返します (クラスに含まれる関数とサブ関数はメソッドと呼ばれます)。

EchoTest の Echo メソッドはストリングをパラメーターとして使い、同じストリングを返します。ここで、この Web サービスが有効かどうかを調べてみましょう。Web サービスを保管して閉じてみてください。すると、以下のエラーを受信します。

The Web Service has been saved, but is not valid: 
Please specify which class exposes your Web service interface(s), 
using the 'PortType class' field of the Web Service properties panel.

このエラーが発生しないようにするには、Web Service のプロパティー・ボックスを開いて、使用するクラスを指定します。Web サービスのコードには複数のクラスを定義できるので、そのうちの 1 つだけを Web サービスへのインターフェースとして選択する必要があります。インターフェース・クラスとは、Web サービス・クライアントが呼び出せる public メソッドを持つクラスのことです。

プロパティー・ボックスで、最初のタブにある PortType クラスに EchoTest (前述の手順で作成したクラスの名前) と入力します。ボックスを閉じて、Web サービスをもう一度保管して閉じてみてください。今度はうまくいくはずです。これで、有効な Web サービスになりました。

Web Service のプロパティー・ボックス

もう一度、Web サービスと Web Service のプロパティー・ボックスの両方を開いてください。ボックスの最初のタブ (基本タブ) は、図 3 のように表示されます。

図 3. Web Service プロパティー・ボックスの基本タブ
Web Service プロパティー・ボックスの基本タブ
Web Service プロパティー・ボックスの基本タブ

基本タブには、以下のフィールドがあります。

  • Name (必須)。これは Web サービスの名前で、クライアントが Web サービスの WSDL ファイルやメソッドにアクセスするときに使用します。
  • Alias。Name とは別に、ユーザーがサービスにアクセスするときに使用できるもう 1 つの名前です。
  • Comment。Web サービスに関する単なる情報用のフィールドです (通常、このフィールドに入力する情報は 1 つのセンテンスだけです。Web サービスについての長い説明文や情報は、コードのコメントに書き込む必要があります)。
  • Warn if the WSDL interface is modified。このオプションは、コードに加えた変更が Web サービスによって作成される WSDL ファイルに影響する場合に警告します。WSDL ファイルの一貫性を確実にするには役立ちますが、このオプションが選択されていると、変更された WSDL ファイルでサービスを保管できなくなるので注意してください。
  • PortType class (必須)。Web サービス・インターフェースとして使用するクラスの名前です。つまり、ユーザーがアクセス可能な public メソッドを持つ Web サービス・コード内のクラスです。

ボックスの 2 番目のタブはセキュリティー・タブです (図 4 を参照)。

図 4. Web Service プロパティー・ボックスのセキュリティー・タブ
Web Service プロパティー・ボックスのセキュリティー・タブ
Web Service プロパティー・ボックスのセキュリティー・タブ

セキュリティー・タブには、以下のフィールドがあります。

  • Run as web user。このオプションを有効にすると、Web サービスを呼び出したユーザーのセキュリティー・コンテキストにおいて Web サービス・コードが実行されます (デフォルトでは、Lotus Domino Designer で最後に Web サービスにサインインした ID のセキュリティー・コンテキストにおいて、Web サービス・コードが実行されます)。
  • Run on behalf of。Lotus Domino Designer で最後に Web サービスにサインインした ID ではなく、特定ユーザーのセキュリティー・コンテキストにおいて Web サービス・コードを実行する場合、このフィールドにそのユーザーを指定します。
  • Allow remote debugging。このオプションは、Web サービスのリモート・デバッグを有効にします (リモート・デバッグについては、Lotus Domino Designer のヘルプ・トピック「Using the Remote Debugger」を参照してください)。
  • Profile this web service。このオプションを有効にすると、Web サービスが実行時にプロファイル情報を生成します (プロファイルについては、Lotus Domino Designer のヘルプ・トピック「Profiling agents and Web services」を参照してください)。
  • Set runtime security level。1 を設定すると、ほとんどの LotusScript および Java 操作が適切に実行されます。ファイルの読み取り/書き込み操作、COM オブジェクトの作成操作、またはネットワーク操作などを実行する場合は、2 または 3 を設定する必要があります (詳細は、Lotus Domino Designer のヘルプ・トピック「Restricted LotusScript and Java agent operations」を参照してください)。
  • Default access for this web service。このオプションを使用して、データベース ACL による制御に関わらず、Web サービスにアクセス可能なユーザーを管理できます (匿名ユーザーの Web サービスへのアクセスが禁止されている場合、匿名ユーザーが接続しようとすると 401 Access Denied または 404 Not Found のエラーを受信します)。
  • Allow Public Access users to use this web service。このオプションを有効にすると、データベース ACL での「Read Public Documents (公開文書の読み取り)」アクセス権のみを持つユーザーが、この Web サービスを使用できるようになります。多数のユーザーに完全な読み取りアクセス (またはそれ以上) を与えたくない場合に便利です。

ボックスの 3 番目のタブはオプション・タブです (図 5 を参照)。

図 5. Web Service プロパティー・ボックスのオプション・タブ
Web Service プロパティー・ボックスのオプション・タブ
Web Service プロパティー・ボックスのオプション・タブ

オプション・タブには、以下のフィールドがあります。

  • Programming model。RPC または Message を選択できます (ほとんどの場合は RPC を使用します)。
  • SOAP message format。このフィールドでは、この Web サービスの SOAP メッセージ形式を選択できます (メッセージ形式についての詳細は、次のセクションを参照してください)。Lotus Domino V7.0 でのデフォルト形式は、RPC/encoded (RPC/エンコード形式) です。
  • Include operation name in SOAP action。このオプションを有効にすると、受信する要求の SOAP アクション・ヘッダー内に操作名が含まれることが条件となります (絶対とは言えないまでも、操作名が必要になることはめったにありません)。
  • Port type name。デフォルトでは、このフィールドには、基本タブの PortType class フィールドに指定した値が設定されます (ただし、必要に応じて名前を変更できます)。WSDL ファイルを生成するときに使用される名前です。
  • Service element name。デフォルトでは、このフィールドには、ポート・タイプ名に Service が追加された値が設定されます (ただし、必要に応じて名前を変更できます)。WSDL ファイルを生成するときに使用される名前です。
  • Service port name。デフォルトでは、このフィールドの値は Domino に設定されますが、必要に応じて名前を変更できます。WSDL ファイルを生成するときに使用される名前です。

以上のように、設定可能なプロパティーはたくさんありますが、必須プロパティーは Web サービス名とポート・タイプ・クラスだけです。その他はオプション・プロパティー、または適切なデフォルト値が設定されたプロパティーのいずれかです。

SOAP メッセージ形式

Web Service のプロパティー・ボックスでは、さまざまな SOAP メッセージ形式を選択できるので、使用する形式を決めかねるかもしれません。形式によって作成される WSDL ファイルが多少異なってくるため、SOAP 要求と応答にも多少の影響があります。

コーディングの点からすると、形式による違いは何もありません。使用する形式が何であれ、作成する Web サービスはまったく同じでだからです。一方、Web サービスを呼び出すユーザー・クライアントにとっては、形式によって違いが出てきます。

一般的に、Apache SOAP や MSSOAP などの歴史の長い Web クライアント技術では、RPC/エンコード形式のほうが普及しています。Doc/リテラル形式は、Microsoft .NET クライアントおよびサーバーがデフォルトで使用する形式で、ここ数年間で人気が高まっています。

メッセージ形式は、サービスを呼び出すクライアント側で使用している技術と、そのクライアントの技術でもっとも使いやすい SOAP 形式を基準に選択してください。サービスを呼び出すクライアントに対して何のコントロールも利かない場合は、RPC/エンコード形式と Doc/リテラル形式の両方が賢い選択肢となります。

形式の違いによって WSDL 構造と SOAP メッセージにどのような影響があるかについては、度々引用されている developerWorks の記事「Which style of WSDL should I use?」にわかりやすい説明があるので、参照してください。

単純なデータ型を使用した Web サービス・クラス

話を Web サービス・コードの作成に戻しましょう。ご存知のとおり、Web サービスとして公開する LotusScript コードはクラスとして作成しなければなりません。実質的には、LotusScript で通常作成するあらゆる関数とサブ関数が Web サービスでクラス・メソッドとして機能しますが、以下の制限事項があります。

  • 固有の LotusScript クラス (NotesDatabase、NotesDocument など) をパラメーターや戻り値として使用しないこと。
  • バリアント型または通貨のデータ型をパラメーターや戻り値として使用しないこと。
  • リストまたは配列をパラメーターや戻り値として使用しないこと (配列は可能ですが、この記事の後半で説明する特殊なデータ型を使用する必要があります)。
  • カスタム・タイプをパラメーターや戻り値として使用しないこと

逆に、Web サービスのクラス・メソッドでは、以下をパラメーターまたは戻り値として使用できます。

  • 単純なデータ型 (ストリング、整数など)
  • カスタム・ユーザー定義クラス
  • lsxsd.lss ファイルで定義された特殊クラス (Lotus Notes/Domino V7.0 クライアントおよびサーバー・ファイルに含まれています。)

ユーザー定義クラスは複合データ型として現れますが、これについては次回の記事で説明します。lsxsd.lss ファイル (ローカル Notes プログラム・ディレクトリーにあります) に含まれるクラスは非常に便利で、これらのクラスを使用してストリング配列、ファイル、日付を渡すことができます。この記事では後で、このクラスをいくつか抜粋して説明し、残りについては次回の記事で説明します。

ここで、クラスで単純なデータ型を使用する例を紹介します。以下のクラスを見てください。

リスト 2. 複数のメソッドを使った LotusScript Web サービス
Class DatabaseInfo
	Private session As NotesSession
	Private db As NotesDatabase
	
	Public Sub New ()
		Set session = New NotesSession
		Set db = session.CurrentDatabase
	End Sub
	
	Public Function GetDbName () As String
		GetDbName = db.Title
	End Function
	
	Public Sub UpdateFTIndex ()
		Call db.UpdateFTIndex(True)
	End Sub
	
	Public Function GetUserRoles (userName As String) As String
		GetUserRoles = Join(getRoles(userName), ",")
	End Function
	
	Private Function getRoles (userName As String) As Variant
		Dim acl As NotesACL
		Dim entry As NotesACLEntry
		Dim sep As String
		
		Set acl = db.ACL
		Set entry = acl.GetEntry(userName)
		
		If (entry Is Nothing) Then
			Dim returnArray(0) As String
			getRoles = returnArray
		Else
			getRoles = entry.Roles
		End If
	End Function
End Class

上記のコードは単純なものですが、以下のさまざまなメソッドに注目してください。

  • New。New メソッドはオプションで、Web サービスを呼び出すクライアントでは使用できません。これは単なる初期化コードで、必要に応じて使用されます。また、New メソッドを書き込む場合は、サブ関数として作成し、パラメーターは一切使用しないでください。
  • GetDbName。GetDbName メソッドはパラメーターを使用しません。これは決まりです。
  • UpdateFTIndex。UpdateFTIndex メソッドはパラメーターを使用することも、値を返すこともありません。これも決まりです。
  • GetUserRoles。GetUserRoles メソッドは別のメソッドを呼び出して作業のほとんどを行います。別の (クラスの外にある) 関数やサブ関数を呼び出すことも可能で、Use ステートメントで参照するスクリプト・ライブラリーからクラス、関数、サブ関数を呼び出すこともできます。このメソッドは Web サービス・コードを簡潔に保つだけでなく、Web サービス・コードを既存のビジネス・ロジック・コードと区別するのに役立つため、非常に便利です。
  • getRoles。getRoles メソッドは Private として宣言されているため、クラス内のその他のメソッドが使用することはできますが、Web サービスを呼び出すクライアントでは使用できません。メソッドを Private として宣言すると、コードとロジックをクラス内に維持すると同時に、ユーザーが直接呼び出せないようにすることができます。

    メソッドが Public または Private のいずれとしても宣言されていない場合は、Public メソッドとして使用されることに注意してください。

ここまでのところは、何も複雑な点はありません。ユーザーが呼び出すことのできる関数/サブ関数を決め、メソッドとしてクラス内にラップするだけです。必要なコードまたはロジックがすでに作成されている場合は、スクリプト・ライブラリーから他のクラス、関数、サブクラスを参照することもできます。

配列を返す

お気付きかもしれませんが、GetUserRoles メソッドは値を返す前に、getRoles メソッドが返すストリングの配列を区切り文字で区切った単一のストリングに変換しています。これは、LotusScript 配列は配列としても変数としても、Web サービスから直接戻せないためです。

ただし、lsxsd.lss ファイルのいずれかの ARRAY_HOLDER クラスのインスタンスを返すことによって配列を返すことができます。ARRAY_HOLDER クラス (STRINGARRAY_HOLDER、INTEGERARRAY_HOLDER など) は、値として戻されるときに自動的に SOAP が扱いやすい配列に変換されます。

その一例として、Web サービスの (Options) セクションに %INCLUDE "lsxsd.lss" という行を追加して、GetUserRoles メソッドを以下のように書き換えます。

リスト 3. LotusScript Web サービスで返すストリング配列
	Public Function GetUserRolesArray (userName As String) As STRINGARRAY_HOLDER
		Dim returnArray As New STRINGARRAY_HOLDER
		Dim roles As Variant
		Dim i As Integer
		
		roles = getRoles(userName)
		Redim returnArray.Value(Ubound(roles))
		For i = 0 To Ubound(roles)
			returnArray.Value(i) = roles(i)
		Next
		
		Set GetUserRolesArray = returnArray
	End Function

ユーザーのクライアントが接続されている限り、GetUserRolesArray メソッドは特殊な STRINGARRAY_HOLDER オブジェクトではなく、通常のストリング配列を返します。これは、Domino Web サービスがアクセス時に STRINGARRAY_HOLDER とストリング配列の変換をバックグラウンドで行うためです。getRoles 配列の要素を STRINGARRAY_HOLDER の Value メンバーに追加するには多少の追加作業が必要になりますが (Value をそのまま他の配列と同等に設定することはできないため)、この作業はわずか数行のコードに過ぎません。

もちろん、受け渡しできる配列の種類はストリング配列だけではありません。lsxsd.lss ファイルに定義された INTEGERARRAY_HOLDER、LONGARRAY_HOLDER などのクラスは、その他の固有データ型を対象として同じ機能を提供します。詳細は、Lotus Domino Designer のヘルプまたは lsxsd.lss ファイルを参照してください。

配列を返すためのもう 1 つのオプションは、配列を複合データ型の一部として返すことです。この手法については、次回の記事で説明します。

InOut パラメーターで複数の値を返す

単純なデータ型だけを操作する場合に使用できる手法には、InOut パラメーターもあります。InOut パラメーターでは、入力用の値を受け取ったり、出力用の値を返すことができます。例えば、以下のクラスを見てください。

リスト 4. LotusScript Web サービスでの InOut パラメーターの使用
Class InOutTest
	Public Sub AddOne (inout As INTEGER_HOLDER)
		inout.Value = inout.Value + 1
	End Sub
	
	Public Function SwapAndAdd (inout1 As INTEGER_HOLDER, _
	inout2 As INTEGER_HOLDER) As Integer
		SwapAndAdd = inout1.Value + inout2.Value
		inout1.Value = inout2.Value
		inout2.Value = SwapAndAdd - inout2.Value
	End Function
End Class

最初のメソッド (AddOne) は、整数を入力パラメーターとして使用します。このメソッドのコードは渡された値に 1 を加算し (渡された INTEGER_HOLDER であるため)、新しい値を SOAP 応答で返します。

このメソッドは、lsxsd.lss ファイルに定義された HOLDER クラスの特別なプロパティーです。メソッド・パラメーターとして使用されると、SOAP 要求/応答の InOut パラメーターとなって値の送受信を行います。

普段は通常の整数をパラメーターとして受け取り、変更された整数を返す関数としてメソッドを作成するため、AddOne メソッドはあまり実際的な例とは言えません。ただし、1 つ以上の InOut パラメーターと 1 つのメソッド戻り値がある場合、メソッドの応答で 1 つの値だけでなく、複数の別個の値を返すことができます。

次に、2 番目のメソッド SwapAndAdd を見てください。このメソッドはパラメーターとして 2 つの InOut 値を持ち、整数を返します。ユーザーのクライアントでは、2 つの整数値をパラメーターとして送信する SOAP 要求を作成し、応答に 3 つの整数値が含まれる SOAP 応答を受け取ります。この 3 つの値とは、パラメーターとして渡された 2 つの値 (メソッドによって変更済み) と結果です。

複数の値を返す場合には通常、複合データ型が使用されるため、InOut パラメーターを見かけることはあまりありませんが、これは頭に入れておく価値のある手法です。繰り返しますが、複合データ型については次回の記事で説明します。

日付と時刻を操作する

操作対象となる可能性がある単純なデータ型として最後に取り上げるのは、日付/時刻オブジェクトです。以下に、パラメーターと戻りオブジェクトで日付/時刻の値を使用する例を示します。

リスト 5. LotusScript Web サービスで使用されている日付と時刻
Class DateTester
	Public Function getCurrentTime () As XSD_DATETIME
		Dim dt As New NotesDateTime(Now)
		Set getCurrentTime = New XSD_DATETIME
		Call getCurrentTime.SetValueFromNotesDateTime(dt)
	End Function
 	
	Public Function getLocalDateFormat (xdt As XSD_DATETIME) As String
		Dim dt As NotesDateTime
		Set dt = xdt.GetValueAsNotesDateTime()
		getLocalDateFormat = dt.LocalTime
	End Function
End Class

ここでもまた、lsxsd.lss クラスのおかげで、XSD_DATETIME 型の変数 (SOAP dateTime 要素になります) の受け渡し、NotesDateTime オブジェクトとの変換が単純になっています。

ただし、サーバーとクライアントが SOAP dateTime 要素のタイム・ゾーン・オフセットを適切に追加、あるいは解釈するかどうかによっては、時刻値のタイム・ゾーンの扱いが問題になる場合があります。この問題のいくつかの側面については、最近の W3C Note で取り上げています。いつものことながら、まずは Web サービス・クライアントで十分にテストする必要があります。

Web サービスをテストする

Web サービスの作成が完了したら、必ずそのサービスをテストしてください。Web サービスの WSDL にアクセスするには、Web サービスの完全 URL パスの最後に ?WSDL URL コマンドを追加します。

例えば、サーバーのデータベース名が WSTest.nsf、DNS 名が mydomino.example.com、そしてWeb サービス名が MyNewWebService の場合には、以下の URL を使用します。

http://mydomino.example.com/WSTest.nsf/MyNewWebService?WSDL

テストに使用できる Web サービス・テスト・ツールは無料、商用を含めて数多くあるため、各種のテスト方法について説明すると長々とした記事やチュートリアルになってしまいます。

以下に、Web サービスをテストして呼び出すために使用できる無料のツールのそれぞれについて簡単に説明します。各ツールの詳細については、読者が調べる宿題として残しておきます。

soapUI

Web サービスのテストに使いやすいツールの 1 つとして挙げられるのは、soapUI Web サイトから入手できる soapUI です。soapUI は Java で作成された無料のデスクトップ・プログラムで、各種のオペレーティング・システムで実行できます。これを使って Web サービスをテストする手順は、以下のとおりです。

  1. Java 1.5 以降が正しくローカル・マシンにインストールされていることを確認します。
  2. soapUI プログラムをダウンロードして、ファイルを unzip します。
  3. unzip したファイルの /bin ディレクトリーで、soapui.bat ファイル (Windows マシンの場合) または soapui.sh ファイル (その他のオペレーティング・システムの場合) を実行して soapUI を開きます。
  4. File - New WSDL Project を選択し、プロンプトが表示されたらプロジェクトの名前を入力します。
  5. 左側ナビゲーターのプロジェクト・リストに表示された新規プロジェクトを右クリックし、「Add WSDL From URL」オプションを選択します。
  6. テスト対象サービスの URL (例えば、http://localhost/DWSTest.nsf/EchoTestService?WSDL) を入力し、すべての操作のデフォルト要求を作成するかどうかを尋ねるプロンプトが表示されたら、Yes をクリックします。
  7. 左側の新規プロジェクトを完全に展開して、呼び出しが可能な各 Web サービス・メソッドのエントリーを表示します。メソッド名の下にある Request エントリーをダブルクリックすると、事前作成された SOAP 要求が表示されます。これをテストとして送信できます (図 6 を参照)。
    図 6. soapUI インターフェース
    soapUI インターフェース
    soapUI インターフェース
  8. 図 6 に表示された EchoTest サービスには、送信用の単純な SOAP 要求が作成されています。サービスをテストするには、要求エンベロープの <TXT> ノードにテキストを入力し、SOAP 要求テキストの真上にあるツールバーで緑色の矢印ボタンをクリックします。これによって、要求がサービスに送信され、この要求に対する SOAP 応答が右側のペインに表示されます。

SoapUI では、Web サービスのユニット・テストに適したテスト・スイートを作成できます。一連のテストを作成しておけば、Web サービスに変更を加えるごとに事前作成したテストを実行して、すべてが適切に機能することを確認できます。

マイナス面としては、作業はすべて未処理の XML SOAP 要求および応答で行わなければならないということです。XML と SOAP を扱い慣れていれば、骨の折れる部分 (最初の SOAP 要求の作成) はプログラムに任せて SOAP 応答の正確な表示を見ることができるので、これが難点になることはありません。ですが、それよりも抽象的なレベルで作業したい場合 (プログラム内で単純な API や関数呼び出しを使用するなど) は、このツールのレベルは低すぎるかもしれません。

Eclipse と WTP (Web Tools Platform)

Eclipse がインストールされている場合 (または、Eclipse を使う言い訳をしたい場合)、WTP (Web Tools Platform) という非常に優れたパッケージがあります。このパッケージでは、より高いレベルのインターフェースを使用して Web サービスをテストできます。WTP では Web サービスのメソッドごとにフォームを作成するため、未処理の SOAP 要求を操作する代わりに、このフォームに値を入力するだけで要求を送信できます。

WTP をインストールして使用するための基本手順は、以下のとおりです。

  1. Eclipse プラットフォームをダウンロードしてインストールします。
  2. WTP コンポーネントをインストールします。Eclipse 3.2 より前のバージョンについては、WTP Web サイトのインストール手順を参照してください。Eclipse 3.2 以降については、「Web and J2EE Development」セクションにある Callisto ツールキットの一部としてインストール手順が記載されています。以下の手順に従ってください。
    1. Help - Software Updates - Find and Install を選択します。
    2. 次の画面で「Search for new features to install」を選択し、Next をクリックします。
    3. Callisto Discovery Site オプションが選択されていることを確認してから、Next をクリックします。
    4. インストール・パッケージのリストに表示された Callisto Discovery Site セクションの下にある「Web and J2EE Development」項目を選択します (これにより「Web and J2EE Development」の下にある項目もすべて選択されます)。次に、その他の必要なコンポーネントをすべて取得するために Select Required ボタンをクリックし、Next をクリックしてインストールします (図 7 を参照)。インストールには数分かかります。

      図 7. Eclipse での WST パッケージのインストール
      WST package installation in Eclipse
      WST package installation in Eclipse
  3. インストールが完了したら、Eclipse を再起動します。メインの Workbench ページで、Run - Launch the Web Services Explorer を選択します。
  4. Web Services Explorer ビューで WSDL Page ボタンをクリックすると、WSDL Main が Navigator ペインに追加されます (図 8 を参照)。
    図 8. WST の WSDL Explorer
    WST の WSDL Explorer
    WST の WSDL Explorer
  5. Actions ペインには WSDL パスを入力できます。テスト対象サービスの URL (例えば、http://localhost/DWSTest.nsf/EchoTestService?WSDL) を入力し、Go ボタンをクリックします。
  6. WSDL ファイルが見つかると、Navigator ペインの WSDL Main 項目の下にツリー構造が表示され、Web サービス内のすべてのメソッドがリストされます。
  7. WSDL ツリーにあるいずれかのメソッド名をダブルクリックすると、Actions ペインにフォームが表示されます。このフォームでメソッドの各パラメーターの値を入力し、Web サービスに送信します。応答は、下部の Status ペインに表示されます (図 9 を参照)。
    図 9. WST での SOAP 応答
    WST での SOAP 応答
    WST での SOAP 応答
  8. 送信した未処理の XML SOAP メッセージとWeb サービス呼び出しが受け取った未処理の XML SOAP メッセージを表示するには、Status ペインの Source リンクをクリックします。

soapUI ツールに比べ、Eclipse WTP の初期セットアップは複雑ですが、インターフェース (未処理の要求ではなくフォーム) の使いやすさは優れています。下位レベルの詳細が必要な場合には送受信された未処理のメッセージを確認することもできますが、フォームに基づいて要求を作成して送信するほうが簡単だと結論する人もいます。

MSSOAP ツールキット

Windows プラットフォームを使用する多くの LotusScript プログラマーは、MSSOAP ツールキットを使った Web サービスの呼び出しに成功しています。MSSOAP ツールキットのサポートや更新は Microsoft ではもう行っていませんが (Microsoft .NET フレームワークに代替されています)、非常に普及している手法なので紹介しておきます。

MSSOAP は DLL ファイルで、Microsoft からダウンロードできます。あるいは、標準 Windows システムの一部としてワークステーションにすでに組み込まれている場合もあります。この DLL を COM オブジェクトとして呼び出すには、以下のような LotusScript を使います。

リスト 6. LotusScript からの単純な MSSOP 呼び出し
Dim Client As Variant
Set Client = CreateObject("MSSOAP.SoapClient")
Call Client.MSSoapInit("http://localhost/DWSTest.nsf/EchoTestService?WSDL")
Print "Echo said " & Client.Echo("echo")

明らかに、Web サービスに含まれるメソッドと、使用するパラメーターおよびデータ型についてのある程度の知識が必要になります。別の Web サービスを呼び出す場合は、WSDL ファイルを手動で読み取って解釈するか (やっかいな作業になりますが)、あるいは soapUI や the Eclipse WTP などのツールを使用してすべて変換させることができます。

残念ながら、Windows マシンでの一般的な MSSOP のバージョンは 1.x で、これは単純なデータ型をパラメーターとして使用する RPC/エンコード形式の Web サービスでしか有効に機能しません。通常戻される複合データ型は IXMLDOMNodeList オブジェクトですが、複合データ型をパラメーターとして渡すには新しい IXMLDOMNodeList オブジェクトを作成する必要があり、この作業がネックとなる場合があります。また、MSSOAP 1.x は通常、列挙型を使用する Web サービスを解釈することができません (次回の記事で説明する話題です)。

MSSOAP ライブラリーを使用するサーバーまたはワークステーションを管理できる場合は、各種の Web サービスを呼び出せる SOAP Toolkit バージョン 3.0 をダウンロードしてインストールするという選択肢があります。このツールキットをインストールした後、上記のコードを CreateObject("MSSOAP.SoapClient") から CreateObject("MSSOAP.SoapClient30") に変更すると、新しいバージョンのライブラリーを使用できるようになります。表 1 に、この 2 つのバージョンの違いをリストします。

表 1. MSSOAP 1.x と 3.0 の相違点
MSSOAP 1.xMSSOAP 3.0
ほとんどの Windows XP/2000 マシンでのデフォルトダウンロードおよびインストールが必要
CreateObject("MSSOAP.SoapClient")CreateObject("MSSOAP.SoapClient30")
RPC/エンコード形式の Web サービスのみRPC/エンコード形式、RPC/リテラル形式、Doc/リテラル形式、ラップ形式
列挙型は解釈されないLotusScript Web サービスからの列挙型には対応。だたし、Java Web サービスから戻される列挙型は正しく解釈されない場合がある

MSSOAP では、Web サービスの動的呼び出しが可能で (便利な場合があります)、MSSOAP を使用するための多数のコード・サンプル (LotusScript と、LotusScript に簡単に変換できる Visual Basic の両方で作成されたサンプル) が用意されているため、Web サービスを Windows マシンから呼び出す場合には絶好のオプションとして使用できます。

Apache Axis

Lotus Notes 環境では、Apache Axis フレームワークも Web サービスを呼び出すオプションとして見逃せません。Axis は、長年さまざまなプラットフォームで Web サービスを作成、提供、そして利用するために用いられている非常に完成度の高い Java パッケージです。実際、Lotus Domino V7 では Axis のバージョンを基礎技術として Web サービスを提供しています。

Axis で Web サービスをクライアントとして呼び出すには、一般的に、wsdl2java という Axis 付属の Java コマンド・ライン・ツールを使用します。このツールは Web サービスの WSDL ファイルに基づいてスタブ・ファイルを作成し、Web サービスを呼び出します。これらのスタブ・ファイルは、Web サービスにアクセスして使用するために必要な複合コードのラッパーとして機能する Java クラスなので、このスタブ・クラスを使用するだけで、メソッドを呼び出して応答を返すことができます。呼び出したい Web サービスのすべてに対してスタブ・ファイルを生成するという下準備は必要ですが、その後の Web サービスの複雑な内容 (SOAP メッセージ形式、名前空間、応答の構文解析など) を理解するという厄介な作業からは解放されます。

Apache Axis を使用して、Lotus Notes で Web サービスを呼び出すコードを作成する場合は、手始めとして developerWorks の記事「Consuming Web services from a Lotus Domino Java agent」および OpenNTF Web サイトで入手できるオープン・ソースの Stubby データベースがお勧めです。一例として、Stubby を使用して EchoTest サービスを呼び出す Axis コードを作成する方法を以下に説明します。

  1. OpenNTF.org から Stubby データベースをダウンロードし、Lotus Notes V7 クライアントで開きます。
  2. Create New Doc ボタンをクリックしてデータベース内に新しい文書を作成し、フォームの WSDL File フィールドに EchoTest サービスの URL (http://localhost/DWSTest.nsf/EchoTestService?WSDL) を入力します (図 10 を参照)。
    図 10. Stubby データベース文書
    Stubby データベース文書
    Stubby データベース文書
  3. フォーム上の Generate Stub Files ボタンをクリックして Axis スタブ・ファイルを作成します。これによって、コンパイル済みですぐに使用できるすべてのスタブ・ファイルが含まれる JAR ファイルも作成されます。作成されるすべてのファイルは、Stubby 文書の generated files タブ上のフィールドに追加されます。
  4. generated files タブ上の JAR ファイル (この場合は EchoTestService.jar) をローカル・ファイル・システムに持ってきます (Detatch)。
  5. Lotus Domino Designer V7 を使用してデータベース内に新しい Java エージェントを作成し、Edit Project ボタンで上記の JAR ファイルを追加します。
  6. Stubby 文書の sample code タブで、生成されたサンプル・エージェント・コードをコピーしてエージェントに貼り付けます。Web サービスの Echo メソッドを呼び出す行も追加してください。エージェント・コードは以下のようになっているはずです (簡潔にするため、コメント行と空白行は取り除いています)。
    リスト 7. Lotus Notes Java エージェントでの Apache Axis スタブ・ファイルの使用
    import lotus.domino.*;
    import DefaultNamespace.*;
    public class JavaAgent extends AgentBase {
        public void NotesMain() {
            try {
                EchoTestServiceLocator locator = new EchoTestServiceLocator();
                EchoTest service = locator.getDomino();
                System.out.println("Echo said " + service.ECHO("echo"));
            } catch(Exception e) {
                e.printStackTrace();
            }
        }
    }
  7. これで、このエージェントを任意の Lotus Notes/Domino V7 クライアントまたはサーバーで実行すると Web サービスにアクセスできます。

Stubby データベースには、LotusScript のほうが使いやすいというプログラマーのために、LS2J を使用して LotusScript で Web サービスのスタブ・コードを呼び出すサンプルもあります。LS2J についての詳細は、Lotus Domino Designer のヘルプを参照してください。

PHP nuSOAP

Web サービスをテストするときに試してみたいもう 1 つのものは、PHP nuSOAP ライブラリーです。このライブラリーは、Web サービスを利用する際にはそれほど簡単には使えませんが、Domino Web サービスに関する情報を表示するには便利な方法となります。

例えば、PHP サーバーを使用できる場合 (または、WAMP サーバーなどのローカル PHP システムがある場合)、nuSOAP をサーバーにコピーすると以下のページを作成できます。

リスト 8. PHP nuSOAP による WSDL ファイルの詳細の取得
<?php
$wsdlURL = $_POST["wsdlurl"];

if ($wsdlURL) {
	// MODIFY THIS -- make sure the path below is set correctly 
	require_once('../nusoap/lib/nusoap.php');
	
	$wsdlURL = urldecode($wsdlURL);
   	$wsdl = new wsdl($wsdlURL);
	
	$wsdlerror = $wsdl->getError();
	if ($wsdlerror) {
		echo 'There was an error getting the WSDL file at ' .
		htmlspecialchars($wsdlURL) . ':<br>' . $wsdlerror;
	} else {
		echo $wsdl->WebDescription();
	}
} else {
	$htmlPage = '<html>
<head>
<title>nuSoap WSDL Documentation Generator</title>
</head>
<body>
<h3>nuSoap WSDL Documentation Generator</h3>
This page uses the 
<a href="http://sourceforge.net/projects/nusoap/">PHP nuSOAP</a> 
library to generate a nice description of a given WSDL file
and all of its available methods.<p>
<form method="post" action="' . $_SERVER['PHP_SELF'] . '">
Please enter the URL of your WSDL file below:<br>
<input type="text" size="75" name="wsdlurl"><p>
<input type="submit" value="submit" name="submit"><br />
</form>
</body>
</html>';
	
	echo $htmlPage;
}

?>

このページを PHP サーバーに保管すると、ページをブラウザーで開くときに WSDL ファイルの URL ロケーションの入力を求めるプロンプトが表示されます。URL を入力して Submit ボタンをクリックすると、Web サービスのそれぞれの public メソッドを記述するページが表示されます (図 11 を参照)。

図 11. PHP nuSOAP WSDL の文書化の例
PHP nuSOAP WSDL の文書化の例
PHP nuSOAP WSDL の文書化の例

: Web サービスがローカル・マシン上のデータベース内にある場合は、このページを PHP サーバー (設定および使用するには、WAMP サーバーがとても簡単です) のローカル・システムから実行して、ローカル PHP サーバーがポート 80 を使用していないことを確認する必要があります (ローカル側の Notes HTTP サービスが干渉されないようにするため)。

Domino SOAP メッセージ追跡用 SoapLog

もう 1 つ、使用を検討するツールとして SoapLog DSAPI Filter があります。これは DLL ファイルで、この Notes データベースをサーバーにコピーすると、サーバー上で Web サービスに送信された SOAP メッセージが記録されます。この記事を書いている現時点では、このツールは Windows サーバー専用の DLL で、無料バージョンはサポートされていません。

SoapLog ツールのインストール手順は、以下のとおりです。

  1. SoapLog をダウンロードして、ダウンロードしたファイルをローカル・ワークステーションに unzip します。
  2. soaplog.dll ファイルを Domino サーバーの Notes プログラム・ディレクトリーにコピーします。
  3. SoapLog.nsf データベースを Domino サーバーのデータ・ディレクトリーにコピーして、必要に応じて ACL を変更します (サーバーが ACL に書き込み可能なことを確認します)。
  4. サーバーの Notes.ini ファイルに SOAPLOG_DBNAME 変数を追加し、SoapLog.nsf データベースを指定します。例えば、SoapLog.nsf データベースがルート・データ・ディレクトリーにある場合は、Notes.ini ファイルに以下の行を追加します。
    SOAPLOG_DBNAME=SoapLog.nsf
  5. SOAPLOG_DBNAME=SoapLog.nsf
  6. 使用しているサーバーのサーバー文書を Domino Directory で開きます。Internet Protocols - HTTP タブに、ページ右側の中間あたりに DSAPI セクションがあります。このフィールドに soaplog.dll のエントリーを追加します (このフィールドにすでにエントリーがある場合は、新しい行を追加してから soaplog.dll エントリーを追加してください)。

Domino サーバーで HTTP タスクを再起動します。SoapLog DSAPI も同じくロードされていることを示すメッセージが表示されます。

フィルターがロードされると、サーバー上の Web サービスに対するすべての SOAP メッセージ要求が、SoapLog.nsf データベースに新規ログ文書を作成します (図 12 および図 13 を参照)。

図 12. SoapLog の request タブ
SoapLog の request タブ
SoapLog の request タブ
図 13. SoapLog の response タブ
SoapLog の response タブ
SoapLog の response タブ

他にも、ロギングを絞り込むことができる Notes.ini パラメーターがいくつかあります。動作についての詳細は、SoapLog.nsf データベースの「Using This Database」文書を参照してください。

まとめ

この記事では、Lotus Domino V7 で単純な Web サービスを作成してテストする手順を案内しました。Domino V7 プラットフォームでは、LotusScript や Java エージェント用に作成するコードとよく似たコードを使って、極めて簡単に Web サービスを作成して提供できます。Lotus Notes で Web サービスのテストと呼び出しを行うプロセスは、Web サービスの提供ほどには簡単なプロセスではありませんが、作成する Web サービスと Web サービス・クライアントを相互作用させるために有効なオプションが数多くあります。

Domino V7 で作成する Web サービスには、エンタープライズ内の他の (Domino 以外の) Web サービス対応システムが簡単にアクセスして利用できるという大きな利点があり、SOA 環境での Lotus Domino の地位を確固たるものにしています。

この連載の次回の記事では、一層高度な Web サービスを作成する方法を取り上げます。例えば、複合データ型を使用するサービス、ファイル添付を送受信するサービス、そしてカスタム・フォールトを生成するサービスなどです。


ダウンロード可能なリソース


関連トピック


コメント

コメントを登録するにはサインインあるいは登録してください。

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Lotus, SOA and web services
ArticleID=276499
ArticleTitle=IBM Lotus Domino 7 での実用的 Web サービス: 単純な Web サービスを作成してテストする
publish-date=11212006