org.ggf.drmaa
Interface JobTemplate

All Known Implementing Classes:
JobTemplateImpl, SimpleJobTemplate

public interface JobTemplate

This interface represents a template to be used for the creation of a job. The properties set on a JobTemplate instance are used to create a new job and set up the new job's environment.

There is a 1:n relationship between JobTemplate instances and jobs. A single JobTemplate instance can be used to submit any number of jobs. Once a job has been submitted, e.g. via Session.runJob(), the JobTemplate instance no longer has any affect on that job. Changes made to the JobTemplate instance will have no affect on already running jobs. Deleting the JobTemplate instance (via Session.deleteJobTemplate()) also has no effect on running jobs.

Once a JobTemplate instance has been created (via Session.createJobTemplate()), it is the responsibility of the developer to delete it when no longer needed (via Session.deleteJobTemplate ()). Failure to do so may result in a memory leak.

Example:

public static void main(String[] args) {
   SessionFactory factory = SessionFactory.getFactory();
   Session session = factory.getSession();

   try {
      session.init("");
      JobTemplate jt = session.createJobTemplate();
      jt.setRemoteCommand("sleeper.sh");
      jt.setWorkingDirectory(":" + HOME_DIRECTORY + "/jobs");
      jt.setArgs(Collections.singletonList("5"));

      String id = session.runJob(jt);

      session.deleteJobTemplate(jt);
      session.exit();
   }
   catch (DrmaaException e) {
      System.out.println("Error: " + e.getMessage ());
   }
 }
 

Since:
0.4.2
Version:
1.0
Author:
dan.templeton@sun.com
See Also:
Session

Field Summary
static int ACTIVE_STATE
          Means the job has been queued and is eligible to run.
static int HOLD_STATE
          Means the job has been queued but it is not eligible to run.
static java.lang.String HOME_DIRECTORY
          Placeholder which represents the home directory in the workingDirectory, inputPath, outputPath, and errorPath properties
static java.lang.String PARAMETRIC_INDEX
          Placeholder which represents the job id for a job in a parametric job set in the inputPath, outputPath, and errorPath properties
static java.lang.String WORKING_DIRECTORY
          Placeholder which represents the working directory in the workingDirectory, inputPath, outputPath, and errorPath properties
 
Method Summary
 java.util.List getArgs()
          Get the arguments to the job.
 java.util.Set getAttributeNames()
          Returns the list of supported property names.
 boolean getBlockEmail()
          Get whether to block sending e-mail by default, regardless of the DRMS settings.
 PartialTimestamp getDeadlineTime()
          Sets a deadline after which the DRMS will terminate the job.
 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()
          Gets how long the job may be in a running state before its limit has been exceeded.
 long getHardWallclockTimeLimit()
          Gets the duration of the job's wall clock time limit.
 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()
          Gets an estimate as to how long the job will need to remain in a running state to complete.
 long getSoftWallclockTimeLimit()
          Gets an estimate as to how much wall clock time job will need to complete.
 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.
 void setArgs(java.util.List args)
          Sets the arguments to the job.
 void setBlockEmail(boolean blockEmail)
          Set whether to block sending e-mail by default, regardless of the DRMS settings.
 void setDeadlineTime(PartialTimestamp deadline)
          Sets a deadline after which the DRMS will terminate the job.
 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)
          Sets how long the job may be in a running state before its limit has been exceeded, and therefore is terminated by the DRMS.
 void setHardWallclockTimeLimit(long hardWallclockLimit)
          Sets when the job's wall clock time limit has been exceeded.
 void setInputPath(java.lang.String inputPath)
          Set the job's standard input path.
 void setJobCategory(java.lang.String category)
          Set an opaque string specifying how to resolve site-specific resources and/or policies.
 void setJobEnvironment(java.util.Map env)
          Set the environment values that define the remote environment.
 void setJobName(java.lang.String name)
          Set the name of the job.
 void setJobSubmissionState(int state)
          Set 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)
          Set an opaque string that is passed by the end user to DRMAA to specify site-specific resources and/or policies.
 void setOutputPath(java.lang.String outputPath)
          Sets how to direct the job's standard output.
 void setRemoteCommand(java.lang.String remoteCommand)
          Set the command string to execute as the job.
 void setSoftRunDurationLimit(long softRunLimit)
          Sets an estimate as to how long the job will need to remain in a running state to complete.
 void setSoftWallclockTimeLimit(long softWallclockLimit)
          Sets an estimate as to how much wall clock time job will need to complete.
 void setStartTime(PartialTimestamp startTime)
          Set the earliest time when the job may be eligible to be run.
 void setTransferFiles(FileTransferMode mode)
          Specifies, which of the standard I/O files (stdin, stdout and stderr) are to be transferred to/from the execution host.
 void setWorkingDirectory(java.lang.String wd)
          Set the directory where the job is executed.
 

Field Detail

HOLD_STATE

public static final int HOLD_STATE
Means the job has been queued but it is not eligible to run. Used with the jobSubmissionState property.

See Also:
Constant Field Values

ACTIVE_STATE

public static final int ACTIVE_STATE
Means the job has been queued and is eligible to run. Used with the jobSubmissionState property.

See Also:
Constant Field Values

HOME_DIRECTORY

public static final java.lang.String HOME_DIRECTORY
Placeholder which represents the home directory in the workingDirectory, inputPath, outputPath, and errorPath properties

See Also:
Constant Field Values

WORKING_DIRECTORY

public static final java.lang.String WORKING_DIRECTORY
Placeholder which represents the working directory in the workingDirectory, inputPath, outputPath, and errorPath properties

See Also:
Constant Field Values

PARAMETRIC_INDEX

public static final java.lang.String PARAMETRIC_INDEX
Placeholder which represents the job id for a job in a parametric job set in the inputPath, outputPath, and errorPath properties

See Also:
Constant Field Values
Method Detail

setRemoteCommand

public void setRemoteCommand(java.lang.String remoteCommand)
                      throws DrmaaException
Set the command string to execute as the job. The command is relative to the execution host and is evaluated on the execution host.

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.

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
Sets the arguments to the job.

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.

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
Set the job state at submission. The states are HOLD_STATE and ACTIVE_STATE:

A job submitted in the HOLD_STATE state can be made eligible to run through the Session.control() method using the Session.RELEASE constant.

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

getJobSubmissionState

public int getJobSubmissionState()
                          throws DrmaaException
Get the job state at submission.

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
Set the environment values that define the remote environment. The values override any remote environment values if there is a collision.

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.

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
Set the directory where the job is executed. If the working directory is not set, behavior is implementation dependent. The working directory is evaluated relative to the execution host.

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

The PARAMETRIC_INDEX placeholder can be used at any position within the directory name of a parametric job and will be replaced by the underlying DRM system 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 expected.

If the directory does not exist when the job is run, the job enters the state Session.FAILED.

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

getWorkingDirectory

public java.lang.String getWorkingDirectory()
                                     throws DrmaaException
Get the directory where the job is executed.

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
Set an opaque string specifying how to resolve site-specific resources and/or policies. The job category can be used, for example, to submit jobs that are "low priority" jobs. It is then up to the local DRM administrator to map "low priority" to a set of appropriate job submission characteristics, such as reduced memory allowance or lower priority value.

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

getJobCategory

public java.lang.String getJobCategory()
                                throws DrmaaException
Get the opaque string specifying how to resolve site-specific resources and/or policies.

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
Set an opaque string that is passed by the end user to DRMAA to specify site-specific resources and/or policies.

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

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.

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.

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.

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(Set)

setBlockEmail

public void setBlockEmail(boolean blockEmail)
                   throws DrmaaException
Set whether to block sending e-mail by default, regardless of the DRMS settings. This property can only be used to prevent email from being sent. It cannot force the DRM to send email.

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.

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.

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

getStartTime

public PartialTimestamp getStartTime()
                              throws DrmaaException
Get the earliest time when the job may be eligible to be run.

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(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. The DRMAA implementation may truncate client provided job names to an implementation defined length that is at least 31 characters.

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

getJobName

public java.lang.String getJobName()
                            throws DrmaaException
Get the name of the job.

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 set, specifies the network path of the job's input stream in the form of [hostname]:file_path

When the transferFiles property is supported and has it's inputStream property set, the input file will be fetched by the underlying DRM system from the specified host or from the submit host if no hostname is specified.

When the transferFiles property is not supported or does not have its inputStream property set, the input file is always expected to be at the host where the job is executed irrespective of a whether a hostname is specified in the path.

The PARAMETRIC_INDEX placeholder can be used at any position within the file path of parametric job templates and will be replaced by the underlying DRM system with the parametric job's index.

A HOME_DIRECTORY placeholder at the beginning of the file path denotes that the remaining portion of the file path is relative to the job submiter's home directory on the host where the file is located.

A WORKING_DIRECTORY placeholder at the beginning of the file path denotes that the remaining portion of the file path is relative to the job's working directory on the host where the file is located.

The file path must be specified in a syntax that is common at the host where the file is located.

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

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

getInputPath

public java.lang.String getInputPath()
                              throws DrmaaException
Get the job's standard input path.

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. If not explicitly set in the job template, the whereabouts of the jobs output stream is not defined. If set, 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 has its outputStream property set, the output file will be transferred by the underlying DRM system to the specified host or to the submit host if no hostname is specified.

When the transferFiles property is not supported or does not have it's outputStream property set, the output file is always kept at the host where the job is executed irrespective of a whether a hostname is specified in the path.

The PARAMETRIC_INDEX placeholder can be used at any position within the file path of parametric job templates and will be replaced by the underlying DRM system with the parametric job's index.

A HOME_DIRECTORY placeholder at the beginning of the file path denotes that the remaining portion of the file path is relative to the job submiter's home directory on the host where the file is located.

A WORKING_DIRECTORY placeholder at the beginning of the file path denotes that the remaining portion of the file path is relative to the job's working directory on the host where the file is located.

The file path must be specified in a syntax that is common at the host where the file is located.

When the job is run, if this property is set, and the file can't be written before execution the job will enter the state Session.FAILED.

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

getOutputPath

public java.lang.String getOutputPath()
                               throws DrmaaException
Gets how to direct the job's standard output.

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. If not explicitly set in the job template, the whereabouts of the job's error stream is not defined. If set, specifies the network path of the job's error stream file in the form [hostname]:file_path

When the transferFiles property is supported and has its errorStream property set, the error file will be transferred by the underlying DRM system to the specified host or to the submit host if no hostname is specified.

When the transferFiles property is not supported or does not have it's errorStream property set, the error file is always kept at the host where the job is executed irrespective of a whether a hostname is specified in the path.

The PARAMETRIC_INDEX placeholder can be used at any position within the file path of parametric job templates and will be replaced by the underlying DRM system with the parametric job's index.

A HOME_DIRECTORY placeholder at the beginning of the file path denotes that the remaining portion of the file path is relative to the job submiter's home directory on the host where the file is located.

A WORKING_DIRECTORY placeholder at the beginning of the file path denotes that the remaining portion of the file path is relative to the job's working directory on the host where the file is located.

The file path must be specified in a syntax that is common at the host where the file is located.

When the job is run, if this property is set, and the file can't be written before execution the job will enter the state Session.FAILED.

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

getErrorPath

public java.lang.String getErrorPath()
                              throws DrmaaException
Gets how to direct the job's standard error.

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 this property defaults to false.

If true is specified 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 by the outputPath property.

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.

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

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)

getTransferFiles

public FileTransferMode getTransferFiles()
                                  throws DrmaaException
Gets how to transfer files between hosts.

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(FileTransferMode)

setDeadlineTime

public void setDeadlineTime(PartialTimestamp deadline)
                     throws DrmaaException
Sets a deadline after which the DRMS will terminate the job.

Parameters:
deadline - the deadline after which the DRMS will terminate 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

getDeadlineTime

public PartialTimestamp getDeadlineTime()
                                 throws DrmaaException
Sets a deadline after which the DRMS will terminate the job.

Returns:
the deadline after which the DRMS will terminate the job
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:
setDeadlineTime(PartialTimestamp)

setHardWallclockTimeLimit

public void setHardWallclockTimeLimit(long hardWallclockLimit)
                               throws DrmaaException
Sets when the job's wall clock time limit has been exceeded. The DRMS will terminate a job that has exceeded its wall clock time limit. Note that time spent suspended is also accounted for here.

Parameters:
hardWallclockLimit - when the job's wall clock time limit has been exceeded. Specified in seconds
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

getHardWallclockTimeLimit

public long getHardWallclockTimeLimit()
                               throws DrmaaException
Gets the duration of the job's wall clock time limit.

Returns:
when the job's wall clock time limit has been exceeded. Specified in seconds
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:
setHardWallclockTimeLimit(long)

setSoftWallclockTimeLimit

public void setSoftWallclockTimeLimit(long softWallclockLimit)
                               throws DrmaaException
Sets an estimate as to how much wall clock time job will need to complete. Note that time spent suspended is also accounted for here.

This attribute is intended to assist the scheduler. If the time specified in insufficient, the drmaa-implementation may impose a scheduling penalty.

Parameters:
softWallclockLimit - an estimate as to how much wall clock time job will need to complete. Specified in seconds
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

getSoftWallclockTimeLimit

public long getSoftWallclockTimeLimit()
                               throws DrmaaException
Gets an estimate as to how much wall clock time job will need to complete.

Returns:
an estimate as to how much wall clock time job will need to complete. Specified in seconds
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:
setSoftWallclockTimeLimit(long)

setHardRunDurationLimit

public void setHardRunDurationLimit(long hardRunLimit)
                             throws DrmaaException
Sets how long the job may be in a running state before its limit has been exceeded, and therefore is terminated by the DRMS.

Parameters:
hardRunLimit - how long the job may be in a running state before its limit has been exceeded. Specified in seconds
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

getHardRunDurationLimit

public long getHardRunDurationLimit()
                             throws DrmaaException
Gets how long the job may be in a running state before its limit has been exceeded.

Returns:
how long the job may be in a running state before its limit has been exceeded. Specified in seconds
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:
setHardRunDurationLimit(long)

setSoftRunDurationLimit

public void setSoftRunDurationLimit(long softRunLimit)
                             throws DrmaaException
Sets an estimate as to how long the job will need to remain in a running state to complete. This attribute is intended to assist the scheduler. If the time specified in insufficient, the DRMAA implementation may impose a scheduling penalty.

Parameters:
softRunLimit - an estimate as to how long the job will need to remain in a running state to complete. Specified in seconds
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

getSoftRunDurationLimit

public long getSoftRunDurationLimit()
                             throws DrmaaException
Gets an estimate as to how long the job will need to remain in a running state to complete.

Returns:
an estimate as to how long the job will need to remain in a running state to complete. Specified in seconds
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:
setSoftRunDurationLimit(long)

getAttributeNames

public java.util.Set getAttributeNames()
                                throws DrmaaException
Returns the list of supported property names. This list includes supported DRMAA reserved property names (both required and optional) and DRM-specific property names.

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


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