Session

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.ggf.drmaa
Interface Session

All Known Implementing Classes:: GridWaySession

public interface Session

This is the interface to the majority of the functionality offered by the GridWay DRMAA JAVA library.

Field Summary
`static int`	`DONE` DONE Job state.
`static int`	`FAILED` FAILED Job state.
`static int`	`HOLD` HOLD signal.
`static java.lang.String`	`JOB_IDS_SESSION_ALL` Pre-defined string used to refer to ALL the jobs submitted during a DRMAA session.
`static java.lang.String`	`JOB_IDS_SESSION_ANY` Pre-defined string used to refer to ANY job submitted during a DRMAA session.
`static int`	`QUEUED_ACTIVE` QUEUED-ACTIVE Job state.
`static int`	`RELEASE` RELEASE signal.
`static int`	`RESUME` RESUME signal.
`static int`	`RUNNING` RUNNING Job state.
`static int`	`SUSPEND` SUSPEND signal.
`static int`	`SYSTEM_ON_HOLD` SYSTEM-ON-HOLD Job state.
`static int`	`SYSTEM_SUSPENDED` SYSTEM-SUSPENDED Job state.
`static int`	`TERMINATE` TERMINATE signal.
`static long`	`TIMEOUT_NO_WAIT` Pre-defined timeout to be used with `wait(java.lang.String, long)` and `synchronize(java.util.List, long, boolean)` methods.
`static long`	`TIMEOUT_WAIT_FOREVER` Pre-defined timeout to be used with `wait(java.lang.String, long)` and `synchronize(java.util.List, long, boolean)` method calls.
`static int`	`UNDETERMINED` UNDETERMINED Job state.
`static int`	`USER_ON_HOLD` USER-ON-HOLD Job state.
`static int`	`USER_SUSPENDED` USER-SUSPENDED Job state.
`static int`	`USER_SYSTEM_ON_HOLD` USER-SYSTEM-ON-HOLD Job state.
`static int`	`USER_SYSTEM_SUSPENDED` USER-SYSTEM-SUSPENDED Job state.

Method Summary
`void`	`control(java.lang.String jobName, int operation)` This method allows the job specified by jobid to be controlled according to a given action.
`JobTemplate`	`createJobTemplate()` This method allocates a new job template.
`void`	`deleteJobTemplate(JobTemplate jt)` This method deallocates a job template.
`void`	`exit()` Disengage from DRMAA library.
`java.lang.String`	`getContact()` If called before `init(java.lang.String)`, this method returns a string containing a comma-delimited list of default contact hosts for the GridWay daemon.
`java.lang.String`	`getDrmaaImplementation()` This method returns the DRMAA implementation.
`java.lang.String`	`getDrmsInfo()` This method always returns "GridWay" in drm_system, the only DRM system supported by the GridWay DRMAA implementation
`int`	`getJobStatus(java.lang.String jobName)` Obtains the status of a given job.
`Version`	`getVersion()` This method sets major and minor to the major and minor versions of the DRMAA C binding specification implemented by the DRMAA implementation.
`void`	`init(java.lang.String contactString)` Initialize DRMAA API library and create a new DRMAA Session.
`java.util.List`	`runBulkJobs(JobTemplate jobTemplate, int beginIndex, int endIndex, int step)` Submits a set of parametric jobs tha can be run concurrently.
`java.lang.String`	`runJob(JobTemplate jobTemplate)` This method submits a single job with the attributes defined in the job template.
`void`	`synchronize(java.util.List jobList, long timeout, boolean dispose)` This method blocks until all jobs specified by jobList have completed execution or fail.
`JobInfo`	`wait(java.lang.String jobName, long timeout)` This method waits for a given job to either finish executing or fail.

Field Detail

TIMEOUT_WAIT_FOREVER

static final long TIMEOUT_WAIT_FOREVER

Pre-defined timeout to be used with wait(java.lang.String, long) and synchronize(java.util.List, long, boolean) method calls. TIMEOUT_WAIT_FOREVER, can be used to specify an undetermined amount of time.

See Also:: Constant Field Values

TIMEOUT_NO_WAIT

static final long TIMEOUT_NO_WAIT

Pre-defined timeout to be used with wait(java.lang.String, long) and synchronize(java.util.List, long, boolean) methods. TIMEOUT_NO_WAIT, can be used to specify no timeout at all. The current GridWay-DRMAA implementation does NOT SUPPORT TIMEOUT_NO_WAIT.

See Also:: Constant Field Values

UNDETERMINED

static final int UNDETERMINED

UNDETERMINED Job state. An UNDETERMINED state can either be obtained due to a communication error with the GridWay daemon, or because the job has not been initialized yet.

See Also:: Constant Field Values

QUEUED_ACTIVE

static final int QUEUED_ACTIVE

QUEUED-ACTIVE Job state. The job has been successfully submitted and it is pending to be scheduled. This state corresponds to the PENDING state in the GridWay system.

See Also:: Constant Field Values

SYSTEM_ON_HOLD

static final int SYSTEM_ON_HOLD

SYSTEM-ON-HOLD Job state. The GridWay system does NOT DEFINE a SYSTEM-ON-HOLD state (currently), and so it will not be never returned by a #getJobProgramStatus method.

See Also:: Constant Field Values

USER_ON_HOLD

static final int USER_ON_HOLD

USER-ON-HOLD Job state. The job has been held by the user. This state corresponds to the HOLD state in the GridWay system.

See Also:: Constant Field Values

USER_SYSTEM_ON_HOLD

static final int USER_SYSTEM_ON_HOLD

USER-SYSTEM-ON-HOLD Job state. The GridWay system does NOT DEFINE a USER-SYSTEM-ON-HOLD state, and so it will not be never returned by a #getJobProgramStatus method.

See Also:: Constant Field Values

RUNNING

static final int RUNNING

RUNNING Job state. The job has been successfully scheduled and dispatched to a remote host.Please note that once submitted, the job can be in any of the execution states, namely: PROLOG (file stage-in), WRAPPER (execution), EPILOG (file stage-out) or MIGRATING (to another host).

See Also:: Constant Field Values

SYSTEM_SUSPENDED

static final int SYSTEM_SUSPENDED

SYSTEM-SUSPENDED Job state. The GridWay system does NOT DEFINE a SYSTEM-SUSPENDED state, and so it will not be never returned by a #getJobProgramStatus method.

See Also:: Constant Field Values

USER_SUSPENDED

static final int USER_SUSPENDED

USER-SUSPENDED Job state. The job has been successfully stopped. This state corresponds to the STOPPED state in the GridWay system. Once stopped, restart files (if provided by the job) have been tranferred to the client.

See Also:: Constant Field Values

USER_SYSTEM_SUSPENDED

static final int USER_SYSTEM_SUSPENDED

USER-SYSTEM-SUSPENDED Job state. The GridWay system does NOT DEFINE a USER-SYSTEM-SUSPENDED state, and so it will not be never returned by a #getJobProgramStatus method.

See Also:: Constant Field Values

DONE

static final int DONE

DONE Job state. Job has been completely executed and output files are available at the client. This state corresponds to the ZOMBIE state in the GridWay system. wait(java.lang.String, long) and synchronize(java.util.List, long, boolean) calls on the job will return immediately. Also rusage information is available.

See Also:: Constant Field Values

FAILED

static final int FAILED

FAILED Job state. Job execution has failed, and the "on_failure" policy is to hold it on FAILED state. This state corresponds to the FAILED state in the GridWay system.

See Also:: Constant Field Values

SUSPEND

static final int SUSPEND

SUSPEND signal. A job will be stopped, and restart files transferred back to the client. These files if provided by the running job will be used on RESUME to re-start execution.

See Also:: Constant Field Values

RESUME

static final int RESUME

RESUME signal. A previously stopped job will be resumed. If re-start files are provided the job will used them to re-start execution from the last checkpointing context.

See Also:: Constant Field Values

HOLD

static final int HOLD

HOLD signal. A job can be held if it is in the QUEUED_ACTIVE state, and on SUCESS will enter the USER_ON_HOLD state.

See Also:: Constant Field Values

RELEASE

static final int RELEASE

RELEASE signal. Release a previously held job, only jobs in the USER_ON_HOLD state cen be released. On SUCCESS the job will enter the QUEUED_ACTIVE state.

See Also:: Constant Field Values

TERMINATE

static final int TERMINATE

TERMINATE signal. The job will be killed, it execution can be synchronized through the wait(java.lang.String, long) and synchronize(java.util.List, long, boolean) methods. However, job rusage information will not be available and these methods will return DRMAA_ERRNO_NO_RUSAGE.

See Also:: Constant Field Values

JOB_IDS_SESSION_ANY

static final java.lang.String JOB_IDS_SESSION_ANY

Pre-defined string used to refer to ANY job submitted during a DRMAA session. Please note that "disposed" jobs will be removed from the job-list associated to the DRMAA session.

See Also:: Constant Field Values

JOB_IDS_SESSION_ALL

static final java.lang.String JOB_IDS_SESSION_ALL

Pre-defined string used to refer to ALL the jobs submitted during a DRMAA session. Please note that "disposed" jobs will be removed from the job-list associated to the DRMAA session.

See Also:: Constant Field Values

Method Detail

init

void init(java.lang.String contactString)
          throws DrmaaException

Initialize DRMAA API library and create a new DRMAA Session. init() method MUST BE called once per DRMAA program BEFORE any DRMAA related methods are used.

Parameters:: contactString - is an implementation dependent string which may be used to specify which DRM system to use. The current GridWay DRMAA implementation contact MUST be NULL or "localhost".
Throws:: DrmsInitException; InvalidContactStringException; AlreadyActiveSessionException; DefaultContactStringException; NoDefaultContactStringSelectedException; java.lang.OutOfemoryError; DrmCommunicationException; AuthorizationException; java.lang.IllegalArgumentException; InternalException; DrmaaException

exit

void exit()
          throws DrmaaException

Disengage from DRMAA library. This routine ends this DRMAA Session, but does not effect any jobs (i.e. queued and running jobs remain queued and running).

Throws:: DrmsExitException; NoActiveSessionException; java.lang.OutOfemoryError; DrmCommunicationException; AuthorizationException; java.lang.IllegalArgumentException; InternalException; DrmaaException

createJobTemplate

JobTemplate createJobTemplate()
                              throws DrmaaException

This method allocates a new job template. This template is used to describe the job to be submitted. This is accomplished by setting the desired scalar and vector attributes to their appropriate values.

Returns:: A reference to a JobTemplate Object. The DRMAA API runtime library will allocate memory for the new template. This memory MUST be freed with a subsequent call to deleteJobTemplate(org.ggf.drmaa.JobTemplate) method.
Throws:: NoActiveSessionException; DrmCommunicationException; java.lang.OutOfemoryError; AuthorizationException; java.lang.IllegalArgumentException; InternalException; DrmaaException

deleteJobTemplate

void deleteJobTemplate(JobTemplate jt)
                       throws DrmaaException

This method deallocates a job template.

Parameters:: jt - Rerence to a JobTemplate object. The JobTemplate object jt MUST BE previously allocated with a createJobTemplate() method.
Throws:: NoActiveSessionException; InvalidJobTemplateException; DrmCommunicationException; java.lang.OutOfemoryError; AuthorizationException; java.lang.IllegalArgumentException; InternalException; DrmaaException

runJob

java.lang.String runJob(JobTemplate jobTemplate)
                        throws DrmaaException

This method submits a single job with the attributes defined in the job template.

Parameters:: jobTemplate - Reference to a JobTemplate object. The JobTemplate jobTemplate MUST BE previously allocated with a createJobTemplate() method call. Job template values MUST be previously defined with set methods.
Returns:: An unique String identification as provided by the GridWay system.
Throws:: TryLaterException; DeniedByDrmException; InvalidJobTemplateException; NoActiveSessionException; DrmCommunicationException; java.lang.OutOfemoryError; DrmCommunicationException; AuthorizationException; java.lang.IllegalArgumentException; InternalException; DrmaaException

runBulkJobs

java.util.List runBulkJobs(JobTemplate jobTemplate,
                           int beginIndex,
                           int endIndex,
                           int step)
                           throws DrmaaException

Submits a set of parametric jobs tha can be run concurrently. For each parametric job the same template is used, and so must be properly set. Each job is identical except of it's index:

The first parametric job has an index equal to beginIndex.

The next job has an index equal to beginIndex + step, and so on.

The last job has an index equal to beginIndex + n *step, where n is equal to (endIndex-beginIndex)/step. These values can be used as arguments for each task and to generate input/output filenames.

GridWay will internally rescale the start-end range to 0-total_tasks The coherence of start, end and incr values are not check by runJob(). Their coherence SHOULD be guarantee by the calling program.

Parameters:: jobTemplate - Reference to a JobTemplate structure. The JobTemplate jobTemplate MUST BE previously allocated with a createJobTemplate() method call. Job template values MUST be previously defined with sets methods calls.; beginIndex - index associated to the first job. The smallest start value is 0; endIndex - index associated to the last job.; step - increment used to obtain the total number of job. GridWay will internally used incr=1
Throws:: TryLaterException; DeniedByDrmException; InvalidJobTemplateException; NoActiveSessionException; DrmCommunicationException; AuthorizationException; java.lang.OutOfemoryError; java.lang.IllegalArgumentException; InternalException; DrmaaException

control

void control(java.lang.String jobName,
             int operation)
             throws DrmaaException

This method allows the job specified by jobid to be controlled according to a given action. Possible action to be performed over a given job are:

SUSPEND A job will be stopped, and restart files tranferred back to the client. These files if provided by the running job will be used on RESUME to re-start execution.
RESUME A previously stopped job will be resumed. If re-start files are provided the job will used them to re-start execution, from the last checkpointing context.
TERMINATE The job will be killed, it execution can be synchronized through the drmaa_wait and drmaa_synchronize method calls. However, job rusage information will not be available.
HOLD The job will be held, it execution will not start until it is released. Only jobs in the QUEUED_ACTIVE state can be held.
RELEASE The job will be released and scheduled, only jobs in the USER_ON_HOLD state can be released.

Parameters:: jobName - String with the job unique identification as provided by the GridWay system. The jobid SHOULD be obtained from a runJob(org.ggf.drmaa.JobTemplate) or runBulkJobs(org.ggf.drmaa.JobTemplate, int, int, int) methods calls.; operation - The action to be performed over the job whose value may be one of the following: SUSPEND, RESUME, TERMINATE, HOLD or RELEASE.
Throws:: NoActiveSessionException; ResumeInconsistentStateException; SuspendInconsistentStateException; HoldInconsistentStateException; ReleaseInconsistentStateException; InvalidJobException; java.lang.OutOfemoryError; DrmCommunicationException; AuthorizationException; java.lang.IllegalArgumentException; InternalException; DrmaaException

synchronize

void synchronize(java.util.List jobList,
                 long timeout,
                 boolean dispose)
                 throws DrmaaException,
                        java.lang.RuntimeException

This method blocks until all jobs specified by jobList have completed execution or fail.

Parameters:: jobList - A NULL terminated list of jobid strings. The jobids SHOULD be obtained from a runJob(org.ggf.drmaa.JobTemplate) or runBulkJobs(org.ggf.drmaa.JobTemplate, int, int, int) methods calls. The pre-defined value JOB_IDS_SESSION_ALL can be used to synchronize all jobs submitted during the DRMAA session. Please note that "disposed" jobs will be removed from the job-list associated to the DRMAA session.; timeout - The current GridWay DRMAA implementation only supports TIMEOUT_WAIT_FOREVER, it specifies an undetermined amount of time.; dispose - If dispose is equal to 1 the jobid will be killed, and its resources freed in the GridWay system. Therefore subsequent calls on this job will fail. However, if dispose is equal to 0 the job remains in DONE state in the GridWay system and its rusage statistics can be obtained with wait(java.lang.String, long) method call. Also these jobid will not make subsequent calls synchronize method call to fail.
Throws:: NoActiveSessionException; ExitTimeoutException; InvalidJobException; java.lang.OutOfemoryError; DrmCommunicationException; AuthorizationException; java.lang.IllegalArgumentException; InternalException; DrmaaException; java.lang.RuntimeException

wait

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

This method waits for a given job to either finish executing or fail. If successfully waited, the jobs rusage information has been reaped, and further calls to wait with this job_id will throw InvalidJobException.

Parameters:: jobName - String with the job unique identification as provided by the GridWay system. The jobid SHOULD be obtained from a runJob(org.ggf.drmaa.JobTemplate) or runBulkJobs(org.ggf.drmaa.JobTemplate, int, int, int) methods calls. JOB_IDS_SESSION_ANY can be used to wait on any job submitted during the DRMAA session. Please note that "disposed" jobs will be removed from the job-list associated to the DRMAA session.; timeout - The current GridWay DRMAA implementation only supports TIMEOUT_WAIT_FOREVER. TIMEOUT_WAIT_FOREVER, specifies an undetermined amount of time.
Returns:: JobInfo object that stores the exit status and the resource usage of the job_out.
Throws:: NoActiveSessionException; ExitTimeoutException; InvalidJobException; java.lang.OutOfemoryError; DrmCommunicationException; AuthorizationException; java.lang.IllegalArgumentException; InternalException; DrmaaException

getJobStatus

int getJobStatus(java.lang.String jobName)
                 throws DrmaaException

Obtains the status of a given job.

Parameters:

jobName - String with the job unique identification as provided by the GridWay system. The jobid SHOULD be obtained from a runJob(org.ggf.drmaa.JobTemplate) or runBulkJobs(org.ggf.drmaa.JobTemplate, int, int, int) method calls.

Returns:

The actual state of the job can be one of the following:

UNDETERMINED: An UNDETERMINED state can either obtained due to a communication error with the GridWay daemon, or because the job has not been initialized yet.
QUEUED_ACTIVE: The job has been successfully submitted and it is pending to be scheduled.
RUNNING: The job has been successfully submitted to a remote host. Please note that once submitted, the job can be in any of the execution stages, namely: prolog (file stage-in), wrapper (execution), epilog (file stage-out) or migrating (to another host).
USER_ON_HOLD: The job has been held by the user
DONE: Job has been completely executed and output files are available at the client. drmaa_wait() and drmaa_synchronize() calls on the job will return immediately. Also rusage information is available.
DONE: Job has been completely executed and output files are available at the client. drmaa_wait() and drmaa_synchronize() calls on the job will return immediately. Also rusage information is available.
FAILED: Job execution has failed, and the "on_failure" policy is to hold it on FAILED state.

The GridWay DRMAA implementation does not define the following actions: SYSTEM_ON_HOLD, USER_SYSTEM_ON_HOLD, SYSTEM_SUSPENDED and USER_SYSTEM_SUSPENDED.

Throws:

NoActiveSessionException

InvalidJobException

java.lang.OutOfemoryError

DrmCommunicationException

AuthorizationException

java.lang.IllegalArgumentException

InternalException

DrmaaException

getContact

java.lang.String getContact()

If called before init(java.lang.String), this method returns a string containing a comma-delimited list of default contact hosts for the GridWay daemon. If called after init(java.lang.String), this funtion returns the contact string (hostname) where GridWay is running. The client library has been initialized by contacting this host.

Returns:: The contact string
Throws:: java.lang.OutOfemoryError; DrmCommunicationException; AuthorizationException; java.lang.IllegalArgumentException; InternalException

getVersion

Version getVersion()

This method sets major and minor to the major and minor versions of the DRMAA C binding specification implemented by the DRMAA implementation. Current implementation is 1.0

Returns:: Returns the version number as a Version object
Throws:: java.lang.OutOfemoryError; DrmCommunicationException; AuthorizationException; java.lang.IllegalArgumentException; InternalException

getDrmsInfo

java.lang.String getDrmsInfo()

This method always returns "GridWay" in drm_system, the only DRM system supported by the GridWay DRMAA implementation

Returns:: Always "GridWay"

getDrmaaImplementation

java.lang.String getDrmaaImplementation()

This method returns the DRMAA implementation. It always returns "DRMAA for GridWay M.m" where M is the GridWay major version number and m is the minor version number

Returns:: Always "DRMAA for GridWay M.m"
Throws:: java.lang.OutOfemoryError; DrmCommunicationException; AuthorizationException; java.lang.IllegalArgumentException; InternalException