Configuring JBI Components

SOAP WSDL Extensibility Elements

The SOAP WSDL elements allow you to configure two sets of information for the HTTP Binding Component: SOAP Connectivity information and SOAP Binding information, to convert WSDL messages to and from SOAP messages.

This section contains information on the following WSDL Extensibility Elements:

SOAP Connectivity

Soap Connectivity elements consist of the address element.

The SOAP Address Element

The SOAP address extensibility element allows the user to specify the connectivity information to the SOAP server.

The SOAP Address Element

The SOAP address extensibility element allows the user to specify the connectivity information to the SOAP server.

Table 1–4 The SOAP Address Element Attributes


Property	Description	Required or Optional	Example
location	A URL which specifies the connectivity information used to connect to the SOAP server.	Required	http://myhost:7676/some/additional/context

The following example illustrates the use of the SOAP address element:

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

SOAP Binding

The SOAP extensibility elements for binding abstract WSDL messages to SOAP messages fall into several sections. Each section signifies how the binding should occur. At the binding level, the configuration applies to the entire port type. At the operation level, the configuration applies only to the operation. At the message level, the configuration applies to that particular message, regardless of whether the message is input or output.

The SOAP Binding Element

The purpose of the SOAP binding element is to indicate that the binding is bound to the SOAP protocol format: Envelope, Header and Body. This element makes no claim as to the encoding or format of the message (e.g. that it necessarily follows section 5 of the SOAP 1.1 specification).

Table 1–5 The SOAP 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 binding element MUST be present when using the SOAP binding. The following example illustrates the use of the SOAP 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, it 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).

The SOAP Operation Element

The purpose of the SOAP operation element is to provide binding information from the abstract operation to the concrete SOAP operation.

Table 1–6 The SOAP 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 (messages containing parameters and return values) or document-oriented (messages containing documents). This information may be 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. This URI value should be used directly as the value for the SOAPAction header. No attempt should be made to make a relative URI value absolute when making the request. For the HTTP protocol binding of SOAP, this value is required (it has no default value). For other SOAP protocol bindings, it MUST NOT be specified, and the soap:operation element can be omitted.

The SOAP Body Element

The purpose of the SOAP body element is to provide binding information from the abstract operation to the concrete SOAP operation.

Table 1–7 The SOAP 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 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 required 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, 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).

For an example that illustrates "defining the contents of a composite Body using a type", see section 2.3.1. The value of the encodingStyle attribute may be used 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 URI's represent encodings used within the message, in order of most restrictive to least restrictive (exactly like the encodingStyle attribute defined in the SOAP specification).

The SOAP Fault Element

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

Table 1–8 The SOAP 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 with Body, only style="document" is assumed, since faults do not contain parameters.

The SOAP Header and Headerfault Elements

The header and headerfault elements allow headers to be defined that are transmitted inside the Header element of the SOAP Envelope. It is not necessary 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 it is not required to list those headers here.

Table 1–9 The SOAP Header Element Attributes


Property	Description	Required or Optional	Example
message	Indicates 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 1–10 The SOAP Headerfault Element Attributes


Property	Description	Required or Optional	Example
name	Indicates 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 with Body, only style="document" is assumed since 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 which appear inside the header and have the same syntax as the header, allow specification of 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 allows specification of the format of such headers.