RPC::XML::Server(3p)  User Contributed Perl Documentation RPC::XML::Server(3p)



NAME
       RPC::XML::Server - A server base-class for XML-RPC

SYNOPSIS
           use RPC::XML::Server;

           ...
           $srv = RPC::XML::Server->new(port => 9000);
           # Several of these, most likely:
           $srv->add_method(...);
           ...
           $srv->server_loop; # Never returns

DESCRIPTION
       This is both a base-class for developing XML-RPC servers, and a working
       server class in its own right. It is built upon the RPC::XML data
       classes, and defaults to using HTTP::Daemon for the communication
       layer.

SUBROUTINES/METHODS
       Use of the RPC::XML::Server is based on an object model. A server is
       instantiated from the class, methods (subroutines) are made public by
       adding them through the object interface, and then the server object is
       responsible for dispatching requests (and possibly for the HTTP
       listening, as well).

   Static Methods
       These methods are static to the package, and are used to provide
       external access to internal settings:

       INSTALL_DIR
           Returns the directory that this module is installed into. This is
           used by methods such as add_default_methods to locate the XPL files
           that are shipped with the distribution.

       version
           Returns the version string associated with this package.

       product_tokens
           This returns the identifying string for the server, in the format
           "NAME/VERSION" consistent with other applications such as Apache
           and LWP. It is provided here as part of the compatibility with
           HTTP::Daemon that is required for effective integration with
           Net::Server.

   Methods
       The following are object (non-static) methods. Unless otherwise
       explicitly noted, all methods return the invoking object reference upon
       success, and a non-reference error string upon failure.

       See "Content Compression" below for details of how the server class
       manages gzip-based compression and expansion of messages.

       new(OPTIONS)
           Creates a new object of the class and returns the blessed
           reference. Depending on the options, the object will contain some
           combination of an HTTP listener, a pre-populated HTTP::Response
           object, a RPC::XML::ParserFactory-generated object, and a dispatch
           table with the set of default procedures pre-loaded. The options
           that new accepts are passed as a hash of key/value pairs (not a
           hash reference).  The accepted options are:

           no_http
               If passed with a "true" value, prevents the creation and
               storage of the HTTP::Daemon object. This allows for deployment
               of a server object in other environments. Note that if this is
               set, the server_loop method described below will silently
               attempt to use the Net::Server module.

           no_default
               If passed with a "true" value, prevents the loading of the
               default procedures provided with the RPC::XML distribution.
               These may be later loaded using the add_default_methods
               interface described later. The procedures themselves are
               described below (see "The Default Procedures Provided").

           path
           host
           port
           queue
               These four are specific to the HTTP-based nature of the server.
               The path argument sets the additional URI path information that
               clients would use to contact the server.  Internally, it is not
               used except in outgoing status and introspection reports.  The
               host, port and queue arguments are passed to the HTTP::Daemon
               constructor if they are passed. They set the hostname, TCP/IP
               port, and socket listening queue, respectively. They may also
               be used if the server object tries to use Net::Server as an
               alternative server core.

           xpl_path
               If you plan to add procedures/methods/functions to the server
               object by passing filenames to the
               add_method/add_procedure/add_function calls, this argument may
               be used to specify one or more additional directories to be
               searched when the passed-in filename is a relative path. The
               value for this must be an array reference. See also the add_*
               and xpl_path methods, below.

           timeout
               Specify a value (in seconds) for the HTTP::Daemon server to use
               as a timeout value when reading request data from an inbound
               connection. The default value is 10 seconds. This value is not
               used except by HTTP::Daemon.

           auto_methods
               If specified and set to a true value, enables the automatic
               searching for a requested remote method/procedure/function that
               is unknown to the server object handling the request. If set to
               "no" (or not set at all), then a request for an unknown
               function causes the object instance to report an error. If the
               routine is still not found, the error is reported. Enabling
               this is a security risk, and should only be permitted by a
               server administrator with fully informed acknowledgement and
               consent.

           auto_updates
               If specified and set to a "true" value, enables the checking of
               the modification time of the file from which a
               method/procedure/function was originally loaded. If the file
               has changed, the method is re-loaded before execution is handed
               off. As with the auto-loading of methods, this represents a
               security risk, and should only be permitted by a server
               administrator with fully informed acknowledgement and consent.

           parser
               If this parameter is passed, its value is expected to be an
               array reference. The contents of that array are passed to the
               new method of the RPC::XML::ParserFactory class, which creates
               the parser object that the server object caches for its use.
               See the RPC::XML::ParserFactory manual page for a list of
               recognized parameters to the constructor.

           message_file_thresh
               If this key is passed, the value associated with it is assumed
               to be a numerical limit to the size of in-memory messages. Any
               out-bound request that would be larger than this when
               stringified is instead written to an anonynous temporary file,
               and spooled from there instead. This is useful for cases in
               which the request includes RPC::XML::base64 objects that are
               themselves spooled from file-handles. This test is independent
               of compression, so even if compression of a request would drop
               it below this threshhold, it will be spooled anyway. The file
               itself is created via File::Temp with "UNLINK" set, so once it
               is freed the disk space is immediately freed.

           message_temp_dir
               If a message is to be spooled to a temporary file, this key can
               define a specific directory in which to open those files. If
               this is not given, then the "tmpdir" method from the File::Spec
               package is used, instead.

           fault_code_base
               Specify a base integer value that is added to the numerical
               codes for all faults the server can return. See "Server Faults"
               for the list of faults that are built-in to the server class.
               This allows an application to "move" the RPC::XML::Server pre-
               defined fault codes out of the way of codes that the
               application itself may generate.

               Note that this value is not applied to any faults specified via
               the next option, "fault_table". It is assumed that the
               developer has already applied any offset to those codes.

           fault_table
               Specify one or more fault types to either add to or override
               the built-in set of faults for the server object. The value of
               this parameter is a hash reference whose keys are the fault
               type and whose values are either a scalar (which is taken to be
               the numerical code) or a list reference with two elements (the
               code followed by the string). See "Server Faults" for the list
               of faults that are built-in to the server class, and for more
               information on defining your own.

           Any other keys in the options hash not explicitly used by the
           constructor are copied over verbatim onto the object, for the
           benefit of sub-classing this class. All internal keys are prefixed
           with "__" to avoid confusion. Feel free to use this prefix only if
           you wish to re-introduce confusion.

       url This returns the HTTP URL that the server will be responding to,
           when it is in the connection-accept loop. If the server object was
           created without a built-in HTTP listener, then this method returns
           "undef".

       requests
           Returns the number of requests this server object has marshalled.
           Note that in multi-process environments (such as Apache or
           Net::Server::PreFork) the value returned will only reflect the
           messages dispatched by the specific process itself.

       response
           Each instance of this class (and any subclasses that do not
           completely override the "new" method) creates and stores an
           instance of HTTP::Response, which is then used by the HTTP::Daemon
           or Net::Server processing loops in constructing the response to
           clients. The response object has all common headers pre-set for
           efficiency. This method returns a reference to that object.

       started([BOOL])
           Gets and possibly sets the clock-time when the server starts
           accepting connections. If a value is passed that evaluates to true,
           then the current clock time is marked as the starting time. In
           either case, the current value is returned. The clock-time is based
           on the internal time command of Perl, and thus is represented as an
           integer number of seconds since the system epoch. Generally, it is
           suitable for passing to either localtime or to the "time2iso8601"
           routine exported by the RPC::XML package.

       timeout(INT)
           You can call this method to set the timeout of new connections
           after they are received.  This function returns the old timeout
           value.  If you pass in no value then it will return the old value
           without modifying the current value.  The default value is 10
           seconds.

       server_fault(STRING, STRING)
           Create a RPC::XML::fault object of the specified type, optionally
           including the second (string) parameter. See "Server Faults" for
           the list of faults defined by RPC::XML::Server (as well as
           documentation on creating your own).

       add_method(FILE | HASHREF | OBJECT)
       add_procedure(FILE | HASHREF | OBJECT)
       add_function(FILE | HASHREF | OBJECT)
           This adds a new published method/procedure/function to the server
           object that invokes it. The new method may be specified in one of
           three ways: as a filename, a hash reference or an existing object
           (generally of either RPC::XML::Procedure, RPC::XML::Method or
           RPC::XML::Function classes).

           If passed as a hash reference, the following keys are expected:

           name
               The published (externally-visible) name for the method.

           version
               An optional version stamp. Not used internally, kept mainly for
               informative purposes.

           hidden
               If passed and evaluates to a "true" value, then the method
               should be hidden from any introspection API implementations.
               This parameter is optional, the default behavior being to make
               the method publically-visible.

           code
               A code reference to the actual Perl subroutine that handles
               this method. A symbolic reference is not accepted. The value
               can be passed either as a reference to an existing routine, or
               possibly as a closure. See "How Procedures are Called" for the
               semantics the referenced subroutine must follow.

           signature
               A list reference of the signatures by which this routine may be
               invoked. Every method has at least one signature. Though less
               efficient for cases of exactly one signature, a list reference
               is always used for sake of consistency.

           help
               Optional documentation text for the method. This is the text
               that would be returned, for example, by a system.methodHelp
               call (providing the server has such an externally-visible
               method).

           If a file is passed, then it is expected to be in the XML-based
           format, described in the RPC::XML::Procedure page (see
           RPC::XML::Procedure).  If the name passed is not an absolute
           pathname, then the file will be searched for in any directories
           specified when the object was instantiated, then in the directory
           into which this module was installed, and finally in the current
           working directory. If the operation fails, the return value will be
           a non-reference, an error message. Otherwise, the return value is
           the object reference.

           The add_method, add_function and add_procedure calls are essentialy
           identical unless called with hash references. Both files and
           objects contain the information that defines the type (method vs.
           procedure) of the funtionality to be added to the server. If
           add_method is called with a file that describes a procedure, the
           resulting addition to the server object will be a
           RPC::XML::Procedure object, not a method object.

           For more on the creation and manipulation of procedures and methods
           as objects, see RPC::XML::Procedure.

       delete_method(NAME)
       delete_procedure(NAME)
       delete_function(NAME)
           Delete the named method/procedure/function from the calling object.
           Removes the entry from the internal table that the object
           maintains. If the method is shared across more than one server
           object (see "share_methods"), then the underlying object for it
           will only be destroyed when the last server object releases it. On
           error (such as no method by that name known), an error string is
           returned.

           The delete_procedure and delete_function calls are identical,
           supplied for the sake of symmetry. All calls return the matched
           object regardless of its underlying type.

       list_methods
       list_procedures
       list_functions
           This returns a list of the names of methods and procedures the
           server current has published.  Note that the returned values are
           not the method objects, but rather the names by which they are
           externally known. The "hidden" status of a method is not consulted
           when this list is created; all methods and procedures known are
           listed. The list is not sorted in any specific order.

           The list_procedures and list_functions calls are provided for
           symmetry. All calls list all published routines on the calling
           server object, regardless of underlying type.

       xpl_path([LISTREF])
           Get and/or set the object-specific search path for "*.xpl" files
           (files that specify methods) that are specified in calls to
           add_method, above. If a list reference is passed, it is installed
           as the new path (each element of the list being one directory name
           to search). Regardless of argument, the current path is returned as
           a list reference. When a file is passed to add_method, the elements
           of this path are searched first, in order, before the installation
           directory or the current working directory are searched.

       get_method(NAME)
       get_procedure(NAME)
       get_function(NAME)
           Returns a reference to an object of the class RPC::XML::Method,
           RPC::XML::Function or RPC::XML::Procedure, which is the current
           binding for the published method NAME. If there is no such method
           known to the server, then "undef" is returned. Note that this is a
           referent to the object as stored on the server object itself, and
           thus changes to it could affect the behavior of the server.

           The get_procedure and get_function calls are provided for symmetry.
           All will return the same object for NAME, regardless of the
           underlying type.

       server_loop(HASH)
           Enters the connection-accept loop, which generally does not return.
           This is the "accept()"-based loop of HTTP::Daemon if the object was
           created with an instance of that class as a part. Otherwise, this
           enters the run-loop of the Net::Server class. It listens for
           requests, and marshalls them out via the "dispatch" method
           described below. It answers HTTP-HEAD requests immediately (without
           counting them on the server statistics) and efficiently by using a
           cached HTTP::Response object.

           Because infinite loops requiring a "HUP" or "KILL" signal to
           terminate are generally in poor taste, the HTTP::Daemon side of
           this sets up a localized signal handler which causes an exit when
           triggered. By default, this is attached to the "INT" signal. If the
           Net::Server module is being used instead, it provides its own
           signal management.

           The arguments, if passed, are interpreted as a hash of key/value
           options (not a hash reference, please note). For HTTP::Daemon, only
           one is recognized:

           signal
               If passed, should be the traditional name for the signal that
               should be bound to the exit function. If desired, a reference
               to an array of signal names may be passed, in which case all
               signals will be given the same handler. The user is responsible
               for not passing the name of a non-existent signal, or one that
               cannot be caught. If the value of this argument is 0 (a "false"
               value) or the string "NONE", then the signal handler will not
               be installed, and the loop may only be broken out of by killing
               the running process (unless other arrangements are made within
               the application).

           The options that Net::Server responds to are detailed in the manual
           pages for that package. All options passed to "server_loop" in this
           situation are passed unaltered to the "run()" method in
           Net::Server.

       dispatch(REQUEST)
           This is the server method that actually manages the marshalling of
           an incoming request into an invocation of a Perl subroutine. The
           parameter passed in may be one of: a scalar containing the full XML
           text of the request, a scalar reference to such a string, or a pre-
           constructed RPC::XML::request object.  Unless an object is passed,
           the text is parsed with any errors triggering an early exit. Once
           the object representation of the request is on hand, the parameter
           data is extracted, as is the method name itself. The call is sent
           along to the appropriate subroutine, and the results are collated
           into an object of the RPC::XML::response class, which is returned.
           Any non-reference return value should be presumed to be an error
           string.

           The dispatched method may communicate error in several ways.
           First, any non-reference return value is presumed to be an error
           string, and is encoded and returned as an RPC::XML::fault response.
           The method is run under an "eval()", so errors conveyed by $@ are
           similarly encoded and returned.  As a special case, a method may
           explicitly "die()" with a fault response, which is passed on
           unmodified.

       add_default_methods([DETAILS])
           This method adds all the default methods (those that are shipped
           with this extension) to the calling server object. The files are
           denoted by their "*.xpl" extension, and are installed into the same
           directory as this Server.pm file. The set of default methods are
           described below (see "The Default Methods Provided").

           If any names are passed as a list of arguments to this call, then
           only those methods specified are actually loaded. If the "*.xpl"
           extension is absent on any of these names, then it is silently
           added for testing purposes. Note that the methods shipped with this
           package have file names without the leading "status." part of the
           method name. If the very first element of the list of arguments is
           "except" (or "-except"), then the rest of the list is treated as a
           set of names to not load, while all others do get read. The
           Apache::RPC::Server module uses this to prevent the loading of the
           default "system.status" method while still loading all the rest of
           the defaults. (It then provides a more Apache-centric status
           method.)

           Note that there are no symmetric calls in this case. The provided
           API is implemented as methods, and thus only this interface is
           provided.

       add_methods_in_dir(DIR [, DETAILS])
       add_procedures_in_dir(DIR [, DETAILS])
       add_functions_in_dir(DIR [, DETAILS])
           This is exactly like add_default_methods above, save that the
           caller specifies which directory to scan for "*.xpl" files. In
           fact, the add_default_methods routine simply calls this routine
           with the installation directory as the first argument. The
           definition of the additional arguments is the same as above.

           add_procedures_in_dir and add_functions_in_dir are provided for
           symmetry.

       share_methods(SERVER, NAMES)
       share_procedures(SERVER, NAMES)
       share_functions(SERVER, NAMES)
           The calling server object shares the methods/procedures/functions
           listed in NAMES with the source-server passed as the first object.
           The source must derive from this package in order for this
           operation to be permitted. At least one method must be specified,
           and all are specified by name (not by object refernce). Both
           objects will reference the same exact RPC::XML::Procedure (or
           derivative thereof) object in this case, meaning that call-
           statistics and the like will reflect the combined data. If one or
           more of the passed names are not present on the source server, an
           error message is returned and none are copied to the calling
           object.

           Alternately, one or more of the name parameters passed to this call
           may be regular-expression objects (the result of the qr operator).
           Any of these detected are applied against the list of all available
           methods known to the source server. All matching ones are inserted
           into the list (the list is pared for redundancies in any case).
           This allows for easier addition of whole classes such as those in
           the "system.*" name space (via "qr/^system[.]/"), for example.
           There is no substring matching provided. Names listed in the
           parameters to this routine must be either complete strings or
           regular expressions.

           The share_procedures and share_functions calls are provided for
           symmetry.

       copy_methods(SERVER, NAMES)
       copy_procedures(SERVER, NAMES)
       copy_functions(SERVER, NAMES)
           These behave like the methods share_* above, with the exception
           that the calling object is given a clone of each method, rather
           than referencing the same exact method as the source server. The
           code reference part of the method is shared between the two, but
           all other data are copied (including a fresh copy of any list
           references used) into a completely new RPC::XML::Procedure (or
           derivative) object, using the "clone()" method from that class.
           Thus, while the calling object has the same methods available, and
           is re-using existing code in the Perl runtime, the method objects
           (and hence the statistics and such) are kept separate. As with the
           above, an error is flagged if one or more are not found.

           This routine also accepts regular-expression objects with the same
           behavior and limitations. Again, copy_procedures and copy_functions
           are provided for symmetry.

   Specifying Server-Side Remote Procedures
       Specifying the methods themselves can be a tricky undertaking. Some
       packages (in other languages) delegate a specific class to handling
       incoming requests.  This works well, but it can lead to routines not
       intended for public availability to in fact be available. There are
       also issues around the access that the methods would then have to other
       resources within the same running system.

       The approach taken by RPC::XML::Server (and the Apache::RPC::Server
       subclass of it) require that remote procedures be explicitly published
       in one of the several ways provided. Procedures may be added directly
       within code by using add_procedure/add_method/add_function as described
       above, with full data provided for the code reference, signature list,
       etc. The add_* technique can also be used with a file that conforms to
       a specific XML-based format (detailed in the manual page for the
       RPC::XML::Procedure class, see RPC::XML::Procedure).  Entire
       directories of files may be added using add_methods_in_dir, which
       merely reads the given directory for files that appear to be method
       definitions.

   The Three Types of Procedures
       There are three types of procedures that RPC::XML::Server marshalls
       calls to. All are provided by the RPC::XML::Procedure module. You
       should not need to load or reference this module directly, as loading
       RPC::XML::Server (or a derivative) makes it available. The three types
       are:

       Methods (RPC::XML::Method)
           Code that is considered a "method" by the server is called as
           though it were, in fact, a method in that class. The first argument
           in the list is the server object itself, with the arguments to the
           call making up the rest of the list.  The server checks the
           signature of the method against the arguments list before the call
           is made. See below ("How Procedures Are Called") for more on the
           invocation of code as methods.

       Procedures (RPC::XML::Procedure)
           Code that is considered a "procedure" by the server is called like
           a normal (non-method) subroutine call. The server object is not
           injected into the arguments list. The signature of the procedure is
           checked again the list of arguments before the call is made, as
           with methods.

       Functions (RPC::XML::Function)
           Lastly, code that is considered a "function" is the simplest of the
           three: it does not have the server object injected into the
           arguments list, and no check of signatures is done before the call
           is made. It is the responsibility of the function to properly
           understand the arguments list, and to return a value that the
           caller will understand.

       There is (currently) no version that is called like a method but
       ignores signatures like a function.

   How Procedures Are Called
       When a routine is called via the server dispatcher, it is called with
       the arguments that the client request passed. Depending on whether the
       routine is considered a "function", a "procedure" or a "method", there
       may be an extra argument at the head of the list. The extra argument is
       present when the routine being dispatched is part of a RPC::XML::Method
       object. The extra argument is a reference to a RPC::XML::Server object
       (or a subclass thereof). This is derived from a hash reference, and
       will include these special keys:

       method_name
           This is the name by which the method was called in the client. Most
           of the time, this will probably be consistent for all calls to the
           server-side method. But it does not have to be, hence the passing
           of the value.

       signature
           This is the signature that was used, when dispatching. Perl has a
           liberal view of lists and scalars, so it is not always clear what
           arguments the client specifically has in mind when calling the
           method. The signature is an array reference containing one or more
           datatypes, each a simple string. The first of the datatypes
           specifies the expected return type. The remainder (if any) refer to
           the arguments themselves.

       peeraddr
           This is the address part of a packed SOCKADDR_IN structure, as
           returned by "pack_sockaddr_in" in Socket, which contains the
           address of the client that has connected and made the current
           request. This is provided "raw" in case you need it. While you
           could re-create it from "peerhost", it is readily available in both
           this server environment and the Apache::RPC::Server environment and
           thus included for convenience.

       peerhost
           This is the address of the remote (client) end of the socket, in
           "x.x.x.x" (dotted-quad) format. If you wish to look up the clients
           host-name, you can use this to do so or utilize the encoded
           structure above directly.

       peerport
           This is the port of the remote (client) end of the socket, taken
           from the SOCKADDR_IN structure.

       request
           The HTTP::Request object for this request. Can be used to read HTTP
           headers sent by the client ("X-Forwarded-For" for your access
           checks, for example).

       Those keys should only be referenced within method code itself, as they
       are not set on the server object outside of that context.

       Note that by passing the server object reference first, method-classed
       routines are essentially expected to behave as actual methods of the
       server class, as opposed to ordinary functions. Of course, they can
       also discard the initial argument completely.

       The routines should not make (excessive) use of global variables, for
       obvious reasons. When the routines are loaded from XPL files, the code
       is created as a closure that forces execution in the
       RPC::XML::Procedure package (unless the XPL specifies a namespace, see
       RPC::XML::Procedure). If the code element of a procedure/method is
       passed in as a direct code reference by one of the other syntaxes
       allowed by the constructor, the package may well be different. Thus,
       routines should strive to be as localized as possible, independent of
       specific namespaces. If a group of routines are expected to work in
       close concert, each should explicitly set the namespace with a
       "package" declaration as the first statement within the routines
       themselves.

   The Default Methods Provided
       The following methods are provided with this package, and are the ones
       installed on newly-created server objects unless told not to. These are
       identified by their published names, as they are compiled internally as
       anonymous subroutines and thus cannot be called directly:

       system.identity
           Returns a string value identifying the server name, version, and
           possibly a capability level. Takes no arguments.

       system.introspection
           Returns a series of struct objects that give overview documentation
           of one or more of the published methods. It may be called with a
           string identifying a single routine, in which case the return value
           is a struct. It may be called with an array of string values, in
           which case an array of struct values, one per element in, is
           returned. Lastly, it may be called with no input parameters, in
           which case all published routines are documented.  Note that
           routines may be configured to be hidden from such introspection
           queries.

       system.listMethods
           Returns a list of the published methods or a subset of them as an
           array of string values. If called with no parameters, returns all
           (non-hidden) method names. If called with a single string pattern,
           returns only those names that contain the string as a substring of
           their name (case-sensitive, and this is not a regular expression
           evaluation).

       system.methodHelp
           Takes either a single method name as a string, or a series of them
           as an array of string. The return value is the help text for the
           method, as either a string or array of string value. If the
           method(s) have no help text, the string will be null.

       system.methodSignature
           As above, but returns the signatures that the method accepts, as
           array of string representations. If only one method is requests via
           a string parameter, then the return value is the corresponding
           array. If the parameter in is an array, then the returned value
           will be an array of array of string.

       system.multicall
           This is a simple implementation of composite function calls in a
           single request. It takes an array of struct values. Each struct has
           at least a "methodName" member, which provides the name of the
           method to call. If there is also a "params" member, it refers to an
           array of the parameters that should be passed to the call.

       system.status
           Takes no arguments and returns a struct containing a number of
           system status values including (but not limited to) the current
           time on the server, the time the server was started (both of these
           are returned in both ISO 8601 and UNIX-style integer formats),
           number of requests dispatched, and some identifying information
           (hostname, port, etc.).

       In addition, each of these has an accompanying help file in the
       "methods" sub-directory of the distribution.

       These methods are installed as "*.xpl" files, which are generated from
       files in the "methods" directory of the distribution using the
       make_method tool (see make_method). The files there provide the Perl
       code that implements these, their help files and other information.

   Content Compression
       The RPC::XML::Server class now supports compressed messages, both
       incoming and outgoing. If a client indicates that it can understand
       compressed content, the server will use the Compress::Zlib (available
       from CPAN) module, if available, to compress any outgoing messages
       above a certain threshhold in size (the default threshhold is set to
       4096 bytes). The following methods are all related to the compression
       support within the server class:

       compress
           Returns a false value if compression is not available to the server
           object.  This is based on the availability of the Compress::Zlib
           module at start-up time, and cannot be changed.

       compress_thresh([MIN_LIMIT])
           Return or set the compression threshhold value. Messages smaller
           than this size in bytes will not be compressed, even when
           compression is available, to save on CPU resources. If a value is
           passed, it becomes the new limit and the old value is returned.

   Spooling Large Messages
       If the server anticipates handling large out-bound messages (for
       example, if the hosted code returns large Base64 values pre-encoded
       from file handles), the "message_file_thresh" and "message_temp_dir"
       settings may be used in a manner similar to RPC::XML::Client.
       Specifically, the threshhold is used to determine when a message should
       be spooled to a filehandle rather than made into an in-memory string
       (the RPC::XML::base64 type can use a filehandle, thus eliminating the
       need for the data to ever be completely in memory). An anonymous
       temporary file is used for these operations.

       Note that the message size is checked before compression is applied,
       since the size of the compressed output cannot be known until the full
       message is examined. It is possible that a message will be spooled even
       if its compressed size is below the threshhold, if the uncompressed
       size exceeds the threshhold.

       message_file_thresh
       message_temp_dir
           These methods may be used to retrieve or alter the values of the
           given keys as defined earlier for the "new" method.

   Server Faults
       Previous versions of this library had a very loosely-organized set of
       fault codes that a server might return in certain (non-fatal) error
       circumstances.  This has been replaced by a more configurable,
       adjustable system to allow users to better integrate the server-defined
       faults with any that their application may produce. It also allows for
       the definition of additional fault types so that the same mechanism for
       formatting the pre-defined faults can be used within sub-classes and
       user applications.

       The server method server_fault is used to generate RPC::XML::fault
       objects for these situations. It takes one or two arguments, the first
       being the name of the type of fault to create and the second being the
       specific message. If a fault is defined with a static message, the
       second argument may be skipped (and will be ignored if passed).

       In addition to defining their own faults, a user may override the
       definition of any of the server's pre-defined faults.

       Defining faults

       The user may define their own faults using the "fault_table" argument
       to the constructor of the server class being instantiated. They may
       also override any of the pre-defined faults (detailed in the next
       section) by providing a new definition for the name.

       The value of the "fault_table" argument is a hash reference whose keys
       are the names of the faults and whose values are one of two types:

       An integer
           If the value for the key is a scalar, it is assumed to be an
           integer and will be used as the fault code. When the fault is
           created, the message argument (the second parameter) will be used
           verbatim as the fault message.

       A 2-element list reference
           If the value is a list reference, it is assumed to have two
           elements: the first is the integer fault code to use, and the
           second is a message "template" string to use as the fault message.
           If the string contains the sequence %s, this will be replaced with
           the message argument (the second parameter) passed to server_fault.
           If that sequence is not in the string, then the fault message is
           considered static and the message argument is ignored.

       An example of defining faults:

           my $server = RPC::XML::Server->new(
               ...
               fault_table => {
                   limitexceeded => [ 500 => 'Call limit exceeded' ],
                   accessdenied  => [ 600 => 'Access denied: %s' ],
                   serviceclosed => 700
               },
               ...
           );

       In this example, the fault-type "limitexceeded" is defined as having a
       fault code of 500 and a static message of "Call limit exceeded". The
       next fault defined is "accessdenied", which has a code of 600 and
       message that starts with "Access denied:" and incorporates whatever
       message was passed in to the fault creation. The last example defines a
       fault called "serviceclosed" that has a code of 700 and uses any
       passed-in message unaltered.

       Server-defined faults

       The RPC::XML::Server class defines the following faults and uses them
       internally. You can override the codes and messages for these by
       including them in the table passed as a "fault_table" argument. The
       faults fall into three groups:

       Request Initialization
           Faults in this group stem from the initialization of the request
           and the parsing of the XML. The codes for this group fall in the
           range 100-199.

       Method Resolution
           This group covers problems with mapping the request to a known
           method or function on the server. These codes will be in the range
           200-299.

       Execution
           Lastly, these faults are for problems in actually executing the
           requested code. Their codes are in the range 300-399.

       The faults, and the phases they apply to, are:

       badxml (Request Initialization)
           This fault is sent back to the client when the XML of the request
           did not parse as a valid XML-RPC request.

           The code is 100, and the message is of the form, "XML parse error:
           %s".  The specific error from the XML parser is included in the
           message.

       badmethod (Method Resolution)
           This fault is sent when the requested method is unknown to the
           server. No method has been configured on the server by that name.

           The code is 200, and the message is of the form, "Method lookup
           error: %s".  The name of the method and other information is
           included in the message.

       badsignature (Method Resolution)
           If a method is known on the server, but there is no signature that
           matches the sequence of arguments passed, this fault is returned.
           This fault cannot be triggered by server-side code configured via
           RPC::XML::Function, as no signature-checking is done for those.

           The code is 201, and the message is of the form, "Method signature
           error: %s". The name of the method and the signature of the
           arguments is included in the message.

       execerror (Execution)
           This fault relates back to the client any exception thrown by the
           remote code during execution. If the invoked code returned their
           error in the form of a RPC::XML::fault object, that fault is
           returned instead. Otherwise, the value of $@ is used in the message
           of the fault that gets generated.

           The code is 300, and the message is of the form, "Code execution
           error: %s". The actual text of the exception thrown is included in
           the message.

       There is one special server-fault whose code and message cannot be
       overridden.  If a call is made to server_fault for an unknown type of
       fault, the returned object will have a code of "-1" and a message
       stating that the fault-type is unknown. The message will include both
       the requested type-name and any message (if any) that was passed in.

       Adjusting the server-defined codes

       If you just want to "move" the range of codes that the server uses out
       of the way of your application's own faults, this can be done with the
       "fault_code_base" parameter when constructing the server object. The
       value of the parameter must be an integer, and it is added to the value
       of all existing fault codes. For example, a value of 10000 would make
       the code for the "badxml" fault be 10100, the code for "badmethod" be
       10200, etc.

       This is applied before any user-defined faults are merged in, so their
       code values will not be affected by this value.

DIAGNOSTICS
       Unless explicitly stated otherwise, all methods return some type of
       reference on success, or an error string on failure. Non-reference
       return values should always be interpreted as errors unless otherwise
       noted.

BUGS
       Please report any bugs or feature requests to "bug-rpc-xml at
       rt.cpan.org", or through the web interface at
       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
       notified, and then you'll automatically be notified of progress on your
       bug as I make changes.

SUPPORT
       o   RT: CPAN's request tracker

           http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML
           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>

       o   AnnoCPAN: Annotated CPAN documentation

           http://annocpan.org/dist/RPC-XML <http://annocpan.org/dist/RPC-XML>

       o   CPAN Ratings

           http://cpanratings.perl.org/d/RPC-XML
           <http://cpanratings.perl.org/d/RPC-XML>

       o   Search CPAN

           http://search.cpan.org/dist/RPC-XML
           <http://search.cpan.org/dist/RPC-XML>

       o   MetaCPAN

           https://metacpan.org/release/RPC-XML
           <https://metacpan.org/release/RPC-XML>

       o   Source code on GitHub

           http://github.com/rjray/rpc-xml <http://github.com/rjray/rpc-xml>

LICENSE AND COPYRIGHT
       This file and the code within are copyright (c) 2011 by Randy J. Ray.

       Copying and distribution are permitted under the terms of the Artistic
       License 2.0
       (http://www.opensource.org/licenses/artistic-license-2.0.php
       <http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
       GNU LGPL 2.1 (http://www.opensource.org/licenses/lgpl-2.1.php
       <http://www.opensource.org/licenses/lgpl-2.1.php>).

CREDITS
       The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software,
       Inc.  See <http://www.xmlrpc.com> for more information about the XML-
       RPC specification.

SEE ALSO
       RPC::XML, RPC::XML::Client, RPC::XML::ParserFactory

AUTHOR
       Randy J. Ray "<rjray@blackperl.com>"



perl v5.12.2                      2011-08-18              RPC::XML::Server(3p)
