home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  

Book HomeJava and XSLTSearch this book

14.2. SOAP::Lite

You can try an implementation of SOAP with Perl called SOAP::Lite, written by Paul Kulchenko. SOAP::Lite is a collection of Perl modules that provide a simple and lightweight interface for both the client and server side. This version of SOAP::Lite supports the SOAP 1.1 specification (http://www.w3.org/TR/SOAP) and works with many SOAP implementions, including Apache SOAP, Frontier, Microsoft SOAP, Microsoft .NET, DevelopMentor, XMethods, 4s4c, Phalanx, Kafka, SQLData, Lucin (in Java), Perl, C++, Python, VB, COM, and XSLT.

Here's an example that uses SOAP::Lite. The following code creates a SOAP::Lite object and uses it, but what's special about the SOAP::Lite object is that it's based on code that lives on www.soaplite.com. In other words, the code that lives on the remote end of the connection might not be Perl at all—but by using SOAP::Lite, you can execute the f2c( ) function as if you were calling f2c( ) from your own Perl program.

Also note the uri and proxy options. The uri option is the URI for SOAP methods. Basically, uri tells SOAP::Lite where SOAP-related content lives. In Perl terms, uri can represent the class in which you'll find the function to execute. For example, let's say you have the following SOAP server that uses HTTP as its transport mechanism:

#!/usr/local/bin/perl -w

use SOAP::Transport::HTTP;

    -> dispatch_to('Hello::(?:hello)')
    -> handle

This example has two key parts: it will look for a module named "Hello" and will execute Hello::hello( ) when called. Note that you don't have to explicitly "require" Hello.pm; SOAP::Lite does this for you. Now, let's look at the client:

#!/usr/local/bin/perl -w

use SOAP::Lite;

# If you want to see why something isn't working, enable +trace after
# use SOAP::Lite, as shown below     

#use SOAP::Lite +trace;
my $proxy = 'http://www.some.server/cgi-bin/hello';
print SOAP::Lite
    -> uri('urn:Hello')
    -> proxy($proxy)
    -> hello()
    -> result . "\n\n"

It's essential that uri, as used above, matches the module in which the hello( ) function lives. If it doesn't, you won't see any returned results, since SOAP::Lite won't be able to find the module in @INC (using the +trace option makes it clear that an unavailable module was not found in @INC). Now that we have some context, let's take a look at the proxy option. In the above example, proxy is the URL where the SOAP server lives. When SOAP::Lite sees the proxy option, it loads the appropriate module based on what you request.

14.2.1. SOAP::Lite Methods

All methods that SOAP::Lite provides can be used for setting and retrieving values. If you provide no parameters, you will get the current value, and if parameters are provided, a new value will be assigned to the object, and the method in question will return the current object (if not stated otherwise). This is suitable for stacking these calls. For example:

  $lite = SOAP::Lite
    -> uri('http://simon.fell.com/calc')
    -> proxy('http://soap.4s4c.com/ssss4c/soap.asp')

The order is insignificant. You may call the new( ) method first, but if you don't, SOAP::Lite will do it for you. Calling the new( ) method explicitly gives you additional syntax:

  $lite = SOAP::Lite->new(
    uri => 'http://simon.fell.com/calc',
    proxy => 'http://soap.4s4c.com/ssss4c/soap.asp'

The SOAP::Lite methods are:

new( )
Accepts a hash with method names as keys. It will call the appropriate methods together with the passed values..

transport( )
Provides access to the SOAP/Transport object. You probably shouldn't play with transport( ), since the object will be created for you.

serializer( )
Provides access to the SOAP/Serialization object. You probably shouldn't play with serializer( ), since the object will be created for you.

endpoint( )
Lets you specify an endpoint without changing/loading the protocol module. This is useful for switching endpoints without switching protocols. You should call proxy( ) first. No checks for protocol equivalence will be made.

outputxml( )
If true, all methods will return raw XML code, which you can then parse with XML::Parser or a similar module.

autotype( )
Specifies whether the serializer will try to enable autotyping. Default is true.

readable( )
Specifies the format for the generated XML code, adding carriage returns and indentation for readability.

namespace( )
Specifies the default namespace for generated envelopes (SOAP-ENV by default).

encodingspace( )
Specifies the default encoding namespace for generated envelopes (SOAP-ENC by default).

encoding( )
Specifies the encoding for generated envelopes (UTF-8 by default).

typelookup( )
Gives you access to the typelookup table used for autotyping.

multirefinplace( )
Determines whether the serializer should put values for multireferences in the first occurrence of the reference. Default is false.

on_action( )
Specifies a handler (either globally or locally) to be triggered for an on_action event. The default handler is uri#method.

on_fault( )
Specifies a handler (either globally or locally) to be triggered for an on_fault event. The default behavior will die on a transport error and do nothing on other error conditions.

on_debug( )
Globally specifies a handler to be triggered for an on_debug event. Default behavior is to do nothing, since moving the +trace/+debug options is preferred.

on_nonserialized( )
Specifies a handler to be triggered for an on_nonserialized event. The default behavior is to produce a warning, if warnings are enabled for these events.

call( )
Provides an alternative interface for remote method calls, with additional options:

Prefixed method
If you want to specify a prefix for generated method's element, try:

call('myprefix:method' => @parameters)
Access to any method
To access remote procedures that have the same names as methods of the SOAP::Lite object:

call(new => @parameters) 
Implementation of OO interface
To use the object-oriented interface:

# You should specify uri( )
my $soap = SOAP::Lite
  -> uri('http://my.own.site/CLASS')
  # ..... other parameters

my $obj = $soap->call(new => @parameters)->result;
print $soap->call(method => $obj)->result;
Ability to set method's attributes
To specify attributes for a method element:

call(SOAP::Data->name('method')->attr({xmlns => 'mynamespace'})
    => @parameters)
self( )
Returns the object reference to global default object specified with the use SOAP::Lite ... interface. For example:

my $proxy = 'http://www.some.server';
my $soap - SOAP::Lite->proxy($proxy);
print $soap->self->proxy;

This prints http://www.some.server.

dispatch_from( )
The same as autodispatch, but doesn't install the UNIVERSAL::AUTOLOAD handler. It installs only the AUTOLOAD handlers in specified classes.

Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.