1RPC::XML::Server(3)   User Contributed Perl Documentation  RPC::XML::Server(3)
2
3
4

NAME

6       RPC::XML::Server - A server base-class for XML-RPC
7

SYNOPSIS

9           use RPC::XML::Server;
10
11           ...
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

DESCRIPTION

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

SUBROUTINES/METHODS

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
31   Static Methods
32       These methods are static to the package, and are used to provide
33       external access to internal settings:
34
35       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
40       version
41           Returns the version string associated with this package.
42
43       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
50   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
55       See "Content Compression" below for details of how the server class
56       manages gzip-based compression and expansion of messages.
57
58       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
67           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
74           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
81           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
95           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
104           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
110           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
121           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
130           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
138           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
151           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
157           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
165               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
169           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
179           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
185       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
190       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
196       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
204       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
214       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
221       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
227       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
236           If passed as a hash reference, the following keys are expected:
237
238           name
239               The published (externally-visible) name for the method.
240
241           version
242               An optional version stamp. Not used internally, kept mainly for
243               informative purposes.
244
245           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
251           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
258           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
264           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
270           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
280           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
288           For more on the creation and manipulation of procedures and methods
289           as objects, see RPC::XML::Procedure.
290
291       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
302           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
306       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
316           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
320       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
330       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
340           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
344       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
354           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
361           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
365           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
377           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
382       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
396           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
404       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
411           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
424           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
428       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
437           add_procedures_in_dir and add_functions_in_dir are provided for
438           symmetry.
439
440       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
455           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
466           The share_procedures and share_functions calls are provided for
467           symmetry.
468
469       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
484           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
488   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
496       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
508   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
515       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
524       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
531       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
539       There is (currently) no version that is called like a method but
540       ignores signatures like a function.
541
542   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
552       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
558       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
567       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
572       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
584       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
590       peerport
591           This is the port of the remote (client) end of the socket, taken
592           from the SOCKADDR_IN structure.
593
594       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
599       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
602       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
607       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
620   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
626       system.identity
627           Returns a string value identifying the server name, version, and
628           possibly a capability level. Takes no arguments.
629
630       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
641       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
649       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
655       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
662       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
669       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
677       In addition, each of these has an accompanying help file in the
678       "methods" sub-directory of the distribution.
679
680       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
685   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
694       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
699       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
705   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
716       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
722       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
727   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
737       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
743       In addition to defining their own faults, a user may override the
744       definition of any of the server's pre-defined faults.
745
746       Defining faults
747
748       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
753       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
756       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
762       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
771       An example of defining faults:
772
773           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
783       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
791       Server-defined faults
792
793       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
798       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
803       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
808       Execution
809           Lastly, these faults are for problems in actually executing the
810           requested code. Their codes are in the range 300-399.
811
812       The faults, and the phases they apply to, are:
813
814       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
818           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
822       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
826           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
830       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
836           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
840       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
847           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
851       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
857       Adjusting the server-defined codes
858
859       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
867       This is applied before any user-defined faults are merged in, so their
868       code values will not be affected by this value.
869

DIAGNOSTICS

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

BUGS

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

SUPPORT

884       ·   RT: CPAN's request tracker
885
886           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
887
888       ·   AnnoCPAN: Annotated CPAN documentation
889
890           <http://annocpan.org/dist/RPC-XML>
891
892       ·   CPAN Ratings
893
894           <http://cpanratings.perl.org/d/RPC-XML>
895
896       ·   Search CPAN
897
898           <http://search.cpan.org/dist/RPC-XML>
899
900       ·   MetaCPAN
901
902           <https://metacpan.org/release/RPC-XML>
903
904       ·   Source code on GitHub
905
906           <http://github.com/rjray/rpc-xml>
907
909       This file and the code within are copyright (c) 2011 by Randy J. Ray.
910
911       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

CREDITS

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

SEE ALSO

922       RPC::XML, RPC::XML::Client, RPC::XML::ParserFactory
923

AUTHOR

925       Randy J. Ray "<rjray@blackperl.com>"
926
927
928
929perl v5.28.0                      2018-07-15               RPC::XML::Server(3)
Impressum