1Apache::RPC::Status(3)User Contributed Perl DocumentationApache::RPC::Status(3)
2
3
4

NAME

6       Apache::RPC::Status - A status monitor similar to Apache::Status for
7       RPC
8

SYNOPSIS

10           # In httpd.conf:
11           </Location /rpc-status>
12               SetHandler perl-script
13               PerlHandler Apache::RPC::Status
14           </Location>
15
16           # In the start-up Perl file:
17           use Apache::RPC::Status;
18

DESCRIPTION

20       The Apache::RPC::Status package is provided as a simple status monitor
21       for XML-RPC servers running in a mod_perl environment, using the
22       Apache::RPC::Server class (or derivative of). Patterned after the
23       status system provided with mod_perl itself, information is broken down
24       into a series of screens providing information ranging from the RPC
25       servers currently configured down to the individual methods provided by
26       the servers.
27
28   Information Screens
29       There are three basic screens provided by the stock Apache::RPC::Status
30       package:
31
32       Main: Listing of Servers
33           This screen is the first screen that comes up when the location for
34           which this class was assigned as a handler is invoked. It lists the
35           server objects that this running Apache process knows of. Note that
36           if the servers are defined in such a way as to mean on-demand
37           creation, then a given child process may not have all the
38           configured servers in memory. This is by design, it is not a bug.
39           See "Usage Within <Perl> Sections" in Apache::RPC::Server for
40           details on configuring the RPC servers such that they are pre-
41           loaded into all child processes.
42
43       Server: Details of a Server
44           Each of the known servers in the main screen links to this screen,
45           which provides details on the specific server. Information such as
46           when the server was started (which usually matches the time that
47           Apache was started), when the specific child was started (which may
48           not be the same), number of requests servered, and so forth is
49           provided. Additionally, each of the methods that the server
50           provides is listed in alphanumeric order, with a link to the next
51           screen.
52
53       Method: Details of a Specific Method
54           For each of the known methods published by a server, this screen
55           summarizes all that is known about the method itself. The
56           signatures, help text and hidden status (whether the method is
57           visible to the introspection API that is shipped with
58           RPC::XML::Server) are all shown. Some optional information is shown
59           if available: if the method has a version number associated with
60           it, that is displayed. If the method was loaded from an external
61           XPL file, the file path and modification-time are also displayed.
62
63       The primary purpose of this status system is to allow for checking the
64       availability and sanity of the RPC servers themselves. For example, if
65       a server is configured to auto-load methods, and automatically check
66       for updates, the status system could confirm that a method is available
67       or is at the correct version.
68
69       (Note that auto-loading and auto-updating are done on demand, when a
70       call is made to the method in question. Thus, the status might not
71       reflect changes until at least one call has been made. Further, if
72       there are very many child processes handling the RPC servers, several
73       calls may be necessary to ensure that the child process answering the
74       status request also has the most up-to-date impression of the server.)
75

SUBROUTINES/METHODS

77       This package is implemented as a method handler for Apache/mod_perl.
78       This means that is should be relatively easy to subclass this package
79       to implement an extended version of status reporting, or to provide
80       handlers for phases of the request lifecycle not otherwise addressed.
81
82   Class Methods
83       There are three class methods defined in this package. One is the
84       constructor, the other two are handlers for specific phases in the
85       Apache request lifecycle.
86
87       new(CLASS, ARGS)
88           This creates a new object of this class and returns a reference to
89           it. The first argument is the class being created into, the
90           remaining arguments are treated as key/value pairs (note: not a
91           hash reference). At present, the only additional argument
92           recognized is:
93
94           serverclass
95                   This is used when the status monitor is being used with a
96                   server class other than Apache::RPC::Server directly.
97                   Because several methods from that class are invoked, it is
98                   presumed that the class named here is a subclass of
99                   Apache::RPC::Server. If not, the status monitor may not
100                   work correctly, or at all. In the absence of this value,
101                   "Apache::RPC::Server" is assumed. This value may also be
102                   set with the mod_perl PerlSetVar directive. See the
103                   documentation for "init_handler", below.
104
105       handler(CLASS, REQUEST)
106           This is the primary entry-point for the package. This is the
107           handler defined for assignment to "PerlHandler" in a location
108           configuration block. It is invoked by mod_perl as a method handler,
109           thus the first argument is either the name of the class (in the
110           case of class-method, or static, invocation) or the object
111           configured as the handler. The second argument is the Apache
112           request object itself.
113
114           This method derives the query parameters for the request from the
115           Apache object, and treats them according to the type of information
116           screen requested:
117
118           screen  This specifies which screen of the status monitor is to be
119                   displayed. In absence, the value defaults to "main", which
120                   is the internal identifier for the primary screen of the
121                   status monitor system. If the value of this parameter does
122                   not match a known interface hook, then the handler will
123                   signify to mod_perl that it cannot handler the request, by
124                   replying with the "DECLINED" response code.
125
126           server  When the screen parameter is set to "server", the monitor
127                   displays the server detail screen. In that case, this
128                   parameter specifies which server should be displayed.
129                   Servers are given unique identifiers when they are created,
130                   usually derived from the URL path that they are attached
131                   to. If the value here does not match any known servers, a
132                   warning is sent to the browser.
133
134           method  When the screen parameter is set to "method", this calls
135                   for the method detail screen. The provided interface hook
136                   to deal with these requests looks for both the server
137                   parameter above and this one, which specifies by name the
138                   method to be laid out in detail. As with the server
139                   parameter, if the value in this parameter does not match
140                   any known data, an error is reported to the browser.
141
142           Any additional parameters will be preserved by make_url call
143           detailed below. These are merely the specific ones recognized by
144           the status monitor as written.
145
146       init_handler(CLASS, REQUEST)
147           This is a very simple handler designed for the PerlChildInitHandler
148           phase. At present, it only does one simple task (and thus makes no
149           direct use of either parameter passed to it by mod_perl). However,
150           it is included mainly as a placeholder for possible future
151           expansion. The current behavior is to check for the existence of
152           directory-configuration item called "ServerClass", and record the
153           value if it is set. This is used to specifiy the class from which
154           the RPC server objects are created, if something other than
155           Apache::RPC::Server. If this information is passed via the
156           "serverclass" parameter to the new method above, that value
157           overrides any value here. However, that requires actually creating
158           an object to use as the handler, whereas this handler may be used
159           directly, as a static handler. It would be configured outside of
160           any <Location> blocks, a requirement for the PerlChildInitHandler
161           phase. It is designed to stack cleanly with any other handlers for
162           that phase, provided your mod_perl installation supports stacked
163           handlers.
164
165   Additional Methods
166       In addition to the class methods above, the following are provided. In
167       most cases, these do not rely on any data contained within the actual
168       object itself. Many may also be called as static methods (these are so
169       noted). They are provided as a utility, implemented as methods so as to
170       avoid namespace issues:
171
172       version
173           (May be called as a static method.) Returns the current version of
174           this module.
175
176       apache_status_attach
177           Attach the Apache::RPC::Status module to the main screen of the
178           Apache::Status display.
179
180       default_object
181           (May be called as a static method.) Returns a default
182           Apache::RPC::Status instance when called as a static method.
183           Returns the calling reference itself, otherwise.
184
185       header(REQUEST, TITLE)
186           Produces the HTML header for a page. Uses the passed-in title
187           parameter to give the page a title, and extracts any request-
188           specific information from the Apache request object passed as the
189           first parameter.
190
191       footer(REQUEST)
192           Produces the HTML footer.
193
194       make_url(QUERY|REQUEST, FLAG)
195           (May be called as a static method.) This creates a URL string for
196           use as a hyperlink. It makes certain to preserve all parameters in
197           a CGI-like fashion. Additionally, it can make the URL in such a
198           fashion as to allow better integration with the Apache::Status
199           package. If the "FLAG" parameter is passed and is any true value,
200           then the resulting URL will be tailored for use with
201           Apache::Status. The first argument must be either the original
202           request object as passed by mod_perl, or a reference to a CGI
203           object created from the request (see CGI for more on the CGI
204           class).
205
206       main_screen(REQUEST, QUERY, INTERNAL)
207           Renders the HTML (minus the header and footer) for the main screen.
208           The arguments are the Apache request object, a CGI query object
209           created from the request, and a boolean flag indicating whether the
210           call into this method was made from within this module or made from
211           the Apache::Status page.
212
213       server_summary(SERVER)
214           Creates an HTML snippet to provide a summary for the server passed
215           in as an argument. The passed-in value should be the server object,
216           not the name.
217
218       server_detail(REQUEST, QUERY, INTERNAL)
219           Renders the HTML (minus header and footer) for a screen describing
220           a server instance in detail. The server is specified by name in the
221           query parameters.  The arguments are the same as for "main_screen".
222
223       method_summary(SERVER, METHOD, BASEURL)
224           Creates and HTML snippet to provide a summary for the specified
225           method of the specified server. The third argument is a base-URL to
226           use for making links to the detailed method page.
227
228       method_detail(REQUEST, QUERY, INTERNAL)
229           Renders the HTML (minus header and footer) for a screen describing
230           a method on a specific server instance, in detail. The method and
231           server are specified by name in the query parameters. The arguments
232           are the same as for "main_screen".
233
234   Use and Extension Within Perl Sections
235       Some extension may be done without necessarily subclassing this
236       package. The class object are implemented simply as hash references.
237       When a request is received, the screen parameter (see above) is
238       extracted, and used to look up in the hash table. If there is a value
239       for that key, the value is assumed to be a hash reference with at least
240       two keys (described below). If it does not exist, the handler routine
241       declines to handle the request. Thus, some degree of extension may be
242       done without the need for developing a new class, if the configuration
243       and manipulation are done within <Perl> configuration blocks.
244
245       Adding a new screen means writing a routine to handle the requests, and
246       then adding a hook into that routine to the object that is the handler
247       for the Apache location that serves RPC status requests. The routines
248       that are written to handle a request should expect four arguments (in
249       order):
250
251       The object reference for the location handler
252       The Apache request object reference
253       A query object reference (see below)
254       A flag that is only passed when called from Apache::Status
255
256       The routines are given both the original request object and a query
257       object reference for sake of ease. The query object is already
258       available prior to the dispatch, so there is no reason to have each
259       hook routine write the same few lines to derive a query object from an
260       Apache request. At the same time, the hooks themselves may need the
261       Apache object to call methods on. The query object is an instance of
262       CGI. The flag parameter is passed by the linkage from this status
263       package to Apache::Status. The primary use for it is to pass to
264       routines such as make_url that are sensitive to the Apache::Status
265       context.
266
267       The return value from these routines must be a reference to a list of
268       lines of text. It is passed to the print method of the Apache class.
269       This is necessary for compatibility with the Apache::Status
270       environment.
271
272       To add a new hook, merely assign it to the object directly. The key is
273       the value of the "screen" parameter defined above, and the value is a
274       hash reference with two keys:
275
276       title
277           A string that is incorporated into the HTML title for the page.
278
279       call
280           A reference to a subroutine or closure that implements the hook,
281           and conforms to the conventions described above.
282
283       A sample addition:
284
285           $stat_obj->{dbi} = {
286                                  title => 'RPC-side DBI Pool',
287                                  call  => \&show_dbi_pool
288                              };
289

INTEGRATION WITH Apache::Status

291       This package is designed to integrate with the Apache::Status package
292       that is a part of mod_perl. However, this is not currently functional.
293       When this has been debugged, the details will be presented here.
294

CAVEATS

296       This is the newest part of the RPC-XML package. While the package as a
297       whole is now considered beta, this piece may yet undergo some alpha-
298       like enhancements to the interface and such. However, the design and
299       planning of this were carefully considered, so any such changes should
300       be minimal.
301

DIAGNOSTICS

303       Diagnostics are not handled well in this module.
304

BUGS

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

SUPPORT

313       •   RT: CPAN's request tracker
314
315           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
316
317       •   AnnoCPAN: Annotated CPAN documentation
318
319           <http://annocpan.org/dist/RPC-XML>
320
321       •   CPAN Ratings
322
323           <http://cpanratings.perl.org/d/RPC-XML>
324
325       •   Search CPAN
326
327           <http://search.cpan.org/dist/RPC-XML>
328
329       •   MetaCPAN
330
331           <https://metacpan.org/release/RPC-XML>
332
333       •   Source code on GitHub
334
335           <http://github.com/rjray/rpc-xml>
336
338       This file and the code within are copyright (c) 2011 by Randy J. Ray.
339
340       Copying and distribution are permitted under the terms of the Artistic
341       License 2.0
342       (<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
343       GNU LGPL 2.1 (<http://www.opensource.org/licenses/lgpl-2.1.php>).
344

CREDITS

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

SEE ALSO

351       Apache::Status, Apache::RPC::Server, RPC::XML::Method
352

AUTHOR

354       Randy J. Ray "<rjray@blackperl.com>"
355
356
357
358perl v5.34.0                      2021-07-22            Apache::RPC::Status(3)
Impressum