WSDL language basics

The Web Services Description Language (WSDL) is the most fundamental technology standard associated with the design of services. As you will see in subsequent chapters, WSDL definitions are a central part of all aspects of service design. In Chapter 5 we introduced the WSDL document and established how it consists of separate abstract and concrete definitions.

Just to recap, the abstract definition contains a series of parts that include types, message, and port type (or interface), whereas the concrete definition is comprised of binding and service parts.

Each of these parts relates to corresponding elements (Figure 13.4) that are defined in the WSDL specification. In the following sections we describe the syntactical implementation of these elements, as they are relevant to the majority of upcoming case study examples used in Chapter 15 to demonstrate service interface design. (How WSDL relates to SOA is discussed separately in the WSDL and SOA section of Chapter 14.)

Figure 13.4. The structure of a WSDL definition.

 

13.3.1. The definitions element

This is the root or parent element of every WSDL document. It houses all other parts of the service definition and is also the location in which the many namespaces used within WSDL documents are established.

Example 13.6. A definitions element of the Employee Service, declaring a number of namespaces.

<definitions name="Employee"
 targetNamespace="http://www.xmltc.com/tls/employee/wsdl/"
 xmlns="http://schemas.xmlsoap.org/wsdl/"
 xmlns:act="http://www.xmltc.com/tls/employee/schema/accounting/"
 xmlns:hr="http://www.xmltc.com/tls/employee/schema/hr/"
 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:tns="http://www.xmltc.com/tls/employee/wsdl/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 ...
definitions>

In the preceding example, the service definition is started with a definitions element that contains a series of attributes in which the service is assigned the name of "Employee" and in which a number of namespaces are declared.

For example, the xmlns attribute establishes the standard value of http://schemas.xmlsoap.org/wsdl/ as the default namespace. This means that all of the elements that belong to the WSDL language do not need prefixes to associate them with the WSDL specification.

By defining the xmlns:xsd namespace declaration, all elements within the WSDL that belong to the XML Schema Definition Language need to be prefixed with the xsd: qualifier. Also note the use of the xmlns:act and xmlns:hr namespace declarations. These are used to distinguish between two separate schemas that are imported into the types construct.

The xmlns:soap namespace declaration establishes the soap: qualifier used by elements introduced later in the bindings construct, where the WSDL definition associates its abstract operations to concrete SOAP bindings.

13.3.2. The types element

The types construct is where XSD schema content is placed. This part of the WSDL can consist of actual XSD schema markup (an entire schema construct containing type definitions), or it can contain import elements that reference external schema definitions (or it can contain both embedded and imported XSD types).

As illustrated in Figure 13.5, the types established in this part of the WSDL definition are used to represent the XML content of message bodies. The message element (explained later) references these types and associates them with messages.

Figure 13.5. The WSDL types construct populated by XSD schema types used by the message construct to represent the SOAP message body.

The SOAP message body contains XML content that can represent anything from simple parameter data to complex business documents. This content can be formally defined through types provided by the WSDL types area. Therefore, XSD schema complexType elements are commonly provided here, as they consist of groups of related types that can represent entire message body structures.

In the following example, an entire schema construct is embedded within the WSDL types construct.

Example 13.7. A types construct containing an XSD schema construct in which a complexType is defined.

<types>
 
 
 
 
 
 
 
 
types>

Use of the types construct is common in WSDL definitions with substantial content. However, it is not a required element. Native XSD schema types can be referenced directly within the message element, as explained next.

13.3.3. The message and part elements

For every message a service is designed to receive or transmit, a message construct must be added. This element assigns the message a name and contains one or more part child elements that each are assigned a type. message elements later are associated to operation elements to establish the input and output messages of the operation.

part elements use the type or element attributes to identify the data type of the message part. The type attribute can be assigned a simple or complex type and generally is used for RPC-style messages. part elements in document-style messages typically rely on the element attribute, which can reference an XSD element element. The name attribute is used to uniquely identify part elements within a message construct.

In the example below, we define request and response messages with two separate message constructs. Each message contains a part element that is assigned a predefined XSD element using the element attribute.

Example 13.8. Two message constructs likely representing the input and output messages for an operation.

<message name="getEmployeeWeeklyHoursRequestMessage">
 <part name="RequestParameter"
 element="act:EmployeeHoursRequestType"/>
message>
<message name="getEmployeeWeeklyHoursResponseMessage">
 <part name="ResponseParameter"
 element="act:EmployeeHoursResponseType"/>
message>

In the next example the part element is simply assigned a native XSD schema data type using the type attribute.

Example 13.9. A simple parameter message requiring just a single integer value.

 type="xsd:integer"/>

If all messages in a WSDL definition are assigned native (simple) XSD types, a separate types construct generally is not required.

13.3.4. The portType, interface, and operation elements

Service operations are defined within the portType area of the WSDL definition. Hence, portType constructs simply represent collections of operations. Individual operations are defined using the aptly named operation element.

Example 13.10. The portType construct hosting two operation constructs.

<portType name="EmployeeInterface">
 <operation name="GetWeeklyHoursLimit">
 ...
 operation>
 <operation name="UpdateHistory">
 ...
 operation>
portType>

The portType element is defined in version 1.1 of the Web Services Description Language. Version 2.0 of this specification changes the name of this element to interface. The examples provided in this book are based on WSDL 1.1 and therefore continue to use the portType element.

13.3.5. The input and output elements (when used with operation)

Each operation construct contains input and/or output child elements that represent the request and response messages the operation is capable of processing.

In the example below, each operation has one input and one output message. The respective input and output elements are assigned messages defined in the message constructs (explained in the previous section) via their message attributes.

Example 13.11. operation elements with child input and output elements.

 <input message="tns:getWeeklyHoursRequestMessage"/>
 <output message="tns:getWeeklyHoursResponseMessage"/>


 <input message="tns:updateHistoryRequestMessage"/>
 <output message="tns:updateHistoryResponseMessage"/>

As explained in Chapter 6, WSDL supports predefined message exchange patterns (MEPs). The presence of input and output elements and the sequence in which they are displayed generally establishes the MEP of the operation. For instance, the two operations defined in the previous example represent the request-response MEP.

Placing a single input element within the operation construct expresses the one-way MEP, as shown in the next example.

Example 13.12. An operation element with a single child input element.

 <input message="tns:receiveSubmitMessage"/>

Note

It may seem confusing to associate request-and-response with a sequence of input and then output messages because there is a tendency to think that a request requires the service to initiate communication. The reason this makes sense in the Web services world is because WSDL definitions express an interface from the perspective of the service provider. So the request-response MEP, to a WSDL, means that a requestor will send it (the service provider) a request as input, to which it (the service provider) will reply with a response as output.

 

13.3.6. The binding element

So far, all of the elements we've described belong to the abstract service definition. On their own, they complete the description of a service interfacebut without referencing any means of messaging communication technology.

The binding element begins the concrete portion of the service definition, to assign a communications protocol that can be used to access and interact with the WSDL.

Upon first glance of the following example, the binding element appears similar in structure to the portType element. As with portType, the binding construct contains one or more operation elements. However, you'll notice the additional soap:binding and soap:operation elements interspersed within the construct syntax. These are what establish the SOAP protocol as the manner in which this WSDL can be communicated with.

Example 13.13. The binding construct hosting concrete operation definitions.

<binding name="EmployeeBinding" type="tns:EmployeeInterface">
 <soap:binding style="document"
 transport="http://schemas.xmlsoap.org/soap/http"/>
 
 <soap:operation soapAction="..."/>
 ...
 
 
 <soap:operation soapAction="..."/>
 ...
 
binding>

Further, the style attribute of the soap:binding element defines whether the SOAP messages used to support an operation are to be formatted as document or RPC-style messages.

The value of "document" allows the SOAP message body to contain a fully definable XML document structure. Assigning a value of "rpc" to the style attribute requires compliance to a body structure defined within the SOAP specification, which primarily forces the root element of the body to be named after the operation name.

13.3.7. The input and output elements (when used with binding)

Each operation element within a binding construct mirrors the input and output message child elements defined in the abstract definition.

Within a binding construct, however, the input and output elements do not reference the message elements again. Instead, they contain protocol details that establish how the messages are going to be processed and interpreted by the chosen communication technology. In our example, the service interface has been bound to the SOAP protocol.

Example 13.14. input and output elements providing message processing information.

 
 <input>
 <soap:body use="literal"/>
 input>
 <output>
 <soap:body use="literal"/>
 output>


 
 <input>
 <soap:body use="literal"/>
 input>
 <output>
 <soap:body use="literal"/>
 output>

This introduces the soap:body element from the SOAP language that defines the data type system to be used by SOAP processors, via the use attribute. The use attribute can be set to "encoding" or "literal".

Note

How the style and use attributes affect the processing of messages within SOA is discussed in the WSDL and SOA section in Chapter 14.

 

13.3.8. The service, port, and endpoint elements

The service element simply provides a physical address at which the service can be accessed. It hosts the port element that contains this location information.

Example 13.15. The service and port elements establishing the physical service address.

<service name="EmployeeService">
 <port binding="tns:EmployeeBinding" name="EmployeePort">
 
 port>
service>

Because we are binding to the SOAP protocol, the port element contains a child soap:address element with the physical address information. Note that the port element is replaced with the endpoint element in version 2.0 of the WSDL specification.

13.3.9. The import element

WSDL definitions support a similar form of modularity as XSD schemas do. The import element can be used to import parts of the WSDL definition as well as XSD schemas.

Example 13.16. The import element referencing a schema document.

<import namespace="http://www.xmltc.com/tls/schemas/"
 location="http://www.xmltc.com/tls/schemas/employee.xsd"/>

Note

See the Consider using modular WSDL documents guideline at the end of Chapter 15 for more information.

 

13.3.10. The documentation element

This optional element simply allows you to add descriptive, human-readable annotations within a WSDL definition. Developers can use this information when building service requestors or it can be programmatically retrieved through a service registry to aid the discovery of the service.

Example 13.17. The documentation element providing a description of the overall service interface.

 <documentation>
 Retrieves an XML document and converts it into the
 native accounting document format.
 documentation>
 ...

SUMMARY OF KEY POINTS

• The Web Services Description Language is the focal point of service design, as it is used to design the abstract and concrete definitions of service interfaces.
• The WSDL definition hosts multiple child constructs associated with abstract and concrete parts of the service description.