NAME

Bio::CIPRES::Job - a CIPRES job

SYNOPSIS

    use Bio::CIPRES;

    my $ua  = Bio::CIPRES->new( %args );
    my $job = $ua->submit( %params );

DESCRIPTION

Bio::CIPRES::Job is a class representing a single CIPRES job. It's purpose is to simplify handling of job status and job outputs.

Users should not create Bio::CIPRES::Job objects directly - they are returned by methods in the Bio::CIPRES class.

METHODS

delete

    $job->delete;

Deletes a job from the user workspace, including all of the output files. Generally this should be called once a job is completed and all desired output files have been fetched. This will help to keep the user workspace clean.

is_finished

    if ($job->is_finished) {}

Returns true if the job has completed, false otherwise.

is_failed

    die "CIPRES error" if ($job->is_failed);

Returns true if the submission has failed, false otherwise. Note that, according to the API docs, this value can be false even if the job itself has failed for some reason. Use Bio::CIPRES::Job::exit_code for a more reliable way to check for job success.

poll_interval

    my $s = $job->poll_interval;

Returns the minimum number of seconds that the client should wait between status updates. Generally this is called as part of a while loop.

stage

    if ($job->stage eq 'COMPLETED') {}

Returns a string describing the current stage of the job.

refresh

    $job->refresh;

Makes a call to the API to retrieve the current status of the job, and updates the object attributes accordingly. Generally this is called as part of a while loop while waiting for a job to complete.

wait

    $job->wait($timeout) or die "Timeout waiting for job to finish";

Enters a blocking loop waiting for the job to finish. Takes a single optional argument of the maximum number of seconds to wait before timing out (default: no timeout). Returns true if the job finishes or false if the wait times out.

outputs

    my @results = $job->outputs(
        name  => 'foo.txt',
        group => 'bar',
        force_download => 0,
    );

Returns an array of Bio::CIPRES::Output objects representing files generated by the job. Generally this should only be called after a job has completed. By default returns all available outputs. Possible arguments include:

group

Limit returned outputs to those in the specified group

name

Limit returned output to that with the specified name

force_download

Force the client to re-download output list (as opposed to using cached values). This is automatically called from within Bio::CIPRES::Job::refresh and generally doesn't need to be set by the user. (default: false)

exit_code

Returns the actual exit code of the job on the remote server. Exit codes < 0 indicate API or server errors, while exit codes > 0 indicate errors in the job tool itself (possibly described in the tool's documentation).

stdout

Returns the STDOUT from the job as a string.

stderr

Returns the STDERR from the job as a string.

submit_time

Returns the original submission date/time as a Time::Piece object

CAVEATS AND BUGS

Please reports bugs to the author.

AUTHOR

Jeremy Volkening <jdv@base2bio.com>

COPYRIGHT AND LICENSE

Copyright 2016 Jeremy Volkening

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.