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