lib/ZOOM/IRSpy.pm

   1 # $Id: IRSpy.pm,v 1.4 2006-06-21 14:35:03 mike Exp $
   2
   3 package ZOOM::IRSpy;
   4
   5 use 5.008;
   6 use strict;
   7 use warnings;
   8 use ZOOM::IRSpy::Record;
   9 use ZOOM::Pod;
  10
  11 our @ISA = qw();
  12 our $VERSION = '0.02';
  13
  14 =head1 NAME
  15
  16 ZOOM::IRSpy - Perl extension for discovering and analysing IR services
  17
  18 =head1 SYNOPSIS
  19
  20  use ZOOM::IRSpy;
  21  $spy = new ZOOM::IRSpy("target/string/for/irspy/database");
  22  print $spy->report_status();
  23
  24 =head1 DESCRIPTION
  25
  26 This module exists to implement the IRspy program, which discovers,
  27 analyses and monitors IR servers implementing the Z39.50 and SRU/W
  28 protocols.  It is a successor to the ZSpy program.
  29
  30 =cut
  31
  32 BEGIN { ZOOM::Log::mask_str("irspy") }
  33
  34 sub new {
  35     my $class = shift();
  36     my($dbname) = @_;
  37
  38     my $conn = new ZOOM::Connection($dbname)
  39         or die "$0: can't connection to IRSpy database 'dbname'";
  40
  41     my $this = bless {
  42         conn => $conn,
  43         allrecords => 1,        # unless overridden by targets()
  44         query => undef,         # filled in later
  45         targets => undef,       # filled in later
  46         target2record => undef, # filled in later
  47         pod => undef,           # filled in later
  48     }, $class;
  49     $this->log("irspy", "starting up with database '$dbname'");
  50
  51     return $this;
  52 }
  53
  54
  55 sub log {
  56     my $this = shift();
  57     ZOOM::Log::log(@_);
  58 }
  59
  60
  61 # Explicitly nominate a set of targets to check, overriding the
  62 # default which is to re-check everything in the database.  Each
  63 # target already in the database results in the existing record being
  64 # updated; each new target causes a new record to be added.
  65 #
  66 sub targets {
  67     my $this = shift();
  68     my($targetList) = @_;
  69
  70     $this->log("irspy", "setting explicit list of targets '$targetList'");
  71     $this->{allrecords} = 0;
  72     my @targets = split /\s+/, $targetList;
  73     my @qlist;
  74     foreach my $target (@targets) {
  75         my($host, $port, $db) = ($target =~ /(.*?):(.*?)\/(.*)/);
  76         if (!defined $host) {
  77             $port = 210;
  78             ($host, $db) = ($target =~ /(.*?)\/(.*)/);
  79             $this->log("irspy", "rewrote '$target' to '$host:$port/$db'");
  80             $target = "$host:$port/$db";
  81         }
  82         die "invalid target string '$target'"
  83             if !defined $host;
  84         push @qlist,
  85             (qq[(host = "$host" and port = "$port" and path="$db")]);
  86     }
  87
  88     $this->{targets} = \@targets;
  89     $this->{query} = join(" or ", @qlist);
  90 }
  91
  92
  93 # There are two cases.
  94 #
  95 # 1. A specific set of targets is nominated on the command line.
  96 #       - Records must be fetched for those targets that are in the DB
  97 #       - New, empty records must be made for those that are not.
  98 #       - Updated records written to the DB may or may not be new.
  99 #
 100 # 2. All records in the database are to be checked.
 101 #       - Records must be fetched for all targets in the DB
 102 #       - Updated records written to the DB may not be new.
 103 #
 104 # That's all -- what could be simpler?
 105 #
 106 sub initialise {
 107     my $this = shift();
 108
 109     my %target2record;
 110     if ($this->{allrecords}) {
 111         # We need to check on every target in the database, which
 112         # means we need to do a "find all".  According to the BIB-1
 113         # semantics document at
 114         #       http://www.loc.gov/z3950/agency/bib1.html
 115         # the query
 116         #       @attr 2=103 @attr 1=1035 x
 117         # should find all records, but it seems that Zebra doesn't
 118         # support this.  Furthermore, when using the "alvis" filter
 119         # (as we do for IRSpy) it doesn't support the use of any BIB-1
 120         # access point -- not even 1035 "everywhere" -- so instead we
 121         # hack together a search that we know will find all records.
 122         $this->{query} = "port=?*";
 123     } else {
 124         # Prepopulate the target map with nulls so that after we fill
 125         # in what we can from the database query, we know which target
 126         # IDs we need new records for.
 127         foreach my $target (@{ $this->{targets} }) {
 128             $target2record{lc($target)} = undef;
 129         }
 130     }
 131
 132     my $rs = $this->{conn}->search(new ZOOM::Query::CQL($this->{query}));
 133     foreach my $i (1 .. $rs->size()) {
 134         my $target = _render_record($rs, $i-1, "id");
 135         my $zeerex = _render_record($rs, $i-1, "zeerex");
 136         $target2record{lc($target)} =
 137             new ZOOM::IRSpy::Record($target, $zeerex);
 138     }
 139
 140     foreach my $target (keys %target2record) {
 141         my $record = $target2record{$target};
 142         if (!defined $record) {
 143             $this->log("irspy", "made new record for '$target'");
 144             $target2record{$target} = new ZOOM::IRSpy::Record($target);
 145         } else {
 146             $this->log("irspy", "using existing record for '$target'");
 147         }
 148     }
 149
 150     $this->{target2record} = \%target2record;
 151     $this->{pod} = new ZOOM::Pod(@{ $this->{targets} });
 152     delete $this->{targets};    # The information is now in the Pod.
 153     delete $this->{query};      # Not needed at all
 154 }
 155
 156
 157 sub _render_record {
 158     my($rs, $which, $elementSetName) = @_;
 159
 160     # There is a slight race condition here on the element-set name,
 161     # but it shouldn't be a problem as this is (currently) only called
 162     # from parts of the program that run single-threaded.
 163     my $old = $rs->option(elementSetName => $elementSetName);
 164     my $rec = $rs->record($which);
 165     $rs->option(elementSetName => $old);
 166
 167     return $rec->render();
 168 }
 169
 170
 171 # Returns:
 172 #       0 all tests successfully run
 173 #       1 some tests skipped
 174 #
 175 sub check {
 176     my $this = shift();
 177
 178     return $this->_run_test("Main");
 179 }
 180
 181
 182 sub _run_test {
 183     my $this = shift();
 184     my($tname) = @_;
 185
 186     eval {
 187         require "ZOOM/IRSpy/Test/$tname.pm";
 188     }; if ($@) {
 189         $this->log("warn", "can't load test '$tname': skipping",
 190                    $@ =~ /^Can.t locate/ ? () : " ($@)");
 191         return 1;
 192     }
 193
 194     $this->log("irspy", "running test '$tname'");
 195     my $test = "ZOOM::IRSpy::Test::$tname"->new($this);
 196     return $test->run();
 197 }
 198
 199
 200 # Access methods for the use of Test modules
 201 sub pod {
 202     my $this = shift();
 203     return $this->{pod};
 204 }
 205
 206 sub record {
 207     my $this = shift();
 208     my($target) = @_;
 209     return $this->{target2record}->{$target};
 210 }
 211
 212
 213
 214 =head1 SEE ALSO
 215
 216 ZOOM::IRSpy::Record
 217
 218 The ZOOM-Perl module,
 219 http://search.cpan.org/~mirk/Net-Z3950-ZOOM/
 220
 221 The Zebra Database,
 222 http://indexdata.com/zebra/
 223
 224 =head1 AUTHOR
 225
 226 Mike Taylor, E<lt>mike@indexdata.comE<gt>
 227
 228 =head1 COPYRIGHT AND LICENSE
 229
 230 Copyright (C) 2006 by Index Data ApS.
 231
 232 This library is free software; you can redistribute it and/or modify
 233 it under the same terms as Perl itself, either Perl version 5.8.7 or,
 234 at your option, any later version of Perl 5 you may have available.
 235
 236 =cut
 237
 238 1;