X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=lib%2FZOOM%2FIRSpy%2FMaintenance.pod;h=4c8e310c746054d409699387cbf604040dc7ff86;hb=7756fea114005961008fd69527ba5876c814ac51;hp=415934301d197f63ca323263535d50e49973bcdf;hpb=c0aa2f67e251d1157bdf1b81967aacb3011a5450;p=irspy-moved-to-github.git diff --git a/lib/ZOOM/IRSpy/Maintenance.pod b/lib/ZOOM/IRSpy/Maintenance.pod index 4159343..4c8e310 100644 --- a/lib/ZOOM/IRSpy/Maintenance.pod +++ b/lib/ZOOM/IRSpy/Maintenance.pod @@ -1,4 +1,4 @@ -# $Id: Maintenance.pod,v 1.1 2006-09-12 16:32:42 mike Exp $ +# $Id: Maintenance.pod,v 1.4 2006-09-18 10:27:57 mike Exp $ package ZOOM::IRSpy::Maintenance; @@ -6,23 +6,219 @@ package ZOOM::IRSpy::Maintenance; ZOOM::IRSpy::Maintenance - maintenance documentation for IRSpy -=head1 SYNOPSIS +=head1 INTRODUCTION -The IRSpy application is implemented by a library of classes mostly -within the C "namespace", together with a command-line -invocation script called C and a web-based UI - either can be -used to run the spy software, but the latter is more capable in that -it also provides ways to interrogate the database of results. +The IRSpy application is implemented by five components: -=head1 DESCRIPTION +=over 4 -I<### To follow> +=item * + +A library of classes within the C "namespace". + +=item * + +A command-line invocation script called C + +=item * + +A web-based UI - either this or the command-line script can be used to +run the spy software, but the latter is more capable in that it also +provides ways to interrogate the database of results. + +=item * + +A small additional library, C, which is used by IRSpy and +which is more conveniently included in this distribution than released +and maintained separately. + +=item * + +The configuration for a Zebra database that stores the harvested +information. + +=back + +These components are discussed in turn. + +=head1 THE ZOOM::POD LIBRARY + +Provides a simple API to ZOOM-Perl's asynchronous multiplexing. This +is documented in its own manual page. It shouldn't need any +maintenance, as it was written and tested independently of the rest of +IRSpy. + +=head1 THE IRSPY COMMAND-LINE TOOL + +There is only one command-line interface to the IRSpy library, the +C program which is provided in the C directory of the +distribution. + +There are other programs in that directory, but they are all tests, of +little interest now. The original of these is C which is +a script to exercise the C library. When this script +uncovered a subtle bug in ZOOM-C, I needed to isolate the bug in a +form that would be easy for Adam to see, so I made a sequence of +derivatives of this test-script, each of them functionally equivalent, +coming closer and closer to the metal: C unrolled the +Pod code into a script that uses the pure ZOOM-Perl API; +C is the low-level version of this, using the +ZOOM-C-like C API rather than the object-oriented +C API; and C is a translation of this into C, +using the ZOOM-C API directly. + +=head1 THE IRSPY WEB INTERFACE + +The web interface is built using the C module, a +framework that allows Perl to be embedded in web-pages much like PHP. +To install this on a Debian-based operating system it should suffice +to C. + +The components of this interface can be found in the C directory +(well, who'd have thought?) which in turn contains the following +directories: + +=over 4 + +=item conf + +Sample configuration for wiring the UI into a web-server. The +subdirectories name specific web-servers (e.g. C) and the +files within are named after the particular hosts where they are known +to work (but will in general work on other hosts). For example, +C is an Apache 1.3 configuration for xeno, +my desktop development box; but it should work just fine on any Ubuntu +6.06 box, probably on any Ubuntu box, and most likely on anything +running any Debian-based Linux distribution. + +The sample configurations assume that IRSpy is unpacked into the +C directory. If you've put it elsewhere, +you'll need to either make a symbolic link or tweak the configuration. + +=item htdocs + +The Document Root containing actual page that make up the UI. These +pages are HTML containing embedded Perl, as enabled by the +C module. + +=item logs + +Logs generated by the web server are directed here by the provided +sample configurations. +You may need to tweak the permissions of this directory to get things +to work properly. + +=item data + +Temporary files generated by the C module. +You may need to tweak the permissions of this directory to get things +to work properly. + +=back + +=head1 THE IRSPY LIBRARY + +The IRSpy library does the bulk of the work in this software: the +command-line and web interfaces are both as thin as possible, relying +on the library; and the C library is small and +self-contained. The library is contained in the C directory. + +The library consists of the following hierarchy of classes: + + IRSpy.pm -- the controlling class + IRSpy/Maintenance.pod -- this document + IRSpy/Record.pm -- a record of a probed database + IRSpy/Test.pm -- base class for individual tests + IRSpy/Test -- contains individual tests + IRSpy/Test/Main.pm -- the top-level test, calls others + IRSpy/Test/Ping.pm -- simplest test: checks server is alive + IRSpy/Test/Search -- contains tests for searching + IRSpy/Test/Search/Title.pm -- test for title search + +=head2 IRSpy.pm + +The main class, and the only one used directly by the command-line +application. And C object represents a connection to a +database of extended ZeeRex records, together with a set of +connections to target databases being tested. + +With the aid of C, this class implements a framework +within which separately authored tests may be run, the tests running +sequentially but with all connections attempting each test in parallel +- i.e. all connections must complete a given test (whether +successfully or not) before the next test is begun. + +=head2 IRSpy/Maintenance.pod + +Do you really need a section about this file? + +=head2 IRSpy/Record.pm + +Represents a record describing a target database, based on an extended +ZeeRex record. Includes the results of the tests that have been run +during the current session. + +=head2 IRSpy/Test.pm + +This is an abstract base-class that is used by all the concrete +classes implementing specific tests. Its principle purpose is to +provide the C method whereby high-level tests such as +C
can invoke lower-level tests. + +=head2 IRSpy/Test + +Directory containing plugins for specific tests. + +=head2 IRSpy/Test/Main.pm + +The top-level test: running an IRSpy object (by calling its C +method) consists of running the C
test, then writing the results +of that test back to the database. This test itself does nothing but +call lower-level tests, using the C method provided by +its superclass. + +=head2 IRSpy/Test/Ping.pm + +The simplest of all the "real" tests (i.e. not including C
) and +good one to use as a template when developing new tests. It tests +whether the target can be connected to, using C callbacks +to be notified of each target's success or failure, and updates the +associated record accordingly. + +=head2 IRSpy/Test/Search + +Directory containing plugins for specific tests of searching. In +time, we will probably have analogous directories for retrieval tests, +extended services tests. etc. + +=head2 IRSpy/Test/Search/Title.pm + +A simple test of title-searching. =cut +=head1 DATABASE + +The results of IRSpy's probing are held in a Zebra database of +extended ZeeRex records: these mostly conform to the ZeeRex schema as +described on the website at http://explain.z3950.org/dtd/ but are +extended with additional elements to store the results of various +tests. + +The configuration for the Zebra database is found in the C +directory. It consists of a distressingly large number of files, all +of which are described in that directory's C file. + +=head1 CRUD + +There is also a C module, but it's unfinished and +unused. + =head1 SEE ALSO -ZOOM::IRSpy +C, +C, +C =head1 AUTHOR