Creating Web Services and Web Clients in Caché
Using MTOM for Attachments
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

You can include attachments in SOAP request and response messages. The preferred way to do this is to use Caché support for MTOM (Message Transmission Optimization Mechanism).

This chapter discusses the details:
You can also specify MTOM use within a policy; see Securing Caché Web Services.
You can also configure Caché web services and web clients to use gzip to compress their messages after performing any packaging; see the chapters Fine-Tuning a Caché Web Service and Fine-Tuning a Caché Web Client.”
Attachments and SOAP Message Packaging
Attachments are generally used to carry binary data. Caché SOAP support provides three ways to package your SOAP messages. Before discussing detailed options, it is worthwhile to review these kinds of packaging.
SOAP Messages with All-Inline Parts (Default)
The default way to package a SOAP message is to include all its elements as inline parts (that is, without attachments). Any binary data is included inline as base-64–encoded data. For example (with line breaks and spaces added for readability):
HTTP/1.1 200 OK
Date: Wed, 19 Nov 2008 21:57:50 GMT
Server: Apache
SET-COOKIE: CSPSESSIONID-SP-8080-UP-csp-gsoap-=003000010000248
guobl000000K7opwlDlY$XbvrGR1eYZsA--; path=/csp/gsop/;
CACHE-CONTROL: no-cache
EXPIRES: Thu, 29 Oct 1998 17:04:19 GMT
PRAGMA: no-cache
TRANSFER-ENCODING: chunked
Connection: close
Content-Type: text/xml; charset=UTF-8

1d7b
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' 
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
xmlns:s='http://www.w3.org/2001/XMLSchema'>
<SOAP-ENV:Body>
  <DownloadResponse xmlns="http://www.filetransfer.org">
     <DownloadResult><Filename>sample.pdf</Filename>
     <IsBinary>true</IsBinary>
     <BinaryContents>
        [very long binary content not shown here]
     </BinaryContents></attachment></Upload>  
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Notice that this packaging does not use MIME, and there are no message boundaries.
SOAP Messages with MTOM Packaging
Another way to package a SOAP message is to use MIME parts as described in the MTOM (Message Transmission Optimization Mechanism) specification. Binary data can be placed into separate MIME parts without base-64 encoding. The SOAP message includes references to the separate parts as needed. For example (with line breaks and spaces added for readability):
HTTP/1.1 200 OK
Date: Wed, 19 Nov 2008 21:54:57 GMT
Server: Apache
SET-COOKIE: CSPSESSIONID-SP-8080-UP-csp-gsoap-=003000010
000247guhlx000000NW1KN5UtWg$CWY38$bbTOQ--; path=/csp/gsop/;
CACHE-CONTROL: no-cache
EXPIRES: Thu, 29 Oct 1998 17:04:19 GMT
MIME-VERSION: 1.0
PRAGMA: no-cache
TRANSFER-ENCODING: chunked
Connection: close
Content-Type: multipart/related; type="application/xop+xml"; 
boundary=--boundary388.5294117647058824932.470588235294118--; 
start="<0.B1150656.EC8A.4B5A.8835.A932E318190B>"; start-info="text/xml"

1ddb
----boundary388.5294117647058824932.470588235294118--
Content-Type: application/xop+xml; type="text/xml"; charset="UTF-8"
Content-Transfer-Encoding: 8bit
Content-Id: <0.B1150656.EC8A.4B5A.8835.A932E318190B>

<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' 
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
xmlns:s='http://www.w3.org/2001/XMLSchema'>
<SOAP-ENV:Body>
<DownloadResponse xmlns="http://www.filetransfer.org">
<DownloadResult>
   <Filename>sample.pdf</Filename>
   <IsBinary>true</IsBinary>
   <BinaryContents>
      <xop:Include href="cid:1.B1150656.EC8A.4B5A.8835.A932E318190B" 
              xmlns:xop="http://www.w3.org/2004/08/xop/include"/>
   </BinaryContents></DownloadResult></DownloadResponse>  
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
----boundary388.5294117647058824932.470588235294118--
Content-Id: <1.B1150656.EC8A.4B5A.8835.A932E318190B>
Content-Transfer-Encoding: binary
CONTENT-TYPE: application/octet-stream


[very long binary content not shown here]
Notice the following differences compared to the default package:
SOAP with Attachments
A third way to package SOAP messages is to use the SOAP with Attachments specification, which also uses MIME parts, but packages the message somewhat differently from MTOM. An example follows (with line breaks and spaces added for readability):
HTTP/1.1 200 OK
Date: Mon, 09 Nov 2009 17:47:36 GMT
Server: Apache
SET-COOKIE: CSPSESSIONID-SP-8080-UP-csp-gsoap-=
000000010000213eMwn70000004swjTo4cGuInLMU1n7jaPg--; path=/csp/gsop/;
CACHE-CONTROL: no-cache
EXPIRES: Thu, 29 Oct 1998 17:04:19 GMT
MIME-VERSION: 1.0
PRAGMA: no-cache
TRANSFER-ENCODING: chunked
Connection: close
Content-Type: multipart/related; type="text/xml";
 boundary=--boundary2629.3529411764705883531.411764705882353--

1ca2
----boundary2629.3529411764705883531.411764705882353--
Content-Type: text/xml; charset="UTF-8"
Content-Transfer-Encoding: 8bit

<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' 
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
xmlns:s='http://www.w3.org/2001/XMLSchema'>
  <SOAP-ENV:Body><DownloadBinaryResponse xmlns="http://www.filetransfer.org">
<DownloadBinaryResult>MQ==</DownloadBinaryResult></DownloadBinaryResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
----boundary2629.3529411764705883531.411764705882353--
Content-Transfer-Encoding: binary
Content-Type: application/octet-stream

%PDF-1.4
%âãÏÓ
86 0 obj
<</Length 87 0 R
/Filter /FlateDecode
>>
stream
[stream not shown]
As with MTOM, there is a boundary string and the attachment is a MIME part. However, in contrast to MTOM, the MIME part does not have a content ID, and the SOAP body does not include any references to the MIME part.
Default Behavior of Caché Web Services and Web Clients
By default, a Caché web service behaves as follows:
By default, a Caché web client behaves as follows:
Forcing Responses as MTOM Packages
You can force a Caché web service to send every response as an MTOM package. To do, do any of the following:
Effect on the WSDL
MTOMREQUIRED and MTOMRequired do not affect the WSDL of the web service.
A policy statement that refers to MTOM does affect the WSDL; if you add a policy statement, it is necessary to regenerate any web clients. For a Caché web client, you can simply attach an MTOM policy statement to the client instead of regenerating the client classes.
Forcing Requests as MTOM Packages
You can force a Caché web client to send every request as an MTOM package. To do, do either of the following:
Effect on the WSDL
MTOMREQUIRED and MTOMRequired do not assume any change in the WSDL of the web service used by this web client.
A policy statement that refers to MTOM does affect the WSDL. That is, you would add an MTOM policy statement to a client only if the web service required it.
Controlling the MTOM Packaging
By default, when Caché creates an MTOM package, it uses the following rules:
You can use the MTOM property parameter to change this default:
The MTOM property parameter has no effect when a web service or web client is not using MTOM.
Also, this property parameter has no effect on the WSDL of a web service.
Example
This example shows a Caché web service that receives a binary file and sends it back to the caller.
The corresponding web client sends a file with a hardcoded filename, receives the same file from the web service, and then saves it with a new name to prove that it has been successfully sent.
Web Service
The web service is as follows:
/// Receive an attachment and send it back
Class MTOM.RoundTripWS Extends %SOAP.WebService
{

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

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

///  Receive an attachment and send it back
Method ReceiveFile(attachment As %GlobalBinaryStream) As %GlobalBinaryStream [ WebMethod ]
{
  Set ..MTOMRequired=1
  Quit attachment
}

}
Web Client
The generated web client (MTOMClient.RoundTripSoap) contains the method ReceiveFile(), which invokes the web method of the same name. This method is originally as follows:
Method ReceiveFile(attachment As %xsd.base64Binary) As %xsd.base64Binary 
[ Final, SoapBindingStyle = document, SoapBodyUse = literal, WebMethod ]
{
 Quit ..WebMethod("ReceiveFile").Invoke($this,"http://www.roundtrip.org/MTOM.RoundTripWS.ReceiveFile",
 .attachment)
}
Because the files we send might exceed the long string limit, we adjust the method signature as follows:
Method ReceiveFile(attachment As %GlobalBinaryStream) As %GlobalBinaryStream 
[ Final, SoapBindingStyle = document, SoapBodyUse = literal, WebMethod ]
{
 Quit ..WebMethod("ReceiveFile").Invoke($this,"http://www.roundtrip.org/MTOM.RoundTripWS.ReceiveFile",
 .attachment)
}
MTOM is not required by default in the web client; that is, the MTOMREQUIRED parameter is not defined.
To use this proxy client, we create the following class:
Include %systemInclude

Class MTOMClient.UseClient
{

/// For this example, hardcode what we are sending
ClassMethod SendFile() As %GlobalBinaryStream
{
  Set client=##class(MTOMClient.RoundTripSoap).%New()
  Set client.MTOMRequired=1

  //reset location to port 8080 to enable tracing
  Set client.Location="http://localhost:8080/csp/gsop/MTOM.RoundTripWS.cls"

  //create file
  Set filename="c:\sample.pdf"
  Set file=##class(%Library.FileBinaryStream).%New()
  Set file.Filename=filename

  //create %GlobalBinaryStream
  Set attachment=##class(%GlobalBinaryStream).%New()
  Do attachment.CopyFrom(file)
  
  //call the web service
  Set answer=client.ReceiveFile(attachment)
  
  //save the received file to prove we made the round trip successfully
  Set newfilename="c:\roundtrip"_$h_"sample.pdf"
  Set newfile=##class(%Library.FileBinaryStream).%New()
  Set newfile.Filename=newfilename
  Do newfile.CopyFromAndSave(answer)
  
  Quit answer
}

}