home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Book HomeJava and XML, 2nd EditionSearch this book

13.3. WSDL

WSDL is the Web Services Description Language. The entire specification is online at http://www.w3.org/TR/wsdl, and describes everything you need to know about a service in order to interact with it. Like UDDI, it's a fairly simple piece of technology on its own (really, it's not even technology; it's just markup), but becomes extremely important in the overall web services picture. The WSDL file describes several critical pieces of information a service client would need:

  • The name of the service, including its URN

  • The location the service can be accessed at (usually an HTTP URL address)

  • The methods available for invocation

  • The input and output parameter types for each method

Each of these pieces of data on their own are fairly useless, but together, they represent the complete client picture of the service. Additionally, a WSDL document incorporates elements of XML Schema, XML-RPC-style parameters, and quite a bit of everything else you've read about so far. Example 13-1 is a portion of a WSDL schema for the CD catalog from the last chapter; it only describes the getCD( ) method of the service. It's not complete, but it should give you an idea of what a WSDL document looks like.

Example 13-1. Portion of a WSDL document

<?xml version="1.0"?>

<definitions name="CDCatalog"
             targetNamespace="http://www.oreilly.com/javaxml2/cd-catalog.wsdl"
             xmlns:cd="http://www.oreilly.com/javaxml2/cd-catalog.wsdl"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:cdXSD="http://www.oreilly.com/javaxml2/cd-catalog.xsd"
             xmlns="http://schemas.xmlsoap.org/wsdl/"
>
  <types>
    <schema targetNamespace="http://www.oreilly.com/javaxml2/cd-catalog.xsd"
            xmlns="http://www.w3.org/2000/10/XMLSchema">
      <element name="Title">
        <complexType>
          <all><element name="title" type="string" /></all>
        </complexType>
      </element>
      <element name="CD">
        <complexType>
          <all>
            <element name="title" type="string" />
            <element name="artist" type="string" />
            <element name="label" type="string" />
          </all>
        </complexType>
      </element>
    </schema>
  </types>

  <message name="getCDInput">
    <part name="body" element="cdXSD:Title" />
  </message>

  <message name="getCDOutput">
    <part name="body" element="cdXSD:CD" />
  </message>

  <portType name="CDCatalogPortType">
    <operation name="getCD">
      <input message="cd:getCDInput" />
      <output message="cd:getCDOutput" />
    </operation>
  </portType>

  <binding name="CDCatalogBinding" type="cd:CDCatalogPortType">
    <soap:binding style="rpc" 
                  transport="http://schemas.xmlsoap.org/soap/http" />
    <operation name="getCD">
      <soap:operation soapAction="urn:cd-catalog" />
      <input>
        <soap:body use="encoded"
            encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
            namespace="urn:cd-catalog" />
      </input>
      <output>
        <soap:body use="encoded"
            encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
            namespace="urn:cd-catalog" />
      </output>
    </operation>
  </binding>

  <service name="CDCatalog">
    <documentation>CD Catalog Service from Java and XML</documentation>
    <port name="CDCatalogPort" binding="cd:CDCatalogBinding">
      <soap:address location="http://newInstance.com/soap/servlet/rpcrouter" />
    </port>
  </service>
</defintions>

As you can see, this is a fairly verbose format for describing a service; however, it's also easy to understand. First, any types that must be passed across the wire are described using the types element, and an XML Schema-style syntax.

WARNING: Currently, WSDL specifications are using the 2000 version of the XML Schema specification, and not the finalized April 2001 XML Schema specification. You'll need to use the slightly older schema constructs until the WSDL specification is brought completely up to date.

Next, the message element is used to define interaction from the client to the server, and the server to the client. These are combined in the portType element to define available operations (you would find additional available methods in this section as well). The binding element details how the operations can be accessed and the URN where they are accessible, and the service element brings all of this together. Thinking about this process as a hierarchy will help keep everything straight in your head.

SOAP's All You Got?

Don't get the idea that a SOAP service is the only type of web service around. It's certainly possible to build a program (or programs) that interact with clients through some other means, and represent that interaction through a WSDL file. For example, an XML-RPC service fits the bill pretty nicely; even though it doesn't have an envelope and custom parameter support, it still can easily interact with clients and represent its input and output parameters in WSDL. However, almost all the services I've seen (and I've seen a lot!) are SOAP, so it is certainly the overriding trend. Still, keep in the back of your mind the ability to use any program as a service, not just SOAP ones.

Currently, the Apache SOAP implementation does not directly use WSDL documents. In other words, you can't consume a WSDL document and automatically get a client class, for example. While some of the other platforms, such as Microsoft, are further along, Apache's Axis project is working on this functionality. For now, you'll need to interpret the WSDL document on your own, and then manually code up a client. That's more fun anyway.



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.