{
    "mode": "perldoc",
    "parameter": "RPC::XML::Server",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/RPC%3A%3AXML%3A%3AServer/json",
    "generated": "2026-06-13T23:47:47Z",
    "synopsis": "use RPC::XML::Server;\n...\n$srv = RPC::XML::Server->new(port => 9000);\n# Several of these, most likely:\n$srv->addmethod(...);\n...\n$srv->serverloop; # Never returns",
    "sections": {
        "NAME": {
            "content": "RPC::XML::Server - A server base-class for XML-RPC\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use RPC::XML::Server;\n\n...\n$srv = RPC::XML::Server->new(port => 9000);\n# Several of these, most likely:\n$srv->addmethod(...);\n...\n$srv->serverloop; # Never returns\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This is both a base-class for developing XML-RPC servers, and a working server class in its own\nright. It is built upon the RPC::XML data classes, and defaults to using HTTP::Daemon for the\ncommunication layer.\n",
            "subsections": []
        },
        "SUBROUTINES/METHODS": {
            "content": "Use of the RPC::XML::Server is based on an object model. A server is instantiated from the\nclass, methods (subroutines) are made public by adding them through the object interface, and\nthen the server object is responsible for dispatching requests (and possibly for the HTTP\nlistening, as well).\n",
            "subsections": [
                {
                    "name": "Static Methods",
                    "content": "These methods are static to the package, and are used to provide external access to internal\nsettings:\n\nINSTALLDIR\nReturns the directory that this module is installed into. This is used by methods such as\nadddefaultmethods to locate the XPL files that are shipped with the distribution.\n\nversion\nReturns the version string associated with this package.\n\nproducttokens\nThis returns the identifying string for the server, in the format \"NAME/VERSION\" consistent\nwith other applications such as Apache and LWP. It is provided here as part of the\ncompatibility with HTTP::Daemon that is required for effective integration with Net::Server.\n"
                },
                {
                    "name": "Methods",
                    "content": "The following are object (non-static) methods. Unless otherwise explicitly noted, all methods\nreturn the invoking object reference upon success, and a non-reference error string upon\nfailure.\n\nSee \"Content Compression\" below for details of how the server class manages gzip-based\ncompression and expansion of messages.\n"
                },
                {
                    "name": "new",
                    "content": "Creates a new object of the class and returns the blessed reference. Depending on the\noptions, the object will contain some combination of an HTTP listener, a pre-populated\nHTTP::Response object, a RPC::XML::ParserFactory-generated object, and a dispatch table with\nthe set of default procedures pre-loaded. The options that new accepts are passed as a hash\nof key/value pairs (not a hash reference). The accepted options are:\n\nnohttp\nIf passed with a \"true\" value, prevents the creation and storage of the HTTP::Daemon\nobject. This allows for deployment of a server object in other environments. Note that\nif this is set, the serverloop method described below will silently attempt to use the\nNet::Server module.\n\nnodefault\nIf passed with a \"true\" value, prevents the loading of the default procedures provided\nwith the RPC::XML distribution. These may be later loaded using the adddefaultmethods\ninterface described later. The procedures themselves are described below (see \"The\nDefault Procedures Provided\").\n\npath\nhost\nport\nqueue\nThese four are specific to the HTTP-based nature of the server. The path argument sets\nthe additional URI path information that clients would use to contact the server.\nInternally, it is not used except in outgoing status and introspection reports. The\nhost, port and queue arguments are passed to the HTTP::Daemon constructor if they are\npassed. They set the hostname, TCP/IP port, and socket listening queue, respectively.\nThey may also be used if the server object tries to use Net::Server as an alternative\nserver core.\n\nxplpath\nIf you plan to add procedures/methods/functions to the server object by passing\nfilenames to the addmethod/addprocedure/addfunction calls, this argument may be used\nto specify one or more additional directories to be searched when the passed-in filename\nis a relative path. The value for this must be an array reference. See also the add*\nand xplpath methods, below.\n\ntimeout\nSpecify a value (in seconds) for the HTTP::Daemon server to use as a timeout value when\nreading request data from an inbound connection. The default value is 10 seconds. This\nvalue is not used except by HTTP::Daemon.\n\nautomethods\nIf specified and set to a true value, enables the automatic searching for a requested\nremote method/procedure/function that is unknown to the server object handling the\nrequest. If set to \"no\" (or not set at all), then a request for an unknown function\ncauses the object instance to report an error. If the routine is still not found, the\nerror is reported. Enabling this is a security risk, and should only be permitted by a\nserver administrator with fully informed acknowledgement and consent.\n\nautoupdates\nIf specified and set to a \"true\" value, enables the checking of the modification time of\nthe file from which a method/procedure/function was originally loaded. If the file has\nchanged, the method is re-loaded before execution is handed off. As with the\nauto-loading of methods, this represents a security risk, and should only be permitted\nby a server administrator with fully informed acknowledgement and consent.\n\nparser\nIf this parameter is passed, its value is expected to be an array reference. The\ncontents of that array are passed to the new method of the RPC::XML::ParserFactory\nclass, which creates the parser object that the server object caches for its use. See\nthe RPC::XML::ParserFactory manual page for a list of recognized parameters to the\nconstructor.\n\nmessagefilethresh\nIf this key is passed, the value associated with it is assumed to be a numerical limit\nto the size of in-memory messages. Any out-bound request that would be larger than this\nwhen stringified is instead written to an anonynous temporary file, and spooled from\nthere instead. This is useful for cases in which the request includes RPC::XML::base64\nobjects that are themselves spooled from file-handles. This test is independent of\ncompression, so even if compression of a request would drop it below this threshold, it\nwill be spooled anyway. The file itself is created via File::Temp with \"UNLINK\" set, so\nonce it is freed the disk space is immediately freed.\n\nmessagetempdir\nIf a message is to be spooled to a temporary file, this key can define a specific\ndirectory in which to open those files. If this is not given, then the \"tmpdir\" method\nfrom the File::Spec package is used, instead.\n\nfaultcodebase\nSpecify a base integer value that is added to the numerical codes for all faults the\nserver can return. See \"Server Faults\" for the list of faults that are built-in to the\nserver class. This allows an application to \"move\" the RPC::XML::Server pre-defined\nfault codes out of the way of codes that the application itself may generate.\n\nNote that this value is not applied to any faults specified via the next option,\n\"faulttable\". It is assumed that the developer has already applied any offset to those\ncodes.\n\nfaulttable\nSpecify one or more fault types to either add to or override the built-in set of faults\nfor the server object. The value of this parameter is a hash reference whose keys are\nthe fault type and whose values are either a scalar (which is taken to be the numerical\ncode) or a list reference with two elements (the code followed by the string). See\n\"Server Faults\" for the list of faults that are built-in to the server class, and for\nmore information on defining your own.\n\nAny other keys in the options hash not explicitly used by the constructor are copied over\nverbatim onto the object, for the benefit of sub-classing this class. All internal keys are\nprefixed with \"\" to avoid confusion. Feel free to use this prefix only if you wish to\nre-introduce confusion.\n\nurl This returns the HTTP URL that the server will be responding to, when it is in the\nconnection-accept loop. If the server object was created without a built-in HTTP listener,\nthen this method returns \"undef\".\n\nrequests\nReturns the number of requests this server object has marshalled. Note that in multi-process\nenvironments (such as Apache or Net::Server::PreFork) the value returned will only reflect\nthe messages dispatched by the specific process itself.\n\nresponse\nEach instance of this class (and any subclasses that do not completely override the \"new\"\nmethod) creates and stores an instance of HTTP::Response, which is then used by the\nHTTP::Daemon or Net::Server processing loops in constructing the response to clients. The\nresponse object has all common headers pre-set for efficiency. This method returns a\nreference to that object.\n"
                },
                {
                    "name": "started",
                    "content": "Gets and possibly sets the clock-time when the server starts accepting connections. If a\nvalue is passed that evaluates to true, then the current clock time is marked as the\nstarting time. In either case, the current value is returned. The clock-time is based on the\ninternal time command of Perl, and thus is represented as an integer number of seconds since\nthe system epoch. Generally, it is suitable for passing to either localtime or to the\n\"time2iso8601\" routine exported by the RPC::XML package.\n"
                },
                {
                    "name": "timeout",
                    "content": "You can call this method to set the timeout of new connections after they are received. This\nfunction returns the old timeout value. If you pass in no value then it will return the old\nvalue without modifying the current value. The default value is 10 seconds.\n"
                },
                {
                    "name": "server_fault",
                    "content": "Create a RPC::XML::fault object of the specified type, optionally including the second\n(string) parameter. See \"Server Faults\" for the list of faults defined by RPC::XML::Server\n(as well as documentation on creating your own).\n"
                },
                {
                    "name": "add_method",
                    "content": ""
                },
                {
                    "name": "add_procedure",
                    "content": ""
                },
                {
                    "name": "add_function",
                    "content": "This adds a new published method/procedure/function to the server object that invokes it.\nThe new method may be specified in one of three ways: as a filename, a hash reference or an\nexisting object (generally of either RPC::XML::Procedure, RPC::XML::Method or\nRPC::XML::Function classes).\n\nIf passed as a hash reference, the following keys are expected:\n\nname\nThe published (externally-visible) name for the method.\n\nversion\nAn optional version stamp. Not used internally, kept mainly for informative purposes.\n\nhidden\nIf passed and evaluates to a \"true\" value, then the method should be hidden from any\nintrospection API implementations. This parameter is optional, the default behavior\nbeing to make the method publically-visible.\n\ncode\nA code reference to the actual Perl subroutine that handles this method. A symbolic\nreference is not accepted. The value can be passed either as a reference to an existing\nroutine, or possibly as a closure. See \"How Procedures are Called\" for the semantics the\nreferenced subroutine must follow.\n\nsignature\nA list reference of the signatures by which this routine may be invoked. Every method\nhas at least one signature. Though less efficient for cases of exactly one signature, a\nlist reference is always used for sake of consistency.\n\nhelp\nOptional documentation text for the method. This is the text that would be returned, for\nexample, by a system.methodHelp call (providing the server has such an\nexternally-visible method).\n\nIf a file is passed, then it is expected to be in the XML-based format, described in the\nRPC::XML::Procedure page (see RPC::XML::Procedure). If the name passed is not an absolute\npathname, then the file will be searched for in any directories specified when the object\nwas instantiated, then in the directory into which this module was installed, and finally in\nthe current working directory. If the operation fails, the return value will be a\nnon-reference, an error message. Otherwise, the return value is the object reference.\n\nThe addmethod, addfunction and addprocedure calls are essentialy identical unless called\nwith hash references. Both files and objects contain the information that defines the type\n(method vs. procedure) of the functionality to be added to the server. If addmethod is\ncalled with a file that describes a procedure, the resulting addition to the server object\nwill be a RPC::XML::Procedure object, not a method object.\n\nFor more on the creation and manipulation of procedures and methods as objects, see\nRPC::XML::Procedure.\n"
                },
                {
                    "name": "delete_method",
                    "content": ""
                },
                {
                    "name": "delete_procedure",
                    "content": ""
                },
                {
                    "name": "delete_function",
                    "content": "Delete the named method/procedure/function from the calling object. Removes the entry from\nthe internal table that the object maintains. If the method is shared across more than one\nserver object (see \"sharemethods\"), then the underlying object for it will only be\ndestroyed when the last server object releases it. On error (such as no method by that name\nknown), an error string is returned.\n\nThe deleteprocedure and deletefunction calls are identical, supplied for the sake of\nsymmetry. All calls return the matched object regardless of its underlying type.\n\nlistmethods\nlistprocedures\nlistfunctions\nThis returns a list of the names of methods and procedures the server current has published.\nNote that the returned values are not the method objects, but rather the names by which they\nare externally known. The \"hidden\" status of a method is not consulted when this list is\ncreated; all methods and procedures known are listed. The list is not sorted in any specific\norder.\n\nThe listprocedures and listfunctions calls are provided for symmetry. All calls list all\npublished routines on the calling server object, regardless of underlying type.\n"
                },
                {
                    "name": "xpl_path",
                    "content": "Get and/or set the object-specific search path for \"*.xpl\" files (files that specify\nmethods) that are specified in calls to addmethod, above. If a list reference is passed, it\nis installed as the new path (each element of the list being one directory name to search).\nRegardless of argument, the current path is returned as a list reference. When a file is\npassed to addmethod, the elements of this path are searched first, in order, before the\ninstallation directory or the current working directory are searched.\n"
                },
                {
                    "name": "get_method",
                    "content": ""
                },
                {
                    "name": "get_procedure",
                    "content": ""
                },
                {
                    "name": "get_function",
                    "content": "Returns a reference to an object of the class RPC::XML::Method, RPC::XML::Function or\nRPC::XML::Procedure, which is the current binding for the published method NAME. If there is\nno such method known to the server, then \"undef\" is returned. Note that this is a referent\nto the object as stored on the server object itself, and thus changes to it could affect the\nbehavior of the server.\n\nThe getprocedure and getfunction calls are provided for symmetry. All will return the same\nobject for NAME, regardless of the underlying type.\n"
                },
                {
                    "name": "server_loop",
                    "content": "Enters the connection-accept loop, which generally does not return. This is the\n\"accept()\"-based loop of HTTP::Daemon if the object was created with an instance of that\nclass as a part. Otherwise, this enters the run-loop of the Net::Server class. It listens\nfor requests, and marshalls them out via the \"dispatch\" method described below. It answers\nHTTP-HEAD requests immediately (without counting them on the server statistics) and\nefficiently by using a cached HTTP::Response object.\n\nBecause infinite loops requiring a \"HUP\" or \"KILL\" signal to terminate are generally in poor\ntaste, the HTTP::Daemon side of this sets up a localized signal handler which causes an exit\nwhen triggered. By default, this is attached to the \"INT\" signal. If the Net::Server module\nis being used instead, it provides its own signal management.\n\nThe arguments, if passed, are interpreted as a hash of key/value options (not a hash\nreference, please note). For HTTP::Daemon, only one is recognized:\n\nsignal\nIf passed, should be the traditional name for the signal that should be bound to the\nexit function. If desired, a reference to an array of signal names may be passed, in\nwhich case all signals will be given the same handler. The user is responsible for not\npassing the name of a non-existent signal, or one that cannot be caught. If the value of\nthis argument is 0 (a \"false\" value) or the string \"NONE\", then the signal handler will\n*not* be installed, and the loop may only be broken out of by killing the running\nprocess (unless other arrangements are made within the application).\n\nThe options that Net::Server responds to are detailed in the manual pages for that package.\nAll options passed to \"serverloop\" in this situation are passed unaltered to the \"run()\"\nmethod in Net::Server.\n"
                },
                {
                    "name": "dispatch",
                    "content": "This is the server method that actually manages the marshalling of an incoming request into\nan invocation of a Perl subroutine. The parameter passed in may be one of: a scalar\ncontaining the full XML text of the request, a scalar reference to such a string, or a\npre-constructed RPC::XML::request object. Unless an object is passed, the text is parsed\nwith any errors triggering an early exit. Once the object representation of the request is\non hand, the parameter data is extracted, as is the method name itself. The call is sent\nalong to the appropriate subroutine, and the results are collated into an object of the\nRPC::XML::response class, which is returned. Any non-reference return value should be\npresumed to be an error string.\n\nThe dispatched method may communicate error in several ways. First, any non-reference return\nvalue is presumed to be an error string, and is encoded and returned as an RPC::XML::fault\nresponse. The method is run under an \"eval()\", so errors conveyed by $@ are similarly\nencoded and returned. As a special case, a method may explicitly \"die()\" with a fault\nresponse, which is passed on unmodified.\n"
                },
                {
                    "name": "add_default_methods",
                    "content": "This method adds all the default methods (those that are shipped with this extension) to the\ncalling server object. The files are denoted by their \"*.xpl\" extension, and are installed\ninto the same directory as this Server.pm file. The set of default methods are described\nbelow (see \"The Default Methods Provided\").\n\nIf any names are passed as a list of arguments to this call, then only those methods\nspecified are actually loaded. If the \"*.xpl\" extension is absent on any of these names,\nthen it is silently added for testing purposes. Note that the methods shipped with this\npackage have file names without the leading \"status.\" part of the method name. If the very\nfirst element of the list of arguments is \"except\" (or \"-except\"), then the rest of the list\nis treated as a set of names to *not* load, while all others do get read. The\nApache::RPC::Server module uses this to prevent the loading of the default \"system.status\"\nmethod while still loading all the rest of the defaults. (It then provides a more\nApache-centric status method.)\n\nNote that there are no symmetric calls in this case. The provided API is implemented as\nmethods, and thus only this interface is provided.\n"
                },
                {
                    "name": "add_methods_in_dir",
                    "content": ""
                },
                {
                    "name": "add_procedures_in_dir",
                    "content": ""
                },
                {
                    "name": "add_functions_in_dir",
                    "content": "This is exactly like adddefaultmethods above, save that the caller specifies which\ndirectory to scan for \"*.xpl\" files. In fact, the adddefaultmethods routine simply calls\nthis routine with the installation directory as the first argument. The definition of the\nadditional arguments is the same as above.\n\naddproceduresindir and addfunctionsindir are provided for symmetry.\n"
                },
                {
                    "name": "share_methods",
                    "content": ""
                },
                {
                    "name": "share_procedures",
                    "content": ""
                },
                {
                    "name": "share_functions",
                    "content": "The calling server object shares the methods/procedures/functions listed in NAMES with the\nsource-server passed as the first object. The source must derive from this package in order\nfor this operation to be permitted. At least one method must be specified, and all are\nspecified by name (not by object reference). Both objects will reference the same exact\nRPC::XML::Procedure (or derivative thereof) object in this case, meaning that\ncall-statistics and the like will reflect the combined data. If one or more of the passed\nnames are not present on the source server, an error message is returned and none are copied\nto the calling object.\n\nAlternately, one or more of the name parameters passed to this call may be\nregular-expression objects (the result of the qr operator). Any of these detected are\napplied against the list of all available methods known to the source server. All matching\nones are inserted into the list (the list is pared for redundancies in any case). This\nallows for easier addition of whole classes such as those in the \"system.*\" name space (via\n\"qr/^system[.]/\"), for example. There is no substring matching provided. Names listed in the\nparameters to this routine must be either complete strings or regular expressions.\n\nThe shareprocedures and sharefunctions calls are provided for symmetry.\n"
                },
                {
                    "name": "copy_methods",
                    "content": ""
                },
                {
                    "name": "copy_procedures",
                    "content": ""
                },
                {
                    "name": "copy_functions",
                    "content": "These behave like the methods share* above, with the exception that the calling object is\ngiven a clone of each method, rather than referencing the same exact method as the source\nserver. The code reference part of the method is shared between the two, but all other data\nare copied (including a fresh copy of any list references used) into a completely new\nRPC::XML::Procedure (or derivative) object, using the \"clone()\" method from that class.\nThus, while the calling object has the same methods available, and is re-using existing code\nin the Perl runtime, the method objects (and hence the statistics and such) are kept\nseparate. As with the above, an error is flagged if one or more are not found.\n\nThis routine also accepts regular-expression objects with the same behavior and limitations.\nAgain, copyprocedures and copyfunctions are provided for symmetry.\n"
                },
                {
                    "name": "Specifying Server-Side Remote Procedures",
                    "content": "Specifying the methods themselves can be a tricky undertaking. Some packages (in other\nlanguages) delegate a specific class to handling incoming requests. This works well, but it can\nlead to routines not intended for public availability to in fact be available. There are also\nissues around the access that the methods would then have to other resources within the same\nrunning system.\n\nThe approach taken by RPC::XML::Server (and the Apache::RPC::Server subclass of it) require that\nremote procedures be explicitly published in one of the several ways provided. Procedures may be\nadded directly within code by using addprocedure/addmethod/addfunction as described above,\nwith full data provided for the code reference, signature list, etc. The add* technique can\nalso be used with a file that conforms to a specific XML-based format (detailed in the manual\npage for the RPC::XML::Procedure class, see RPC::XML::Procedure). Entire directories of files\nmay be added using addmethodsindir, which merely reads the given directory for files that\nappear to be method definitions.\n"
                },
                {
                    "name": "The Three Types of Procedures",
                    "content": "There are three types of procedures that RPC::XML::Server marshalls calls to. All are provided\nby the RPC::XML::Procedure module. You should not need to load or reference this module\ndirectly, as loading RPC::XML::Server (or a derivative) makes it available. The three types are:\n\nMethods (RPC::XML::Method)\nCode that is considered a \"method\" by the server is called as though it were, in fact, a\nmethod in that class. The first argument in the list is the server object itself, with the\narguments to the call making up the rest of the list. The server checks the signature of the\nmethod against the arguments list before the call is made. See below (\"How Procedures Are\nCalled\") for more on the invocation of code as methods.\n\nProcedures (RPC::XML::Procedure)\nCode that is considered a \"procedure\" by the server is called like a normal (non-method)\nsubroutine call. The server object is not injected into the arguments list. The signature of\nthe procedure is checked again the list of arguments before the call is made, as with\nmethods.\n\nFunctions (RPC::XML::Function)\nLastly, code that is considered a \"function\" is the simplest of the three: it does not have\nthe server object injected into the arguments list, and no check of signatures is done\nbefore the call is made. It is the responsibility of the function to properly understand the\narguments list, and to return a value that the caller will understand.\n\nThere is (currently) no version that is called like a method but ignores signatures like a\nfunction.\n"
                },
                {
                    "name": "How Procedures Are Called",
                    "content": "When a routine is called via the server dispatcher, it is called with the arguments that the\nclient request passed. Depending on whether the routine is considered a \"function\", a\n\"procedure\" or a \"method\", there may be an extra argument at the head of the list. The extra\nargument is present when the routine being dispatched is part of a RPC::XML::Method object. The\nextra argument is a reference to a RPC::XML::Server object (or a subclass thereof). This is\nderived from a hash reference, and will include these special keys:\n\nmethodname\nThis is the name by which the method was called in the client. Most of the time, this will\nprobably be consistent for all calls to the server-side method. But it does not have to be,\nhence the passing of the value.\n\nsignature\nThis is the signature that was used, when dispatching. Perl has a liberal view of lists and\nscalars, so it is not always clear what arguments the client specifically has in mind when\ncalling the method. The signature is an array reference containing one or more datatypes,\neach a simple string. The first of the datatypes specifies the expected return type. The\nremainder (if any) refer to the arguments themselves.\n\npeerfamily\nThis is the address family, \"AFINET\" or \"AFINET6\", of a network address of the client that\nhas connected and made the current request. It is required for unpacking \"peeraddr\"\nproperly.\n\npeeraddr\nThis is the address part of a packed SOCKADDRIN or SOCKADDRIN6 structure, as returned by\n\"packsockaddrin\" in Socket or \"packsockaddrin6\" in Socket, which contains the address of\nthe client that has connected and made the current request. This is provided \"raw\" in case\nyou need it. While you could re-create it from \"peerhost\", it is readily available in both\nthis server environment and the Apache::RPC::Server environment and thus included for\nconvenience. Apply \"inetntop\" in Socket to \"peerfamily\" and this value to obtain textual\nrepresentation of the address.\n\npeerhost\nThis is the address of the remote (client) end of the socket, in \"x.x.x.x\" (dotted-quad)\nformat. If you wish to look up the clients host-name, you can use this to do so or utilize\nthe encoded structure above directly.\n\npeerport\nThis is the port of the remote (client) end of the socket, taken from the SOCKADDRIN\nstructure.\n\nrequest\nThe HTTP::Request object for this request. Can be used to read HTTP headers sent by the\nclient (\"X-Forwarded-For\" for your access checks, for example).\n\nThose keys should only be referenced within method code itself, as they are not set on the\nserver object outside of that context.\n\nNote that by passing the server object reference first, method-classed routines are essentially\nexpected to behave as actual methods of the server class, as opposed to ordinary functions. Of\ncourse, they can also discard the initial argument completely.\n\nThe routines should not make (excessive) use of global variables, for obvious reasons. When the\nroutines are loaded from XPL files, the code is created as a closure that forces execution in\nthe RPC::XML::Procedure package (unless the XPL specifies a namespace, see RPC::XML::Procedure).\nIf the code element of a procedure/method is passed in as a direct code reference by one of the\nother syntaxes allowed by the constructor, the package may well be different. Thus, routines\nshould strive to be as localized as possible, independent of specific namespaces. If a group of\nroutines are expected to work in close concert, each should explicitly set the namespace with a\n\"package\" declaration as the first statement within the routines themselves.\n"
                },
                {
                    "name": "The Default Methods Provided",
                    "content": "The following methods are provided with this package, and are the ones installed on\nnewly-created server objects unless told not to. These are identified by their published names,\nas they are compiled internally as anonymous subroutines and thus cannot be called directly:\n\nsystem.identity\nReturns a string value identifying the server name, version, and possibly a capability\nlevel. Takes no arguments.\n\nsystem.introspection\nReturns a series of struct objects that give overview documentation of one or more of the\npublished methods. It may be called with a string identifying a single routine, in which\ncase the return value is a struct. It may be called with an array of string values, in which\ncase an array of struct values, one per element in, is returned. Lastly, it may be called\nwith no input parameters, in which case all published routines are documented. Note that\nroutines may be configured to be hidden from such introspection queries.\n\nsystem.listMethods\nReturns a list of the published methods or a subset of them as an array of string values. If\ncalled with no parameters, returns all (non-hidden) method names. If called with a single\nstring pattern, returns only those names that contain the string as a substring of their\nname (case-sensitive, and this is *not* a regular expression evaluation).\n\nsystem.methodHelp\nTakes either a single method name as a string, or a series of them as an array of string.\nThe return value is the help text for the method, as either a string or array of string\nvalue. If the method(s) have no help text, the string will be null.\n\nsystem.methodSignature\nAs above, but returns the signatures that the method accepts, as array of string\nrepresentations. If only one method is requests via a string parameter, then the return\nvalue is the corresponding array. If the parameter in is an array, then the returned value\nwill be an array of array of string.\n\nsystem.multicall\nThis is a simple implementation of composite function calls in a single request. It takes an\narray of struct values. Each struct has at least a \"methodName\" member, which provides the\nname of the method to call. If there is also a \"params\" member, it refers to an array of the\nparameters that should be passed to the call.\n\nsystem.status\nTakes no arguments and returns a struct containing a number of system status values\nincluding (but not limited to) the current time on the server, the time the server was\nstarted (both of these are returned in both ISO 8601 and UNIX-style integer formats), number\nof requests dispatched, and some identifying information (hostname, port, etc.).\n\nIn addition, each of these has an accompanying help file in the \"methods\" sub-directory of the\ndistribution.\n\nThese methods are installed as \"*.xpl\" files, which are generated from files in the \"methods\"\ndirectory of the distribution using the makemethod tool (see makemethod). The files there\nprovide the Perl code that implements these, their help files and other information.\n"
                },
                {
                    "name": "Content Compression",
                    "content": "The RPC::XML::Server class now supports compressed messages, both incoming and outgoing. If a\nclient indicates that it can understand compressed content, the server will use the\nCompress::Zlib (available from CPAN) module, if available, to compress any outgoing messages\nabove a certain threshold in size (the default threshold is set to 4096 bytes). The following\nmethods are all related to the compression support within the server class:\n\ncompress\nReturns a false value if compression is not available to the server object. This is based on\nthe availability of the Compress::Zlib module at start-up time, and cannot be changed.\n"
                },
                {
                    "name": "compress_thresh",
                    "content": "Return or set the compression threshold value. Messages smaller than this size in bytes will\nnot be compressed, even when compression is available, to save on CPU resources. If a value\nis passed, it becomes the new limit and the old value is returned.\n"
                },
                {
                    "name": "Spooling Large Messages",
                    "content": "If the server anticipates handling large out-bound messages (for example, if the hosted code\nreturns large Base64 values pre-encoded from file handles), the \"messagefilethresh\" and\n\"messagetempdir\" settings may be used in a manner similar to RPC::XML::Client. Specifically,\nthe threshold is used to determine when a message should be spooled to a filehandle rather than\nmade into an in-memory string (the RPC::XML::base64 type can use a filehandle, thus eliminating\nthe need for the data to ever be completely in memory). An anonymous temporary file is used for\nthese operations.\n\nNote that the message size is checked before compression is applied, since the size of the\ncompressed output cannot be known until the full message is examined. It is possible that a\nmessage will be spooled even if its compressed size is below the threshold, if the uncompressed\nsize exceeds the threshold.\n\nmessagefilethresh\nmessagetempdir\nThese methods may be used to retrieve or alter the values of the given keys as defined\nearlier for the \"new\" method.\n"
                },
                {
                    "name": "Server Faults",
                    "content": "Previous versions of this library had a very loosely-organized set of fault codes that a server\nmight return in certain (non-fatal) error circumstances. This has been replaced by a more\nconfigurable, adjustable system to allow users to better integrate the server-defined faults\nwith any that their application may produce. It also allows for the definition of additional\nfault types so that the same mechanism for formatting the pre-defined faults can be used within\nsub-classes and user applications.\n\nThe server method serverfault is used to generate RPC::XML::fault objects for these situations.\nIt takes one or two arguments, the first being the name of the type of fault to create and the\nsecond being the specific message. If a fault is defined with a static message, the second\nargument may be skipped (and will be ignored if passed).\n\nIn addition to defining their own faults, a user may override the definition of any of the\nserver's pre-defined faults.\n\nDefining faults\nThe user may define their own faults using the \"faulttable\" argument to the constructor of the\nserver class being instantiated. They may also override any of the pre-defined faults (detailed\nin the next section) by providing a new definition for the name.\n\nThe value of the \"faulttable\" argument is a hash reference whose keys are the names of the\nfaults and whose values are one of two types:\n\nAn integer\nIf the value for the key is a scalar, it is assumed to be an integer and will be used as the\nfault code. When the fault is created, the message argument (the second parameter) will be\nused verbatim as the fault message.\n\nA 2-element list reference\nIf the value is a list reference, it is assumed to have two elements: the first is the\ninteger fault code to use, and the second is a message \"template\" string to use as the fault\nmessage. If the string contains the sequence %s, this will be replaced with the message\nargument (the second parameter) passed to serverfault. If that sequence is not in the\nstring, then the fault message is considered static and the message argument is ignored.\n\nAn example of defining faults:\n\nmy $server = RPC::XML::Server->new(\n...\nfaulttable => {\nlimitexceeded => [ 500 => 'Call limit exceeded' ],\naccessdenied  => [ 600 => 'Access denied: %s' ],\nserviceclosed => 700\n},\n...\n);\n\nIn this example, the fault-type \"limitexceeded\" is defined as having a fault code of 500 and a\nstatic message of \"Call limit exceeded\". The next fault defined is \"accessdenied\", which has a\ncode of 600 and message that starts with \"Access denied:\" and incorporates whatever message was\npassed in to the fault creation. The last example defines a fault called \"serviceclosed\" that\nhas a code of 700 and uses any passed-in message unaltered.\n\nServer-defined faults\nThe RPC::XML::Server class defines the following faults and uses them internally. You can\noverride the codes and messages for these by including them in the table passed as a\n\"faulttable\" argument. The faults fall into three groups:\n\nRequest Initialization\nFaults in this group stem from the initialization of the request and the parsing of the XML.\nThe codes for this group fall in the range 100-199.\n\nMethod Resolution\nThis group covers problems with mapping the request to a known method or function on the\nserver. These codes will be in the range 200-299.\n\nExecution\nLastly, these faults are for problems in actually executing the requested code. Their codes\nare in the range 300-399.\n\nThe faults, and the phases they apply to, are:\n\nbadxml (Request Initialization)\nThis fault is sent back to the client when the XML of the request did not parse as a valid\nXML-RPC request.\n\nThe code is 100, and the message is of the form, \"XML parse error: %s\". The specific error\nfrom the XML parser is included in the message.\n\nbadmethod (Method Resolution)\nThis fault is sent when the requested method is unknown to the server. No method has been\nconfigured on the server by that name.\n\nThe code is 200, and the message is of the form, \"Method lookup error: %s\". The name of the\nmethod and other information is included in the message.\n\nbadsignature (Method Resolution)\nIf a method is known on the server, but there is no signature that matches the sequence of\narguments passed, this fault is returned. This fault cannot be triggered by server-side code\nconfigured via RPC::XML::Function, as no signature-checking is done for those.\n\nThe code is 201, and the message is of the form, \"Method signature error: %s\". The name of\nthe method and the signature of the arguments is included in the message.\n\nexecerror (Execution)\nThis fault relates back to the client any exception thrown by the remote code during\nexecution. If the invoked code returned their error in the form of a RPC::XML::fault object,\nthat fault is returned instead. Otherwise, the value of $@ is used in the message of the\nfault that gets generated.\n\nThe code is 300, and the message is of the form, \"Code execution error: %s\". The actual text\nof the exception thrown is included in the message.\n\nThere is one special server-fault whose code and message cannot be overridden. If a call is made\nto serverfault for an unknown type of fault, the returned object will have a code of -1 and a\nmessage stating that the fault-type is unknown. The message will include both the requested\ntype-name and any message (if any) that was passed in.\n\nAdjusting the server-defined codes\nIf you just want to \"move\" the range of codes that the server uses out of the way of your\napplication's own faults, this can be done with the \"faultcodebase\" parameter when\nconstructing the server object. The value of the parameter must be an integer, and it is added\nto the value of all existing fault codes. For example, a value of 10000 would make the code for\nthe \"badxml\" fault be 10100, the code for \"badmethod\" be 10200, etc.\n\nThis is applied before any user-defined faults are merged in, so their code values will not be\naffected by this value.\n"
                }
            ]
        },
        "DIAGNOSTICS": {
            "content": "Unless explicitly stated otherwise, all methods return some type of reference on success, or an\nerror string on failure. Non-reference return values should always be interpreted as errors\nunless otherwise noted.\n",
            "subsections": []
        },
        "BUGS": {
            "content": "Please report any bugs or feature requests to \"bug-rpc-xml at rt.cpan.org\", or through the web\ninterface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be notified, and\nthen you'll automatically be notified of progress on your bug as I make changes.\n",
            "subsections": []
        },
        "SUPPORT": {
            "content": "*   RT: CPAN's request tracker\n\n<http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>\n\n*   AnnoCPAN: Annotated CPAN documentation\n\n<http://annocpan.org/dist/RPC-XML>\n\n*   CPAN Ratings\n\n<http://cpanratings.perl.org/d/RPC-XML>\n\n*   Search CPAN\n\n<http://search.cpan.org/dist/RPC-XML>\n\n*   MetaCPAN\n\n<https://metacpan.org/release/RPC-XML>\n\n*   Source code on GitHub\n\n<http://github.com/rjray/rpc-xml>\n",
            "subsections": []
        },
        "LICENSE AND COPYRIGHT": {
            "content": "This file and the code within are copyright (c) 2011 by Randy J. Ray.\n\nCopying and distribution are permitted under the terms of the Artistic License 2.0\n(<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the GNU LGPL 2.1\n(<http://www.opensource.org/licenses/lgpl-2.1.php>).\n",
            "subsections": []
        },
        "CREDITS": {
            "content": "The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software, Inc. See\n<http://www.xmlrpc.com> for more information about the XML-RPC specification.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "RPC::XML, RPC::XML::Client, RPC::XML::ParserFactory\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Randy J. Ray \"<rjray@blackperl.com>\"\n",
            "subsections": []
        }
    },
    "summary": "RPC::XML::Server - A server base-class for XML-RPC",
    "flags": [],
    "examples": [],
    "see_also": []
}