1RPC::XML::Procedure(3)User Contributed Perl DocumentationRPC::XML::Procedure(3)
2
6 RPC::XML::Procedure - Object encapsulation of server-side RPC
7 procedures
8
10 require RPC::XML::Procedure;
11 ...
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
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 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
37 This module provides three classes, representing the three types of
38 procedures that servers can use:
39 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 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 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 There is (currently) no version that is called like a method but
65 ignores signatures like a function.
66
68 The following methods are provided by this class:
69 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 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 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 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 name The name of the method, as it will be presented
95 to clients
96 code A reference to a subroutine, or an anonymous
98 subroutine, that will receive calls for the
99 method
100 signature Provides one calling-signature for the method,
102 as either a space-separated string of types or
103 a list-reference
104 help The help-text for a method, which is generally
106 used as a part of the introspection interface
107 for a server
108 version The version number/string for the method
110 hidden A boolean (true or false) value indicating
112 whether the method should be hidden from
113 introspection and similar listings
114 Note that all of these correspond to the values that can be
116 changed via the accessor methods detailed later.
117 If any error occurs during object creation, an error message is
119 returned in lieu of the object reference.
120 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 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 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 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 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 help([NEW])
161 Returns or sets the help-text for the method. As with code, the
162 previous value is lost.
163 hidden([NEW])
165 Returns or sets the hidden status of the method. Setting it loses
166 the previous value.
167 version([NEW])
169 Returns or sets the version string for the method (overwriting as
170 with the other accessors).
171 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 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 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 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 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 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 file
224 When the method was loaded from a file, this key contains the path
225 to the file used.
226 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 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 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 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 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 The lightweight DTD for the layout can be summarized as:
265 <!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 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 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 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 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 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 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 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
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 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 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
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
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
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
383 • RT: CPAN's request tracker
384 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
386 • AnnoCPAN: Annotated CPAN documentation
388 <http://annocpan.org/dist/RPC-XML>
390 • CPAN Ratings
392 <http://cpanratings.perl.org/d/RPC-XML>
394 • Search CPAN
396 <http://search.cpan.org/dist/RPC-XML>
398 • MetaCPAN
400 <https://metacpan.org/release/RPC-XML>
402 • Source code on GitHub
404 <http://github.com/rjray/rpc-xml>
406
408 This file and the code within are copyright (c) 2011 by Randy J. Ray.
409 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
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
421 RPC::XML::Server, make_method
422
424 Randy J. Ray "<rjray@blackperl.com>"
425perl v5.36.0 2023-01-20 RPC::XML::Procedure(3)