view release on metacpan or  search on metacpan

lib/Bio/CIPRES/Job.pm  view on Meta::CPAN

    $s->{url_results} = $dom->findvalue('resultsUri/url');
    $s->{url_working} = $dom->findvalue('workingDirUri/url');
    $s->{poll_secs}   = $dom->findvalue('minPollIntervalSeconds');
    $s->{is_finished} = $dom->findvalue('terminalStage') =~ /^true$/i ? 1 : 0;
    $s->{is_failed}   = $dom->findvalue('failed') =~ /^true$/i ? 1 : 0;;
    $s->{stage}       = $dom->findvalue('jobStage');
    $s->{submit_time} = $dom->findvalue('dateSubmitted');

    # check for missing values
    map {length $s->{$_} || croak "Missing value for $_\n"} keys %$s;

    # parse submit time
    my $submit_time = $s->{submit_time};
    $submit_time =~ s/(\d\d):(\d\d)$/$1$2/;
    $submit_time = Time::Piece->strptime(
        $submit_time,
        "%Y-%m-%dT%H:%M:%S%z",
    ) or croak "Failed to parse submit time ($s->{submit_time})\n";
    $s->{submit_time} = $submit_time;

    # parse messages
    my @messages;
    for my $msg_node ($dom->findnodes('messages/message')) {
        push @messages,
            Bio::CIPRES::Message->new($msg_node);
    }
    $s->{messages} = [sort {$a <=> $b} @messages];

    # parse metadata
    for my $meta ($dom->findnodes('metadata/entry')) {
        my $key = $meta->findvalue('key');
        my $val = $meta->findvalue('value');

        # check for missing values
        map {length $_ || croak "Unexpected metadata format\n"} ($key, $val);

        $s->{meta}->{$key} = $val;
    }

    $self->{$_} = $s->{$_} for (keys %$s);

    return 1;

}

1;

__END__

=head1 NAME

Bio::CIPRES::Job - a CIPRES job class

=head1 SYNOPSIS

    use Bio::CIPRES;

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

    $job->wait(6000) or die "Timeout waiting for job completion";

    warn "Job returned non-zero status" if ($job->exit_code != 0);

    print STDOUT $job->stdout;
    print STDERR $job->stderr;

    $job->delete;

=head1 DESCRIPTION

C<Bio::CIPRES::Job> is a class representing a single CIPRES job. Its purpose
is to simplify handling of job status and job outputs.

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

=head1 METHODS

=over 4

=item B<stage>

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

Returns a string describing the current stage of the job.

=item B<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.

=item B<is_finished>

    if ($job->is_finished) {}

Returns true if the job has completed, false otherwise.

=item B<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 L<Bio::CIPRES::Job::exit_code> for a more reliable way to
check for job success.

=item B<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.

=item B<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.

=item B<outputs>

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

Returns an array of L<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:

=over 2

=item  * group

Limit returned outputs to those in the specified group

=item  * name

Limit returned output to that with the specified name

=item  * force_download

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

=back

=item B<exit_code>

    warn "Job returned non-zero status" if ($job->exit_code != 0);

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).

=item B<stdout>

    print STDOUT $job->stdout;

Returns the STDOUT from the job as a string.

=item B<stderr>

    print STDERR $job->stderr;

Returns the STDERR from the job as a string.

=item B<submit_time>

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