public class JobTemplateImpl extends java.lang.Object implements JobTemplate
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.
The following DRMAA attributes correspond to the following qsub options:
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:
Using the accessors for any of these attributes will result in an UnsupportedAttributeException being thrown.
JobTemplate
,
Session
,
SessionImpl
,
sge_request(5),
qsub(1),
qtask(5)ACTIVE_STATE, HOLD_STATE, HOME_DIRECTORY, PARAMETRIC_INDEX
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.
|
public void setRemoteCommand(java.lang.String remoteCommand) throws DrmaaException
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.
setRemoteCommand
in interface JobTemplate
remoteCommand
- the command to execute as the jobDrmaaException
- May be one of the following:
public java.lang.String getRemoteCommand() throws DrmaaException
getRemoteCommand
in interface JobTemplate
DrmaaException
- May be one of the following:
setRemoteCommand(String)
public void setArgs(java.util.List args) throws DrmaaException
setArgs
in interface JobTemplate
args
- the parameters passed as arguments to the jobDrmaaException
- May be one of the following:
public java.util.List getArgs() throws DrmaaException
getArgs
in interface JobTemplate
DrmaaException
- May be one of the following:
setArgs(List)
public void setJobSubmissionState(int state) throws DrmaaException
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".
setJobSubmissionState
in interface JobTemplate
state
- the job state at submissionDrmaaException
- May be one of the following:
public int getJobSubmissionState() throws DrmaaException
getJobSubmissionState
in interface JobTemplate
DrmaaException
- May be one of the following:
setJobSubmissionState(int)
public void setJobEnvironment(java.util.Map env) throws DrmaaException
setJobEnvironment
in interface JobTemplate
env
- the environment values that define the remote environmentDrmaaException
- May be one of the following:
public java.util.Map getJobEnvironment() throws DrmaaException
getJobEnvironment
in interface JobTemplate
DrmaaException
- May be one of the following:
setJobEnvironment(Map)
public void setWorkingDirectory(java.lang.String wd) throws DrmaaException
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.
setWorkingDirectory
in interface JobTemplate
wd
- the directory where the job is executedDrmaaException
- May be one of the following:
JobTemplate.HOME_DIRECTORY
,
JobTemplate.PARAMETRIC_INDEX
,
Session.FAILED
public java.lang.String getWorkingDirectory() throws DrmaaException
getWorkingDirectory
in interface JobTemplate
DrmaaException
- May be one of the following:
setWorkingDirectory(String)
public void setJobCategory(java.lang.String category) throws DrmaaException
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.
setJobCategory
in interface JobTemplate
category
- an opaque string specifying how to resolve site-specific
resources and/or policies.DrmaaException
- May be one of the following:
public java.lang.String getJobCategory() throws DrmaaException
getJobCategory
in interface JobTemplate
DrmaaException
- May be one of the following:
setJobCategory(String)
public void setNativeSpecification(java.lang.String spec) throws DrmaaException
setNativeSpecification
in interface JobTemplate
spec
- an opaque string that is passed by the end user to DRMAA to
specify site-specific resources and/or policiesDrmaaException
- May be one of the following:
public java.lang.String getNativeSpecification() throws DrmaaException
getNativeSpecification
in interface JobTemplate
DrmaaException
- May be one of the following:
setNativeSpecification(String)
public void setEmail(java.util.Set email) throws DrmaaException
setEmail
in interface JobTemplate
email
- the list of email addresses used to report the job
completion and status.DrmaaException
- May be one of the following:
public java.util.Set getEmail() throws DrmaaException
getEmail
in interface JobTemplate
DrmaaException
- May be one of the following:
setEmail(java.util.Set)
public void setBlockEmail(boolean blockEmail) throws DrmaaException
setBlockEmail
in interface JobTemplate
blockEmail
- whether to block sending e-mail by defaultDrmaaException
- May be one of the following:
public boolean getBlockEmail() throws DrmaaException
getBlockEmail
in interface JobTemplate
DrmaaException
- May be one of the following:
setBlockEmail(boolean)
public void setStartTime(PartialTimestamp startTime) throws DrmaaException
setStartTime
in interface JobTemplate
startTime
- the earliest time when the job may be eligible to be runDrmaaException
- May be one of the following:
PartialTimestamp
public PartialTimestamp getStartTime() throws DrmaaException
getStartTime
in interface JobTemplate
DrmaaException
- May be one of the following:
setStartTime(org.ggf.drmaa.PartialTimestamp)
public void setJobName(java.lang.String name) throws DrmaaException
setJobName
in interface JobTemplate
name
- the name of the jobDrmaaException
- May be one of the following:
public java.lang.String getJobName() throws DrmaaException
getJobName
in interface JobTemplate
DrmaaException
- May be one of the following:
setJobName(String)
public void setInputPath(java.lang.String inputPath) throws DrmaaException
[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
.
setInputPath
in interface JobTemplate
inputPath
- the job's standard input pathDrmaaException
- May be one of the following:
JobTemplate.HOME_DIRECTORY
,
JobTemplate.WORKING_DIRECTORY
,
JobTemplate.PARAMETRIC_INDEX
,
Session.FAILED
public java.lang.String getInputPath() throws DrmaaException
getInputPath
in interface JobTemplate
DrmaaException
- May be one of the following:
setInputPath(String)
public void setOutputPath(java.lang.String outputPath) throws DrmaaException
[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
.
setOutputPath
in interface JobTemplate
outputPath
- how to direct the job's standard outputDrmaaException
- May be one of the following:
JobTemplate.HOME_DIRECTORY
,
JobTemplate.WORKING_DIRECTORY
,
JobTemplate.PARAMETRIC_INDEX
,
Session.FAILED
public java.lang.String getOutputPath() throws DrmaaException
getOutputPath
in interface JobTemplate
DrmaaException
- May be one of the following:
setOutputPath(String)
public void setErrorPath(java.lang.String errorPath) throws DrmaaException
[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
.
setErrorPath
in interface JobTemplate
errorPath
- how to direct the job's standard errorDrmaaException
- May be one of the following:
JobTemplate.HOME_DIRECTORY
,
JobTemplate.WORKING_DIRECTORY
,
JobTemplate.PARAMETRIC_INDEX
,
Session.FAILED
public java.lang.String getErrorPath() throws DrmaaException
getErrorPath
in interface JobTemplate
DrmaaException
- May be one of the following:
setErrorPath(String)
public void setJoinFiles(boolean join) throws DrmaaException
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.setJoinFiles
in interface JobTemplate
join
- whether the error stream should be intermixed with the output
streamDrmaaException
- May be one of the following:
public boolean getJoinFiles() throws DrmaaException
getJoinFiles
in interface JobTemplate
DrmaaException
- May be one of the following:
setJoinFiles(boolean)
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.
setTransferFiles
in interface JobTemplate
mode
- how to transfer files between hosts.DrmaaException
- May be one of the following:
setInputPath(String)
,
setOutputPath(String)
,
setErrorPath(String)
,
sge_conf(5)public FileTransferMode getTransferFiles() throws DrmaaException
getTransferFiles
in interface JobTemplate
DrmaaException
- May be one of the following:
setTransferFiles(org.ggf.drmaa.FileTransferMode)
public void setDeadlineTime(PartialTimestamp deadline) throws UnsupportedAttributeException
setDeadlineTime
in interface JobTemplate
deadline
- the deadline after which the DRMS will terminate the jobUnsupportedAttributeException
- unsupported propertypublic PartialTimestamp getDeadlineTime() throws UnsupportedAttributeException
getDeadlineTime
in interface JobTemplate
UnsupportedAttributeException
- unsupported propertyJobTemplate.setDeadlineTime(PartialTimestamp)
public void setHardWallclockTimeLimit(long hardWallclockLimit) throws UnsupportedAttributeException
setHardWallclockTimeLimit
in interface JobTemplate
hardWallclockLimit
- when the job's wall clock time limit has been
exceeded. Specified in secondsUnsupportedAttributeException
- unsupported propertypublic long getHardWallclockTimeLimit() throws UnsupportedAttributeException
getHardWallclockTimeLimit
in interface JobTemplate
UnsupportedAttributeException
- unsupported propertyJobTemplate.setHardWallclockTimeLimit(long)
public void setSoftWallclockTimeLimit(long softWallclockLimit) throws UnsupportedAttributeException
setSoftWallclockTimeLimit
in interface JobTemplate
softWallclockLimit
- an estimate as to how much wall clock time job
will need to complete. Specified in secondsUnsupportedAttributeException
- unsupported propertypublic long getSoftWallclockTimeLimit() throws UnsupportedAttributeException
getSoftWallclockTimeLimit
in interface JobTemplate
UnsupportedAttributeException
- unsupported propertyJobTemplate.setSoftWallclockTimeLimit(long)
public void setHardRunDurationLimit(long hardRunLimit) throws UnsupportedAttributeException
setHardRunDurationLimit
in interface JobTemplate
hardRunLimit
- how long the job may be in a running state before its
limit has been exceeded. Specified in secondsUnsupportedAttributeException
- unsupported propertypublic long getHardRunDurationLimit() throws UnsupportedAttributeException
getHardRunDurationLimit
in interface JobTemplate
UnsupportedAttributeException
- unsupported propertyJobTemplate.setHardRunDurationLimit(long)
public void setSoftRunDurationLimit(long softRunLimit) throws UnsupportedAttributeException
setSoftRunDurationLimit
in interface JobTemplate
softRunLimit
- an estimate as to how long the job will need to
remain in a running state to complete. Specified in secondsUnsupportedAttributeException
- unsupported propertypublic long getSoftRunDurationLimit() throws UnsupportedAttributeException
getSoftRunDurationLimit
in interface JobTemplate
UnsupportedAttributeException
- unsupported propertyJobTemplate.setSoftRunDurationLimit(long)
public java.util.Set getAttributeNames() throws DrmaaException
getAttributeNames
in interface JobTemplate
DrmaaException
- May be one of the following:
public boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
obj
- the object against which to comparepublic int hashCode()
hashCode
in class java.lang.Object
The contents of this file are licensed under the Sun Industry Standards Source License version 1.2.
Copyright 2008, Sun Microsystems, Inc.