In this article, we will look at WSDL document so that a developer can succeed on the web service developer exam. We will provide an overview of WSDL explaining the structure of a WSDL document and how to construct one that describes a Web service properly. Also we will focus on WSDL documents that describe Web services that are SOAP-based and compliant with the WS-I Basic Profile 1.1. This is one of two articles that focus on describing and publishing web services using WSDL and UDDI. This is part of a larger series of articles to help you prepare for the web service developer exam. You can review the first two article of this series, ďTutorial:Review of Building Web Services for the Web Service Developer ExamĒ and ďTutorial:Review of SOAP Web Services for the Web Service Developer ExamĒ if needed.

WSDL Document

The first things that must be known before you can use SOAP based Web services is the structure of the SOAP messages, the protocol being employed (i.e. generally HTTP but sometimes SMTP as well), and the address (i.e. URL) of the Web service. In the case of the BookQuote SOAP message from the previous article, ďTutorial:Review of SOAP Web Services for the Web Service Developer ExamĒ, this information is straightforward. In order to standardize the information required to use web services, the Web services community has adopted the Web Services Description Language (WSDL), as a document format for describing precisely Web services.

WSDL is used to specify the exact message format, Internet protocol, and address that a client must use to communicate with a particular Web service. It is an XML grammar for describing a web service as a collection of access endpoints capable of exchanging messages in a procedure- or document-oriented fashion. A WSDL document is a recipe used to automate the details involved in application-to-application communication. We use a WSDL document to learn how to use a Web service. WSDL is the de facto standard for Web services description and because it has achieved widespread adoption; it has the endorsement of most enterprise software vendors and major standard organizations that are involved in the evolutions of web service standards.

WSDL is used to define the interfaces and datatypes for a discreet piece of programming logic. As well, WSDL offers a degree of extensibility that is not known in other similar interfaces such as CORBA IDL or Microsoft IDL. Using WSDL, we can do the following:
Describe endpoints and the messages with which the endpoints are associated irrespective of the message format or network protocol used to exchange them.
Handle messages as abstract descriptions of the data being exchanged.
Handle port types as abstract collections of a web services' operations. A Port type is then available to be mapped to a concrete protocol and data format.

The Basic Structure of WSDL and WSDL Web Services

A WSDL document is simply an XML document that conforms to the WSDL XML schema. As with any XML document instance, WSDL documents must use the correct elements in the proper order if it is to be considered valid and well formed. A WSDL document contains the following elements:
  • types - uses XML schema language to declare complex data types and elements used within the WSDL document. The XML schema language is used by the types element to declare complex data types and elements that are used within the WSDL document.
  • import - is similar to an import element in an XML schema document; it's used to import WSDL definitions from other WSDL documents.
  • message - describes the message's payload using XML schema built-in types, complex types, or elements that are defined in the WSDL document's types element, or defined in an external WSDL document the import element refers to.
  • portType - describe a Web service's interface. This and its operation elements are similar to a Java interface and its method declarations.
  • operations - uses one or more message types to define its input and output payloads.
  • binding - assigns a portType and its operation elements to a particular protocol like SOAP 1.1 and itís encoding style.
  • service - is responsible for assigning an Internet address to a specific binding.

These are all nested in the definitions element, the root element of a WSDL document. The figure below shows the basic structure of a WSDL document.

Tutorial:Review of WSDL Document for the Web Service Developer Exam-b3-wsdldocument.jpg
Figure: The Basic Structure of a WSDL Document

There is also a documentation element that explains some aspect of the WSDL document to human readers. Any of the other WSDL elements may contain documentation elements.
An example of a simple WSDL document is shown below continuing from previous article, ďTutorial:Review of SOAP Web Services for the Web Service Developer ExamĒ, where we developed the SOAP messages related to a BookQuote Web service. The WSDL definition for the BookQuote Web service including the types of SOAP messages, protocols, and Internet addresses used to access that Web service are shown below:

XML Code: WSDL Definition for the BookQuote Web Service
<?xml version="1.0" encoding="UTF-8"?>
<definitions name="BookQuoteWS"
 targetNamespace="http://www.acmebooks.com/b2bbooks/BookQuote"
 xmlns:mh="http://www.acmebooks.com/b2bbooks/BookQuote"
 xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns="http://schemas.xmlsoap.org/wsdl/">

  <!-- message elements describe the input and output parameters -->
  <message name="GetBookPriceRequest">
    <part name="isbn" type="xsd:string" />
  </message>
  <message name="GetBookPriceResponse">
    <part name="price" type="xsd:float" />
  </message>

  <!-- portType element describes the abstract interface of a Web service -->
  <portType name="BookQuote">
    <operation name="getBookPrice">
      <input name="isbn" message="mh:GetBookPriceRequest"/>
      <output name="price" message="mh:GetBookPriceResponse"/>
    </operation>
  </portType>

  <!-- binding tells us which protocols and encoding styles are used -->
  <binding name="BookPrice_Binding" type="mh:BookQuote">
    <soapbind:binding style="rpc"
     transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="getBookPrice">
      <soapbind:operation style="rpc"
       soapAction=
       "http://www.acmebooks.com/b2bbooks/BookQuote/GetBookPrice"/>
        <input>
          <soapbind:body use="literal"
           namespace="http://www.acmebooks.com/b2bbooks/BookQuote" />
        </input>
        <output>
          <soapbind:body use="literal"
           namespace="http://www.acmebooks.com/b2bbooks/BookQuote" />
        </output>
    </operation>
  </binding>

  <!-- service tells us the Internet address of a Web service -->
  <service name="BookPriceService">
    <port name="BookPrice_Port" binding="mh:BookPrice_Binding">
      <soapbind:address location=
       "http://www.acmebooks.com/b2bbooks/BookQuote" />
    </port>
  </service>
</definitions>
Letís now look in detail as to how a WSDL document is organized and as well as the purpose of all its elements and attributes.

WSDL Declarations

The first part of the WSDL is the part containing declarations. It holds the definitions of the root element, types and import of various artifacts including data types and other WSDL documents.

The XML Declaration

The first line in the listing shows the XML declaration specifying the character encoding of UTF-8 for the document. WSDL document must use either UTF-8 or UTF-16 encoding. This is shown in the listing below:

CODE=XML;XML Declaration]<?xml version="1.0" encoding="UTF-8"?>[/CODE]

The definitions Element

The <definitions> element of a WSDL document serves as the container for the service description. It is the place to do global declarations of namespaces intended to be visible throughout the rest of the document. It is the root element of all WSDL documents and encapsulates the entire document and also provides a WSDL document with its name. This is shown in the listing below:

XML Code: Definitions Element
<definitions name="BookQuoteWS"
 targetNamespace="http://www.acmebooks.com/b2bbooks/BookQuote"
 xmlns:mh="http://www.acmebooks.com/b2bbooks/BookQuote"
 xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns="http://schemas.xmlsoap.org/wsdl/">
The definitions element contains several XML namespace declarations. Some of the namespaces defined in this element have prefixes (xsd, soap, soapenc, xer, etc.), and others do not. The prefixes are bound to a particular namespace but donít govern the schemas that are actually available to a schema processor. Among these declarations is one for the namespace of the WSDL 1.1 XML schema "http://schemas.xmlsoap.org/wsdl/". By making this declaration for the WSDL namespace, it is seen as the default namespace which means that it doesnít need to be added as a prefix for those WSDL element that belong to it.

In our listing, the first attribute shown in the definitions element is name. This becomes the name for the entire WSDL document. It is not required. Next we have the targetNamespace attribute that defines the namespace of elements defined in the WSDL document. The URI for the targetNamspace attribute must be an absolute reference, not a relative one. After the targetNamespace attribute, there is message, portType, and binding elements that are assigned labels using their name attributes. These labels automatically use the namespace specified by the targetNamespace attribute and are commonly called definitions. These definitions assume the namespace specified by targetNamespace.
There are other elements in the document also referred to as definitions by their label and namespace prefix. A prefixed label is considered a fully qualified name (QName) for a definition. Here are the things you need to consider when working with namespaces:
  • A namespace is qualified in an XML document through a QNAME. The QNAME is the value following xmlns: in an XML document and is a value used to qualify an element within the XML document. If two elements imported from different namespaces have the same name, they are qualified by using the QNAME followed by a colon.
  • The default namespace or default qualifier used on elements is the namespace that follows the xmlns= attribute in an XML definition. If two conflicting elements come from different namespaces, the element defined in the namespace identified by xmlns= is used.
  • The targetNamespace creates a unique identifier of the namespace created in the WSDL document. As the WSDL document defines new elements and attributes, the value of this attribute is the identifier given to the namespace to which those elements belong.

It is common practice to further qualify the target namespace by creating a QNAME named tns that points to the same value of targetNamespace. This means that the targetNamespace creates a new namespace, and tns becomes the QNAME for identifying "this namespace" within the same WSDL document.

Below is a table with the list of namespace prefixes and URIs that are most frequently used in WSDL documents. There are many others that I have not listed but can be found with the appropriate documentation:
Tutorial:Review of WSDL Document for the Web Service Developer Exam-b3-namespaceprefixes.jpg
Table: Frequently Used Namespace Prefixes

Below is an example of fully qualified names (QNames) of message definitions for input and output elements:

XML Code: Message Elements with QNames
<message name="GetBookPriceRequest">
  <part name="isbn" type="xsd:string" />
</message>
<message name="GetBookPriceResponse">
  <part name="price" type="xsd:float" />
</message>

<!-- the portType element describes the interface of the Web service -->
<portType name="BookQuote">
  <operation name="getBookPrice">
    <input name="isbn" message="mh:GetBookPriceRequest"/>
    <output name="price" message="mh:GetBookPriceResponse"/>
  </operation>
</portType>
The types Element

WSDL uses the W3C XML schema built-in types as its basic type system. These types element serves as a container for defining any data types that are not described by the XML schema built-in types. This would be either complex types or custom simple types. The data types and elements defined in the types element are then used by message definitions for declaring various parts of messages.
In the WSDL definition we have not used the types element because they were not need for the message definitions of GetBookPriceRequest and GetBookPriceResponse. Both refer to simple built-in types.

Instead of using simple built-in types, we could define a custom simple type for ISBN number and use this for the GetBookPriceRequest message. This is shown in the listing below:

XML Code: Using XML Schema Types Defined in the WSDL types Element
<?xml version="1.0" encoding="UTF-8"?>
<definitions name="BookQuoteWS"
 targetNamespace="http://www.acmebooks.com/b2bbooks/BookQuote"
 xmlns:mh="http://www.acmebooks.com/b2bbooks/BookQuote"
 xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns="http://schemas.xmlsoap.org/wsdl/">

  <types>

    <xsd:schema
     targetNamespace="http://www.acmebooks.com/b2bbooks/BookQuote">
      <!-- The ISBN simple type -->
      <xsd:simpleType name="ISBN">
        <xsd:restriction base="xsd:string">
          <xsd:pattern value="[0-9]{9}[0-9Xx]" />
        </xsd:restriction>
      </xsd:simpleType>

    </xsd:schema>

  </types>

  <!-- message elements describe the input and output parameters -->
  <message name="GetBookPriceRequest">
    <part name="isbn" type="mh:ISBN" />
  </message>
  <message name="GetBookPriceResponse">
    <part name="price" type="xsd:float" />
  </message>
  ...
</definitions>
The listing shows the complete W3C XML schema document nested directly in the types element. We have defined a custom simple type, labeled ISBN, and assigned it to the mh namespace by the XML schema targetNamespace attribute. Now we use the mh:ISBN type to define the isbn part of the GetBookPriceRequest message definition.

Note that the targetNamespace attribute of the XML schema must be a valid non-null value, otherwise the types and element are considered to not belong to a valid namespace. Also the XML schema defined in the types element must belong to a namespace either specified by the WSDL document or imported into the WSDL document. This ensures that the WSDL document is aware of any and all namespaces used in the document.

The import Element
The <import> element is similar to the #include directive in the C/C++ programming language. It allows you to separate the elements of a service definition into independent WSDL documents and include them in the main document, where appropriate. Effective use of the <import> element promotes the modularization of WSDL documents and creates an environment of reuse that can create clear service definitions. For example, you may want to maintain separate WSDL documents for shipping and order processing but also maintain a complete definition of all Web services in a public directory accessible by business partners. This is shown in the following example:
XML Code: Import Elements Example
<definitions name="AllMhWebServices"
 xmlns="http://schemas.xmlsoap.org/wsdl/">

    <import namespace="http://www.acmebooks.com/b2bbooks/BookQuote"
     location="http://www.acmebooks.com/b2bbooks/BookPrice.wsdl"/>
    <import namespace="http://www.acmebooks.com/b2bbooks/po"
     location="http://www.acmebooks.com/b2bbooks/wsdl/PurchaseOrder.wsdl"/>
    <import namespace="http://www.acmebooks.com/b2bbooks/Shipping"
     location="http://www.acmebooks.com/b2bbooks/wsdl/Shipping.wsdl"/>

</definitions >
The WSDL import element has two attributes: namespace and location. The value of the namespace attribute should match the targetNamespace declared by the WSDL document being imported. The location attribute should point to an actual WSDL document that is not empty or null. The location is considered a hint since if the WSDL document has been cached or stored locally, the application reading the WSDL document may use that instance instead.

The main issue with the use of import is the possibility of creating versioning problems. When WSDL documents are maintained separately, the is a risk that an imported document will be changed without any regard for the WSDL documents that import it. You need to define some way of ensuring that changes are not made to imported WSDL documents without considering their impact. The best way to do this is to develop some versioning mechanism to ensure compatibility. Also you can use import and types together, but you need to list the import elements before the types element in a WSDL document.

To clarify confusion about the use of the WSDL import element, the WS-I Basic Profile 1.1 specifies that a WSDL import element may refer only to WSDL documents. If you want to import an XML schema element, do this in the XML schema definition contained in the WSDL types element via the standard XML schema import statement. Finally, you cannot use the XML schema import statement to import an XML schema directly from the types element of some other WSDL document.

WSDL Abstract Interface

This section describes the abstract interface of the Web Service. Here we list the message, portType, and operation elements for the abstract interface. The portType combines the operation and message definitions into an abstract interface that is analogous to a Java interface definition. The portType describes the kinds of operations that a Web service supports using the messaging mode and payloads while not specifying the Internet protocol or address being used.

The message Element

The message element is used to describe the payload of a message used by a Web service. A message element can describe the payloads of either outgoing or incoming messages. These are the messages that are sent directly to or received from a Web service. The message element can also describe the contents of SOAP header blocks and fault detail elements. This is dependent n whether the message element uses RPC-style or document-style messaging.

Message Element with RPC-Style Web Services

For RPC-style messaging, message elements describes the payloads of the SOAP request and reply messages. They are basically the call parameters, call return values, header blocks, or faults. In the BookQuote Web service, there are two message elements used to describe the parameters and return value of the service. This is shown in the listing below:

XML Code: RPC Style Message Element Descriptions
<!-- message elements describe the input and output parameters -->
<message name="GetBookPriceRequest">
  <part name="isbn" type="xsd:string" />
</message>
<message name="GetBookPriceResponse">
  <part name="price" type="xsd:float" />
</message>
In this listing, the GetBookPriceRequest message represents the input parameters while GetBookPriceResponse represents the output parameters. This is the payload of the message transmitted from a SOAP client to the BookQuote Web service by the GetBookPriceRequest message definition and the he payload of the message transmitted by the BookQuote Web service back to the client is described in the GetBookPriceResponse message definition.

In RPC-style messaging, messages generally have multiple parts. An example of this is shown for the GetBulkBookPriceRequest message which as multiple part elements each representing a different parameter:

XML Code: RPC-style Messaging with Multiple Parts
<definitions name="BookPrice" ...>
  ...
  <message name="GetBulkBookPriceRequest">
    <part name="isbn" type="xsd:string"/>
    <part name="quantity" type="xsd:int"/>
  </message>
  <message name="GetBulkBookPriceResponse">
    <part name="price" type="mh:prices" />
  </message>
  ...
</definitions>
Message Element with Document-Style Web Services

When using document-style messaging, the message definition now refers to the top-level element in the types definition. The best way to show this is with an example. Returning to the idea of a BookQuote Web Service, below we show a WSDL document describing a SubmitPurchaseOrder Web Service. We import a Purchase Order schema into the types element of the WSDL document. The Web service is using One-Way messaging meaning that there is no reply message.


XML Code: Document-Style Message Using the XML Schema Import
<?xml version="1.0" encoding="UTF-8"?>
<definitions name="PurchaseOrderWS"
 targetNamespace="http://www.acmebooks.com/b2bbooks/PO"
 xmlns:mh="http://www.acmebooks.com/b2bbooks/PO"
 xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns="http://schemas.xmlsoap.org/wsdl/">

  <types>
    <xsd:schema targetNamespace="http://www.acmebooks.com/b2bbooks/PO">
      <!-- Import the PurchaseOrder XML schema document -->
      <xsd:import namespace="http://www.acmebooks.com/b2bbooks/PO"
       schemaLocation="http://www.acmebooks.com/b2bbooks/po.xsd" />
    </xsd:schema>
  </types>
  <!-- message elements describe the input and output parameters -->
  <message name="SubmitPurchaseOrderMessage">
    <part name="order" element="mh:purchaseOrder" />
  </message>
  ...
</definitions>
You can use a message part to declare either a type attribute or an element attribute. Itís use depends on the type of messaging you're doing. For RPC-style messaging, the part elements must use the type attribute; for document-style messaging, the part elements must use the element attribute. RPC-style messaging uses types to define procedure calls, where each element represents a type of parameter. Document-style messaging use an exchange of XML document fragments and refers to their top-level (global) elements.

Declaring Fault Messages

Message definitions can be used to declare faults in the same manner they are used to declare input and output messages. The example below show the definition of a fault message that is sent back if a BookQuote request message containing an invalid ISBN:

XML Code: Declaring a Fault Message
<definitions name="BookQuote" ...>
  <types>
    <xsd:schema targetNamespace="http://www.acmebooks.com/b2bbooks/PO">
      <!-- Import the PurchaseOrder XML schema document -->
      <xsd:element name="InvalidIsbnFaultDetail" >
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="offending-value" type="xsd:string"/>
            <xsd:element name="conformance-rules" type="xsd:string" />
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </types>
  <!-- message elements describe the input and output parameters -->
  <message name="GetBookPriceRequest">
    <part name="isbn" type="xsd:string" />
  </message>
  <message name="GetBookPriceResponse">
    <part name="price" type="xsd:float" />
  </message>
  <message name="InvalidArgumentFault">
    <part name="error_message" element="mh:InvalidIsbnFaultDetail" />
  </message>
</definitions>
Note that the listing includes one single part, an error message.

The portType Element

The <portType> element specifies the subset of operations supported for a particular endpoint of a web service. A <portType> element provides a unique identifier to a group of actions that can be executed at a single endpoint. In WSDL the portType is implemented by the binding and service elements that dictate the Internet protocols, encoding schemes, and Internet address that is used by a Web service. The "methods" of the portType are its operation elements. This element is an abstract definition of an action supported by a web service. A portType may have one or more operation elements each defining an RPC- or document-style Web service method. Each operation is composed of at most one input or output element and any number of fault elements.

There is not a perfect analogy between a WSDL portType and a Java interface despite the fact that most Java-based Web service code generators create mappings between Java interfaces and WSDL portType elements. They generally generate Java interfaces from WSDL portType elements but could be used to generate WSDL portType, operation, and message elements from simple Java interfaces.

A WSDL document may have a number of portType elements which are used to describe the abstract interface different Web services. We could for example, have a WSDL Web service that defined one portType named "BookQuote" and another named "SubmitPurchaseOrder".

The operation Element

The <operation> element is used to represent an operation. It is an abstract definition of an action supported by a web service. The WSDL <operation> element is analogous to a Java method definition. Each operation element declared for a portType uses one or more message definitions to define its input, output, and faults. In the example below, we show the "BookQuote" portType declaring the GetBookPriceRequest as its input, GetBookPrice Response as its output, and InvalidArgumentFault as its fault:

XML Code: Operation Element with Input, Output, and Fault Messages in a portType
<portType name="BookQuote">
  <operation name="getBookPrice">
     <input name="isbn" message="mh:GetBookPriceRequest"/>
     <output name="price" message="mh:GetBookPriceResponse"/>
     <fault name="InvalidArgumentFault" message="mh:InvalidArgumentFault"/>
  </operation>
</portType>
In this listing, the input message is used to represent the payload sent to the Web service, the output message is used to represents the payload sent to the client and the fault message is used to represent the fault that may be sent to the client. For RPC-style messaging the input is the request, and the output is the response. For document-style messaging the input is the XML document fragment sent to the Web service, and the output is the XML document fragment sent back to the client. Finally the operation may include zero or more fault messages, each of which describes a different kind of error.

WSDL Messaging Exchange Patterns

There are four message exchange patterns (MEPs) used in Web services: Request/Response, One-Way, Notification, and Solicit/Response. Only the first two are supported by the Basic Profile as well as in JEE Web Services. A WSDL document dictates the MEP for a specific operation by the manner that it declares its input and output elements.

Request/Response Messaging

In Request/Response messaging exchange pattern, the client initiates the communication by sending a request message to the Web service and the Web service replies with a response message. If you declare an operation with a single input element followed by a single output element then it is considered a Request/Response operation and defined as such. The input listing indicates that in the operation the Web service receives a message sent initially by the client. The output listing indicates that the Web service should respond to the message. The order of the listing determines which operation will be done first. The following example shows a classic Request/Response operation with exactly one input and one output:

XML Code: Classic Request/Response MEP for Web Service
<!-- portType element describes the abstract interface of a Web service -->
<portType name="BookQuote">
  <operation name="getBookPrice">
    <input name="isbn" message="mh:GetBookPriceRequest"/>
    <output name="price" message="mh:GetBookPriceResponse"/>
  </operation>
</portType>
You also have the option of including fault elements that will be returned to the client in the case of an error. A Request/Response operation can have zero or more faults. This is shown in the following listing

XML Code: Request/Response MEP for Web Service with Faults
<portType name="BookQuote">
  <operation name="getBookPrice">
     <input name="isbn" message="mh:GetBookPriceRequest"/>
     <output name="price" message="mh:GetBookPriceResponse"/>
     <fault name="InvalidArgumentFault" message="mh:InvalidArgumentFault"/>
     <fault name="SecurityFault" message="mh:SecurityFault"/>
  </operation>
</portType>
One-Way Messaging

One-Way messaging is defined by the client sending a message to a Web service without any reply message. This MEP is typical of asynchronous messaging. If an operation is declared with only a single input and no output, it is considered a One-Way operation. The listing of only an input message indicates that clients using this operation will send messages to the Web service without expecting a response. This is shown in the following listing:

XML Code: Classic One-Way MEP for Web Services
<portType name="SubmitPurchaseOrder_PortType">
  <operation name="SubmitPurchaseOrder">
     <input name="order" message="mh:SubmitPurchaseOrderMessage"/>
  </operation>
</portType>
As One-Way operations cannot specify fault elements and donít generate fault messages, this messaging model is strictly unidirectional.

The binding Element

A binding element is a concrete protocol and data format specification for a portType element. It is uses one of the standard binding extensions such as HTTP, SOAP, or MIME or a custom protocol to map it to a portType. It maps an abstract portType to a set of concrete protocols such as SOAP and HTTP, messaging styles (RPC or document), and encoding styles (Literal or SOAP Encoding). The binding element is used in combination with protocol-specific elements to identify which portType and operation elements are being bound, while the protocol-specific elements declare the protocol and encoding style to be associated with the portType. Each type of protocol (SOAP, MIME, and HTTP) has its own set of protocol-specific elements and its own namespace. An example of this is shown below using the binding between the "BookQuote" portType to the SOAP 1.1 protocol using SOAP-specific protocol elements:

XML Code: Binding between portType and SOAP Protocol
<?xml version="1.0" encoding="UTF-8"?>
<definitions name="BookQuoteWS"
 targetNamespace="http://www.acmebooks.com/b2bbooks/BookQuote"
 xmlns:mh="http://www.acmebooks.com/b2bbooks/BookQuote"
 xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns="http://schemas.xmlsoap.org/wsdl/">
  ...
  <!-- binding tells us which protocols and encoding styles are used -->
  <binding name="BookPrice_Binding" type="mh:BookQuote">
    <soapbind:binding style="rpc"
     transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="getBookPrice">
      <soapbind:operation style="rpc"
       soapAction=
       "http://www.acmebooks.com/b2bbooks/BookQuote/GetBookPrice"/>
        <input>
          <soapbind:body use="literal"
           namespace="http://www.acmebooks.com/b2bbooks/BookQuote" />
        </input>
        <output>
          <soapbind:body use="literal"
           namespace="http://www.acmebooks.com/b2bbooks/BookQuote" />
        </output>
    </operation>
  </binding>
  ...
</definitions>
Note that the binding element declaration in the above listing is actually composed of two different namespaces. The elements such as binding, operation, input and output are without a namespace prefix are automatically members of the WSDL 1.1 namespace "http://schemas.xmlsoap.org/wsdl/", since this is the default namespace for the WSDL document. The other body elements such as soapbind:binding, soapbind:operation, and soapbind:body are members of the namespace for the SOAP-WSDL binding, "http://schemas.xmlsoap.org/wsdl/soap/". The soapbind:binding and soapbind:body elements are used for expressing the SOAP-specific details of the Web service. The soapbind:binding element indicates that the messaging style is RPC and that the network application protocol is HTTP. The soapbind:body element indicates that both the input and output messages use literal encoding. The children of the binding element (i.e. operation, input, and output) map directly to the corresponding children of the portType element.In the table below is the elements of the SOAP binding extension:

Tutorial:Review of WSDL Document for the Web Service Developer Exam-b3-soapbindingextensions.jpg
Table: SOAP Binding Extensions

The WSDL specification defines two other protocol-specific binding besides the one for SOAP binding elements. This is for HTTP and MIME. An example of this is shown in the listing below:

XML Code: HTTP/MIME-binding of BookQuote
<binding name="BookPrice_HttpMimeBinding" type="mh:BookQuote">
   <http:binding verb="GET"/>
   <operation name="getBookPrice">
      <http:operation location="alt.http.service"/>
      <input>
         <http:urlEncoded/>
      </input>
      <output>
         <mime:content type="text/html"/>
      </output>
   </operation>
</binding>
Although WSDL 1.1 allows the use of MIME and HTTP bindings were not supported in the Basic Profile 1.0, as of Basic Profile 1.1, the support was extended to SwA including MIME binding. SwA relies on the MIME standard, which introduces a second packaging standard on top of the SOAP envelope.

WSDL Implementation

At the end of the WSDL implementation is the service and port elements. This will define the last section of your WSDL document.

The service element

A <service> element is used for describing the actual endpoint of a service. It typically appears at the end of a WSDL document and identifies a web service. The service element is a grouping of one or more port elements, each of which represents a different Web service. The port element assigns the URL to a specific binding. The example below shows a service definition based on our previous listing for the BookQuote Web Service:

XML Code: Service Element Definition for BookQuote Web Service
<service name="BookPriceService">
  <port name="BookPrice_Port" binding="mh:BookPrice_Binding">
    <soapbind:address location=
     "http://www.acmebooks.com/b2bbooks/BookQuote" />
  </port>
</service>
Since a service can have more than one port element, each assigning a URL to a specific binding. It's possible for two or more port elements to assign different URLs for the same binding. This configuration can be useful in providing features such as load balancing or failover. An example of this is shown below for a service element containing three port elements with two of them referring to the same binding.

XML Code: Defining a service with Multiple port Elements
<service name="BookPriceService">
  <port name="BookPrice_Port" binding="mh:BookPrice_Binding">
    <soapbind:address location=
     "http://www.acmebooks.com/b2bbooks/BookQuote" />
  </port>
  <port name="BookPrice_Failover_Port" binding="mh:BookPrice_Binding">
    <soapbind:address location=
     "http://www.monson-haefel.org/jwsbook/BookPrice" />
  </port>
  <port name="SubmitPurchaseOrder_Port"
   binding="mh:SubmitPurchaseOrder_Binding">
    <soapbind:address location=
     "https://www.monson-haefel.org/jwsbook/po" />
  </port>
</service>
The soapbind:address Element

The soapbind:address element assigns an Internet address to a SOAP binding via its location attribute. This is because the Basic Profile allows URLs that use only HTTP or HTTPS schemas despite WSDL allowing any type of address (i.e. HTTP, FTP, SMTP, and so on) to be used. In the listing above, the location attribute for the first two port elements is an HTTP address while the third port has an HTTPS address. Note that you cannot have two or more port elements within the same WSDL document specify the same URL value for the location attribute of the soapbind:address.

WS-I Conformance Claims

A WS-I conformance claim is used in a WSDL definition to assert adherence to the WS-I Basic Profile 1.1 specification. There is an inheritance property that exists so child elements will inherit their parents' conformance claims. For example, a portType's claim of conformance to the Basic Profile 1.1 applies as well to all the operation and message definitions associated with that portType. You should put conformance claim inside the port definition since it applies to all the other definitions associated with that port such as binding, portType, operation, and message.

Best Practice

The key thing to remember about WSDL is that it is a precise, structured, and standard format for describing Web services. The advantage of this is that for both vendors creating code generators and developers using SOAP APIs, it allows vendors to offer tools that automatically generate callable interfaces to a specific Web service, and enables developers using SOAP APIs to construct, deliver, and process SOAP messages correctly when using lower-level APIs like SAAJ.

Often the nature of WSDL Web Services and its format means that many developers make the error with with WSDL of defining operations and messages that are too fine-grained. You need to ensure that you define coarse-grained web services that are business oriented and not program-oriented. OK. That is it for WSDL Web Services. In the next article we will cover UDDI.