lib/ZOOM/IRSpy/Maintenance.pod

   1 # $Id: Maintenance.pod,v 1.4 2006-09-18 10:27:57 mike Exp $
   2
   3 package ZOOM::IRSpy::Maintenance;
   4
   5 =head1 NAME
   6
   7 ZOOM::IRSpy::Maintenance - maintenance documentation for IRSpy
   8
   9 =head1 INTRODUCTION
  10
  11 The IRSpy application is implemented by five components:
  12
  13 =over 4
  14
  15 =item *
  16
  17 A library of classes within the C<ZOOM::IRSpy> "namespace".
  18
  19 =item *
  20
  21 A command-line invocation script called C<irspy>
  22
  23 =item *
  24
  25 A web-based UI - either this or the command-line script can be used to
  26 run the spy software, but the latter is more capable in that it also
  27 provides ways to interrogate the database of results.
  28
  29 =item *
  30
  31 A small additional library, C<ZOOM::Pod>, which is used by IRSpy and
  32 which is more conveniently included in this distribution than released
  33 and maintained separately.
  34
  35 =item *
  36
  37 The configuration for a Zebra database that stores the harvested
  38 information.
  39
  40 =back
  41
  42 These components are discussed in turn.
  43
  44 =head1 THE ZOOM::POD LIBRARY
  45
  46 Provides a simple API to ZOOM-Perl's asynchronous multiplexing.  This
  47 is documented in its own manual page.  It shouldn't need any
  48 maintenance, as it was written and tested independently of the rest of
  49 IRSpy.
  50
  51 =head1 THE IRSPY COMMAND-LINE TOOL
  52
  53 There is only one command-line interface to the IRSpy library, the
  54 C<irspy.pl> program which is provided in the C<bin> directory of the
  55 distribution.
  56
  57 There are other programs in that directory, but they are all tests, of
  58 little interest now.  The original of these is C<test-pod.pl> which is
  59 a script to exercise the C<ZOOM::Pod> library.  When this script
  60 uncovered a subtle bug in ZOOM-C, I needed to isolate the bug in a
  61 form that would be easy for Adam to see, so I made a sequence of
  62 derivatives of this test-script, each of them functionally equivalent,
  63 coming closer and closer to the metal: C<test-zoom.pl> unrolled the
  64 Pod code into a script that uses the pure ZOOM-Perl API;
  65 C<test-net-z3950-zoom.pl> is the low-level version of this, using the
  66 ZOOM-C-like C<Net::Z3950::ZOOM> API rather than the object-oriented
  67 C<ZOOM> API; and C<test-zoom-c.c> is a translation of this into C,
  68 using the ZOOM-C API directly.
  69
  70 =head1 THE IRSPY WEB INTERFACE
  71
  72 The web interface is built using the C<HTML::Mason> module, a
  73 framework that allows Perl to be embedded in web-pages much like PHP.
  74 To install this on a Debian-based operating system it should suffice
  75 to C<apt-get install libhtml-mason-perl>.
  76
  77 The components of this interface can be found in the C<web> directory
  78 (well, who'd have thought?) which in turn contains the following
  79 directories:
  80
  81 =over 4
  82
  83 =item conf
  84
  85 Sample configuration for wiring the UI into a web-server.  The
  86 subdirectories name specific web-servers (e.g. C<apache1.3>) and the
  87 files within are named after the particular hosts where they are known
  88 to work (but will in general work on other hosts).  For example,
  89 C<conf/apache1.3/xeno.conf> is an Apache 1.3 configuration for xeno,
  90 my desktop development box; but it should work just fine on any Ubuntu
  91 6.06 box, probably on any Ubuntu box, and most likely on anything
  92 running any Debian-based Linux distribution.
  93
  94 The sample configurations assume that IRSpy is unpacked into the
  95 C</usr/local/src/cvs/irspy> directory.  If you've put it elsewhere,
  96 you'll need to either make a symbolic link or tweak the configuration.
  97
  98 =item htdocs
  99
 100 The Document Root containing actual page that make up the UI.  These
 101 pages are HTML containing embedded Perl, as enabled by the
 102 C<HTML::Mason> module.
 103
 104 =item logs
 105
 106 Logs generated by the web server are directed here by the provided
 107 sample configurations.
 108 You may need to tweak the permissions of this directory to get things
 109 to work properly.
 110
 111 =item data
 112
 113 Temporary files generated by the C<HTML::Mason> module.
 114 You may need to tweak the permissions of this directory to get things
 115 to work properly.
 116
 117 =back
 118
 119 =head1 THE IRSPY LIBRARY
 120
 121 The IRSpy library does the bulk of the work in this software: the
 122 command-line and web interfaces are both as thin as possible, relying
 123 on the library; and the C<ZOOM::Pod> library is small and
 124 self-contained.  The library is contained in the C<lib> directory.
 125
 126 The library consists of the following hierarchy of classes:
 127
 128         IRSpy.pm -- the controlling class
 129          IRSpy/Maintenance.pod -- this document
 130          IRSpy/Record.pm -- a record of a probed database
 131          IRSpy/Test.pm -- base class for individual tests
 132          IRSpy/Test -- contains individual tests
 133           IRSpy/Test/Main.pm -- the top-level test, calls others
 134           IRSpy/Test/Ping.pm -- simplest test: checks server is alive
 135           IRSpy/Test/Search -- contains tests for searching
 136            IRSpy/Test/Search/Title.pm -- test for title search
 137
 138 =head2 IRSpy.pm
 139
 140 The main class, and the only one used directly by the command-line
 141 application.  And C<IRSpy> object represents a connection to a
 142 database of extended ZeeRex records, together with a set of
 143 connections to target databases being tested.
 144
 145 With the aid of C<IRSpy/Record.pm>, this class implements a framework
 146 within which separately authored tests may be run, the tests running
 147 sequentially but with all connections attempting each test in parallel
 148 - i.e. all connections must complete a given test (whether
 149 successfully or not) before the next test is begun.
 150
 151 =head2 IRSpy/Maintenance.pod
 152
 153 Do you really need a section about this file?
 154
 155 =head2 IRSpy/Record.pm
 156
 157 Represents a record describing a target database, based on an extended
 158 ZeeRex record.  Includes the results of the tests that have been run
 159 during the current session.
 160
 161 =head2 IRSpy/Test.pm
 162
 163 This is an abstract base-class that is used by all the concrete
 164 classes implementing specific tests.  Its principle purpose is to
 165 provide the C<run_tests()> method whereby high-level tests such as
 166 C<Main> can invoke lower-level tests.
 167
 168 =head2 IRSpy/Test
 169
 170 Directory containing plugins for specific tests.
 171
 172 =head2 IRSpy/Test/Main.pm
 173
 174 The top-level test: running an IRSpy object (by calling its C<check()>
 175 method) consists of running the C<Main> test, then writing the results
 176 of that test back to the database.  This test itself does nothing but
 177 call lower-level tests, using the C<run_tests()> method provided by
 178 its superclass.
 179
 180 =head2 IRSpy/Test/Ping.pm
 181
 182 The simplest of all the "real" tests (i.e. not including C<Main>) and
 183 good one to use as a template when developing new tests.  It tests
 184 whether the target can be connected to, using C<ZOOM::Pod> callbacks
 185 to be notified of each target's success or failure, and updates the
 186 associated record accordingly.
 187
 188 =head2 IRSpy/Test/Search
 189
 190 Directory containing plugins for specific tests of searching.  In
 191 time, we will probably have analogous directories for retrieval tests,
 192 extended services tests. etc.
 193
 194 =head2 IRSpy/Test/Search/Title.pm
 195
 196 A simple test of title-searching.
 197
 198 =cut
 199
 200 =head1 DATABASE
 201
 202 The results of IRSpy's probing are held in a Zebra database of
 203 extended ZeeRex records: these mostly conform to the ZeeRex schema as
 204 described on the website at http://explain.z3950.org/dtd/ but are
 205 extended with additional elements to store the results of various
 206 tests.
 207
 208 The configuration for the Zebra database is found in the C<zebra>
 209 directory.  It consists of a distressingly large number of files, all
 210 of which are described in that directory's C<README> file.
 211
 212 =head1 CRUD
 213
 214 There is also a C<ZOOM::XML::Simple> module, but it's unfinished and
 215 unused.
 216
 217 =head1 SEE ALSO
 218
 219 C<ZOOM::IRSpy>,
 220 C<ZOOM::Pod>,
 221 C<HTML::Mason>
 222
 223 =head1 AUTHOR
 224
 225 Mike Taylor, E<lt>mike@indexdata.comE<gt>
 226
 227 =head1 COPYRIGHT AND LICENSE
 228
 229 Copyright (C) 2006 by Index Data ApS.
 230
 231 This library is free software; you can redistribute it and/or modify
 232 it under the same terms as Perl itself, either Perl version 5.8.7 or,
 233 at your option, any later version of Perl 5 you may have available.
 234
 235 =cut
 236
 237 1;