SOAP 1.1 WSDL Extensibility Elements

The SOAP 1.1 WSDL elements enable you to configure SOAP Connectivity and SOAP Binding information for the HTTP Binding Component.

• The only SOAP 1.1 Connectivity Element is SOAP 1.1 address Element

• SOAP 1.1 Binding Elements elements include the following:

  • 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 Connectivity Element

The only SOAP 1.1 Connectivity element is the address element.

SOAP 1.1 address Element

The SOAP 1.1 address extensibility element specifies the address used to connect to the SOAP server.

Table 1 SOAP 1.1 address Element Attributes

The following example illustrates the use of the SOAP 1.1 address element.

<port binding="y:binding" name="soapEndpoint">
   <soap:address location="http://myhost:7676/some/additional/context" />
</port>

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

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

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

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

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

Table 7 SOAP 1.1 headerfault Element Attributes

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.