Creating Web Services and Web Clients in Caché
SOAP Message Variations
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter discusses the primary variations for SOAP messages and how they are specified in Caché web services and clients.

For a Caché 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.
This chapter discusses the following:
Overview
A SOAP message is in one of the following modes, determined formally by the WSDL:
Informally, document/literal messages can have an additional variation: they can be either wrapped (the default in Caché) 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 the book Projecting Objects to XML.
How Message Variation Is Determined
For a Caché 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 a Caché 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, Caché 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 the section <message> in the appendix Details of the Generated WSDLs.”
Wrapped Document/Literal
This is the most common message style (and is the default message style for Caché web services).
<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>
    <MyMethod xmlns="http://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='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>
      <A xmlns="http://www.demoservice.org">stringA</A>
      <B xmlns="http://www.demoservice.org">stringB</B>
      <C xmlns="http://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='http://schemas.xmlsoap.org/soap/envelope/'
                   xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
                   xmlns:s='http://www.w3.org/2001/XMLSchema'
                   xmlns:SOAP-ENC='http://schemas.xmlsoap.org/soap/encoding/'
                   xmlns:tns='http://www.demoservice.org'
                   xmlns:types='http://www.demoservice.org'>
  <SOAP-ENV:Body SOAP-ENV:encodingStyle='http://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='http://www.w3.org/2003/05/soap-envelope'
                   xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
                   xmlns:s='http://www.w3.org/2001/XMLSchema'
                   xmlns:SOAP-ENC='http://www.w3.org/2003/05/soap-encoding'
                   xmlns:tns='http://www.demoservice.org'
                   xmlns:types='http://www.demoservice.org'>
  <SOAP-ENV:Body>
    <types:MyMethod SOAP-ENV:encodingStyle="http://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='http://schemas.xmlsoap.org/soap/envelope/'
                   xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
                   xmlns:s='http://www.w3.org/2001/XMLSchema'
                   xmlns:tns='http://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>