Books / SOAP Web Services / Chapter 7
The WSDL 2.0 Building Blocks
As seen Figure 7-1 below, WSDL 2.0 enables the developer to separate the description of a Web service’s abstract functionality from the concrete details of how and where that functionality is offered. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it.
Different implementations of the same Web service can be made accessible using different communication protocols. (Recall also that SOAP supports binding to different transport protocols, as we saw in Chapter 5.)
The description of the endpoint’s functional capabilities is the abstract interface specification
represented in WSDL by the interface
element. An abstract interface can support any number
of operations. An operation is defined by the set of messages that define its interface pattern.
Recall that invoking an object method involves a request message passing a set of parameters (or
arguments) as well as receiving a response message that carries the result returned by the method. (The reader should recall the discussion of the RPC-style SOAP communication discussed in Chapter 4.) Also, some of the method parameters may be used to pass back the output results; these
are known as in-out or out parameters. Since the operation is invoked over the network, we must specify how the forward message carries the input parameters, as well as how the feedback
message carries the result and the output parameters, or error message in case of failure.
For the abstract concepts of messages and operations, concrete counterparts are specified in the
binding
element. A binding mechanism represented in WSDL by a binding element is used to
map the abstract definition of the Web service to a specific implementation using a particular
messaging protocol, data encoding model and underlying communication protocol. When the
binding is combined with an address where the implementation can be accessed, the abstract
endpoint becomes the concrete endpoint that service customers can invoke.
WSDL 2.0 Schema Elements
The WSDL 2.0 schema defines the following high-level or major elements in the language:
- description – Every WSDL 2.0 document has a description element as its top-most element. This merely acts as a container for the rest of the WSDL document, and is used to declare namespaces that will be used throughout the document.
- types – Defines the collection of message types that can be sent to the Web service or received from it. Each message type is defined by the message name and the data types used in the message.
- interface – The abstract interface of a Web service defined as a set of abstract operations. Each child operation element defines a simple interaction between the client and the service. The interaction is defined by specifying the messages (defined in the types element) that can be sent or received in the course of a service method invocation.
- binding – Contains details of how the elements in an abstract interface are converted into concrete representation in a particular combination of data formats and transmission protocols. Must supply such details for every operation and fault in the interface.
- service – Specifies which interface the service implements, and a list of endpoint locations where this service can be accessed.
WSDL 2.0 also offers import or interface inheritance mechanisms that are
described below. Briefly, an import
statement brings in other namespaces into the current
namespace. An include
statement brings in other element declarations that are part of the same
(current) namespace. In other words, the key difference is whether the imported components are
from the same or different namespace.
Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 Core Language) clearly states a set of constraints about how the child elements of the description element should be ordered.
Documenting a Web Service Description
A WSDL document is inherently only a partial description of a service. Although it captures the basic mechanics of interacting with the service—the message types, transmission protocols, service location, etc.—in general, additional documentation will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose and use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked.
The documentation
element allows the WSDL author to include some human readable documentation inside a WSDL document. It is also a convenient place to reference any
additional external documentation that a client developer may need in order to use the service.
The documentation
element is optional and can appear as a sub-element of any WSDL
element, not only at the beginning of a WSDL document, since all WSDL elements are derived
from wsdl:ExtensibleDocumentedType
, which is a complex type containing zero or
more documentation
elements. This fact is omitted, for simplicity, in the Schema diagrams in
this section.
Import vs Include for Reuse of WSDL 2.0 Descriptions
The include
element helps to modularize the Web service descriptions so that
separation of various service definition components from the same target namespace are allowed
to exist in other WSDL documents which can be used or shared across Web service descriptions.
This allows us to assemble a WSDL namespace from several WSDL documents that define
components for that namespace. Some elements will be defined in the given document (locally)
and others will be defined in the documents that are included in it via the include
element. The
effect of the include
element is cumulative so that if document A includes document B which in turn includes document C, then the components defined by document A comprise all those defined in A, B, and C.
In contrast, the import
element does not define any components. Instead, the import
element
declares that the components defined in this document refer to components that belong to a
different namespace. No file is being imported; just a namespace is imported from one schema to
another. If a WSDL document contains definitions of components that refer to other namespaces,
then those namespaces must be declared via an import
element. The import
element also has
an optional location attribute that is a hint to the processor where the definitions of the
imported namespace can be found. However, the processor may find the definitions by other
means, for example, by using a catalog.
After processing any include
elements and locating the components that belong to any
imported namespaces, the WSDL component model for a WSDL document will contain a set
of components that belong to this document’s namespace and any imported namespaces. These
components will refer to each other, usually via QName
references. A WSDL document is invalid
if any component reference cannot be resolved, whether or not the referenced component belongs
to the same or a different namespace.