XML::Compile::RPC::Client - XML-RPC based on unofficial schema
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;
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.
time()
dateTime.iso8601
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.
$response
-Option --Default autoload_underscore_is '_' destination <required> http_header [] schemas <created for you> user_agent <created internally> xmlformat 0
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.
-
The address of the XML-RPC server.
Additional headers for the HTTP request. This is either an ARRAY of key-value pairs, or an HTTP::Headers 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.
You may pass your own LWP::UserAgent object, fully loaded with your own settings. When you do not, one will be created for you.
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.
0
1
Returns the internal HTTP::Headers, which you may modify (for instance to change/set the Authentication field.
Returns the internal XML::Compile::RPC object, used to encode and decode the exchanged XML messages.
The call parameters are passed as PAIRS or HASH.
example:
my ($rc, $response, $trace) = $rpc->call('getQuote', string => 'IBM'); $rc == 0 or die "error: $response\n"; # If you did not catch trace on time my $trace = $rpc->trace; # facts about the last call # same call, via autoload of 'getQuote'. One simple parameter my ($rc, $resp, $trace) = $rpc->getQuote(string => 'IBM'); # function produces a HASH, example complex parameter my $struct = struct_from_hash string => symbol => 'IBM'; my ($rc, $resp, $trace) = $rpc->call('getQuote', $struct); my ($rc, $resp, $trace) = $rpc->getQuote($struct); # or mixed simple and complex types # Three parameters, of which two are complex structures. my ($rc, $resp, $t) = $rcp->someMethod($struct, int => 3, $struct2);
Pretty print the trace, by default to STDERR.
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.
LWP
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, $trace) = $self->call(getQuote => $params); $rc==0 or die "error: $data ($rc)"; # now simplify $data ... return $data; }
Now, the main program runs like this:
my $service = My::Service->new(destination => $uri); my $price = $service->getQuote('IBM');
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 "standard" 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 not easy 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.
This module is part of XML-Compile-RPC distribution version 0.20, built on January 15, 2020. Website: http://perl.overmeer.net/xml-compile/
Copyrights 2009-2020 by [Mark Overmeer <markov@cpan.org>]. 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://dev.perl.org/licenses/
To install XML::Compile::RPC, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XML::Compile::RPC
CPAN shell
perl -MCPAN -e shell install XML::Compile::RPC
For more information on module installation, please visit the detailed CPAN module installation guide.