1 package C4::BackgroundJob;
3 # Copyright (C) 2007 LibLime
4 # Galen Charlton <galen.charlton@liblime.com>
6 # This file is part of Koha.
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
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.
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
23 use C4::Auth qw/get_session/;
26 use vars qw($VERSION);
28 # set the version for version checking
33 C4::BackgroundJob - manage long-running jobs
34 initiated from the web staff interface
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);
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();
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.
72 my $job = C4::BackgroundJob->new($sessionID, $job_name, $job_invoker, $num_work_units);
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,
85 my ($sessionID, $job_name, $job_invoker, $num_work_units) = @_;
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().{}.$$));
102 # store object in CGI session
106 my $prefix = "job_" . $self->{'jobID'};
107 my $session = get_session($self->{'sessionID'});
108 $session->param("$prefix.name", $self->{'name'});
109 $session->param("$prefix.invoker", $self->{'invoker'});
110 $session->param("$prefix.size", $self->{'size'});
111 $session->param("$prefix.progress", $self->{'size'});
112 $session->param("$prefix.status", $self->{'size'});
113 if (exists $self->{'results'}) {
115 foreach my $key (keys %{ $self->{'results'} }) {
116 $session->param("$prefix.results.$key", $self->{'results'}->{$key});
119 $session->param("$prefix.results_keys", join("\t", @keys));
128 my $jobID = $job->id();
132 Read-only accessor for job ID.
138 return $self->{'id'};
145 my $name = $job->name();
150 Read/write accessor for job name.
157 $self->{'name'} = shift;
160 return $self->{'name'};
168 my $invoker = $job->invoker();
169 $job->invoker($invoker);
173 Read/write accessor for job invoker.
180 $self->{'invoker'} = shift;
183 return $self->{'invoker'};
191 my $progress = $job->progress();
192 $job->progress($progress);
196 Read/write accessor for job progress.
203 $self->{'progress'} = shift;
206 return $self->{'progress'};
214 my $status = $job->status();
218 Read-only accessor for job status.
224 return $self->{'status'};
231 my $size = $job->size();
236 Read/write accessor for job size.
243 $self->{'size'} = shift;
246 return $self->{'size'};
254 $job->finish($results_hashref);
258 Mark the job as finished, setting its status to 'completed'.
259 C<$results_hashref> should be a reference to a hash containing
260 the results of the job.
266 my $results_hashref = shift;
267 my $self->{'status'} = 'completed';
268 my $self->{'results'} = $results_hashref;
276 my $results_hashref = $job->results();
280 Retrieve the results of the current job. Returns undef
281 if the job status is not 'completed'.
287 return undef unless $self->{'status'} eq 'completed';
288 return $self->{'results'};
295 my $job = C4::BackgroundJob->fetch($sessionID, $jobID);
299 Retrieve a job that has been serialized to the database.
300 Returns C<undef> if the job does not exist in the current
307 my $sessionID = shift;
310 my $session = get_session($sessionID);
311 my $prefix = "job_$jobID";
312 unless (defined $session->param("$prefix.name")) {
317 $self->{'name'} = $session->param("$prefix.name");
318 $self->{'status'} = $session->param("$prefix.status");
319 $self->{'invoker'} = $session->param("$prefix.invoker");
320 $self->{'size'} = $session->param("$prefix.size");
321 $self->{'progress'} = $session->param("$prefix.progress");
322 if (defined(my $keys = $session->param("$prefix.results_keys"))) {
323 my @keys = split /\t/, $keys;
324 $self->{'results'} = {};
325 foreach my $key (@keys) {
326 $self->{'results'}->{$key} = $session->param("$prefix.results.$key");
336 Koha Development Team <info@koha.org>
338 Galen Charlton <galen.charlton@liblime.com>