intertwingly

By Sam Ruby, February 7, 2002.

To borrow a line, SOAP celebrates diversity.  This document describes the integration between a popular scripting platform and a Java based implementation of SOAP, both in what is possible today and what could be done to improve the user's experience in the future.

Calling a Radio service using JAX RPC and Axis 

import javax.xml.rpc.Call;
import javax.xml.rpc.ParameterMode;
import javax.xml.rpc.namespace.QName;
import org.apache.axis.client.Service;
import org.apache.axis.encoding.XMLType;
import org.apache.axis.transport.http.HTTPConstants;</xmp><xmp>public class HelloDave {
  public static void main(String args[]) throws Exception {
    Call call = (new Service()).createCall();
    call.setTargetEndpointAddress(new java.net.URL(("http://127.0.0.1:5335/")));
    call.setOperationName(new QName("", "helloWorld") );
    call.addParameter("Name", XMLType.XSD_STRING, ParameterMode.PARAM_MODE_IN);
    call.setProperty(HTTPConstants.MC_HTTP_SOAPACTION, "/radio");
    System.out.println(call.invoke(new Object[] {"Dave from Axis"}));
  }
}</xmp>

Calling a Axis service using soap.rpc.client 

on getQuote (name) {</xmp><xmp>   local (quote, params={"symbol": name});</xmp><xmp>   quote = soap.rpc.client (
      actionURI:  "/axis/servlet/AxisServlet",
      methodName: "getQuote",
      adrParams:  @params,
      rpcServer:  "nagoya.apache.org",
      rpcPort:    5049,
      username:   "user1",
      password:   "pass1",
      methodNamespace:    "xdq",
      methodNamespaceURI: "urn:xmltoday-delayed-quotes"
   );</xmp><xmp>   return ("Stock quote for " + name + " is " + quote)</xmp><xmp>}</xmp>

You can see the results here: [Macro error: Poorly formed XML text, string constant is improperly formatted. (At character #421.)]

Taking stock of where we are 

OK, that proves it can be done.  Now should look to make things simpler.  Particularly for the script developer.

Take a closer look at these examples. They are dominated by administrivia - soap action, namespaces, uri's, parameter names, etc. Wouldn't it be nice if all of this could be removed from sight? If you are a Radio script developer today, you already know can create a macro for your use by putting a few lines in a Macros folder. Move that same file to a WebServices folder and you have exposed a web service. That's great for serving, but what if you wanted to consume? Wouldn't it be nice if there was a standard XML based format which contains all of this information that you can simply drop into a folder which would define all of this stuff for you?

Well there is such a format.  I won't lie to you and tell you that it is sleek, elegant, or perfect.  But it does have a few things going for it.  It exists.  It is fairly widely adopted.  It is extensible.  And it gets the job done.

Gentle introduction to WSDL 

Procedures are called operations.  Operations have an input message and and output message.  A port is a collection of operations, and is described in two parts.  The abstract part is called the portType.  The concrete association to a protocol is called a binding.  That's enough to get started!

Now lets see how all of this works in practice, starting with the Apache Axis base interop WSDL. At the present point in time, we are only really interested in four pieces of data from this file.  The soap:address contains the rpcServer,  rpcPort, and actionURI in the traditional URL syntax.  You will also see a port and a binding.  These will be used in a minute.  Finally there is an import statement.  That's where the rest of the WSDL can be found.  The reason this is structured this way is that we have dozens of  vendors implementing the same set of operations, where the only difference is where you can find the endpoint and what bindings are supported.

Next lets look at the binding in the imported WSDL.  While there is no limit to the number of different protocols you could support, at the moment let's simply ensure that there is one present which specifies RPC style SOAP over HTTP.  The way this is encoded in WSDL is with the following attributes: style="rpc" and transport="http:///soap/http".  Since the binding is for SOAP over HTTP, you can also find the soapAction for each operation in the binding.

Finally, lets look at the portType itself.  It contains a list of operations which contain a list of messages.  These messages contain various parts which each describe the name and type of each operand.  For now, don't worry about type, that's the subject of another essay.

That's pretty much it.  You may notice the WSDL contains other information.  For example, it specifies that the 2001 schema is what is expected.  Simple rule: support as much as you can, ignore the rest, and hope for the best.  Just remember, the worst thing that can happen is that your request will fail.  In this case, Radio sends the 1999 version of the schema, but at least in the Apache implementations, this is accepted.

How this hypothetically would work 

Drag or SaveAs this WSDL to a folder.  Give the file a name, say AxisInterop.wsdl.  Then enter the following:

<% AxisInterop.echoString("Hi Sam!") %>

What could be simpler?  OK, so this example may not be all that exciting.  But you might find more exciting services here.

Conclusion 

Interoperability between diverse platforms isn't a distant future thought, it is a reality today.  But as SOAPBuilders, we shouldn't stop here.  Instead, we should work together and continuously strive to make things ever more simpler.  While WSDL is certainly far from perfect and has many other potential usages, this essay focused on one way in which it could be applied to make life easier for the script developer.