intertwingly

By Sam Ruby, March 5, 2002.

This document builds upon Part I to show how to add type information to a WSDL document.

Overview 

Dave Winer proposed a second interface, one with multiple parameters and a structure to deal with.  Just like cooking shows on TV, this essay starts with a document which has already been partially prepared, in this case by a member of the studio audience.  Thanks Ari!

Declaring the portType 

Looking at the interface, you can see that the request message has two parts, both of simple string types.  The response is more complex in that it has single result element which is composed of a sequence of elements, namely a single occurrence of a flerror of type boolean, followed by a single occurrence of a message of type string.  This is expressed in WSDL thus:

<types>
  <s:schema targetNamespace="uri:weblogscom">
    <s:complexType name="pingResult">
      <s:sequence>
        <s:element minOccurs="1" maxOccurs="1" name="flerror" type="s:boolean"/>
        <s:element minOccurs="1" maxOccurs="1" name="message" type="s:string" />
      </s:sequence>
    </s:complexType>
  </s:schema>
</types>

<message name="pingRequest">
  <part name="weblogname" type="s:string"/>
  <part name="weblogurl" type="s:string"/>
</message>

<message name="pingResponse">
  <part name="result" type="tns:pingResult"/>
</message>

That's all there is to it.  For convenience, the completed WSDL is available here.  Now lets see this in action.

Accessing this Web Service using Apache Axis 

Again, use the WSDL2Java tool to produce Java classes from this WSDL.  Compile the generated Java classes along with the following test program:

import weblogscom.*;

public class Pinger {
  public static void main(String[] args) throws Exception {
    PingPort weblogscom = new WeblogscomLocator().getPingPort();
    PingResult result = weblogscom.ping(args[0], args[1]);
    System.out.println("error   => " + result.getFlerror());
    System.out.println("message => " + result.getMessage());
  }
}

Now invoke the result using

java Pinger "Sam Ruby's Radio Weblog" "http://radio.weblogs.com/0101679/"

And after a brief delay you should see the following output:

error => false
message => Thanks for the ping. We checked and found that the "Sam Ruby's Radio Weblog" weblog has not changed, so it has not been added to changes.xml.

Accessing this Web Service using the Microsoft .NET Framework SDK 

This time, use the Wsdl.exe tool to produce C# classes from this WSDL.  Compile the generated C# classes along with the following test program:

public class pinger {
  public static void Main(string[] args) {
    weblogscom port = new weblogscom();
    pingResult result = port.ping(args[0], args[1]);
    System.Console.WriteLine("error   => " + result.flerror);
    System.Console.WriteLine("message => " + result.message);
  }
}

Now invoke the result using

Pinger "Sam Ruby's Radio Weblog" "http://radio.weblogs.com/0101679/"

This time you get a much quicker response... see the message below for the reason why:

error => False
message => Thanks for the ping, however we can only accept one ping every five minutes. It's cool that you're updating so often, however, if I may be so bold as to offer some advice -- take a break, you'll enjoy life more.

Conclusion 

Adding type information can both increase interoperability and further reduce the effort required to access your web service.  As demonstrated here, achieving this is not all that difficult, generally it only amounts to adding more parts or elements and declaring each as either primitive or derived data types.

Part III covers document literal descriptions of interfaces.