NAME

RPC::XML::Client - Sample implementation of a RPC::XML client

SYNOPSIS

    require RPC::XML;
    require RPC::XML::Client;

    $cli = new RPC::XML::Client 'http://www.localhost.net/RPCSERV';
    $resp = $cli->send_request(RPC::XML::request->new('system.listMethods');

    # Assuming a successful return, should produce a well-formed XML doc
    print $resp->as_string;

DESCRIPTION

This is a sample 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.

METHODS

The following methods are available:

new (URI)

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.

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 allows for more flexibility on the input side, and 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, this could be due to either an actual return value from the request, or an error. simple_request clears the global error variable $RPC::XML::ERROR before the call, and as such the developer may assume that if this variable has data upon return, then the empty return value is due to an error.

send_request (REQ)

Sends a request to the server and attempts to parse the returned data. The argument is an object of the RPC::XML::request class, and the return value will be either an error string or a response object. See RPC::XML for more on the response class and its methods. If the error encountered was a run-time error within the RPC request itself, then the client will return a response object that encapsulates a RPC::XML::fault value rather than an error string.

DIAGNOSTICS

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.

CAVEATS

This is a reference implementation in which clarity of process and readability of the code took precedence over general efficiency. Much, if not all, of this can be written more compactly and/or efficiently.

CREDITS

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.

LICENSE

This module is licensed under the terms of the Artistic License that covers Perl itself. See <http://language.perl.com/misc/Artistic.html> for the license itself.

SEE ALSO

RPC::XML, RPC::XML::Server

AUTHOR

Randy J. Ray <rjray@blackperl.com>