# $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<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

C<ZOOM::IRSpy>,
C<ZOOM::Pod>,
C<HTML::Mason>

=head1 AUTHOR

Mike Taylor, E<lt>mike@indexdata.comE<gt>

=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;
