NAME

CAM::SOAPClient - SOAP interaction tools

LICENSE

Copyright 2005 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() . "\n");
  }

DESCRIPTION

This library offers some basic tools to simplify the creation of SOAP client implementations. It is intended to be subclassed.

The purpose for this module is the complexity of SOAP::Lite. That module makes easy things really easy and hard things possible, but really obscure. The problem is that the easy things are often too basic. This module makes normal SOAP/WSDL activities easier by hiding some of the weirdness of SOAP::Lite.

METHODS

new [opts] URI

new [opts] URI, PROXY

new [opts] URI, PROXY, USERNAME, PASSWORD

new [opts] wsdl => URL

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, you can use a WSDL URL instead of a URI and proxy. The username and password may not be needed at all for some applications. There are included here for convenience, since many applications do need them.

The options are as follows:

timeout => seconds

This defaults to 6 hours.

setWSDL URL

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

setURI URI

Specifies the URI for the SOAP server.

setProxy PROXY

Specifies the URL for the SOAP server.

setUserPass USERNAME, PASSWORD

Specifies the username and password to use on the SOAP server.

getLastSOM

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

hadFault

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

getLastFaultString

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

call METHOD, undef, KEY => VALUE, KEY => VALUE, ...

call METHOD, XPATH, KEY => VALUE, KEY => VALUE, ...

call METHOD, XPATH_ARRAYREF, KEY => VALUE, KEY => 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

loginParams

This is intened 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.

request KEY => VALUE, KEY => VALUE, ...

request SOAPDATA, SOAPDATA, ...

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

AUTHOR

Clotho Advanced Media, cpan@clotho.com