RPC::XML::Client - An XML-RPC client class
require RPC::XML;
require RPC::XML::Client;
$cli = RPC::XML::Client->new('http://www.localhost.net/RPCSERV');
$resp = $cli->send_request('system.listMethods');
print ref $resp ? join(', ', @{$resp->value}) : "Error: $resp";
This is an XML-RPC client built upon the RPC::XML data
classes, and using LWP::UserAgent and HTTP::Request for the
communication layer. This client supports the full XML-RPC
specification.
The following methods are available:
- new (URI [, ARGS])
- Creates a new client object that will route its requests to the URL
provided. The constructor creates a HTTP::Request object and a
LWP::UserAgent object, which are stored on the client object. When
requests are made, these objects are ready to go, with the headers set
appropriately. The return value of this method is a reference to the new
object. The "URI" argument may be a
string or an object from the URI class from CPAN.
Any additional arguments are treated as key-value pairs. Most
are attached to the object itself without change. The following are
recognized by "new" and treated
specially:
- parser
- If this parameter is passed, the value following it is expected to be an
array reference. The contents of that array are passed to the new
method of the RPC::XML::ParserFactory-generated object that the
client object caches for its use. See the RPC::XML::ParserFactory
manual page for a list of recognized parameters to the constructor.
- useragent
- This is similar to the "parser" argument
above, and also expects an array reference to follow it. The contents are
passed to the constructor of the LWP::UserAgent class when creating
that component of the client object. See the manual page for
LWP::UserAgent for supported values.
- error_handler
- If passed, the value must be a code reference that will be invoked when a
request results in a transport-level error. The closure will receive a
single argument, the text of the error message from the failed
communication attempt. It is expected to return a single value (assuming
it returns at all).
- fault_handler
- If passed, the value must be a code reference. This one is invoked when a
request results in a fault response from the server. The closure will
receive a single argument, a RPC::XML::fault instance that can be
used to retrieve the code and text-string of the fault. It is expected to
return a single value (if it returns at all).
- combined_handler
- If this parameter is specified, it too must have a code reference as a
value. It is installed as the handler for both faults and errors. Should
either of the other parameters be passed in addition to this one, they
will take precedence over this (more-specific wins out over less). As a
combined handler, the closure will get a string (non-reference) in cases
of errors, and an instance of RPC::XML::fault in cases of faults.
This allows the developer to install a simple default handler, while later
providing a more specific one by means of the methods listed below.
- message_file_thresh
- If this key is passed, the value associated with it is assumed to be a
numerical limit to the size of in-memory messages. Any out-bound request
that would be larger than this when stringified is instead written to an
anonynous temporary file, and spooled from there instead. This is useful
for cases in which the request includes RPC::XML::base64 objects
that are themselves spooled from file-handles. This test is independent of
compression, so even if compression of a request would drop it below this
threshold, it will be spooled anyway. The file itself is created via
File::Temp with UNLINK=>1, so once it is freed the disk space is
immediately freed.
- message_temp_dir
- If a message is to be spooled to a temporary file, this key can define a
specific directory in which to open those files. If this is not given,
then the "tmpdir" method from the
File::Spec package is used, instead.
- request_as_string
- For aiding in debugging, you can pass this key with a non-false value to
enable a step in each request cycle that saves a stringified version of
the request XML as a private key on the client object. The request will be
saved to the key
"_xmlrpc_request_as_string", and will
endure until the next request is made by the client object.
See the section on the effects of callbacks on return values,
below.
- uri ([URI])
- Returns the URI that the invoking object is set to communicate with
for requests. If a string or "URI" class
object is passed as an argument, then the URI is set to the new value. In
either case, the pre-existing value is returned.
- useragent
- Returns the LWP::UserAgent object instance stored on the client
object. It is not possible to assign a new such object, though direct
access to it should allow for any header modifications or other needed
operations.
- request
- Returns the HTTP::Request object. As with the above, it is not
allowed to assign a new object, but access to this value should allow for
any needed operations.
- simple_request
(ARGS)
- This is a somewhat friendlier wrapper around the next routine
("send_request") that returns Perl-level
data rather than an object reference. The arguments may be the same as one
would pass to the RPC::XML::request constructor, or there may be a
single request object as an argument. The return value will be a native
Perl value. If the return value is
"undef", an error has occurred and
"simple_request" has placed the error
message in the global variable
"$RPC::XML::ERROR".
- send_request
(ARGS)
- Sends a request to the server and attempts to parse the returned data. The
argument may be an object of the RPC::XML::request class, or it may
be the arguments to the constructor for the request class. The return
value will be either an error string or a data-type object. If the error
encountered was a run-time error within the RPC request itself, then the
call will return a "RPC::XML::fault"
value rather than an error string.
If the return value from
"send_request" is not a reference,
then it can only mean an error on the client-side (a local problem with
the arguments and/or syntax, or a transport problem). All data-type
classes now support a method called
"is_fault" that may be easily used to
determine if the "successful" return value is actually a
"RPC::XML::fault" without the need to
use "UNIVERSAL::ISA".
- error_handler ([CODEREF])
- fault_handler ([CODEREF])
- combined_handler ([CODEREF])
- These accessor methods get (and possibly set, if CODEREF is passed) the
specified callback/handler. The return value is always the current
handler, even when setting a new one (allowing for later restoration, if
desired).
- credentials
(REALM, USERNAME, PASSWORD)
- This sets the username and password for a given authentication realm at
the location associated with the current request URL. Needed if the RPC
location is protected by Basic Authentication. Note that changing the
target URL of the client object to a different (protected) location would
require calling this with new credentials for the new realm (even if the
value of $realm is identical at both
locations).
- timeout
([INTEGER])
- Get or set the current time-out value on the underlying
LWP::UserAgent object that this object uses for sending requests.
This is just a proxy through to the method of the same name in the
LWP::UserAgent class. The return value is the current time-out
value (prior to change, if a new value is given).
- message_file_thresh
- message_temp_dir
- These methods may be used to retrieve or alter the values of the given
keys as defined earlier for the "new"
method.
The RPC::XML::Server class supports compression of requests
and responses via the Compress::Zlib module available from CPAN.
Accordingly, this class also supports compression. The methods used for
communicating compression support should be compatible with the server and
client classes from the XMLRPC::Lite class that is a part of the
SOAP::Lite package (also available from CPAN).
Compression support is enabled (or not) behind the scenes; if the
Perl installation has Compress::Zlib, then RPC::XML::Client
can deal with compressed responses. However, since outgoing messages are
sent before a client generally has the chance to see if a server supports
compression, these are not compressed by default.
- compress_requests(BOOL)
- If a client is communicating with a server that is known to support
compressed messages, this method can be used to tell the client object to
compress any outgoing messages that are longer than the threshold setting
in bytes.
- compress_thresh([MIN_LIMIT])
- With no arguments, returns the current compression threshold; messages
smaller than this number of bytes will not be compressed, regardless of
the above method setting. If a number is passed, this is set to the new
lower-limit. The default value is 4096 (4k).
If a callback is installed for errors or faults, it will be called
before either of "send_request" or
"simple_request" return. If the callback
calls die or otherwise interrupts execution, then there is no need to
worry about the effect on return values. Otherwise, the return value of the
callback becomes the return value of the original method
("send_request" or
"simple_request"). Thus, all callbacks are
expected, if they return at all, to return exactly one value. It is
recommended that any callback return values conform to the expected return
values. That is, an error callback would return a string, a fault callback
would return the fault object.
All methods return some type of reference on success, or an error
string on failure. Non-reference return values should always be interpreted
as errors, except in the case of
"simple_request".
This began as a reference implementation in which clarity of
process and readability of the code took precedence over general efficiency.
It is now being maintained as production code, but may still have parts that
could be written more efficiently.
Please report any bugs or feature requests to
"bug-rpc-xml at rt.cpan.org", or through
the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
notified, and then you'll automatically be notified of progress on your bug
as I make changes.
- RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
- AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/RPC-XML>
- CPAN Ratings
<http://cpanratings.perl.org/d/RPC-XML>
- Search CPAN
<http://search.cpan.org/dist/RPC-XML>
- MetaCPAN
<https://metacpan.org/release/RPC-XML>
- Source code on GitHub
<http://github.com/rjray/rpc-xml>
This file and the code within are copyright (c) 2011 by Randy J.
Ray.
Copying and distribution are permitted under the terms of the
Artistic License 2.0
(<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
GNU LGPL 2.1 (<http://www.opensource.org/licenses/lgpl-2.1.php>).
The XML-RPC standard is Copyright (c) 1998-2001, UserLand
Software, Inc. See <http://www.xmlrpc.com> for more information about
the XML-RPC specification.
RPC::XML, RPC::XML::Server
Randy J. Ray
"<rjray@blackperl.com>"