Mark Overmeer > XML-Compile-RPC > XML::Compile::RPC::Client

Download:
XML-Compile-RPC-0.17.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.17   Source  

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.17, built on September 12, 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

syntax highlighting: