A WSDL document describes a web service in terms of the operations that it provides and the data types that each operation requires as inputs and can return in the form of results. It is important to note that WSDL itself does not make any assumptions about the way in which the service is provided at the protocol level. Instead, the service is first defined in abstract terms and then mapped onto one or more specific protocols by the use of bindings. A binding specifies how each of the inputs and outputs for each operation are mapped onto a protocol (such as SOAP). A WSDL file may also contain a set of addresses at which a bound service can be accessed.
The logical structure of a WSDL file is shown in Example 5-1.
<wsdl:definitions ....>
<!-- Import definitions from external sources -->
<wsdl:import ..../>
<!-- Definitions of types used only in this WSDL file -->
<wsdl:types ..../>
<!-- Definitions of messages for this web service -->
<wsdl:message .../>
<!-- Definitions of the interfaces and operations provided by the service -->
<wsdl:portType .../>
<!-- Concrete bindings of interfaces and operations to protocols -->
<wsdl:binding ..../>
<!-- Defines the service as a collection of interfaces and supplies the
protocol address -->
<wsdl:service ..../>
</wsdl:definitions>
The order of child elements shown here is a natural one that reflects a progression from most abstract at the beginning to most concrete at the end. It also approximately matches the order in which we discuss the elements in this chapter and is the only order strictly permitted by the schema document for WSDL, which can be obtained from http://schemas.xmlsoap.org/wsdl, a URL that also defines the namespace for WSDL elements.
Any WSDL element can contain a single documentation element with arbitrary content that can be used to add descriptive text to it for the benefit of implementors of the service itself or of clients that will use the service. The use of documentation elements is preferred over XML comments because XML parsers are not required to pass XML comments to application code.[1] Here's a trivial example of the use of a documentation element:
[1] At the time of this writing, application code that needs to parse or manipulate WSDL must do so by using a DOM or SAX parser or a third-party class library. However, a standardized Java API called JWSDL that provides a higher-level interface to a WSDL document is currently being developed by the JSR 110 expert group. See http://jcp.org/jsr/detail/110.jsp for details.
<wsdl:types>
<wsdl:documentation>
This section defines the data types used by this service.
</wsdl:documentation>
<!-- Type definitions would be added here -->
</wsdl:types>
Each element can also contain any number of other elements that are not defined by the generic part of the WSDL specification. This feature allows the use of extensibility elements, which contain information relevant to particular bindings of a service to an underlying protocol. For example, the binding section is typically composed of extensibility elements that describe how to map the service onto SOAP messages. There are also extensibility elements that can be used to map a simple web service onto HTTP GET and POST messages, and another set of elements that describe web service messages that contain data that is represented using a MIME encoding. Each of these sets of elements is defined by its own XML schema, which is also used as the namespace for those elements, as shown in Table 5-1.
|
Element type |
Schema location and namespace URI |
|---|---|
|
Generic WSDL elements |
|
|
Elements for the SOAP binding |
|
|
Elements for the HTTP binding |
|
|
Elements for the MIME binding |
Aside from documentation, the top-level elements that may appear in a WSDL file are as follows:
Allows parts of a web service definition to be spread over multiple files and then imported as required. Use of this technique is recommended, in order to allow different web services to share the same data types or to separate the definition of a web service and its protocol bindings from the elements that provide the address of a server that offers the service. See Section 5.2.9 at the end of this chapter for some examples of this.
Defines the data types used by the web service. See Section 5.2.2 later in this chapter for details.
These elements describe the data that is exchanged between the web service and its clients in terms of the data types defined within the type elements. In concrete terms, each message defined here corresponds to a SOAP message when SOAP is used as the underlying communications mechanism.
Defines the operations that a web service provides. A port type is the WSDL equivalent of a service endpoint interface, as described in Chapter 2.
Describes how the operations and messages defined by the message and portType elements are mapped onto their concrete representations when a specific transport mechanism is used. WSDL defines extensions that allow the description of bindings to SOAP with attachments and to HTTP.
Gives the address at which a binding of a portType can be found. Port addresses are used by clients to connect to the web service.
Groups related ports together and thereby represents an entire web service.
|
|
|