This section shows you how to write a SOAP client using SOAP::Lite for Perl. The instructions given here pertain to Win32 and Unix systems but can be adapted for any applicable platform.

Introduction
We will be writing some very simple SOAP clients which will exploit the Quotation Service as described and developed in the Section 4 of Server-Side SOAP.

You can of course incorporate the perl code you find here into CGI Web Pages but it is not our intention to provide examples of that here because the SOAP-related code that you would incorporate is essentially invariant. As such we will just look at the bare essentials in a stripped down client with the rawest user interface possible.

As is the case when writing clients to any SOAP service, ensure in advance that you are familiar with the service and its method signatures.

We will build three clients, one for each service method.

Installing Perl and the required Perl Modules [ for Win32 ]
As the installation is quite different for Win32 and Unix systems, these are treated separately. Unix instructions are further down the page.

By far the easiest way to install everything you need is to start afresh (ie. with no prior Perl installation) and install the latest version of ActivePerl (5.6.1 or later) from ActiveState.com. To do this, simply go to their download area, choose the Windows/MSI package and save it to your machine. You will then have a Microsoft Installer (msi) file called ActivePerl-5.6.1.628-MSWin32-x86-multi-thread.msi (version number may change).

If you cannot start afresh because you already have ActivePerl installed and it is a version prior to 5.6.1 or you have another kind of Perl installation then you can try one of the following:

• Upgrade your older version of ActivePerl to 5.6.1 (download and install as described for a fresh install).
• Leave your older ActivePerl version as is. Then, using ppm, check that you have the modules as shown below (ignoring version numbers for the moment), install those that you do not have and try to complete the tutorial. If this does not work then upgrade to 5.6.1.
• Install ActivePerl alongside your non-ActivePerl Perl installation. You will have either to alter your path to ensure that ActivePerl is picked up first when you type 'perl' or type the full path of ActivePerl's perl.exe when you want to run the SOAP client later on in this tutorial.

Launch the installer by double clicking on the downloaded msi file. Follow the instructions to install ActivePerl on your machine. If you accept all the defaults then everything will be installed to C:/Perl (other destination directories are fine but just note that the paths mentioned below are based on the default).

Fortunately, this installation includes all of the Perl Modules required for writing Perl clients that exploit SOAP::Lite for Perl. To verify that you have got all the required modules, open up a command window and run the Perl Package Manager (PPM) with the following command (note that you will need to be connected to the internet for this to work).

  > ppm

  PPM interactive shell (2.1.5) - type 'help' for available commands 
  PPM>

Once PPM is working, type the following command to view the list of installed packages:

  PPM> query

  Archive-Tar      [0.072  ] module for manipulation of tar archives.
  Compress-Zlib    [1.08   ] Interface to zlib compression library
  Digest-MD5       [2.11   ] Perl interface to the MD5 Algorithm
  File-CounterFile [0.12   ] Persistent counter class
  Font-AFM         [1.18   ] Interface to Adobe Font Metrics files
  HTML-Parser      [3.19   ] SGML parser class
  HTML-Tagset      [3.03   ] Data tables useful in parsing HTML
  HTML-Tree        [3.11   ] HTML syntax tree builder
  MIME-Base64      [2.11   ] Encoding and decoding of base64 strings
  PPM              [2.1.5  ] Perl Package Manager: locate, install, upgrade
                             software packages.
  SOAP-Lite        [0.46   ] Library for Simple Object Access Protocol (SOAP)
                             clients and servers in Perl
  URI              [1.11   ] Uniform Resource Identifiers (absolute and relative)
  XML-Parser       [2.27   ] A Perl module for parsing XML documents
  libnet           [1.07.03] Collection of Network protocol modules
  libwin32         [0.17.2 ] A collection of extensions that aims to provide
                             comprehensive access to the Windows API.
  libwww-perl      [5.51   ] Library for WWW access in Perl

That completes the Win32 installation. If you do not want to install Perl and the required Perl Modules on a Unix system as well, you can skip the following and go directly to Understanding the Client Code .

Installing Perl and the required Perl Modules [ for Unix ]
You will need Perl 5.004 or later. It is not entirely unlikely that perl is already installed on your UNIX system (Perl 5.005_03 comes shipped with Solaris 8 for example). Type "perl -v" at a command prompt to check if perl is installed and view your version at the same time. If you do need to install or upgrade perl then a link to a downloadable Perl install that is suitable for your system can be found at CPAN Binary Distributions. Find the download site appropriate for your system and download the install file. Follow the instructions that come with the package (they will differ from system to system so we cannot provide help here).

Once perl is installed you will also need to install the following packages. The versions shown are not strictly required although these are the versions that we have tested and confirmed so we do recommend you use these versions or later. If you are not experienced with Perl Module installation then please read the installation notes below before you start.

• HTML-Tagset [3.03]
• Digest-MD5 [2.16]
• HTML-Parser [3.25]
• IO [1.20]
• libnet [1.0704]
• MIME-Base64 [2.12]
• URI [1.16]
• libwww-perl [5.53_96]
• expat (C Package) [1.95.2]
• XML-Parser [2.30]
• SOAP-Lite [0.51]

Installation notes : installing perl modules can be a little tricky - here are a few tips to help you avoid or get you over at least some of the obstacles. The internet abounds with FAQs for the many potential hazards not covered here.

• Do the installations in the order in which they appear above so that the tests that are a part of the install for each module work OK).
• Perform all installations as the root user.
• You will need a standard C-Compiler (such as gcc) installed prior to installing the modules. If you do not have such a compiler then a link to a downloadable gcc install can be found at gnu.org.
• For each installation, download the archive, unpack it to any convenient location, read the README file that can be found in the directory that is created. This will typically instruct you to do the following:-

    > perl Makefile.PL
    > make
    > make test
    > make install
  

  The first command "perl Makefile.PL" will create a Makefile. If you are using gcc as your compiler you may need to alter the Makefile to avoid errors at compile time. In particular change compile option "-KPIC" to "-fPIC" and remove all optimisation flags (such as "-x03 -xdepend")
• The exception to the rule is the expat package which is a c (not a perl) package. The README in this case will instruct you to do the following:-

    > ./configure
    > make
    > make install
  

Understanding the Client Code
As you will see the Perl code for calling a service is extremely terse. Following is a list of the steps to take and a code snippet drawn from getAllQuotations.pl which is shown in full below.

• Declare usage of the SOAP::Lite package

    use SOAP::Lite;

• Define the service

    $service = SOAP::Lite -> uri('urn:QuotationService')
                 -> proxy('http://localhost:8080/soap/servlet/rpcrouter');

• Invoke the service method and save the result. Note that in Perl there are only three data types : scalars, arrays and hashes (and combinations thereof) and the result of a SOAP call will one of these. Complex types will be returned as hashes, arrays as arrays and primitive types as scalars.

    $result = $service -> getAllQuotations() -> result();

• Traverse and interpret your result as required by its type. You will need to know what the return type is to be able to do this. In the case of getAllQuotations we know that the return type is an array of Quotation objects (ie. an array of complex types) and according to the mentioned rule this will be returned to us as an array of hashes. We can thus surf the result as follows:

    $i = -1;
    while ( ref $result->[++$i] )
    {
      print "$result->[$i]{'text'} ($result->[$i]{'author'})\n";
    }

Writing the Clients
Here is the source code for all three clients (the code is the same for Win32 and UNIX systems). Note that there is no return value for the submitQuotation service method so we do not store or interpret a result.

getAllQuotations.pl

use SOAP::Lite; $service = SOAP::Lite -> uri('urn:QuotationService') -> proxy('http://localhost:8080/soap/servlet/rpcrouter'); $result = $service -> getAllQuotations() -> result(); $i = -1; while ( ref $result->[++$i] ) { print "$result->[$i]{'text'} ($result->[$i]{'author'})\n"; }

submitQuotation.pl

use SOAP::Lite; $service = SOAP::Lite -> uri('urn:QuotationService') -> proxy('http://localhost:8080/soap/servlet/rpcrouter'); $service -> submitQuotation('Kennedy, John F.', 'Forgive your enemies, but never forget their names.');

getQuotationsByAuthor.pl

use SOAP::Lite; $service = SOAP::Lite -> uri('urn:QuotationService') -> proxy('http://localhost:8080/soap/servlet/rpcrouter'); $result = $service -> getQuotationsByAuthor('Wilde, Oscar') -> result(); $i = -1; while ( $result->[++$i] ) { print "$result->[$i]\n"; }

Note that the perl scripts shown here presume that you have the Quotation Service running on your machine (at localhost:8080). If this is not the case then you can run the clients against our demo SOAP server. To do this simply replace localhost:8080 with services.xmethods.net in the above script. For more information on our demo server, refer to the Demo Section .

Running the Clients
At a command prompt, go to the directory where you have created the above scripts and type the following commands (this presumes that the perl binary is somewhere in your path):

  > perl getAllQuotations.pl
  > perl submitQuotation.pl
  > perl getAllQuotations.pl
  > perl getQuotationsByAuthor.pl

Conclusion
The simplicity of the Perl client is evidence to this Perl package's elegance. Notice how we can call the service almost as if it were a function defined locally without ever having to declare the method name. This is a powerful feature of SOAP::Lite for Perl.