/ 
XML-Compile-RPC-0.16
River stage one • 1 direct dependent • 1 total dependent
/ XML::Compile::RPC::Client

NAME

XML::Compile::RPC::Client - XML-RPC based on unofficial schema

DESCRIPTION

Client XML-RPC implementation, based on an unofficial XML-RPC schema. The schema used is an extended version from one produced by Elliotte Rusty Harold.

Using the schema with XML::Compile means that the messages are validated. Besides, XML::Compile offers you some tricks: for instance, you can pass a time() result (seconds since epoc)to a dateTime.iso8601 field, which will automaticallu get formatted into the right format.

In XML-RPC, values which do not explicitly specify their type are interpreted as string. So, you may encounter two notations for the same:

<value><string>Hello, World!</string></value>
<value>Hello, World!</value>

The reader (used to produce the $response) will translate the second syntax in the first. This simplifies your code.

METHODS

Constructors

XML::Compile::RPC::Client->new(OPTIONS)
-Option                --Default
 autoload_underscore_is  '_'
 destination             <required>
 http_header             []
 schemas                 <created for you>
 user_agent              <created internally>
 xmlformat               0
autoload_underscore_is => STRING

When calls are made using the autoload mechanism you may encounter problems when the method names contain dashes (-). So, with this option, you can use underscores which will all be replaced to STRING value specified.

destination => URI

The address of the XML-RPC server.

http_header => ARRAY|OBJECT

Additional headers for the HTTP request. This is either an ARRAY of key-value pairs, or an HTTP::Headers OBJECT.

schemas => OBJECT

When you need special additional trics with the schemas, you may pass your own XML::Compile::RPC instance. However, by default this is created for you.

user_agent => OBJECT

You may pass your own LWP::UserAgent object, fully loaded with your own settings. When you do not, one will be created for you.

xmlformat => 0|1|2

XML::LibXML has three different output formats. Format 0 is the most condense, and 1 is nicely indented. Of course, a zero value is fastest.

Accessors

$obj->headers()

Returns the internal HTTP::Headers, which you may modify (for instance to change/set the Authentication field.

$obj->schemas()

Returns the internal XML::Compile::RPC object, used to encode and decode the exchanged XML messages.

Handlers

$obj->call(METHOD, PARAM-(HASH|PAIR)S)

example:

my ($rc, $response) = $rpc->call('getQuote', string => 'IBM');
$rc == 0
    or die "error: $response\n";
my $trace = $rpc->trace;  # facts about the last call

# same call, via autoload. One simple parameter
my ($rc, $response) = $rpc->getQuote(string => 'IBM');

# function produces a HASH, one complex parameter
my $struct = struct_from_hash string => symbol => 'IBM';
my ($rc, $response) = $rpc->call('getQuote', $struct);
my ($rc, $response) = $rpc->getQuote($struct);

# or mixed simple and complex types
# Three parameters, of which two are complex structures.
my ($rc, $ans) = $rcp->someMethod($struct, int => 3, $struct2);
$obj->printTrace([FILEHANDLE])

Pretty print the trace, by default to STDERR.

$obj->trace()

Returns a HASH with various facts about the last call; timings, the request and the response from the server. Be aware that LWP will add some more header lines to the request before it is sent.

DETAILS

Create an interface

My advice: if you have to use XML-RPC, first create an abstraction layer. That layer should implement error handling and logging. Have a look at XML::eXistDB::Client for an extended example.

package My::Service;
use base 'XML::Compile::RPC::Client';

sub getQuote($)
{   my ($self, $symbol) = @_;
    my $params = struct_from_hash string => {symbol => $symbol};
    my ($rc, $data) = $self->call(getQuote => $params);
    $rc==0 or die "error: $data ($rc)";

    # now simplify $data
    $data;
}

Now, the main program runs like this:

my $service = My::Service->new(destination => $uri);
my $price   = $service->getQuote('IBM');

Comparison

The XML::RPC module uses the XML::TreePP XML parser and parameter type guessing, where XML::Compile::RPC uses strict typed and validated XML via XML::LibXML: smaller chance on unexpected behavior. For instance, the XML::Compile::RPC client application will not produce incorrect messages when a string contains only digits. Besides, XML::RPC does not support all data types.

XML::RPC::Fast is compatible with XML::RPC, but uses XML::LibXML which is faster and safer. It implements "manually" what XML::Compile offers for free in XML::Compile::RPC. Getting the types of the parameters right is difficult for other things than strings and numbers.

Finally, RPC::XML makes you handle parameters as object: create a typed object for each passed value. It offers a standard method signatures to simplify that task. On the other hand, RPC::XML does offer more features.

There are many ways to do it.

SYNOPSYS

my $rpc = XML::Compile::RPC::Client->new
  ( destination => $service_uri
  , xmlformat   => 1
  , autoload_underscore_is => '-'
  );

# Call the server
my ($rc, $answer) = $rpc->call($procedure, @param_pairs);
my ($rc, $answer) = $rpc->call($procedure, \%params);
$rc==0 or die "error: $answer ($rc)";

# explict and autoload examples of the same.
my ($rc, $answer) = $rpc->call('getQuote", string => 'IBM');
my ($rc, $answer) = $rpc->getQuote(string => 'IBM');

# when param is a structure:
my $data = struct_from_hash string => {symbol => 'IBM'};
my ($rc, $answer) = $rpc->call('getQuote", $data);
my ($rc, $answer) = $rpc->getQuote($data);

# Data::Dumper is your friend
use Data::Dumper;
$Data::Dumper::Indent = 1;
print Dumper $answer;

# Many useful functions in XML::Compile::RPC::Util
use XML::Compile::RPC::Util;
if($answer->{array})
{   my @a = rpcarray_values $answer->{array};
}

# Retreive detailed trace of last call
my $trace = $rpc->trace;
print $trace->{response}->as_string;
print "$trace->{total_elapse}\n";

# clean-up of connections depends on LWP
undef $rpc;

SEE ALSO

This module is part of XML-Compile-RPC distribution version 0.16, built on August 18, 2013. Website: http://perl.overmeer.net/xml-compile/

Other distributions in this suite: XML::Compile, XML::Compile::SOAP, XML::Compile::SOAP12, XML::Compile::SOAP::Daemon, XML::Compile::SOAP::WSA, XML::Compile::C14N, XML::Compile::WSS, XML::Compile::WSS::Signature, XML::Compile::Tester, XML::Compile::Cache, XML::Compile::Dumper, XML::Compile::RPC, XML::Rewrite and XML::LibXML::Simple.

Please post questions or ideas to the mailinglist at http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile . For live contact with other developers, visit the #xml-compile channel on irc.perl.org.

LICENSE

Copyrights 2009-2013 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html