1RPC::XML::Procedure(3)User Contributed Perl DocumentationRPC::XML::Procedure(3)
2
3
4

NAME

6       RPC::XML::Procedure - Object encapsulation of server-side RPC
7       procedures
8

SYNOPSIS

10           require RPC::XML::Procedure;
11
12           ...
13           $procedure = RPC::XML::Procedure->new({ name => 'system.identity',
14                                                   code => sub { ... },
15                                                   signature => [ 'string' ] });
16           $method    = RPC::XML::Method->new('/path/to/status.xpl');
17           $function  = RPC::XML::Function->new(name => 'add',
18                                                code => sub { ... });
19

DESCRIPTION

21       The RPC::XML::Procedure package is designed primarily for behind-the-
22       scenes use by the RPC::XML::Server class and any subclasses of it. It
23       is documented here in case a project chooses to sub-class it for their
24       purposes (which would require setting the "method_class" attribute when
25       creating server objects, see RPC::XML::Server).
26
27       This package grew out of the increasing need to abstract the operations
28       that related to the methods a given server instance was providing.
29       Previously, methods were passed around simply as hash references. It
30       was a small step then to move them into a package and allow for
31       operations directly on the objects themselves. In the spirit of the
32       original hashes, all the key data is kept in clear, intuitive hash keys
33       (rather than obfuscated as the other classes do). Thus it is important
34       to be clear on the interface here before sub-classing this package.
35

CLASSES

37       This module provides three classes, representing the three types of
38       procedures that servers can use:
39
40       Methods (RPC::XML::Method)
41           Code that is considered a "method" by the server is called as
42           though it were, in fact, a method in that class. The first argument
43           in the list is the server object itself, with the arguments to the
44           call making up the rest of the list.  The server checks the
45           signature of the method against the arguments list before the call
46           is made. See below ("How Procedures Are Called") for more on the
47           invocation of code as methods.
48
49       Procedures (RPC::XML::Procedure)
50           Code that is considered a "procedure" by the server is called like
51           a normal (non-method) subroutine call. The server object is not
52           injected into the arguments list. The signature of the procedure is
53           checked again the list of arguments before the call is made, as
54           with methods.
55
56       Functions (RPC::XML::Function)
57           Lastly, code that is considered a "function" is the simplest of the
58           three: it does not have the server object injected into the
59           arguments list, and no check of signatures is done before the call
60           is made. It is the responsibility of the function to properly
61           understand the arguments list, and to return a value that the
62           caller will understand.
63
64       There is (currently) no version that is called like a method but
65       ignores signatures like a function.
66

SUBROUTINES/METHODS

68       The following methods are provided by this class:
69
70       new(FILE|HASHREF|LIST)
71           Creates a new object of the class, and returns a reference to it.
72           The arguments to the constructor are variable in nature, depending
73           on the type:
74
75           FILE    If there is exactly on argument that is not a reference, it
76                   is assumed to be a filename from which the method is to be
77                   loaded. This is presumed to be in the XPL format described
78                   below (see "XPL File Structure"). If the file cannot be
79                   opened, or if once opened cannot be parsed, an error is
80                   raised.
81
82           HASHREF If there is exactly one argument that is a reference, it is
83                   assumed to be a hash with the relevant information on the
84                   same keys as the object itself uses. This is primarily to
85                   support backwards-compatibility to code written when
86                   methods were implemented simply as hash references.
87
88           LIST    If there is more than one argument in the list, then the
89                   list is assumed to be a sort of "ersatz" hash construct, in
90                   that one of the keys ("signature") is allowed to "stack" if
91                   it occurs multiple times. Otherwise, any keys that occur
92                   multiple times overwrite the previous value:
93
94                   name        The name of the method, as it will be presented
95                               to clients
96
97                   code        A reference to a subroutine, or an anonymous
98                               subroutine, that will receive calls for the
99                               method
100
101                   signature   Provides one calling-signature for the method,
102                               as either a space-separated string of types or
103                               a list-reference
104
105                   help        The help-text for a method, which is generally
106                               used as a part of the introspection interface
107                               for a server
108
109                   version     The version number/string for the method
110
111                   hidden      A boolean (true or false) value indicating
112                               whether the method should be hidden from
113                               introspection and similar listings
114
115                   Note that all of these correspond to the values that can be
116                   changed via the accessor methods detailed later.
117
118           If any error occurs during object creation, an error message is
119           returned in lieu of the object reference.
120
121       clone
122           Create a copy of the calling object, and return the new reference.
123           All elements are copied over cleanly, except for the code reference
124           stored on the "code" hash key. The clone will point to the same
125           code reference as the original. Elements such as "signature" are
126           copied, so that changes to the clone will not impact the original.
127
128       name
129           Returns the name by which the server is advertising the method.
130           Unlike the next few accessors, this cannot be changed on an object.
131           In order to streamline the management of methods within the server
132           classes, this must persist. However, the other elements may be used
133           in the creation of a new object, which may then be added to the
134           server, if the name absolutely must change.
135
136       namespace
137           If the procedure object was created from a file, or if the
138           instantiation included namespace information, this accessor will
139           return the namespace that the underlying code executes in.
140           Otherwise, it returns an empty string. This cannot be altered (even
141           if the code method is used to replace the code routine).
142
143       code([NEW])
144           Returns or sets the code-reference that will receive calls as
145           marshalled by the server. The existing value is lost, so if it must
146           be preserved, then it should be retrieved prior to the new value
147           being set.
148
149       signature([NEW])
150           Return a list reference containing the signatures, or set it. Each
151           element of the list is a string of space-separated types (the first
152           of which is the return type the method produces in that calling
153           context). If this is being used to set the signature, then an array
154           reference must be passed that contains one or more strings of this
155           nature. Nested list references are not allowed at this level. If
156           the new signatures would cause a conflict (a case in which the same
157           set of input types are specified for different output types), the
158           old set is silently restored.
159
160       help([NEW])
161           Returns or sets the help-text for the method. As with code, the
162           previous value is lost.
163
164       hidden([NEW])
165           Returns or sets the hidden status of the method. Setting it loses
166           the previous value.
167
168       version([NEW])
169           Returns or sets the version string for the method (overwriting as
170           with the other accessors).
171
172       add_signature(LIST)
173           Add one or more signatures (which may be a list reference or a
174           string) to the internal tables for this method. Duplicate
175           signatures are ignored. If the new signature would cause a conflict
176           (a case in which the same set of input types are specified for
177           different output types), the old set is restored and an error
178           message is returned.
179
180       delete_signature(LIST)
181           Deletes the signature or signatures (list reference or string) from
182           the internal tables. Quietly ignores any signature that does not
183           exist. If the new signature would cause a conflict (a case in which
184           the same set of input types are specified for different output
185           types), the old set is restored and an error message is returned.
186
187       match_signature(SIGNATURE)
188           Check that the passed-in signature is known to the method, and if
189           so returns the type that the method should be returning as a result
190           of the call. Returns a zero (0) otherwise. This differs from other
191           signature operations in that the passed-in signature (which may be
192           a list-reference or a string) does not include the return type.
193           This method is provided so that servers may check a list of
194           arguments against type when marshalling an incoming call. For
195           example, a signature of 'int int' would be tested for by calling
196           "$M->match_signature('int')" and expecting the return value to be
197           "int".
198
199       call(SERVER, PARAMLIST)
200           Execute the code that this object encapsulates, using the list of
201           parameters passed in PARAMLIST. The SERVER argument should be an
202           object derived from the RPC::XML::Server class. For some types of
203           procedure objects, this becomes the first argument of the parameter
204           list to simulate a method call as if it were on the server object
205           itself. The return value should be a data object (possibly a
206           RPC::XML::fault), but may not always be pre-encoded. Errors trapped
207           in $@ are converted to fault objects. This method is generally used
208           in the "dispatch" method of the server class, where the return
209           value is subsequently wrapped within a RPC::XML::response object.
210
211       reload
212           Instruct the object to reload itself from the file it originally
213           was loaded from, assuming that it was loaded from a file to begin
214           with. Returns an error if the method was not originally loaded from
215           a file, or if an error occurs during the reloading operation.
216
217   Additional Hash Data
218       In addition to the attributes managed by the accessors documented
219       earlier, the following hash keys are also available for use. These are
220       also not strongly protected, and the same care should be taken before
221       altering any of them:
222
223       file
224           When the method was loaded from a file, this key contains the path
225           to the file used.
226
227       namespace
228           If the code is loaded from a file, this hash key will reflect what
229           namespace the code executes in. If the file specified a namespace,
230           that is the value you will get (any occurrence of "." in the
231           specified namespace will have been converted to "::"). If no
232           explicit namespace was provided, the namespace of the class you
233           called new from will be used. See "Namespaces".
234
235       mtime
236           When the method was loaded from a file, this key contains the
237           modification-time of the file, as a UNIX-style "time" value. This
238           is used to check for changes to the file the code was originally
239           read from.
240
241       called
242           When the method is being used by one of the server classes provided
243           in this software suite, this key is incremented each time the
244           server object dispatches a request to the method. This can later be
245           checked to provide some indication of how frequently the method is
246           being invoked.
247
248   XPL File Structure
249       This section focuses on the way in which methods are expressed in these
250       files, referred to here as "XPL files" due to the "*.xpl" filename
251       extension (which stands for "XML Procedure Layout"). This mini-dialect,
252       based on XML, is meant to provide a simple means of specifying method
253       definitions separate from the code that comprises the application
254       itself. Thus, methods may theoretically be added, removed, debugged or
255       even changed entirely without requiring that the server application
256       itself be rebuilt (or, possibly, without it even being restarted).
257
258       The XML-based file structure
259           The XPL Procedure Layout dialect is a very simple application of
260           XML to the problem of expressing the method in such a way that it
261           could be useful to other packages than this one, or useful in other
262           contexts than this one.
263
264           The lightweight DTD for the layout can be summarized as:
265
266               <!ELEMENT  proceduredef  (name, namespace?, version?, hidden?,
267                                         signature+, help?, code)>
268               <!ELEMENT  methoddef     (name, namespace?, version?, hidden?,
269                                         signature+, help?, code)>
270               <!ELEMENT  functiondef   (name, namespace?, version?, hidden?,
271                                         signature+, help?, code)>
272               <!ELEMENT  name       (#PCDATA)>
273               <!ELEMENT  namespace  (#PCDATA)>
274               <!ELEMENT  version    (#PCDATA)>
275               <!ELEMENT  hidden     EMPTY>
276               <!ELEMENT  signature  (#PCDATA)>
277               <!ELEMENT  help       (#PCDATA)>
278               <!ELEMENT  code       (#PCDATA)>
279               <!ATTLIST  code       language (#PCDATA)>
280
281           The containing tag is always one of "<methoddef>", "<proceduredef>"
282           or "<functiondef>". The tags that specify name, signatures and the
283           code itself must always be present. Some optional information may
284           also be supplied. The "help" text, or what an introspection API
285           would expect to use to document the method, is also marked as
286           optional.  Having some degree of documentation for all the methods
287           a server provides is a good rule of thumb, however.
288
289           The default methods that this package provides are turned into XPL
290           files by the make_method tool (see make_method). The final forms of
291           these may serve as examples of what the file should look like.
292
293       Information used only for book-keeping
294           Some of the information in the XPL file is only for book-keeping:
295           the version stamp of a method is never involved in the invocation.
296           The server also keeps track of the last-modified time of the file
297           the method is read from, as well as the full directory path to that
298           file. The "<hidden />" tag is used to identify those methods that
299           should not be exposed to the outside world through any sort of
300           introspection/documentation API. They are still available and
301           callable, but the client must possess the interface information in
302           order to do so.
303
304       The information crucial to the method
305           The name, signatures and code must be present for obvious reasons.
306           The "<name>" tag tells the server what external name this procedure
307           is known by. The "<signature>" tag, which may appear more than
308           once, provides the definition of the interface to the function in
309           terms of what types and quantity of arguments it will accept, and
310           for a given set of arguments what the type of the returned value
311           is. Lastly is the "<code>" tag, without which there is no procedure
312           to remotely call.
313
314       Why the <code> tag allows multiple languages
315           Note that the "<code>" tag is the only one with an attribute, in
316           this case "language". This is designed to allow for one XPL file to
317           provide a given method in multiple languages. Why, one might ask,
318           would there be a need for this?
319
320           It is the hope behind this package that collections of RPC suites
321           may one day be made available as separate entities from this
322           specific software package.  Given this hope, it is not unreasonable
323           to suggest that such a suite of code might be implemented in more
324           than one language (each of Perl, Python, Ruby and Tcl, for
325           example). Languages which all support the means by which to take
326           new code and add it to a running process on demand (usually through
327           an ""eval"" keyword or something similar). If the file A.xpl is
328           provided with implementations in all four of the above languages,
329           the name, help text, signature and even hidden status would likely
330           be identical. So, why not share the non-language-specific elements
331           in the spirit of re-use?
332
333   The "make_method" Utility
334       The utility script "make_method" is provided as a part of this software
335       suite. It allows for the automatic creation of XPL files from either
336       command-line information or from template files. It has a wide variety
337       of features and options, and is out of the scope of this particular
338       manual page. The package Makefile.PL features an example of engineering
339       the automatic generation of XPL files and their delivery as a part of
340       the normal Perl module build process. Using this tool is highly
341       recommended over managing XPL files directly. For the full details, see
342       make_method.
343

NAMESPACES

345       As default behavior, Perl code that is passed to "eval" when a XPL file
346       is loaded gets put into the same namespace as the package used to load
347       the XPL.  It is not an issue when you create your own
348       RPC::XML::Procedure (or ::Method or ::Function) objects, as the code is
349       already instantiated into a given namespace.  This can be important if
350       your code expects to call routines in other loaded packages, utilize
351       package-level globals, etc.
352
353       To give developers control over the namespace in XPL code, a new
354       optional tag "<namespace>" was added in the 0.65 release. If this tag
355       is present in the XPL being read, it defines the namespace that the
356       "<code>" block is evaluated in.
357
358       The value of the namespace tag is a string providing the namespace in
359       either the Perl-style of hierarchy parts separated by "::", or the
360       style used by Java, Perl6, etc., in which the parts are separated by
361       ".". The latter form is converted to Perl style for the evaluation of
362       the code. If there is no namespace declaration in a XPL file, the
363       namespace of the class that loads the XPL is used.
364

DIAGNOSTICS

366       Unless otherwise noted in the individual documentation sections, all
367       methods return the object reference on success, or a (non-reference)
368       text string containing the error message upon failure.
369

CAVEATS

371       Moving the method management to a separate class adds a good deal of
372       overhead to the general system. The trade-off in reduced complexity and
373       added maintainability should offset this.
374

BUGS

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

SUPPORT

383       •   RT: CPAN's request tracker
384
385           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
386
387       •   AnnoCPAN: Annotated CPAN documentation
388
389           <http://annocpan.org/dist/RPC-XML>
390
391       •   CPAN Ratings
392
393           <http://cpanratings.perl.org/d/RPC-XML>
394
395       •   Search CPAN
396
397           <http://search.cpan.org/dist/RPC-XML>
398
399       •   MetaCPAN
400
401           <https://metacpan.org/release/RPC-XML>
402
403       •   Source code on GitHub
404
405           <http://github.com/rjray/rpc-xml>
406
408       This file and the code within are copyright (c) 2011 by Randy J. Ray.
409
410       Copying and distribution are permitted under the terms of the Artistic
411       License 2.0
412       (<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
413       GNU LGPL 2.1 (<http://www.opensource.org/licenses/lgpl-2.1.php>).
414

CREDITS

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

SEE ALSO

421       RPC::XML::Server, make_method
422

AUTHOR

424       Randy J. Ray "<rjray@blackperl.com>"
425
426
427
428perl v5.38.0                      2023-07-21            RPC::XML::Procedure(3)
Impressum