NAME

CAM::SOAPClient - SOAP interaction tools

LICENSE

Copyright 2006 Clotho Advanced Media, Inc., <cpan@clotho.com>

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

SYNOPSIS

  use CAM::SOAPClient;
  my $client = CAM::SOAPClient->new(wsdl => 'http://www.clotho.com/staff.wsdl');
  my ($fname, $lname) = $client->call('fetchEmployee', '[firstName,lastName]',
                                      ssn => '000-00-0000');
  my $record = $client->call('fetchEmployee', undef, ssn => '000-00-0000');
  my @addresses = $client->call('allEmployees', '@email');
  
  my $firstbudget = $client->call('listClientProjects', 
                                  '/client/projects/project/budget');
  
  if ($client->hadFault()) {
     die 'SOAP Fault: ' . $client->getLastFaultString();
  }

DESCRIPTION

This module offers some basic tools to simplify the creation of SOAP client implementations. It is intended to be subclassable, but works fine as-is too.

The purpose for this module is to abstract the complexity of SOAP::Lite. That module makes easy things really easy and hard things possible, but quite obscure. The problem is that the easy things are often too basic. For example, calling remote methods with positional arguments is easy, but with named arguments is much harder. Calling methods on a SOAP::Lite server is easy, but an Apache Axis server is much harder. This module attempts to make typical SOAP and WSDL activities easier by hiding some of the weirdness of SOAP::Lite.

The main method is call(), via which you can specify what remote method to invoke, what return values you want, and the named arguments you want to pass. See below for more detail.

This package has been tested against servers running SOAP::Lite, Apache Axis, and PEAR SOAP.

SEE ALSO

SOAP::Lite::Simple is another module with very similar goals to this one. Leo Lapworth, the author of that module, and I have briefly discussed merging the work into a single package, but have not made much progress. If any users are interested in such a merger, let us know.

METHODS

$pkg->new([opts], $uri)

$pkg->new([opts], $uri, $proxy)

$pkg->new([opts], $uri, $proxy, $username, $password)

$pkg->new([opts], wsdl => $url)

$pkg->new([opts], wsdl => $url, $username, $password)

Create a connection instance. The $proxy is not required here, but if not specified it must be set later via setProxy(). Optionally (and recommended) you can specify a WSDL $url instead of a $uri and $proxy.

If a $username is specified, then the $username and $password are simply passed to setUserPass().

The options are as follows:

timeout => $seconds

This defaults to 6 hours.

$self->setWSDL($url)

Loads a Web Service Description Language file describing the SOAP service.

$self->setURI($uri)

Specifies the URI for the SOAP server. This is not needed if you are using WSDL.

$self->setProxy($proxy)

Specifies the URL for the SOAP server. This is not needed if you are using WSDL.

$self->setUserPass($username, $password)

Specifies the $username and $password to use on the SOAP server. These values are stored until used via loginParams(). Most applications won't use this method.

$self->getLastSOM()

Returns the SOAP::SOM object for the last query.

$self->hadFault()

Returns a boolean indicating whether the last call() resulted in a fault.

$self->getLastFaultCode()

Returns the fault code from the last query, or (none) if the last query did not result in a fault.

$self->getLastFaultString()

Returns the fault string from the last query, or (none) if the last query did not result in a fault.

$self->getLastFault()

Creates a new SOAP::Fault instance from the last fault data, if any. If there was no fault (as per the hadFault() method) then this returns undef.

$self->call($method, undef, $key1 => $value1, $key2 => $value, ...)

$self->call($method, $xpath, $key1 => $value1, $key2 => $value, ...)

$self->call($method, $xpath_arrayref, $key1 => $value1, $key2 => $value, ...)

Invoke the named SOAP method. The return values are indicated in the second argument, which can be undef, a single scalar or a list of return fields. If this path is undef, then all data are returned as if the SOAP paramsout() method was called. Otherwise, the SOAP response is searched for these values. If any of them are missing, call() returns undef. If multiple values are specified, they are all returned in array context, while just the first one is returned in scalar context. This is best explained by examples:

    'documentID' 
           returns 
        /Envelope/Body/<method>/documentID

    ['documentID', 'data/[2]/type', '//result']
           returns
       (/Envelope/Body/<method>/documentID,
        /Envelope/Body/<method>/data/[2]/type,
        /Envelope/Body/<method>/*/result)
           or
        /Envelope/Body/<method>/documentID
           in scalar context

If the path matches multiple fields, just the first is returned. Alternatively, if the path is prefixed by a @ character, it is expected that the path will match multiple fields. If there is just one path, the matches are returned as an array (just the first one in scalar context). If there are multiple paths specified, then the matches are returned as an array reference. For example, imagine a query that returns a list of documents with IDs 4,6,7,10,20 for user #12. Here we detail the return values for the following paths:

  path: 'documents/item/id' or ['documents/item/id']
      returns
   array context: (4)
  scalar context: 4
  
  path: '@documents/item/id' or ['@documents/item/id']
      returns
   array context: (4,6,7,10,20)
  scalar context: 4
  
  path: ['documents/item/id', 'userID']
      returns
   array context: (4, 12)
  scalar context: 4
  
  path: ['@documents/item/id', 'userID']
      returns
   array context: ([4,6,7,10,20], 12)
  scalar context: [4,6,7,10,20]
  
  path: ['userID', '@documents/item/id']
      returns
   array context: (12, [4,6,7,10,20])
  scalar context: 12

$self->loginParams()

This is intended to return a hash of all the required parameters shared by all SOAP requests. This version returns the contents of %{$soap-{auth}}>. Some subclasses may wish to override this, while others may wish to simply add more to that hash.

$self->request($key1 => $value1, $key2 => $value2, ...)

$self->request($soapdata1, $soapdata2, ...)

Helper routine which wraps its key-value pair arguments in SOAP::Data objects, if they are not already in that form.

SEE ALSO

SOAP::Lite

CAM::SOAPApp

CODING

This module has over 80% code coverage in its regression tests, as reported by Devel::Cover via perl Build testcover.

With three policy exceptions, this module passes Perl Best Practices guidelines, as enforced by Perl::Critic v0.13.

AUTHOR

Clotho Advanced Media, cpan@clotho.com

Primary developer: Chris Dolan