lib/ZOOM/IRSpy/Task.pm

   1 # $Id: Task.pm,v 1.7 2007-08-01 15:11:03 mike Exp $
   2
   3 package ZOOM::IRSpy::Task;
   4
   5 use 5.008;
   6 use strict;
   7 use warnings;
   8
   9 =head1 NAME
  10
  11 ZOOM::IRSpy::Task - base class for tasks in IRSpy
  12
  13 =head1 SYNOPSIS
  14
  15  use ZOOM::IRSpy::Task;
  16  package ZOOM::IRSpy::Task::SomeTask;
  17  our @ISA = qw(ZOOM::IRSpy::Task);
  18  # ... override methods
  19
  20 =head1 DESCRIPTION
  21
  22 This class provides a base-class from which individual IRSpy task
  23 classes can be derived.  For example, C<ZOOM::IRSpy::Task::Search>
  24 will represent a searching task, carrying with it a query, a pointer
  25 to a result-set, etc.
  26
  27 The base class provides nothing more exciting than a link to a
  28 callback function to be called when the task is complete, and a
  29 pointer to the next task to be performed after this.
  30
  31 =cut
  32
  33 sub new {
  34     my $class = shift();
  35     my($conn, $udata, $options, %cb) = @_;
  36
  37     return bless {
  38         irspy => $conn->{irspy},
  39         conn => $conn,
  40         udata => $udata,
  41         options => $options,
  42         cb => \%cb,
  43         timeRegistered => time(),
  44     }, $class;
  45 }
  46
  47
  48 sub irspy {
  49     my $this = shift();
  50     return $this->{irspy};
  51 }
  52
  53 sub conn {
  54     my $this = shift();
  55     return $this->{conn};
  56 }
  57
  58 sub udata {
  59     my $this = shift();
  60     return $this->{udata};
  61 }
  62
  63 sub run {
  64     my $this = shift();
  65     die "can't run base-class task $this";
  66 }
  67
  68 # In general, this sets the Connection's options to what is in the
  69 # task's option hash and sets the option-hash entry to the
  70 # Connection's old value of the option: this means that calling this
  71 # twice restores the state to how it was before.  (That's not quite
  72 # true as its impossible to unset an option that was previously set:
  73 # such options are instead set to the empty string.)
  74 #
  75 # As a special case, options in the task's option-hash whose names
  76 # begin with an asterisk are taken to be persistent: they are set into
  77 # the Connection (with the leading hash removed) and deleted from the
  78 # task's option-hash so that they will NOT be reset the next time this
  79 # function is called.
  80 #
  81 sub set_options {
  82     my $this = shift();
  83
  84     foreach my $key (sort keys %{ $this->{options} }) {
  85         my $value = $this->{options}->{$key};
  86         my $persistent = ($key =~ s/^\*//);
  87         $value = "" if !defined $value;
  88         $this->conn()->log("irspy_debug", "$this setting option '$key' -> ",
  89                            defined $value ? "'$value'" : "undefined");
  90         my $old = $this->conn()->option($key, $value);
  91         if ($persistent) {
  92             delete $this->{options}->{"*$key"}
  93         } else {
  94             $this->{options}->{$key} = $old;
  95         }
  96     }
  97 }
  98
  99 sub render {
 100     my $this = shift();
 101     return "[base-class] " . ref($this);
 102 }
 103
 104 use overload '""' => \&render;
 105
 106
 107 =head1 SEE ALSO
 108
 109 ZOOM::IRSpy
 110
 111 =head1 AUTHOR
 112
 113 Mike Taylor, E<lt>mike@indexdata.comE<gt>
 114
 115 =head1 COPYRIGHT AND LICENSE
 116
 117 Copyright (C) 2006 by Index Data ApS.
 118
 119 This library is free software; you can redistribute it and/or modify
 120 it under the same terms as Perl itself, either Perl version 5.8.7 or,
 121 at your option, any later version of Perl 5 you may have available.
 122
 123 =cut
 124
 125 1;