C4/BackgroundJob.pm

   1 package C4::BackgroundJob;
   2
   3 # Copyright (C) 2007 LibLime
   4 # Galen Charlton <galen.charlton@liblime.com>
   5 #
   6 # This file is part of Koha.
   7 #
   8 # Koha is free software; you can redistribute it and/or modify it under the
   9 # terms of the GNU General Public License as published by the Free Software
  10 # Foundation; either version 2 of the License, or (at your option) any later
  11 # version.
  12 #
  13 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
  14 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  15 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License along with
  18 # Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
  19 # Suite 330, Boston, MA  02111-1307 USA
  20
  21 use strict;
  22 use C4::Context;
  23 use C4::Auth qw/get_session/;
  24 use Digest::MD5;
  25
  26 use vars qw($VERSION);
  27
  28 # set the version for version checking
  29 $VERSION = 3.00;
  30
  31 =head1 NAME
  32
  33 C4::BackgroundJob - manage long-running jobs
  34 initiated from the web staff interface
  35
  36 =head1 SYNOPSIS
  37
  38 =over 4
  39
  40 # start tracking a job
  41 my $job = C4::BackgroundJob->new($sessionID, $job_name, $job_invoker, $num_work_units);
  42 my $jobID = $job->id();
  43 $job->progress($work_units_processed);
  44 $job->finish($job_result_hashref);
  45
  46 # get status and results of a job
  47 my $job = C4::BackgroundJob->fetch($sessionID, $jobID);
  48 my $max_work_units = $job->size();
  49 my $work_units_processed = $job->progress();
  50 my $job_status = $job->status();
  51 my $job_name = $job->name();
  52 my $job_invoker = $job->invoker();
  53 my $results_hashref = $job->results();
  54
  55 =back
  56
  57 This module manages tracking the progress and results
  58 of (potentially) long-running jobs initiated from
  59 the staff user interface.  Such jobs can include
  60 batch MARC and patron record imports.
  61
  62 =cut
  63
  64 =head1 METHODS
  65
  66 =cut
  67
  68 =head2 new
  69
  70 =over 4
  71
  72 my $job = C4::BackgroundJob->new($sessionID, $job_name, $job_invoker, $num_work_units);
  73
  74 =back
  75
  76 Create a new job object and set its status to 'running'.  C<$num_work_units>
  77 should be a number representing the size of the job; the units of the
  78 job size are up to the caller and could be number of records,
  79 number of bytes, etc.
  80
  81 =cut
  82
  83 sub new {
  84     my $class = shift;
  85     my ($sessionID, $job_name, $job_invoker, $num_work_units) = @_;
  86
  87     my $self = {};
  88     $self->{'sessionID'} = $sessionID;
  89     $self->{'name'} = $job_name;
  90     $self->{'invoker'} = $job_invoker;
  91     $self->{'size'} = $num_work_units;
  92     $self->{'progress'} = 0;
  93     $self->{'status'} = "running";
  94     $self->{'jobID'} = Digest::MD5::md5_hex(Digest::MD5::md5_hex(time().{}.rand().{}.$$));
  95
  96     bless $self, $class;
  97     $self->_serialize();
  98
  99     return $self;
 100 }
 101
 102 # store object in CGI session
 103 sub _serialize {
 104     my $self = shift;
 105
 106     my $prefix = "job_" . $self->{'jobID'};
 107     my $session = get_session($self->{'sessionID'});
 108     $session->param($prefix, $self);
 109     $session->flush();
 110 }
 111
 112 =head2 id
 113
 114 =over 4
 115
 116 my $jobID = $job->id();
 117
 118 =back
 119
 120 Read-only accessor for job ID.
 121
 122 =cut
 123
 124 sub id {
 125     my $self = shift;
 126     return $self->{'jobID'};
 127 }
 128
 129 =head2 name
 130
 131 =over 4
 132
 133 my $name = $job->name();
 134 $job->name($name);
 135
 136 =back
 137
 138 Read/write accessor for job name.
 139
 140 =cut
 141
 142 sub name {
 143     my $self = shift;
 144     if (@_) {
 145         $self->{'name'} = shift;
 146         $self->_serialize();
 147     } else {
 148         return $self->{'name'};
 149     }
 150 }
 151
 152 =head2 invoker
 153
 154 =over 4
 155
 156 my $invoker = $job->invoker();
 157 $job->invoker($invoker);
 158
 159 =back
 160
 161 Read/write accessor for job invoker.
 162
 163 =cut
 164
 165 sub invoker {
 166     my $self = shift;
 167     if (@_) {
 168         $self->{'invoker'} = shift;
 169         $self->_serialize();
 170     } else {
 171         return $self->{'invoker'};
 172     }
 173 }
 174
 175 =head2 progress
 176
 177 =over 4
 178
 179 my $progress = $job->progress();
 180 $job->progress($progress);
 181
 182 =back
 183
 184 Read/write accessor for job progress.
 185
 186 =cut
 187
 188 sub progress {
 189     my $self = shift;
 190     if (@_) {
 191         $self->{'progress'} = shift;
 192         $self->_serialize();
 193     } else {
 194         return $self->{'progress'};
 195     }
 196 }
 197
 198 =head2 status
 199
 200 =over 4
 201
 202 my $status = $job->status();
 203
 204 =back
 205
 206 Read-only accessor for job status.
 207
 208 =cut
 209
 210 sub status {
 211     my $self = shift;
 212     return $self->{'status'};
 213 }
 214
 215 =head2 size
 216
 217 =over 4
 218
 219 my $size = $job->size();
 220 $job->size($size);
 221
 222 =back
 223
 224 Read/write accessor for job size.
 225
 226 =cut
 227
 228 sub size {
 229     my $self = shift;
 230     if (@_) {
 231         $self->{'size'} = shift;
 232         $self->_serialize();
 233     } else {
 234         return $self->{'size'};
 235     }
 236 }
 237
 238 =head2 finish
 239
 240 =over 4
 241
 242 $job->finish($results_hashref);
 243
 244 =back
 245
 246 Mark the job as finished, setting its status to 'completed'.
 247 C<$results_hashref> should be a reference to a hash containing
 248 the results of the job.
 249
 250 =cut
 251
 252 sub finish {
 253     my $self = shift;
 254     my $results_hashref = shift;
 255     $self->{'status'} = 'completed';
 256     $self->{'results'} = $results_hashref;
 257     $self->_serialize();
 258 }
 259
 260 =head2 results
 261
 262 =over 4
 263
 264 my $results_hashref = $job->results();
 265
 266 =back
 267
 268 Retrieve the results of the current job.  Returns undef
 269 if the job status is not 'completed'.
 270
 271 =cut
 272
 273 sub results {
 274     my $self = shift;
 275     return undef unless $self->{'status'} eq 'completed';
 276     return $self->{'results'};
 277 }
 278
 279 =head2 fetch
 280
 281 =over 4
 282
 283 my $job = C4::BackgroundJob->fetch($sessionID, $jobID);
 284
 285 =back
 286
 287 Retrieve a job that has been serialized to the database.
 288 Returns C<undef> if the job does not exist in the current
 289 session.
 290
 291 =cut
 292
 293 sub fetch {
 294     my $class = shift;
 295     my $sessionID = shift;
 296     my $jobID = shift;
 297
 298     my $session = get_session($sessionID);
 299     my $prefix = "job_$jobID";
 300     unless (defined $session->param($prefix)) {
 301         return undef;
 302     }
 303     my $self = $session->param($prefix);
 304     bless $self, $class;
 305     return $self;
 306 }
 307
 308 =head1 AUTHOR
 309
 310 Koha Development Team <info@koha.org>
 311
 312 Galen Charlton <galen.charlton@liblime.com>
 313
 314 =cut