Chapter 1. Introducing WSDL Contracts
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
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:
The logical part
The logical part of a WSDL document contains 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 of
operationelements 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. A
bindingelement 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 related
portelements. 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.