(December 2006 Update: This article was written in 2003 (originally written for the Tokyo PC Users newsletter), so may be wildly out of date now. Read it at your own risk! If you are using PHP there is a good article in the Nov 2006 php Architect magazine on SDO and SCA extensions. Also take a look at: http://www.osoa.org/display/PHP/SOA+PHP+Homepage.)

Pass The Soap

I think I'm going to start using SOAP more and more. If you ever met me after a long, pre-deadline programming session - especially in the communal sauna known as the Tokyo Summer - you're probably saying, "And about time too!". But no, I'm not talking about the slippery things you wash with, and I'm not talking about Japanese Soap Land either. The SOAP I'm talking about here is Simple Object Access Protocol, which is the most common protocol for Web Services.

If you listen to the advocates then Web Services are going to change the world. They are very similar to the Web we all know, use and love, but the problem with the Web is that it was designed to be used by humans. Now, don't misunderstand, I have nothing against humans and some of them are even quite likeable, but they are a bit analog and HTML reflects that. HTML mixes the information with the layout and the explanation of the information.

Why is that bad? Well, the problem comes when you want to automate the use of the data you found on the Web. The program you write, called a screen scraper has to go through and separate the information from the layout, and if you have never written one it is probably harder than you think. But the really depressing thing is that everytime the Web page you are "scraping" has even just a minor layout change, or adds an extra row of information, your program crumbles and has to be rewritten and retested. If you are really unlucky it won't even break and will continue to cheerfully scrape the wrong information.

What Is SOAP?

SOAP is an XML protocol that allows a client program to get formatted data from a server. How does it work? Your program makes an XML document saying which function (think of a function here as a single page in the normal Web) on the remote server you want to use, and any data you want to give to it, and it then sends back another XML document containing the data you requested. Everything runs over the http protocol which is one of its strengths - it can use the existing infrastructure that the Web uses. That means the firewall, encryption, even cookies to maintain state.

Another key strength of SOAP is it is platform-independent. In addition for most languages there will be a SOAP library you can use to hide all this XML stuff, and make it look just like calling a function in a local library. See the examples below.

How Easy Is It?

I read a book on Web services (Java Web Services Unleashed - not recommended) and it all seemed very complicated. But when I actually sat down to write a server and a client it turned out to be really easy. I'm going to introduce a Web Service to tell you if your computer clock is fast or slow, with clients in Java, PHP and Python.

I chose this as an example because it is short but nearly useful: the NTP protocol exists to do the same thing but you need to open a special port in your firewall to use that and typically your conversation with the system administrator will go like this:

You: Hi! Lovely weather isn't it? You administer the firewall don't you?
SA: What do you want?
You: Well, I was wondering if you could open port -
SA: No. Go away.
You: How about a 100,000yen bribe?
SA: No. Go away.
You: How about 200,000yen and this perfumed soap gift set?
SA: No. Is "perfumed" a new XML namespace? What's that strange smell? Go away.

To keep the code short and focussed on SOAP I've made the clients just output the time and date the remote server returns. Expanding it to compare it to the local time on your machine, and modifying your local time to match, is left as the infamous Exercise For The Reader.

To get the examples to work you need to change "yourserver" to the address of your SOAP server. If testing on your local machine it will be "127.0.0.1".

One thing to notice is that each client is free to format the date in its own way and it could even decide to output in Japanese. This is the whole point - separating the data from the presentation of the data.

Enough chat, lets see some code...

In PHP

include_once('nusoap.php'); $soapclient = new soapclient('http://yourserver/soap/server.php'); $when = $soapclient->call('time_in_secs'); echo date("Y-m-d H:i:s",$when)."\n";

NuSOAP is an open-source PHP library that you can get from:
http://dietrich.ganx4.com/nusoap/

Line 2 creates a soapclient object, specifying the server to use. Line 3 says what function to call, and line 4 formats the date and outputs it.

Save the code as "client.php" (inside PHP tags of course) and run it with "php client.php".

In Python

Python guru Jim Tittsler kindly gave me this example:

#!/usr/bin/python from SOAPpy import SOAP import time server = SOAP.SOAPProxy("http://yourserver/soap/server.php") when = server.time_in_secs() print time.asctime(time.localtime(when))

SOAP.py is an open source library that you can get from http://pywebsvcs.sf.net/.

The last three lines correspond to the last three lines of the PHP example.

In Java

The simplest example in the Java Web Services Unleashed book is three pages long, but it does not have to be that way. Having said that, it is slightly more involved that the PHP and Python examples.

import org.apache.axis.client.Call; import org.apache.axis.client.Service; import javax.xml.namespace.QName; import java.util.Date; public class myclient{ public static void main(String [] args) { try { String endpoint ="http://yourserver/soap/server.php"; Service service = new Service(); Call call = (Call) service.createCall(); call.setTargetEndpointAddress( new java.net.URL(endpoint) ); Integer secs = (Integer)call.invoke("time_in_secs",new Object[]{}); //Multiply by 1000 as it wants milliseconds. Date d = new Date(secs.longValue()*1000); System.out.println(d.toString()); }catch(Exception e){System.err.println(e.toString());} } }

This uses two open-source packages from the Apache project (www.apache.org): Axis and Xerces. I downloaded and unzipped them under /usr/local/src. To use them I added their libraries to my CLASSPATH; there is no need to do the tomcat installation described in the documentation if just making a SOAP client.

Save the above file as myclient.java, then run these commands:

javac myclient.java java myclient

The Server

Here is the server in PHP. It again uses the NuSOAP library.

include_once('nusoap.php'); $s = new soap_server; $s->register('time_in_secs'); function time_in_secs(){ return time(); } $s->service($HTTP_RAW_POST_DATA);

As this shows exposing an existing library as Web server is a matter of a few lines. Save the above file as "server.php" somewhere on your Web server (to be compatible with the above client examples it should go in a top-level directory called "soap").

If you want to have multiple Web services you call register() multiple times.

WSDL and UDDI

One thing you will notice as you get into Web Services is there are lots and lots of standards, many still immature, and all with acronyms that utterly fail to be catchy. Here are a couple of the more important ones.

WSDL, Web Service Description Language, is an XML language for describing your Web services: the function name, the data types of the parameters and the data type of the returned information as well as some other things such as if the Web service runs over HTTP or SMTP. This becomes especially useful when dealing with objects instead of simple data types. Tools exist for automating the Web service client creation given a WSDL file.

UDDI, Universal Description, Discovery and Integration, is another XML language that is intended as a phone book for Web services. It allows you to search a registry for Web services and it tells you where to access the Web service and where to get the WSDL file for the services.

Summary

Setting up a Web service and then accessing it from three different languages was fairly easy. Things get more complex when you start to deal with objects across different languages; WSDL comes in useful then, and the code gets a bit longer.

Is this going to change the world? Maybe, but many of the standards are still immature and being revised, so I think it will be a while before Web services become part of our daily lives the way email and the Web have. But as I said above I plan to use SOAP more and more. I might even try the slippery white stuff one of these days.


© Copyright 2003, Darren Cook.

About The Author: I am a freelancer programmer, living and working in Tokyo, Japan. You can learn more about my skills and experience at http://dcook.org/work/ and you can contact me directly at darren@dcook.org.





 

Work Top Page   *   Personal Home Page   *   Email me at: darren@dcook.org   *   PGP Public Key

Last updated: 18th Dec 2006, © Copyright Darren Cook, 2003, 2006.

No Software Patents