## com.sun.grid.drmaa
Class SessionImpl

    java.lang.Object
      com.sun.grid.drmaa.SessionImpl

All Implemented Interfaces:
  Session

public class SessionImpl
extends java.lang.Object
implements Session

The SessionImpl 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 drmaa shared library.

Since:
  0.5
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)` Hold, release, suspend, resume, or kill the job identified by jobId.
`JobTemplate` `createJobTemplate()` Get a new job template.
`void` `deleteJobTemplate(JobTemplate jt)` The deleteJobTemplate() method releases all resources associated with the DRMAA JobTemplate.
`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 program status of the job identified by jobId.
`Version` `getVersion()` The getVersion() method returns a Version object containing the major and minor version numbers of the DRMAA library.
`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)` The synchronize() method blocks the calling thread until all jobs specified in jobIds have failed or finished execution.
`JobInfo` `wait(java.lang.String jobId, long timeout)` The wait() function blocks the calling thread until a job fails or finishes execution.

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

Method Detail

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

  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 routine returns once the action has been acknowledged by the DRM system, but does not necessarily wait until the action has been completed.

  The DRMAA suspend/resume operations are equivalent to the use of `-s <jobid>' and `-us <jobid>' 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:
    - DrmCommunicationException
    - AuthorizationException
    - ResumeInconsistentStateException
    - SuspendInconsistentStateException
    - HoldInconsistentStateException
    - ReleaseInconsistentStateException
    - InvalidJobException

### 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
    - NoActiveSessionException

### 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. In the current implemention, however, the getContact() function returns an empty string, and the contact parameter has no effect on the init() method.

  The getContact() method returns the same value before and after init() is called.

  Specified by:
    `getContact` in interface `Session`
  Returns:
    current contact information for DRM system or a comma delimited list of possible contact Strings

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

### getJobProgramStatus

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

  Get the program status of the job identified by jobId. The possible return values and their meanings 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
  - `USER_SYSTEM_SUSPENDED`: job is user and system suspended
  - `DONE`: job finished normally
  - `FAILED`: job finished, but failed.

  DRMAA always gets the status of jobId from DRM system. No caching of job state is done.

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

  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:
    - DrmCommunicationException
    - AuthorizationException
    - InvalidJobException

### createJobTemplate

    public JobTemplate createJobTemplate()
                                  throws DrmaaException

  Get a new job template. The job template is used to set the environment for submitted jobs.

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

  The deleteJobTemplate() method releases all resources associated with the DRMAA JobTemplate. Jobs that were submitted using the JobTemplate are not affected.

  Specified by:
    `deleteJobTemplate` in interface `Session`
  Parameters:
    `jt` - the job template to delete
  Throws:
    `DrmaaException` - May be one of the following:
    - DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE

### getVersion

    public Version getVersion()

  The getVersion() method returns a Version object containing the major and minor version numbers of the DRMAA library. For a DRMAA Java language binding specification 0.5 compliant implementation (e.g. this binding) `0' and `5' will be the major and minor numbers, respectively.

  Specified by:
    `getVersion` in interface `Session`
  Returns:
    the version number as a Version object
  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. If contact is null or empty, the default Grid Engine cell will be used. In the current implementation setting contact has no effect.

  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. If null, will select the default DRM if there is only one DRM implementation available. Ignored in the current implementation.
  Throws:
    `DrmaaException` - Maybe be one of the following:
    - InvalidContactStringException
    - AlreadyActiveSessionException
    - DefaultContactStringException
    - NoDefaultContactStringSelectedException

### 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
    - DeniedByDrmException
    - DrmCommunicationException
    - AuthorizationException

### 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 by the underlying DRM system
  Throws:
    `DrmaaException` - May be one of the following:
    - TryLaterException
    - DeniedByDrmException
    - DrmCommunicationException
    - AuthorizationException

### synchronize

    public void synchronize(java.util.List jobIds,
                            long timeout,
                            boolean dispose)
                     throws DrmaaException

  The synchronize() method blocks the calling thread until all jobs specified in jobIds have failed or finished execution. If jobIds contains `JOB_IDS_SESSION_ALL`, then this method waits for all jobs submitted during this DRMAA session.

  To prevent blocking indefinitely in this call, the caller may use timeout, specifying how many seconds to wait for this call to complete before timing out. The special value `TIMEOUT_WAIT_FOREVER` can be used to wait indefinitely for a result. The special value `DRMAA_TIMEOUT_NO_WAIT` can be used to return immediately. If the call exits before timeout, all the specified jobs have completed or the calling thread received an interrupt. In both cases, the method will throw an ExitTimeoutException.

  The dispose parameter specifies how to treat reaping information. If false is passed to this paramter, job finish information will still be available if wait() is called. If true is passed, wait() will be unable to access this job's finish information.

  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:
    - DrmCommunicationException
    - AuthorizationException
    - ExitTimeoutException
    - InvalidJobException
  See Also:
    `Session.wait(java.lang.String, long)`

### wait

    public JobInfo wait(java.lang.String jobId,
                        long timeout)
                 throws DrmaaException

  The wait() function blocks the calling thread until a job fails or finishes execution. This routine is modeled on the UNIX wait4(3) routine. If the special string `JOB_IDS_SESSION_ANY` is passed as jobId, this routine will wait for any job from the session. Otherwise the jobId must be the job identifier of a job or array job task that was submitted during the session.

  To prevent blocking indefinitely in this call, the caller may use timeout, specifying how many seconds to wait for this call to complete before timing out. The special value `TIMEOUT_WAIT_FOREVER` can be uesd to wait indefinitely for a result. The special value `TIMEOUT_NO_WAIT` can be used to return immediately. If the call exits before timeout, all the specified jobs have completed or the calling thread received an interrupt. In both cases, the method will throw an ExitTimeoutException.

  The routine reaps jobs on a successful call, so any subsequent calls to wait() will fail, throwing an InvalidJobException, meaning that the job has already been reaped. This exception is the same as if the job were unknown. Returning due to an elapsed timeout or an interrupt does not cause the job information to be reaped. This means that, in that case it is possible to issue wait() multiple times for the same jobId.

  The wait() method will return a JobInfo object. The JobInfo object contains information about the job execution. In particular, the JobInfo object will contain the job id of the failed or finished job. This is useful when `JOB_IDS_SESSION_ANY` is passed as the jobId.

  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:
    - DrmCommunicationException
    - AuthorizationException
    - NoResourceUsageDataException
    - ExitTimeoutException
    - InvalidJobException

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