1RPC::XML(3) User Contributed Perl Documentation RPC::XML(3)
2
6 RPC::XML - A set of classes for core data, message and XML handling
7
9 use RPC::XML;
10 $req = RPC::XML::request->new('fetch_prime_factors',
12 RPC::XML::int->new(985_120_528));
13 ...
14 $resp = RPC::XML::ParserFactory->new()->parse(STREAM);
15 if (ref($resp))
16 {
17 return $resp->value->value;
18 }
19 else
20 {
21 die $resp;
22 }
23
25 The RPC::XML package is an implementation of the XML-RPC standard. The
26 package as a whole provides classes for data, for clients, for servers
27 and for parsers (based on the XML::Parser and XML::LibXML packages from
28 CPAN).
29 This module provides a set of classes for creating values to pass to
31 the constructors for requests and responses. These are lightweight
32 objects, most of which are implemented as blessed scalar references so
33 as to associate specific type information with the value. Classes are
34 also provided for requests, responses and faults (errors).
35 This module does not actually provide any transport implementation or
37 server basis. For these, see RPC::XML::Client and RPC::XML::Server,
38 respectively.
39
41 At present, two subroutines are available for import. They must be
42 explicitly imported as part of the "use" statement, or with a direct
43 call to "import":
44 time2iso8601([$time])
46 Convert the integer time value in $time (which defaults to calling
47 the built-in "time" if not present) to a (pseudo) ISO 8601 string
48 in the UTC time zone. This is a convenience function for occassions
49 when the return value needs to be of the dateTime.iso8601 type, but
50 the value on hand is the return from the "time" built-in. Note that
51 the format of this string is not strictly compliant with ISO 8601
52 due to the way the dateTime.iso8601 data-type was defined in the
53 specification. See "DATES AND TIMES", below.
54 smart_encode(@args)
56 Converts the passed-in arguments to datatype objects. Any that are
57 already encoded as such are passed through unchanged. The routine
58 is called recursively on hash and array references. Note that this
59 routine can only deduce a certain degree of detail about the values
60 passed. Boolean values will be wrongly encoded as integers. Pretty
61 much anything not specifically recognizable will get encoded as a
62 string object. Thus, for types such as "fault", the ISO time value,
63 base-64 data, etc., the program must still explicitly encode it.
64 However, this routine will hopefully simplify things a little bit
65 for a majority of the usage cases.
66 If an argument is a blessed reference (an object), smart_encode
68 will generally treat it as a non-blessed reference of the
69 underlying type. That is, objects based on hash references will be
70 encoded as if they are unblessed hash references (becoming
71 RPC::XML::struct objects), objects based on array references are
72 encoded as array references (RPC::XML::array), etc. Only hash
73 references, array references and scalar references are treated in
74 this fashion; any other blessed references cannot be down-graded
75 and will cause an exception to be thrown.
76 The exception to this are objects of the DateTime class: this
78 package does not utilize DateTime directly, but if you pass in a
79 reference to an existing object of that class, it is properly
80 converted to an object of the RPC::XML::datetime_iso8601 class.
81 In addition to these, the following "helper" functions are also
83 available. They may be imported explicitly, or all may be imported via
84 the tag ":types":
85 RPC_BOOLEAN RPC_INT RPC_I4 RPC_I8 RPC_DOUBLE
87 RPC_DATETIME_ISO8601 RPC_BASE64 RPC_STRING RPC_NIL
88 Each creates a data object of the appropriate type from a single value
90 (or, in the case of RPC_NIL, from no value). They are merely short-
91 hand for calling the constructors of the data classes directly.
92 All of the above (helpers and the first two functions) may be imported
94 via the tag ":all".
95
97 The classes provided by this module are broken into two groups: data
98 classes and message classes.
99 Data Classes
101 The following data classes are provided by this library. Each of these
102 provide at least the set of methods below. Note that these classes are
103 designed to create throw-away objects. There is currently no mechanism
104 for changing the value stored within one of these object after the
105 constructor returns. It is assumed that a new object would be created,
106 instead.
107 The common methods to all data classes are:
109 new($value)
111 Constructor. The value passed in is the value to be encapsulated in
112 the new object.
113 value
115 Returns the value kept in the object. Processes recursively for
116 "array" and "struct" objects.
117 as_string
119 Returns the value as a XML-RPC fragment, with the proper tags, etc.
120 serialize($filehandle)
122 Send the stringified rendition of the data to the given file
123 handle. This allows messages with arbitrarily-large base-64 data
124 within them to be sent without having to hold the entire message
125 within process memory.
126 length
128 Returns the length, in bytes, of the object when serialized into
129 XML. This is used by the client and server classes to calculate
130 message length.
131 type
133 Returns the type of data being stored in an object. The type
134 matches the XML-RPC specification, so the normalized form
135 "datetime_iso8601" comes back as "dateTime.iso8601".
136 is_fault
138 All types except the fault class return false for this. This is to
139 allow consistent testing of return values for fault status, without
140 checking for a hash reference with specific keys defined.
141 The classes themselves are:
143 RPC::XML::int
145 Creates an integer value. Constructor expects the integer value as
146 an argument.
147 RPC::XML::i4
149 This is like the "int" class. Note that services written in
150 strictly-typed languages such as C, C++ or Java may consider the
151 "i4" and "int" types as distinct and different.
152 RPC::XML::i8
154 This represents an 8-byte integer, and is not officially supported
155 by the XML-RPC specification. This has been added to accommodate
156 services already in use that have chosen to add this extension.
157 RPC::XML::double
159 Creates a floating-point value.
160 RPC::XML::string
162 Creates an arbitrary string. No special encoding is done to the
163 string (aside from XML document encoding, covered later) with the
164 exception of the "<", ">" and "&" characters, which are XML-escaped
165 during object creation, and then reverted when the "value" method
166 is called.
167 RPC::XML::boolean
169 Creates a boolean value. The value returned will always be either
170 of 1 or 0, for true or false, respectively. When calling the
171 constructor, the program may specify any of: 0, "no", "false", 1,
172 "yes", "true".
173 RPC::XML::datetime_iso8601
175 Creates an instance of the XML-RPC "dateTime.iso8601" type. The
176 specification for ISO 8601 may be found elsewhere. No processing is
177 done to the data. Note that the XML-RPC specification actually got
178 the format of an ISO 8601 date slightly wrong. Because this is what
179 is in the published spec, this package produces dates that match
180 the XML-RPC spec, not the the ISO 8601 spec. However, it will read
181 date-strings in proper ISO 8601 format. See "DATES AND TIMES",
182 below.
183 RPC::XML::nil
185 Creates a "nil" value. The value returned will always be undef. No
186 value should be passed when calling the constructor.
187 Note that nil is an extension to XML-RPC, which is not supported by
189 all implementations. $RPC::XML::ALLOW_NIL must be set to a non-
190 false value before objects of this type can be constructed. See
191 "GLOBAL VARIABLES". However, even if $RPC::XML::ALLOW_NIL is set to
192 a false value, the parsers will recognize the "<nil />" tag and
193 construct an object.
194 In practice, this type is only useful to denote the equivalent of a
196 "void" return value from a function. The type itself is not
197 interchangeable with any of the other data-types.
198 RPC::XML::base64
200 Creates an object that encapsulates a chunk of data that will be
201 treated as base-64 for transport purposes. The value may be passed
202 in as either a string or as a scalar reference. Additionally, a
203 second (optional) parameter may be passed, that if true identifies
204 the data as already base-64 encoded. If so, the data is decoded
205 before storage. The "value" method returns decoded data, and the
206 "as_string" method encodes it before stringification.
207 Alternately, the constructor may be given an open filehandle
209 argument instead of direct data. When this is the case, the data is
210 never read into memory in its entirety, unless the "value" or
211 "as_string" methods are called. This allows the manipulation of
212 arbitrarily-large Base-64-encoded data chunks. In these cases, the
213 flag (optional second argument) is still relevant, but the data is
214 not pre-decoded if it currently exists in an encoded form. It is
215 only decoded as needed. Note that the filehandle passed must be
216 open for reading, at least. It will not be written to, but it will
217 be read from. The position within the file will be preserved
218 between operations.
219 Because of this, this class supports a special method called
221 "to_file", that takes one argument. The argument may be either an
222 open, writable filehandle or a string. If it is a string, "to_file"
223 will attempt to open it as a file and write the decoded data to it.
224 If the argument is a an open filehandle, the data will be written
225 to it without any pre- or post-adjustment of the handle position
226 (nor will it be closed upon completion). This differs from the
227 "serialize" method in that it always writes the decoded data (where
228 the other always writes encoded data), and in that the XML opening
229 and closing tags are not written. The return value of "to_file" is
230 the size of the data written in bytes.
231 RPC::XML::array
233 Creates an array object. The constructor takes zero or more data-
234 type instances as arguments, which are inserted into the array in
235 the order specified. "value" returns an array reference of native
236 Perl types. If a non-null value is passed as an argument to
237 "value()", then the array reference will contain datatype objects
238 (a shallow rather than deep copy).
239 RPC::XML::struct
241 Creates a struct object, the analogy of a hash table in Perl. The
242 keys are ordinary strings, and the values must all be data-type
243 objects. The "value" method returns a hash table reference, with
244 native Perl types in the values. Key order is not preserved. Key
245 strings are now encoded for special XML characters, so the use of
246 such ("<", ">", etc.) should be transparent to the user. If a non-
247 null value is passed as an argument to "value()", then the hash
248 reference will contain the datatype objects rather than native Perl
249 data (a shallow vs. deep copy, as with the array type above).
250 When creating RPC::XML::struct objects, there are two ways to pass
252 the content in for the new object: Either an existing hash
253 reference may be passed, or a series of key/value pairs may be
254 passed. If a reference is passed, the existing data is copied (the
255 reference is not re-blessed), with the values encoded into new
256 objects as needed.
257 RPC::XML::fault
259 A fault object is a special case of the struct object that checks
260 to ensure that there are two keys, "faultCode" and "faultString".
261 As a matter of convenience, since the contents of a RPC::XML::fault
263 structure are specifically defined, the constructor may be called
264 with exactly two arguments, the first of which will be taken as the
265 code, and the second as the string. They will be converted to
266 RPC::XML types automatically and stored by the pre-defined key
267 names.
268 Also as a matter of convenience, the fault class provides the
270 following accessor methods for directly retrieving the integer code
271 and error string from a fault object:
272 code
274 string
275 Both names should be self-explanatory. The values returned are Perl
277 values, not RPC::XML class instances.
278 Message Classes
280 The message classes are used both for constructing messages for
281 outgoing communication as well as representing the parsed contents of a
282 received message. Both implement the following methods:
283 new This is the constructor method for the two message classes. The
285 response class may have only a single value (as a response is
286 currently limited to a single return value), and requests may have
287 as many arguments as appropriate. In both cases, the arguments are
288 passed to the exported "smart_encode" routine described earlier.
289 as_string
291 Returns the message object expressed as an XML document. The
292 document will be lacking in linebreaks and indention, as it is not
293 targeted for human reading.
294 serialize($filehandle)
296 Serialize the message to the given file-handle. This avoids
297 creating the entire XML message within memory, which may be
298 relevant if there is especially-large Base-64 data within the
299 message.
300 length
302 Returns the total size of the message in bytes, used by the client
303 and server classes to set the Content-Length header.
304 The two message-object classes are:
306 RPC::XML::request
308 This creates a request object. A request object expects the first
309 argument to be the name of the remote routine being called, and all
310 remaining arguments are the arguments to that routine. Request
311 objects have the following methods (besides "new" and "as_string"):
312 name
314 The name of the remote routine that the request will call.
315 args
317 Returns a list reference with the arguments that will be
318 passed. No arguments will result in a reference to an empty
319 list.
320 RPC::XML::response
322 The response object is much like the request object in most ways.
323 It may take only one argument, as that is all the specification
324 allows for in a response. Responses have the following methods (in
325 addition to "new" and "as_string"):
326 value
328 The value the response is returning. It will be a RPC::XML
329 data-type.
330 is_fault
332 A boolean test whether or not the response is signalling a
333 fault. This is the same as taking the "value" method return
334 value and testing it, but is provided for clarity and
335 simplicity.
336
338 The XML-RPC specification refers to the date/time values as ISO 8601,
339 but unfortunately got the syntax slightly wrong in the examples.
340 However, since this is the published specification it is necessary to
341 produce time-stamps that conform to this format. The specification
342 implies that the only format for date/time values is:
343 YYYYMMDDThh:mm:ss
345 (Here, the "T" is literal, the rest represent elements of the date and
347 time.) However, the ISO 8601 specification does not allow this
348 particular format, and in generally is considerably more flexible than
349 this. Yet there are implementations of the XML-RPC standard in other
350 languages that rely on a strict interpretation of this format.
351 To accommodate this, the RPC::XML package only produces
353 dateTime.iso8601 values in the format given in the spec, with the
354 possible addition of timezone information if the string used to create
355 a RPC::XML::datetime_iso8601 instance included a timezone offset. The
356 string passed in to the constructor for that class must match:
357 \d\d\d\d-?\d\d-?\d\dT?\d\d:\d\d:\d\d([.,]\d+)?(Z|[-+]\d\d:\d\d)?
359 This pattern is also used by smart_encode to distinguish a date/time
361 string from a regular string. Note that the "T" is optional here, as it
362 is in the ISO 8601 spec. The timezone is optional, and if it is not
363 given then UTC is assumed. The XML-RPC specification says not to assume
364 anything about the timezone in the absence of one, but the format of
365 ISO 8601 declares that that absence of an explicit timezone dictates
366 UTC.
367 If you have DateTime::Format::ISO8601 installed, then
369 RPC::XML::datetime_iso8601 will fall back on it to try and parse any
370 input strings that do not match the above pattern. If the string cannot
371 be parsed by the DateTime::Format::ISO8601 module, then the constructor
372 returns undef and $RPC::XML::ERROR is set.
373
375 All constructors (in all data classes) return "undef" upon failure,
376 with the error message available in the package-global variable
377 $RPC::XML::ERROR.
378
380 The following global variables may be changed to control certain
381 behavior of the library. All variables listed below may be imported
382 into the application namespace when you "use" RPC::XML:
383 $ENCODING
385 This variable controls the character-set encoding reported in
386 outgoing XML messages. It defaults to "us-ascii", but may be set to
387 any value recognized by XML parsers.
388 $FORCE_STRING_ENCODING
390 By default, "smart_encode" uses heuristics to determine what
391 encoding is required for a data type. For example, 123 would be
392 encoded as "int", where 3.14 would be encoded as "double". In some
393 situations it may be handy to turn off all these heuristics, and
394 force encoding of "string" on all data types encountered during
395 encoding. Setting this flag to "true" will do just that.
396 Defaults to "false".
398 $ALLOW_NIL
400 By default, the XML-RPC "nil" extension is not supported. Set this
401 to a non-false value to allow use of nil values. Data objects that
402 are "nil" are represented as undef by Perl. See "The nil Datatype".
403
405 This began as a reference implementation in which clarity of process
406 and readability of the code took precedence over general efficiency. It
407 is now being maintained as production code, but may still have parts
408 that could be written more efficiently.
409
411 Please report any bugs or feature requests to "bug-rpc-xml at
412 rt.cpan.org", or through the web interface at
413 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
414 notified, and then you'll automatically be notified of progress on your
415 bug as I make changes.
416
418 • RT: CPAN's request tracker
419 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
421 • AnnoCPAN: Annotated CPAN documentation
423 <http://annocpan.org/dist/RPC-XML>
425 • CPAN Ratings
427 <http://cpanratings.perl.org/d/RPC-XML>
429 • Search CPAN
431 <http://search.cpan.org/dist/RPC-XML>
433 • MetaCPAN
435 <https://metacpan.org/release/RPC-XML>
437 • Source code on GitHub
439 <http://github.com/rjray/rpc-xml>
441
443 This file and the code within are copyright (c) 2011 by Randy J. Ray.
444 Copying and distribution are permitted under the terms of the Artistic
446 License 2.0
447 (<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
448 GNU LGPL 2.1 (<http://www.opensource.org/licenses/lgpl-2.1.php>).
449
451 The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software,
452 Inc. See <http://www.xmlrpc.com> for more information about the XML-
453 RPC specification.
454
456 RPC::XML::Client, RPC::XML::Server
457
459 Randy J. Ray <rjray@blackperl.com>
460perl v5.32.1 2021-01-27 RPC::XML(3)