lib/ZOOM/IRSpy/Maintenance.pod

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