# $Id: Maintenance.pod,v 1.4 2006-09-18 10:27:57 mike Exp $ package ZOOM::IRSpy::Maintenance; =head1 NAME ZOOM::IRSpy::Maintenance - maintenance documentation for IRSpy =head1 INTRODUCTION The IRSpy application is implemented by five components: =over 4 =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 C, C, C =head1 AUTHOR Mike Taylor, Emike@indexdata.comE =head1 COPYRIGHT AND LICENSE Copyright (C) 2006 by Index Data ApS. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available. =cut 1;