WSDL

The Web Services Description Language (WSDL) allows servers to describe a SOAP endpoint. The file describes the types passed back and forth, the messages in which those types are used, and the collection of messages used by various operations. The file also describes what protocols are used to communicate when using the supported operations.

WSDL provides for extra elements within any WSDL document called extensibility elements. Extensibility elements are used to map the semantics of a particular protocol into the WSDL document. Because of this, you can map any protocol into a WSDL document. You can use WSDL to describe any message exchange mechanism. The only requirement is that both the sender and receiver have to understand how those extensibility elements were mapped into WSDL. For use with .NET, you will only see extensibility elements used for SOAP, HTTP GET, and HTTP POST. What does this mean in practical terms?

WSDL is just another interface definition language. The notable difference is that it describes the interface using a standardized XML schema. The authors of the specification recognize that the concepts behind Web Service messaging transcend things already done over many different protocols. E-mail, whose protocols are POP3 and SMTP, allows for message exchanges via mailboxes. Microsoft Message Queue (MSMQ) allows for message exchanges via queues hosted on machines. COM and CORBA specify message exchanges over particular binary protocols. The content of the message does not change depending on the underlying protocol. The thing that does change is how the content is exchanged and communicated. The extensibility elements of WSDL let me do things such as define that when I pass the integer value 4, in a SOAP message it will be expressed as <someElement>4</someElement>, and in a binary format it will be the third byte of the message and represented as 0100 (binary). To date, the only widely accepted extensibility elements relate to SOAP on HTTP. However, if you can get another party to agree to what your set of extensibility elements means, you can define mappings onto any format you choose.

In this section, you will learn about the parts of a WSDL document as well as the SOAP and HTTP bindings.

Document Parts

A WSDL document is made up of several different elements. Each of these elements has a specific purpose and a defined set of attributes. Listing 3.2 contains a sample document that you may want to refer to while reading over the description of the elements contained within a WSDL document. The major elements in the WSDL document are as follows:

  • definitions Root element of all WSDL documents. Typically, this element also declares the namespaces used within the document.

  • types An XML Schema document specifying the types used by the messages defined in the document. This element typically occurs once within a WSDL document.

  • message This element can occur zero or more times within the WSDL document.

  • portType Defines a collection of operation elements. The operation elements in turn define the input and or output message that define the operation.

  • binding Defines the semantics of an operation with respect to a specific protocol. WSDL specifies bindings for SOAP, HTTP GET and POST, and MIME.

  • service Used to tell a client of the Web Service where to communicate with the Web Service. Typically, a service maps a set of bindings that all map to the same portType and states the URL to use to access the Web Service.

  • documentation This element can exist anywhere within the WSDL document. It allows the WSDL author to add extra information for human readers about the particular WSDL element.

WSDL documents allow for the importing of other parts, including XSD and fragments of other WSDL documents. Those document fragments might contain message definitions as well as portType and binding data. WSDL also allows for the addition of content specific to the protocol being used to carry the data. This content, called extensibility elements, could be used to define ways to carry data over binary protocols, such as binary RPC, via e-mail or other methods. Because of this, extensibility elements are typically protocol specific. In this chapter, you will only look at the elements specific to SOAP that are defined in the WSDL 1.1 specification. Other extensibility elements have been defined for other transports (HTTP GET and POST) and other uses of SOAP. For example, Microsoft's .NET My Services uses extensibility elements to add routing and other information to the WSDL document. In general, a WSDL document will have the layout shown in Listing 3.2.

Listing 3.2. Pseudo-XML Document Describing the General Layout of a WSDL Document
<wsdl:definitions>

    <import namespace="some-uri" location="some-uri" /> {1 or more}
 
    <wsdl:documentation></wsdl:documentation> {0 or 1}

    <wsdl:types> {0 or 1}
        <wsdl:documentation></wsdl:documentation> {0 or 1}
        <xsd:schema></xsd:schema> {0 or more}
        <-- extensibility element --> {0 or more}
    </wsdl:types>

    <wsdl:message> {0 or more}
        <wsdl:documentation></wsdl:documentation> {0 or 1}
        <part name="nmtoken" element="qname" type="qname" />
            {0 or more}
    </wsdl:message>

    <wsdl:portType>
        <wsdl:documentation></wsdl:documentation> {0 or 1}
        <wsdl:operation> {0 or more}
            <wsdl:documentation></wsdl:documentation> {0 or 1}
            <wsdl:input name="nmtoken"? message="qname"> {0 or 1}
                <wsdl:documentation></wsdl:documentation> {0 or 1}
            </wsdl:input>
            <wsdl:output name="nmtoken"? message="qname"> {0 or 1}
                <wsdl:documentation></wsdl:documentation> {0 or 1}
            </wsdl:output>
            <wsdl:fault name="nmtoken"? message="qname"> {0 or 1}
                <wsdl:documentation></wsdl:documentation> {0 or 1}
            </wsdl:fault>
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="token" type="qname"> {0 or more}
        <wsdl:documentation></wsdl:documentation> {0 or 1}
        <-- extensibility element --> {0 or more}
        <wsdl:operation name="nmtoken"> {0 or more}
            <wsdl:documentation></wsdl:documentation> {0 or 1}
            <-- extensibility element --> {0 or more}
            <wsdl:input> {0 or 1}
                <wsdl:documentation></wsdl:documentation> {0 or 1}
                <-- extensibility element --> {0 or more}
            </wsdl:input>
            <wsdl:output> {0 or 1}
                <wsdl:documentation></wsdl:documentation> {0 or 1}
                <-- extensibility element --> {0 or more}
            </wsdl:output>
            <wsdl:fault> {0 or 1}
                <wsdl:documentation></wsdl:documentation> {0 or 1}
                <-- extensibility element --> {0 or more}
            </wsdl:fault>     
        </wsdl:operation>
    </wsdl:binding>

    <wsdl:service name="nmtoken"> {0 or more}
        <wsdl:documentation></wsdl:documentation> {0 or 1}
        <wsdl:port> {0 or more}
            <wsdl:documentation></wsdl:documentation> {0 or 1}
            <-- extensibility element --> {0 or more}
        </wsdl:port>
        <-- extensibility element --> {0 or more}
    </wsdl:service>

    <-- extensibility element --> {0 or more}
</wsdl:definitions>

As you can see, documentation and extensibility elements can appear almost anywhere within the document.

Supported Message Patterns

WSDL supports the definition of four different message patterns:

  • Request/Response— This is typical procedure call semantics. You send out a message and expect the result to be returned in a response to that message.

  • Solicit/Response— In this case, the roles of server and client are reversed. The server asks a client for data, and the client provides it. You would use this mechanism for things such as a Web Service that reports on overall system health or any other service where it would be useful to aggregate data from several other machines.

  • One-way— The client sends a message to the server and does not wait for a response. This can be used when the message itself has a limited period of usefulness. For example, a client may regularly report status or event information to a main server. The client does not want any data back, it just wants to send the data.

  • Notification— The server sends a message to a client and does not wait for a response. This might happen when a server is informing interested clients that a particular event occurred. When the clients start up, they may notify the server that they want to hear about certain system events. When those events happen, the server sends a notification to the client.

With these message patterns, you can use Web Services to create complex behaviors and interactions.

SOAP Extensibility Elements

Looking at Listing 3.2, you will note that WSDL does not allow for extensibility elements in the message or portType definitions. Extensibility elements are used to describe how a particular portType is bound to a specific protocol and how to describe the method of accessing that portType via service. Because of this, these mappings typically are called bindings. The WSDL 1.1 specification defines a set of elements specific to SOAP that allow the WSDL document to communicate the following information:

  • The method of message exchange for the portType.

  • The SOAPAction element for a given operation on the portType.

  • Any Header types, Header fault, and Body information for input and output messages.

  • Any fault information for Fault messages.

  • The location of the SOAP endpoint (defined in the service element).

Listing 3.3 shows the SOAP-specific extensibility elements with respect to their locations within a WSDL document. Elements shown as a|b means that either value a or value b can exist for the attribute, but not both.

Listing 3.3. Pseudo-WSDL File Showing only the Parts that Contain the SOAP-Specific Extensibility Elements
<wsdl:definitions>
    <wsdl:binding>
        <soap:binding style="rpc|document" transport="uri">
        <wsdl:operation>
           <soap:operation soapAction="uri"
                style="rpc|document"> {0 or 1}
           <wsdl:input>
               <soap:body parts="nmtokens" use="literal|encoded"
                    encodingStyle="uri-list" namespace="uri">
               <soap:header message="qname" part="nmtoken"
                    use="literal|encoded"
                    encodingStyle="uri-list"
                    namespace="uri"> {0 or more}
                    <soap:headerfault message="qname"
                        part="nmtoken" use="literal|encoded"
                        encodingStyle="uri-list"
                        namespace="uri" /> {0 or more}
               <soap:header>
           </wsdl:input>
           <wsdl:output>
               <soap:body parts="nmtokens" use="literal|encoded"
                    encodingStyle="uri-list" namespace="uri">
               <soap:header message="qname" part="nmtoken"
                    use="literal|encoded" encodingStyle="uri-list"
                    namespace="uri"> {0 or more}
                    <soap:headerfault message="qname" part="nmtoken"
                        use="literal|encoded"
                        encodingStyle="uri-list"
                        namespace="uri"/>{0 or more}
               <soap:header>
           </wsdl:output>
           <wsdl:fault> {0 or 1}
               <soap:fault name="nmtoken" use="literal|encoded"
                    encodingStyle="uri-list" namespace="uri">
            </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>

    <wsdl:service>
        <wsdl:port>
            <soap:address location="uri"/>
        </wsdl:port>
    </wsdl:service>
</definitions>

To understand what the various SOAP extensibility elements mean, the next sections cover them individually. In Chapter 4, “Using Attributes to Shape the WSDL and XML,” you will see how to manipulate an actual WSDL document using these elements.

soap:binding

This element describes the style of the set of operations being sent back and forth and the transport being used to send them. The style attribute can have one of two values—rpc or document. The rpc setting indicates that the messages contain parameters and return values. When set to document, the WSDL document indicates that this Web Service exchanges XML documents. When the style attribute is omitted, it is assumed to be document.

The transport attribute holds a URI referring to the network method being used to carry the message. Currently, the only value defined in the WSDL specification is http://schemas.xmlsoap.org/soap/http, which maps to HTTP. Other values can be defined for transports, such as SMTP or FTP.

soap:operation

The SOAP operation extensibility element provides a means for the WSDL to describe individual SOAP methods. The style attribute can have a value of rpc or document, just like the soap:binding element. The meanings of rpc and document are the same and provide a way to override what was stated for the binding as a whole. If the binding is set to document, all operations default to document unless otherwise defined. The same is true for the rpc style.

This element also allows the user to define the SOAPAction related to each operation through the soapAction attribute. This attribute is only useful for SOAP v1.1. SOAP v1.2 currently intends to drop this attribute. The URI should be used as it appears in the document. Readers of the URI should not try to read this as a relative URI.

soap:body and soap:fault

These elements convey the same meaning. The soap:body and soap:fault extensibility elements refers to content found in the SOAP Body and SOAP Fault elements, respectively. This element defines how the Body will be presented within the input or output of the operation. The parts attribute, if included, indicates which parts show up somewhere within the SOAP Body element. Other parts may appear elsewhere with multipart/related MIME binding. When the attribute does not appear, all parts defined by the message are assumed to be included in the SOAP Body.

The use attribute can have the value of literal or encoded. When set to literal, the encodingStyle attribute can be set to indicate how the concrete format of the message was derived. Typically, you will not see the encodingStyle set for literal encoding. Why? Because literal encoding indicates that the writer of the message should already know the message data being sent. As such, the type information is not embedded in the message, and the reader is expected to know how to transform the data into the correct types.

When the encoding style is set to encoded, the encodingStyle needs to be set to describe the types of encoding used on the elements. The encoding styles are separated by spaces and ordered from most restrictive to least restrictive. Typically, this means that the actual SOAP message will contain attributes on each element that map to values defined in the types section of the WSDL document or map to XML schema types. The namespace attribute only applies to types not defined by the abstract types.

soap:header and soap:headerfault

The soap:header and soap:headerfault extensibility elements and their attributes have the same meaning as the soap:body and soap:fault extensibility elements. They also contain one additional attribute—message. The message attribute maps to one of the message elements defined earlier in the WSDL document. You can have multiple, optional Header elements used with any given operation. Each headerfault maps back to a specific fault that can occur when the SOAP Header cannot be evaluated.

soap:address

This element allows the WSDL document to indicate where ports supporting a particular binding are found. The location attribute indicates the URL used to access the SOAP Web Service. When using the HTTP transport, this will be an HTTP address.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.148.144.228