NAME

WWW::Crab::Client - Crab client library

SYNOPSIS

  use WWW::Crab::Client;

  my $crab = new WWW::Crab::Client();

  my $start_response = eval {
      $crab->start();
  };

  # Check for "inhibit" flag (optional).
  if ($start_response and $start_response->{'inhibit'}) {
      eval {
          $crab->finish(status => WWW::Crab::Client::INHIBITED);
      };
      exit;
  }

  # Perform the cron job actions ...

  my $finished_ok = eval {
      $crab->finish(status => WWW::Crab::Client::SUCCESS, stdout => $message);
  };
  unless ($finished_ok) {
      print "Failed to report job completion.\n" . $@ . "\n" . $message;
  }

DESCRIPTION

This module implements a subset of the Crab protocol sufficient for reporting the status of a cron job to the Crab server. It is intended to work similarly to the Python Crab client module, but be more convient for cron jobs written in Perl.

CONSTRUCTOR

new()

Constructs a new client object. All parameters are optional. If no job identifier is given, then a null value is sent to the server. If the command is unspecified, $0 will be used. No communication is performed until the start or finish methods are called.

  my $crab = new WWW::Crab::Client(id       => 'job identifier',
                                   command  => 'command name',
                                   server   => 'localhost',
                                   port     => 8000,
                                   hostname => 'localhost',
                                   username => 'username',
                                   timeout  => 30);

If the other settings are not specified, the Crab settings files will be read, the CRABHOST and CRABPORT environment variables will be checked, or defaults will be used.

METHODS

start()

Reports that the job has started.

  $crab->start();

This method uses "die" to raise an exception if it is unsuccessful in reporting to the Crab server.

Returns the decoded server response on success, which make include an "inhibit" hash key.

finish()

Reports that the job has finished. If the status is not specified, UNKNOWN will be sent.

  $crab->finish(status => WWW::Crab::Client::SUCCESS,
                stdout => $command_output,
                stderr => $error_message);

The following constants are defined in this module, and should be used to obtain the appropriate Crab status codes:

  SUCCESS
  FAIL
  UNKNOWN
  COULDNOTSTART
  ALREADYRUNNING
  WARNING

This method uses "die" to raise an exception if it is unsuccessful in reporting to the Crab server.

Returns a true value on success.

AUTHOR

Graham Bell <g.bell@eaobservatory.org>

COPYRIGHT

Copyright (C) 2012-2013 Science and Technology Facilities Council. Copyright (C) 2016 East Asian Observatory.

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