NAME

Dispatcher::Tool - base class for tools.


SYNOPSIS

  # examples here
  use Dispatcher::Tool;


DESCRIPTION


VERSIONS

$Id: Tool.pm.html,v 1.1.1.1 2005/08/18 13:18:25 hunter Exp $

Copyright (c) European Bioinformatics Institute 2002


AUTHORS / ACKNOWLEDGEMENTS

Ville Silventoinen <vsi@ebi.ac.uk>

new

 Description: Constructor allocates an anonymous hash, which
              is tied to the class.
 Arguments:   -
 Returns:     $self object

getToolName

 Description: Returns tool name.
 Arguments:   -
 Returns:     Tool name.

setToolName

 Description: Sets tool name.
 Arguments:   $name    Tool name.
 Returns:     -

getParam

 Description: Returns tool input parameter value.
 Arguments:   $key    Parameter key.
 Returns:     Value or empty string if key has no value.

setParam

 Description: Sets tool input parameter value.
 Arguments:   $key      Parameter key.
              $value    Parameter value.
 Returns:     -

removeParam

 Description: Removes tool input parameter.
 Arguments:   $key      Parameter key.
 Returns:     -

getParams

 Description: Returns tool's input parameters.
 Arguments:   -
 Returns:     Reference to a hash.

setParams

 Description: Sets tool parameters.
 Arguments:   $params    Reference to a hash.
 Returns:     -

getConfigValue

 Description: Returns tool configuration value.
 Arguments:   $key    Configuration key.
 Returns:     Value or empty string if key has no value.

setConfigValue

 Description: Sets tool configuration value.
 Arguments:   $key      Configuration key.
              $value    Parameter value.
 Returns:     -

removeConfigValue

 Description: Removes tool configuration key-value pair.
 Arguments:   $key      Configuration key.
 Returns:     -

getConfig

 Description: Returns tool configuration.
 Arguments:   -
 Returns:     Reference to Dispatcher::Config object

setConfig

 Description: Sets tool configuration.
 Arguments:   $config    Reference to Dispatcher::Config object.
 Returns:     -

mapParamToDescription

 Description: Returns parameter description.
              NOTE: this method uses param2desc hash reference inside the object.
              Each tool that wishes to support descriptions should set it in the
              object constructor.
 Arguments:   $key    Parameter key.
 Returns:     Description or empty string.

parseConfig

 Description: Parses tool configuration and sets it inside the tool object.
              This is a convenience method for all tools derived from
              Dispatcher::Tool. It sets the YYYY, MM, DD, hh, mm and ss tags
              automatically by parsing the jobid.
 Arguments:   Same as Dispatcher::Config::parse, excluding the first argument.
 Returns:     1, ''  on success
              0, msg on failure

isTool

 Description: Validates tool name.
 Arguments:   $name    Tool name.
 Returns:     1 on success
              0 on failure

createConfirmationPage

 Description: Creates an HTML job confirmation page.
              NOTE 1: HTTP headers must be added by the caller, because it is
              impossible to know when they should be added (caller may have
              started the page and this call finishes it).
 Arguments:   $in        Input sequence (optional).
              $out       Output (default: stdout).
              $top       Page top (default: getHtmlTop).
              $bottom    Page bottom (default: getHtmlBottom).
 Returns:     1, ''  on success
              0, msg on failure

createErrorPage

 Description: Creates error HTML page to stdout or file.
              NOTE 1: HTTP headers must be sent by the caller.
              NOTE 2: This method does not return errors, it is "best effort".
 Arguments:   $out       Output (default: stdout).
              $emsg      Error message string (optional).
              $efile     Error file or file handle (optional).
              $top       Page top (default: getHtmlTop).
              $bottom    Page bottom (default: getHtmlBottom).
 Returns:     -

createPollPage

 Description: Creates HTML page that polls the result page.
 Arguments:   $url    URL to be polled.
              $out    Output (default: stdout).
 Returns:     1, ''  on success
              0, msg on failure

createConfirmationMail

 Description: Creates confirmation mail to stdout or file.
 Arguments:   $in     Input sequence (optional).
              $out    Output (default: stdout).
 Returns:     1, ''  on success
              0, msg on failure

hasAccess

 Description: Checks whether remote host is allowed to access the tool or more
              specifically the group that the tool belongs to (like EPO tools).
              Host name is retrieved from environment variables REMOTE_HOST or
              REMOTE_ADDR.
 Arguments:   $group    Group name (optional).
 Returns:     1, host on access allowed
              0, msg  on access denied

parseRequest

 Description: Reads the request parameters to a hash table. Parameters must
              be given as a CGI query object. Uploaded files are written to
              disk with the configured paths uploadfile.1, uploadfile.2, etc.
 Arguments:   $query    CGI query object.
              $check    1: check parameters
                        0: no check
 Returns:     1, ''  on success
              0, msg on failure

readParamFile

 Description: Reads parameters from file (handle) and creates a hash.
 Arguments:   $in        Input parameters.
              $params    Reference to a hash.
 Returns:     1, ''  on success
              0, msg on failure

writeParamFile

 Description: Writes submission parameters to a file (handle).
 Arguments:   $out       Output parameters file.
              $params    Parameter hash.
 Returns:     1, path on success
              0, msg  on failure

getDate

 Description: Returns current date.
 Arguments:   -
 Returns:     yyyy, mm, dd

getDateFromJobID

 Description: Returns date extracted from job ID.
 Arguments:   $jobid    Job identifier containing "-YYYYMMDD-",
 Returns:     yyyy, mm, dd

parseDate

 Description: Returns date in format YYYYMMDD (numerical).
 Arguments:   $date    Date in format in of the following formats:
                       DD-MMM-YYYY (01-Oct-2003)
                       DD-MMM-YY   (01-Oct-03)
                       DD-MM-YYYY  (01-10-2003)
                       DD-MM-YY    (01-10-03)
                       MM/DD/YYYY  (10/01/2003)
                       MM/DD/YY    (10/01/03)
 Returns:     YYYYMMDD

protect

 Description: Replaces unsafe characters in a string.
 Arguments:   $s    String.
 Returns:     string

removeIllegalChars

 Description: Removes < > " ' characters from string.
 Arguments:   $s    String.
 Returns:     string

systemCall

 Description: Execute a command as a system call
              (see Programming Perl system function for details).
 Arguments:   $cmd    Command (with args) to execute.
 Returns:     1, ''  on success
              0, msg on error

sendMail

 Description: Sends mail message. If both message body string and file are
              given, string is set first, then file.
 Arguments:   $to          To field.
              $subject     Subject field.
              $bodys       Body passed in a string (optional).
              $bodyf       Body passed in a file or file handle (optional).
              $from        From field (optional).
              $errorsTo    Errors-To field (optional).
              $chunk       Split file to N line chunks (optional). This adds
                           " (part N)" strings also to subject lines.
 Returns:     1, ''  on success
              0, msg on failure

checkDirectory

 Description: Checks if given directory exists and tries to create it.
 Arguments:   $dir     Directory.
              $mode    Numeric mode (optional).
 Returns:     1, ''  on success
              0, msg on failure

generateJobID

 Description: Generates new job identifier.
 Arguments:   $group    Tool group, e.g., 'fasta' for all fastas.
 Returns:     jobid in format "toolgroup-YYYYMMDD-rand"

checkJobID

 Description: Checks if given job ID is in correct format.
 Arguments:   $jobid    Job identifier.
 Returns:     1, ''  on success
              0, msg on failure

trim

 Description: Trims leading and trailing whitespace.
 Arguments:   $s    String.
 Returns:     trimmed string

errorExit

 Description: Reports errors and exits.
 Arguments:   $error    Error message, OR
              $efile    Error file.
              $html     1: create HTML error page
                        0: email error to user
 Returns:     -

sendForbidden

 Description: Sends HTTP 403 Forbidden.
              NOTE! Does not exit!
 Arguments:   $error     Error message (optional).
 Returns:     -

findFile

 Description: Tries to find a file. This is a convenience method for situations
              when job files can be in different directories. At the moment
              following work directories set in the tool configuration are
              searched: workdir, aworkdir and sworkdir.
 Arguments:   $file    filename, path or key in tool configuration.
 Returns:     Full path or $file.

safeWrite

 Description: Reads from a file handle and writes to another file handle. Checks
              the number of bytes written and stops writing if the given limit is
              exceeded.
              NOTE! Caller is responsible for closing the file handles!
 Arguments:   $readFH     Read file handle.
              $writeFH    Write file handle.
              $limit      Limit in bytes (optional).
 Returns:     1, ''  on success
              0, msg on failure

getUniqueID

 Description: Generates unique identifier.
 Arguments:   -
 Returns:     id string

getSequenceInfo

 Description: Returns information about sequence. The sequence must be
              passed in raw or fasta format.
 Arguments:   $in    Input sequence file or file handle.
 Returns:     1, dna|rna|protein, length
              0, msg

checkBoolean

 Description: Checks boolean.
 Arguments:   $value      Value string (optional).
              $default    Default value (optional).
 Returns:     value

checkInteger

 Description: Checks integer.
 Arguments:   $value      Value string (optional).
              $default    Default value (optional).
              $lower      Lower limit (optional).
              $upper      Upper limit (optional).
 Returns:     1, value on success
              0, msg   on failure

checkDecimal

 Description: Checks decimal.
 Arguments:   $value      Value string (optional).
              $default    Default value (optional).
              $lower      Lower limit (optional).
              $upper      Upper limit (optional).
 Returns:     value

checkRange

 Description: Checks range.
 Arguments:   $value      Value string (optional).
              $default    Default value (optional).
              $lower      Lower limit (optional).
              $upper      Upper limit (optional).
 Returns:     value

checkString

 Description: Checks string value.
 Arguments:   $value      Value string (optional).
              $default    Default value (optional).
              $values     Allowed values as array reference (optional).
 Returns:     value

checkParams

 Description: Checks input parameters. Each tool must override this method.
 Arguments:   -
 Returns:     1, ''  on success
              0, msg on failure

isFileHandle

 Description: Checks whether parameter is a file handle.
 Arguments:   $fh    File handle.
 Returns:     1 for FileHandle reference or FileHandle glob.
              0 otherwise

getReadHandle

 Description: Returns reference to a file handle for reading. The caller
              must close the file handle if close flag is 1.
              Examples:
                # pass file as string, caller must close file handle
                my ($res, $close, $fh) = $self->getReadHandle('file');
                # pass a file handle glob
                my ($res, $close, $fh) = $self->getReadHandle(\*STDIN);
                # pass reference to a FileHandle object
                my $input = new FileHandle("< file");
                my ($res, $close, $fh) = $self->getReadHandle($input);
 Arguments:   $file    Path, FileHandle reference or Filehandle glob.
 Returns:     1, close flag, file handle on success
              0, 0,          message     on failure

getWriteHandle

 Description: Returns reference to a file handle for writing. The caller
              must close the file handle if close flag is 1.
              Examples:
                # pass file as string, caller must close file handle
                my ($res, $close, $fh) = $self->getWriteHandle('file');
                # pass a file handle glob
                my ($res, $close, $fh) = $self->getWriteHandle(\*STDOUT);
                # pass reference to a FileHandle object
                my $input = new FileHandle("> file");
                my ($res, $close, $fh) = $self->getWriteHandle($input);
 Arguments:   $file    Path, FileHandle reference or Filehandle glob.
 Returns:     1, close flag, file handle on success
              0, 0,          message     on failure