use ResourcePool::Command::SOAP::Lite::Call;

my $cmd = ResourcePool::Command::SOAP::Lite::Call->new(
  "namespace"
);
eval {
  my $result = $pool->execute($cmd, "method", "argument1", $arg2);
};

This command makes it possible to use ResourcePool's and ResourcePool::LoadBalancer's and recovering, fail over and load balancing capabilities for SOAP RPC calls.

This class supports only a very small sub set of SOAP::Lites capabilities. People who are interested in taking over maintenance of this package to make it more generic are welcome!

Constructs a object which can be used as first argument to ResourcePools and ResourcePool::LoadBalancers execute() methods.

$namespace

This method is usually accessed thought the same named method of ResourcePool or ResourcePool::LoadBalancer. The description here explains how to use this method with a ResourcePool or LoadBalancer, it's not intended to be invoked by manual.

This method invokes a remote SOAP RPC method. The return value of the remote method will be returned. Faults will be propagated through an ResourcePool::Command::Exception, please have a look at the FAULTS section below for details about the exception handling.

The first parameter is required, additional parameters will be passed to the remote method as positional parameters.

$method

SOAP faults are propagated to the client as exceptions. So if you want to catch them, you have to use a eval {} block like shown in the example below.

The exception thrown is of the type ResourcePool::Command::Exception, use the rootException() method to obtain the SOAP::Fault object:

eval {
  $pool->execute($cmd, "method");
};

if ($@) { # if an exception happend
  # $soapfault will be of type SOAP::Fault 
  # as described in SOAP::Lite
  my $soapfault = $@->rootException();
  printf("faultcode: %s\nfaultstring: %s\n" 
    . "faultdetail: %s\nfaultactor: %s\n"
    , $soapfault->faultcode()
    , $soapfault->faultstring()
    , $soapfault->faultdetail()
    , $soapfault->faultactor()
  );
}

If a SOAP fault happens, the ResourcePool execution environment will retry the operation if the fault was a Server fault (specified in faultcode). For a ResourcePool::LoadBalancer setup this might cause a fail over to another proxy. Client faults will be translated into ResourcePool::Command::NoFailoverExceptions which will not cause any retry or fail over, those exceptions will be directly propagated to the client.

The following example illustrates the usage of the class together with ResourcePool::LoadBalancer in order to gain better availability.

It assumes that you have two servers (host1 and host2) which are capable of handling your SOAP requests. The namespace used for the request will be 'StockExchange', the method which will be invoked is called 'getquote'. 'TMTA' will be used as argument for this method.

use ResourcePool;
use ResourcePool::LoadBalancer;
use ResourcePool::Factory::SOAP::Lite;
use ResourcePool::Command::SOAP::Lite::Call;

my $factory1 = ResourcePool::Factory::SOAP::Lite->new(
  "host1.you.com/SOAP/"
);
my $pool1 = ResourcePool->new($factory1);

my $factory2 = ResourcePool::Factory::SOAP::Lite->new(
  "host2.you.com/SOAP/"
);
my $pool2 = ResourcePool->new($factory2);

my $lb = ResourcePool::LoadBalancer->new("SOAP");
$lb->add_pool($pool1);
$lb->add_pool($pool2);

my $cmd = ResourcePool::Command::SOAP::Lite::Call->new("StockExchange");

my $quote = $lb->execute($cmd, "getquote", "TMTA");

The example will handle simple server outages, for more details about the configuration and behavior of ResourcePool::LoadBalancer have a look at it's documentation.