1 # $Id: Maintenance.pod,v 1.4 2006-09-18 10:27:57 mike Exp $
3 package ZOOM::IRSpy::Maintenance;
7 ZOOM::IRSpy::Maintenance - maintenance documentation for IRSpy
11 The IRSpy application is implemented by five components:
17 A library of classes within the C<ZOOM::IRSpy> "namespace".
21 A command-line invocation script called C<irspy>
25 A web-based UI - either this or the command-line script can be used to
26 run the spy software, but the latter is more capable in that it also
27 provides ways to interrogate the database of results.
31 A small additional library, C<ZOOM::Pod>, which is used by IRSpy and
32 which is more conveniently included in this distribution than released
33 and maintained separately.
37 The configuration for a Zebra database that stores the harvested
42 These components are discussed in turn.
44 =head1 THE ZOOM::POD LIBRARY
46 Provides a simple API to ZOOM-Perl's asynchronous multiplexing. This
47 is documented in its own manual page. It shouldn't need any
48 maintenance, as it was written and tested independently of the rest of
51 =head1 THE IRSPY COMMAND-LINE TOOL
53 There is only one command-line interface to the IRSpy library, the
54 C<irspy.pl> program which is provided in the C<bin> directory of the
57 There are other programs in that directory, but they are all tests, of
58 little interest now. The original of these is C<test-pod.pl> which is
59 a script to exercise the C<ZOOM::Pod> library. When this script
60 uncovered a subtle bug in ZOOM-C, I needed to isolate the bug in a
61 form that would be easy for Adam to see, so I made a sequence of
62 derivatives of this test-script, each of them functionally equivalent,
63 coming closer and closer to the metal: C<test-zoom.pl> unrolled the
64 Pod code into a script that uses the pure ZOOM-Perl API;
65 C<test-net-z3950-zoom.pl> is the low-level version of this, using the
66 ZOOM-C-like C<Net::Z3950::ZOOM> API rather than the object-oriented
67 C<ZOOM> API; and C<test-zoom-c.c> is a translation of this into C,
68 using the ZOOM-C API directly.
70 =head1 THE IRSPY WEB INTERFACE
72 The web interface is built using the C<HTML::Mason> module, a
73 framework that allows Perl to be embedded in web-pages much like PHP.
74 To install this on a Debian-based operating system it should suffice
75 to C<apt-get install libhtml-mason-perl>.
77 The components of this interface can be found in the C<web> directory
78 (well, who'd have thought?) which in turn contains the following
85 Sample configuration for wiring the UI into a web-server. The
86 subdirectories name specific web-servers (e.g. C<apache1.3>) and the
87 files within are named after the particular hosts where they are known
88 to work (but will in general work on other hosts). For example,
89 C<conf/apache1.3/xeno.conf> is an Apache 1.3 configuration for xeno,
90 my desktop development box; but it should work just fine on any Ubuntu
91 6.06 box, probably on any Ubuntu box, and most likely on anything
92 running any Debian-based Linux distribution.
94 The sample configurations assume that IRSpy is unpacked into the
95 C</usr/local/src/cvs/irspy> directory. If you've put it elsewhere,
96 you'll need to either make a symbolic link or tweak the configuration.
100 The Document Root containing actual page that make up the UI. These
101 pages are HTML containing embedded Perl, as enabled by the
102 C<HTML::Mason> module.
106 Logs generated by the web server are directed here by the provided
107 sample configurations.
108 You may need to tweak the permissions of this directory to get things
113 Temporary files generated by the C<HTML::Mason> module.
114 You may need to tweak the permissions of this directory to get things
119 =head1 THE IRSPY LIBRARY
121 The IRSpy library does the bulk of the work in this software: the
122 command-line and web interfaces are both as thin as possible, relying
123 on the library; and the C<ZOOM::Pod> library is small and
124 self-contained. The library is contained in the C<lib> directory.
126 The library consists of the following hierarchy of classes:
128 IRSpy.pm -- the controlling class
129 IRSpy/Maintenance.pod -- this document
130 IRSpy/Record.pm -- a record of a probed database
131 IRSpy/Test.pm -- base class for individual tests
132 IRSpy/Test -- contains individual tests
133 IRSpy/Test/Main.pm -- the top-level test, calls others
134 IRSpy/Test/Ping.pm -- simplest test: checks server is alive
135 IRSpy/Test/Search -- contains tests for searching
136 IRSpy/Test/Search/Title.pm -- test for title search
140 The main class, and the only one used directly by the command-line
141 application. And C<IRSpy> object represents a connection to a
142 database of extended ZeeRex records, together with a set of
143 connections to target databases being tested.
145 With the aid of C<IRSpy/Record.pm>, this class implements a framework
146 within which separately authored tests may be run, the tests running
147 sequentially but with all connections attempting each test in parallel
148 - i.e. all connections must complete a given test (whether
149 successfully or not) before the next test is begun.
151 =head2 IRSpy/Maintenance.pod
153 Do you really need a section about this file?
155 =head2 IRSpy/Record.pm
157 Represents a record describing a target database, based on an extended
158 ZeeRex record. Includes the results of the tests that have been run
159 during the current session.
163 This is an abstract base-class that is used by all the concrete
164 classes implementing specific tests. Its principle purpose is to
165 provide the C<run_tests()> method whereby high-level tests such as
166 C<Main> can invoke lower-level tests.
170 Directory containing plugins for specific tests.
172 =head2 IRSpy/Test/Main.pm
174 The top-level test: running an IRSpy object (by calling its C<check()>
175 method) consists of running the C<Main> test, then writing the results
176 of that test back to the database. This test itself does nothing but
177 call lower-level tests, using the C<run_tests()> method provided by
180 =head2 IRSpy/Test/Ping.pm
182 The simplest of all the "real" tests (i.e. not including C<Main>) and
183 good one to use as a template when developing new tests. It tests
184 whether the target can be connected to, using C<ZOOM::Pod> callbacks
185 to be notified of each target's success or failure, and updates the
186 associated record accordingly.
188 =head2 IRSpy/Test/Search
190 Directory containing plugins for specific tests of searching. In
191 time, we will probably have analogous directories for retrieval tests,
192 extended services tests. etc.
194 =head2 IRSpy/Test/Search/Title.pm
196 A simple test of title-searching.
202 The results of IRSpy's probing are held in a Zebra database of
203 extended ZeeRex records: these mostly conform to the ZeeRex schema as
204 described on the website at http://explain.z3950.org/dtd/ but are
205 extended with additional elements to store the results of various
208 The configuration for the Zebra database is found in the C<zebra>
209 directory. It consists of a distressingly large number of files, all
210 of which are described in that directory's C<README> file.
214 There is also a C<ZOOM::XML::Simple> module, but it's unfinished and
225 Mike Taylor, E<lt>mike@indexdata.comE<gt>
227 =head1 COPYRIGHT AND LICENSE
229 Copyright (C) 2006 by Index Data ApS.
231 This library is free software; you can redistribute it and/or modify
232 it under the same terms as Perl itself, either Perl version 5.8.7 or,
233 at your option, any later version of Perl 5 you may have available.