-# $Id: Maintenance.pod,v 1.1 2006-09-12 16:32:42 mike Exp $
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<ZOOM::IRSpy> "namespace", together with a command-line
-invocation script called C<irspy> 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<ZOOM::IRSpy> "namespace".
+
+=item *
+
+A command-line invocation script called C<irspy>
+
+=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<ZOOM::Pod>, 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<irspy.pl> program which is provided in the C<bin> 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<test-pod.pl> which is
+a script to exercise the C<ZOOM::Pod> 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<test-zoom.pl> unrolled the
+Pod code into a script that uses the pure ZOOM-Perl API;
+C<test-net-z3950-zoom.pl> is the low-level version of this, using the
+ZOOM-C-like C<Net::Z3950::ZOOM> API rather than the object-oriented
+C<ZOOM> API; and C<test-zoom-c.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<HTML::Mason> 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<apt-get install libhtml-mason-perl>.
+
+The components of this interface can be found in the C<web> 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<apache1.3>) 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<conf/apache1.3/xeno.conf> 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</usr/local/src/cvs/irspy> 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<HTML::Mason> 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<HTML::Mason> 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<ZOOM::Pod> library is small and
+self-contained. The library is contained in the C<lib> 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<IRSpy> 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<IRSpy/Record.pm>, 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<run_tests()> method whereby high-level tests such as
+C<Main> 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<check()>
+method) consists of running the C<Main> 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<run_tests()> method provided by
+its superclass.
+
+=head2 IRSpy/Test/Ping.pm
+
+The simplest of all the "real" tests (i.e. not including C<Main>) and
+good one to use as a template when developing new tests. It tests
+whether the target can be connected to, using C<ZOOM::Pod> 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<zebra>
+directory. It consists of a distressingly large number of files, all
+of which are described in that directory's C<README> file.
+
+=head1 CRUD
+
+There is also a C<ZOOM::XML::Simple> module, but it's unfinished and
+unused.
+
=head1 SEE ALSO
-ZOOM::IRSpy
+C<ZOOM::IRSpy>,
+C<ZOOM::Pod>,
+C<HTML::Mason>
=head1 AUTHOR
projects / irspy-moved-to-github.git / blobdiff