org.ggf.drmaa
Interface Session

All Known Implementing Classes:

SessionImpl

public interface Session

This interface represents a the operations available for interacting with the DRM. In DRMAA, (almost) all DRM interaction occur within the context of a session. The spec 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 (null);
      JobTemplate jt = session.createJobTemplate ();
      jt.setRemoteCommand ("sleeper.sh");
      jt.setArgs (new String[] {"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

Author:

dan.templeton@sun.com

See Also:

Runtime.addShutdownHook(java.lang.Thread), SessionFactory, Grid Engine DRMAA Java[TM] Language Binding HowTo

Field Summary

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

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 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 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 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 object 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 set of parametric jobs, dependent on the implied loop index, 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

public static final int SUSPEND

Suspend the job

See Also:

Constant Field Values

RESUME

public static final int RESUME

Resume the job

See Also:

Constant Field Values

HOLD

public static final int HOLD

Put the job on hold

See Also:

Constant Field Values

RELEASE

public static final int RELEASE

Release the hold on the job

See Also:

Constant Field Values

TERMINATE

public static final int TERMINATE

Kill the job

See Also:

Constant Field Values

JOB_IDS_SESSION_ALL

public static final java.lang.String JOB_IDS_SESSION_ALL

All jobs submitted during this DRMAA session

See Also:

Constant Field Values

JOB_IDS_SESSION_ANY

public static final java.lang.String JOB_IDS_SESSION_ANY

Any job from the session

See Also:

Constant Field Values

TIMEOUT_WAIT_FOREVER

public static final long TIMEOUT_WAIT_FOREVER

Wait indefinitely for a result

See Also:

Constant Field Values

TIMEOUT_NO_WAIT

public static final long TIMEOUT_NO_WAIT

Return immediately if no result is available

See Also:

Constant Field Values

UNDETERMINED

public static final int UNDETERMINED

Job status cannot be determined

See Also:

Constant Field Values

QUEUED_ACTIVE

public static final int QUEUED_ACTIVE

Job is queued and active

See Also:

Constant Field Values

SYSTEM_ON_HOLD

public static final int SYSTEM_ON_HOLD

Job is queued and in system hold

See Also:

Constant Field Values

USER_ON_HOLD

public static final int USER_ON_HOLD

Job is queued and in user hold

See Also:

Constant Field Values

USER_SYSTEM_ON_HOLD

public static final int USER_SYSTEM_ON_HOLD

Job is queued and in user and system hold

See Also:

Constant Field Values

RUNNING

public static final int RUNNING

Job is running

See Also:

Constant Field Values

SYSTEM_SUSPENDED

public static final int SYSTEM_SUSPENDED

Job is system suspended

See Also:

Constant Field Values

USER_SUSPENDED

public static final int USER_SUSPENDED

Job is user suspended

See Also:

Constant Field Values

USER_SYSTEM_SUSPENDED

public static final int USER_SYSTEM_SUSPENDED

Job is user suspended

See Also:

Constant Field Values

DONE

public static final int DONE

Job has finished normally

See Also:

Constant Field Values

FAILED

public static final int FAILED

Job finished, but terminated abnormally

See Also:

Constant Field Values

Method Detail

init

public 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 getVersion(), getDRMSystem(), getDRMAAImplementation(), or getContact().

If contact is null, the default DRM system is used, provided there is only one DRMAA implementation in the module. If there is more than one DRMAA implementation in the module, 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. If null, will select the default DRM if there is only one DRMAA implementation available.

Throws:

DrmaaException - May be be one of the following:

• InvalidContactStringException
• AlreadyActiveSessionException
• DefaultContactStringException
• NoDefaultContactStringSelectedException

exit

public void exit()
          throws DrmaaException

Disengage from 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 (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
• NoActiveSessionException

createJobTemplate

public JobTemplate createJobTemplate()
                              throws DrmaaException

Get a new job template. The job template is used to set the environment for jobs to be submitted. Once the 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 object

Throws:

DrmaaException - May be one of the following:

• DrmCommunicationException

See Also:

JobTemplate

deleteJobTemplate

public void deleteJobTemplate(JobTemplate jt)
                       throws DrmaaException

Deallocate a job template. This routine has no effect on running jobs.

Parameters:

jt - the JobTemplate to delete

Throws:

DrmaaException - May be one of the following:

• DrmCommunicationException
• InvalidJobTemplateException

runJob

public 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
• DeniedByDrmException
• DrmCommunicationException
• AuthorizationException
• InvalidJobTemplateException

runBulkJobs

public java.util.List runBulkJobs(JobTemplate jt,
                                  int start,
                                  int end,
                                  int incr)
                           throws DrmaaException

Submit a set of parametric jobs, dependent on the implied loop index, 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 JobTemplate class defines a PARAMETRIC_INDEX placeholder for use in specifying paths. This placeholder is used to represent the individual identifiers of the tasks submitted through this method.

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
• DeniedByDrmException
• DrmCommunicationException
• AuthorizationException
• InvalidJobTemplateException

control

public 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 in multithreaded applications, the DRMAA implementation user should explicitly synchronize this call with any other job submission calls 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, and
• TERMINATE: kill the job.

This method returns once the action has been acknowledged by the DRM system, but 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 session in other DRMAA implementations or jobs submitted via native utilities.

Parameters:

jobId - The id of the job to control

action - the control action to be taken

Throws:

DrmaaException - May be one of the following:

• DrmCommunicationException
• AuthorizationException
• ResumeInconsistentStateException
• SuspendInconsistentStateException
• HoldInconsistentStateException
• ReleaseInconsistentStateException
• InvalidJobException

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 calls 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 after 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 job's internal data record, which includes a record of the job's consumption of system resources during its execution and other statistical information. If set to true, the DRM will dispose of the job's data record at the end of the synchroniize() call. If set to false, the data record will be left for future access via the wait() method.

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:

• DrmCommunicationException
• AuthorizationException
• ExitTimeoutException
• InvalidJobException

See Also:

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() 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 was 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. The values contain the amount of resources consumed by the job and are implementation defined.

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:

• DrmCommunicationException
• AuthorizationException
• NoResourceUsageDataException
• ExitTimeoutException
• InvalidJobException

getJobProgramStatus

public 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 determined
• QUEUED_ACTIVE: job is queued and active
• SYSTEM_ON_HOLD: job is queued and in system hold
• USER_ON_HOLD: job is queued and in user hold
• USER_SYSTEM_ON_HOLD: job is queued and in user and system hold
• RUNNING: job is running
• SYSTEM_SUSPENDED: job is system suspended
• USER_SUSPENDED: job is user suspended
• DONE: job finished normally
• FAILED: job finished, but failed.

The DRMAA implementation should 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.

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:

• DrmCommunicationException
• AuthorizationException
• InvalidJobException

getContact

public 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

getVersion

public Version getVersion()

Returns a Version object 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 object

See Also:

Version

getDrmSystem

public java.lang.String getDrmSystem()

If called before init(), this method returns a comma delimited list of 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

getDrmaaImplementation

public java.lang.String getDrmaaImplementation()

If called before init(), this method returns a comma delimited list of 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