{ "mode": "perldoc", "parameter": "RPC::XML::Procedure", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/RPC%3A%3AXML%3A%3AProcedure/json", "generated": "2026-07-05T11:17:41Z", "synopsis": "require RPC::XML::Procedure;\n...\n$procedure = RPC::XML::Procedure->new({ name => 'system.identity',\ncode => sub { ... },\nsignature => [ 'string' ] });\n$method = RPC::XML::Method->new('/path/to/status.xpl');\n$function = RPC::XML::Function->new(name => 'add',\ncode => sub { ... });", "sections": { "NAME": { "content": "RPC::XML::Procedure - Object encapsulation of server-side RPC procedures\n", "subsections": [] }, "SYNOPSIS": { "content": "require RPC::XML::Procedure;\n\n...\n$procedure = RPC::XML::Procedure->new({ name => 'system.identity',\ncode => sub { ... },\nsignature => [ 'string' ] });\n$method = RPC::XML::Method->new('/path/to/status.xpl');\n$function = RPC::XML::Function->new(name => 'add',\ncode => sub { ... });\n", "subsections": [] }, "DESCRIPTION": { "content": "The RPC::XML::Procedure package is designed primarily for behind-the-scenes use by the\nRPC::XML::Server class and any subclasses of it. It is documented here in case a project chooses\nto sub-class it for their purposes (which would require setting the \"methodclass\" attribute\nwhen creating server objects, see RPC::XML::Server).\n\nThis package grew out of the increasing need to abstract the operations that related to the\nmethods a given server instance was providing. Previously, methods were passed around simply as\nhash references. It was a small step then to move them into a package and allow for operations\ndirectly on the objects themselves. In the spirit of the original hashes, all the key data is\nkept in clear, intuitive hash keys (rather than obfuscated as the other classes do). Thus it is\nimportant to be clear on the interface here before sub-classing this package.\n", "subsections": [] }, "CLASSES": { "content": "This module provides three classes, representing the three types of procedures that servers can\nuse:\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", "subsections": [] }, "SUBROUTINES/METHODS": { "content": "The following methods are provided by this class:\n", "subsections": [ { "name": "new", "content": "Creates a new object of the class, and returns a reference to it. The arguments to the\nconstructor are variable in nature, depending on the type:\n\nFILE If there is exactly on argument that is not a reference, it is assumed to be a\nfilename from which the method is to be loaded. This is presumed to be in the XPL\nformat described below (see \"XPL File Structure\"). If the file cannot be opened, or\nif once opened cannot be parsed, an error is raised.\n\nHASHREF If there is exactly one argument that is a reference, it is assumed to be a hash\nwith the relevant information on the same keys as the object itself uses. This is\nprimarily to support backwards-compatibility to code written when methods were\nimplemented simply as hash references.\n\nLIST If there is more than one argument in the list, then the list is assumed to be a\nsort of \"ersatz\" hash construct, in that one of the keys (\"signature\") is allowed to\n\"stack\" if it occurs multiple times. Otherwise, any keys that occur multiple times\noverwrite the previous value:\n\nname The name of the method, as it will be presented to clients\n\ncode A reference to a subroutine, or an anonymous subroutine, that will\nreceive calls for the method\n\nsignature Provides one calling-signature for the method, as either a\nspace-separated string of types or a list-reference\n\nhelp The help-text for a method, which is generally used as a part of the\nintrospection interface for a server\n\nversion The version number/string for the method\n\nhidden A boolean (true or false) value indicating whether the method should be\nhidden from introspection and similar listings\n\nNote that all of these correspond to the values that can be changed via the accessor\nmethods detailed later.\n\nIf any error occurs during object creation, an error message is returned in lieu of the\nobject reference.\n\nclone\nCreate a copy of the calling object, and return the new reference. All elements are copied\nover cleanly, except for the code reference stored on the \"code\" hash key. The clone will\npoint to the same code reference as the original. Elements such as \"signature\" are copied,\nso that changes to the clone will not impact the original.\n\nname\nReturns the name by which the server is advertising the method. Unlike the next few\naccessors, this cannot be changed on an object. In order to streamline the management of\nmethods within the server classes, this must persist. However, the other elements may be\nused in the creation of a new object, which may then be added to the server, if the name\nabsolutely must change.\n\nnamespace\nIf the procedure object was created from a file, or if the instantiation included namespace\ninformation, this accessor will return the namespace that the underlying code executes in.\nOtherwise, it returns an empty string. This cannot be altered (even if the code method is\nused to replace the code routine).\n" }, { "name": "code", "content": "Returns or sets the code-reference that will receive calls as marshalled by the server. The\nexisting value is lost, so if it must be preserved, then it should be retrieved prior to the\nnew value being set.\n" }, { "name": "signature", "content": "Return a list reference containing the signatures, or set it. Each element of the list is a\nstring of space-separated types (the first of which is the return type the method produces\nin that calling context). If this is being used to set the signature, then an array\nreference must be passed that contains one or more strings of this nature. Nested list\nreferences are not allowed at this level. If the new signatures would cause a conflict (a\ncase in which the same set of input types are specified for different output types), the old\nset is silently restored.\n" }, { "name": "help", "content": "Returns or sets the help-text for the method. As with code, the previous value is lost.\n" }, { "name": "hidden", "content": "Returns or sets the hidden status of the method. Setting it loses the previous value.\n" }, { "name": "version", "content": "Returns or sets the version string for the method (overwriting as with the other accessors).\n" }, { "name": "add_signature", "content": "Add one or more signatures (which may be a list reference or a string) to the internal\ntables for this method. Duplicate signatures are ignored. If the new signature would cause a\nconflict (a case in which the same set of input types are specified for different output\ntypes), the old set is restored and an error message is returned.\n" }, { "name": "delete_signature", "content": "Deletes the signature or signatures (list reference or string) from the internal tables.\nQuietly ignores any signature that does not exist. If the new signature would cause a\nconflict (a case in which the same set of input types are specified for different output\ntypes), the old set is restored and an error message is returned.\n" }, { "name": "match_signature", "content": "Check that the passed-in signature is known to the method, and if so returns the type that\nthe method should be returning as a result of the call. Returns a zero (0) otherwise. This\ndiffers from other signature operations in that the passed-in signature (which may be a\nlist-reference or a string) *does not include the return type*. This method is provided so\nthat servers may check a list of arguments against type when marshalling an incoming call.\nFor example, a signature of 'int int' would be tested for by calling\n\"$M->matchsignature('int')\" and expecting the return value to be \"int\".\n" }, { "name": "call", "content": "Execute the code that this object encapsulates, using the list of parameters passed in\nPARAMLIST. The SERVER argument should be an object derived from the RPC::XML::Server class.\nFor some types of procedure objects, this becomes the first argument of the parameter list\nto simulate a method call as if it were on the server object itself. The return value should\nbe a data object (possibly a RPC::XML::fault), but may not always be pre-encoded. Errors\ntrapped in $@ are converted to fault objects. This method is generally used in the\n\"dispatch\" method of the server class, where the return value is subsequently wrapped within\na RPC::XML::response object.\n\nreload\nInstruct the object to reload itself from the file it originally was loaded from, assuming\nthat it was loaded from a file to begin with. Returns an error if the method was not\noriginally loaded from a file, or if an error occurs during the reloading operation.\n" }, { "name": "Additional Hash Data", "content": "In addition to the attributes managed by the accessors documented earlier, the following hash\nkeys are also available for use. These are also not strongly protected, and the same care should\nbe taken before altering any of them:\n\nfile\nWhen the method was loaded from a file, this key contains the path to the file used.\n\nnamespace\nIf the code is loaded from a file, this hash key will reflect what namespace the code\nexecutes in. If the file specified a namespace, that is the value you will get (any\noccurrence of \".\" in the specified namespace will have been converted to \"::\"). If no\nexplicit namespace was provided, the namespace of the class you called new from will be\nused. See \"Namespaces\".\n\nmtime\nWhen the method was loaded from a file, this key contains the modification-time of the file,\nas a UNIX-style \"time\" value. This is used to check for changes to the file the code was\noriginally read from.\n\ncalled\nWhen the method is being used by one of the server classes provided in this software suite,\nthis key is incremented each time the server object dispatches a request to the method. This\ncan later be checked to provide some indication of how frequently the method is being\ninvoked.\n\nXPL File Structure\nThis section focuses on the way in which methods are expressed in these files, referred to here\nas \"XPL files\" due to the \"*.xpl\" filename extension (which stands for \"XML Procedure Layout\").\nThis mini-dialect, based on XML, is meant to provide a simple means of specifying method\ndefinitions separate from the code that comprises the application itself. Thus, methods may\ntheoretically be added, removed, debugged or even changed entirely without requiring that the\nserver application itself be rebuilt (or, possibly, without it even being restarted).\n\nThe XML-based file structure\nThe XPL Procedure Layout dialect is a very simple application of XML to the problem of\nexpressing the method in such a way that it could be useful to other packages than this one,\nor useful in other contexts than this one.\n\nThe lightweight DTD for the layout can be summarized as:\n\n\n\n\n\n\n\n\n\n\n\n\n\nThe containing tag is always one of \"\", \"\" or \"\". The\ntags that specify name, signatures and the code itself must always be present. Some optional\ninformation may also be supplied. The \"help\" text, or what an introspection API would expect\nto use to document the method, is also marked as optional. Having some degree of\ndocumentation for all the methods a server provides is a good rule of thumb, however.\n\nThe default methods that this package provides are turned into XPL files by the makemethod\ntool (see makemethod). The final forms of these may serve as examples of what the file\nshould look like.\n\nInformation used only for book-keeping\nSome of the information in the XPL file is only for book-keeping: the version stamp of a\nmethod is never involved in the invocation. The server also keeps track of the last-modified\ntime of the file the method is read from, as well as the full directory path to that file.\nThe \"\" tag is used to identify those methods that should not be exposed to the\noutside world through any sort of introspection/documentation API. They are still available\nand callable, but the client must possess the interface information in order to do so.\n\nThe information crucial to the method\nThe name, signatures and code must be present for obvious reasons. The \"\" tag tells\nthe server what external name this procedure is known by. The \"\" tag, which may\nappear more than once, provides the definition of the interface to the function in terms of\nwhat types and quantity of arguments it will accept, and for a given set of arguments what\nthe type of the returned value is. Lastly is the \"\" tag, without which there is no\nprocedure to remotely call.\n\nWhy the tag allows multiple languages\nNote that the \"\" tag is the only one with an attribute, in this case \"language\". This\nis designed to allow for one XPL file to provide a given method in multiple languages. Why,\none might ask, would there be a need for this?\n\nIt is the hope behind this package that collections of RPC suites may one day be made\navailable as separate entities from this specific software package. Given this hope, it is\nnot unreasonable to suggest that such a suite of code might be implemented in more than one\nlanguage (each of Perl, Python, Ruby and Tcl, for example). Languages which all support the\nmeans by which to take new code and add it to a running process on demand (usually through\nan \"\"eval\"\" keyword or something similar). If the file A.xpl is provided with\nimplementations in all four of the above languages, the name, help text, signature and even\nhidden status would likely be identical. So, why not share the non-language-specific\nelements in the spirit of re-use?\n\nThe \"makemethod\" Utility\nThe utility script \"makemethod\" is provided as a part of this software suite. It allows for the\nautomatic creation of XPL files from either command-line information or from template files. It\nhas a wide variety of features and options, and is out of the scope of this particular manual\npage. The package Makefile.PL features an example of engineering the automatic generation of XPL\nfiles and their delivery as a part of the normal Perl module build process. Using this tool is\nhighly recommended over managing XPL files directly. For the full details, see makemethod.\n" } ] }, "NAMESPACES": { "content": "As default behavior, Perl code that is passed to \"eval\" when a XPL file is loaded gets put into\nthe same namespace as the package used to load the XPL. It is not an issue when you create your\nown RPC::XML::Procedure (or ::Method or ::Function) objects, as the code is already instantiated\ninto a given namespace. This can be important if your code expects to call routines in other\nloaded packages, utilize package-level globals, etc.\n\nTo give developers control over the namespace in XPL code, a new optional tag \"\" was\nadded in the 0.65 release. If this tag is present in the XPL being read, it defines the\nnamespace that the \"\" block is evaluated in.\n\nThe value of the namespace tag is a string providing the namespace in either the Perl-style of\nhierarchy parts separated by \"::\", or the style used by Java, Perl6, etc., in which the parts\nare separated by \".\". The latter form is converted to Perl style for the evaluation of the code.\nIf there is no namespace declaration in a XPL file, the namespace of the class that loads the\nXPL is used.\n", "subsections": [] }, "DIAGNOSTICS": { "content": "Unless otherwise noted in the individual documentation sections, all methods return the object\nreference on success, or a (non-reference) text string containing the error message upon\nfailure.\n", "subsections": [] }, "CAVEATS": { "content": "Moving the method management to a separate class adds a good deal of overhead to the general\nsystem. The trade-off in reduced complexity and added maintainability should offset this.\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 . 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\n\n* AnnoCPAN: Annotated CPAN documentation\n\n\n\n* CPAN Ratings\n\n\n\n* Search CPAN\n\n\n\n* MetaCPAN\n\n\n\n* Source code on GitHub\n\n\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() or the GNU LGPL 2.1\n().\n", "subsections": [] }, "CREDITS": { "content": "The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software, Inc. See\n for more information about the XML-RPC specification.\n", "subsections": [] }, "SEE ALSO": { "content": "RPC::XML::Server, makemethod\n", "subsections": [] }, "AUTHOR": { "content": "Randy J. Ray \"\"\n", "subsections": [] } }, "summary": "RPC::XML::Procedure - Object encapsulation of server-side RPC procedures", "flags": [], "examples": [], "see_also": [] }