SOAP 1.2 WSDL Extensibility Elements

The SOAP 1.2 WSDL extensibility elements enable you to configure two sets of information for the HTTP Binding Component: SOAP 1.2 connectivity information, and binding information to convert WSDL messages to and from SOAP messages.

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

• SOAP 1.2 Binding Elements elements include the following:

  • SOAP 1.2 binding Element

  • SOAP 1.2 operation Element

  • SOAP 1.2 body Element

  • SOAP 1.2 fault Element

  • SOAP 1.2 header and headerfault Elements

SOAP 1.2 Connectivity Element

The only SOAP 1.2 Connectivity element is the address element.

SOAP 1.2 address Element

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

Table 8 SOAP 1.2 address Element Attributes

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

 <service name="echoService">
        <port name="echoPort" binding="tns:echoBinding">
            <soap12:address location="http://localhost:9080/echoService/echoPort"/>
        </port>
    </service>

SOAP 1.2 Binding Elements

The SOAP 1.2 extensibility elements for binding abstract WSDL messages to SOAP 1.2 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.2 binding Element

The SOAP 1.2 extensibility elements, for binding abstract WSDL messages to SOAP 1.2 messages, fall into different 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

Table 9 SOAP 1.2 binding Element Attributes

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

<wsdl:definitions ...>
...
    <wsdl:binding ...>
      <soap12:binding style="rpc|document" ? transport="xs:anyURI"wsdl:
required="xs:boolean" ? />

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.2 operation Element

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

Table 10 SOAP 1.2 operation Element Attributes

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

<definitions ....>;
    <binding .... >;
        <operation .... >;
           <soap12:operation soapAction="xs:anyURI" ?
                              soapActionRequired="xs:boolean" ?
                              style="rpc|document" ?
                              wsdl:required="xs:boolean" ? /> ?
        </soap12:operation>
    </binding>;
</definitions>

The style attribute value, if present, is a string that specifies the style for the operation. The style attribute indicates whether the operation is RPC-oriented (a messages containing parameters and return values) or document-oriented (a message containing documents). If the style attribute is omitted from the soap12:operation element, then the operation inherits the style specified or implied by the soap12:binding element in the containing wsdl:binding element.

The soapAction attribute (of type xs:anyURI) specifies the value of the action parameter, carried in the application/soap+xml Content-Type header field, for this operation. The value of this attribute must be an absolute URI.

The soapActionRequired attribute (of type xs:Boolean), if present, indicates whether the value of the soapAction attribute is or is not required to be conveyed in the request message. If the soapActionRequired attribute is omitted, its value defaults to true. When the value of soapActionRequired is true, the soapAction attribute must be present

SOAP 1.2 body Element

The SOAP 1.2 body element specifies how the message parts appear within the SOAP body element.

Table 11 SOAP 1.2 body Element Attributes

The following example illustrates the SOAP 1.2 body element.

<wsdl:definitions ... >
    
  <wsdl:binding ... >
    <wsdl:operation ... >
        <wsdl:input>
            <soap12:body parts="soap12:tParts" ?
                      namespace="xs:anyURI" ?
                      use="literal|encoded" ?
                      encodingStyle="xs:anyURI" ? ... />
        ...
        </wsdl:input>
        <wsdl:output>
            <soap12:body parts="soap12:tParts ?
                    namespace="xs:anyURI" ?
                    use="literal|encoded" ?
                    encodingStyle="xs:anyURI" ? ... />
        ...
        </wsdl:output>
    </wsdl:operation>
    ...
  </wsdl:binding>
...
</wsdl:definitions>

The optional parts attribute (of type soap12:tParts, which is a list of xs:NMTOKENs) indicates which message parts are bound to the SOAP 1.2 body element of the message. Other message parts may be bound to other portions of the message, such as when SOAP is used in conjunction with the multipart/related MIME binding, or when bound as SOAP header blocks. If the parts attribute is omitted, then all of the parts defined by the associated wsdl:message are assumed to be included in the SOAP body.

The use attribute, if present, indicates whether the message parts are encoded using some encoding rules, or the parts define the concrete schema of the message. If the value is "encoded" the message parts are encoded using encoding rules that are specified by the value, actual or implied, of the encodingStyle attribute. If the value is "literal" then the message parts are literally defined by the schema types referenced.

The encodingStyle attribute (of type xs:anyURI), if present, identifies the set of encoding rules used to construct the message. This attribute must not be present unless the style attribute of the soap12:binding element of the containing wsdl:binding has a value of “rpc” and the use attribute on the containing soap12:body element has a value of "encoded". The value of the encodingStyle attribute, if present, must not be a relative URI.

SOAP 1.2 fault Element

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

Table 12 SOAP 1.2 fault Element Attributes

The following example illustrates the SOAP fault element.

<wsdl:definitions ... >
...
    <wsdl:binding ... >
    ...
        <wsdl:operation ... >
        ...
            <wsdl:fault ... >*
                <soap12:fault name="xs:NMTOKEN"
                        namespace="xs:anyURI" ?
                        use="literal|encoded" ?
                        encodingStyle="xs:anyURI" ? ... />
                ...
            </wsdl:fault>
        </wsdl:operation>
    ...
    </wsdl:binding>
...
</wsdl:definitions>

The name attribute (of type xs:NMTOKEN) associates the corresponding wsdl:fault defined in the wsdl:portType for the containing wsdl:operation.

The use attribute, if present, indicates whether the message parts are encoded using some encoding rules, or whether the parts define the concrete schema of the message. If the value is "encoded" the message parts are encoded using some encoding rules as specified by the value, actual or implied, of the encodingStyle attribute. If the value is "literal" then the message parts are literally defined by the schema types referenced.

The namespace attribute (of type xs:anyURI), if present, defines the namespace to be assigned to the wrapper element for the fault. This attribute is ignored if the style attribute of either the soap12:binding element of the containing wsdl:binding or of the soap12:operation element of the containing wsdl:operation is either omitted or has a value of “document”. This attribute must be present if the value of the style attribute of the soap12:binding element of the containing wsdl:binding is “rpc”. The value of the namespace attribute must not be a relative URI.

The encodingStyle attribute (of type xs:anyURI), if present, identifies the set of encoding rules used to construct the fault message. This attribute must not be present unless the style attribute of the soap12:binding element of the containing wsdl:binding has a value of “rpc” and the use attribute on the containing soap12:body element has a value of "encoded". The value of the encodingStyle attribute must not be a relative URI.

SOAP 1.2 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 1.2 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 13 SOAP 1.2 header Element Attributes

The following example illustrates the SOAP 1.2 header element.

<wsdl:definitions ... >
...
    <wsdl:binding ... >
...
        <wsdl:operation ... >
...
            <wsdl:input ... >*
                <soap12:header message="xs:QName"
                        part="xs:NMTOKEN"
                        use="literal|encoded"
                        namespace="xs:anyURI" ?
                        encodingStyle="xs:anyURI" ? ... /> *
...
            </wsdl:input>
            <wsdl:output ... >*
                <soap12:header message="xs:QName"
                        part="xs:NMTOKEN"
                        use="literal|encoded"
                        namespace="xs:anyURI" ?
                        encodingStyle="xs:anyURI" ? ... /> *
...
            </wsdl:output>
        </wsdl:operation>
...
    </wsdl:binding>
...
</wsdl:definitions>

The message attribute (of type xs:QName), together with the parts attribute, indicates which message parts are bound as children of the SOAP 1.2 header element of the message. The referenced message does not need to be the same as the message that defines the SOAP Body.

The parts attribute (of type xs:NMTOKEN), together with the message attribute, indicates which message part is bound as a child of the SOAP 1.2 header element of the message.

The namespace attribute (of type xs:anyURI), if present, defines the namespace to be assigned to the header element serialized with use="encoded". In all cases, the header is constructed as if the style attribute of the wsoap12:binding element, of the containing wsdl:binding, has a value of “document”. The value of the namespace attribute, if present, must not be a relative URI.

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 the value is "encoded" the message parts are encoded using some encoding rules as specified by the value, actual or implied, of the encodingStyle attribute. If the value is "literal" then the message parts are literally defined by the schema types referenced.

The encodingStyle attribute (of type xs:anyURI), if present, identifies the set of encoding rules used to construct the message. This attribute must not be present unless the style attribute, of the soap12:binding element, of the containing wsdl:binding, has a value of “rpc” and the use attribute, on the containing soap12:body element, has a value of "encoded". The value of the encodingStyle attribute, if present, must not be a relative URI.

/soap12:header/@{any}}} is an extensibility mechanism that enables additional attributes, that are defined in a foreign namespace, to be added to the element.

Optional soap12:headerfault elements, which appear inside wsoap12:header elements, specify the header types used to transmit error information pertaining to the header, defined by the soap12:header.

Table 14 SOAP 1.2 headerfault Element Attributes

The following example illustrates the SOAP 1.2 headerfault element.

<wsdl:definitions ... >
...
    <wsdl:binding ... >
...
        <wsdl:operation ... >
...
            <wsdl:input ... >
    
                <soap12:header ... >
                    <soap12:headerfault message="xs:QName"
                                part="xs:NMTOKEN"
                                use="literal|encoded"
                                namespace="xs:anyURI" ?
                                encodingStyle="xs:anyURI" ?
                                            ... /> *
                </soap12:header> *
...
            </wsdl:input> *
            <wsdl:output ... >
                <soap12:header ... >
                    <soap12:headerfault message="xs:QName"
                                part="xs:NMTOKEN"
                                use="literal|encoded"
                                namespace="xs:anyURI" ?
                                encodingStyle="xs:anyURI" ?
                                            ... /> *
                </soap12:header> *
...
            </wsdl:output> *
        </wsdl:operation>
...
    </wsdl:binding>
...
</wsdl:definitions>

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

The message attribute (of type xs:QName), together with the parts attribute, indicates which message part is to be bound as a child of the SOAP 1.2 header element of the message, for returning faults pertaining to the enclosing soap12:header. The referenced message does not need to be the same as the message that defines the SOAP Body.

The parts attribute (of type xs:NMTOKEN), together with the message attribute, indicates which message part is to be bound as a child of the SOAP 1.2 header element of the message for returning faults pertaining to the enclosing soap12:header.

The namespace attribute (of type xs:anyURI), if present, defines the namespace to be assigned to the wrapper element for an rpc-style operation. This attribute is ignored if the style attribute of either the soap12:binding element, of the containing wsdl:binding or of the soap12:operation element of the containing wsdl:operation, is either omitted or has a value of “document”. This attribute must be present if the value of the style attribute of the soap12:binding element of the containing wsdl:binding is “rpc”. The value of the namespace attribute, must not be a relative URI.

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 the value is "encoded" the message parts are encoded using some encoding rules, as specified by the value, actual or implied, of the encodingStyle attribute. If the value is "literal" then the message parts are literally defined by the schema types referenced.

The encodingStyle attribute (of type xs:anyURI), if present, identifies the set of encoding rules used to construct the message. This attribute must not be present unless the style attribute, of the soap12:binding element, of the containing wsdl:binding, has a value of “rpc” and the use attribute on the containing soap12:body element has a value of "encoded". The value of the encodingStyle attribute must not be a relative URI.

/soap12:headerfault/@{any}}} is an extensibility mechanism that enables additional attributes, defined in a foreign namespace, to be added to the element.