Section 6.4. WSDL 1.1

6.4. WSDL 1.1

WSDL 1.1 is the de facto standard for describing Web services. Many vendors widely support it, both in development tools and in runtimes. After SOAP, WSDL is the most widely adopted Web services specification. This section first discusses the language structure of WSDL and presents some of the design rationale that went into it. Then it discusses the processing model for WSDL and offers some do's and don'ts as best practices for using WSDL 1.1.

6.4.1. Language Structure

WSDL documents typically contain two groups of definitions: an abstract part and a concrete part. The abstract part describes what the Web service does in terms of the messages it consumes and produces without considering how and where that service is offered. The "what" part of the description is covered by the <types>, <message>, and <portType> elements. The "how" and "where" parts are covered by the <binding> and <service> elements. Figure 6-1 summarizes the language syntax.

Figure 6-1. Syntactic structure of the WSDL 1.1 language.

A WSDL document consists of a set of definitions contained within a <definitions> element. The definitions define data structures (<types>), messages (<message>), interfaces (<portType>), bindings (<binding>), and services (<service>). The following sections consider each of these in some detail.

Definitions

Similar to XML Schema, a WSDL <definitions> element defines a bag of definitions for a single namespace, called the target namespace. The namespace is like an ownership or relationship assertion among the definitions within that document. Note that although the "targetNamespace" attribute is defined to be optional, you cannot really omit it for a nontrivial use of WSDL because omitting the namespace would make the definitions within <definitions> unreferenceable, even within the same document.

More than one definition's element might exist with the same value for the targetNamespace attribute, which demonstrates the idea that more than one physical document can define items for a single namespace. The "name" attribute of <definitions> was meant to distinguish a given collection of definitions for a namespace from another collection for the same namespace. However, because you cannot refer to that name while importing other WSDL documents, the name does not offer much value and has in fact been dropped in WSDL 2.0.

The items that can be described within <definitions> are messages, portTypes, bindings, and services. Note that a single <definitions> element can contain any number of portTypes. Therefore, it is possible for one organization to place all the portTypes offered by one entity (identified by the target namespace) within a single document.

Types

The <types> element is used to contain data structure declarations that are referred to later to define the messages that a service exchanges. Keeping to WSDL's design principle of minimality, WSDL does not define a data structure declaration language of its own. Instead, it uses extensibility to allow other languages to be used. Languages that can define XML data include XML Schema, RelaxNG, and DTDs. Languages that can define non-XML data include the MIME type system, OMG IDL, or COBOL copybooks.

For the case of XML Schema in particular, you can embed a schema directly by including an <xsd:schema> element inside <types>. The WSDL fragment that follows shows an element being declared inside the schema:

 <types>   <xsd:schema targetNamespace="http://foo.com"          xmlns:xsd="http://www.w3.org/2001/XMLSchema">    <element name="ServicePacValidationData">     <complexType>      <sequence>        <element name="Header" type="ServicePacData:Header"/>        <element maxOccurs="20" minOccurs="1"            name="LineItemSegment"            type="ServicePacData:LineItemSegment"/>      </sequence>     </complexType>    </element>   <xsd:schema> </types> 

If another type description language is used, you must employ an extension element to contain those definitions. Although this is how WSDL was designed, that capability is not often used. Instead, most users have utilized XML Schema as the type system language and converted whatever their native type system is to XML Schema. Although that is the most flexible in terms of understandability by consumers of the service (as more people will understand XML Schema), it is not the only way to WSDL.

Messages

The <message> construct allows you to describe the messages that the Web service is exchanging. In WSDL, messages can consist of one or more parts, where a part represents a single item that is to be sent or received. For example, a medical record that is sent from a hospital to an archiving service might include some information encoded in XML and a set of images representing X-Rays and other scans. A WSDL description of that message would have one part for the XML document and one part for each of the images.

Each part of a message must be described in some manner: whether the part is an XML document, an image, or a Java object. Thus, the general problem of describing a part is coupled to the language that defined data structures in the <types> element. Hence, the mechanism for describing parts is necessarily extensible.

Recognizing that XML Schema plays a central role in Web services, WSDL has built-in support for describing parts whose content was defined using XML Schema's top-level modeling constructs of global elements and complex types. To indicate that a message part is of a certain complex type, you must ensure that the optional attribute "type" is present on the <part> element. Similarly, to indicate that a message part is a certain global element, you must ensure that the optional attribute "element" is present on the <part> element. An example is given next:

 <message name="ValidationMessage">    <part name="count" type="xsd:int"/>    <part name="items" type="tns:ItemType"/> </message> 

Although XML Schema support appears to be deeply integrated to <part>, it is actually an extension attribute of <part>. In fact, during WSDL's design, the designers considered whether to use an attribute from a namespace other than the WSDL namespace to indicate XML Schemadefined elements and attributes. However, given the expected widespread use of XML Schema, designers decided that option would be unnecessarily burdensome to users.

The design of <part> envisioned that if a type system other than XML Schema were used to define the structure of the part, a different extension attribute should be introduced to indicate the type of that part. For example, for a MIME part of type image/gif, the expectation was to use the following:

 <part name="xray" mime:type="image/gif"/> 

However, for describing MIME parts in particular, the usage did not go this way. In fact, even the WSDL 1.1 specification neglected to follow through with this design and used XML Schema to describe the content abstractly and employed the MIME binding to indicate that the part was sent or received over a MIME binding (such as SOAP with Attachments, as you will be see later in the "HTTP & MIME Binding" section). Instead of the <message> and <part> construct defining MIME-typed parts in a first-class manner as MIME-typed, the specification described the parts in XML Schema and used the binding to indicate their actual MIME types. The actual part would then be defined using the "type" or "element" attribute that referred to the mapped XML Schema description of the MIME-typed part.

PortTypes

A <portType> construct defines a set of related <operation>s that a Web service supports. As a processor of messages, there is nothing intrinsic to a Web service called an "operation." Instead, an operation is simply a grouping of a related set of messages that are exchanged. In WSDL 1.1, operations are named and defined by the messages that the service receives or sends; each operation can send or receive at most one message in each direction. Thus, WSDL 1.1 has four kinds of operations:

• One-way A message comes to the service, and the service produces nothing in response.

• Request-response A message comes to the service, and the service produces a message in response.

• Solicit-response The service sends a message and gets a response back.

• Notification The service sends a message and receives nothing in response.

The WSDL fragment that follows illustrates how these four kinds of operations are indicated in a WSDL document.

 <portType name="p1">    <operation name="op1">       <input message="x:m1"/>    </operation>    <operation name="op2">       <input message="x:m1"/>       <output message="y:m2"/>    </operation>    <operation name="op3">       <output message="x:m1"/>       <input message="y:m2"/>    </operation>    <operation name="op4">       <output message="x:m1"/>    </operation> </portType> 

The first operation, op1, is a one-way operation; it declares an input message only. The second is a request-response operation; the server expects message x:m1 to be sent and responds with message y:m2. The third, op3, is a solicit-response operation; the server sends the message x:m1 and expects to receive a response of message y:m2. Finally, the fourth operation is a notification operation; the server sends the message x:m1 and does not expect a response.

The first two kinds of operations are sometimes called inbound operations because they are offered by the service and triggered by a message coming into the service. Similarly, the latter two are typically called outbound operations. Although WSDL 1.1 defined all four of these operations, only the inbound operations are fully supported. That's because the bindings that are defined by the specification only support those two styles. Outbound operations are not bound in the standard bindings in WSDL 1.1 because it's difficult for the server to decide where to send the outbound operations. With the advent of WS-Addressing (see Chapter 5, "WS-Addressing"), it is now possible to bind these properly.

A common confusion about WSDL is that request-response and solicit-response operations are automatically synchronous. In other words, the programming models that are suitable for using such operations and the bindings that are possible for such operations must be blocking and synchronous. However, no such assumption was made in WSDL 1.1's design. Request-response operations can be bound to asynchronous protocols such as SMTP and programmed either with a blocking style or a nonblocking callback style. In fact, it's not even assumed that the response will be sent back to the same party that sent the request. Bindings might offer mechanisms for a requester to direct responses to some other party. Thus, request-response operations are in many ways a composition of a one-way operation and a notification operation. They are composed to indicate that the application message pattern is such that the message is first received by the service (the one-way operation), and then it responds with the response message (the notification operation). Without this coupling, the service description would not be explicit about the ordering of the messages.

For request-response operations, the service might also indicate faults that can occur during the message exchange. Such faults are messages that might be sent in place of the response message if a faulty condition arises during the execution of the service. These faults are typically application-level faults and not infrastructure-level faults. Therefore, from the point of view of the Web service consumer, additional faults can occur because of infrastructure issues, such as network problems. It is not WSDL's intent to document all possible errors that might occur when invoking a Web service.

The WSDL 1.1 specification allows faults to be declared for solicit-response operations. However, no bindings are given for them, and it is not clear what such faults mean. Because the service generates faults, it is not immediately obvious why a service would send a fault to start an operation.

Bindings

The <types>, <message>, and <portType> constructs describe what a service does in terms of which messages are exchanged. The purpose of the <binding> element is to describe how to format those messages to interact with a particular service.

WSDL does not assume one standard way to format messages. Instead, it uses extensibility to define how to exchange messages using SOAP, HTTP, or MIME.

SOAP Binding

The SOAP binding of WSDL is an extension of WSDL that describes how to format the messages using SOAP 1.1. In summary, the SOAP binding specifies how to take the input or output <message> of an operation and create a SOAP envelope from it. To support the unification of describing message-oriented and RPC-oriented Web services, the binding introduces the concept of operation styles. The SOAP binding defines two operation styles:

• Document style Document style basically means that all the parts of the <message> are directly inserted into the SOAP envelope as children of the <Body> element.

• RPC style RPC style basically means that all the parts of the <message> are wrapped in some outer element representing the RPC. Then that resulting single wrapper element is inserted as the single child of SOAP's <Body> element.

The SOAP binding supports even greater flexibility by introducing the notion of encoding: the mapping of an abstract data structure definition into a concrete XML representation. Given that there are often many ways in which you can map an abstract structure into XML, the encoding style selects the appropriate mapping algorithm.

The following fragment shows a simple SOAP binding.

 <binding name="ServicePacValidationBinding"           type="tns:ServicePacValidationPortType">    <soap:binding style="document"            transport="http://schemas.xmlsoap.org/soap/http"/>    <operation name="validateServicePac">       <input>          <soap:body use="literal"/>       </input>       <output>          <soap:body use="literal"/>       </output>    </operation> </binding> 

HTTP & MIME Binding

The HTTP & MIME bindings that are defined by WSDL 1.1 allow you to bind a restricted set of portTypes to HTTP and MIME. The allowable set is restricted because not all XML structures can be easily represented in HTTP GET and POST operations.

The MIME binding assumes that the MIME parts have been described using XML Schema as Base64-encoded strings and then indicates how that is mapped to a MIME part. You can combine the HTTP and MIME bindings to form SOAP-with-Attachments-compatible SOAP messages.

Services

The <service> element in WSDL is the final part of a service description. It indicates where to find a service using its <port> element children. A single <service> can contain any number of <port> elements. Each <port> describes where a single portType is offered via a given binding. Thus, each <port> refers to a binding element by name and adds the address at which that binding is offered. The fragment next shows a simple <service>.

 <service name="ServicePacValidationService">    <port binding="tns:ServicePacValidationBinding"           name="ServicePacValidationPort">       <soap:address            location="http://foo.com/services/SPVPort"/>    </port> </service> 

6.4.2. Best Practices

WSDL 1.1 offers flexibility in how you can describe a service. Although that flexibility makes the language quite powerful, applying all of that flexibility can lead to interoperability problems. In particular, if a service is meant for public consumption, you must take into account specific considerations. If the service is to be used within a single organization, the organization can define the particular patterns of WSDL usage.

This is where the Web Services Interoperability Organization (WS-I) fits in. The role of WS-I is to define profiles of various Web service specifications to enable maximum interoperability. For WSDL, the WS-I Basic Profile [WS-I BP 1.0 in App. A] defines a set of constraints; adhering to them undoubtedly offers the greatest interoperability.

The specific requirements of the WS-I Basic Profile for WSDL include the use of only "literal" encodings with both document style and RPC style operations. Furthermore, for document style operations, the <message> constructs are required to have only one part. These rules were carefully constructed based on user experience and other interoperability problems. You should adhere to them unless the services are not meant for general public consumption.

Looking forward to WSDL 2.0, you should follow some additional constraints when using WSDL 1.1. In particular, WSDL 2.0 requires a service to implement exactly one interface. Thus, it is best to avoid defining WSDL 1.1 services with multiple ports when those ports offer different portTypes.

6.4.3. Problems and Limitations

Despite its phenomenal success in terms of wide adoption, WSDL 1.1 has several fundamental problems and limitations. Many of these issues are addressed in WSDL 2.0.

6.4.3.1 Messages

The problem with the <message> construct is that it was both too powerful and too weak simultanouesly.

One of the common requirements for describing services is to be able to say that a variable number of items needs to be sent or received. Unfortunately, the <part> mechanism of <message> doesn't support that. You can list only a fixed number of parts of a message. Another common need is to be able to indicate that a choice of responses exists. That is not supported by <message> either.

One of the main values of <message> and <part> was to enable description of parts in other systems, such as MIME. However, the WSDL specification neglected to use this mechanism to describe MIME parts.

To address these restrictions of <message> properly, you need to make it as functional as XML Schema's complexType construct. WSDL 2.0 solves this problem by doing away with <message> and <part> completely and using XML Schema constructs directly and carefully defining how other type systems will work.

6.4.3.2 SOAP Binding

The concept of operation styles and encodings has caused numerous difficulties for users. Originally created as a solution to bridge messaging-oriented and RPC-oriented service descriptions under one abstract form, SOAP binding has become a focal point of criticism against WSDL. This, too, is addressed in WSDL 2.0 by focusing only on "document/literal" style cases directly and allowing others to be built on top of that by convention.

6.4.3.3 Services

The problem with the <service> element is that it lacks clarity and crispness. When offering a service that has multiple interfaces, <service> offers no real guidelines as to whether to group all of it into one <service> element or multiple <service> elements within the same document. Furthermore, no semantics are given for the set of all ports that are found within a single <service> element. This leads to lack of interoperability because different people might choose differently.