Interface Session
-
- All Known Implementing Classes:
SessionImpl
public interface Session
This interface represents the operations available for interacting with the DRM. In DRMAA, (almost) all DRM interaction occur within the context of a session. The DRMAA specification also strongly recommends that a DRMAA implementation not allow concurrent sessions. Since DRMAA has no facility for user authentication or authorization, most DRMAA implementations will likely only support one session per implementation instance.In order to use a Session, it must first be initialized. Once initialized it is the responsibility of the programmer to ensure that the session also be explicitly terminated. Otherwise, session artifacts may be left behind on the client and/or server. A handy way to make sure the Session is terminated is to set up a shutdown hook to call the exit() method on the active session.
To get a Session implementation appropriate for the DRM in use, one uses the SessionFactory.getSession() method.
Example:
public static void main(String[] args) throws Exception { SessionFactory factory = SessionFactory.getFactory(); Session session = factory.getSession(); try { session.init(""); JobTemplate jt = session.createJobTemplate(); jt.setRemoteCommand("sleeper.sh"); jt.setArgs(Collections.singletonList("5")); String id = session.runJob(jt); session.deleteJobTemplate(jt); while (session.getJobProgramStatus(id) != Session.RUNNING) { Thread.sleep(1000); } System.out.println("Job " + id + " is now running."); session.control(id, Session.SUSPEND); Thread.sleep(1000); session.control(id, Session.RELEASE); JobInfo info = session.wait(id, Session.TIMEOUT_WAIT_FOREVER); System.out.println("Job " + info.getJobId () + " exited with status: " + info.getExitStatus ()); session.exit(); } catch (DrmaaException e) { System.out.println("Error: " + e.getMessage ()); } }
- Since:
- 0.5
- Version:
- 1.0
- See Also:
Runtime.addShutdownHook(java.lang.Thread)
,SessionFactory
, Grid Engine DRMAA Java™ Language Binding HowTo
-
-
Field Summary
Fields Modifier and Type Field Description static int
DONE
Job has finished normally.static int
FAILED
Job finished, but terminated abnormally.static int
HOLD
Put the job on hold.static java.lang.String
JOB_IDS_SESSION_ALL
All jobs submitted during this DRMAA session.static java.lang.String
JOB_IDS_SESSION_ANY
Any job from the session.static int
QUEUED_ACTIVE
Job is queued and active.static int
RELEASE
Release the hold on the job.static int
RESUME
Resume the job.static int
RUNNING
Job is running.static int
SUSPEND
Suspend the job.static int
SYSTEM_ON_HOLD
Job is queued and in system hold.static int
SYSTEM_SUSPENDED
Job is system suspended.static int
TERMINATE
Kill the job.static long
TIMEOUT_NO_WAIT
Return immediately if no result is available.static long
TIMEOUT_WAIT_FOREVER
Wait indefinitely for a result.static int
UNDETERMINED
Job status cannot be determined.static int
USER_ON_HOLD
Job is queued and in user hold.static int
USER_SUSPENDED
Job is user suspended.static int
USER_SYSTEM_ON_HOLD
Job is queued and in user and system hold.static int
USER_SYSTEM_SUSPENDED
Job is user suspended.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
control(java.lang.String jobId, int action)
Hold, release, suspend, resume, or kill the job identified by jobId.JobTemplate
createJobTemplate()
Get a new job template.void
deleteJobTemplate(JobTemplate jt)
Deallocate a job template.void
exit()
Disengage from the DRM and allow the DRMAA implementation to perform any necessary internal cleanup.java.lang.String
getContact()
If called before init(), this method returns a comma delimited String containing the contact Strings available from the default DRMAA implementation, one element per DRM system available.java.lang.String
getDrmaaImplementation()
If called before init(), this method returns a comma delimited list of available DRMAA implementations, one element for each DRMAA implementation provided.java.lang.String
getDrmSystem()
If called before init(), this method returns a comma delimited list of available DRM systems, one element per DRM system implementation provided.int
getJobProgramStatus(java.lang.String jobId)
Get the program status of the job identified by jobId.Version
getVersion()
Returns a Version instance containing the major and minor version numbers of the DRMAA library.void
init(java.lang.String contact)
Initialize the DRMAA implementation.java.util.List
runBulkJobs(JobTemplate jt, int start, int end, int incr)
Submit a range of parametric jobs, each with attributes defined in the job template, jt.java.lang.String
runJob(JobTemplate jt)
Submit a job with attributes defined in the job template, jt.void
synchronize(java.util.List jobIds, long timeout, boolean dispose)
Wait until all jobs specified by jobIds have finished execution.JobInfo
wait(java.lang.String jobId, long timeout)
This method will wait for a job with jobId to finish execution or fail.
-
-
-
Field Detail
-
SUSPEND
static final int SUSPEND
Suspend the job. Used with the Session.control() method.- See Also:
- Constant Field Values
-
RESUME
static final int RESUME
Resume the job. Used with the Session.control() method.- See Also:
- Constant Field Values
-
HOLD
static final int HOLD
Put the job on hold. Used with the Session.control() method.- See Also:
- Constant Field Values
-
RELEASE
static final int RELEASE
Release the hold on the job. Used with the Session.control() method.- See Also:
- Constant Field Values
-
TERMINATE
static final int TERMINATE
Kill the job. Used with the Session.control() method.- See Also:
- Constant Field Values
-
JOB_IDS_SESSION_ALL
static final java.lang.String JOB_IDS_SESSION_ALL
All jobs submitted during this DRMAA session. Used with the Session.control() and Session.synchronize() methods.- See Also:
- Constant Field Values
-
JOB_IDS_SESSION_ANY
static final java.lang.String JOB_IDS_SESSION_ANY
Any job from the session. Used with the Session.wait() method.- See Also:
- Constant Field Values
-
TIMEOUT_WAIT_FOREVER
static final long TIMEOUT_WAIT_FOREVER
Wait indefinitely for a result. Used with the Session.wait() and Session.synchronize() methods.- See Also:
- Constant Field Values
-
TIMEOUT_NO_WAIT
static final long TIMEOUT_NO_WAIT
Return immediately if no result is available. Used with the Session.wait() and Session.synchronize() methods.- See Also:
- Constant Field Values
-
UNDETERMINED
static final int UNDETERMINED
Job status cannot be determined. Used with the Session.getJobProgramStatus() method.- See Also:
- Constant Field Values
-
QUEUED_ACTIVE
static final int QUEUED_ACTIVE
Job is queued and active. Used with the Session.getJobProgramStatus() method.- See Also:
- Constant Field Values
-
SYSTEM_ON_HOLD
static final int SYSTEM_ON_HOLD
Job is queued and in system hold. Used with the Session.getJobProgramStatus() method.- See Also:
- Constant Field Values
-
USER_ON_HOLD
static final int USER_ON_HOLD
Job is queued and in user hold. Used with the Session.getJobProgramStatus() method.- See Also:
- Constant Field Values
-
USER_SYSTEM_ON_HOLD
static final int USER_SYSTEM_ON_HOLD
Job is queued and in user and system hold. Used with the Session.getJobProgramStatus() method.- See Also:
- Constant Field Values
-
RUNNING
static final int RUNNING
Job is running. Used with the Session.getJobProgramStatus() method.- See Also:
- Constant Field Values
-
SYSTEM_SUSPENDED
static final int SYSTEM_SUSPENDED
Job is system suspended. Used with the Session.getJobProgramStatus() method.- See Also:
- Constant Field Values
-
USER_SUSPENDED
static final int USER_SUSPENDED
Job is user suspended. Used with the Session.getJobProgramStatus() method.- See Also:
- Constant Field Values
-
USER_SYSTEM_SUSPENDED
static final int USER_SYSTEM_SUSPENDED
Job is user suspended. Used with the Session.getJobProgramStatus() method.- See Also:
- Constant Field Values
-
DONE
static final int DONE
Job has finished normally. Used with the Session.getJobProgramStatus() method.- See Also:
- Constant Field Values
-
FAILED
static final int FAILED
Job finished, but terminated abnormally. Used with the Session.getJobProgramStatus() method.- See Also:
- Constant Field Values
-
-
Method Detail
-
init
void init(java.lang.String contact) throws DrmaaException
Initialize the DRMAA implementation. contact is an implementation-dependent string that may be used to specify which DRM system to use. This routine must be called before any other DRMAA calls, except for getDrmSystem(), getDrmaaImplementation(), and getContact().If contact is
null
or "", the default DRM system is used, provided there is only one DRMAA implementation available. If there is more than one DRMAA implementation available, init() throws a NoDefaultContactStringSelectedException.init() should be called only once, by only one of the threads. The main thread is recommended. A call to init() by another thread or additional calls to init() by the same thread with throw a SessionAlreadyActiveException.
- Parameters:
contact
- implementation-dependent string that may be used to specify which DRM system to use.- Throws:
DrmaaException
- May be be one of the following:- DrmsInitException -- the session could not be initialized
- InvalidContactStringException -- the contact string is invalid
- AlreadyActiveSessionException -- the session has already been initialized
- DefaultContactStringException -- no contact string was specified, and the DRMAA implementation was unable to use the default contact information to connect to a DRM
- NoDefaultContactStringSelectedException -- no contact string was specified, and the DRMAA implementation has no default contact information
- 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
-
exit
void exit() throws DrmaaException
Disengage from the DRM and allow the DRMAA implementation to perform any necessary internal cleanup. This routine ends the current DRMAA session but doesn't affect any jobs which have already been submitted (e.g., queued and running jobs remain queued and running). exit() should be called only once, by only one of the threads. Additional calls to exit() beyond the first will throw a NoActiveSessionException.- Throws:
DrmaaException
- May be one of the following:- DrmsExitException -- an error occured while tearing down the session
- 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
-
createJobTemplate
JobTemplate createJobTemplate() throws DrmaaException
Get a new job template. A job template is used to set the environment for jobs to be submitted. Once a job template has been created, it should also be deleted (via deleteJobTemplate()) when no longer needed. Failure to do so may result in a memory leak.- Returns:
- a blank JobTemplate instance
- 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:
JobTemplate
-
deleteJobTemplate
void deleteJobTemplate(JobTemplate jt) throws DrmaaException
Deallocate a job template. This routine has no effect on jobs which have already been submitted.- Parameters:
jt
- the JobTemplate to delete- Throws:
DrmaaException
- May be one of the following:- InvalidJobTemplateException -- the JobTemplate instance does not belong to the current session, was not created with createJobTemplate(), or has already been deleted
- 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
-
runJob
java.lang.String runJob(JobTemplate jt) throws DrmaaException
Submit a job with attributes defined in the job template, jt. The returned job identifier is a String identical to that returned from the underlying DRM system.- Parameters:
jt
- the job template to be used to create the job- Returns:
- job identifier String identical to that returned from the underlying DRM system
- Throws:
DrmaaException
- May be one of the following:- TryLaterException -- the DRM was temporarily unable to fulfill the request, but a retry might succeed
- DeniedByDrmException -- the DRM has rejected the job due to configuration problems either in the DRM or the job template
- InvalidJobTemplateException -- the JobTemplate instance does not belong to the current session, was not created with createJobTemplate(), or has already been deleted
- 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
-
runBulkJobs
java.util.List runBulkJobs(JobTemplate jt, int start, int end, int incr) throws DrmaaException
Submit a range of parametric jobs, each with attributes defined in the job template, jt. The returned job identifiers are Strings identical to those returned from the underlying DRM system. The number of jobs submitted will be Math.floor((end - start + 1) / incr).The JobTemplate class defines a
PARAMETRIC_INDEX
placeholder for use in specifying paths in the job template. This placeholder is used to represent the individual identifiers of the tasks submitted through this method.- Parameters:
start
- the starting value for the loop indexend
- the terminating value for the loop indexincr
- the value by which to increment the loop index each iterationjt
- the job template to be used to create the job- Returns:
- job identifier Strings identical to that returned by the underlying DRM system
- Throws:
DrmaaException
- May be one of the following:- TryLaterException -- the DRM was temporarily unable to fulfill the request, but a retry might succeed
- DeniedByDrmException -- the DRM has rejected the job due to configuration problems either in the DRM or the job template
- InvalidJobTemplateException -- the JobTemplate instance does not belong to the current session, was not created with createJobTemplate(), or has already been deleted
- 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
-
control
void control(java.lang.String jobId, int action) throws DrmaaException
Hold, release, suspend, resume, or kill the job identified by jobId. If jobId is
JOB_IDS_SESSION_ALL
, then this routine acts on all jobs submitted during this DRMAA session up to the moment control() is called. To avoid thread races conditions in multithreaded applications, the DRMAA implementation user should explicitly synchronize this call with any other job submission or control calls that may change the number of remote jobs.The legal values for action and their meanings are:
SUSPEND
: stop the job,RESUME
: (re)start the job,HOLD
: put the job on-hold,RELEASE
: release the hold on the job, andTERMINATE
: kill the job.
This method returns once the action has been acknowledged by the DRM system, but it does not necessarily wait until the action has been completed.
Some DRMAA implementations may allow this method to be used to control jobs submitted external to the DRMAA session, such as jobs submitted by other DRMAA sessions or jobs submitted via native utilities.
If jobId is
JOB_IDS_SESSION_ALL
and the control action fails for one or more jobs, and InternalException will be thrown, and the state of the jobs in the session will be undefined.- Parameters:
jobId
- The id of the job to controlaction
- the control action to be taken- Throws:
DrmaaException
- May be one of the following:- ResumeInconsistentStateException -- an attempt was made to resume a job that was not is a suspended state
- SuspendInconsistentStateException -- an attempt was made to suspend a job that was not is a running state
- HoldInconsistentStateException -- an attempt was made to hold a job that was not is a pending state
- ReleaseInconsistentStateException -- an attempt was made to release a job that was not is a held state
- InvalidJobException -- the job identifier does not refer to an active job
- 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
-
synchronize
void synchronize(java.util.List jobIds, long timeout, boolean dispose) throws DrmaaException
Wait until all jobs specified by jobIds have finished execution. If jobIds containsJOB_IDS_SESSION_ALL
, then this method waits for all jobs submitted during this DRMAA session up to the moment synchronize() is called. To avoid thread race conditions in multithreaded applications, the DRMAA implementation user should explicitly synchronize this call with any other job submission or control calls that may change the number of remote jobs.To prevent blocking indefinitely in this call, the caller may use a timeout specifying how many seconds to block in this call. The value
TIMEOUT_WAIT_FOREVER
may be specified to wait indefinitely for a result. The valueTIMEOUT_NO_WAIT
may be specified to return immediately if no result is available. If the call exits before the timeout has elapsed, all the jobs have been waited on or there was an interrupt. If the invocation exits on timeout, an ExitTimeException is thrown. The caller should check system time before and after this call in order to be sure of how much time has passed.The dispose parameter specifies how to treat the reaping of the remote jobs' internal data records, which includes a record of the jobs' consumption of system resources during their execution and other statistical information. If this parameter is set to
true
, the DRM will dispose of the jobs' data records at the end of the synchroniize() call. If set tofalse
, the data records will be left for future access via the wait() method.- Parameters:
jobIds
- the ids of the jobs to synchronizetimeout
- the maximum number of seconds to waitdispose
- specifies how to treat reaping information- Throws:
DrmaaException
- May be one of the following:- ExitTimeoutException -- the operation timed out before completing
- InvalidJobException -- the job identifier does not refer to an active job
- 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:
wait(java.lang.String, long)
-
wait
JobInfo wait(java.lang.String jobId, long timeout) throws DrmaaException
This method will wait for a job with jobId to finish execution or fail. If the special string,JOB_IDS_SESSION_ANY
, is provided as the jobId, this routine will wait for any job from the session. This routine is modeled on the wait3 POSIX routine.The timeout value is used to specify the desired behavior when a result is not immediately available. The value,
TIMEOUT_WAIT_FOREVER
, may be specified to wait indefinitely for a result. The value,TIMEOUT_NO_WAIT
, may be specified to return immediately if no result is available. Alternatively, a number of seconds may be specified to indicate how long to wait for a result to become available.If the call exits before timeout, either the job has been waited on successfully or there was an interrupt. If the invocation exits on timeout, an ExitTimeoutException is thrown. The caller should check system time before and after this call in order to be sure how much time has passed.
The routine reaps job data records on a successful call, so any subsequent calls to wait(), synchronize(), control(), or getJobProgramStatus() will fail, throwing an InvalidJobException, meaning that the job's data record has been already reaped. This exception is the same as if the job were unknown. (The only case where wait() can be successfully called on a single job more than once is when the previous call to wait() timed out before the job finished.)
When successful, the resource usage information for the job is provided as a Map of usage parameter names and their values in the JobInfo object. The values contain the amount of resources consumed by the job and are implementation defined. If no resource usage information is available for the finished job, the resourceUsage property of the returned JobInfo instance will be
null
.In the 0.5 version of this method, a NoResourceUsageException would be thrown if the target job finished with no resource usage information. In the current implementation, no exception is thrown in that case. Instead, the JobInfo.getResourceUsage() method will return null.
- Parameters:
jobId
- the id of the job for which to waittimeout
- the maximum number of seconds to wait- Returns:
- the resource usage and status information
- Throws:
DrmaaException
- May be one of the following:- ExitTimeoutException -- the operation timed out before completing
- InvalidJobException -- the job identifier does not refer to an active job
- 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:
JobInfo
-
getJobProgramStatus
int getJobProgramStatus(java.lang.String jobId) throws DrmaaException
Get the program status of the job identified by jobId. The possible values returned from this method are:UNDETERMINED
: process status cannot be determinedQUEUED_ACTIVE
: job is queued and activeSYSTEM_ON_HOLD
: job is queued and in system holdUSER_ON_HOLD
: job is queued and in user holdUSER_SYSTEM_ON_HOLD
: job is queued and in user and system holdRUNNING
: job is runningSYSTEM_SUSPENDED
: job is system suspendedUSER_SUSPENDED
: job is user suspendedUSER_SYSTEM_SUSPENDED
: job is user and system suspendedDONE
: job finished normallyFAILED
: job finished, but failed.
The DRMAA implementation must always get the status of jobId from DRM system unless the status has already been determined to be
FAILED
orDONE
and the status has been successfully cached. Terminated jobs return aFAILED
status.- Parameters:
jobId
- the id of the job whose status is to be retrieved- Returns:
- the program status
- Throws:
DrmaaException
- May be one of the following:- InvalidJobException -- the job identifier does not refer to an active job
- 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
-
getContact
java.lang.String getContact()
If called before init(), this method returns a comma delimited String containing the contact Strings available from the default DRMAA implementation, one element per DRM system available. If called after init(), this method returns the contact String for the DRM system to which the session is attached. The returned String is implementation dependent.- Returns:
- current contact information for DRM system or a comma delimited list of possible contact Strings
- Throws:
DrmaaException
- May be one of the following:- 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
-
getVersion
Version getVersion()
Returns a Version instance containing the major and minor version numbers of the DRMAA library. For DRMAA 0.5, major is 0 and minor is 5.- Returns:
- the version number as a Version instance
- 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:
Version
-
getDrmSystem
java.lang.String getDrmSystem()
If called before init(), this method returns a comma delimited list of available DRM systems, one element per DRM system implementation provided. If called after init(), this method returns the selected DRM system. The returned String is implementation dependent.- Returns:
- DRM system implementation information
- Throws:
DrmaaException
- May be one of the following:- 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
-
getDrmaaImplementation
java.lang.String getDrmaaImplementation()
If called before init(), this method returns a comma delimited list of available DRMAA implementations, one element for each DRMAA implementation provided. If called after init(), this method returns the selected DRMAA implementation. The returned String is implementation dependent and may contain the DRM system as a component.- Returns:
- DRMAA implementation information
- Throws:
DrmaaException
- May be one of the following:- 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
-
-