SoapBodyUse (Class Keyword)

Specifies the encoding for any web methods defined in this class. This keyword applies only to web service and web client classes.

Usage

To specify the encoding used by the inputs and outputs of the web methods of this class, use the following syntax:

Class MyApp.MyClass [ SoapBodyUse = soapbodyuse ]  { //class members }

Where soapbodyuse is one of the following:

literal (default) — Web methods in this class use literal data by default. That is, the XML within the <Body> of the SOAP message exactly matches the schema given in the WSDL.
encoded — Web methods in this class use SOAP-encoded data by default. That is, the XML within the <Body> of the SOAP message uses SOAP encoding as appropriate for the SOAP version being used, as required by the following specifications:
- SOAP 1.1 (https://www.w3.org/TR/2000/NOTE-SOAP-20000508/Opens in a new tab)
- SOAP 1.2 (https://www.w3.org/TR/soap12-part2/Opens in a new tab)

Important:

For a web service that you create manually, the default value of this keyword is usually suitable. When you generate a web client or service from a WSDL with the SOAP Wizard, InterSystems IRIS sets this keyword as appropriate for that WSDL; if you modify the value, your web client or service may no longer work.

Details

This keyword specifies the default encoding used by any web methods defined in this class. It also controls the default values for the ELEMENTQUALIFIED and XMLELEMENT parameters for this class, as discussed in a subsection of this topic.

You can override this keyword for individual methods, by using the SoapBodyUse method keyword or the SoapBodyUse query keyword.

Effect on Subclasses

This keyword is not inherited.

Default

The default value is literal. (The SOAP standard v1.1 (Chapter 5Opens in a new tab) specifies that web methods should use SOAP encoding. However, most SOAP clients, including .NET, use literal style.)

Relationship to WSDL

The SoapBodyUse keyword specifies the value of the use attribute of the <soap:body> element within the <binding> section of the WSDL. For example, if SoapBodyUse is literal, the WSDL could look as follows:

...
<binding name="MyServiceNameSoap" 
 ...
    <soap:binding ...
    <operation name="Add">
        <soap:operation ...>
        <input>
            <soap:body use="literal"/>
        </input>
        <output>
            <soap:body use="literal"/>
        </output>
    </operation>
</binding>
...

In contrast, if SoapBodyUse is encoded, the WSDL could instead be as follows:

...
<binding name="MyServiceNameSoap" ...
    <soap:binding ...
    <operation name="Add">
        <soap:operation .../>
        <input>
            <soap:body use="encoded" namespace="http://www.mynamespace.org" 
                       encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
        </input>
        <output>
            <soap:body use="encoded" namespace="http://www.mynamespace.org" 
                       encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
        </output>

    </operation>
</binding>
...

For SOAP 1.2, the encodingStyle attribute is as follows instead:

encodingStyle="http://www.w3.org/2003/05/soap-encoding"

The SoapBodyUse keyword also determines the contents of a <part> element of a <message> element for each web method:

If SoapBodyUse is literal, each <part> element includes an element attribute. For example:
```
<part name="parameters" element="s0:Add"/>
```
For another example:
```
<part name="b" element="s0:b"/>
```
If SoapBodyUse is encoded, each <part> element includes a type attribute rather than an element attribute. For example:
```
<part name="a" type="s0:ComplexNumber"/>
```

Note that SoapBodyUse also controls the default values for the ELEMENTQUALIFIED and XMLELEMENT parameters, which also affect the WSDL.

Effect on SOAP Messages

For a web method that uses a document-style message, the web service sends a response message like the following:

<?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>
      <AddResponse ...>
...

In contrast, for a web service that uses an encoded-style message, the response message would be as follows:

<?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' 
                   xmlns:SOAP-ENC='http://schemas.xmlsoap.org/soap/encoding/' 
                   xmlns:tns='http://www.mynamespace.org' 
                   xmlns:types='http://www.mynamespace.org'>
   <SOAP-ENV:Body SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
      <types:AddResponse>
...

Effect on Default for Parameters of the Web Service or Web Client

The default value for the ELEMENTQUALIFIED parameter depends on the SoapBodyUse keyword:

Value of SoapBodyUse	Default for ELEMENTQUALIFIED	Notes
literal	1	elementFormDefault="qualified"
encoded	0	elementFormDefault="unqualified"

The default value for the XMLELEMENT parameter also depends on the SoapBodyUse keyword:

Value of SoapBodyUse	Default for XMLELEMENT	Notes
literal	1	Message parts have the element attribute
encoded	0	Message parts have the type attribute

For details on the ELEMENTQUALIFIED and XMLELEMENT parameters, see Projecting Objects to XML.

Use with %XML.DataSet

For objects of type %XML.DataSetOpens in a new tab, not all permutations of the SoapBindingStyle and SoapBodyUse keywords are permitted. See the entry for the SoapBindingStyle class keyword.