ZOOM::IRSpy::Maintenance - maintenance documentation for IRSpy
The IRSpy application is implemented by five components:
ZOOM::Pod, which is used by IRSpy and which is more conveniently included in this distribution than released and maintained separately.
These components are discussed in turn.
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.
There is only one command-line interface to the IRSpy library,
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
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 web interface is built using the
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:
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).
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
If you've put it elsewhere,
you'll need to either make a symbolic link or tweak the configuration.
The Document Root containing actual page that make up the UI.
These pages are HTML containing embedded Perl,
as enabled by the
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.
Temporary files generated by the
You may need to tweak the permissions of this directory to get things to work properly.
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
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
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.
Do you really need a section about this file?
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.
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.
Directory containing plugins for specific tests.
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.
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.
Directory containing plugins for specific tests of searching. In time, we will probably have analogous directories for retrieval tests, extended services tests. etc.
A simple test of title-searching.
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
There is also a
ZOOM::XML::Simple module, but it's unfinished and unused.
Mike Taylor, <email@example.com>
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.