Basic WSDL Syntax

Basic WSDL Syntax

A WSDL document can be thought of as a contract between a client and a server. It describes what the Web Service can do, where it can be found, and how to invoke it. Essentially, WSDL defines an XML grammar that describes Web Services (and in gen-eral, any network service) as collections of communications endpoints (that is, the client and the server) that are able to exchange messages with each other.

WSDL documents use the following elements:

   definitions. Associates the Web Service with its namespaces.

   types. A container for data type definitions, typically using a XML Schema

Definition (XSD) or possibly some other type system.

   message. An abstract, typed definition of the data contained in the message.

   operation. An abstract description of an action that the Web Service supports.

   portType. The set of operations supported by one or more endpoints.

   binding. A specification of the protocol and data format for a particular portType.

   port. An endpoint, defined in terms of a binding and its network address (typically

a URL). This is not a TCP/IP port, which is represented by a number.

• service. A collection of related endpoints.

The structure of a typical WSDL document is shown in Figure 16.1.

Let’s take a look at a simple WSDL document example and break it down into its com-ponent elements:

<?xml  version=”1.0”?>

<definitions name=”MyService” targetNamespace=”http://mySite.com/myService.wsdl” xmlns:tns=”http://mySite.com/myService.wsdl” xmlns:xsd1=”http://mySite.com/myService.xsd” xmlns:soap=”http://schemas.xmlsoap.org/wsdl/soap/” xmlns=”http://schemas.xmlsoap.org/wsdl/”>

<import namespace=”http:/mySite.com/myService/schemas” location=”http:// mySite.com/myService/myNameSpace.xsd”/>

<types>

<schema targetNamespace=”http://mySite.com/myService.xsd” xmlns=”http://www.w3.org/2000/10/XMLSchema”>

<element  name=”MyRequest”>

...

</element>

</schema>

</types>

<message  name=”GetMyInput”>

<part name=”body” element=”xsd1:MyRequest”/> </message>

<message  name=”GetMyOutput”>

<part name=”body” element=”xsd1:myParameter”/> </message>

<portType name=”MyServicePortType”> <operation name=”MyMethod”>

<input message=”tns:GetMyInput”/> <output message=”tns:GetMyOutput”/>

</operation>

</portType>

<binding name=”MyServiceSoapBinding” type=”tns:MyServicePortType”> <soap:binding style=”document”

transport=”http://schemas.xmlsoap.org/soap/http”/> <operation name=”MyMethod”>

<soap:operation

soapAction=”http://mySite.com/MyMethod”/>

<input>

<soap:body use=”literal”/> </input>

<output>

<soap:body use=”literal”/> </output>

</operation>

</binding>

<service  name=”MyService”>

<documentation>My  first  service</documentation>

<port name=”MyServicePort” binding=”tns:MyServiceBinding”> <soap:address location=”http://mySite.com/myService”/>

</port>

</service>

</definitions>

The definitions Element and Namespaces

First, we have the definitions element:

<definitions name=”MyService” targetNamespace=”http://mySite.com/myService.wsdl” xmlns:tns=”http://mySite.com/myService.wsdl” xmlns:xsd1=”http://mySite.com/myService.xsd” xmlns:soap=”http://schemas.xmlsoap.org/wsdl/soap/” xmlns=”http://schemas.xmlsoap.org/wsdl/”>

Typically, this element defines a single Web Service, but it may define more than one. The definitions element typically contains the following attributes:

   name. An optional attribute that describes the overall service.

   targetNamespace. A typically unique namespace that defines the logical name-

space that provides information about the service.

• xmlns:tns. An optional attribute that must be set to the same value as targetNamespace. By scoping references between sections of the WSDL document with the tns: prefix, one WSDL document can import another without running into the problem of element name clashes.

   xmlns:xsd1. An example of a custom namespace that is used here to define terms such as MyRequest and MyParameter.

   xmlns:soap and xmlns:xsd. Standard namespace definitions for SOAP-specific

information and data types.

   xmlns. The default WSDL namespace, which contains <definitions>, <message>,

<service>, and so on.

The types Element

The types element contains data type definitions that are required by the messages described in the WSDL document:

<types>

<schema targetNamespace=”http://mySite.com/myService.xsd” xmlns=”http://www.w3.org/2000/10/XMLSchema”>

<element  name=”MyRequest”>

...

</element>

</schema>

</types>

In this example, we are using an optional custom schema to define our complex types as well as a standard schema.

The message and portType Elements

Within the definitions element is one or more message elements:

<message  name=”GetMyInput”>

<part name=”body” element=”xsd1:MyRequest”/> </message>

<message  name=”GetMyOutput”>

<part name=”body” element=”xsd1:myParameter”/> </message>

A message element is simply one piece of information that moves between the client and server endpoints. Typical roundtrip remote method calls have two message elements— one for the request, and the second for the response. Each message can have any number of part child elements.

The definitions element also contains the portType element:

<portType name=”MyServicePortType”> <operation name=”MyMethod”>

<input message=”tns:GetMyInput”/> <output message=”tns:GetMyOutput”/>

</operation>

</portType>

The portType element contains one or more operation elements, each of which describes a specific message sequence. Each operation element corresponds to a message element. The portType element corresponds to a class (or an interface), and the operation element corresponds to one of its methods.

The binding Element

The binding element corresponds to a portType element implemented in a particular protocol, namely SOAP. The type attribute ties the binding element to the portType ele-ment. It is possible to use different protocols (such as CORBA or DCOM), or even more than one protocol, in which case you would have more than one binding element. Here’s an example:

<binding name=”MyServiceSoapBinding” type=”tns:MyServicePortType”> <soap:binding style=”document”

transport=”http://schemas.xmlsoap.org/soap/http”/> <operation name=”MyMethod”>

<soap:operation

soapAction=”http://mySite.com/MyMethod”/>

<input>

<soap:body use=”literal”/> </input>

<output>

<soap:body use=”literal”/> </output>

</operation>

</binding>

The service Element

The service element represents a collection of port elements, where each port repre-sents the availability of a binding at a particular endpoint:

<service  name=”MyService”>

<documentation>My  first  service</documentation>

<port name=”MyServicePort” binding=”tns:MyServiceBinding”> <soap:address location=”http://mySite.com/myService”/>

</port>

</service>

The binding attribute of the port element ties it to the corresponding binding element defined previously.

The documentation Element

You should also notice the documentation child element of the preceding service ele-ment. This element essentially allows you to provide a human-readable comment and is allowed in every other element as well.

The import Element

The import element is an optional element that allows you to break up a WSDL document into multiple documents. When present, it must immediately follow the definitions element. The following example imports a schema, but it is possible to import any WSDL elements, including the definitions element, essentially allowing you to import an entire WSDL document:

<import namespace=”http:/mySite.com/myService/schemas” location=”http:// mySite.com/myService/mySchema.xsd”/>

The import element is particularly useful for breaking up a WSDL document into inter-face and implementation documents.

Extensibility Elements

Finally, we come to extensibility elements, which allow elements in a WSDL document to represent specific technologies, including SOAP. They are typically used to specify binding information. Extensibility elements are optional and can occur in most WSDL document elements. Table 16.1 shows where extensibility elements can occur and why each one is used.

TABLE 16.1    WSDL Extensibility Elements

The next section contains several examples of how to use extensibility elements to bind SOAP endpoints.