はじめに
今回は、CachéによるWebサービスの概要を説明します。SOAP(Simple Object Access Protocol)プロトコルによる関連メソッドの集合であるWebサービスは、プラットフォームの違いを越えたデータのやりとりを実現する手段です。Cachéでは、SOAPの完全サポートを提供しています。Cachéは、Webサービスのサービスを生成する機能(Webサービスプロバイダ)と、Webサービスのクライアントインタフェースを生成する機能(Webサービスコンシューマ)の両方を提供します。
対象読者
- アプリケーション・システム開発をしている人
- データベース関連の開発およびメンテナンスをしている人
- JavaやC#でプログラミングしている人
CACHÉのWebサービスとは
Cachéでは、WebサービスはCaché SOAPサーバにより実現されます。CSPゲートウェイ経由でSOAP要求を受けとったCaché SOAPサーバは、開封したメッセージの検証後、すべての入力パラメータをCachéに適合する表記に変換し、指定されたWebメソッドを呼び出します。
CACHÉによるWebサービスの作成方法
CachéにはWebサービスのサポートが組み込まれているため、追加のミドルウェアなどは必要ありません。「WebMethod」としてタグ付けしたメソッドを含めてCachéクラスを作成すれば、自動的にWebサービスクラスとして使用可能となります。このWebサービスクラス作成には、Cachéスタジオに用意されている「Webサービスウィザード」を利用すれば、パラメータの設定なども対話式で行えます。
Webサービスクラスのパラメータ
CachéによるWebサービスは、すべて%SOAP.WebService
クラスのサブクラスによって定義されます。この%SOAP.WebService
ベースのクラスは、SOAPプロトコル経由で呼び出すメソッド作成に必要な機能をすべて提供しています。また、このクラスはSOAPに関連する「ブックキーピング」(サービスについて説明しているWSDLのドキュメントの保持など)の管理も自動化します。このクラスには、Webサービスの特性を指定する次表のようなパラメータがあります。
パラメータ | 説明 |
NAMESPACE | ユーザーのWebサービスのネームスペースを定義するのに使用するURI。既定では、開発時に一時的に使う「http://tempuri.org」に設定されているので、実行時には変更する必要ある。 |
SERVICENAME | Webサービスの名前。この名前は有効な識別子である必要がある(英数字のみ。1文字目は英字でなければならない)。 |
Webサービスウィザードの実行例
さっそくCachéスタジオを利用して、新規Webサービスを生成させてみましょう。まず、次の手順で新規のWebサービスクラスを作成します。
- Cachéスタジオの[ファイル]メニューから[新規]を選択して、[新規作成]ダイアログを表示させます。
- ダイアログの[カスタム]タブにある[Web Service]を選択して、[OK]ボタンを押します。
- 表示された[Cachéウェブサービスウィザード](次図)で、パッケージ名、クラス名のほか、上表にある2つのパラメータを指定します。
[パッケージ名] | 「MyApp」(デフォルト) |
[クラス名] | 「StockService」 |
[サービス名] | 「MyStockService」 |
[サービスネームスペース] | 「http://tempuri.org」(デフォルト) |
[サービスメソッド] | 「Test」(デフォルト) |
[OK]ボタンを押すと、次のような新規Webサービスクラス「MyApp.StockService.cls」が作成されます。
この図の[ WebMethod ]と示された箇所に、クラスメソッドを記述します。例を挙げて説明していきましょう。
Webメソッドの定義例
先ほどのウィザードでは、[サービスメソッド]をデフォルトのままにしていましたが、そのデフォルト値である「Test」メソッドの箇所を次のように変えてみましょう。
/// TODO: 引数および実装を追加します。 /// Forecast ClassMethod Forecast(StockName As %String) As %Integer [WebMethod] { Set price = $Random(1000) Quit price }
コンパイルすると、「Forecast
」というメソッドを含む「MyStockService」というWebサービスが発行されます。Webメソッドには、データベースアクセス、埋め込みのSQLクエリ、オブジェクトアクセスなど、あらゆる実装コードが使用できます。制約条件としては、非リテラルの入力パラメータや返り値に関してのみ、XML対応のクラス(スーパークラス)として%XML.Adaptor
を含めなければなりません。
単純なリテラルではCachéデータ型クラスを使用して表します。例えば2つの整数の入力値を持ち、文字列を返すWebメソッドは、次のように定義します。
ClassMethod MyMethod(p1 As %Integer,p2 As %Integer) As %String [WebMethod]
{
Quit "A string"
}
それに対して非リテラルの場合は、非データ型のXML対応Cachéクラスとしなければなりません。例えば2つの複雑な数字の入力値を持ち、複雑な数字を返すWebメソッドは、次のように定義します。
ClassMethod Add(a As ComplexNumber,b As ComplexNumber) As ComplexNumber [WebMethod]
{
Set sum = ##class(ComplexNumber).%New()
Set sum.Real = a.Real + b.Real
Set sum.Imaginary = a.Imaginary + b.Imaginary
Quit sum
}
/// A complex number
Class MyApp.ComplexNumber Extends (%RegisteredObject,%XML.Adaptor)
{
Property Real As %Float;
Property Imaginary As %Float;
}
ブラウザによるWebサービスの利用法
CachéのWebサービスは、すべて、単純なHTTPベースのインターフェイスを自動的に提供します。各Webサービスクラスは、%SOAP.WebService
クラスから派生し、その%SOAP.WebService
は%CSP.Page
から派生します。それゆえに、すべてのWebサービスクラスは、CSP経由のHTTP要求に応答できることになります。
%SOAP.WebService
クラスは、HTTP要求に応答するメソッドを実装し、次の3つを実行します。
1. HTML形式で、Webサービスとメソッドについて説明するカタログページを発行
特定のカタログページを表示させるには、対応するWebサービスクラスのURLを使います。例えば、MyApp.StockService
がUSERネームスペース内に定義されているのであれば、「http://localhost:57772/csp/user/MyApp.StockService.cls」とします。
次図は、Cachéのサンプルカタログページです。
2. XMLドキュメントとして、WebサービスのWSDL(Webサービス記述言語)ドキュメントを発行
特定のWSDLドキュメントを表示させるには、対応するWebサービスクラスのURLのパラメータリストに「WSDL」を付けます。例えば、WebサービスクラスがMyApp.StockService
の場合は、「http://localhost:57772/csp/user/MyApp.StockService.cls?WSDL」とします。
次図は、CachéのサンプルWSDLドキュメントです。
3. WebメソッドのHTMLベースのテストページを発行
特定のWebメソッドのテストページを表示させるには、対応するWebサービスクラスのURLのあとに「/(メソッド名)」を付けます。例えば、WebサービスクラスがMyApp.StockService
で、表示させたいメソッドがForecast
の場合は、「http://localhost:57772/csp/user/MyApp.StockService.cls/Forecast」とします。
次図は、Cachéのサンプルメソッド「FindPerson」のテストページです。
CACHÉによるWebサービスクライアントの作成方法
Caché WebサービスコンシューマがWebサービスプロデューサと通信するには、プロデューサのプロキシクラスを必要とします。Cachéでは、このプロキシクラスを、ウィザードを利用し、WSDLドキュメントに基づいて自動的に生成します。ウィザードでは、WSDLドキュメントのアドレスを指定するだけです。また、Cachéは、SOAP―オブジェクト間の変換をすべて自動的に行うため、CachéのアプリケーションとWebサービスとの通信が完全に透過的になります。
ウィザードを利用したプロキシクラスの作成
Caché Webサービスクライアントウィザードを利用して、プロキシクラスを生成してみましょう。
- Cachéスタジオで、プロデューサ側とは異なるネームスペースを選択します。
- [ツール]の[アドイン]メニューから[アドイン]を選択して、[アドイン]ダイアログを表示させます。
- [SOAP Client Wizard]を選択し、[OK]ボタンを押して、[SOAPクライアントウィザード]を起動します。
- プロデューサアプリケーションのWSDLドキュメントのURLを入力し、[次]ボタンを押します。クライアントウィザードの[WSDLソース]画面で、WSDLドキュメントが表示されるので、問題がなければ、オプションはデフォルトのままで[次]ボタンを押します。
- [SOAPクライアントクラスを生成中]と表示された画面に変わりますので、生成が完了したら、[完了]ボタンを押します。これで指定したネームスペースにプロキシクラスがインストールされて、生成は完了です。
CACHÉによるWebサービスのエラー処理
SOAPには、フォルト要素という、フォルトの原因となった特定のエラーに関する情報を、Webサービスプロデューサから返す仕組みがあります。Cachéでは%SOAP.Fault
オブジェクトを使用しますが、CachéのWebサービスプロデューサは、これらのオブジェクトをSOAPの標準的なフォルト要素に変換してからクライアントに返します。このようにプロデューサから受け取ったフォルト要素は、CachéのWebサービスコンシューマによって、%SOAP.Fault
オブジェクトに自動的に変換されます。
%SOAP.Fault
オブジェクトには、次表のようなプロパティがあります。
プロパティ | 説明 |
detail | フォルトの原因に関する情報 |
faultactor | フォルトを生成したサービスのURI |
faultcode | SOAPの仕様で定義されているSOAPフォルトコード |
faultstring | フォルトの原因に関する説明 |
Webサービスプロデューサ側では、エラーの可能性がある箇所すべてでSOAPフォルトを生成させる必要があります。しかし、SOAPフォルト生成コードが何度も実行される事態は回避しなければなりません。そのためには、エラーコードと詳細をパラメータとして受け取り、適切なSOAPフォルトを生成する、次のようなメソッドを用意しておく必要があります。
ClassMethod ApplicationError(code, detail) { set fault=##class(%SOAP.Fault).%New() set fault.faultcode=code set fault.detail=detail set fault.faultstring="application error" do ..ReturnFault(fault) }
このメソッドは、%SOAP.WebService ReturnFault
メソッドを呼び出し、Webサービスの実行を即座に停止し、有効なSOAPメッセージをクライアントに返します。
サンプルアプリケーションについて
Cachéでは、Webサービスの演習用に、前述したサンプルカタログページ「SOAP.Demo」が用意されています(http://localhost:57772/csp/samples/SOAP.Demo.cls)。生成されたソースコードは、SAMPLESネームスペース内の「SOAPDemo」内にありますので、参照してください。
まとめ
今回は、CachéによるWebサービスの概要として、「Webサービスウィザード」と「Webサービスクライアントウィザード」を中心に解説しました。本稿は、Cachéドキュメントをもとに構成していますので、さらに詳しく知りたい方は、「ドキュメント」の「Caché言語バインディング」と「Cachéチュートリアル」の該当ページを参照してください。