1Apache::RPC::Server(3)User Contributed Perl DocumentationApache::RPC::Server(3)
2
6 Apache::RPC::Server - A subclass of RPC::XML::Server tuned for mod_perl
7
9 # In httpd.conf:
10 PerlModule Apache::RPC::Server
11 PerlSetVar RpcMethodDir /var/www/rpc:/usr/lib/perl5/RPC-shared
12 PerlChildInitHandler Apache::RPC::Server->init_handler
13 ...
14 <Location /RPC>
15 SetHandler perl-script
16 PerlHandler Apache::RPC::Server
17 </Location>
18 </Location /RPC-limited>
19 SetHandler perl-script
20 PerlHandler Apache::RPC::Server
21 PerlSetVar RPCOptPrefix RpcLimit
22 PerlSetVar RpcLimitRpcServer Limited
23 PerlSetVar RpcLimitRpcMethodDir /usr/lib/perl5/RPC-shared
24 </Location>
25 # In the start-up Perl file:
27 use Apache::RPC::Server;
28
30 The Apache::RPC::Server module is a subclassing of RPC::XML::Server
31 that is tuned and designed for use within Apache with mod_perl.
32 Provided are phase-handlers for the general request-processing phase
34 ("PerlHandler") and the child-process initialization phase
35 ("PerlChildInitHandler"). The module should be loaded either by
36 inclusion in a server start-up Perl script or by directives in the
37 server configuration file (generally httpd.con). One loaded, the
38 configuration file may assign the module to handle one or more given
39 locations with the general set of "<Location>" directives and familiar
40 options. Additional configuration settings specific to this module are
41 detailed below.
42 Generally, externally-available methods are provided as files in the
44 XML dialect explained in RPC::XML::Server. A subclass derived from this
45 class may of course use the methods provided by this class and its
46 parent class for adding and manipulating the method table.
47
49 This module is designed to be dropped in with little (if any)
50 modification. The methods that the server publishes are provided by a
51 combination of the installation files and Apache configuration values.
52 Details on remote method syntax and semantics is covered in
53 RPC::XML::Server.
54 Methods
56 In addition to inheriting all the methods from RPC::XML::Server, the
57 following methods are either added or overloaded by
58 Apache::RPC::Server:
59 handler
61 This is the default content-handler routine that mod_perl expects
62 when the module is defined as managing the specified location. This
63 is provided as a method handler, meaning that the first argument is
64 either an object reference or a static string with the class name.
65 This allows for other packages to easily subclass
66 Apache::RPC::Server.
67 This routine takes care of examining the incoming request, choosing
69 an appropriate server object to actually process the request, and
70 returning the results of the remote method call to the client.
71 init_handler
73 This is another Apache-level handler, this one designed for
74 installation as a "PerlChildInitHandler". At present, its only
75 function is to iterate over all server object currently in the
76 internal tables and invoke the "child_started" method (detailed
77 below) on each. Setting this handler assures that each child has a
78 correct impression of when it started as opposed to the start time
79 of the server itself.
80 Note that this is only applied to those servers known to the master
82 Apache process. In most cases, this will only be the default server
83 object as described above. That is because of the delayed-loading
84 nature of all servers beyond the default, which are likely only in
85 child-specific memory. There are some configuration options
86 described in the next section that can affect and alter this.
87 new(HASH)
89 This is the class constructor. It calls the superclass "new"
90 method, then performs some additional steps. These include
91 installing the default methods (which includes an Apache-specific
92 version of "system.status"), adding the installation directory of
93 this module to the method search path, and adding any directories
94 or explicitly-requested methods to the server object.
95 The arguments to the constructor are regarded as a hash table (not
97 a hash reference), and are mostly passed unchanged to the
98 constructor for RPC::XML::Server. Three parameters are of concern
99 to this class:
100 apache The value associated with this key is a reference to an
102 Apache request object. If this is not passed, then it is
103 assumed that this is being called in the start-up phase of
104 the server and the value returned from "Apache-"server>
105 (see Apache) is used.
106 server_id
108 This provides the server ID string for the RPC server (not
109 to be confused with the Apache server) that is being
110 configured.
111 prefix The prefix is used in retrieving certain configuration
113 settings from the Apache configuration file.
114 The server identification string and prefix concepts are explained
116 in more detail in the next section. See RPC::XML::Server for a full
117 list of what additional arguments may be passed to new for eventual
118 proxy to the parent class constructor.
119 child_started([BOOLEAN])
121 This method is very similar to the "started" method provided by
122 RPC::XML::Server. When called with no argument or an argument that
123 evaluates to a false value, it returns the UNIX-style time value of
124 when this child process was started. Due to the child-management
125 model of Apache, this may very well be different from the value
126 returned by "started" itself. If given an argument that evaluates
127 as true, the current system time is set as the new child-start
128 time.
129 If the server has not been configured to set this at child
131 initialization, then the main "started" value is returned. The name
132 is different so that a child may specify both server-start and
133 child-start times with clear distinction.
134 get_server(APACHEREQ|STRING)
136 Get the server object that corresponds to the argument passed. If
137 the argument is a reference to an Apache request object, use it to
138 determine the name (by path, etc.) and return that object. If the
139 parameter is not a reference, it is assumed to be the specific name
140 desired.
141 If the requested server object does not yet exist, an attempt will
143 be made to create it and add it to the internal table. The newly-
144 created object is then returned.
145 list_servers
147 Return a list of the names used for all the current server
148 instances. Does not return the server objects themselves (use
149 get_server, above, for that).
150 version
152 This method behaves exactly like the RPC::XML::Server method,
153 except that the version string returned is specific to this module
154 instead.
155 INSTALL_DIR
157 As with version, this is an overload of the parent-class static
158 method that returns the installation directory of this particular
159 module.
160 Apache configuration semantics
162 In addition to the known directives such as "PerlHandler" and
163 "PerlChildInitHandler", configuration of this system is controlled
164 through a variety of settings that are manipulated with the
165 "PerlSetVar" and "PerlAddVar" directives. These variables are:
166 RPCOptPrefix [STRING]
168 Sets a prefix string to be applied to all of the following names
169 before trying to read their values. Useful for setting within a
170 "<Location>" block to ensure that no settings from a higher point
171 in the hierarchy influence the server being defined.
172 RpcServer [STRING]
174 Specify the name of the server to use for this location. If not
175 passed, then the default server is used. This server may also be
176 explicitly requested by the name """<default>""". If more than one
177 server is going to be created within the same Apache environment,
178 this setting should always be used outside the default area so that
179 the default server is not loaded down with extra method
180 definitions. If a sub-location changes the default server, those
181 changes will be felt by any location that uses that server.
182 Different locations may share the same server by specifying the
184 name with this variable. This is useful for managing varied access
185 schemes, traffic analysis, etc.
186 RpcMethodDir [DIRECTORY]
188 This variable specifies directories to be scanned for method
189 "*.xpl" files. To specify more than one directory, separate them
190 with "":"" just as with any other directory-path expression. All
191 directories are kept (in the order specified) as the search path
192 for future loading of methods.
193 RpcMethod [FILENAME]
195 This is akin to the directory-specification option above, but only
196 provides a single method at a time. It may also have multiple
197 values separated by colons. The method is loaded into the server
198 table. If the name is not an absolute pathname, then it is searched
199 for in the directories that currently comprise the path. The
200 directories above, however, have not been added to the search path
201 yet. This is because these directives are processed immediately
202 after the directory specifications, and thus do not need to be
203 searched. This directive is designed to allow selective overriding
204 of methods in the previously-specified directories.
205 RpcDefMethods [YES|NO]
207 If specified and set to "no" (case-insensitive), suppresses the
208 loading of the system default methods that are provided with this
209 package. The absence of this setting is interpreted as a "yes", so
210 explicitly specifying such is not needed.
211 RpcAutoMethods [YES|NO]
213 If specified and set to "yes", enables the automatic searching for
214 a requested remote method that is unknown to the server object
215 handling the request. If set to "no" (or not set at all), then a
216 request for an unknown function causes the object instance to
217 report an error. If the routine is still not found, the error is
218 reported. Enabling this is a security risk, and should only be
219 permitted by a server administrator with fully informed
220 acknowledgement and consent.
221 RpcAutoUpdates [YES|NO]
223 If specified and set to "yes", enables the checking of the
224 modification time of the file from which a method was originally
225 loaded. If the file has changed, the method is re-loaded before
226 execution is handed off. As with the auto-loading of methods, this
227 represents a potential security risk, and should only be permitted
228 by a server administrator with fully informed acknowledgement and
229 consent.
230 Specifying methods to the server(s)
232 Methods are provided to an Apache::RPC::Server object in three ways:
233 Default methods
235 Unless suppressed by a "RpcDefMethods" option, the methods shipped
236 with this package are loaded into the table. The
237 Apache::RPC::Server objects get a slightly different version of
238 "system.status" than the parent class does.
239 Configured directories
241 All method files (those ending in a suffix of "*.xpl") in the
242 directories specified in the relevant "RpcMethodDir" settings are
243 read next. These directories are also (after the next step) added
244 to the search path the object uses.
245 By specific inclusion
247 Any methods specified directly by use of "RpcMethod" settings are
248 loaded last. This allows for them to override methods that may have
249 been loaded from the system defaults or the specified directories.
250 If a request is made for an unknown method, the object will first
252 attempt to find it by searching the path of directories that were given
253 in the configuration as well as those that are part of the system
254 (installation-level directories). If it is still not found, then an
255 error is reported back to the requestor. By using this technique, it is
256 possible to add methods to a running server without restarting it. It
257 is a potential security hole, however, and it is for that reason that
258 the previously-documented "RpcAutoMethods" setting is provided.
259 Usage Within <Perl> Sections
261 To truly unlock the power of having the RPC server attached to a
262 mod_perl environment, the application and configuration of the server
263 should be done within Perl-configuration blocks on the Apache server
264 itself.
265 In doing this, two immediate benefits are gained:
267 (1) The rpc-server object gets created in the master Apache process,
269 rather than within each child as a side-effect of the first
270 request. Especially in cases where there are going to be more than
271 one server in use within the Apache environment, this boosts
272 performance by allowing newly-created children to already have the
273 server object and method table readily available.
274 (2) It becomes possible to exert more detailed control over the
276 creation and configuration of each server object. Combining the
277 get_method and add_method operations permits "sharing" (of a sort)
278 of methods between server objects. Recall from the RPC::XML::Server
279 documentation that, when a method is invoked, the first argument is
280 the server object that is marshalling it.
281 The following example illustrates these concepts in a fairly simple
283 environment:
284 # In httpd.conf:
286 <Perl>
287 # First, create and configure some Apache::RPC::Server objects
289 # One regular one, with the standard settings:
291 $main::defobj = Apache::RPC::Server->new(path => '/RPC',
292 auto_methods => 1,
293 auto_updates => 1);
294 # One version without the default methods, and no auto-actions
295 $main::secobj = Apache::RPC::Server->new(no_default => 1,
296 path => '/rpc-secured');
297 # Imagine that add_method and/or add_methods_in_dir has been used to
299 # add to the methods tables for those objects. Now assign them to
300 # locations managed by Apache:
301 $Location{'/RPC'} =
302 {
303 SetHandler => 'perl-script',
304 PerlHandler => '$main::defobj'
305 };
306 $Location{'/rpc-secure'} =
307 {
308 SetHandler => 'perl-script',
309 PerlHandler => '$main::secobj',
310 AuthUserFile => '/etc/some_file',
311 AuthType => 'Basic',
312 AuthName => 'SecuredRPC',
313 'require' => 'valid-user'
314 };
315 </Perl>
317 Note that the assignment of the "PerlHandler" value was a string
319 representation of the object reference itself. mod_perl performs a sort
320 of "thaw" of this string when the location is accessed. Since this
321 class implements itself as a method handler, this causes the
322 "handler()" method for each of the locations to be handed the
323 Apache::RPC::Server object directly. Note also that the value assigned
324 to "PerlHandler" cannot be a lexical variable, or it will be out of
325 scope when the handler is called.
326
328 All methods return some type of reference on success, or an error
329 string on failure. Non-reference return values should always be
330 interpreted as errors unless otherwise noted.
331 Where appropriate, the "log_error" method from the Apache package is
333 called to note internal errors.
334
336 This began as a reference implementation in which clarity of process
337 and readability of the code took precedence over general efficiency. It
338 is now being maintained as production code, but may still have parts
339 that could be written more efficiently.
340
342 Please report any bugs or feature requests to "bug-rpc-xml at
343 rt.cpan.org", or through the web interface at
344 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML
345 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
346 notified, and then you'll automatically be notified of progress on your
347 bug as I make changes.
348
350 · RT: CPAN's request tracker
351 http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML
353 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
354 · AnnoCPAN: Annotated CPAN documentation
356 http://annocpan.org/dist/RPC-XML <http://annocpan.org/dist/RPC-XML>
358 · CPAN Ratings
360 http://cpanratings.perl.org/d/RPC-XML
362 <http://cpanratings.perl.org/d/RPC-XML>
363 · Search CPAN
365 http://search.cpan.org/dist/RPC-XML
367 <http://search.cpan.org/dist/RPC-XML>
368 · Source code on GitHub
370 http://github.com/rjray/rpc-xml/tree/master
372 <http://github.com/rjray/rpc-xml/tree/master>
373
375 This file and the code within are copyright (c) 2009 by Randy J. Ray.
376 Copying and distribution are permitted under the terms of the Artistic
378 License 2.0
379 (http://www.opensource.org/licenses/artistic-license-2.0.php
380 <http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
381 GNU LGPL 2.1 (http://www.opensource.org/licenses/lgpl-2.1.php
382 <http://www.opensource.org/licenses/lgpl-2.1.php>).
383
385 The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software,
386 Inc. See <http://www.xmlrpc.com> for more information about the XML-
387 RPC specification.
388
390 RPC::XML::Server, RPC::XML
391
393 Randy J. Ray <rjray@blackperl.com>
394perl v5.12.0 2009-09-03 Apache::RPC::Server(3)