1RPC::XML::Server(3) User Contributed Perl Documentation RPC::XML::Server(3)
2
6 RPC::XML::Server - A sample server implementation based on RPC::XML
7
9 use RPC::XML::Server;
10 ...
12 $srv = RPC::XML::Server->new(port => 9000);
13 # Several of these, most likely:
14 $srv->add_method(...);
15 ...
16 $srv->server_loop; # Never returns
17
19 This is a sample XML-RPC server built upon the RPC::XML data classes,
20 and using HTTP::Daemon and HTTP::Response for the communication layer.
21
23 Use of the RPC::XML::Server is based on an object model. A server is
24 instantiated from the class, methods (subroutines) are made public by
25 adding them through the object interface, and then the server object is
26 responsible for dispatching requests (and possibly for the HTTP
27 listening, as well).
28 Static Methods
30 These methods are static to the package, and are used to provide
31 external access to internal settings:
32 INSTALL_DIR
34 Returns the directory that this module is installed into. This is
35 used by methods such as "add_default_methods" to locate the XPL
36 files that are shipped with the distribution.
37 version
39 Returns the version string associated with this package.
40 product_tokens
42 This returns the identifying string for the server, in the format
43 "NAME/VERSION" consistent with other applications such as Apache
44 and LWP. It is provided here as part of the compatibility with
45 HTTP::Daemon that is required for effective integration with
46 Net::Server.
47 Methods
49 The following are object (non-static) methods. Unless otherwise
50 explicitly noted, all methods return the invoking object reference upon
51 success, and a non-reference error string upon failure.
52 See "Content Compression" below for details of how the server class
54 manages gzip-based compression and expansion of messages.
55 new(OPTIONS)
57 Creates a new object of the class and returns the blessed
58 reference. Depending on the options, the object will contain some
59 combination of an HTTP listener, a pre-populated HTTP::Response
60 object, a RPC::XML::ParserFactory-generated object, and a dispatch
61 table with the set of default methods pre-loaded. The options that
62 new accepts are passed as a hash of key/value pairs (not a hash
63 reference). The accepted options are:
64 no_http
66 If passed with a "true" value, prevents the creation and
67 storage of the HTTP::Daemon object. This allows for deployment
68 of a server object in other environments. Note that if this is
69 set, the server_loop method described below will silently
70 attempt to use the Net::Server module.
71 no_default
73 If passed with a "true" value, prevents the loading of the
74 default methods provided with the RPC::XML distribution. These
75 may be later loaded using the add_default_methods interface
76 described later. The methods themselves are described below
77 (see "The Default Methods Provided").
78 path
80 host
81 port
82 queue
83 These four are specific to the HTTP-based nature of the server.
84 The path argument sets the additional URI path information that
85 clients would use to contact the server. Internally, it is not
86 used except in outgoing status and introspection reports. The
87 host, port and queue arguments are passed to the HTTP::Daemon
88 constructor if they are passed. They set the hostname, TCP/IP
89 port, and socket listening queue, respectively. They may also
90 be used if the server object tries to use Net::Server as an
91 alternative server core.
92 xpl_path
94 If you plan to add methods to the server object by passing
95 filenames to the "add_method" call, this argument may be used
96 to specify one or more additional directories to be searched
97 when the passed-in filename is a relative path. The value for
98 this must be an array reference. See also add_method and
99 xpl_path, below.
100 timeout
102 Specify a value (in seconds) for the HTTP::Daemon server to use
103 as a timeout value when reading request data from an inbound
104 connection. The default value is 10 seconds. This value is not
105 used except by HTTP::Daemon.
106 auto_methods
108 If specified and set to a true value, enables the automatic
109 searching for a requested remote method that is unknown to the
110 server object handling the request. If set to "no" (or not set
111 at all), then a request for an unknown function causes the
112 object instance to report an error. If the routine is still not
113 found, the error is reported. Enabling this is a security risk,
114 and should only be permitted by a server administrator with
115 fully informed acknowledgement and consent.
116 auto_updates
118 If specified and set to a "true" value, enables the checking of
119 the modification time of the file from which a method was
120 originally loaded. If the file has changed, the method is re-
121 loaded before execution is handed off. As with the auto-loading
122 of methods, this represents a security risk, and should only be
123 permitted by a server administrator with fully informed
124 acknowledgement and consent.
125 parser
127 If this parameter is passed, its value is expected to be an
128 array reference. The contents of that array are passed to the
129 new method of the RPC::XML::ParserFactory class, which creates
130 the parser object that the server object caches for its use.
131 See the RPC::XML::ParserFactory manual page for a list of
132 recognized parameters to the constructor.
133 message_file_thresh
135 If this key is passed, the value associated with it is assumed
136 to be a numerical limit to the size of in-memory messages. Any
137 out-bound request that would be larger than this when
138 stringified is instead written to an anonynous temporary file,
139 and spooled from there instead. This is useful for cases in
140 which the request includes RPC::XML::base64 objects that are
141 themselves spooled from file-handles. This test is independent
142 of compression, so even if compression of a request would drop
143 it below this threshhold, it will be spooled anyway. The file
144 itself is created via File::Temp with UNLINK=>1, so once it is
145 freed the disk space is immediately freed.
146 message_temp_dir
148 If a message is to be spooled to a temporary file, this key can
149 define a specific directory in which to open those files. If
150 this is not given, then the "tmpdir" method from the File::Spec
151 package is used, instead.
152 fault_code_base
154 Specify a base integer value that is added to the numerical
155 codes for all faults the server can return. See "Server Faults"
156 for the list of faults that are built-in to the server class.
157 This allows an application to "move" the RPC::XML::Server pre-
158 defined fault codes out of the way of codes that the
159 application itself may generate.
160 Note that this value is not applied to any faults specified via
162 the next option, "fault_table". It is assumed that the
163 developer has already applied any offset to those codes.
164 fault_table
166 Specify one or more fault types to either add to or override
167 the built-in set of faults for the server object. The value of
168 this parameter is a hash reference whose keys are the fault
169 type and whose values are either a scalar (which is taken to be
170 the numerical code) or a list reference with two elements (the
171 code followed by the string). See "Server Faults" for the list
172 of faults that are built-in to the server class, and for more
173 information on defining your own.
174 Any other keys in the options hash not explicitly used by the
176 constructor are copied over verbatim onto the object, for the
177 benefit of sub-classing this class. All internal keys are prefixed
178 with "__" to avoid confusion. Feel free to use this prefix only if
179 you wish to re-introduce confusion.
180 url This returns the HTTP URL that the server will be responding to,
182 when it is in the connection-accept loop. If the server object was
183 created without a built-in HTTP listener, then this method returns
184 "undef".
185 requests
187 Returns the number of requests this server object has marshalled.
188 Note that in multi-process environments (such as Apache or
189 Net::Server::PreFork) the value returned will only reflect the
190 messages dispatched by the specific process itself.
191 response
193 Each instance of this class (and any subclasses that do not
194 completely override the "new" method) creates and stores an
195 instance of HTTP::Response, which is then used by the HTTP::Daemon
196 or Net::Server processing loops in constructing the response to
197 clients. The response object has all common headers pre-set for
198 efficiency. This method returns a reference to that object.
199 started([BOOL])
201 Gets and possibly sets the clock-time when the server starts
202 accepting connections. If a value is passed that evaluates to true,
203 then the current clock time is marked as the starting time. In
204 either case, the current value is returned. The clock-time is based
205 on the internal time command of Perl, and thus is represented as an
206 integer number of seconds since the system epoch. Generally, it is
207 suitable for passing to either localtime or to the "time2iso8601"
208 routine exported by the RPC::XML package.
209 timeout(INT)
211 You can call this method to set the timeout of new connections
212 after they are received. This function returns the old timeout
213 value. If you pass in no value then it will return the old value
214 without modifying the current value. The default value is 10
215 seconds.
216 server_fault(STRING, STRING)
218 Create a RPC::XML::fault object of the specified type, optionally
219 including the second (string) parameter. See "Server Faults" for
220 the list of faults defined by RPC::XML::Server (as well as
221 documentation on creating your own).
222 add_method(FILE | HASHREF | OBJECT)
224 add_proc(FILE | HASHREF | OBJECT)
225 This adds a new published method or procedure to the server object
226 that invokes it. The new method may be specified in one of three
227 ways: as a filename, a hash reference or an existing object
228 (generally of either RPC::XML::Procedure or RPC::XML::Method
229 classes).
230 If passed as a hash reference, the following keys are expected:
232 name
234 The published (externally-visible) name for the method.
235 version
237 An optional version stamp. Not used internally, kept mainly for
238 informative purposes.
239 hidden
241 If passed and evaluates to a "true" value, then the method
242 should be hidden from any introspection API implementations.
243 This parameter is optional, the default behavior being to make
244 the method publically-visible.
245 code
247 A code reference to the actual Perl subroutine that handles
248 this method. A symbolic reference is not accepted. The value
249 can be passed either as a reference to an existing routine, or
250 possibly as a closure. See "How Methods are Called" for the
251 semantics the referenced subroutine must follow.
252 signature
254 A list reference of the signatures by which this routine may be
255 invoked. Every method has at least one signature. Though less
256 efficient for cases of exactly one signature, a list reference
257 is always used for sake of consistency.
258 help
260 Optional documentation text for the method. This is the text
261 that would be returned, for example, by a system.methodHelp
262 call (providing the server has such an externally-visible
263 method).
264 If a file is passed, then it is expected to be in the XML-based
266 format, described in the RPC::XML::Procedure manual (see
267 RPC::XML::Procedure). If the name passed is not an absolute
268 pathname, then the file will be searched for in any directories
269 specified when the object was instantiated, then in the directory
270 into which this module was installed, and finally in the current
271 working directory. If the operation fails, the return value will be
272 a non-reference, an error message. Otherwise, the return value is
273 the object reference.
274 The add_method and add_proc calls are essentialy identical unless
276 called with hash references. Both files and objects contain the
277 information that defines the type (method vs. procedure) of the
278 funtionality to be added to the server. If add_method is called
279 with a file that describes a procedure, the resulting addition to
280 the server object will be a RPC::XML::Procedure object, not a
281 method object.
282 For more on the creation and manipulation of procedures and methods
284 as objects, see RPC::XML::Procedure.
285 delete_method(NAME)
287 delete_proc(NAME)
288 Delete the named method or procedure from the calling object.
289 Removes the entry from the internal table that the object
290 maintains. If the method is shared across more than one server
291 object (see "share_methods"), then the underlying object for it
292 will only be destroyed when the last server object releases it. On
293 error (such as no method by that name known), an error string is
294 returned.
295 The delete_proc call is identical, supplied for the sake of
297 symmetry. Both calls return the matched object regardless of its
298 underlying type.
299 list_methods
301 list_procs
302 This returns a list of the names of methods and procedures the
303 server current has published. Note that the returned values are
304 not the method objects, but rather the names by which they are
305 externally known. The "hidden" status of a method is not consulted
306 when this list is created; all methods and procedures known are
307 listed. The list is not sorted in any specific order.
308 The list_procs call is provided for symmetry. Both calls list all
310 published routines on the calling server object, regardless of
311 underlying type.
312 xpl_path([LISTREF])
314 Get and/or set the object-specific search path for "*.xpl" files
315 (files that specify methods) that are specified in calls to
316 add_method, above. If a list reference is passed, it is installed
317 as the new path (each element of the list being one directory name
318 to search). Regardless of argument, the current path is returned as
319 a list reference. When a file is passed to add_method, the elements
320 of this path are searched first, in order, before the installation
321 directory or the current working directory are searched.
322 get_method(NAME)
324 get_proc(NAME)
325 Returns a reference to an object of the class RPC::XML::Method or
326 RPC::XML::Procedure, which is the current binding for the published
327 method NAME. If there is no such method known to the server, then
328 "undef" is returned. The object is implemented as a hash, and has
329 the same key and value pairs as for "add_method", above. Thus, the
330 reference returned is suitable for passing back to "add_method".
331 This facilitates temporary changes in what a published name maps
332 to. Note that this is a referent to the object as stored on the
333 server object itself, and thus changes to it could affect the
334 behavior of the server.
335 The get_proc interface is provided for symmetry.
337 server_loop(HASH)
339 Enters the connection-accept loop, which generally does not return.
340 This is the "accept()"-based loop of HTTP::Daemon if the object was
341 created with an instance of that class as a part. Otherwise, this
342 enters the run-loop of the Net::Server class. It listens for
343 requests, and marshalls them out via the "dispatch" method
344 described below. It answers HTTP-HEAD requests immediately (without
345 counting them on the server statistics) and efficiently by using a
346 cached HTTP::Response object.
347 Because infinite loops requiring a "HUP" or "KILL" signal to
349 terminate are generally in poor taste, the HTTP::Daemon side of
350 this sets up a localized signal handler which causes an exit when
351 triggered. By default, this is attached to the "INT" signal. If the
352 Net::Server module is being used instead, it provides its own
353 signal management.
354 The arguments, if passed, are interpreted as a hash of key/value
356 options (not a hash reference, please note). For HTTP::Daemon, only
357 one is recognized:
358 signal
360 If passed, should be the traditional name for the signal that
361 should be bound to the exit function. If desired, a reference
362 to an array of signal names may be passed, in which case all
363 signals will be given the same handler. The user is responsible
364 for not passing the name of a non-existent signal, or one that
365 cannot be caught. If the value of this argument is 0 (a "false"
366 value) or the string "NONE", then the signal handler will not
367 be installed, and the loop may only be broken out of by killing
368 the running process (unless other arrangements are made within
369 the application).
370 The options that Net::Server responds to are detailed in the manual
372 pages for that package. All options passed to "server_loop" in this
373 situation are passed unaltered to the "run()" method in
374 Net::Server.
375 dispatch(REQUEST)
377 This is the server method that actually manages the marshalling of
378 an incoming request into an invocation of a Perl subroutine. The
379 parameter passed in may be one of: a scalar containing the full XML
380 text of the request, a scalar reference to such a string, or a pre-
381 constructed RPC::XML::request object. Unless an object is passed,
382 the text is parsed with any errors triggering an early exit. Once
383 the object representation of the request is on hand, the parameter
384 data is extracted, as is the method name itself. The call is sent
385 along to the appropriate subroutine, and the results are collated
386 into an object of the RPC::XML::response class, which is returned.
387 Any non-reference return value should be presumed to be an error
388 string.
389 The dispatched method may communicate error in several ways.
391 First, any non-reference return value is presumed to be an error
392 string, and is encoded and returned as an RPC::XML::fault response.
393 The method is run under an "eval()", so errors conveyed by $@ are
394 similarly encoded and returned. As a special case, a method may
395 explicitly "die()" with a fault response, which is passed on
396 unmodified.
397 add_default_methods([DETAILS])
399 This method adds all the default methods (those that are shipped
400 with this extension) to the calling server object. The files are
401 denoted by their "*.xpl" extension, and are installed into the same
402 directory as this Server.pm file. The set of default methods are
403 described below (see "The Default Methods Provided").
404 If any names are passed as a list of arguments to this call, then
406 only those methods specified are actually loaded. If the "*.xpl"
407 extension is absent on any of these names, then it is silently
408 added for testing purposes. Note that the methods shipped with this
409 package have file names without the leading "status." part of the
410 method name. If the very first element of the list of arguments is
411 "except" (or "-except"), then the rest of the list is treated as a
412 set of names to not load, while all others do get read. The
413 Apache::RPC::Server module uses this to prevent the loading of the
414 default "system.status" method while still loading all the rest of
415 the defaults. (It then provides a more Apache-centric status
416 method.)
417 Note that there is no symmetric call in this case. The provided API
419 is implemented as methods, and thus only this interface is
420 provided.
421 add_methods_in_dir(DIR [, DETAILS])
423 add_procs_in_dir(DIR [, DETAILS])
424 This is exactly like add_default_methods above, save that the
425 caller specifies which directory to scan for "*.xpl" files. In
426 fact, the add_default_methods routine simply calls this routine
427 with the installation directory as the first argument. The
428 definition of the additional arguments is the same as above.
429 add_procs_in_dir is provided for symmetry.
431 share_methods(SERVER, NAMES)
433 share_procs(SERVER, NAMES)
434 The calling server object shares the methods and/or procedures
435 listed in NAMES with the source-server passed as the first object.
436 The source must derive from this package in order for this
437 operation to be permitted. At least one method must be specified,
438 and all are specified by name (not by object refernce). Both
439 objects will reference the same exact RPC::XML::Procedure (or
440 Method, or derivative thereof) object in this case, meaning that
441 call-statistics and the like will reflect the combined data. If one
442 or more of the passed names are not present on the source server,
443 an error message is returned and none are copied to the calling
444 object.
445 Alternately, one or more of the name parameters passed to this call
447 may be regular-expression objects (the result of the qr operator).
448 Any of these detected are applied against the list of all available
449 methods known to the source server. All matching ones are inserted
450 into the list (the list is pared for redundancies in any case).
451 This allows for easier addition of whole classes such as those in
452 the "system.*" name space (via "qr/^system\./"), for example. There
453 is no substring matching provided. Names listed in the parameters
454 to this routine must be either complete strings or regular
455 expressions.
456 The share_procs interface is provided for symmetry.
458 copy_methods(SERVER, NAMES)
460 copy_procs(SERVER, NAMES)
461 This behaves like the method share_methods above, with the
462 exception that the calling object is given a clone of each method,
463 rather than referencing the same exact method as the source server.
464 The code reference part of the method is shared between the two,
465 but all other data are copied (including a fresh copy of any list
466 references used) into a completely new RPC::XML::Procedure (or
467 derivative) object, using the "clone()" method from that class.
468 Thus, while the calling object has the same methods available, and
469 is re-using existing code in the Perl runtime, the method objects
470 (and hence the statistics and such) are kept separate. As with the
471 above, an error is flagged if one or more are not found.
472 This routine also accepts regular-expression objects with the same
474 behavior and limitations. Again, copy_procs is simply provided for
475 symmetry.
476 Specifying Server-Side Remote Methods
478 Specifying the methods themselves can be a tricky undertaking. Some
479 packages (in other languages) delegate a specific class to handling
480 incoming requests. This works well, but it can lead to routines not
481 intended for public availability to in fact be available. There are
482 also issues around the access that the methods would then have to other
483 resources within the same running system.
484 The approach taken by RPC::XML::Server (and the Apache::RPC::Server
486 subclass of it) require that methods be explicitly published in one of
487 the several ways provided. Methods may be added directly within code by
488 using "add_method" as described above, with full data provided for the
489 code reference, signature list, etc. The "add_method" technique can
490 also be used with a file that conforms to a specific XML-based format
491 (detailed in the manual page for the RPC::XML::Procedure class, see
492 RPC::XML::Procedure). Entire directories of files may be added using
493 "add_methods_in_dir", which merely reads the given directory for files
494 that appear to be method definitions.
495 How Methods Are Called
497 When a routine is called via the server dispatcher, it is called with
498 the arguments that the client request passed. Depending on whether the
499 routine is considered a "procedure" or a "method", there may be an
500 extra argument at the head of the list. The extra argument is present
501 when the routine being dispatched is part of a RPC::XML::Method object.
502 The extra argument is a reference to a RPC::XML::Server object (or a
503 subclass thereof). This is derived from a hash reference, and will
504 include these special keys:
505 method_name
507 This is the name by which the method was called in the client. Most
508 of the time, this will probably be consistent for all calls to the
509 server-side method. But it does not have to be, hence the passing
510 of the value.
511 signature
513 This is the signature that was used, when dispatching. Perl has a
514 liberal view of lists and scalars, so it is not always clear what
515 arguments the client specifically has in mind when calling the
516 method. The signature is an array reference containing one or more
517 datatypes, each a simple string. The first of the datatypes
518 specifies the expected return type. The remainder (if any) refer to
519 the arguments themselves.
520 peeraddr
522 This is the address part of a packed SOCKADDR_IN structure, as
523 returned by "pack_sockaddr_in" in Socket, which contains the
524 address of the client that has connected and made the current
525 request. This is provided "raw" in case you need it. While you
526 could re-create it from "peerhost", it is readily available in both
527 this server environment and the Apache::RPC::Server environment and
528 thus included for convenience.
529 peerhost
531 This is the address of the remote (client) end of the socket, in
532 "x.x.x.x" (dotted-quad) format. If you wish to look up the clients
533 host-name, you can use this to do so or utilize the encoded
534 structure above directly.
535 peerport
537 Lastly, this is the port of the remote (client) end of the socket,
538 taken from the SOCKADDR_IN structure.
539 Those keys should only be referenced within method code itself, as they
541 are not set on the server object outside of that context.
542 Note that by passing the server object reference first, method-classed
544 routines are essentially expected to behave as actual methods of the
545 server class, as opposed to ordinary functions. Of course, they can
546 also discard the initial argument completely.
547 The routines should not make (excessive) use of global variables, for
549 obvious reasons. When the routines are loaded from XPL files, the code
550 is created as a closure that forces execution in the
551 RPC::XML::Procedure package. If the code element of a procedure/method
552 is passed in as a direct code reference by one of the other syntaxes
553 allowed by the constructor, the package may well be different. Thus,
554 routines should strive to be as localized as possible, independant of
555 specific namespaces. If a group of routines are expected to work in
556 close concert, each should explicitly set the namespace with a
557 "package" declaration as the first statement within the routines
558 themselves.
559 The Default Methods Provided
561 The following methods are provided with this package, and are the ones
562 installed on newly-created server objects unless told not to. These are
563 identified by their published names, as they are compiled internally as
564 anonymous subroutines and thus cannot be called directly:
565 system.identity
567 Returns a string value identifying the server name, version, and
568 possibly a capability level. Takes no arguments.
569 system.introspection
571 Returns a series of struct objects that give overview documentation
572 of one or more of the published methods. It may be called with a
573 string identifying a single routine, in which case the return value
574 is a struct. It may be called with an array of string values, in
575 which case an array of struct values, one per element in, is
576 returned. Lastly, it may be called with no input parameters, in
577 which case all published routines are documented. Note that
578 routines may be configured to be hidden from such introspection
579 queries.
580 system.listMethods
582 Returns a list of the published methods or a subset of them as an
583 array of string values. If called with no parameters, returns all
584 (non-hidden) method names. If called with a single string pattern,
585 returns only those names that contain the string as a substring of
586 their name (case-sensitive, and this is not a regular expression
587 evaluation).
588 system.methodHelp
590 Takes either a single method name as a string, or a series of them
591 as an array of string. The return value is the help text for the
592 method, as either a string or array of string value. If the
593 method(s) have no help text, the string will be null.
594 system.methodSignature
596 As above, but returns the signatures that the method accepts, as
597 array of string representations. If only one method is requests via
598 a string parameter, then the return value is the corresponding
599 array. If the parameter in is an array, then the returned value
600 will be an array of array of string.
601 system.multicall
603 This is a simple implementation of composite function calls in a
604 single request. It takes an array of struct values. Each struct has
605 at least a "methodName" member, which provides the name of the
606 method to call. If there is also a "params" member, it refers to an
607 array of the parameters that should be passed to the call.
608 system.status
610 Takes no arguments and returns a struct containing a number of
611 system status values including (but not limited to) the current
612 time on the server, the time the server was started (both of these
613 are returned in both ISO 8601 and UNIX-style integer formats),
614 number of requests dispatched, and some identifying information
615 (hostname, port, etc.).
616 In addition, each of these has an accompanying help file in the
618 "methods" sub-directory of the distribution.
619 These methods are installed as "*.xpl" files, which are generated from
621 files in the "methods" directory of the distribution using the
622 make_method tool (see make_method). The files there provide the Perl
623 code that implements these, their help files and other information.
624 Content Compression
626 The RPC::XML::Server class now supports compressed messages, both
627 incoming and outgoing. If a client indicates that it can understand
628 compressed content, the server will use the Compress::Zlib (available
629 from CPAN) module, if available, to compress any outgoing messages
630 above a certain threshhold in size (the default threshhold is set to
631 4096 bytes). The following methods are all related to the compression
632 support within the server class:
633 compress
635 Returns a false value if compression is not available to the server
636 object. This is based on the availability of the Compress::Zlib
637 module at start-up time, and cannot be changed.
638 compress_thresh([MIN_LIMIT])
640 Return or set the compression threshhold value. Messages smaller
641 than this size in bytes will not be compressed, even when
642 compression is available, to save on CPU resources. If a value is
643 passed, it becomes the new limit and the old value is returned.
644 Spooling Large Messages
646 If the server anticipates handling large out-bound messages (for
647 example, if the hosted code returns large Base64 values pre-encoded
648 from file handles), the "message_file_thresh" and "message_temp_dir"
649 settings may be used in a manner similar to RPC::XML::Client.
650 Specifically, the threshhold is used to determine when a message should
651 be spooled to a filehandle rather than made into an in-memory string
652 (the RPC::XML::base64 type can use a filehandle, thus eliminating the
653 need for the data to ever be completely in memory). An anonymous
654 temporary file is used for these operations.
655 Note that the message size is checked before compression is applied,
657 since the size of the compressed output cannot be known until the full
658 message is examined. It is possible that a message will be spooled even
659 if its compressed size is below the threshhold, if the uncompressed
660 size exceeds the threshhold.
661 message_file_thresh
663 message_temp_dir
664 These methods may be used to retrieve or alter the values of the
665 given keys as defined earlier for the "new" method.
666 Server Faults
668 Previous versions of this library had a very loosely-organized set of
669 fault codes that a server might return in certain (non-fatal) error
670 circumstances. This has been replaced by a more configurable,
671 adjustable system to allow users to better integrate the server-defined
672 faults with any that their application may produce. It also allows for
673 the definition of additional fault types so that the same mechanism for
674 formatting the pre-defined faults can be used within sub-classes and
675 user applications.
676 The server method server_fault is used to generate RPC::XML::fault
678 objects for these situations. It takes one or two arguments, the first
679 being the name of the type of fault to create and the second being the
680 specific message. If a fault is defined with a static message, the
681 second argument may be skipped (and will be ignored if passed).
682 In addition to defining their own faults, a user may override the
684 definition of any of the server's pre-defined faults.
685 Defining faults
687 The user may define their own faults using the "fault_table" argument
689 to the constructor of the server class being instantiated. They may
690 also override any of the pre-defined faults (detailed in the next
691 section) by providing a new definition for the name.
692 The value of the "fault_table" argument is a hash reference whose keys
694 are the names of the faults and whose values are one of two types:
695 An integer
697 If the value for the key is a scalar, it is assumed to be an
698 integer and will be used as the fault code. When the fault is
699 created, the message argument (the second parameter) will be used
700 verbatim as the fault message.
701 A 2-element list reference
703 If the value is a list reference, it is assumed to have two
704 elements: the first is the integer fault code to use, and the
705 second is a message "template" string to use as the fault message.
706 If the string contains the sequence %s, this will be replaced with
707 the message argument (the second parameter) passed to server_fault.
708 If that sequence is not in the string, then the fault message is
709 considered static and the message argument is ignored.
710 An example of defining faults:
712 my $server = RPC::XML::Server->new(
714 ...
715 fault_table => {
716 limitexceeded => [ 500 => 'Call limit exceeded' ],
717 accessdenied => [ 600 => 'Access denied: %s' ],
718 serviceclosed => 700
719 },
720 ...
721 );
722 In this example, the fault-type "limitexceeded" is defined as having a
724 fault code of 500 and a static message of "Call limit exceeded". The
725 next fault defined is "accessdenied", which has a code of 600 and
726 message that starts with "Access denied:" and incorporates whatever
727 message was passed in to the fault creation. The last example defines a
728 fault called "serviceclosed" that has a code of 700 and uses any
729 passed-in message unaltered.
730 Server-defined faults
732 The RPC::XML::Server class defines the following faults and uses them
734 internally. You can override the codes and messages for these by
735 including them in the table passed as a "fault_table" argument. The
736 faults fall into three groups:
737 Request Initialization
739 Faults in this group stem from the initialization of the request
740 and the parsing of the XML. The codes for this group fall in the
741 range 100-199.
742 Method Resolution
744 This group covers problems with mapping the request to a known
745 method or function on the server. These codes will be in the range
746 200-299.
747 Execution
749 Lastly, these faults are for problems in actually executing the
750 requested code. Their codes are in the range 300-399.
751 The faults, and the phases they apply to, are:
753 badxml (Request Initialization)
755 This fault is sent back to the client when the XML of the request
756 did not parse as a valid XML-RPC request.
757 The code is 100, and the message is of the form, "XML parse error:
759 %s". The specific error from the XML parser is included in the
760 message.
761 badmethod (Method Resolution)
763 This fault is sent when the requested method is unknown to the
764 server. No method has been configured on the server by that name.
765 The code is 200, and the message is of the form, "Method lookup
767 error: %s". The name of the method and other information is
768 included in the message.
769 badsignature (Method Resolution)
771 If a method is known on the server, but there is no signature that
772 matches the sequence of arguments passed, this fault is returned.
773 This fault cannot be triggered by server-side code configured via
774 RPC::XML::Function, as no signature-checking is done for those.
775 The code is 201, and the message is of the form, "Method signature
777 error: %s". The name of the method and the signature of the
778 arguments is included in the message.
779 execerror (Execution)
781 This fault relates back to the client any exception thrown by the
782 remote code during execution. If the invoked code returned their
783 error in the form of a RPC::XML::fault object, that fault is
784 returned instead. Otherwise, the value of $@ is used in the message
785 of the fault that gets generated.
786 The code is 300, and the message is of the form, "Code execution
788 error: %s". The actual text of the exception thrown is included in
789 the message.
790 There is one special server-fault whose code and message cannot be
792 overridden. If a call is made to server_fault for an unknown type of
793 fault, the returned object will have a code of "-1" and a message
794 stating that the fault-type is unknown. The message will include both
795 the requested type-name and any message (if any) that was passed in.
796 Adjusting the server-defined codes
798 If you just want to "move" the range of codes that the server uses out
800 of the way of your application's own faults, this can be done with the
801 "fault_code_base" parameter when constructing the server object. The
802 value of the parameter must be an integer, and it is added to the value
803 of all existing fault codes. For example, a value of 10000 would make
804 the code for the "badxml" fault be 10100, the code for "badmethod" be
805 10200, etc.
806 This is applied before any user-defined faults are merged in, so their
808 code values will not be affected by this value.
809
811 Unless explicitly stated otherwise, all methods return some type of
812 reference on success, or an error string on failure. Non-reference
813 return values should always be interpreted as errors unless otherwise
814 noted.
815
817 Please report any bugs or feature requests to "bug-rpc-xml at
818 rt.cpan.org", or through the web interface at
819 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML
820 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
821 notified, and then you'll automatically be notified of progress on your
822 bug as I make changes.
823
825 · RT: CPAN's request tracker
826 http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML
828 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
829 · AnnoCPAN: Annotated CPAN documentation
831 http://annocpan.org/dist/RPC-XML <http://annocpan.org/dist/RPC-XML>
833 · CPAN Ratings
835 http://cpanratings.perl.org/d/RPC-XML
837 <http://cpanratings.perl.org/d/RPC-XML>
838 · Search CPAN
840 http://search.cpan.org/dist/RPC-XML
842 <http://search.cpan.org/dist/RPC-XML>
843 · Source code on GitHub
845 http://github.com/rjray/rpc-xml/tree/master
847 <http://github.com/rjray/rpc-xml/tree/master>
848
850 This file and the code within are copyright (c) 2009 by Randy J. Ray.
851 Copying and distribution are permitted under the terms of the Artistic
853 License 2.0
854 (http://www.opensource.org/licenses/artistic-license-2.0.php
855 <http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
856 GNU LGPL 2.1 (http://www.opensource.org/licenses/lgpl-2.1.php
857 <http://www.opensource.org/licenses/lgpl-2.1.php>).
858
860 The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software,
861 Inc. See <http://www.xmlrpc.com> for more information about the XML-
862 RPC specification.
863
865 RPC::XML, RPC::XML::Client, RPC::XML::ParserFactory
866
868 Randy J. Ray "<rjray@blackperl.com>"
869perl v5.12.0 2009-09-03 RPC::XML::Server(3)