Skip to main content

SOAP Message Variations

This topic discusses the primary variations for SOAP messages and how they can be generated by InterSystems IRIS® data platform web services and clients.

For an InterSystems IRIS web service or client, several keywords and one parameter specify the message variation used by each web method. If you create a web service manually, the default values for these items are typically appropriate. If you create a web service or client by using the SOAP Wizard, the system sets the values as required by the WSDL. On some occasions, however, you may find it necessary to choose a specific message variation.

Overview

A SOAP message is in one of the following modes, determined formally by the WSDL:

  • Document/literal — This is the default message mode in InterSystems IRIS web services and is the most commonly used mode.

    This message mode uses document-style binding and literal encoding format; bindings and encoding formats are discussed briefly in subsections.

  • RPC/encoded — This is the second most common mode.

  • RPC/literal — This mode is widely used by IBM.

  • Document/encoded — This mode is extremely rare and is not recommended. It is also not in compliance with the WS-I Basic Profile 1.0.

Informally, document/literal messages can have an additional variation: they can be either wrapped (the default in InterSystems IRIS) or unwrapped. In a wrapped message, the message contains a single part that contains subparts. This is relevant in the case of methods that take multiple arguments. In a wrapped message, the arguments are subparts within this message. In an unwrapped message, the message consists of multiple parts, one per argument.

RPC messages can have multiple parts.

Binding Style

Each web method has a binding style for the inputs and outputs of the web method. A binding style is either document or RPC. The binding style determines how to translate a WSDL binding to a SOAP message. It also controls the format of the body of the SOAP messages.

Encoding Format

Each web method also has an encoding format, which is either literal or encoded (meaning SOAP-encoded). The encoding details are slightly different for SOAP 1.1 and SOAP 1.2. For details on the differences between literal format and SOAP-encoded format, see Projecting Objects to XML.

How Message Variation Is Determined

For an InterSystems IRIS web service or web client, the details of the service or client class control the message mode used by each web method. These details are as follows:

The following table summarizes how the message mode is determined for an InterSystems IRIS web method:

Message Mode SoapBindingStyle SoapBodyUse ARGUMENTSTYLE
wrapped document/literal document (default) literal (default) wrapped (default)
unwrapped document/literal document literal message
rpc/encoded rpc encoded Ignored
rpc/literal rpc literal Ignored
document/encoded document encoded Ignored

When you use the SOAP wizard to generate a web service or client class, the wizard sets the values for these keywords and parameter as appropriate for the WSDL from which you started.

Important:

For a web service that you create manually, the default values are usually suitable.

When you use the SOAP Wizard to create a web client or service from a WSDL, InterSystems IRIS sets these keywords as appropriate for that WSDL. If you modify the values, your web client or service may no longer work.

Examples of Message Variations

For reference, this section shows examples of the messages in the different modes (except for document/encoded, which is not recommended).

Also see <message> in Details of the Generated WSDLs.

Wrapped Document/Literal

This is the most common message style (and is the default message style for InterSystems IRIS web services).

<SOAP-ENV:Envelope xmlns:SOAP-ENV='https://schemas.xmlsoap.org/soap/envelope/' 
                   xmlns:xsi='https://www.w3.org/2001/XMLSchema-instance'
                   xmlns:s='https://www.w3.org/2001/XMLSchema'>
  <SOAP-ENV:Body>
    <MyMethod xmlns="https://www.demoservice.org">
        <A>stringA</A>
        <B>stringB</B>
        <C>stringC</C>
    </MyMethod>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Message/Unwrapped Document/Literal

This is a slight variation of the preceding style.

<SOAP-ENV:Envelope xmlns:SOAP-ENV='https://schemas.xmlsoap.org/soap/envelope/'
                   xmlns:xsi='https://www.w3.org/2001/XMLSchema-instance'
                   xmlns:s='https://www.w3.org/2001/XMLSchema'>
  <SOAP-ENV:Body>
      <A xmlns="https://www.demoservice.org">stringA</A>
      <B xmlns="https://www.demoservice.org">stringB</B>
      <C xmlns="https://www.demoservice.org">stringC</C>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

RPC/Encoded

This is the second most common style. The following shows an rpc/encoded message for SOAP 1.1:

<SOAP-ENV:Envelope xmlns:SOAP-ENV='https://schemas.xmlsoap.org/soap/envelope/'
                   xmlns:xsi='https://www.w3.org/2001/XMLSchema-instance'
                   xmlns:s='https://www.w3.org/2001/XMLSchema'
                   xmlns:SOAP-ENC='https://schemas.xmlsoap.org/soap/encoding/'
                   xmlns:tns='https://www.demoservice.org'
                   xmlns:types='https://www.demoservice.org'>
  <SOAP-ENV:Body SOAP-ENV:encodingStyle='https://schemas.xmlsoap.org/soap/encoding/'>
    <types:MyMethod>
      <A>stringA</A>
      <B>stringB</B>
      <C>stringC</C>
    </types:MyMethod>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

For SOAP 1.2, the rules for encoding are different, so the message is different:

<SOAP-ENV:Envelope xmlns:SOAP-ENV='https://www.w3.org/2003/05/soap-envelope'
                   xmlns:xsi='https://www.w3.org/2001/XMLSchema-instance'
                   xmlns:s='https://www.w3.org/2001/XMLSchema'
                   xmlns:SOAP-ENC='https://www.w3.org/2003/05/soap-encoding'
                   xmlns:tns='https://www.demoservice.org'
                   xmlns:types='https://www.demoservice.org'>
  <SOAP-ENV:Body>
    <types:MyMethod SOAP-ENV:encodingStyle="https://www.w3.org/2003/05/soap-encoding">
      <A>stringA</A>
      <B>stringB</B>
      <C>stringC</C>
    </types:MyMethod>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

RPC/Literal

The following shows an example of an rpc/literal message:

<SOAP-ENV:Envelope xmlns:SOAP-ENV='https://schemas.xmlsoap.org/soap/envelope/'
                   xmlns:xsi='https://www.w3.org/2001/XMLSchema-instance'
                   xmlns:s='https://www.w3.org/2001/XMLSchema'
                   xmlns:tns='https://www.demoservice.org'>
  <SOAP-ENV:Body>
    <tns:MyMethod>
      <tns:A>stringA</tns:A>
      <tns:B>stringB</tns:B>
      <tns:C>stringC</tns:C>
    </tns:MyMethod>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
FeedbackOpens in a new tab