SOAP 1.1 Binding Elements (Using the HTTP Binding Component)

Using the HTTP Binding Component

SOAP 1.1 Binding Elements

The SOAP 1.1 extensibility elements for binding abstract WSDL messages to SOAP messages fall into several sections or levels.

Each level signifies how the binding should occur:

binding level — the configuration applies to the entire port type
operation level — the configuration applies only to the operation
message level — the configuration applies to that particular message, whether the message is input or output

SOAP 1.1 `binding` Element

The SOAP 1.1 binding element indicates that the binding is bound to the SOAP 1.1 protocol format: Envelope, Header and Body. This element does not indicate the encoding or format of the message, for example, that it necessarily follows section 5 of the SOAP 1.1 specification.

Table 2 SOAP 1.1 binding Element Attributes


Property	Description	Required or Optional	Example
transport	Indicates to which transport of SOAP this binding corresponds	Optional	http://schemas.xmlsoap.org/soap/http
style	Indicates the default style of this particular SOAP binding	Optional	rpc

The SOAP 1.1 binding element must be present when using the SOAP binding. The following example illustrates the use of the SOAP 1.1 binding element.

<definitions .... >
    <binding .... >
        <soap:binding transport="uri"? style="rpc|document"?>
    </binding>
</definitions>

The style attribute value is the default style attribute for each contained operation. If the style attribute is omitted, the value is assumed to be "document".

The value of the required transport attribute indicates the transport to use to deliver SOAP messages. The URI value http://schemas.xmlsoap.org/soap/http corresponds to the HTTP binding in the SOAP specification. Other URIs may be used here to indicate other transports such as SMTP, FTP, and so forth.

SOAP 1.1 `operation` Element

The SOAP 1.1 operation element provides binding information from the abstract operation to the concrete SOAP operation.

Table 3 SOAP 1.1 operation Element Attributes


Property	Description	Required or Optional	Example
soapAction	Indicates the soapAction that should be put into the HTTP header	Optional	urn:someSoapAction
style	Indicates the default style of this particular SOAP operation	Optional	rpc

The following example illustrates the use of the SOAP operation element.

<definitions .... >
    <binding .... >
        <operation .... >
           <soap:operation soapAction="uri"? style="rpc|document"?>?
        </operation>
    </binding>
</definitions>

The style attribute indicates whether the operation is RPC-oriented, with messages containing parameters and return values, or document-oriented, with messages containing documents. This information is used to select an appropriate programming model. The value of this attribute also affects the way in which the body of the SOAP message is constructed. If the attribute is not specified, it defaults to the value specified in the soap:binding element. If the soap:binding element does not specify a style, it is assumed to be "document".

The soapAction attribute specifies the value of the SOAPAction header for this operation. Use this URI value directly as the value for the SOAPAction header. do not attempt to make a relative URI value absolute when making the request. For the HTTP protocol binding of SOAP, this value is required and has no default value. For other SOAP protocol bindings, this value should not be specified, and the soap:operation element can be omitted.

SOAP 1.1 `body` Element

The SOAP 1.1 body element provides binding information from the abstract operation to the concrete SOAP operation.

Table 4 SOAP 1.1 body Element Attributes


Property	Description	Required or Optional	Example
parts	Indicates the parts from the WSDL message that will be included in the body element	Optional	part1
use	Indicates how message parts are encoded in the SOAP body	Optional	literal
encodingStyle	Indicates a particular encoding style to use	Optional	http://someEncodingStyle
namespace	Indicates the namespace of the wrapper element for RPC style messages	Optional	urn:someNamespace

The following example illustrates the SOAP 1.1 body element.

<definitions .... >
    <binding .... >
        <operation .... >
           <input>
               <soap:body parts="nmtokens"? use="literal|encoded"?
                          encodingStyle="uri-list"? namespace="uri"?>
           </input>
           <output>
               <soap:body parts="nmtokens"? use="literal|encoded"?
                          encodingStyle="uri-list"? namespace="uri"?>
           </output>
        </operation>
    </binding>
</definitions>

The optional parts attribute of type nmtokens indicates which parts appear somewhere within the SOAP body portion of the message. Other parts of a message may appear in other portions of the message, such as when SOAP is used in conjunction with the multipart/related MIME binding. If the parts attribute is omitted, then all parts defined by the message are assumed to be included in the SOAP Body portion.

The use attribute indicates whether the message parts are encoded using some encoding rules, or whether the parts define the concrete schema of the message.

If use is encoded, then each message part references an abstract type using the type attribute. These abstract types are used to produce a concrete message by applying an encoding that is specified by the encodingStyle attribute. The part names, types and value of the namespace attribute are all inputs to the encoding, although the namespace attribute only applies to content that is not explicitly defined by the abstract types. If the referenced encoding style allows variations in its format, as does the SOAP encoding, then all variations must be supported ("reader makes right").

If use is literal, then each part references a concrete schema definition using either the element or type attribute. In the first case, the element referenced by the part will appear directly under the body element for document style bindings, or under an accessor element named after the message part in RPC style. In the second case, the type referenced by the part becomes the schema type of the enclosing element: body for document style or part accessor element for RPC style.

You can use the value of the encodingStyle attribute when the use is literal to indicate that the concrete format was derived using a particular encoding such as the SOAP encoding, but that only the specified variation is supported ("writer makes right").

The value of the encodingStyle attribute is a list of URIs, each separated by a single space. The URIs represent encodings used within the message, in order of most restrictive to least restrictive, like the encodingStyle attribute defined in the SOAP specification.

SOAP 1.1 `fault` Element

The fault element specifies the contents of SOAP Fault Details element. It is patterned after the body element.

Table 5 SOAP 1.1 fault Element Attributes


Property	Description	Required or Optional	Example
name	Indicates the name of the part from the WSDL message that will be included in the fault element	Required	part1
use	Indicates how message parts will be encoded in the SOAP fault	Required	literal
encodingStyle	Indicates a particular encoding style to use	Optional	http://someEncodingStyle
namespace	Indicates the namespace of the wrapper element for RPC style messages	Optional	urn:someNamespace

The following example illustrates the SOAP fault element.

<definitions .... >
    <binding .... >
        <operation .... >
           <fault>*
               <soap:fault name="nmtoken" use="literal|encoded"
                                 encodingStyle="uri-list"? namespace="uri"?>
           </fault>
        </operation>
    </binding>
</definitions>

The name attribute relates the soap:fault to the wsdl:fault defined for the operation. The fault message must have a single part.

The use, encodingStyle, and namespace attributes are all used in the same way as those used with the body element, except that style="document" is assumed, because faults do not contain parameters.

SOAP 1.1 `header` and `headerfault` Elements

The header and headerfault elements enable you to define headers that are transmitted inside the header element of the SOAP Envelope. You do not have to exhaustively list all headers that appear in the SOAP Envelope using header. For example, extensions to WSDL may imply specific headers should be added to the actual payload and you do not have to list those headers here.

Table 6 SOAP 1.1 header Element Attributes


Property	Description	Required or Optional	Example
message	Indicates the WSDL message that will be used in binding to the header element	Required	part1
part	Indicates the parts from the WSDL message that will be included in the header element	Required	part1
use	Indicates how message parts will be encoded in the SOAP header	Required	literal
encodingStyle	Indicates a particular encoding style to use	Optional	http://someEncodingStyle
namespace	Indicates the namespace of the wrapper element for RPC style messages	Optional	urn:someNamespace

Table 7 SOAP 1.1 headerfault Element Attributes


Property	Description	Required or Optional	Example
name	Indicates the WSDL message that will be used in binding to the headerfault element	Required	part1
part	Indicates the parts from the WSDL message that will be included in the headerfault element	Required	part1
use	Indicates how message parts will be encoded in the SOAP headerfault	Required	literal
encodingStyle	Indicates a particular encoding style to use	Optional	http://someEncodingStyle
namespace	Indicates the namespace of the wrapper element for RPC style messages	Optional	urn:someNamespace

The following example illustrates the SOAP header and headerfault elements.

<definitions .... >
    <binding .... >
        <operation .... >
           <input>
             <soap:header message="qname" part="nmtoken" use="literal|encoded"
                          encodingStyle="uri-list"? namespace="uri"?>*
               <soap:headerfault message="qname" part="nmtoken" use="literal|encoded"
                                 encodingStyle="uri-list"? namespace="uri"?/>*
             <soap:header>                                
           </input>
           <output>
               <soap:header message="qname" part="nmtoken" use="literal|encoded"
                            encodingStyle="uri-list"? namespace="uri"?>*
                 <soap:headerfault message="qname" part="nmtoken" use="literal|encoded"
                                   encodingStyle="uri-list"? namespace="uri"?/>*
               <soap:header>                                
           </output>
        </operation>
    </binding>
</definitions>

The use, encodingStyle, and namespace attributes are all used in the same way as those used with the body element, except that style="document" is assumed because headers do not contain parameters.

Together, the message attribute (of type QName) and the part attribute (of type nmtoken) reference the message part that defines the header type.

The optional headerfault elements that appear inside the header and have the same syntax as the header, enable you to specify the header types used to transmit error information pertaining to the header, and defined by the header. The SOAP specification states that errors pertaining to headers must be returned in the headers. This mechanism enables you to specify the format of such headers.

SOAP 1.1 Binding Elements

SOAP 1.1 binding Element

SOAP 1.1 operation Element

SOAP 1.1 body Element

SOAP 1.1 fault Element

SOAP 1.1 header and headerfault Elements

SOAP 1.1 `binding` Element

SOAP 1.1 `operation` Element

SOAP 1.1 `body` Element

SOAP 1.1 `fault` Element

SOAP 1.1 `header` and `headerfault` Elements