NAME

ResourcePool::Command::SOAP::Lite::Call - A command to invoke a SOAP RPC call with ResourcePool.

SYNOPSIS

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

DESCRIPTION

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!

ResourcePool::Command::SOAP::Lite::Call->new($namespace)

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

$namespace: Identifies the SOAP namespace(uri) which will be accessed with this command. This is usually a URN which identifies the logical service. Even if this is a URL the service is accessed at the proxy which was specified to the Factory.

$pool->execute($method)

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: Specifies the name of the remote method to be invoked. The execute() method will invoke this method within the namespace specified to the constructor of the command using the proxy specified to the Factory.

FAULTS

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.

EXAMPLE

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.

AUTHOR

    Copyright (C) 2001-2009 by Markus Winand <mws@fatalmind.com>

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