com.sun.grid.drmaa

## Class JobTemplateImpl

- java.lang.Object
- - com.sun.grid.drmaa.JobTemplateImpl

- All Implemented Interfaces:
    JobTemplate

      public class JobTemplateImpl
      extends java.lang.Object
      implements JobTemplate

  This class represents a remote job and its attributes. It is used to set up the environment for a job to be submitted.

  ### DRMMA Attributes

  DRMAA job template attributes can be set from six different sources. In order of precedence, from lowest to highest, there are: options set by DRMAA automatically by default, options set in the sge_request file(s), options set in the script file, options set by the jobCategory property, options set by the nativeSpecification property, and options set through other DRMAA properties.

  By default DRMAA sets four options for all jobs. They are "-p 0", "-b yes", "-shell no", and "-w e". This means that by default, all jobs will have priority 0, all jobs will be treated as binary, i.e. no scripts args will be parsed, all jobs will be executed without a wrapper shell, and jobs which are unschedulable will cause a submit error.

  The sge_request file, found in the $SGE_ROOT/$SGE_CELL/common directory, may contain options to be applied to all jobs. The .sge_request file found in the user's home directory or the current working directory may also contain options to be applied to certain jobs. See the sge_request(5) man page for more information.

  If the sge_request file contains "-b no" or if the nativeSpecification property is set and contains "-b no", the script file will be parsed for in-line arguments. Otherwise, no script's args will be interpreted. See the qsub(1) man page for more information.

  If the jobCategory property is set, and the category it points to exists in one of the qtask files, the options associated with that category will be applied to the job template. See the qtask(5) man page and `setJobCategory(String)` below for more information.

  If the nativeSpecification property is set, all options contained therein will be applied to the job template. See `setNativeSpecification(String)` below for more information.

  Other DRMAA attributes will override any previous settings. For example, if the sge_request file contains "-j y", but the joinFiles property is set to `false`, the ultimate result is that the input and output files will remain separate.

  For various reasons, some options are silently ignored by DRMAA. Setting any of these options will have no effect. The ignored options are: "-cwd", "-help", "-sync", "-t", "-verify", "-w w", and "-w v". The "-cwd" option can be reenabled by setting the environment variable, SGE_DRMAA_ALLOW_CWD. However, the "-cwd" option is not thread safe and should not be used in a multi-threaded context.

  ### Attribute Correlations

  The following DRMAA attributes correspond to the following qsub options:

  DRMAA Attributes
  DRMAA Attribute | qsub Option
  --- | ---
  remoteCommand | script file
  args | script file arguments
  jobSubmissionState = HOLD_STATE | -h
  jobEnvironment | -v
  workingDirectory = $PWD | -cwd
  jobCategory | (qtsch qtask)*
  nativeSpecification | ALL*
  emailAddresses | -M
  blockEmail = true | -m n
  startTime | -a
  jobName | -N
  inputPath | -i
  outputPath | -o
  errorPath | -e
  joinFiles | -j
  transferFiles | (prolog and epilog)*

  * See the individual attribute setter description below

  The following attributes are unsupported by Grid Engine:

  - deadlineTime
  - hardWallclockTimeLimit
  - softWallclockTimeLimit
  - hardRunDurationTimeLimit
  - softRunDurationTimeLimit

  Using the accessors for any of these attributes will result in an UnsupportedAttributeException being thrown.

  Since:
    0.5
  Version:
    1.0
  See Also:
    `JobTemplate`, `Session`, `SessionImpl`, sge_request(5), qsub(1), qtask(5)

- - ### Field Summary

    - ### Fields inherited from interface org.ggf.drmaa.JobTemplate

      `ACTIVE_STATE, HOLD_STATE, HOME_DIRECTORY, PARAMETRIC_INDEX`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object obj)` Tests whether this JobTemplateImpl represents the same native job template as the given object.
    `java.util.List` | `getArgs()` Get the arguments to the job.
    `java.util.Set` | `getAttributeNames()` Returns the list of supported properties names.
    `boolean` | `getBlockEmail()` Get whether to block sending e-mail by default, regardless of the DRMS settings.
    `PartialTimestamp` | `getDeadlineTime()` Unsupported property.
    `java.util.Set` | `getEmail()` Get the list of email addresses used to report the job completion and status.
    `java.lang.String` | `getErrorPath()` Gets how to direct the job's standard error.
    `long` | `getHardRunDurationLimit()` Unsupported property.
    `long` | `getHardWallclockTimeLimit()` Unsupported property.
    `java.lang.String` | `getInputPath()` Get the job's standard input path.
    `java.lang.String` | `getJobCategory()` Get the opaque string specifying how to resolve site-specific resources and/or policies.
    `java.util.Map` | `getJobEnvironment()` Get the environment values that define the remote environment.
    `java.lang.String` | `getJobName()` Get the name of the job.
    `int` | `getJobSubmissionState()` Get the job state at submission.
    `boolean` | `getJoinFiles()` Gets whether the error stream should be intermixed with the output stream.
    `java.lang.String` | `getNativeSpecification()` Get the opaque string that is passed by the end user to DRMAA to specify site-specific resources and/or policies.
    `java.lang.String` | `getOutputPath()` Gets how to direct the job's standard output.
    `java.lang.String` | `getRemoteCommand()` Get the command string to execute as the job.
    `long` | `getSoftRunDurationLimit()` Unsupported property.
    `long` | `getSoftWallclockTimeLimit()` Unsupported property.
    `PartialTimestamp` | `getStartTime()` Get the earliest time when the job may be eligible to be run.
    `FileTransferMode` | `getTransferFiles()` Gets how to transfer files between hosts.
    `java.lang.String` | `getWorkingDirectory()` Get the directory where the job is executed.
    `int` | `hashCode()` Returns a hash code based on the associated native job template's table index.
    `void` | `setArgs(java.util.List args)` Specifies the arguments to the job.
    `void` | `setBlockEmail(boolean blockEmail)` Specifies whether e-mail sending shall blocked or not.
    `void` | `setDeadlineTime(PartialTimestamp deadline)` Unsupported property.
    `void` | `setEmail(java.util.Set email)` Set the list of email addresses used to report the job completion and status.
    `void` | `setErrorPath(java.lang.String errorPath)` Sets how to direct the job's standard error.
    `void` | `setHardRunDurationLimit(long hardRunLimit)` Unsupported property.
    `void` | `setHardWallclockTimeLimit(long hardWallclockLimit)` Unsupported property.
    `void` | `setInputPath(java.lang.String inputPath)` Set the job's standard input path.
    `void` | `setJobCategory(java.lang.String category)` Specifies the DRMAA job category.
    `void` | `setJobEnvironment(java.util.Map env)` Sets the environment values that define the remote environment.
    `void` | `setJobName(java.lang.String name)` Set the name of the job.
    `void` | `setJobSubmissionState(int state)` Specifies the job state at submission.
    `void` | `setJoinFiles(boolean join)` Sets whether the error stream should be intermixed with the output stream.
    `void` | `setNativeSpecification(java.lang.String spec)` Specifies native qsub options which will be interpreted as part of the DRMAA job template.
    `void` | `setOutputPath(java.lang.String outputPath)` Sets how to direct the job's standard output.
    `void` | `setRemoteCommand(java.lang.String remoteCommand)` Specifies the remote command to execute.
    `void` | `setSoftRunDurationLimit(long softRunLimit)` Unsupported property.
    `void` | `setSoftWallclockTimeLimit(long softWallclockLimit)` Unsupported property.
    `void` | `setStartTime(PartialTimestamp startTime)` Set the earliest time when the job may be eligible to be run.
    `void` | `setTransferFiles(FileTransferMode mode)` Set Transfer Files
    `void` | `setWorkingDirectory(java.lang.String wd)` Specifies the directory name where the job will be executed.

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### setRemoteCommand

          public void setRemoteCommand(java.lang.String remoteCommand)
                                throws DrmaaException

      Specifies the remote command to execute. The remoteCommand must be the path of an executable that is available at the job's execution host. If the path is relative, it is assumed to be relative to the working directory, usually set through the workingDirectory property. If workingDirectory is not set, the path is assumed to be relative to the user's home directory.

      The file pointed to by remoteCommand may either be an executable binary or an executable script. If a script, it must include the path to the shell in a #! line at the beginning of the script. By default, the remote command will be executed directly, as by exec. (See the exec(2) man page.) To have the remote command executed in a shell, such as to preserve environment settings, use the nativeSpecification property to include the "-shell yes" option. Jobs which are executed by a wrapper shell fail differently from jobs which are executed directly. When a job which contains a user error, such as an invalid path to the executable, is executed by a wrapper shell, the job will execute successfully, but exit with a return code of 1. When a job which contains such an error is executed directly, it will enter the DRMAA_PS_FAILED state upon execution.

      No binary file management is done.

      Specified by:
        `setRemoteCommand` in interface `JobTemplate`
      Parameters:
        `remoteCommand` - the command to execute as the job
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation

    - #### getRemoteCommand

          public java.lang.String getRemoteCommand()
                                            throws DrmaaException

      Get the command string to execute as the job.
      Specified by:
        `getRemoteCommand` in interface `JobTemplate`
      Returns:
        the command to execute as the job or null if it has not been set
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setRemoteCommand(String)`

    - #### setArgs

          public void setArgs(java.util.List args)
                       throws DrmaaException

      Specifies the arguments to the job.
      Specified by:
        `setArgs` in interface `JobTemplate`
      Parameters:
        `args` - the parameters passed as arguments to the job
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation

    - #### getArgs

          public java.util.List getArgs()
                                 throws DrmaaException

      Get the arguments to the job.
      Specified by:
        `getArgs` in interface `JobTemplate`
      Returns:
        the parameters passed as arguments to the job or null if they have not been set
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setArgs(List)`

    - #### setJobSubmissionState

          public void setJobSubmissionState(int state)
                                     throws DrmaaException

      Specifies the job state at submission. The possible values are `HOLD_STATE` and `ACTIVE_STATE`:
      - `ACTIVE` means the job is submitted in a runnable state.
      - `HOLD` means the job is submitted in user hold state (either `Session.USER_ON_HOLD` or `Session.USER_SYSTEM_ON_HOLD`).

      This parameter is largely equivalent to the qsub submit option "-h".

      Specified by:
        `setJobSubmissionState` in interface `JobTemplate`
      Parameters:
        `state` - the job state at submission
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        qsub(1)

    - #### getJobSubmissionState

          public int getJobSubmissionState()
                                    throws DrmaaException

      Get the job state at submission.
      Specified by:
        `getJobSubmissionState` in interface `JobTemplate`
      Returns:
        the job state at submission
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setJobSubmissionState(int)`

    - #### setJobEnvironment

          public void setJobEnvironment(java.util.Map env)
                                 throws DrmaaException

      Sets the environment values that define the remote environment. The values override the remote environment values if there is a collision.
      Specified by:
        `setJobEnvironment` in interface `JobTemplate`
      Parameters:
        `env` - the environment values that define the remote environment
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation

    - #### getJobEnvironment

          public java.util.Map getJobEnvironment()
                                          throws DrmaaException

      Get the environment values that define the remote environment.
      Specified by:
        `getJobEnvironment` in interface `JobTemplate`
      Returns:
        the environment values that define the remote environment or null if it has not been set
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setJobEnvironment(Map)`

    - #### setWorkingDirectory

          public void setWorkingDirectory(java.lang.String wd)
                                   throws DrmaaException

      Specifies the directory name where the job will be executed. A `HOME_DIRECTORY` placeholder at the beginning of the directory name denotes that the remaining portion of the directory name is to be resolved relative to the job submiter's home directory on the execution host.

      When the DRMAA job template is used for bulk job submission (see also `Session.runBulkJobs(org.ggf.drmaa.JobTemplate,int,int,int)` the `PARAMETRIC_INDEX` placeholder can be used at any position within the directory name to cause a substitution with the parametric job's index. The directory name must be specified in a syntax that is common at the host where the job will be executed. If no placeholder is used, an absolute directory specification is recommended. If set to a relative path and no placeholder is used, a path relative to the user's home directory is assumed. If not set, the working directory will default to the user's home directory. If set, and the directory does not exist, the job will enter the state `FAILED` when the job is run.

      Specified by:
        `setWorkingDirectory` in interface `JobTemplate`
      Parameters:
        `wd` - the directory where the job is executed
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `JobTemplate.HOME_DIRECTORY`, `JobTemplate.PARAMETRIC_INDEX`, `Session.FAILED`

    - #### getWorkingDirectory

          public java.lang.String getWorkingDirectory()
                                               throws DrmaaException

      Get the directory where the job is executed.
      Specified by:
        `getWorkingDirectory` in interface `JobTemplate`
      Returns:
        the directory where the job is executed or null if it has not been set
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setWorkingDirectory(String)`

    - #### setJobCategory

          public void setJobCategory(java.lang.String category)
                              throws DrmaaException

      Specifies the DRMAA job category. The category string is used by Grid Engine as reference into the qtask file. Certain qsub options used in the referenced qtask file line are applied to the job template before submission to allow site-specific resolving of resources and/or policies. The cluster qtask file, the local qtask file, and the user qtask file are searched. Job settings resulting from job template category are overridden by settings resulting from the job template nativeSpecification property as well as by explict DRMAA job template property settings.

      The options -help, -sync, -t, -verify, and -w w|v are ignored. The -cwd option is ignored unless the $SGE_DRMAA_ALLOW_CWD environment variable is set.

      Specified by:
        `setJobCategory` in interface `JobTemplate`
      Parameters:
        `category` - an opaque string specifying how to resolve site-specific resources and/or policies.
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        qtask(5), qsub(1)

    - #### getJobCategory

          public java.lang.String getJobCategory()
                                          throws DrmaaException

      Get the opaque string specifying how to resolve site-specific resources and/or policies.
      Specified by:
        `getJobCategory` in interface `JobTemplate`
      Returns:
        the opaque string specifying how to resolve site-specific resources and/or policies or null if it has not been set
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setJobCategory(String)`

    - #### setNativeSpecification

          public void setNativeSpecification(java.lang.String spec)
                                      throws DrmaaException

      Specifies native qsub options which will be interpreted as part of the DRMAA job template. All options available to the qsub command may be used in the nativeSpecification, except for -help, -sync, -t, -verify, and -w w|v. -cwd may only be used if the $SGE_DRMAA_ALLOW_CWD enviroment variable is set. Options set in the nativeSpecification will be overridden by the corresponding DRMAA properties. See the qsub(1) man page for more information on qsub command line options.
      Specified by:
        `setNativeSpecification` in interface `JobTemplate`
      Parameters:
        `spec` - an opaque string that is passed by the end user to DRMAA to specify site-specific resources and/or policies
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        qsub(1)

    - #### getNativeSpecification

          public java.lang.String getNativeSpecification()
                                                  throws DrmaaException

      Get the opaque string that is passed by the end user to DRMAA to specify site-specific resources and/or policies.
      Specified by:
        `getNativeSpecification` in interface `JobTemplate`
      Returns:
        the opaque string that is passed by the end user to DRMAA to specify site-specific resources and/or policies or null if it has not been set
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setNativeSpecification(String)`

    - #### setEmail

          public void setEmail(java.util.Set email)
                        throws DrmaaException

      Set the list of email addresses used to report the job completion and status.
      Specified by:
        `setEmail` in interface `JobTemplate`
      Parameters:
        `email` - the list of email addresses used to report the job completion and status.
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation

    - #### getEmail

          public java.util.Set getEmail()
                                 throws DrmaaException

      Get the list of email addresses used to report the job completion and status.
      Specified by:
        `getEmail` in interface `JobTemplate`
      Returns:
        the list of email addresses used to report the job completion and status or null if they have not been set
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setEmail(java.util.Set)`

    - #### setBlockEmail

          public void setBlockEmail(boolean blockEmail)
                             throws DrmaaException

      Specifies whether e-mail sending shall blocked or not. By default email is not sent. If, however, a setting in a cluster or user settings file or the nativeSpecification or jobCategory property enables sending email in association with job events, the blockEmail property will override that setting, causing no email to be sent.
      Specified by:
        `setBlockEmail` in interface `JobTemplate`
      Parameters:
        `blockEmail` - whether to block sending e-mail by default
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation

    - #### getBlockEmail

          public boolean getBlockEmail()
                                throws DrmaaException

      Get whether to block sending e-mail by default, regardless of the DRMS settings.
      Specified by:
        `getBlockEmail` in interface `JobTemplate`
      Returns:
        whether to block sending e-mail by default
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setBlockEmail(boolean)`

    - #### setStartTime

          public void setStartTime(PartialTimestamp startTime)
                            throws DrmaaException

      Set the earliest time when the job may be eligible to be run.
      Specified by:
        `setStartTime` in interface `JobTemplate`
      Parameters:
        `startTime` - the earliest time when the job may be eligible to be run
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `PartialTimestamp`

    - #### getStartTime

          public PartialTimestamp getStartTime()
                                        throws DrmaaException

      Get the earliest time when the job may be eligible to be run.
      Specified by:
        `getStartTime` in interface `JobTemplate`
      Returns:
        the earliest time when the job may be eligible to be run or null if it has not been set
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setStartTime(org.ggf.drmaa.PartialTimestamp)`

    - #### setJobName

          public void setJobName(java.lang.String name)
                          throws DrmaaException

      Set the name of the job. A job name will be comprised of alpha-numeric and _ characters. Setting the job name is equivalent to use of the qsub submit option "-N" with name as option argument and has the same restrictions. See the qsub(1) man page.
      Specified by:
        `setJobName` in interface `JobTemplate`
      Parameters:
        `name` - the name of the job
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        qsub(1)

    - #### getJobName

          public java.lang.String getJobName()
                                      throws DrmaaException

      Get the name of the job.
      Specified by:
        `getJobName` in interface `JobTemplate`
      Returns:
        the name of the job or null if it has not been set
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setJobName(String)`

    - #### setInputPath

          public void setInputPath(java.lang.String inputPath)
                            throws DrmaaException

      Set the job's standard input path. Unless set elsewhere, if not explicitly set in the job template, the job is started with an empty input stream. If the standard input is set, it specifies the network path of the job's input stream file in the form of `[hostname]:file_path`

      When the transferFiles property is supported and the set TranferFileMode instance's inputStream property is set to `true`, the input file will be fetched by Grid Engine from the specified host or from the submit host if no hostname is specified. When the transferFiles property is unsupported or the set TranferFileMode instance's inputStream property is not set or is set to `false`, the input file is always expected to be at the host where the job is executed, regardless of any hostname specified.

      When the DRMAA job template is used for bulk job submission (see also `Session.runBulkJobs(org.ggf.drmaa.JobTemplate,int,int,int)` the `PARAMETRIC_INDEX` placeholder can be used at any position within the file name to cause a substitution with the parametric job's index. A `HOME_DIRECTORY` placeholder at the beginning of the file path denotes the remaining portion of the file path as a relative file specification to be resolved relative to the job user's home directory at the host where the file is located. A `WORKING_DIRECTORY` placeholder at the beginning of file path denotes the remaining portion of the file path as a relative file specification to be resolved relative to the job's working directory at the host where the file is located. The file name must be specified in a syntax that is common at the host where the job will be executed. If no home or working directory placeholder is used, an absolute file specification is recommended. If set to a relative file path and no home or working directory placeholder is used, a path relative to the user's home directory is assumed.

      When the job is run, if this attribute is set, and the file can't be read, the job will enter the state `FAILED`.

      Specified by:
        `setInputPath` in interface `JobTemplate`
      Parameters:
        `inputPath` - the job's standard input path
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `JobTemplate.HOME_DIRECTORY`, `JobTemplate.WORKING_DIRECTORY`, `JobTemplate.PARAMETRIC_INDEX`, `Session.FAILED`

    - #### getInputPath

          public java.lang.String getInputPath()
                                        throws DrmaaException

      Get the job's standard input path.
      Specified by:
        `getInputPath` in interface `JobTemplate`
      Returns:
        the job's standard input path or null if it has not been set
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setInputPath(String)`

    - #### setOutputPath

          public void setOutputPath(java.lang.String outputPath)
                             throws DrmaaException

      Sets how to direct the job's standard output. Unless set elsewhere, if not explicitly set in the job template, the whereabouts of the job's output stream is not defined. If the standard output is set, it specifies the network path of the job's output stream file in the form of `[hostname]:file_path`

      When the transferFiles property is supported and the set TranferFileMode instance's outputStream property is set to `true`, the output file will be transferred by Grid Engine to the specified host or to the submit host if no hostname is specified. When the transferFiles property is unsupported or the set TranferFileMode instance's outputStream property is not set or is set to `false`, the output file is always kept at the host where the job is executed, regardless of any hostname specified.

      When the DRMAA job template is used for bulk job submission (see also `Session.runBulkJobs(org.ggf.drmaa.JobTemplate,int,int,int)` the `PARAMETRIC_INDEX` placeholder can be used at any position within the file name to cause a substitution with the parametric job's index. A `HOME_DIRECTORY` placeholder at the beginning of the file path denotes the remaining portion of the file path as a relative file specification to be resolved relative to the job user's home directory at the host where the file is located. A `WORKING_DIRECTORY` placeholder at the beginning of file path denotes the remaining portion of the file path as a relative file specification to be resolved relative to the job's working directory at the host where the file is located. The file name must be specified in a syntax that is common at the host where the job will be executed. If no home or working directory placeholder is used, an absolute file specification is recommended. If set to a relative file path and no home or working directory placeholder is used, a path relative to the user's home directory is assumed.

      When the job is run, if this attribute is set, and the file can't be read, the job will enter the state `FAILED`.

      Specified by:
        `setOutputPath` in interface `JobTemplate`
      Parameters:
        `outputPath` - how to direct the job's standard output
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `JobTemplate.HOME_DIRECTORY`, `JobTemplate.WORKING_DIRECTORY`, `JobTemplate.PARAMETRIC_INDEX`, `Session.FAILED`

    - #### getOutputPath

          public java.lang.String getOutputPath()
                                         throws DrmaaException

      Gets how to direct the job's standard output.
      Specified by:
        `getOutputPath` in interface `JobTemplate`
      Returns:
        how to direct the job's standard output or null if it has not been set
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setOutputPath(String)`

    - #### setErrorPath

          public void setErrorPath(java.lang.String errorPath)
                            throws DrmaaException

      Sets how to direct the job's standard error. Unless set elsewhere, if not explicitly set in the job template, the whereabouts of the job's error stream is not defined. If the standard error is set, it specifies the network path of the job's error stream file in the form of `[hostname]:file_path`

      When the transferFiles property is supported and the set TranferFileMode instance's errorStream property is set to `true`, the error file will be transferred by Grid Engine to the specified host or to the submit host if no hostname is specified. When the transferFiles property is unsupported or the set TranferFileMode instance's errorStream property is not set or is set to `false`, the error file is always kept at the host where the job is executed, regardless of any hostname specified.

      When the DRMAA job template is used for bulk job submission (see also `Session.runBulkJobs(org.ggf.drmaa.JobTemplate,int,int,int)` the `PARAMETRIC_INDEX` placeholder can be used at any position within the file name to cause a substitution with the parametric job's index. A `HOME_DIRECTORY` placeholder at the beginning of the file path denotes the remaining portion of the file path as a relative file specification to be resolved relative to the job user's home directory at the host where the file is located. A `WORKING_DIRECTORY` placeholder at the beginning of file path denotes the remaining portion of the file path as a relative file specification to be resolved relative to the job's working directory at the host where the file is located. The file name must be specified in a syntax that is common at the host where the job will be executed. If no home or working directory placeholder is used, an absolute file specification is recommended. If set to a relative file path and no home or working directory placeholder is used, a path relative to the user's home directory is assumed.

      When the job is run, if this attribute is set, and the file can't be read, the job will enter the state `FAILED`.

      Specified by:
        `setErrorPath` in interface `JobTemplate`
      Parameters:
        `errorPath` - how to direct the job's standard error
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `JobTemplate.HOME_DIRECTORY`, `JobTemplate.WORKING_DIRECTORY`, `JobTemplate.PARAMETRIC_INDEX`, `Session.FAILED`

    - #### getErrorPath

          public java.lang.String getErrorPath()
                                        throws DrmaaException

      Gets how to direct the job's standard error.
      Specified by:
        `getErrorPath` in interface `JobTemplate`
      Returns:
        how to direct the job's standard error
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setErrorPath(String)`

    - #### setJoinFiles

          public void setJoinFiles(boolean join)
                            throws DrmaaException

      Sets whether the error stream should be intermixed with the output stream. If not explicitly set in the job template the attribute defaults to `false`. If `true`, the underlying DRM system will ignore the value of the errorPath property and intermix the standard error stream with the standard output stream as specified with outputPath.
      Specified by:
        `setJoinFiles` in interface `JobTemplate`
      Parameters:
        `join` - whether the error stream should be intermixed with the output stream
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation

    - #### getJoinFiles

          public boolean getJoinFiles()
                               throws DrmaaException

      Gets whether the error stream should be intermixed with the output stream.
      Specified by:
        `getJoinFiles` in interface `JobTemplate`
      Returns:
        Whether the error stream should be intermixed with the output stream
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setJoinFiles(boolean)`

    - #### setTransferFiles

          public void setTransferFiles(FileTransferMode mode)
                                throws DrmaaException

      Set Transfer Files

      Specifies, which of the standard I/O files (stdin, stdout and stderr) are to be transferred to/from the execution host. If not set, defaults to the equivalent of a FileTransferMode instance with all properties set to false. See inputPath, outputPath and errorPath setters for information about how to specify the standard input file, standard output file, and standard error file.

      If the FileTransferMode instance's errorStream property is set to `true`, the errorPath property is taken to specify the location to which error files should be transfered after the job finishes.

      If the FileTransferMode instance's inputStream property is set to `true`, the inputPath property is taken to specify the location from which input files should be transfered before the job starts.

      If the FileTransferMode instance's outputStream property is set to `true`, the outputPath property is taken to specify the location to which output files should be transfered after the job finishes.

      The file transfer mechanism itself must be configured by the administrator. (See the sge_conf(5) man page.) When it is configured, the administrator has to enable the transferFiles property by setting the execd param, delegated_file_staging, to true. If it is not configured, transferFiles is not supported and accessing this property will result in an UnsupportedAttributeException being thrown.

      Specified by:
        `setTransferFiles` in interface `JobTemplate`
      Parameters:
        `mode` - how to transfer files between hosts.
      Throws:
        `DrmaaException` - May be one of the following:
        - InvalidAttributeFormatException -- the format of the argument is invalid
        - InvalidAttributeValueException -- the value of the argument is invalid
        - ConflictingAttributeValuesException -- the value of the argument conflicts with the value of another job template property
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - IllegalArgumentException -- an argument is invalid
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setInputPath(String)`, `setOutputPath(String)`, `setErrorPath(String)`, sge_conf(5)

    - #### getTransferFiles

          public FileTransferMode getTransferFiles()
                                            throws DrmaaException

      Gets how to transfer files between hosts.
      Specified by:
        `getTransferFiles` in interface `JobTemplate`
      Returns:
        how to transfer files between hosts.
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation
      See Also:
        `setTransferFiles(org.ggf.drmaa.FileTransferMode)`

    - #### setDeadlineTime

          public void setDeadlineTime(PartialTimestamp deadline)
                               throws UnsupportedAttributeException

      Unsupported property. Will throw an UnsupportedAttributeException if called.
      Specified by:
        `setDeadlineTime` in interface `JobTemplate`
      Parameters:
        `deadline` - the deadline after which the DRMS will terminate the job
      Throws:
        `UnsupportedAttributeException` - unsupported property

    - #### getDeadlineTime

          public PartialTimestamp getDeadlineTime()
                                           throws UnsupportedAttributeException

      Unsupported property. Will throw an UnsupportedAttributeException if called.
      Specified by:
        `getDeadlineTime` in interface `JobTemplate`
      Returns:
        the deadline after which the DRMS will terminate the job
      Throws:
        `UnsupportedAttributeException` - unsupported property
      See Also:
        `JobTemplate.setDeadlineTime(PartialTimestamp)`

    - #### setHardWallclockTimeLimit

          public void setHardWallclockTimeLimit(long hardWallclockLimit)
                                         throws UnsupportedAttributeException

      Unsupported property. Will throw an UnsupportedAttributeException if called.
      Specified by:
        `setHardWallclockTimeLimit` in interface `JobTemplate`
      Parameters:
        `hardWallclockLimit` - when the job's wall clock time limit has been exceeded. Specified in seconds
      Throws:
        `UnsupportedAttributeException` - unsupported property

    - #### getHardWallclockTimeLimit

          public long getHardWallclockTimeLimit()
                                         throws UnsupportedAttributeException

      Unsupported property. Will throw an UnsupportedAttributeException if called.
      Specified by:
        `getHardWallclockTimeLimit` in interface `JobTemplate`
      Returns:
        when the job's wall clock time limit has been exceeded. Specified in seconds
      Throws:
        `UnsupportedAttributeException` - unsupported property
      See Also:
        `JobTemplate.setHardWallclockTimeLimit(long)`

    - #### setSoftWallclockTimeLimit

          public void setSoftWallclockTimeLimit(long softWallclockLimit)
                                         throws UnsupportedAttributeException

      Unsupported property. Will throw an UnsupportedAttributeException if called.
      Specified by:
        `setSoftWallclockTimeLimit` in interface `JobTemplate`
      Parameters:
        `softWallclockLimit` - an estimate as to how much wall clock time job will need to complete. Specified in seconds
      Throws:
        `UnsupportedAttributeException` - unsupported property

    - #### getSoftWallclockTimeLimit

          public long getSoftWallclockTimeLimit()
                                         throws UnsupportedAttributeException

      Unsupported property. Will throw an UnsupportedAttributeException if called.
      Specified by:
        `getSoftWallclockTimeLimit` in interface `JobTemplate`
      Returns:
        an estimate as to how much wall clock time job will need to complete. Specified in seconds
      Throws:
        `UnsupportedAttributeException` - unsupported property
      See Also:
        `JobTemplate.setSoftWallclockTimeLimit(long)`

    - #### setHardRunDurationLimit

          public void setHardRunDurationLimit(long hardRunLimit)
                                       throws UnsupportedAttributeException

      Unsupported property. Will throw an UnsupportedAttributeException if called.
      Specified by:
        `setHardRunDurationLimit` in interface `JobTemplate`
      Parameters:
        `hardRunLimit` - how long the job may be in a running state before its limit has been exceeded. Specified in seconds
      Throws:
        `UnsupportedAttributeException` - unsupported property

    - #### getHardRunDurationLimit

          public long getHardRunDurationLimit()
                                       throws UnsupportedAttributeException

      Unsupported property. Will throw an UnsupportedAttributeException if called.
      Specified by:
        `getHardRunDurationLimit` in interface `JobTemplate`
      Returns:
        how long the job may be in a running state before its limit has been exceeded. Specified in seconds
      Throws:
        `UnsupportedAttributeException` - unsupported property
      See Also:
        `JobTemplate.setHardRunDurationLimit(long)`

    - #### setSoftRunDurationLimit

          public void setSoftRunDurationLimit(long softRunLimit)
                                       throws UnsupportedAttributeException

      Unsupported property. Will throw an UnsupportedAttributeException if called.
      Specified by:
        `setSoftRunDurationLimit` in interface `JobTemplate`
      Parameters:
        `softRunLimit` - an estimate as to how long the job will need to remain in a running state to complete. Specified in seconds
      Throws:
        `UnsupportedAttributeException` - unsupported property

    - #### getSoftRunDurationLimit

          public long getSoftRunDurationLimit()
                                       throws UnsupportedAttributeException

      Unsupported property. Will throw an UnsupportedAttributeException if called.
      Specified by:
        `getSoftRunDurationLimit` in interface `JobTemplate`
      Returns:
        an estimate as to how long the job will need to remain in a running state to complete. Specified in seconds
      Throws:
        `UnsupportedAttributeException` - unsupported property
      See Also:
        `JobTemplate.setSoftRunDurationLimit(long)`

    - #### getAttributeNames

          public java.util.Set getAttributeNames()
                                          throws DrmaaException

      Returns the list of supported properties names. With the execd param, delegated_file_staging, set to false, this list includes only the list of DRMAA required properties. With delegated_file_staging set to true, the list also includes the transferFiles property.
      Specified by:
        `getAttributeNames` in interface `JobTemplate`
      Returns:
        the list of supported property names
      Throws:
        `DrmaaException` - May be one of the following:
        - NoActiveSessionException -- the session has not yet been initialized or has already been exited
        - DrmCommunicationException -- the DRMAA implementation was unable to contact the DRM
        - AuthorizationException -- the executing user does not have sufficient permissions to execute the desired action
        - InternalException -- an error has occured in the DRMAA implementation

    - #### equals

          public boolean equals(java.lang.Object obj)

      Tests whether this JobTemplateImpl represents the same native job template as the given object. This implementation means that even if two JobTemplateImpl instance's have all the same settings, they are not equal, because they are associated with different native job templates.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - the object against which to compare
      Returns:
        whether the the given object is the same as this object

    - #### hashCode

          public int hashCode()

      Returns a hash code based on the associated native job template's table index.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        the hash code

The contents of this file are licensed under the Sun Industry Standards Source License version 1.2.
Copyright 2008, Sun Microsystems, Inc.