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 programmatically, InterSystems IRIS 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 SoapBindingStyle class keyword and the SoapBindingStyle method keyword. The method keyword takes precedence.
-
The SoapBodyUse class keyword and the SoapBodyUse method keyword. The method keyword takes precedence.
-
The ARGUMENTSTYLE class parameter.
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 generate a web service or client class, InterSystems IRIS sets the values for these keywords and parameter as appropriate for the WSDL from which you started.
If you modify the values, your web client or service may no longer work.
Also, for a web service that you create manually, the default values are usually suitable.
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>