NAME

ZOOM::IRSpy::Maintenance - maintenance documentation for IRSpy

INTRODUCTION

The IRSpy application is implemented by five components:

• A library of classes within the ZOOM::IRSpy "namespace".

• A command-line invocation script called irspy

• 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.

• A small additional library, ZOOM::Pod, which is used by IRSpy and which is more conveniently included in this distribution than released and maintained separately.

• The configuration for a Zebra database that stores the harvested information.

These components are discussed in turn.

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.

THE IRSPY COMMAND-LINE TOOL

There is only one command-line interface to the IRSpy library, the irspy.pl program which is provided in the 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 test-pod.pl which is a script to exercise the 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: test-zoom.pl unrolled the Pod code into a script that uses the pure ZOOM-Perl API; test-net-z3950-zoom.pl is the low-level version of this, using the ZOOM-C-like Net::Z3950::ZOOM API rather than the object-oriented ZOOM API; and test-zoom-c.c is a translation of this into C, using the ZOOM-C API directly.

THE IRSPY WEB INTERFACE

The web interface is built using the 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 apt-get install libhtml-mason-perl.

The components of this interface can be found in the web directory (well, who'd have thought?) which in turn contains the following directories:

conf

Sample configuration for wiring the UI into a web-server. The subdirectories name specific web-servers (e.g. 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, 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 /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.

htdocs

The Document Root containing actual page that make up the UI. These pages are HTML containing embedded Perl, as enabled by the HTML::Mason module.

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.

data

Temporary files generated by the HTML::Mason module. You may need to tweak the permissions of this directory to get things to work properly.

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 ZOOM::Pod library is small and self-contained. The library is contained in the 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

IRSpy.pm

The main class, and the only one used directly by the command-line application. And 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 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.

IRSpy/Maintenance.pod

Do you really need a section about this file?

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.

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 run_tests() method whereby high-level tests such as Main can invoke lower-level tests.

IRSpy/Test

Directory containing plugins for specific tests.

IRSpy/Test/Main.pm

The top-level test: running an IRSpy object (by calling its check() method) consists of running the 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 run_tests() method provided by its superclass.

IRSpy/Test/Ping.pm

The simplest of all the "real" tests (i.e. not including Main) and good one to use as a template when developing new tests. It tests whether the target can be connected to, using ZOOM::Pod callbacks to be notified of each target's success or failure, and updates the associated record accordingly.

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.

IRSpy/Test/Search/Title.pm

A simple test of title-searching.

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 zebra directory. It consists of a distressingly large number of files, all of which are described in that directory's README file.

CRUD

There is also a ZOOM::XML::Simple module, but it's unfinished and unused.

SEE ALSO

ZOOM::IRSpy, ZOOM::Pod, HTML::Mason

AUTHOR

Mike Taylor, <mike@indexdata.com>

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.

cpanm ZOOM::IRSpy

perl -MCPAN -e shell
install ZOOM::IRSpy