Chapter 1. Introducing WSDL Contracts
Abstract
WSDL documents define services using Web Service Description Language and a number of possible extensions. The documents have a logical part and a concrete part. The abstract part of the contract defines the service in terms of implementation neutral data types and messages. The concrete part of the document defines how an endpoint implementing a service will interact with the outside world.
The recommended approach to design services is to define your services in WSDL and XML Schema before writing any code. When hand-editing WSDL documents you must make sure that the document is valid, as well as correct. To do this you must have some familiarity with WSDL. You can find the standard on the W3C web site, www.w3.org.
1.1. Structure of a WSDL document
Overview
A WSDL document is, at its simplest, a collection of elements contained within a root definition element. These elements describe a service and how an endpoint implementing that service is accessed.
A WSDL document has two distinct parts:
- A logical part that defines the service in implementation neutral terms
- A concrete part that defines how an endpoint implementing the service is exposed on a network
The logical part
The logical part of a WSDL document contains the types, the message, and the portType elements. It describes the service’s interface and the messages exchanged by the service. Within the types element, XML Schema is used to define the structure of the data that makes up the messages. A number of message elements are used to define the structure of the messages used by the service. The portType element contains one or more operation elements that define the messages sent by the operations exposed by the service.
The concrete part
The concrete part of a WSDL document contains the binding and the service elements. It describes how an endpoint that implements the service connects to the outside world. The binding elements describe how the data units described by the message elements are mapped into a concrete, on-the-wire data format, such as SOAP. The service elements contain one or more port elements which define the endpoints implementing the service.
1.2. WSDL elements
A WSDL document is made up of the following elements:
-
definitions— The root element of a WSDL document. The attributes of this element specify the name of the WSDL document, the document’s target namespace, and the shorthand definitions for the namespaces referenced in the WSDL document. -
types— The XML Schema definitions for the data units that form the building blocks of the messages used by a service. For information about defining data types see Chapter 2, Defining Logical Data Units. -
message— The description of the messages exchanged during invocation of a services operations. These elements define the arguments of the operations making up your service. For information on defining messages see Chapter 3, Defining Logical Messages Used by a Service. -
portType— A collection ofoperationelements describing the logical interface of a service. For information about defining port types see Chapter 4, Defining Your Logical Interfaces. -
operation— The description of an action performed by a service. Operations are defined by the messages passed between two endpoints when the operation is invoked. For information on defining operations see the section called “Operations”. -
binding— The concrete data format specification for an endpoint. Abindingelement defines how the abstract messages are mapped into the concrete data format used by an endpoint. This element is where specifics such as parameter order and return values are specified. -
service— A collection of relatedportelements. These elements are repositories for organizing endpoint definitions. -
port— The endpoint defined by a binding and a physical address. These elements bring all of the abstract definitions together, combined with the definition of transport details, and they define the physical endpoint on which a service is exposed.
1.3. Designing a contract
To design a WSDL contract for your services you must perform the following steps:
- Define the data types used by your services.
- Define the messages used by your services.
- Define the interfaces for your services.
- Define the bindings between the messages used by each interface and the concrete representation of the data on the wire.
- Define the transport details for each of the services.
