• NAME
• SUPPORTED PLATFORMS
• SYNOPSIS
• DESCRIPTION
• WHERE TO FIND EXAMPLES
• OVERVIEW OF CLASSES AND PACKAGES
• SOAP::Lite
• SOAP::Data
• SOAP::Serializer
• SOAP::SOM
• SOAP::Schema
• SOAP::Trace
• FEATURES AND OPTIONS
• IN/OUT, OUT PARAMETERS AND AUTOBINDING
• AUTODISPATCHING
• ACCESSING HEADERS AND ENVELOPE ON SERVER SIDE
• SERVICE DEPLOYMENT. STATIC AND DYNAMIC
• SECURITY
• OBJECTS-BY-REFERENCE
• DEFAULT HANDLERS
• INTEROPERABILITY
• BUGS AND LIMITATIONS
• PLATFORMS
• AVAILABILITY
• SEE ALSO
• COPYRIGHT
• AUTHOR

NAME

SOAP::Lite - Client and server side SOAP implementation

SUPPORTED PLATFORMS

• Linux
• Solaris
• Windows

SYNOPSIS

  # client side
  use SOAP::Lite;
  print SOAP::Lite 
    -> uri('http://simon.fell.com/calc')
    -> proxy('http://www.razorsoft.net/ssss4c/soap.asp')
    -> doubler([10,20,30,50,100])
    -> result ->[1];

  # the same code with autodispatch: 
  use SOAP::Lite +autodispatch => 
    uri => 'http://simon.fell.com/calc',
    proxy => 'http://www.razorsoft.net/ssss4c/soap.asp'
  ;
  print doubler([10,20,30,50,100])->[1];

  # code with service description
  use SOAP::Lite;
  print SOAP::Lite
    -> schema('http://www.xmethods.net/sd/StockQuoteService.wsdl')
    -> getQuote('MSFT');

  # code for SOAP server (CGI):
  use SOAP::Transport::HTTP;
  SOAP::Transport::HTTP::CGI
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method') 
    -> handle;

DESCRIPTION

SOAP::Lite is a collection of Perl modules which provides a simple and lightweight interface to the Simple Object Access Protocol (SOAP) both on client and server side.

This version of SOAP::Lite supports the SOAP 1.1 specification ( http://www.w3.org/TR/SOAP ).

The main features of the library are:

• Supports SOAP 1.1 spec.

• Provides full namespace support for SOAP 1.1.

• Supports XML entity encoding.

• Supports header attributes.

• Supports HTTPS protocol.

• Supports SMTP protocol.

• Provides POP3 server implementation.

• Supports Basic/Digest server authentication.

• Supports blessed object references.

• Contains various reusable components (modules) that can be used independently, as, for instance, SOAP::Serializer and SOAP::Deserializer.

• Provides an object oriented interface for serializing/deserializing and sending/receiving SOAP packets. Support for extensibility of the serialization/deserialization architecture has been included; see SOAP::Data for details.

• Supports serialization/deserialization of sophisticated object graphs which may have cycles (a circular queue would serialize just fine, as well as $a=\$a. See test.pl and documentation for more examples).

• Supports arrays (both serialization and deserialization with autotyping).

• Custom/user-defined types (see SOAP::Data::as_ordered_hash for example). Supports ordered hashes (as working example of user-defined data types).

• Customizable auto type definitions.

• Has more than 40 tests that access public test servers with different implementations: Apache SOAP, Frontier, Perl, XSLT, COM and VB6.

• Has (limited) schema support (WSDL) with dynamic and stub access.

• Supports Base64 encoding.

• Supports out parameters binding.

• Supports transparent SOAP calls with autodispatch feature.

• Supports dynamic/static class/method binding.

• Provides CGI/daemon server implementation.

• Provides interactive shell for SOAP sessions (examples/SOAPsh.pl).

• Easy services deployment. Put module in specified directory and it'll be accessible.

• Has enough examples and documentation to be up and running in no time.

WHERE TO FIND EXAMPLES

See test.pl, examples/*.pl and the module documentation for a client-side examples that demonstrate the serialization of a SOAP request, sending it via HTTP to the server and receiving the response, and the deserialization of the response. See examples/soap.cgi, examples/soap.daemon and examples/My/Apache.pm for server-side implementations.

OVERVIEW OF CLASSES AND PACKAGES

This table should give you a quick overview of the classes provided by the library.

 SOAP::Lite.pm
 -- SOAP::Lite           -- Main class provides all logic
 -- SOAP::Transport      -- Supports transport architecture
 -- SOAP::Data           -- Provides extensions for serialization architecture
 -- SOAP::Header         -- Provides extensions for header serialization
 -- SOAP::Parser         -- Parses XML file into object tree
 -- SOAP::Serializer     -- Serializes data structures to SOAP package
 -- SOAP::Deserializer   -- Deserializes results of SOAP::Parser into objects
 -- SOAP::SOM            -- Provides access to deserialized object tree
 -- SOAP::Constants      -- Provides access to common constants
 -- SOAP::Trace          -- Provides tracing facilities
 -- SOAP::Schema         -- Provides access and stub(s) for schema(s)
 -- SOAP::Schema::WSDL   -- WSDL implementation for SOAP::Schema
 -- SOAP::Server         -- Handles requests on server side 
 -- SOAP::Server::Object -- Handles objects-by-reference

 SOAP::Transport::HTTP.pm
 -- SOAP::Transport::HTTP::Client  -- Client interface to HTTP transport
 -- SOAP::Transport::HTTP::Server  -- Server interface to HTTP transport
 -- SOAP::Transport::HTTP::CGI     -- CGI implementation of server interface
 -- SOAP::Transport::HTTP::Daemon  -- Daemon implementation of server interface
 -- SOAP::Transport::HTTP::Apache  -- mod_perl implementation of server interface

 SOAP::Transport::POP3.pm
 -- SOAP::Transport::POP3::Server  -- Server interface to POP3 protocol

 SOAP::Transport::MAILTO.pm
 -- SOAP::Transport::MAILTO::Client -- Client interface to SMTP/sendmail

 SOAP::Transport::LOCAL.pm
 -- SOAP::Transport::LOCAL::Client -- Client interface to local transport

 SOAP::Transport::TCP.pm
 -- SOAP::Transport::TCP::Server -- Server interface to TCP protocol
 -- SOAP::Transport::TCP::Client -- Client interface to TCP protocol

SOAP::Lite

All methods that SOAP::Lite provides can be used for both setting and retrieving values. If you provide no parameters, you will get current value, and if parameter(s) 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 like:

  $lite = SOAP::Lite
    -> uri('http://simon.fell.com/calc')
    -> proxy('http://www.razorsoft.net/ssss4c/soap.asp')
  ;

The order is insignificant and you may call the new() method first. If you don't do it, SOAP::Lite will do it for you. However, the new() method gives you additional syntax:

  $lite = new SOAP::Lite
    uri => 'http://simon.fell.com/calc',
    proxy => 'http://www.razorsoft.net/ssss4c/soap.asp'
  ;

new() accepts a hash with method names as keys. It will call the appropriate methods together with the passed values. Since new() is optional it won't be mentioned anymore.

Other available methods are:

transport()

Provides access to the SOAP::Transport object. The object will be created for you. You can reassign it (but generally you should not).

serializer()

Provides access to the SOAP::Serialization object. The object will be created for you. You can reassign it (but generally you should not).

proxy()

Shortcut for transport->proxy(). This lets you specify an endpoint and also loads the required module at the same time. It is required for dispatching SOAP calls. The name of the module will be defined depending on the protocol specific for the endpoint. The prefix SOAP::Transport will be prepended, the module will be loaded and object of class (with appended ::Client) will be created.

For example, for 'http://localhost/', the class for creating objects will look for SOAP::Transport:HTTP::Client;

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()

Lets you specify the kind of output from all method calls. If true, all methods will return unprocessed, raw XML code. You can parse it with XML::Parser, SOAP::Deserializer or any other appropriate module.

autotype()

Shortcut for serializer->autotype(). This lets you specify whether the serializer will try to make autotyping for you or not. Default setting is true.

readable()

Shortcut for serializer->readable(). This lets you specify the format for the generated XML code. Carriage returns <CR> and indentation will be added for readability. Useful in the case you want to see the generated code in a debugger. By default, there are no additional characters in generated XML code.

namespace()

Shortcut for serializer->namespace(). This lets you specify the default namespace for generated envelopes ('SOAP-ENV' by default).

encodingspace()

Shortcut for serializer->encodingspace(). This lets you specify the default encoding namespace for generated envelopes ('SOAP-ENC' by default).

encoding()

Shortcut for serializer->encoding(). This lets you specify the encoding for generated envelopes. For now it will not actually change envelope encoding, it will just modify the XML header ('UTF-8' by default).

typelookup()

Shortcut for serializer->typelookup(). This gives you access to the typelookup table that is used for autotyping. For more information see SOAP::Serializer.

uri()

Shortcut for serializer->uri(). This lets you specify the uri for SOAP methods. Nothing is specified by default and your call will definitely fail if you don't specify the required uri.

multirefinplace()

Shortcut for serializer->multirefinplace(). If true, the serializer will put values for multireferences in the first occurrence of the reference. Otherwise it will be encoded as top independent element, right after method element inside Body. Default value is 'false'.

header()

DEPRECATED. Use SOAP::Header instead.

Shortcut for serializer->header(). This lets you specify the header for generated envelopes. You can specify root, mustUnderstand or any other header using SOAP::Data class:

  $serializer = SOAP::Serializer->envelope('method' => 'mymethod', 1,
    SOAP::Header->name(t1 => 5)->attr({'~V:mustUnderstand' => 1}),
    SOAP::Header->name(t2 => 7)->mustUnderstand(2),
  );

will be serialized into:

  <SOAP-ENV:Envelope ...attributes skipped>
    <SOAP-ENV:Header>
      <t1 xsi:type="xsd:int" SOAP-ENV:mustUnderstand="1">5</t1>
      <t2 xsi:type="xsd:int" SOAP-ENV:mustUnderstand="1">7</t2>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
      <namesp1:mymethod xmlns:namesp1="urn:SOAP__Serializer">
        <c-gensym6 xsi:type="xsd:int">1</c-gensym6>
      </namesp1:mymethod>
    </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

You can mix SOAP::Header parameters with other parameters and you can also return SOAP::Header parameters as a result of a remote call. They will be placed into the header. See My::Parameters::addheader as an example.

on_action()

This lets you specify a handler for on_action event. It is triggered when creating SOAPAction. The default handler will set SOAPAction to "uri#method". You can change this behavior globally (see DEFAULT HANDLERS) or locally, for a particular object.

on_fault()

This lets you specify a handler for on_fault event. The default behavior is to die on an transport error and to do nothing on other error conditions. You can change this behavior globally (see DEFAULT HANDLERS) or locally, for a particular object.

on_debug()

This lets you specify a handler for on_debug event. Default behavior is to do nothing. Use +trace/+debug option for SOAP::Lite instead.

on_nonserialized()

This lets you specify a handler for on_nonserialized event. The default behavior is to produce a warning if warnings are on for everything that cannot be properly serialized (like CODE references or GLOBs).

SOAP::Data

You can use this class if you want to specify a value, a name, atype, a uri or attributes for SOAP elements (use value(), name(), type(), uri() and attr() methods correspondingly). For example, SOAP::Data->name('abc')->value(123) will be serialized to '<abc>123</abc>', as well as will SOAP::Data->name(abc => 123). Each of them (except the value method) can have a value as the second parameter. All methods return the current value if you call them without parameters. The return the object otherwise, so you can stack them. See test.pl for more examples. You can import these methods with:

  SOAP::Data->import('name');

or

  import SOAP::Data 'name';

and then use name(abc => 123) for brevity.

An interface for specific attributes is also provided. You can use the actor(), mustUnderstand(), encodingStyle() and root() methods to set/get values of the correspondent attributes.

  SOAP::Data
    ->name(c => 3)
    ->encodingStyle('http://xml.apache.org/xml-soap/literalxml')

will be serialized into:

  <c SOAP-ENV:encodingStyle="http://xml.apache.org/xml-soap/literalxml";
     xsi:type="xsd:int">3</c>

SOAP::Serializer

Usually you don't need to interact directly with this module. The only case when you need it, it when using autotyping. This feature lets you specify types for your data according to your needs as well as to introduce new data types (like ordered hash for example).

You can specify a type with SOAP::Data->type(float = 123)>. During the serialization stage the module will try to serialize your data with the as_float method. It then calls the typecast method (you can override it or inherit your own class from SOAP::Data) and only then it will try to serialize it according to data type (SCALAR, ARRAY or HASH). For example:

  SOAP::Data->type('ordered_hash' => [a => 1, b => 2])

will be serialized as an ordered hash, using the as_ordered_hash method.

If you do not specify a type directly, the serialization module will try to autodefine the type for you according to the typelookup hash. It contains the type name as key and the following 3-element array as value:

  priority, 
  check_function (CODE reference), 
  typecast function (METHOD name or CODE reference)

For example, if you want to add uriReference to autodefined types, you should add something like this:

  $s->typelookup({
    %{$s->typelookup},
    uriReference => [11, sub { shift =~ m!^http://! }, 'as_uriReference']
  });

and add the as_uriReference method to the SOAP::Serializer class:

  sub SOAP::Serializer::as_uriReference {
    my $self = shift;
    my($value, $name, $type, $attr) = @_;
    return [$name, {%{$attr || {}}, 'xsi:type' => 'xsd:uriReference'}, $value];
  }

The specified methods will work for both autotyping and direct typing, so you can use either

  SOAP::Data->type(uriReference => 'http://yahoo.com')>

or just

  'http://yahoo.com'

and it will be serialized into the same type. For more examples see as_* methods in SOAP::Serializer.

The SOAP::Serializer provides you with autotype(), readable(), namespace(), encodingspace(), encoding(), typelookup(), uri(), multirefinplace() and envelope() methods. All methods (except envelope()) are described in the SOAP::Lite section.

envelope()

It allows you to build three kind of envelopes depending on the first parameter:

method

  envelope(method => 'methodname', @parameters);

or

  method('methodname', @parameters);

Lets you build a request/response envelope.

fault

  envelope(fault => 'faultcode', 'faultstring', $details);

or

  fault('faultcode', 'faultstring', $details);

Lets you build a fault envelope. Faultcode will be properly qualified and details could be string or object.

freeform

  envelope(freeform => 'something that I want to serialize');

or

  freeform('something that I want to serialize');

Reserved for nonRPC calls. Lets you build your own payload inside a SOAP 
envelope. All SOAP 1.1 specification rules are enforced, except method 
specific ones. See UDDI::Lite as example.

For more examples see test.pl and SOAP::Transport::HTTP.pm

SOAP::SOM

SOM gives you access to the deserialized envelope via several methods. All methods accept a node path (similar to XPath notations). SOM interprets '/' as the root node, '//' as relative location path ('//Body' will find all bodies in document, as well as '/Envelope//nums' will find all 'nums' nodes under Envelope node), '[num]' as node number and '[op num]' with op being a comparison operator ('<', '>', '<=', '>=', '!', '=').

All nodes in nodeset will be returned in document order.

match()

Accepts a path to a node and returns true/false in a boolean context and a SOM object otherwise. valueof() and dataof() can be used to get value(s) of matched node(s).

valueof()

Returns the value of a (previously) matched node. It accepts a node path. In this case, it returns the value of matched node, but does not change the current node. Suitable when you want to match a node and then navigate through node children:

  $som->match('/Envelope/Body/[1]'); # match method
  $som->valueof('[1]');              # result
  $som->valueof('[2]');              # first out parameter (if present)

The returned value depends on the context. In a scalar context it will return the first element from matched nodeset. In an array context it will return all matched elements.

dataof()

Same as valueof(), but it returns a SOAP::Data object, so you can get access to the name, the type and attributes of an element.

headerof()

Same as dataof(), but it returns SOAP::Header object, so you can get access to the name, the type and attributes of an element. Can be used for modifying headers (if you want to see updated header inside Header element, it's better to use this method instead of dataof() method).

namespaceuriof()

Returns the uri associated with the matched element. This uri can also be inherited, for example, if you have

  <a xmlns='http://my.namespace'>
    <b>
       value
    </b>
  </a>

this method will return same value for 'b' element as for 'a'.

SOAP::SOM also provides methods for direct access to the envelope, the body, methods and parameters (both in and out). All these methods return real values (in most cases it will be a hash reference), if called as object method. Returned values also depend on context: in an array context it will return an array of values and in scalar context it will return the first element. So, if you want to access the first output parameter, you can call $param = $som->paramsout; and you will get it regardless of the actual number of output parameters. If you call it as class function (for example, SOAP::SOM::method) it returns an XPath string that matches the current element ('/Envelope/Body/[1]' in case of 'method'). The method will return undef if not present OR if you try to access an element that has an xsi:null="1" attribute. To distinguish between these two cases you can first access the match() method that will return true/false in a boolean context and then get the real value:

  if ($som->match('//myparameter')) {
    $value = $som->valueof; # can be undef too
  } else {
    # doesn't exist
  }

envelope()

Returns a hash with an deserialized envelope. Keys in this hash will be 'Header' (if present) and 'Body'. Values will be the deserialized header and body, respectively. If called as function (SOAP::SOM::envelope) it will return a Xpath string that matches the envelope content. Useful when you want just match it and then iterate over the content by yourself. Example:

  if ($som->match(SOAP::SOM::envelope)) {
    $som->valueof('Header'); # should give access to header if present
    $som->valueof('Body');   # should give access to body
  } else {
    # hm, are we doing SOAP or what?
  }

header()

Returns a hash with the deserialized header. If you want to access all attributes in the header use:

  # get element as SOAP::Data object 
  $transaction = $som->match(join '/', SOAP::SOM::header, 'transaction')->dataof;
  # then you can access all attributes of 'transaction' element
  $transaction->attr;

headers()

Returns a node set of deserialized headers. The difference between the header() and headers() methods is that the first gives you access to the whole header and second to the headers inside the 'Header' tag:

  $som->headerof(join '/', SOAP::SOM::header, '[1]');
  # gives you first header as SOAP::Header object

  ($som->headers)[0];
  # gives you value of the first header, same as
  $som->valueof(join '/', SOAP::SOM::header, '[1]');

  $som->header->{name_of_your_header_here}
  # gives you value of name_of_your_header_here

body()

Returns a hash with the deserialized body.

fault()

Returns a (hash) value of 'Fault' elements: faultcode, faultstring and detail. If the 'Fault' element is present, result(), paramsin(), paramsout() and method() will return an undef.

faultcode()

Returns the value of the faultcode element if present and undef otherwise.

faultstring()

Returns the value of the faultstring element if present and undef otherwise.

faultactor()

Returns the value of the faultactor element if present and undef otherwise.

faultdetail()

Returns the value of the detail element if present and undef otherwise.

method()

Returns the value of the method element (all input parameters if you call it on a deserialized request envelope, and result/output parameters if you call it on a deserialized response envelope). Returns undef if the 'Fault' element is present.

result()

Returns the value of the result of the method call. In fact, it will return the first child element (in document order) of the method element.

paramsin()

Returns the value(s) of all passed parameters.

paramsout()

Returns value(s) of the output parameters.

SOAP::Schema

SOAP::Schema gives you ability to load schemas and create stubs according to these schemas. Different syntaxes are provided:

•   use SOAP::Lite
      schema => 'http://www.xmethods.net/sd/StockQuoteService.wsdl',
      # schema => 'file:/your/local/path/StockQuoteService.wsdl',
      # schema => 'file:./StockQuoteService.wsdl',
    ;
    print getQuote('MSFT'), "\n";

•   use SOAP::Lite;
    print SOAP::Lite
      -> schema('http://www.xmethods.net/sd/StockQuoteService.wsdl')
      -> getQuote('MSFT'), "\n";

•   use SOAP::Lite;
    my $service = SOAP::Lite
      -> schema('http://www.xmethods.net/sd/StockQuoteService.wsdl');
    print $service->getQuote('MSFT'), "\n";

You can create stub with stubmaker script:

  perl stubmaker.pl http://www.xmethods.net/sd/StockQuoteService.wsdl

and you'll be able to access SOAP services in one line:

  perl "-MStockQuoteService qw(:all)" -le "print getQuote('MSFT')"

or dynamically:

  perl "-MSOAP::Lite schema=>'file:./quote.wsdl'" -le "print getQuote('MSFT')"

Other supported syntaxes with stub(s) are:

•   use StockQuoteService ':all';
    print getQuote('MSFT'), "\n";

•   use StockQuoteService;
    print StockQuoteService->getQuote('MSFT'), "\n";

•   use StockQuoteService;
    my $service = StockQuoteService->new;
    print $service->getQuote('MSFT'), "\n";

Support for schemas is limited for now. Though module was tested with dozen different schemas it won't understand complex objects and will work only with WSDL.

SOAP::Trace

SOAP::Trace provides you with a trace/debug facility for the SOAP::Lite library. To activate it you need to specify a list of traceable events/parts of SOAP::Lite:

  use SOAP::Lite +trace =>
    qw(list of available traces here);

Available events are:

 transport  -- (client) access to request/response for transport layer
 dispatch   -- (server) shows full name of dispatched call 
 result     -- (server) result of method call
 parameters -- (server) parameters for method call
 headers    -- (server) headers of received message
 objects    -- (both)   new/DESTROY calls
 method     -- (both)   parameters for '->envelope(method =>' call
 fault      -- (both)   parameters for '->envelope(fault =>' call
 freeform   -- (both)   parameters for '->envelope(freeform =>' call
 trace      -- (both)   trace enters into some important functions
 debug      -- (both)   details about transport

For example:

  use SOAP::Lite +trace =>
    qw(method fault);

lets you output the parameter values for all your fault/normal envelopes onto STDERR. If you want to log it you can either redirect STDERR to some file

  BEGIN { open(STDERR, '>>....'); }

or (preferably) define your own function for a particular event:

  use SOAP::Lite +trace =>
    method => sub {'log messages here'}, fault => \&log_faults;

You can share the same function for several events:

  use SOAP::Lite +trace =>
    method, fault => \&log_methods_and_faults;

Also you can use 'all' to get all available tracing and use '-' in front of an event to disable particular event:

  use SOAP::Lite +trace =>
    all, -transport; # to get all logging without transport messages

Finally,

  use SOAP::Lite +trace;

will switch all debugging on.

You can use 'debug' instead of 'trace'. I prefer 'trace', others 'debug'. Also on_debug is available for backward compatibility, as in

  use SOAP::Lite;

  my $s = SOAP::Lite 
    -> uri('http://tempuri.org/')
    -> proxy('http://beta.search.microsoft.com/search/MSComSearchService.asmx')
    -> on_debug(sub{print@_}) # show you request/response with headers
  ;
  print $s->GetVocabulary(SOAP::Data->name('~:Query' => 'something'))
          ->valueof('//FOUND');

or switch it on individually, with

  use SOAP::Lite +trace => debug;

or

  use SOAP::Lite +trace => debug => sub {'do_what_I_want_here'};

Compare this with:

  use SOAP::Lite +trace => transport;

which gives you access to B<actual> request/response objects, so you can even 
set/read cookies or do whatever you want there.

The difference between debug and transport is that transport will get a HTTP::Request/HTTP::Response object and debug will get a stringified request (NOT OBJECT!). It can also be called in other places too.

FEATURES AND OPTIONS

IN/OUT, OUT PARAMETERS AND AUTOBINDING

SOAP::Lite gives you access to all parameters (both in/out and out) and also does some additional work for you. Lets consider following example:

  <mehodResponse>
    <res1>name1</res1>
    <res2>name2</res2>
    <res3>name3</res3>
  </mehodResponse>

In that case:

  $result = $r->result; # gives you 'name1'
  $paramout1 = $r->paramsout;      # gives you 'name2', because of scalar context
  $paramout1 = ($r->paramsout)[0]; # gives you 'name2' also
  $paramout2 = ($r->paramsout)[1]; # gives you 'name3'

or

  @paramsout = $r->paramsout; # gives you ARRAY of out parameters
  $paramout1 = $paramsout[0]; # gives you 'res2', same as ($r->paramsout)[0]
  $paramout2 = $paramsout[1]; # gives you 'res3', same as ($r->paramsout)[1]

Generally, if server returns return (1,2,3) you will get 1 as the result and 2 and 3 as out parameters.

If the server returns return [1,2,3] you will get an ARRAY from result() and undef from paramsout() . Results can be arbitrary complex: they can be an array of something, they can be objects, they can be anything and still be returned by result() . If only one parameter is returned, paramsout() will return undef.

But there is more. If you have in your output parameters a parameter with the same signature (name+type) as in the input parameters this parameter will be mapped into your input automatically. Example:

server:

  sub mymethod {
    shift; # object/class reference
    my $param1 = shift;
    my $param2 = SOAP::Data->name('myparam' => shift() * 2);
    return $param1, $param2;
  }

client:

  $a = 10;
  $b = SOAP::Data->name('myparam' => 12);
  $result = $soap->mymethod($a, $b);

After that, $result == 10 and $b->value == 24! Magic? Kind of. Autobinding gives it to you. That will work with objects also with one difference: you do not need to worry about the name and the type of object parameter. Consider the PingPong example (examples/My/PingPong.pm and examples/pingpong.pl):

server:

  package My::PingPong;

  sub new { 
    my $self = shift;
    my $class = ref($self) || $self;
    bless {_num=>shift} => $class;
  }

  sub next {
    my $self = shift;
    $self->{_num}++;
  }

client:

  use SOAP::Lite +autodispatch =>
    uri => 'urn:', 
    proxy => 'http://localhost/'
  ;

  my $p = My::PingPong->new(10); # $p->{_num} is 10 now, real object returned 
  print $p->next, "\n";          # $p->{_num} is 11 now!, object autobinded

AUTODISPATCHING

WARNING! This feature can have side effects for your application and can affect functionality of other modules/libraries because of overloading UNIVERSAL::AUTOLOAD. All unresolved calls will be dispatched as SOAP calls, however it could be not what you want in some cases. If so, consider using object interface.

SOAP::Lite provides an autodispatching feature that lets you create code which looks the same for local and remote access.

For example:

  use SOAP::Lite +autodispatch =>
    uri => 'urn:/My/Examples', 
    proxy => 'http://localhost/'
  ;

tells SOAP to 'autodispatch' all calls to the 'http://localhost/' endpoint with the 'urn:/My/Examples' uri. All consequent method calls can look like:

  print getStateName(1), "\n";
  print getStateNames(12,24,26,13), "\n";
  print getStateList([11,12,13,42])->[0], "\n";
  print getStateStruct({item1 => 10, item2 => 4})->{item2}, "\n";

As you can see, there is no SOAP specific coding at all.

The same logic will work for objects as well:

  print "Session iterator\n";
  my $p = My::SessionIterator->new(10);     
  print $p->next, "\n";  
  print $p->next, "\n";

This will access the remote My::SessionIterator module, gets an object, and then calls remote methods again. The object will be transferred to the server, the method is executed there and the result (and the modified object!) will be transferred back to the client.

Autodispatch will work only if you do not have the same method in your code. For example, if you have use My::SessionIterator somewhere in your code of our previous example, all methods will be resolved locally and no SOAP calls will be done. If you want to get access to remote objects/methods even in that case, use SOAP:: prefix to your methods, like:

  print $p->SOAP::next, "\n";

See pingpong.pl for example of a script, that works with the same object locally and remotely.

You can mix autodispatch and usual SOAP calls in the same code if you need it. Keep in mind, that calls with SOAP:: prefix should always be a method call, so if you want to call functions, use SOAP-myfunction()> instead of SOAP::myfunction().

Be warned though Perl has very flexible syntax some versions will complain

  Bareword "autodispatch" not allowed while "strict subs" in use ...

if you try to put 'autodispatch' and '=>' on separate lines. So, keep them on the same line, or put 'autodispatch' in quotes:

  use SOAP::Lite 'autodispatch' # DON'T use plus in this case
    => .... 
  ;

ACCESSING HEADERS AND ENVELOPE ON SERVER SIDE

SOAP::Lite gives you direct access to all headers and the whole envelope on the server side. Consider the following code from My::Parameters.pm:

  sub byname { 
    my($a, $b, $c) = @{pop->method}{qw(a b c)};
    return "a=$a, b=$b, c=$c";
  }

You will get this functionality ONLY if you inherit your class from the SOAP::Server::Parameters class. This should keep existing code working and provides this feature only when you need it.

Every method on server side will be called as class/object method, so it will get an object reference or a class name as the first parameter, then the method parameters, and then an envelope as SOAP::SOM object. Shortly:

  $self [, @parameters] , $envelope

If you have a fixed number of parameters, you can simple do:

  my $self = shift;
  my($param1, $param2) = @_;

and ignore the envelope. If you need access to the envelope you can do:

  my $envelope = pop;

since the envelope is always the last element in the parameters list. The byname() method pop->method will return a hash with parameter names as hash keys and parameter values as hash values:

  my($a, $b, $c) = @{pop->method}{qw(a b c)};

gives you by-name access to your parameters.

SERVICE DEPLOYMENT. STATIC AND DYNAMIC

Let us scrutinize the deployment process. When designing your SOAP server you can consider two kind of deployment: static and dynamic. For both, static and dynamic, you should specify MODULE, MODULE::method, method or PATH/ when creating useing the SOAP::Lite module. The difference between static and dynamic deployment is that in case of 'dynamic', any module which is not present will be loaded on demand. See the SECURITY section for detailed description.

Example for static deployment:

  use SOAP::Transport::HTTP;
  use My::Examples;           # module is preloaded

  SOAP::Transport::HTTP::CGI
    # deployed module should be present here or client will get 'access denied'
    -> dispatch_to('My::Examples') 
    -> handle;

Example for dynamic deployment:

  use SOAP::Transport::HTTP;
  # name is unknown, module will be loaded on demand

  SOAP::Transport::HTTP::CGI
    # deployed module should be present here or client will get 'access denied'
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'My::Examples') 
    -> handle;

For static deployment you should specify the MODULE name directly. For dynamic deployment you can specify the name either directly (in that case it will be required without any restriction) or indirectly, with a PATH In that case, the ONLY path that will be available will be the PATH given to the dispatch_to() method). For information how to handle this situation see SECURITY section.

You should also use static binding when you have several different classes in one file and want to make them available for SOAP calls.

SECURITY

Due to security reasons, the current path for perl modules (@INC) will be disabled once you have chosen dynamic deployment and specified your own PATH/. If you want to access other modules in your included package you have several options:

1. Switch to static linking:

      use MODULE;
      $server->dispatch_to('MODULE');

   It can be useful also when you want to import something specific from the deployed modules:

      use MODULE qw(import_list);

2. Change use to require. The path is unavailable only during the initialization part, and it is available again during execution. So, if you do require somewhere in your package, it will work.

3. Same thing, but you can do:

      eval 'use MODULE qw(import_list)'; die if $@;

4. Assign a @INC directory in your package and then make use. Don't forget to put @INC in BEGIN{} block or it won't work:

      BEGIN { @INC = qw(my_directory); use MODULE }

OBJECTS-BY-REFERENCE

SOAP::Lite implements an experimental (yet fully functional) support for objects-by-reference. You should not see any difference on the client side when using this. On the server side you should specify the names of the classes you want to be returned by reference (instead of by value) in the objects_by_reference() method for your server implementation (see soap.pop3, soap.daemon and Apache.pm).

Garbage collection is done on the server side (not earlier than after 600 seconds of inactivity time), and you can overload the default behavior with specific functions for any particular class.

Binding does not have any special syntax and is implemented on server side (see the differences between My::SessionIterator and My::PersistentIterator). On the client side, objects will have same type/class as before (My::SessionIterator->new() will return an object of class My::SessionIterator). However, this object is just a stub with an object ID inside.

DEFAULT HANDLERS

The use SOAP::Lite syntax also lets you specify default event handlers for your code. Imagine to have different SOAP objects and that you want to share the same on_action() (or on_fault() for that matter) handler. You can specify on_action() during initialization for every object, but also you can do:

  use SOAP::Lite on_action => sub {sprintf '%s#%s', @_};

and this handler will be the default handler for all your SOAP objects. You can override it if you specify a handler for a particular object. See test.pl as example of on_fault() handler.

INTEROPERABILITY

Microsoft's .NET

To use .NET client and SOAP::Lite server

declare proper soapAction (uri#method) in your SDL file or client code

use fully qualified name for your return value, e.g.:

  return SOAP::Data->name('~:myname')->type('string')->value($output);

To use SOAP::Lite client and .NET server

1. declare proper soapAction (uri/method) in your call

2. use fully qualified name for method parameters, e.g.:

     example SOAPsh call (all should be in one line)
     > perl SOAPsh.pl "http://beta.search.microsoft.com/search/mscomsearchservice.asmx";
      "http://tempuri.org/";
      "on_action(sub{sprintf '%s%s', @_ })"
      "GetVocabulary(SOAP::Data->name('~:Query'  => 'biztalk'))"

Thanks to Petr Janata (petr.janata@i.cz) for description and examples.

BUGS AND LIMITATIONS

• No support for multidimensional, partially transmitted and sparse arrays (however arrays of arrays are supported, as well as any other data structures, and you can add your own implementation with SOAP::Data).

• Limited support for xsd schemas.

PLATFORMS

MacOS

Information about XML::Parser for MacPerl could be found here: http://bumppo.net/lists/macperl-modules/1999/07/msg00047.html

Compiled XML::Parser for MacOS could be found here: http://www.perl.com/CPAN-local/authors/id/A/AS/ASANDSTRM/XML-Parser-2.27-bin-1-MacOS.tgz

AVAILABILITY

You can download the latest version SOAP::Lite for Unix or SOAP::Lite for Win32 ( http://geocities.com/paulclinger/soap.html ). SOAP::Lite is available also from CPAN ( http://search.cpan.org/search?dist=SOAP-Lite ). You are very welcome to write mail to the authors (paulclinger@yahoo.com) with your comments, suggestions, bug reports and complaints.

SEE ALSO

the SOAP manpage SOAP/Perl library from Keith Brown ( http://www.develop.com/soap/ ) or ( http://search.cpan.org/search?dist=SOAP )

COPYRIGHT

Copyright (C) 2000 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)