Skip to main content
Previous sectionNext section

Using the InterSystems IRIS Binary SOAP Format

InterSystems IRIS SOAP support provides an optional proprietary binary SOAP format, which is useful when you send and receive large SOAP messages and want to minimize message size.

An InterSystems IRIS web service can receive SOAP requests either in InterSystems IRIS binary SOAP format or in the usual SOAP format. No parameter is needed to enable this behavior. An InterSystems IRIS web client uses binary SOAP format only if it is configured to do so.

This topic discusses the following:

Also see “WSDL Differences for InterSystems IRIS Binary SOAP Format” in the topic “Details of the Generated WSDLs.”

Note:

If an InterSystems IRIS web service or web client uses this proprietary binary SOAP format, you cannot use WS-Security or WS-Policy features with this web service or client. See Securing Web Services.

Introduction

InterSystems IRIS binary SOAP is carried over HTTP messages as follows:

  • The message uses the POST method.

  • Content-Type is always "application/octet-stream".

  • The body is a binary representation of objects using a proprietary protocol.

  • A binary SOAP request includes an HTTP ISCSoap header of the following form:

    ISCSoap: NAMESPACE/Package.Class.Method
    Copy code to clipboard
  • SOAP sessions are supported. The session information is maintained by using the normal web session cookie. However, the SessionCookie property for SOAP web clients and web services is not supported, because binary SOAP does not use the CSPCHD proprietary SOAP header.

The following example shows a binary SOAP request:

POST /csp/gsop/GSOP.WebServiceBinary.cls HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; InterSystems IRIS;)
Host: localhost:8080
Connection: Close
ISCSoap: http://www.myapp.org/GSOAP.WebServiceBinary.Divide
Content-Type: application/octet-stream
Content-Length: 90

00085hdBinaryClient.MyAppSoap.Dividearg1arg2t
Copy code to clipboard

Notice that only the SOAP envelope and its contents are affected. The HTTP header is not affected.

Extending the WSDL for an InterSystems IRIS Web Service

Any InterSystems IRIS web service can receive SOAP requests either in InterSystems IRIS binary SOAP format or in the usual SOAP format. If an InterSystems IRIS web service receives a binary request, it sends a binary response. Otherwise, it sends the usual response. No parameter is needed to enable this behavior.

You can extend the WSDL of a web service so that:

  1. The WSDL publicly states that the web service supports the InterSystems IRIS binary SOAP format in addition to the usual SOAP format.

  2. The WSDL includes information on using the InterSystems IRIS binary SOAP format.

This allows any InterSystems IRIS web client to correctly send messages in this format if wanted.

To extend the WSDL of an InterSystems IRIS web service in this way, set the SOAPBINARY parameter to 1 for the web service.

For details on the changes, see “WSDL Differences for InterSystems IRIS Binary SOAP Format” in the topic “Details of the Generated WSDLs.”

Redefining an InterSystems IRIS Web Client to Use Binary SOAP

You can redefine an existing InterSystems IRIS web client so that it uses InterSystems IRIS binary SOAP format. To do so, set the SOAPBINARY parameter or the SoapBinary property to 1 for the web client. You may need to make additional changes; see “WSDL Differences for InterSystems IRIS Binary SOAP Format” in the topic “Details of the Generated WSDLs.”

Specifying the Character Set

The SoapBinaryCharset property of the web client specifies the InterSystems IRIS character set (for example: Unicode, Latin1) of the web service. If the character set of the client machine and service machine are the same, strings are sent RAW; otherwise they are sent encoded as UTF8.

The SoapBinaryCharset property defaults to the SOAPBINARYCHARSET parameter, which defaults to null, which always converts strings to UTF8.

Details on the InterSystems IRIS Binary SOAP Format

The API for binary SOAP is different from XML SOAP as follows:

  • For the InterSystems IRIS server:

    • Binary SOAP is denoted by the presence of the ISCSoap HTTP header.

    • The Initialize() method of the web service is not called.

    • A normal %request.Content stream is used in the initial implementation.

    • Login is via IRISUsername and IRISPassword query parameters attached to the URL. No login page is ever returned for binary SOAP.

    • If an invalid login occurs, then an instance of %SOAP.Fault is returned.

  • For %Net.HttpRequest responses:

    • A binary SOAP request is indicated by setting the SoapBinary property of the web client class for the method being called.

    • The request is sent using a normal EntityBody stream.

    • The response is returned in the Data property of HttpResponse.