SOAP With Attachments の使用法

Caché Web クライアントおよび Web サービスでは、前の章で説明した、Caché がサポートする MTOM ではなく、同じく Caché がサポートする SOAP With Attachments を使用して、SOAP メッセージに添付を追加したり、添付を使用したりできます。

この方法では、添付として使用される MIME パーツをコードから直接管理する必要があるため、必要な作業が多くなります。

SOAP With Attachments 規格の仕様へのリンクは、このドキュメントの最初の章の “Caché でサポートされる規格” を参照してください。

添付の送信

SOAP with Attachments 規格に対する Caché サポートを使用する場合、添付の送信に以下の処理を使用します。

添付を作成します。添付を作成する手順は以下のとおりです。
1. 添付データを表すストリーム・オブジェクトを使用します。使用するクラスは、ストリーム・データの取得に必要なインタフェースによって異なります。例えば、ファイルのコンテンツをストリームに読み取るには %Library.FileCharacterStreamOpens in a new tab を使用できます。
2. %Net.MIMEPartOpens in a new tab のインスタンスである MIME パーツを作成します。
3. 作成した MIME パーツで以下を実行します。
  - Body プロパティをストリーム・オブジェクトに設定します。または、%Net.MIMEPartOpens in a new tab インスタンスのリストである Parts プロパティを設定します。
  - SetHeader() メソッドを呼び出して、MIME パーツの Content-Transfer-Encoding ヘッダを設定します。これは、必ず送信するデータのタイプに合わせて設定してください。
Web サービスまたは Web クライアントに添付を追加します。指定の添付を追加するには、以下の手順で MIME パートを適切なプロパティに挿入します。
- Web クライアントから添付を送信する場合は、Web クライアントの Attachments プロパティを更新します。
- Web サービスから添付を送信する場合は、Web サービスの ResponseAttachments プロパティを更新します。
これらのプロパティはそれぞれ、通常のリスト・インタフェース (SetAt() メソッド、Count() メソッド、GetAt() メソッドなど) を使用したリストです。
添付のコンテンツが記述されるように、Web クライアントまたは Web サービスの適切なプロパティを更新します。
- ContentId
- ContentLocation

添付の使用

Caché Web サービスや Web クライアントで添付のある SOAP メッセージ (SOAP With Attchments 仕様に準拠) を受信した場合は、次のように処理されます。

添付が適切なプロパティに挿入されます。
- Web サービスでは、着信した添付が Attachments プロパティに配置されます。
- Web クライアントでは、着信した添付が ResponseAttachments プロパティに配置されます。
これらのプロパティはそれぞれ、通常のリスト・インタフェース (SetAt() メソッド、Count() メソッド、GetAt() メソッドなど) を使用したリストです。リスト要素のそれぞれは、%Net.MIMEPartOpens in a new tab のインスタンスです。MIME パートには他の MIME パートを入れ子に組み込むことができます。添付の構造とコンテンツの決定は、コードで行う必要があります。
ContentID プロパティと ContentLocation プロパティが更新され、着信 SOAP メッセージの Content-ID ヘッダおよび Content-Location ヘッダが反映されます。

Web サービスまたは Web クライアントはこれらのプロパティへのアクセスが可能で、これによって添付へのアクセスも可能になります。

例

このセクションでは、添付を相互に送信する Web サービスと Web クライアントの例を紹介します。

Web サービス

Web サービスには、次の 2 つのメソッドがあります。

UploadAscii() は、ASCII 添付を受信して保存します。
DownloadBinary() は、要求側にバイナリ添付を送信します。

クラス定義は以下のとおりです。

Class GSOAP.FileTransferWS Extends %SOAP.WebService
{

///  Name of the web service.
Parameter SERVICENAME = "FileTransfer";

///  SOAP namespace for the web service
Parameter NAMESPACE = "http://www.filetransfer.org";

/// Namespaces of referenced classes will be used in the WSDL.
Parameter USECLASSNAMESPACES = 1;

///  Receive an attachment and save it
Method UploadAscii(filename As %String = "sample.txt") As %Status [WebMethod]
{
  //assume 1 attachment; ignore any others
  Set attach=..Attachments.GetAt(1)
       
  Set file=##class(%FileCharacterStream).%New()
  Set file.Filename="c:\from-client"_$H_filename
       
  //copy attachment into file
  Set status=file.CopyFrom(attach.Body)
  If $$$ISERR(status) {do $System.Status.DisplayError(status)}
  Set status= file.%Save()        
  Quit status
}

///  Create an attachment and send it in response to the web client call
Method DownloadBinary(filename As %String = "sample.pdf") As %Status [WebMethod]
{
  //use a file-type stream to read file contents
  Set file=##class(%Library.FileBinaryStream).%New()
  Set file.Filename="c:\"_filename

  //create MIMEpart and add file to it
  Set mimepart=##class(%Net.MIMEPart).%New() 
  Set mimepart.Body=file

  //set header appropriately for binary file
  Do mimepart.SetHeader("Content-Type","application/octet-stream")
  Do mimepart.SetHeader("Content-Transfer-Encoding","binary")
  
  //attach
  Set status=..ResponseAttachments.Insert(mimepart) 
  Quit status
}

}

Web クライアント

Web クライアント・アプリケーションには、次の 2 つのメソッドがあります。

UploadAscii() は、ASCII ファイルを Web サービスに送信します。
DownloadBinary() は、Web サービスを呼び出し、応答としてバイナリ・ファイルを受信します。

生成された Web クライアント・クラス (GSOAPClient.FileTransfer.FileTransferSoap) には、メソッド UploadAscii() および DownloadBinary() が組み込まれます。これによって先行の Web サービスの対応メソッドが起動されます。クラスは表示されません。

Web クライアント・アプリケーションには、生成された Web クライアント・クラスを使用する次のクラスも組み込まれます。

Include %systemInclude

Class GSOAPClient.FileTransfer.UseClient
{

ClassMethod DownloadBinary(filename As %String = "sample.pdf") As %Status
{
  Set client=##class(GSOAPClient.FileTransfer.FileTransferSoap).%New()

  //call web method
  Set ans=client.DownloadBinary(filename)
  
  //get the attachment (assume only 1)
  Set attach=client.ResponseAttachments.GetAt(1)
  
  //create a file and copy stream contents into it     
  Set file=##class(%FileBinaryStream).%New()
  //include $H in the filename to make filename unique
  Set file.Filename="c:\from-service"_$H_filename
  Set status=file.CopyFrom(attach.Body)
  If $$$ISERR(status) {do $System.Status.DisplayError(status)}
  Set status= file.%Save()
  Quit status
}

ClassMethod UploadAscii(filename As %String = "sample.txt") As %Status
{
  Set client=##class(GSOAPClient.FileTransfer.FileTransferSoap).%New()

  //use a file-type stream to read file contents
  Set file=##class(%Library.FileCharacterStream).%New()
  Set file.Filename="c:\"_filename

  //create MIME part, add file as Body, and set the header
  Set mimepart=##class(%Net.MIMEPart).%New() 
  Set mimepart.Body=file
  Do mimepart.SetHeader("Content-Transfer-Encoding","7bit")
  
  //attach to client and call web method
  Do client.Attachments.Insert(mimepart)  
  Set status=client.UploadAscii(filename)
  Quit status
}


}