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 threshhold, 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
380 Net::Server.
381 dispatch(REQUEST)
383 This is the server method that actually manages the marshalling of
384 an incoming request into an invocation of a Perl subroutine. The
385 parameter passed in may be one of: a scalar containing the full XML
386 text of the request, a scalar reference to such a string, or a pre-
387 constructed RPC::XML::request object. Unless an object is passed,
388 the text is parsed with any errors triggering an early exit. Once
389 the object representation of the request is on hand, the parameter
390 data is extracted, as is the method name itself. The call is sent
391 along to the appropriate subroutine, and the results are collated
392 into an object of the RPC::XML::response class, which is returned.
393 Any non-reference return value should be presumed to be an error
394 string.
395 The dispatched method may communicate error in several ways.
397 First, any non-reference return value is presumed to be an error
398 string, and is encoded and returned as an RPC::XML::fault response.
399 The method is run under an "eval()", so errors conveyed by $@ are
400 similarly encoded and returned. As a special case, a method may
401 explicitly "die()" with a fault response, which is passed on
402 unmodified.
403 add_default_methods([DETAILS])
405 This method adds all the default methods (those that are shipped
406 with this extension) to the calling server object. The files are
407 denoted by their "*.xpl" extension, and are installed into the same
408 directory as this Server.pm file. The set of default methods are
409 described below (see "The Default Methods Provided").
410 If any names are passed as a list of arguments to this call, then
412 only those methods specified are actually loaded. If the "*.xpl"
413 extension is absent on any of these names, then it is silently
414 added for testing purposes. Note that the methods shipped with this
415 package have file names without the leading "status." part of the
416 method name. If the very first element of the list of arguments is
417 "except" (or "-except"), then the rest of the list is treated as a
418 set of names to not load, while all others do get read. The
419 Apache::RPC::Server module uses this to prevent the loading of the
420 default "system.status" method while still loading all the rest of
421 the defaults. (It then provides a more Apache-centric status
422 method.)
423 Note that there are no symmetric calls in this case. The provided
425 API is implemented as methods, and thus only this interface is
426 provided.
427 add_methods_in_dir(DIR [, DETAILS])
429 add_procedures_in_dir(DIR [, DETAILS])
430 add_functions_in_dir(DIR [, DETAILS])
431 This is exactly like add_default_methods above, save that the
432 caller specifies which directory to scan for "*.xpl" files. In
433 fact, the add_default_methods routine simply calls this routine
434 with the installation directory as the first argument. The
435 definition of the additional arguments is the same as above.
436 add_procedures_in_dir and add_functions_in_dir are provided for
438 symmetry.
439 share_methods(SERVER, NAMES)
441 share_procedures(SERVER, NAMES)
442 share_functions(SERVER, NAMES)
443 The calling server object shares the methods/procedures/functions
444 listed in NAMES with the source-server passed as the first object.
445 The source must derive from this package in order for this
446 operation to be permitted. At least one method must be specified,
447 and all are specified by name (not by object refernce). Both
448 objects will reference the same exact RPC::XML::Procedure (or
449 derivative thereof) object in this case, meaning that call-
450 statistics and the like will reflect the combined data. If one or
451 more of the passed names are not present on the source server, an
452 error message is returned and none are copied to the calling
453 object.
454 Alternately, one or more of the name parameters passed to this call
456 may be regular-expression objects (the result of the qr operator).
457 Any of these detected are applied against the list of all available
458 methods known to the source server. All matching ones are inserted
459 into the list (the list is pared for redundancies in any case).
460 This allows for easier addition of whole classes such as those in
461 the "system.*" name space (via "qr/^system[.]/"), for example.
462 There is no substring matching provided. Names listed in the
463 parameters to this routine must be either complete strings or
464 regular expressions.
465 The share_procedures and share_functions calls are provided for
467 symmetry.
468 copy_methods(SERVER, NAMES)
470 copy_procedures(SERVER, NAMES)
471 copy_functions(SERVER, NAMES)
472 These behave like the methods share_* above, with the exception
473 that the calling object is given a clone of each method, rather
474 than referencing the same exact method as the source server. The
475 code reference part of the method is shared between the two, but
476 all other data are copied (including a fresh copy of any list
477 references used) into a completely new RPC::XML::Procedure (or
478 derivative) object, using the "clone()" method from that class.
479 Thus, while the calling object has the same methods available, and
480 is re-using existing code in the Perl runtime, the method objects
481 (and hence the statistics and such) are kept separate. As with the
482 above, an error is flagged if one or more are not found.
483 This routine also accepts regular-expression objects with the same
485 behavior and limitations. Again, copy_procedures and copy_functions
486 are provided for symmetry.
487 Specifying Server-Side Remote Procedures
489 Specifying the methods themselves can be a tricky undertaking. Some
490 packages (in other languages) delegate a specific class to handling
491 incoming requests. This works well, but it can lead to routines not
492 intended for public availability to in fact be available. There are
493 also issues around the access that the methods would then have to other
494 resources within the same running system.
495 The approach taken by RPC::XML::Server (and the Apache::RPC::Server
497 subclass of it) require that remote procedures be explicitly published
498 in one of the several ways provided. Procedures may be added directly
499 within code by using add_procedure/add_method/add_function as described
500 above, with full data provided for the code reference, signature list,
501 etc. The add_* technique can also be used with a file that conforms to
502 a specific XML-based format (detailed in the manual page for the
503 RPC::XML::Procedure class, see RPC::XML::Procedure). Entire
504 directories of files may be added using add_methods_in_dir, which
505 merely reads the given directory for files that appear to be method
506 definitions.
507 The Three Types of Procedures
509 There are three types of procedures that RPC::XML::Server marshalls
510 calls to. All are provided by the RPC::XML::Procedure module. You
511 should not need to load or reference this module directly, as loading
512 RPC::XML::Server (or a derivative) makes it available. The three types
513 are:
514 Methods (RPC::XML::Method)
516 Code that is considered a "method" by the server is called as
517 though it were, in fact, a method in that class. The first argument
518 in the list is the server object itself, with the arguments to the
519 call making up the rest of the list. The server checks the
520 signature of the method against the arguments list before the call
521 is made. See below ("How Procedures Are Called") for more on the
522 invocation of code as methods.
523 Procedures (RPC::XML::Procedure)
525 Code that is considered a "procedure" by the server is called like
526 a normal (non-method) subroutine call. The server object is not
527 injected into the arguments list. The signature of the procedure is
528 checked again the list of arguments before the call is made, as
529 with methods.
530 Functions (RPC::XML::Function)
532 Lastly, code that is considered a "function" is the simplest of the
533 three: it does not have the server object injected into the
534 arguments list, and no check of signatures is done before the call
535 is made. It is the responsibility of the function to properly
536 understand the arguments list, and to return a value that the
537 caller will understand.
538 There is (currently) no version that is called like a method but
540 ignores signatures like a function.
541 How Procedures Are Called
543 When a routine is called via the server dispatcher, it is called with
544 the arguments that the client request passed. Depending on whether the
545 routine is considered a "function", a "procedure" or a "method", there
546 may be an extra argument at the head of the list. The extra argument is
547 present when the routine being dispatched is part of a RPC::XML::Method
548 object. The extra argument is a reference to a RPC::XML::Server object
549 (or a subclass thereof). This is derived from a hash reference, and
550 will include these special keys:
551 method_name
553 This is the name by which the method was called in the client. Most
554 of the time, this will probably be consistent for all calls to the
555 server-side method. But it does not have to be, hence the passing
556 of the value.
557 signature
559 This is the signature that was used, when dispatching. Perl has a
560 liberal view of lists and scalars, so it is not always clear what
561 arguments the client specifically has in mind when calling the
562 method. The signature is an array reference containing one or more
563 datatypes, each a simple string. The first of the datatypes
564 specifies the expected return type. The remainder (if any) refer to
565 the arguments themselves.
566 peerfamily
568 This is the address family, "AF_INET" or "AF_INET6", of a network
569 address of the client that has connected and made the current
570 request. It is required for unpacking "peeraddr" properly.
571 peeraddr
573 This is the address part of a packed SOCKADDR_IN or SOCKADDR_IN6
574 structure, as returned by "pack_sockaddr_in" in Socket or
575 "pack_sockaddr_in6" in Socket, which contains the address of the
576 client that has connected and made the current request. This is
577 provided "raw" in case you need it. While you could re-create it
578 from "peerhost", it is readily available in both this server
579 environment and the Apache::RPC::Server environment and thus
580 included for convenience. Apply "inet_ntop" in Socket to
581 "peerfamily" and this value to obtain textual representation of the
582 address.
583 peerhost
585 This is the address of the remote (client) end of the socket, in
586 "x.x.x.x" (dotted-quad) format. If you wish to look up the clients
587 host-name, you can use this to do so or utilize the encoded
588 structure above directly.
589 peerport
591 This is the port of the remote (client) end of the socket, taken
592 from the SOCKADDR_IN structure.
593 request
595 The HTTP::Request object for this request. Can be used to read HTTP
596 headers sent by the client ("X-Forwarded-For" for your access
597 checks, for example).
598 Those keys should only be referenced within method code itself, as they
600 are not set on the server object outside of that context.
601 Note that by passing the server object reference first, method-classed
603 routines are essentially expected to behave as actual methods of the
604 server class, as opposed to ordinary functions. Of course, they can
605 also discard the initial argument completely.
606 The routines should not make (excessive) use of global variables, for
608 obvious reasons. When the routines are loaded from XPL files, the code
609 is created as a closure that forces execution in the
610 RPC::XML::Procedure package (unless the XPL specifies a namespace, see
611 RPC::XML::Procedure). If the code element of a procedure/method is
612 passed in as a direct code reference by one of the other syntaxes
613 allowed by the constructor, the package may well be different. Thus,
614 routines should strive to be as localized as possible, independent of
615 specific namespaces. If a group of routines are expected to work in
616 close concert, each should explicitly set the namespace with a
617 "package" declaration as the first statement within the routines
618 themselves.
619 The Default Methods Provided
621 The following methods are provided with this package, and are the ones
622 installed on newly-created server objects unless told not to. These are
623 identified by their published names, as they are compiled internally as
624 anonymous subroutines and thus cannot be called directly:
625 system.identity
627 Returns a string value identifying the server name, version, and
628 possibly a capability level. Takes no arguments.
629 system.introspection
631 Returns a series of struct objects that give overview documentation
632 of one or more of the published methods. It may be called with a
633 string identifying a single routine, in which case the return value
634 is a struct. It may be called with an array of string values, in
635 which case an array of struct values, one per element in, is
636 returned. Lastly, it may be called with no input parameters, in
637 which case all published routines are documented. Note that
638 routines may be configured to be hidden from such introspection
639 queries.
640 system.listMethods
642 Returns a list of the published methods or a subset of them as an
643 array of string values. If called with no parameters, returns all
644 (non-hidden) method names. If called with a single string pattern,
645 returns only those names that contain the string as a substring of
646 their name (case-sensitive, and this is not a regular expression
647 evaluation).
648 system.methodHelp
650 Takes either a single method name as a string, or a series of them
651 as an array of string. The return value is the help text for the
652 method, as either a string or array of string value. If the
653 method(s) have no help text, the string will be null.
654 system.methodSignature
656 As above, but returns the signatures that the method accepts, as
657 array of string representations. If only one method is requests via
658 a string parameter, then the return value is the corresponding
659 array. If the parameter in is an array, then the returned value
660 will be an array of array of string.
661 system.multicall
663 This is a simple implementation of composite function calls in a
664 single request. It takes an array of struct values. Each struct has
665 at least a "methodName" member, which provides the name of the
666 method to call. If there is also a "params" member, it refers to an
667 array of the parameters that should be passed to the call.
668 system.status
670 Takes no arguments and returns a struct containing a number of
671 system status values including (but not limited to) the current
672 time on the server, the time the server was started (both of these
673 are returned in both ISO 8601 and UNIX-style integer formats),
674 number of requests dispatched, and some identifying information
675 (hostname, port, etc.).
676 In addition, each of these has an accompanying help file in the
678 "methods" sub-directory of the distribution.
679 These methods are installed as "*.xpl" files, which are generated from
681 files in the "methods" directory of the distribution using the
682 make_method tool (see make_method). The files there provide the Perl
683 code that implements these, their help files and other information.
684 Content Compression
686 The RPC::XML::Server class now supports compressed messages, both
687 incoming and outgoing. If a client indicates that it can understand
688 compressed content, the server will use the Compress::Zlib (available
689 from CPAN) module, if available, to compress any outgoing messages
690 above a certain threshhold in size (the default threshhold is set to
691 4096 bytes). The following methods are all related to the compression
692 support within the server class:
693 compress
695 Returns a false value if compression is not available to the server
696 object. This is based on the availability of the Compress::Zlib
697 module at start-up time, and cannot be changed.
698 compress_thresh([MIN_LIMIT])
700 Return or set the compression threshhold value. Messages smaller
701 than this size in bytes will not be compressed, even when
702 compression is available, to save on CPU resources. If a value is
703 passed, it becomes the new limit and the old value is returned.
704 Spooling Large Messages
706 If the server anticipates handling large out-bound messages (for
707 example, if the hosted code returns large Base64 values pre-encoded
708 from file handles), the "message_file_thresh" and "message_temp_dir"
709 settings may be used in a manner similar to RPC::XML::Client.
710 Specifically, the threshhold is used to determine when a message should
711 be spooled to a filehandle rather than made into an in-memory string
712 (the RPC::XML::base64 type can use a filehandle, thus eliminating the
713 need for the data to ever be completely in memory). An anonymous
714 temporary file is used for these operations.
715 Note that the message size is checked before compression is applied,
717 since the size of the compressed output cannot be known until the full
718 message is examined. It is possible that a message will be spooled even
719 if its compressed size is below the threshhold, if the uncompressed
720 size exceeds the threshhold.
721 message_file_thresh
723 message_temp_dir
724 These methods may be used to retrieve or alter the values of the
725 given keys as defined earlier for the "new" method.
726 Server Faults
728 Previous versions of this library had a very loosely-organized set of
729 fault codes that a server might return in certain (non-fatal) error
730 circumstances. This has been replaced by a more configurable,
731 adjustable system to allow users to better integrate the server-defined
732 faults with any that their application may produce. It also allows for
733 the definition of additional fault types so that the same mechanism for
734 formatting the pre-defined faults can be used within sub-classes and
735 user applications.
736 The server method server_fault is used to generate RPC::XML::fault
738 objects for these situations. It takes one or two arguments, the first
739 being the name of the type of fault to create and the second being the
740 specific message. If a fault is defined with a static message, the
741 second argument may be skipped (and will be ignored if passed).
742 In addition to defining their own faults, a user may override the
744 definition of any of the server's pre-defined faults.
745 Defining faults
747 The user may define their own faults using the "fault_table" argument
749 to the constructor of the server class being instantiated. They may
750 also override any of the pre-defined faults (detailed in the next
751 section) by providing a new definition for the name.
752 The value of the "fault_table" argument is a hash reference whose keys
754 are the names of the faults and whose values are one of two types:
755 An integer
757 If the value for the key is a scalar, it is assumed to be an
758 integer and will be used as the fault code. When the fault is
759 created, the message argument (the second parameter) will be used
760 verbatim as the fault message.
761 A 2-element list reference
763 If the value is a list reference, it is assumed to have two
764 elements: the first is the integer fault code to use, and the
765 second is a message "template" string to use as the fault message.
766 If the string contains the sequence %s, this will be replaced with
767 the message argument (the second parameter) passed to server_fault.
768 If that sequence is not in the string, then the fault message is
769 considered static and the message argument is ignored.
770 An example of defining faults:
772 my $server = RPC::XML::Server->new(
774 ...
775 fault_table => {
776 limitexceeded => [ 500 => 'Call limit exceeded' ],
777 accessdenied => [ 600 => 'Access denied: %s' ],
778 serviceclosed => 700
779 },
780 ...
781 );
782 In this example, the fault-type "limitexceeded" is defined as having a
784 fault code of 500 and a static message of "Call limit exceeded". The
785 next fault defined is "accessdenied", which has a code of 600 and
786 message that starts with "Access denied:" and incorporates whatever
787 message was passed in to the fault creation. The last example defines a
788 fault called "serviceclosed" that has a code of 700 and uses any
789 passed-in message unaltered.
790 Server-defined faults
792 The RPC::XML::Server class defines the following faults and uses them
794 internally. You can override the codes and messages for these by
795 including them in the table passed as a "fault_table" argument. The
796 faults fall into three groups:
797 Request Initialization
799 Faults in this group stem from the initialization of the request
800 and the parsing of the XML. The codes for this group fall in the
801 range 100-199.
802 Method Resolution
804 This group covers problems with mapping the request to a known
805 method or function on the server. These codes will be in the range
806 200-299.
807 Execution
809 Lastly, these faults are for problems in actually executing the
810 requested code. Their codes are in the range 300-399.
811 The faults, and the phases they apply to, are:
813 badxml (Request Initialization)
815 This fault is sent back to the client when the XML of the request
816 did not parse as a valid XML-RPC request.
817 The code is 100, and the message is of the form, "XML parse error:
819 %s". The specific error from the XML parser is included in the
820 message.
821 badmethod (Method Resolution)
823 This fault is sent when the requested method is unknown to the
824 server. No method has been configured on the server by that name.
825 The code is 200, and the message is of the form, "Method lookup
827 error: %s". The name of the method and other information is
828 included in the message.
829 badsignature (Method Resolution)
831 If a method is known on the server, but there is no signature that
832 matches the sequence of arguments passed, this fault is returned.
833 This fault cannot be triggered by server-side code configured via
834 RPC::XML::Function, as no signature-checking is done for those.
835 The code is 201, and the message is of the form, "Method signature
837 error: %s". The name of the method and the signature of the
838 arguments is included in the message.
839 execerror (Execution)
841 This fault relates back to the client any exception thrown by the
842 remote code during execution. If the invoked code returned their
843 error in the form of a RPC::XML::fault object, that fault is
844 returned instead. Otherwise, the value of $@ is used in the message
845 of the fault that gets generated.
846 The code is 300, and the message is of the form, "Code execution
848 error: %s". The actual text of the exception thrown is included in
849 the message.
850 There is one special server-fault whose code and message cannot be
852 overridden. If a call is made to server_fault for an unknown type of
853 fault, the returned object will have a code of "-1" and a message
854 stating that the fault-type is unknown. The message will include both
855 the requested type-name and any message (if any) that was passed in.
856 Adjusting the server-defined codes
858 If you just want to "move" the range of codes that the server uses out
860 of the way of your application's own faults, this can be done with the
861 "fault_code_base" parameter when constructing the server object. The
862 value of the parameter must be an integer, and it is added to the value
863 of all existing fault codes. For example, a value of 10000 would make
864 the code for the "badxml" fault be 10100, the code for "badmethod" be
865 10200, etc.
866 This is applied before any user-defined faults are merged in, so their
868 code values will not be affected by this value.
869
871 Unless explicitly stated otherwise, all methods return some type of
872 reference on success, or an error string on failure. Non-reference
873 return values should always be interpreted as errors unless otherwise
874 noted.
875
877 Please report any bugs or feature requests to "bug-rpc-xml at
878 rt.cpan.org", or through the web interface at
879 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
880 notified, and then you'll automatically be notified of progress on your
881 bug as I make changes.
882
884 · RT: CPAN's request tracker
885 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
887 · AnnoCPAN: Annotated CPAN documentation
889 <http://annocpan.org/dist/RPC-XML>
891 · CPAN Ratings
893 <http://cpanratings.perl.org/d/RPC-XML>
895 · Search CPAN
897 <http://search.cpan.org/dist/RPC-XML>
899 · MetaCPAN
901 <https://metacpan.org/release/RPC-XML>
903 · Source code on GitHub
905 <http://github.com/rjray/rpc-xml>
907
909 This file and the code within are copyright (c) 2011 by Randy J. Ray.
910 Copying and distribution are permitted under the terms of the Artistic
912 License 2.0
913 (<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
914 GNU LGPL 2.1 (<http://www.opensource.org/licenses/lgpl-2.1.php>).
915
917 The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software,
918 Inc. See <http://www.xmlrpc.com> for more information about the XML-
919 RPC specification.
920
922 RPC::XML, RPC::XML::Client, RPC::XML::ParserFactory
923
925 Randy J. Ray "<rjray@blackperl.com>"
926perl v5.30.0 2019-07-26 RPC::XML::Server(3)