com.sun.grid.drmaa
Class SessionImpl

java.lang.Object
  extended bycom.sun.grid.drmaa.SessionImpl
All Implemented Interfaces:
Session

public class SessionImpl
extends java.lang.Object
implements Session

The SessionImpl class provides a DRMAA interface to Grid Engine. This interface is built on top of the DRMAA C binding using JNI. In order to keep the native code as localized as possible, this class also provides native DRMAA services to other classes, such as the JobTemplateImpl.

This class relies on the version 1.0 drmaa shared library.

Since:
0.5
Version:
1.0
Author:
dan.templeton@sun.com
See Also:
Session, JobTemplateImpl, Grid Engine Man Pages

Field Summary
 
Fields inherited from interface org.ggf.drmaa.Session
DONE, FAILED, HOLD, JOB_IDS_SESSION_ALL, JOB_IDS_SESSION_ANY, QUEUED_ACTIVE, RELEASE, RESUME, RUNNING, SUSPEND, SYSTEM_ON_HOLD, SYSTEM_SUSPENDED, TERMINATE, TIMEOUT_NO_WAIT, TIMEOUT_WAIT_FOREVER, UNDETERMINED, USER_ON_HOLD, USER_SUSPENDED, USER_SYSTEM_ON_HOLD, USER_SYSTEM_SUSPENDED
 
Method Summary
 void control(java.lang.String jobId, int action)
          Controls a jobs.
 JobTemplate createJobTemplate()
          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.
 void deleteJobTemplate(JobTemplate jt)
          Deallocate a job template. This routine has no effect on jobs which have already been submitted.
 void exit()
          The exit() method closes the DRMAA session for all threads and must be called before process termination.
 java.lang.String getContact()
          getContact() returns an opaque string containing contact information related to the current DRMAA session to be used with the init() method.
 java.lang.String getDrmaaImplementation()
          The getDrmaaImplementation() method returns a string containing the DRMAA Java language binding implementation version information.
 java.lang.String getDrmSystem()
          The getDRMSystem() method returns a string containing the DRM product and version information.
 int getJobProgramStatus(java.lang.String jobId)
          Get the job programm status.
 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.
 void init(java.lang.String contact)
          The init() method initializes the Grid Engine DRMAA API library for all threads of the process and creates a new DRMAA Session.
 java.util.List runBulkJobs(JobTemplate jt, int start, int end, int incr)
          The runBulkJobs() method submits a Grid Engine array job very much as if the qsub option `-t start-end:incr' had been used with the corresponding attributes defined in the DRMAA JobTemplate, jt.
 java.lang.String runJob(JobTemplate jt)
          The runJob() method submits a Grid Engine job with attributes defined in the DRMAA JobTemplate jt.
 void synchronize(java.util.List jobIds, long timeout, boolean dispose)
          Wait until all jobs specified by jobIds have finished execution. If jobIds contains JOB_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 value TIMEOUT_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 to false, the data records will be left for future access via the wait() method.

 JobInfo wait(java.lang.String jobId, long timeout)
          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.

 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

control

public void control(java.lang.String jobId,
                    int action)
             throws DrmaaException

Controls a jobs.

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:

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.

The DRMAA suspend/resume operations are equivalent to the use of the `-s ' and `-us ' options with qmod. (See the qmod(1) man page.)

The DRMAA hold/release operations are equivalent to the use of qhold and qrls. (See the qhold(1) and qrls(1) man pages.)

The DRMAA terminate operation is equivalent to the use of qdel. (See the qdel(1) man page.)

Only user hold and user suspend can be controled via control(). For affecting system hold and system suspend states the appropriate DRM interfaces must be used.

Specified by:
control in interface Session
Parameters:
jobId - The id of the job to control
action - 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
See Also:
qmod(1), qhold(1), qrls(1), qdel(1)

exit

public void exit()
          throws DrmaaException
The exit() method closes the DRMAA session for all threads and must be called before process termination. The exit() method may be called only once by a single thread in the process and may only be called after the init() function has completed. Any call to exit() before init() returns or after exit() has already been called will result in a NoActiveSessionException.

The exit() method does neccessary clean up of the DRMAA session state, including unregistering from the qmaster. If the exit() method is not called, the qmaster will store events for the DRMAA client until the connection times out, causing extra work for the qmaster and comsuming system resources.

Submitted jobs are not affected by the exit() method.

Specified by:
exit in interface Session
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

getContact

public java.lang.String getContact()
getContact() returns an opaque string containing contact information related to the current DRMAA session to be used with the init() method. The contact string takes the form [name=value[;name=value]*], where name and value are both strings, and the supported values of name are:

Before the init() method has been called, this method will always return an empty string. After the init() method has been called, this method will return the set of name=value pairs which represent the currently active session. The value returned for session can be used with the init() method to reconnect to the current session after exit() has been called.

Specified by:
getContact in interface Session
Returns:
current contact information for DRM system or a comma delimited list of possible contact Strings
See Also:
init(String)

getDrmSystem

public java.lang.String getDrmSystem()
The getDRMSystem() method returns a string containing the DRM product and version information. The getDRMSystem() function returns the same value before and after init() is called.

Specified by:
getDrmSystem in interface Session
Returns:
DRM system implementation information
See Also:
init(String)

getDrmaaImplementation

public java.lang.String getDrmaaImplementation()
The getDrmaaImplementation() method returns a string containing the DRMAA Java language binding implementation version information. The getDrmaaImplementation() method returns the same value before and after init() is called.

Specified by:
getDrmaaImplementation in interface Session
Returns:
DRMAA implementation information
See Also:
init(String)

getJobProgramStatus

public int getJobProgramStatus(java.lang.String jobId)
                        throws DrmaaException

Get the job programm status.

Get the program status of the job identified by jobId. The possible values returned from this method are:

The DRMAA implementation must always get the status of jobId from DRM system unless the status has already been determined to be FAILED or DONE and the status has been successfully cached. Terminated jobs return a FAILED status.

The control method can be used to control job submitted outside of the scope of the DRMAA session as long as the job identifier for the job is known.

Specified by:
getJobProgramStatus in interface Session
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

createJobTemplate

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

Specified by:
createJobTemplate in interface Session
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

public void deleteJobTemplate(JobTemplate jt)
                       throws DrmaaException
Deallocate a job template. This routine has no effect on jobs which have already been submitted.

Specified by:
deleteJobTemplate in interface Session
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

getVersion

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

Specified by:
getVersion in interface Session
Returns:
the version number as a Version instance
See Also:
Version

init

public void init(java.lang.String contact)
          throws DrmaaException
The init() method initializes the Grid Engine DRMAA API library for all threads of the process and creates a new DRMAA Session. This routine must be called once before any other DRMAA call, except for getDrmSystem(), getContact(), and getDrmaaImplementation().

contact is an implementation dependent string which may be used to specify which Grid Engine cell to use. The contact string is composed of a series of name=value pairs separated by semicolons. The supported name=value pairs are:

If contact is null or empty, the default Grid Engine cell will be used.

Except for the above listed methods, no DRMAA methods may be called before the init() function completes. Any DRMAA method which is called before the init() method completes will throw a NoActiveSessionException. Any additional call to init() by any thread will throw a SessionAlreadyActiveException.

Once init() has been called, it is the responsibility of the developer to ensure that the exit() will be called before the program terminates.

Specified by:
init in interface Session
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
See Also:
getContact(), exit()

runBulkJobs

public java.util.List runBulkJobs(JobTemplate jt,
                                  int start,
                                  int end,
                                  int incr)
                           throws DrmaaException
The runBulkJobs() method submits a Grid Engine array job very much as if the qsub option `-t start-end:incr' had been used with the corresponding attributes defined in the DRMAA JobTemplate, jt. The same constraints regarding qsub -t value ranges also apply to the parameters start, end, and incr. See the qsub(1) man page for more information.

On success a String array containing job identifiers for each array job task is returned.

Specified by:
runBulkJobs in interface Session
Parameters:
start - the starting value for the loop index
end - the terminating value for the loop index
incr - the value by which to increment the loop index each iteration
jt - 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
See Also:
qsub(1)

runJob

public java.lang.String runJob(JobTemplate jt)
                        throws DrmaaException
The runJob() method submits a Grid Engine job with attributes defined in the DRMAA JobTemplate jt. On success, the job identifier is returned.

Specified by:
runJob in interface Session
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

synchronize

public void synchronize(java.util.List jobIds,
                        long timeout,
                        boolean dispose)
                 throws DrmaaException
Wait until all jobs specified by jobIds have finished execution. If jobIds contains JOB_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 value TIMEOUT_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 to false, the data records will be left for future access via the wait() method.

Specified by:
synchronize in interface Session
Parameters:
jobIds - the ids of the jobs to synchronize
timeout - the maximum number of seconds to wait
dispose - 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:
Session.wait(java.lang.String, long)

wait

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

Specified by:
wait in interface Session
Parameters:
jobId - the id of the job for which to wait
timeout - 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


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