lib/ZOOM/IRSpy.pm

   1 # $Id: IRSpy.pm,v 1.1 2006-06-20 12:27:12 mike Exp $
   2
   3 package Net::Z3950::IRSpy;
   4
   5 use 5.008;
   6 use strict;
   7 use warnings;
   8 use Net::Z3950::IRSpy::Record;
   9 use ZOOM::Pod;
  10
  11 our @ISA = qw();
  12 our $VERSION = '0.02';
  13
  14 =head1 NAME
  15
  16 Net::Z3950::IRSpy - Perl extension for discovering and analysing IR services
  17
  18 =head1 SYNOPSIS
  19
  20  use Net::Z3950::IRSpy;
  21  $spy = new Net::Z3950::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 and targets will be filled in later
  45     }, $class;
  46     $this->log("irspy", "starting up with database '$dbname'");
  47
  48     return $this;
  49 }
  50
  51
  52 sub log {
  53     my $this = shift();
  54     ZOOM::Log::log(@_);
  55 }
  56
  57
  58 # Explicitly nominate a set of targets to check, overriding the
  59 # default which is to re-check everything in the database.  Each
  60 # target already in the database results in the existing record being
  61 # updated; each new target causes a new record to be added.
  62 #
  63 sub targets {
  64     my $this = shift();
  65     my($targetList) = @_;
  66
  67     $this->log("irspy", "setting explicit list of targets '$targetList'");
  68     $this->{allrecords} = 0;
  69     my @targets = split /\s+/, $targetList;
  70     my @qlist;
  71     foreach my $target (@targets) {
  72         my($host, $port, $db) = ($target =~ /(.*?):(.*?)\/(.*)/);
  73         if (!defined $host) {
  74             $port = 210;
  75             ($host, $db) = ($target =~ /(.*?)\/(.*)/);
  76             $this->log("irspy", "rewrote '$target' to '$host:$port/$db'");
  77             $target = "$host:$port/$db";
  78         }
  79         die "invalid target string '$target'"
  80             if !defined $host;
  81         push @qlist,
  82             (qq[(host = "$host" and port = "$port" and path="$db")]);
  83     }
  84
  85     $this->{targets} = \@targets;
  86     $this->{query} = join(" or ", @qlist);
  87 }
  88
  89
  90 # There are two cases.
  91 #
  92 # 1. A specific set of targets is nominated on the command line.
  93 #       - Records must be fetched for those targets that are in the DB
  94 #       - New, empty records must be made for those that are not.
  95 #       - Updated records written to the DB may or may not be new.
  96 #
  97 # 2. All records in the database are to be checked.
  98 #       - Records must be fetched for all targets in the DB
  99 #       - Updated records written to the DB may not be new.
 100 #
 101 # That's all -- what could be simpler?
 102 #
 103 sub initialise {
 104     my $this = shift();
 105
 106     my %target2record;
 107     if ($this->{allrecords}) {
 108         # We need to check on every target in the database, which
 109         # means we need to do a "find all".  According to the BIB-1
 110         # semantics document at
 111         #       http://www.loc.gov/z3950/agency/bib1.html
 112         # the query
 113         #       @attr 2=103 @attr 1=1035 x
 114         # should find all records, but it seems that Zebra doesn't
 115         # support this.  Furthermore, when using the "alvis" filter
 116         # (as we do for IRSpy) it doesn't support the use of any BIB-1
 117         # access point -- not even 1035 "everywhere" -- so instead we
 118         # hack together a search that we know will find all records.
 119         $this->{query} = "port=?*";
 120     } else {
 121         # Prepopulate the target map with nulls so that after we fill
 122         # in what we can from the database query, we know which target
 123         # IDs we need new records for.
 124         foreach my $target (@{ $this->{targets} }) {
 125             $target2record{lc($target)} = undef;
 126         }
 127     }
 128
 129     my $rs = $this->{conn}->search(new ZOOM::Query::CQL($this->{query}));
 130     foreach my $i (1 .. $rs->size()) {
 131         my $target = _render_record($rs, $i-1, "id");
 132         my $zeerex = _render_record($rs, $i-1, "zeerex");
 133         $target2record{lc($target)} =
 134             new Net::Z3950::IRSpy::Record($target, $zeerex);
 135     }
 136
 137     foreach my $target (keys %target2record) {
 138         my $record = $target2record{$target};
 139         if (!defined $record) {
 140             $this->log("irspy", "new record for '$target'");
 141             $target2record{$target} = new Net::Z3950::IRSpy::Record($target);
 142         } else {
 143             $this->log("irspy", "existing record for '$target' $record");
 144         }
 145     }
 146 }
 147
 148
 149 sub check {
 150     my $this = shift();
 151
 152     $this->{pod} = new ZOOM::Pod(@{ $this->{targets} })
 153 }
 154
 155
 156 sub _render_record {
 157     my($rs, $which, $elementSetName) = @_;
 158
 159     # There is a slight race condition here on the element-set name,
 160     # but it shouldn't be a problem as this is (currently) only called
 161     # from parts of the program that run single-threaded.
 162     my $old = $rs->option(elementSetName => $elementSetName);
 163     my $rec = $rs->record($which);
 164     $rs->option(elementSetName => $old);
 165
 166     return $rec->render();
 167 }
 168
 169
 170 #my $pod = new ZOOM::Pod(@ARGV);
 171 #$pod->option(elementSetName => "b");
 172 #$pod->callback(ZOOM::Event::RECV_SEARCH, \&completed_search);
 173 #$pod->callback(ZOOM::Event::RECV_RECORD, \&got_record);
 174 ##$pod->callback(exception => \&exception_thrown);
 175 #$pod->search_pqf("the");
 176 #my $err = $pod->wait();
 177 #die "$pod->wait() failed with error $err" if $err;
 178 #
 179 #sub completed_search {
 180 #    my($conn, $state, $rs, $event) = @_;
 181 #    print $conn->option("host"), ": found ", $rs->size(), " records\n";
 182 #    $state->{next_to_fetch} = 0;
 183 #    $state->{next_to_show} = 0;
 184 #    request_records($conn, $rs, $state, 2);
 185 #    return 0;
 186 #}
 187 #
 188 #sub got_record {
 189 #    my($conn, $state, $rs, $event) = @_;
 190 #
 191 #    {
 192 #       # Sanity-checking assertions.  These should be impossible
 193 #       my $ns = $state->{next_to_show};
 194 #       my $nf = $state->{next_to_fetch};
 195 #       if ($ns > $nf) {
 196 #           die "next_to_show > next_to_fetch ($ns > $nf)";
 197 #       } elsif ($ns == $nf) {
 198 #           die "next_to_show == next_to_fetch ($ns)";
 199 #       }
 200 #    }
 201 #
 202 #    my $i = $state->{next_to_show}++;
 203 #    my $rec = $rs->record($i);
 204 #    print $conn->option("host"), ": record $i is ", render_record($rec), "\n";
 205 #    request_records($conn, $rs, $state, 3)
 206 #       if $i == $state->{next_to_fetch}-1;
 207 #
 208 #    return 0;
 209 #}
 210 #
 211 #sub exception_thrown {
 212 #    my($conn, $state, $rs, $exception) = @_;
 213 #    print "Uh-oh!  $exception\n";
 214 #    return 0;
 215 #}
 216 #
 217 #sub request_records {
 218 #    my($conn, $rs, $state, $count) = @_;
 219 #
 220 #    my $i = $state->{next_to_fetch};
 221 #    ZOOM::Log::log("irspy", "requesting $count records from $i");
 222 #    $rs->records($i, $count, 0);
 223 #    $state->{next_to_fetch} += $count;
 224 #}
 225 #
 226 #sub render_record {
 227 #    my($rec) = @_;
 228 #
 229 #    return "undefined" if !defined $rec;
 230 #    return "'" . $rec->render() . "'";
 231 #}
 232
 233
 234 =head1 SEE ALSO
 235
 236 Net::Z3950::IRSpy::Record
 237
 238 The ZOOM-Perl module,
 239 http://search.cpan.org/~mirk/Net-Z3950-ZOOM/
 240
 241 The Zebra Database,
 242 http://indexdata.com/zebra/
 243
 244 =head1 AUTHOR
 245
 246 Mike Taylor, E<lt>mike@indexdata.comE<gt>
 247
 248 =head1 COPYRIGHT AND LICENSE
 249
 250 Copyright (C) 2006 by Index Data ApS.
 251
 252 This library is free software; you can redistribute it and/or modify
 253 it under the same terms as Perl itself, either Perl version 5.8.7 or,
 254 at your option, any later version of Perl 5 you may have available.
 255
 256 =cut
 257
 258 1;