Defining Web Services Using WSDL


In order for others to be able to interact with the Web services that you build or simply to enable them to interact with the Web services that any of your client applications might need to consume, you need some sort of description of the Web service. This description is provided through the use of a Web Services Description Language (WSDL) document. This file is also known as Wiz-dull, but you can call it what you want. A WSDL document is an XML document that describes the Web service and can be used by any consuming application.

As you have already seen in this chapter, you are usually required to interact with WSDL files before you start working with the Web services you are interested in consuming. The WSDL document is an important part of any Web service that you want to expose to consumers. This document describes to the end user, the consumer of your Web service, what parameters need to be passed into the Web service. It also tells the users what they should expect to get in return.

Version 1 of the Web Service Description Language specification was finished in the fall of 2000 by a group of companies, including IBM and Microsoft, to help define the Web services that people were building on their systems. The whole concept of Web services demands interoperability; therefore, it made sense for system competitors to sit down together to figure out how their respective Web services can describe themselves to client applications, regardless of their platforms. Luckily these companies realized the best way to achieve the goal of interoperability is to have just one standard in place. Consequently, they have worked together on a standard format to describe the interfaces of Web services that we can all use-WSDL.

In the beginning this wasn't so. At first, both IBM and Microsoft introduced their own Web service description languages. IBM called its standard NASSL, Network Accessible Service Specification Language. Microsoft also had a version called SCL, Service Contract Language. Both these specifications described the Web services on their respective systems, but these two specifications were not able to understand one another. Therefore, people on a Microsoft system were unable to understand NASSL, and people on any IBM or Java system were unable to understand SCL. The difficulties that ensued caused both companies to see the light and to come together to develop WSDL.

WSDL took hold and has now gone on to version 1.1, which was submitted to the World Wide Web Consortium (http://www.w3.org/tr/wsdl) in March of 2001.

The diagram shown in Figure 20-16 demonstrates how WSDL fits in with the rest of the Web service technology pillars discussed so far.

image from book
Figure 20-16

You are building client applications that must interact with Web services. You figure out how to perform these interactions by using the formal service description WSDL. Of course, you are never absolutely required to use WSDL files as a means of providing a description of the interface-you have other more informal ways to do this. There are, however, good reasons for you to have a WSDL file in place and to allow consumers to interact with it. First and foremost, it provides a standard way to understand the interface. By having a standard in place, it is possible to build tools that can interact with these WSDL documents on the developer's behalf. Having a standard means that these tools know what to expect from a WSDL document and, therefore, perform all the operations that are required to interact with the defined Web service. For instance, when working with Visual Studio and the .NET Framework, these technologies will build a proxy class on your behalf to take care of marshalling the SOAP messages back and forth to the Web service. If the WSDL document doesn't follow any standard, the tools could have problems interacting with the document. As a result, you might be required to build a proxy class by hand. WSDL documents are created in different ways depending on the platform on which you are building your Web services. If you are using the .NET Framework, the WSDL document is generated for you dynamically. Other platforms, such as J2EE, also provide you with the necessary tools for automatic WSDL generation.

An example of a simple Web service's WSDL file is shown in Listing 20-17. This Web service, called Calculator, has only two methods: Add() and Subtract(). The interfaces of both methods are defined in the WSDL document. You review all the parts of this document in the rest of this chapter.

Listing 20-17: The WSDL document for the Calculator Web service

image from book
      <?xml version="1.0" encoding="utf-8"?>      <wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"       xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"       xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"       xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"       xmlns:tns="http://www.wrox.com/ws" xmlns:s="http://www.w3.org/2001/XMLSchema"       xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"       xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"       targetNamespace="http://www.wrox.com/ws"       xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">       <wsdl:types>         <s:schema elementFormDefault="qualified"          targetNamespace="http://www.wrox.com/ws">           <s:element name="Add">             <s:complexType>               <s:sequence>                 <s:element minOccurs="1" maxOccurs="1" name="a" type="s:int" />                 <s:element minOccurs="1" maxOccurs="1" name="b" type="s:int" />               </s:sequence>             </s:complexType>           </s:element>           <s:element name="AddResponse">             <s:complexType>               <s:sequence>                 <s:element minOccurs="1" maxOccurs="1" name="AddResult" type="s:int"               </s:sequence>             </s:complexType>           </s:element>           <s:element name="Subtract">             <s:complexType>               <s:sequence>                 <s:element minOccurs="1" maxOccurs="1" name="a" type="s:int" />                 <s:element minOccurs="1" maxOccurs="1" name="b" type="s:int" />               </s:sequence>             </s:complexType>           </s:element>           <s:element name="SubtractResponse">             <s:complexType>               <s:sequence>                 <s:element minOccurs="1" maxOccurs="1" name="SubtractResult"                  type="s:int" />               </s:sequence>             </s:complexType>           </s:element>            </s:schema>        </wsdl:types>        <wsdl:message name="AddSoapIn">          <wsdl:part name="parameters" element="tns:Add" />        </wsdl:message>        <wsdl:message name="AddSoapOut">          <wsdl:part name="parameters" element="tns:AddResponse" />        </wsdl:message>        <wsdl:message name="SubtractSoapIn">          <wsdl:part name="parameters" element="tns:Subtract" />        </wsdl:message>        <wsdl:message name="SubtractSoapOut">          <wsdl:part name="parameters" element="tns:SubtractResponse" />        </wsdl:message>        <wsdl:portType name="CalculatorSoap">          <wsdl:operation name="Add">          <wsdl:input message="tns:AddSoapIn" />          <wsdl:output message="tns:AddSoapOut" />        </wsdl:operation>        <wsdl:operation name="Subtract">          <wsdl:input message="tns:SubtractSoapIn" />          <wsdl:output message="tns:SubtractSoapOut" />        </wsdl:operation>      </wsdl:portType>      <wsdl:binding name="CalculatorSoap" type="tns:CalculatorSoap">        <soap:binding transport="http://schemas.xmlsoap.org/soap/http" />        <wsdl:operation name="Add">          <soap:operation soapAction="http://www.wrox.com/ws/Add" style="document" />          <wsdl:input>            <soap:body use="literal" />          </wsdl:input>          <wsdl:output>            <soap:body use="literal" />          </wsdl:output>        </wsdl:operation>        <wsdl:operation name="Subtract">          <soap:operation soapAction="http://www.wrox.com/ws/Subtract"           style="document" />          <wsdl:input>            <soap:body use="literal" />          </wsdl:input>          <wsdl:output>            <soap:body use="literal" />          </wsdl:output>        </wsdl:operation>      </wsdl:binding>      <wsdl:binding name="CalculatorSoap12" type="tns:CalculatorSoap">        <soap12:binding transport="http://schemas.xmlsoap.org/soap/http" />        <wsdl:operation name="Add">          <soap12:operation soapAction="http://www.wrox.com/ws/Add" style="document" />          <wsdl:input>            <soap12:body use="literal" />          </wsdl:input>          <wsdl:output>            <soap12:body use="literal" />          </wsdl:output>        </wsdl:operation>        <wsdl:operation name="Subtract">          <soap12:operation soapAction="http://www.wrox.com/ws/Subtract"           style="document" />          <wsdl:input>            <soap12:body use="literal" />          </wsdl:input>          <wsdl:output>            <soap12:body use="literal" />          </wsdl:output>        </wsdl:operation>        </wsdl:binding>          <wsdl:service name="Calculator">          <wsdl:port name="CalculatorSoap" binding="tns:CalculatorSoap">            <soap:address location="http://localhost:1780/XMLWS/Calculator.asmx" />          </wsdl:port>          <wsdl:port name="CalculatorSoap12" binding="tns:CalculatorSoap12">            <soap12:address location="http://localhost:1780/XMLWS/Calculator.asmx" />          </wsdl:port>        </wsdl:service>      </wsdl:definitions> 
image from book

Yes, it is a bit lengthy, but it is worth it. You should become familiar with a WSDL document so that you can read it to determine what the Web service needs to run effectively. You might be wondering why you need to do this if the development environments out there can so easily review and interpret these documents for you. Actually, you have a lot of reasons to learn how a WSDL document works.

One reason is that when you are dealing with a Web service, you might not always have access to either the IDEs or development environments you are working with. In such a case, you benefit by being able to open up the WSDL document so you can understand what is going on.

One of the biggest reasons to know how the WSDL file works, however, is that (as all programmers should know by now) developers are not always perfect. Most likely, some WSDL documents out there have errors in them. If this is the case, you want to be able to open up the WSDL document and find the error so that you can modify the document and use it in your applications.

The Structure of WSDL Documents

The WSDL document that was reviewed earlier is a complete WSDL document based on a Calculator Web service with two simple methods. When looking over the code of the WSDL document, you should note that the WSDL document is just a list of definitions using XML grammar.

This grammar is used to describe the protocols that are needed to communicate with the Web service, discover the Web service's interface, and learn the location of the Web service. The grammar of WSDL describes message network endpoints or ports. The diagram in Figure 20-17 shows the message structure of a WSDL document.

image from book
Figure 20-17

Starting from the top of the diagram in Figure 20-17, the first level of the WSDL document contains the services. Each service description refers to the Web service that the end user wants to invoke within his client applications. The service includes all the available methods that the creator of the Web service has exposed or the collection of available endpoints.

Beyond this is the port. The port is referenced from the service and points to the network address of an endpoint and all the bindings that the endpoint adheres to. For example, a Web service might have a port description of multiple bindings such as SOAP, HTTP-POST, and HTTP-GET.

The binding describes the transport and encoding particulars for a portType. The portTypes refer to the operations anticipated by a particular endpoint type, without any specifics relating to transport or encoding.

The operation details all the messages that are involved in dealing with the service at the endpoint. For instance, a Web service that returns a value after a request entails two messages, a request and a response. Each message makes a reference to XSD Schemas to detail the different parts of the message. Each piece of data that makes up part of a message is referred to as a part.

Next, take a look at each of the parts of the WSDL document so you can better understand what is going on.

<definitions>

The WSDL document contains a root element, just like other XML documents. Directly preceding the start of the <definitions> element is the XML declaration.

      <?xml version="1.0" encoding="utf-8"?> 

This specifies what the WSDL document truly is-an XML file. The next line in the WSDL document is the root element, <definitions>. The code in Listing 20-18 shows the <definitions> element for the earlier WSDL file.

Listing 20-18: Breaking down the <definitions> element

image from book
      <wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"       xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"       xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"       xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"       xmlns:tns="http://www.wrox.com/ws" xmlns:s="http://www.w3.org/2001/XMLSchema"       xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"       xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"       targetNamespace="http://www.wrox.com/ws"       xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">      </wsdl:definitions> 
image from book

The <definitions> element includes a number of namespaces. The following table describes some of the namespaces that you might see in various WSDL documents.

Open table as spreadsheet

Prefix

Namespace URI

Definition

wsdl

http://www.schemas.xmlsoap.org/wsdl/

WSDL namespace for WSDL framework.

soap

http://www.schemas.xmlsoap.org/wsdl/soap/

WSDL namespace for WSDL SOAP 1.1 binding.

soap12

http://www.schemas.xmlsoap.org/wsdl/soap12/

WSDL namespace for WSDL SOAP 1.2 binding.

http

http://www.schemas.xmlsoap.org/wsdl/http/

WSDL namespace for WSDL HTTP GET & POST binding.

mime

http://www.schemas.xmlsoap.org/wsdl/mime/

WSDL namespace for WSDL MIME binding.

soapenc

http://www.schemas.xmlsoap.org/soap/encoding/

Encoding namespace as defined by SOAP.

soapenv

http://www.schemas.xmlsoap.org/soap/envelope/

Envelope namespace as defined by SOAP.

xsi

http://www.w3.org/2000/10/XMLSchema-instance

Instance namespace as defined by XSD.

xsd

http://www.w3.org/2000/10/XMLSchema

Schema namespace as defined by XSD.

tns

(various)

The "this namespace" (tns) prefix is used as a convention to refer to the current document.

Along with these namespaces, you also have the option (not shown in this example) of using the attribute name within the <definitions> element. If you use this example, the name attribute could take the following form:

      <lit><definitions name="Calculator" ... 

This really doesn't have any purpose except to provide some sort of lightweight description for any user who might be looking at the WSDL document and trying to figure out the overall purpose of the Web service that he is trying to consume. Another optional element that is used in the example is targetNamespace. This attribute defines the namespace for each of the items in the WSDL document. This means that all the elements contained within this WSDL file belong to this namespace, much the same as a targetNamespace declaration in an XSD file. Along with the targetNamespace are a number of other namespaces for HTTP-POST, HTTP-GET, and SOAP binding, as well as for MIME.

<types>

In the WSDL example from the Calculator Web service, a couple of types are defined. These are shown in Listing 20-19.

Listing 20-19: Breaking down the <types> element

image from book
      <wsdl:types>        <s:schema elementFormDefault="qualified"         targetNamespace="http://www.wrox.com/ws">          <s:element name="Add">            <s:complexType>              <s:sequence>                <s:element minOccurs="1" maxOccurs="1" name="a" type="s:int" />                <s:element minOccurs="1" maxOccurs="1" name="b" type="s:int" />              </s:sequence>            </s:complexType>          </s:element>          <s:element name="AddResponse">            <s:complexType>              <s:sequence>                <s:element minOccurs="1" maxOccurs="1" name="AddResult" type="s:int" />              </s:sequence>            </s:complexType>          </s:element>          <s:element name="Subtract">            <s:complexType>              <s:sequence>                <s:element minOccurs="1" maxOccurs="1" name="a" type="s:int" />                <s:element minOccurs="1" maxOccurs="1" name="b" type="s:int" />              </s:sequence>            </s:complexType>          </s:element>          <s:element name="SubtractResponse">            <s:complexType>              <s:sequence>                <s:element minOccurs="1" maxOccurs="1" name="SubtractResult"                 type="s:int" />              </s:sequence>            </s:complexType>          </s:element>        </s:schema>      </wsdl:types> 
image from book

The information within the <types> element includes the type definitions that are needed in the message exchange. In order to define these types, you should use the XML Schema Definition Language (XSD). The XSD language is described in detail in Chapter 6.

XSD is used to provide the most interoperability possible to a Web service by using a language that is widely accepted as the standard way of describing types within XML documents.

The code example from Listing 20-19 starts with the definition of the types that are required for the Add() and Subtract() methods. For both methods, you first find a parameter, which is of type int. The second parameter is the b parameter, which is also of type int. It is possible to fully describe various complex types and the sequence of these types using XSD within the <types> element of the WSDL document.

In the end, what's being returned from both methods is a single item of the type int. This message is defined by AddResponse and SubtractResponse. Notice that the inbound message has the same name as the method that it is exposing (in this case, Add or Subtract), and the outbound message has the same name as the method, but with the word Response appended to it (in this case, AddResponse or SubtractResponse).

Note 

A large number of types are at your disposal. Be sure to review the available types by looking back on Chapter 6. If you are going to be passing back an undefined type, be sure to use the type anyType in the following manner: type=“s:anyType”. This represents a parameter of any type.

<message>

Messages consist of one or more parts. The sample WSDL document uses a number of different <message> elements which are presented in Listing 20-20.

Listing 20-20: Breaking down the <message> element

image from book
      <wsdl:message name="AddSoapIn">        <wsdl:part name="parameters" element="tns:Add" />      </wsdl:message>      <wsdl:message name="AddSoapOut">        <wsdl:part name="parameters" element="tns:AddResponse" />      </wsdl:message>      <wsdl:message name="SubtractSoapIn">        <wsdl:part name="parameters" element="tns:Subtract" />      </wsdl:message>      <wsdl:message name="SubtractSoapOut">        <wsdl:part name="parameters" element="tns:SubtractResponse" />      </wsdl:message> 
image from book

You see all the type definitions that play a role in the data that is being transported back and forth across the wire, but the <message> element is the piece of the pie that packages this up. The <message> element is protocol independent and is really only concerned with the message and all the parts of the message that are going to be sent and received.

The <message> element can have a single attribute, the name attribute. The name attribute is just that-a name. It doesn't really have any special meaning except that it provides a unique identifier among all messages defined within the enclosing WSDL document. In this example, all the messages have the name of the method, plus the protocol of the part. You can give the <message> elements any name that you choose, because WSDL makes no distinction about the name that is used, just as long as no naming conflicts exist among the messages.

You can think of the <part> elements as the payload of the messages. In the <message> example that is laid out, you can see a message for each request and response for each of the methods available. It is possible to have multiple <part> elements defining requests that cover both HTTP-GET and HTTP- POST messages, whereas the response information contains a single <part> element.

The SOAP <part> elements used in Listing 20-20 are interesting. If you use SOAP, the <part> elements basically correspond to the SOAP request or response. These <part> elements do not contain the parameter type definitions like the other <part> elements do, but instead they point to the type definitions that were defined in the <types> element earlier. Going back to this definition, you see a type definition for Add and AddResponse as well as for Subtract and SubtractResponse.

<portType>

The job of the <portType> element is to define all the operations that can be used. A port type is a set of certain abstract operations and the abstract messages involved.

The WSDL document example has a couple of different <portType> definitions, although it is possible to have a number more. The code shown in Listing 20-21 reviews these definitions.

Listing 20-21: Breaking down the <portType> element

image from book
      <wsdl:portType name="CalculatorSoap">        <wsdl:operation name="Add">          <wsdl:input message="tns:AddSoapIn" />          <wsdl:output message="tns:AddSoapOut" />        </wsdl:operation>        <wsdl:operation name="Subtract">          <wsdl:input message="tns:SubtractSoapIn" />          <wsdl:output message="tns:SubtractSoapOut" />        </wsdl:operation>      </wsdl:portType> 
image from book

The <portType> element can take a single attribute, the name attribute. This attribute provides you with a unique identifier for the <portType> element, so that this <portType> is set out from the other <portType> elements.

A single Web service can support a number of different protocols. The structure of the data depends on the protocol that you use to invoke the Web service. Because of this, you need a way to map from the operations to the endpoints from which they can be accessed. The <portType> element takes care of this mapping.

You can place a portType definition for each of the protocols available to you for this Web service. For instance, you can have individual portType definitions for using SOAP, HTTP-POST, and HTTP-GET. The operation name is the method available from the Web service. If other methods are available to you, additional <operation> elements would be defined as well.

For each <operation> element, you can also provide an optional <documentation> element. This element is discussed later in this chapter. The other elements that you can use within the <operation> element include <input>, <output>, and <fault>. Each <operation> can contain only one of each of these available elements. There can only be one input into a Web service, just as there can only be one output. Each of these three elements has a name and a message attribute.

The <input> element specifies the request to a Web service. The <output> element specifies the response of the Web service. The <fault> element details any error messages that may be output by the Web service.

<binding>

Now that you have definitions in place for the different logical ports at your disposal, you can define how the end user binds to a port where the operation is obtainable. You do this by using the <binding> element. The following code presented in Listing 20-22 is one of the two <binding> elements used in the sample WSDL document.

Listing 20-22: Breaking down the <binding> element

image from book
      <wsdl:binding name="CalculatorSoap" type="tns:CalculatorSoap">        <soap:binding transport="http://schemas.xmlsoap.org/soap/http" />        <wsdl:operation name="Add">          <soap:operation soapAction="http://www.wrox.com/ws/Add" style="document" />          <wsdl:input>            <soap:body use="literal" />          </wsdl:input>          <wsdl:output>            <soap:body use="literal" />          </wsdl:output>        </wsdl:operation>        <wsdl:operation name="Subtract">          <soap:operation soapAction="http://www.wrox.com/ws/Subtract"           style="document" />          <wsdl:input>            <soap:body use="literal" />          </wsdl:input>          <wsdl:output>            <soap:body use="literal" />          </wsdl:output>        </wsdl:operation>      </wsdl:binding> 
image from book

The <binding> that is shown in this example is using SOAP. The other binding that is in the main WSDL document includes a <binding> definition for SOAP 1.2.

The <binding> element contains a name attribute. This attribute's value is the name of the Web service class with the word SOAP attached to it. The <binding> element also contains a type attribute. This attribute is a reference to the <portType> name attribute that was used earlier.

<soap:binding>

The example from Listing 20-22 shows that a number of different elements are enclosed within the <binding> element. The first is the <soap:binding> element. By using this <soap:binding> element, you are specifying that this protocol is bound to the SOAP specification that uses a SOAP packet for transport. The SOAP packet is made up of the envelope, header, and body. The <soap:binding> element can contain two attributes. The first is the transport attribute. The transport attribute, a URI, specifies the protocol that is going to be used in transporting the SOAP packet. The value of this attribute in the example is http://www.schemas.xmlsoap.org/soap/http. This transport value is specifying that the SOAP packet will be transported over HTTP.

The style attribute enables you to specify one of the two available binding styles at your disposal. The optional values are rpc and document. The preceding example is using the style attribute with the value of document. A setting of document means that the SOAP will be transported using a single document message. Using rpc means that the SOAP message will be sent using an RPC-oriented operation. RPC messages are made up of parameters and return values. If a style value isn't specified, assume that document is the style setting.

<soap:operation>

Contained within the <operation> element is a <soap:operation> element. The <operation> element is associated with each of the available methods from the Web service. The <soap:operation> element is used to show how the operation should be bound. In this case, it is to the SOAP protocol. The soapAction attribute specifies the value of the SOAPAction header for this operation.

The style attribute is the same as it is in the <soap:body> element. The possible values of this attribute include both rpc and document.

The <soap:operation> element can take up to one <input> and one <output> element. Each <input> and <output> element can contain either a <soap:body>, <soap:header> or a <soap:headerfault>. The sample WSDL document that is used in this chapter contains only a <soap:body> element for both the <input> and <output> elements.

<soap:body>

The <input> or <output> element can contain a <soap:body> element. This indicates that the message parts are part of the SOAP body element. A number of available attributes can be used within the <soap:body> element.

In the example used in this chapter, the <soap:body> contains a use attribute. The use attribute specifies whether the message parts are being encoded. The possible values of the use attribute include encoded or literal.

The value encoded means that a URI is used to determine how the message is mapped to the SOAP body. If encoded is set as the value, an encodingStyle attribute must be present. The value of the encodingStyle attribute is a list of URIs, each divided by a single space. The URIs signify encoding used within the message, and they are ordered from the most restrictive to the least restrictive.

If literal is used as the value of the use attribute, the message parts represent a concrete schema definition. When this value is set to literal, the message parts are sent literally and not altered in the process.

<service>

The <service> element contains the endpoints for the Web service. The code shown in Listing 20-23 demonstrates this.

Listing 20-23: Breaking down the <service> element

image from book
      <wsdl:service name="Calculator">        <wsdl:port name="CalculatorSoap" binding="tns:CalculatorSoap">          <soap:address location="http://localhost:1780/XMLWS/Calculator.asmx" />        </wsdl:port>        <wsdl:port name="CalculatorSoap12" binding="tns:CalculatorSoap12">          <soap12:address location="http://localhost:1780/XMLWS/Calculator.asmx" />        </wsdl:port>      </wsdl:service> 
image from book

In this example, the Web service has two ports or endpoints. One available port is for SOAP 1.1 and another is for SOAP 1.2. The binding attribute in the <port> element points to the associated <binding> element. Contained within the <port> element is an <soap:address> child element that specifies the URI of the endpoint.

Like the other elements that are part of the WSDL document, the <port> element can also take a name attribute that allows it to have a unique identifier in order to differentiate itself from the other <port> elements.

<import>

Although not shown in any of the examples, you can use the <import> element within a WSDL document. Using the <import> element enables you to associate a namespace with a document location. The following code shows this:

      <definitions>         <import namespace="uri" location="uri"/>      </definitions> 

Basically you can actually import parts of another WSDL document directly into the WSDL document that you are working with. For instance, if you have a type definition in a separate file, your file should look like Listing 20-24:

Listing 20-24: The <types> section in its own WSDL file

image from book
      <wsdl:types>        <s:schema elementFormDefault="qualified"         targetNamespace="http://www.wrox.com/ws">          <s:element name="Add">            <s:complexType>              <s:sequence>                <s:element minOccurs="1" maxOccurs="1" name="a" type="s:int" />                <s:element minOccurs="1" maxOccurs="1" name="b" type="s:int" />              </s:sequence>            </s:complexType>          </s:element>          <s:element name="AddResponse">            <s:complexType>              <s:sequence>                <s:element minOccurs="1" maxOccurs="1" name="AddResult" type="s:int" />              </s:sequence>            </s:complexType>          </s:element>          <s:element name="Subtract">            <s:complexType>              <s:sequence>                <s:element minOccurs="1" maxOccurs="1" name="a" type="s:int" />                <s:element minOccurs="1" maxOccurs="1" name="b" type="s:int" />              </s:sequence>            </s:complexType>          </s:element>          <s:element name="SubtractResponse">            <s:complexType>              <s:sequence>                <s:element minOccurs="1" maxOccurs="1" name="SubtractResult"                 type="s:int" />              </s:sequence>            </s:complexType>          </s:element>        </s:schema>      </wsdl:types> 
image from book

You can now import this .wsdl file directly into the WSDL document that you are working on. The partial code example presented in Listing 20-25 shows how this is done.

Listing 20-25: A WSDL document containing an imported type definition

image from book
      <?xml version="1.0" encoding="utf-8"?>      <wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"       xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"       xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"       xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"       xmlns:tns="http://www.wrox.com/ws" xmlns:s="http://www.w3.org/2001/XMLSchema"       xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"       xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"       targetNamespace="http://www.wrox.com/ws"       xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">        <import namespace="http://www.wrox.com/ws"         location="http://localhost/SomeLocation/TypeDefinition.wsdl" />        <wsdl:message name="AddSoapIn">          <wsdl:part name="parameters" element="tns:Add" />        </wsdl:message>        <!-- The rest removed for clarity -->      </wsdl:definitions> 
image from book

This causes the types that are defined in a separate WSDL document to be planted in the spot where the <import> element is located. You may have pieces of a WSDL document that are easy to carve off and use numerous times in other WSDL documents.

The <import> element takes two attributes. The first is the namespace attribute and the second is the location attribute. The location attribute specifies the location of the actual file that you want to import into the WSDL document.

Using the <import> element properly enables you to separate your WSDL documents into reusable blocks that can be inserted when needed.

<documentation>

It is not always possible for the end user to figure out what is going on in a particular Web service by looking at the WSDL file or any Web services test page. One option to enable the Web service consumer to understand a Web service better is for the Web service developer to use the <documentation> element to further define the methods available. You can use this element to help others understand what is meant by the argument CityDays2007 in your method. The end user might be able to tell that the CityDays2007 takes an int, but he might not know the actually meaning of the argument. Even after testing it on the test page, he may be no closer to figuring it out.

It is always best to give as much information as possible if you want users to consume your Web services with a smile. Do this by providing documentation notes within your WSDL files, as well by using the <documentation> element.

The <documentation> element is allowed anywhere within the WSDL document. I advise you to use this element to place documentation information in as many places as possible to make it easier for end user to consume your Web services.

For instance, in the example used throughout this chapter, the <documentation> element is placed within the <operation> element in order to give the end user more information about what the operation actually does. The code presented in Listing 20-26 shows an example of this.

Listing 20-26: Using the <documentation> element in a WSDL file

image from book
      <wsdl:operation name="Add">        <documentation>Adds two numbers together for          the mathematically impaired.</documentation>        <wsdl:input message="tns:AddSoapIn" />        <wsdl:output message="tns:AddSoapOut" />      </wsdl:operation> 
image from book

The preceding code is somewhat self-explanatory. Because you know a little more about this particular operation, you also know how to work more effectively with the Web service you are looking to consume.




Professional XML
Professional XML (Programmer to Programmer)
ISBN: 0471777773
EAN: 2147483647
Year: 2004
Pages: 215

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net