Chapter 5. WSDL

   

Chapter 5. WSDL

In Chapter 2, you saw how simple it is to create a web service using JAX-RPC by starting with a service definition in the form of a Java interface. Given such definitions and a configuration file, the wscompile and wsdeploy utilities can generate the Java code necessary to link both the client and server implementations to the underlying JAX-RPC infrastructure that ultimately creates or consumes SOAP messages. Although this is convenient for Java developers, it is not really acceptable to describe web services ”which are supposed to be platform- and language-independent ”using the type definition system of a programming language. The JAX-RPC book service created in Chapter 2, for example, uses a command-line client written in Java. In the real world, the client might instead need to be written in VB.NET, C#, or C++, or somebody might want to take the service definition and create an alternative server-side implementation on a different platform, such as Microsoft's .NET. In both of these cases, having the service defined in terms of Java interfaces is not particularly helpful.

The Web Service Description Language (WSDL) is an XML vocabulary that can be used to describe web services in both a platform- and programming language-neutral fashion. Web services defined by WSDL documents are published in a registry. Programmers can then either create their own implementations of these services, or develop clients to consume them by obtaining the WSDL definition and interpreting it in terms of the programming language of their choice. This task is made easier by the availability of tools that can parse WSDL and automatically generate the code necessary to build and decode the SOAP messages used by a web service, thereby freeing developers to concentrate on the business rules of the application instead of the network-level plumbing. In this chapter, we take a brief look at the structure of a WSDL document, and in Chapter 6, you'll see how to use JAX-RPC to implement a web service given a WSDL definition.

This chapter covers WSDL Version 1.1, the specification for which can be downloaded from http://www.w3.org/TR/wsdl. WSDL 1.1 was submitted by IBM, Microsoft, and Ariba and is widely used, but it is not a W3C standard. At the time of the writing, W3C is defining a new version of WSDL that will eventually become the endorsed standard.


   
   

5.1 WSDL Overview

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.

Example 5-1. Logical structure of a WSDL file
 <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.

Table 5-1. Schemas and namespaces commonly used in WSDL documents

Element type

Schema location and namespace URI

Generic WSDL elements

http://schemas.xmlsoap.org/wsdl

Elements for the SOAP binding

http://schemas.xmlsoap.org/wsdl/soap

Elements for the HTTP binding

http://schemas.xmlsoap.org/wsdl/http

Elements for the MIME binding

http://schemas.xmlsoap.org/wsdl/mime

Aside from documentation , the top-level elements that may appear in a WSDL file are as follows :

import

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.

types

Defines the data types used by the web service. See Section 5.2.2 later in this chapter for details.

message

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.

portType

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.

binding

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.

port

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.

service

Groups related ports together and thereby represents an entire web service.