org.ggf.drmaa
Class GridWaySession

java.lang.Object
  org.ggf.drmaa.GridWaySession

All Implemented Interfaces:

Session

public class GridWaySession
extends java.lang.Object
implements Session

This is the class to implement the Session interface.

Field Summary

static java.lang.String	GW_ARCH Pre-defined string to refer to the remote host architecture as returned by the resource selector module.
static java.lang.String	GW_JOB_ID Pre-defined string to refer to the job unique identification as provided by the GridWay system.
static java.lang.String	GW_TASK_ID Pre-defined string to refer to the task unique identification as provided by the GridWay system.
static java.lang.String	GW_TOTAL_TASKS Pre-defined string to refer to the number of total tasks in a bulk job.
static java.lang.String	GW_TYPE_MPI Pre-defined string to define MPI (Message Passing Interface) jobs.
static java.lang.String	GW_TYPE_SINGLE Pre-defined string to define single (one process) jobs.

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

Constructor Summary

GridWaySession()

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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GW_TOTAL_TASKS

public static final java.lang.String GW_TOTAL_TASKS

Pre-defined string to refer to the number of total tasks in a bulk job. GW_TOTAL_TASKS will be available during job execution and can be used as an ARGUMENT for the REMOTE COMMAND. This attribute name should be used ONLY in conjuntion with a drmaa_run_bulk_jobs() function call.

See Also:

Constant Field Values

GW_JOB_ID

public static final java.lang.String GW_JOB_ID

Pre-defined string to refer to the job unique identification as provided by the GridWay system. GW_JOB_ID will be available during job execution and can be used as an ARGUMENT for the REMOTE COMMAND. It is also usefull to generate output filenames, since it is available in the main DRMAA program as returned by runBulkJobs(org.ggf.drmaa.JobTemplate, int, int, int) and runJob(org.ggf.drmaa.JobTemplate) method calls.

See Also:

Constant Field Values

GW_TASK_ID

public static final java.lang.String GW_TASK_ID

Pre-defined string to refer to the task unique identification as provided by the GridWay system. GW_TASK_ID will be available during job execution and can be used as an ARGUMENT for the REMOTE COMMAND. It is also usefull to generate output filenames of bluk jobs. GW_TASK_ID ALWAYS ranges from 0 to GW_TOTAL_TASKS -1. Please note that this attribute name should be used ONLY in conjuntion with a runBulkJobs(org.ggf.drmaa.JobTemplate, int, int, int) method call.

See Also:

Constant Field Values

GW_ARCH

public static final java.lang.String GW_ARCH

Pre-defined string to refer to the remote host architecture as returned by the resource selector module. DRMAA_GW_ARCH will be available during job execution and can be used to generate architecture-dependent REMOTE COMMAND executables.

See Also:

Constant Field Values

GW_TYPE_SINGLE

public static final java.lang.String GW_TYPE_SINGLE

Pre-defined string to define single (one process) jobs.

See Also:

Constant Field Values

GW_TYPE_MPI

public static final java.lang.String GW_TYPE_MPI

Pre-defined string to define MPI (Message Passing Interface) jobs.

See Also:

Constant Field Values

Constructor Detail

GridWaySession

public GridWaySession()

Method Detail

init

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

Description copied from interface: Session

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.

Specified by:

init in interface Session

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

DrmCommunicationException

AuthorizationException

DrmaaException

exit

public void exit()
          throws DrmaaException

Description copied from interface: Session

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

Specified by:

exit in interface Session

Throws:

DrmsExitException

NoActiveSessionException

DrmCommunicationException

AuthorizationException

DrmaaException

createJobTemplate

public JobTemplate createJobTemplate()
                              throws DrmaaException

Description copied from interface: Session

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.

Specified by:

createJobTemplate in interface Session

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 Session.deleteJobTemplate(org.ggf.drmaa.JobTemplate) method.

Throws:

NoActiveSessionException

DrmCommunicationException

AuthorizationException

DrmaaException

deleteJobTemplate

public void deleteJobTemplate(JobTemplate jt)
                       throws DrmaaException

Description copied from interface: Session

This method deallocates a job template.

Specified by:

deleteJobTemplate in interface Session

Parameters:

jt - Rerence to a JobTemplate object. The JobTemplate object jt MUST BE previously allocated with a Session.createJobTemplate() method.

Throws:

NoActiveSessionException

InvalidJobTemplateException

DrmCommunicationException

AuthorizationException

DrmaaException

runJob

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

Description copied from interface: Session

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

Specified by:

runJob in interface Session

Parameters:

jobTemplate - Reference to a JobTemplate object. The JobTemplate jobTemplate MUST BE previously allocated with a Session.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

AuthorizationException

DrmaaException

runBulkJobs

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

Description copied from interface: Session

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.

Specified by:

runBulkJobs in interface Session

Parameters:

jobTemplate - Reference to a JobTemplate structure. The JobTemplate jobTemplate MUST BE previously allocated with a Session.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

DrmaaException

control

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

Description copied from interface: Session

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:

• Session.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.
• Session.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.
• Session.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.
• Session.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.
• Session.RELEASE The job will be released and scheduled, only jobs in the USER_ON_HOLD state can be released.

Specified by:

control in interface Session

Parameters:

jobName - String with the job unique identification as provided by the GridWay system. The jobid SHOULD be obtained from a Session.runJob(org.ggf.drmaa.JobTemplate) or Session.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: Session.SUSPEND, Session.RESUME, Session.TERMINATE, Session.HOLD or Session.RELEASE.

Throws:

NoActiveSessionException

ResumeInconsistentStateException

SuspendInconsistentStateException

HoldInconsistentStateException

ReleaseInconsistentStateException

InvalidJobException

DrmCommunicationException

AuthorizationException

DrmaaException

synchronize

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

Description copied from interface: Session

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

Specified by:

synchronize in interface Session

Parameters:

jobList - A NULL terminated list of jobid strings. The jobids SHOULD be obtained from a Session.runJob(org.ggf.drmaa.JobTemplate) or Session.runBulkJobs(org.ggf.drmaa.JobTemplate, int, int, int) methods calls. The pre-defined value Session.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 Session.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 Session.DONE state in the GridWay system and its rusage statistics can be obtained with Session.wait(java.lang.String, long) method call. Also these jobid will not make subsequent calls synchronize method call to fail.

Throws:

NoActiveSessionException

ExitTimeoutException

InvalidJobException

DrmCommunicationException

AuthorizationException

DrmaaException

wait

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

Description copied from interface: Session

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.

Specified by:

wait in interface Session

Parameters:

jobName - String with the job unique identification as provided by the GridWay system. The jobid SHOULD be obtained from a Session.runJob(org.ggf.drmaa.JobTemplate) or Session.runBulkJobs(org.ggf.drmaa.JobTemplate, int, int, int) methods calls. Session.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 Session.TIMEOUT_WAIT_FOREVER. Session.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

DrmCommunicationException

AuthorizationException

DrmaaException

getJobStatus

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

Description copied from interface: Session

Obtains the status of a given job.

Specified by:

getJobStatus in interface Session

Parameters:

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

Returns:

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

• Session.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.
• Session.QUEUED_ACTIVE: The job has been successfully submitted and it is pending to be scheduled.
• Session.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).
• Session.USER_ON_HOLD: The job has been held by the user
• Session.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.
• Session.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.
• Session.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: Session.SYSTEM_ON_HOLD, Session.USER_SYSTEM_ON_HOLD, Session.SYSTEM_SUSPENDED and Session.USER_SYSTEM_SUSPENDED.

Throws:

NoActiveSessionException

InvalidJobException

DrmCommunicationException

AuthorizationException

DrmaaException

getContact

public java.lang.String getContact()

Description copied from interface: Session

If called before Session.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 Session.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.

Specified by:

getContact in interface Session

Returns:

The contact string

getVersion

public Version getVersion()

Description copied from interface: Session

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

Specified by:

getVersion in interface Session

Returns:

Returns the version number as a Version object

getDrmsInfo

public java.lang.String getDrmsInfo()

Description copied from interface: Session

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

Specified by:

getDrmsInfo in interface Session

Returns:

Always "GridWay"

getDrmaaImplementation

public java.lang.String getDrmaaImplementation()

Description copied from interface: Session

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

Specified by:

getDrmaaImplementation in interface Session

Returns:

Always "DRMAA for GridWay M.m"