=head1 NAME

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

=head1 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);
 };

=head1 DESCRIPTION


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

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

=head2 S<ResourcePool::Command::SOAP::Lite::Call-E<gt>new($namespace)>

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

=over 4

=item $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 L<Factory|ResourcePool::Factory::SOAP::Lite>.

=back

=head2 S<$pool-E<gt>execute($method)>

This method is usually accessed thought the same named method of L<ResourcePool|ResourcePool> or L<ResourcePool::LoadBalancer|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 L<ResourcePool::Command::Exception|ResourcePool::Command::Exception>, please have a look at the L<FAULTS|/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.

=over 4

=item $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 L<Factory|ResourcePool::Factory::SOAP::Lite>.

=back

=head1 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 L<ResourcePool::Command::Exception|ResourcePool::Command::Exception>, use the L<rootException() method|ResourcePool::Command::Exception/rootException> 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 L<ResourcePool execution environment|ResourcePool::Command::Execute> will retry the operation if the fault was a Server fault (specified in faultcode). For a L<ResourcePool::LoadBalancer|ResourcePool::LoadBalancer> setup this might cause a fail over to another proxy. Client faults will be translated into L<ResourcePool::Command::NoFailoverExceptions|ResourcePool::Command::NoFailoverException> which will not cause any retry or fail over, those exceptions will be directly propagated to the client.

=head1 EXAMPLE


The following example illustrates the usage of the class together with L<ResourcePool::LoadBalancer|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 L<ResourcePool::LoadBalancer|ResourcePool::LoadBalancer> have a look at it's documentation.

=head1 AUTHOR

    Copyright (C) 2001-2003 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.