PERL SOAP Programming Tutorial

http://www.webmonkey.com/tutorial/Get_Your_Feet_Wet_With_SOAP

http://www.perl.com/pub/a/2001/01/soap.html

What Is SOAP?

SOAP, or the Simple Object Access Protocol, is a protocol designed to help web applications send messages to each other. It's got a very simple, portable structure, based on XML, and it can travel via HTTP, so it's lightweight and easy to implement, plus it's independent of language and platform. And thus the "Simple" part of the acronym, without which we'd now be learning about "OAP," which isn't nearly as puntastic.

Say this application you're writing needs to convert any European Economic Community currency to euros, and vice versa, at the current market rate. Your application can send a brief SOAP request to a server that does the calculation and returns a response, also in SOAP.

Why is this neat? Well, maybe your application is written in Java, and the server's doing its calculation in Perl. As long as they both use SOAP, the transaction is perfectly clean and simple. Also, if your application is running on a computer with web access, the SOAP messages can be sent via HTTP, through port 80. Using port 80 is nice because it doesn't require any extra setup, and any firewall sitting in the way assumes it's just more web traffic, and lets it through, without the long lines and cavity searches that often crop up if you set aside a dedicated port. Three, SOAP is an open protocol (consult the W3C's spec for SOAP 1.2 for more). There are a number of freely downloadable SOAP client and server tools and libraries that can be bent to your needs.

SOAPing Up

A SOAP message is no more and no less than an XML document, sent via some sort of transport protocol. HTTP is the most common way of sending SOAP messages, although SOAP is flexible enough to work with pretty much any transmission protocol you like.

In this tutorial, we're going to use SOAP::Lite, a set of Perl modules that makes dealing with SOAP a breeze. If you happen to dislike Perl, there are plenty of other implementations:Axis, which runs on Apache, Microsoft .NET SOAP, if you like Visual Basic or C#, or any of a hudred more. Or write your own. But here, today, we are using Perl.

So download and install SOAP::Lite. You can get SOAP::Lite from the developer's site, soaplite.com, or use CPAN to grab it automatically and take care of any dependency issues. You'll want to put it on your Web server as well as on the machine you're going to write a client application on. To install it from a command line, you can type ...

 perl -MCPAN -e

... which will give you a CPAN shell, then ...

 install SOAP::Lite

Follow the prompts, and soon enough you're all lathered up and ready to go.

SOAP::Lite requires MD5, XML::Parser, MIME::Lite, and MIME::Parser, which you probably have already if you have a relatively modern working Perl install. If not, CPAN's got 'em.

I'll wait here, blowing bubbles, until you've done that.

Carving A Quick SOAP Server

All set? Now we're going to put together a real quick SOAP server that will generate a (pseudo)random number between 1 and 10. All together now, in Perl:

  #!/usr/bin/perl -w
use SOAP::Transport::HTTP;
SOAP::Transport::HTTP::CGI
   ->dispatch_to('Random')
   ->handle;
package Random;
   sub choose {
         $random = int(rand(9))+1;
   return $random;
   }

The second half of that script generates and returns a random number - the first half, with dispatch_to and handle, wraps the procedure in a SOAP bubble. In essence, it's telling the HTTP server that any calls that come in for Random should be sent to SOAP::Lite, via this script.

Save this script in your web server's cgi-bin directory, set its permissions so it's executable, and it's ready to go. Now let's write a corresponding client script to use it.

#!/usr/bin/perl -w
use SOAP::Lite;
print SOAP::Lite
-> uri('http://myserver.com/Random')
-> proxy('http://myserver.com/cgi-bin/random.cgi')
-> Random()
-> result;

Quick, update your resume. You've built a complete web service using SOAP. Run that script, and voila! A random number, requested and delivered via SOAP, just for you. Let's take a quick look at how it does what it does.

What's Happening?

When the client is run, it contacts the server via SOAP, gets a random number freshly generated for it, and outputs that number. The Perl modules are handling all the nasty behind-the-scenes work of creating HTTP headers and encoding XML schemas.

The proxy() method points to the URL of the actual procedure you want to run on the server -- in this case, the script we just wrote.

It's not to be confused with uri(), which is where the namespace of the server-side SOAP code is defined. The argument to the uri() method looks like a URL, but it's not. The "http://" part of uri()'s argument specifies the transport protocol; the server name is the server name, right; and then the class to be invoked is last. There isn't a directory called Random on the server.

What's happening behind the scenes is this:The client script sends a SOAP payload to the server via HTTP. This message consists of an HTTP header followed by a SOAP envelope generated by the Perl module.

What the client sends to the server actually looks something like this:

  POST /random.cgi HTTP/1.1
Content-Type:text/xml; charset="utf-8"
Content-Length:124

   
       
          
  
       
   
  

The "xmlns" lines declare default namespaces, whose purpose is to ensure that there's no conflict between the envelope we're creating and another one somewhere that might use the same name. We're referring to predefined namespaces for our schema and envelope, ones that are just sitting there on the W3C's machines waiting to be used. But this is the aspect that SOAP::Lite takes care of for you, so understanding it is secondary for the time being. Again, the W3C specification explains it all in great detail.

Seeing the SOAP Light

SOAP::Lite has a lot of tricks up its sleeve. For example, if you're going to be making a whole bunch of remote function calls, there's an easier way than sending each one on its way with

dispatch_to()

. If you initialize the module in your script with ...

  use SOAP::Lite +autodispatch =>
    uri =>  'http://myserver.com/Random'
    proxy => 'http://myserver.com/cgi-bin/random.cgi'

... then any time your script calls an undefined method, the call will be autodispatched via SOAP to the proxy you specify.

There is a lot more to SOAP, and SOAP::Lite, but you're on your way, so I won't slow you down. For information about error handling techniques, passing complex information and objects back and forth, and suchlike, there is a bunch of useful documentation to be found at cookbook.soaplite.com.

If you need ideas or inspiration, XMethods.com has a useful and entertaining collection of web services you can check out and use.

Network Security Scan

http://www.openvas.org/index.html