1RPC::XML::Client(3) User Contributed Perl Documentation RPC::XML::Client(3)
2
6 RPC::XML::Client - An XML-RPC client class
7
9 require RPC::XML;
10 require RPC::XML::Client;
11 $cli = RPC::XML::Client->new('http://www.localhost.net/RPCSERV');
13 $resp = $cli->send_request('system.listMethods');
14 print ref $resp ? join(', ', @{$resp->value}) : "Error: $resp";
16
18 This is an XML-RPC client built upon the RPC::XML data classes, and
19 using LWP::UserAgent and HTTP::Request for the communication layer.
20 This client supports the full XML-RPC specification.
21
23 The following methods are available:
24 new (URI [, ARGS])
26 Creates a new client object that will route its requests to the URL
27 provided. The constructor creates a HTTP::Request object and a
28 LWP::UserAgent object, which are stored on the client object. When
29 requests are made, these objects are ready to go, with the headers
30 set appropriately. The return value of this method is a reference
31 to the new object. The "URI" argument may be a string or an object
32 from the URI class from CPAN.
33 Any additional arguments are treated as key-value pairs. Most are
35 attached to the object itself without change. The following are
36 recognized by "new" and treated specially:
37 parser
39 If this parameter is passed, the value following it is expected
40 to be an array reference. The contents of that array are passed
41 to the new method of the RPC::XML::ParserFactory-generated
42 object that the client object caches for its use. See the
43 RPC::XML::ParserFactory manual page for a list of recognized
44 parameters to the constructor.
45 useragent
47 This is similar to the "parser" argument above, and also
48 expects an array reference to follow it. The contents are
49 passed to the constructor of the LWP::UserAgent class when
50 creating that component of the client object. See the manual
51 page for LWP::UserAgent for supported values.
52 error_handler
54 If passed, the value must be a code reference that will be
55 invoked when a request results in a transport-level error. The
56 closure will receive a single argument, the text of the error
57 message from the failed communication attempt. It is expected
58 to return a single value (assuming it returns at all).
59 fault_handler
61 If passed, the value must be a code reference. This one is
62 invoked when a request results in a fault response from the
63 server. The closure will receive a single argument, a
64 RPC::XML::fault instance that can be used to retrieve the code
65 and text-string of the fault. It is expected to return a single
66 value (if it returns at all).
67 combined_handler
69 If this parameter is specified, it too must have a code
70 reference as a value. It is installed as the handler for both
71 faults and errors. Should either of the other parameters be
72 passed in addition to this one, they will take precedence over
73 this (more-specific wins out over less). As a combined handler,
74 the closure will get a string (non-reference) in cases of
75 errors, and an instance of RPC::XML::fault in cases of faults.
76 This allows the developer to install a simple default handler,
77 while later providing a more specific one by means of the
78 methods listed below.
79 message_file_thresh
81 If this key is passed, the value associated with it is assumed
82 to be a numerical limit to the size of in-memory messages. Any
83 out-bound request that would be larger than this when
84 stringified is instead written to an anonynous temporary file,
85 and spooled from there instead. This is useful for cases in
86 which the request includes RPC::XML::base64 objects that are
87 themselves spooled from file-handles. This test is independent
88 of compression, so even if compression of a request would drop
89 it below this threshhold, it will be spooled anyway. The file
90 itself is created via File::Temp with UNLINK=>1, so once it is
91 freed the disk space is immediately freed.
92 message_temp_dir
94 If a message is to be spooled to a temporary file, this key can
95 define a specific directory in which to open those files. If
96 this is not given, then the "tmpdir" method from the File::Spec
97 package is used, instead.
98 See the section on the effects of callbacks on return values,
100 below.
101 uri ([URI])
103 Returns the URI that the invoking object is set to communicate with
104 for requests. If a string or "URI" class object is passed as an
105 argument, then the URI is set to the new value. In either case, the
106 pre-existing value is returned.
107 useragent
109 Returns the LWP::UserAgent object instance stored on the client
110 object. It is not possible to assign a new such object, though
111 direct access to it should allow for any header modifications or
112 other needed operations.
113 request
115 Returns the HTTP::Request object. As with the above, it is not
116 allowed to assign a new object, but access to this value should
117 allow for any needed operations.
118 simple_request (ARGS)
120 This is a somewhat friendlier wrapper around the next routine
121 ("send_request") that returns Perl-level data rather than an object
122 reference. The arguments may be the same as one would pass to the
123 RPC::XML::request constructor, or there may be a single request
124 object as an argument. The return value will be a native Perl
125 value. If the return value is "undef", an error has occurred and
126 "simple_request" has placed the error message in the global
127 variable "$RPC::XML::ERROR".
128 send_request (ARGS)
130 Sends a request to the server and attempts to parse the returned
131 data. The argument may be an object of the RPC::XML::request class,
132 or it may be the arguments to the constructor for the request
133 class. The return value will be either an error string or a data-
134 type object. If the error encountered was a run-time error within
135 the RPC request itself, then the call will return a
136 "RPC::XML::fault" value rather than an error string.
137 If the return value from "send_request" is not a reference, then it
139 can only mean an error on the client-side (a local problem with the
140 arguments and/or syntax, or a transport problem). All data-type
141 classes now support a method called "is_fault" that may be easily
142 used to determine if the "successful" return value is actually a
143 "RPC::XML::fault" without the need to use "UNIVERSAL::ISA".
144 error_handler ([CODEREF])
146 fault_handler ([CODEREF])
147 combined_handler ([CODEREF])
148 These accessor methods get (and possibly set, if CODEREF is passed)
149 the specified callback/handler. The return value is always the
150 current handler, even when setting a new one (allowing for later
151 restoration, if desired).
152 credentials (REALM, USERNAME, PASSWORD)
154 This sets the username and password for a given authentication
155 realm at the location associated with the current request URL.
156 Needed if the RPC location is protected by Basic Authentication.
157 Note that changing the target URL of the client object to a
158 different (protected) location would require calling this with new
159 credentials for the new realm (even if the value of $realm is
160 identical at both locations).
161 timeout ([INTEGER])
163 Get or set the current time-out value on the underlying
164 LWP::UserAgent object that this object uses for sending requests.
165 This is just a proxy through to the method of the same name in the
166 LWP::UserAgent class. The return value is the current time-out
167 value (prior to change, if a new value is given).
168 message_file_thresh
170 message_temp_dir
171 These methods may be used to retrieve or alter the values of the
172 given keys as defined earlier for the "new" method.
173 Support for Content Compression
175 The RPC::XML::Server class supports compression of requests and
176 responses via the Compress::Zlib module available from CPAN.
177 Accordingly, this class also supports compression. The methods used for
178 communicating compression support should be compatible with the server
179 and client classes from the XMLRPC::Lite class that is a part of the
180 SOAP::Lite package (also available from CPAN).
181 Compression support is enabled (or not) behind the scenes; if the Perl
183 installation has Compress::Zlib, then RPC::XML::Client can deal with
184 compressed responses. However, since outgoing messages are sent before
185 a client generally has the chance to see if a server supports
186 compression, these are not compressed by default.
187 compress_requests(BOOL)
189 If a client is communicating with a server that is known to support
190 compressed messages, this method can be used to tell the client
191 object to compress any outgoing messages that are longer than the
192 threshhold setting in bytes.
193 compress_thresh([MIN_LIMIT])
195 With no arguments, returns the current compression threshhold;
196 messages smaller than this number of bytes will not be compressed,
197 regardless of the above method setting. If a number is passed, this
198 is set to the new lower-limit. The default value is 4096 (4k).
199 Callbacks and Return Values
201 If a callback is installed for errors or faults, it will be called
202 before either of "send_request" or "simple_request" return. If the
203 callback calls die or otherwise interrupts execution, then there is no
204 need to worry about the effect on return values. Otherwise, the return
205 value of the callback becomes the return value of the original method
206 ("send_request" or "simple_request"). Thus, all callbacks are expected,
207 if they return at all, to return exactly one value. It is recommended
208 that any callback return values conform to the expected return values.
209 That is, an error callback would return a string, a fault callback
210 would return the fault object.
211
213 All methods return some type of reference on success, or an error
214 string on failure. Non-reference return values should always be
215 interpreted as errors, except in the case of "simple_request".
216
218 This began as a reference implementation in which clarity of process
219 and readability of the code took precedence over general efficiency. It
220 is now being maintained as production code, but may still have parts
221 that could be written more efficiently.
222
224 Please report any bugs or feature requests to "bug-rpc-xml at
225 rt.cpan.org", or through the web interface at
226 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML
227 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
228 notified, and then you'll automatically be notified of progress on your
229 bug as I make changes.
230
232 · RT: CPAN's request tracker
233 http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML
235 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
236 · AnnoCPAN: Annotated CPAN documentation
238 http://annocpan.org/dist/RPC-XML <http://annocpan.org/dist/RPC-XML>
240 · CPAN Ratings
242 http://cpanratings.perl.org/d/RPC-XML
244 <http://cpanratings.perl.org/d/RPC-XML>
245 · Search CPAN
247 http://search.cpan.org/dist/RPC-XML
249 <http://search.cpan.org/dist/RPC-XML>
250 · Source code on GitHub
252 http://github.com/rjray/rpc-xml/tree/master
254 <http://github.com/rjray/rpc-xml/tree/master>
255
257 This file and the code within are copyright (c) 2009 by Randy J. Ray.
258 Copying and distribution are permitted under the terms of the Artistic
260 License 2.0
261 (http://www.opensource.org/licenses/artistic-license-2.0.php
262 <http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
263 GNU LGPL 2.1 (http://www.opensource.org/licenses/lgpl-2.1.php
264 <http://www.opensource.org/licenses/lgpl-2.1.php>).
265
267 The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software,
268 Inc. See <http://www.xmlrpc.com> for more information about the XML-
269 RPC specification.
270
272 RPC::XML, RPC::XML::Server
273
275 Randy J. Ray "<rjray@blackperl.com>"
276perl v5.12.0 2009-09-03 RPC::XML::Client(3)