# 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.