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 $method_1 = RPC::XML::Procedure->new({ name => 'system.identity',
14 code => sub { ... },
15 signature => [ 'string' ] });
16 $method_2 = RPC::XML::Procedure->new('/path/to/status.xpl');
17
19 This package is comprised of the code that was formerly
20 RPC::XML::Method. The package was renamed when the decision was made
21 to support procedures and methods as functionally different entities.
22 It is not necessary to include both this module and RPC::XML::Method --
23 this module provides the latter as an empty subclass. In time,
24 RPC::XML::Method will be removed from the distribution entirely.
25
27 The RPC::XML::Procedure package is designed primarily for behind-the-
28 scenes use by the RPC::XML::Server class and any subclasses of it. It
29 is documented here in case a project chooses to sub-class it for their
30 purposes (which would require setting the "method_class" attribute when
31 creating server objects, see RPC::XML::Server).
32 This package grew out of the increasing need to abstract the operations
34 that related to the methods a given server instance was providing.
35 Previously, methods were passed around simply as hash references. It
36 was a small step then to move them into a package and allow for
37 operations directly on the objects themselves. In the spirit of the
38 original hashes, all the key data is kept in clear, intuitive hash keys
39 (rather than obfuscated as the other classes do). Thus it is important
40 to be clear on the interface here before sub-classing this package.
41
43 The following methods are provided by this class:
44 new(FILE|HASHREF|LIST)
46 Creates a new object of the class, and returns a reference to it.
47 The arguments to the constructor are variable in nature, depending
48 on the type:
49 FILE If there is exactly on argument that is not a reference, it
51 is assumed to be a filename from which the method is to be
52 loaded. This is presumed to be in the XPL format descibed
53 below (see "XPL File Structure"). If the file cannot be
54 opened, or if once opened cannot be parsed, an error is
55 raised.
56 HASHREF If there is exactly one argument that is a reference, it is
58 assumed to be a hash with the relevant information on the
59 same keys as the object itself uses. This is primarily to
60 support backwards-compatibility to code written when
61 methods were implemented simply as hash references.
62 LIST If there is more than one argument in the list, then the
64 list is assumed to be a sort of "ersatz" hash construct, in
65 that one of the keys ("signature") is allowed to occur
66 multiple times. Otherwise, each of the following is
67 allowed, but may only occur once:
68 name The name of the method, as it will be presented
70 to clients
71 code A reference to a subroutine, or an anonymous
73 subroutine, that will receive calls for the
74 method
75 signature (May appear more than once) Provides one
77 calling-signature for the method, as either a
78 space-separated string of types or a list-
79 reference
80 help The help-text for a method, which is generally
82 used as a part of the introspection interface
83 for a server
84 version The version number/string for the method
86 hidden A boolean (true or false) value indicating
88 whether the method should be hidden from
89 introspection and similar listings
90 Note that all of these correspond to the values that can be
92 changed via the accessor methods detailed later.
93 If any error occurs during object creation, an error message is
95 returned in lieu of the object reference.
96 clone
98 Create a copy of the calling object, and return the new reference.
99 All elements are copied over cleanly, except for the code reference
100 stored on the "code" hash key. The clone will point to the same
101 code reference as the original. Elements such as "signature" are
102 copied, so that changes to the clone will not impact the original.
103 name
105 Returns the name by which the server is advertising the method.
106 Unlike the next few accessors, this cannot be changed on an object.
107 In order to streamline the managment of methods within the server
108 classes, this must persist. However, the other elements may be used
109 in the creation of a new object, which may then be added to the
110 server, if the name absolutely must change.
111 namespace
113 If the procedure object was created from a file, or if the
114 instantiation included namespace information, this accessor will
115 return the namespace that the underlying code executes in.
116 Otherwise, it returns an empty string. This cannot be altered (even
117 if the code method is used to replace the code routine).
118 code([NEW])
120 Returns or sets the code-reference that will receive calls as
121 marshalled by the server. The existing value is lost, so if it must
122 be preserved, then it should be retrieved prior to the new value
123 being set.
124 signature([NEW])
126 Return a list reference containing the signatures, or set it. Each
127 element of the list is a string of space-separated types (the first
128 of which is the return type the method produces in that calling
129 context). If this is being used to set the signature, then an array
130 reference must be passed that contains one or more strings of this
131 nature. Nested list references are not allowed at this level. If
132 the new signatures would cause a conflict (a case in which the same
133 set of input types are specified for different output types), the
134 old set is silently restored.
135 help([NEW])
137 Returns or sets the help-text for the method. As with code, the
138 previous value is lost.
139 hidden([NEW])
141 Returns or sets the hidden status of the method. Setting it loses
142 the previous value.
143 version([NEW])
145 Returns or sets the version string for the method (overwriting as
146 with the other accessors).
147 is_valid
149 Returns a true/false value as to whether the object currently has
150 enough content to be a valid method for a server to publish. This
151 entails having at the very least a name, one or more signatures,
152 and a code-reference to route the calls to. A server created from
153 the classes in this software suite will not accept a method that is
154 not valid.
155 add_signature(LIST)
157 Add one or more signatures (which may be a list reference or a
158 string) to the internal tables for this method. Duplicate
159 signatures are ignored. If the new signature would cause a conflict
160 (a case in which the same set of input types are specified for
161 different output types), the old set is restored and an error
162 message is returned.
163 delete_signature(LIST)
165 Deletes the signature or signatures (list reference or string) from
166 the internal tables. Quietly ignores any signature that does not
167 exist. If the new signature would cause a conflict (a case in which
168 the same set of input types are specified for different output
169 types), the old set is restored and an error message is returned.
170 match_signature(SIGNATURE)
172 Check that the passed-in signature is known to the method, and if
173 so returns the type that the method should be returning as a result
174 of the call. Returns a zero (0) otherwise. This differs from other
175 signature operations in that the passed-in signature (which may be
176 a list-reference or a string) does not include the return type.
177 This method is provided so that servers may check a list of
178 arguments against type when marshalling an incoming call. For
179 example, a signature of 'int int' would be tested for by calling
180 "$M->match_signature('int')" and expecting the return value to be
181 "int".
182 call(SERVER, PARAMLIST)
184 Execute the code that this object encapsulates, using the list of
185 parameters passed in PARAMLIST. The SERVER argument should be an
186 object derived from the RPC::XML::Server class. For some types of
187 procedure objects, this becomes the first argument of the parameter
188 list to simulate a method call as if it were on the server object
189 itself. The return value should be a data object (possibly a
190 RPC::XML::fault), but may not always be pre-encoded. Errors trapped
191 in $@ are converted to fault objects. This method is generally used
192 in the "dispatch" method of the server class, where the return
193 value is subsequently wrapped within a RPC::XML::response object.
194 reload
196 Instruct the object to reload itself from the file it originally
197 was loaded from, assuming that it was loaded from a file to begin
198 with. Returns an error if the method was not originally loaded from
199 a file, or if an error occurs during the reloading operation.
200 Additional Hash Data
202 In addition to the attributes managed by the accessors documented
203 earlier, the following hash keys are also available for use. These are
204 also not strongly protected, and the same care should be taken before
205 altering any of them:
206 file
208 When the method was loaded from a file, this key contains the path
209 to the file used.
210 namespace
212 If the code is loaded from a file, this hash key will reflect what
213 namespace the code executes in. If the file specified a namespace,
214 that is the value you will get (any occurrence of "." in the
215 specified namespace will have been converted to "::"). If no
216 explicit namespace was provided, the namespace of the class you
217 called new from will be used. See "Namespaces".
218 mtime
220 When the method was loaded from a file, this key contains the
221 modification-time of the file, as a UNIX-style "time" value. This
222 is used to check for changes to the file the code was originally
223 read from.
224 called
226 When the method is being used by one of the server classes provided
227 in this software suite, this key is incremented each time the
228 server object dispatches a request to the method. This can later be
229 checked to provide some indication of how frequently the method is
230 being invoked.
231 XPL File Structure
233 This section focuses on the way in which methods are expressed in these
234 files, referred to here as "XPL files" due to the "*.xpl" filename
235 extension (which stands for "XML Procedure Layout"). This mini-dialect,
236 based on XML, is meant to provide a simple means of specifying method
237 definitions separate from the code that comprises the application
238 itself. Thus, methods may theoretically be added, removed, debugged or
239 even changed entirely without requiring that the server application
240 itself be rebuilt (or, possibly, without it even being restarted).
241 The XML-based file structure
243 The XPL Procedure Layout dialect is a very simple application of
244 XML to the problem of expressing the method in such a way that it
245 could be useful to other packages than this one, or useful in other
246 contexts than this one.
247 The lightweight DTD for the layout can be summarized as:
249 <!ELEMENT proceduredef (name, namespace?, version?, hidden?,
251 signature+, help?, code)>
252 <!ELEMENT methoddef (name, namespace?, version?, hidden?,
253 signature+, help?, code)>
254 <!ELEMENT name (#PCDATA)>
255 <!ELEMENT namespace (#PCDATA)>
256 <!ELEMENT version (#PCDATA)>
257 <!ELEMENT hidden EMPTY>
258 <!ELEMENT signature (#PCDATA)>
259 <!ELEMENT help (#PCDATA)>
260 <!ELEMENT code (#PCDATA)>
261 <!ATTLIST code language (#PCDATA)>
262 The containing tag is always one of "<methoddef>" or
264 "<proceduredef>". The tags that specify name, signatures and the
265 code itself must always be present. Some optional information may
266 also be supplied. The "help" text, or what an introspection API
267 would expect to use to document the method, is also marked as
268 optional. Having some degree of documentation for all the methods
269 a server provides is a good rule of thumb, however.
270 The default methods that this package provides are turned into XPL
272 files by the make_method tool (see make_method). The final forms of
273 these may serve as examples of what the file should look like.
274 Information used only for book-keeping
276 Some of the information in the XPL file is only for book-keeping:
277 the version stamp of a method is never involved in the invocation.
278 The server also keeps track of the last-modified time of the file
279 the method is read from, as well as the full directory path to that
280 file. The "<hidden />" tag is used to identify those methods that
281 should not be exposed to the outside world through any sort of
282 introspection/documentation API. They are still available and
283 callable, but the client must possess the interface information in
284 order to do so.
285 The information crucial to the method
287 The name, signatures and code must be present for obvious reasons.
288 The "<name>" tag tells the server what external name this procedure
289 is known by. The "<signature>" tag, which may appear more than
290 once, provides the definition of the interface to the function in
291 terms of what types and quantity of arguments it will accept, and
292 for a given set of arguments what the type of the returned value
293 is. Lastly is the "<code>" tag, without which there is no procedure
294 to remotely call.
295 Why the <code> tag allows multiple languages
297 Note that the "<code>" tag is the only one with an attribute, in
298 this case "language". This is designed to allow for one XPL file to
299 provide a given method in multiple languages. Why, one might ask,
300 would there be a need for this?
301 It is the hope behind this package that collections of RPC suites
303 may one day be made available as separate entities from this
304 specific software package. Given this hope, it is not unreasonable
305 to suggest that such a suite of code might be implemented in more
306 than one language (each of Perl, Python, Ruby and Tcl, for
307 example). Languages which all support the means by which to take
308 new code and add it to a running process on demand (usually through
309 an ""eval"" keyword or something similar). If the file A.xpl is
310 provided with implementations in all four of the above languages,
311 the name, help text, signature and even hidden status would likely
312 be identical. So, why not share the non-language-specific elements
313 in the spirit of re-use?
314 The "make_method" Utility
316 The utility script "make_method" is provided as a part of this software
317 suite. It allows for the automatic creation of XPL files from either
318 command-line information or from template files. It has a wide variety
319 of features and options, and is out of the scope of this particular
320 manual page. The package Makefile.PL features an example of engineering
321 the automatic generation of XPL files and their delivery as a part of
322 the normal Perl module build process. Using this tool is highly
323 recommended over managing XPL files directly. For the full details, see
324 make_method.
325
327 As default behavior, Perl code that is passed to "eval" when a XPL file
328 is loaded gets put into the same namespace as the package used to load
329 the XPL. It is not an issue when you create your own
330 RPC::XML::Procedure (or ::Method or ::Function) objects, as the code is
331 already instantiated into a given namespace. This can be important if
332 your code expects to call routines in other loaded packages, utilize
333 package-level globals, etc.
334 To give developers control over the namespace in XPL code, a new
336 optional tag "<namespace>" was added in the 0.65 release. If this tag
337 is present in the XPL being read, it defines the namespace that the
338 "<code>" block is evaluated in.
339 The value of the namespace tag is a string providing the namespace in
341 either the Perl-style of hierarchy parts separated by "::", or the
342 style used by Java, Perl6, etc., in which the parts are separated by
343 ".". The latter form is converted to Perl style for the evaluation of
344 the code. If there is no namespace declaration in a XPL file, the
345 namespace of the class that loads the XPL is used.
346
348 Unless otherwise noted in the individual documentation sections, all
349 methods return the object reference on success, or a (non-reference)
350 text string containing the error message upon failure.
351
353 Moving the method management to a separate class adds a good deal of
354 overhead to the general system. The trade-off in reduced complexity and
355 added maintainability should offset this.
356
358 Please report any bugs or feature requests to "bug-rpc-xml at
359 rt.cpan.org", or through the web interface at
360 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML
361 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
362 notified, and then you'll automatically be notified of progress on your
363 bug as I make changes.
364
366 · RT: CPAN's request tracker
367 http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML
369 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
370 · AnnoCPAN: Annotated CPAN documentation
372 http://annocpan.org/dist/RPC-XML <http://annocpan.org/dist/RPC-XML>
374 · CPAN Ratings
376 http://cpanratings.perl.org/d/RPC-XML
378 <http://cpanratings.perl.org/d/RPC-XML>
379 · Search CPAN
381 http://search.cpan.org/dist/RPC-XML
383 <http://search.cpan.org/dist/RPC-XML>
384 · Source code on GitHub
386 http://github.com/rjray/rpc-xml/tree/master
388 <http://github.com/rjray/rpc-xml/tree/master>
389
391 This file and the code within are copyright (c) 2009 by Randy J. Ray.
392 Copying and distribution are permitted under the terms of the Artistic
394 License 2.0
395 (http://www.opensource.org/licenses/artistic-license-2.0.php
396 <http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
397 GNU LGPL 2.1 (http://www.opensource.org/licenses/lgpl-2.1.php
398 <http://www.opensource.org/licenses/lgpl-2.1.php>).
399
401 The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software,
402 Inc. See <http://www.xmlrpc.com> for more information about the XML-
403 RPC specification.
404
406 RPC::XML::Server, make_method
407
409 Randy J. Ray "<rjray@blackperl.com>"
410perl v5.12.0 2009-09-03 RPC::XML::Procedure(3)