org.gridlab.gat.resources
Interface Job

All Superinterfaces:
Advertisable, Monitorable, Serializable
All Known Subinterfaces:
CoScheduleJob, WrapperJob

public interface Job
extends Monitorable, Advertisable

An instance of this class represents a job.

A job is the entire process of (1) getting an application to execute on some location, (2) the actual execution of the application and (3) the cleanup after the execution.

A job will be constructed by a ResourceBroker according to a description of it, the JobDescription.

A job object always has an associated state and can be polled for this state. Examples of state sequences are:

The following relations are true for the state order: It depends on the implementation of the Job in the adaptor which states are supported for that adaptor. For instance a local job might never be in the state SCHEDULED.

It's also possible to add a listener to a Job object which can listen to a metric that the job provides. Most Jobs provide at least the metric "job.status", which will indicate state changes. Note that it is possible to receive a state twice, or that some states may never occur.

Furthermore, if you want to listen to metric that's firing metrics during the creation of the Job object (which is done by the ResourceBroker), you can add the listener and the metric name to the submitJob method in the ResourceBroker.

Note that adaptors might not implement the whole functionality.


Nested Class Summary
static class Job.JobState
          An instance of this enumeration indicates the state of a Job.
 
Field Summary
static String ADAPTOR_JOB_ID
          Key corresponding to a String value which indicates an adaptor-specific job-id.
static String HOSTNAME
          Key corresponding to a String value which is the name of the host on which the physical job is running, if the job is in the RUNNING state.
static String POSTSTAGE_EXCEPTION
          Key corresponding to an exception value that occurred while poststaging.
static String STARTTIME
          Key corresponding to a long value which is the number of milliseconds after January 1, 1970, 00:00:00 GMT when the associated physical job was started.
static String STATE
          Key corresponding to a value which is the name of the state the job is in.
static String STOPTIME
          Key corresponding to a long value which is the number of milliseconds after January 1, 1970, 00:00:00 GMT when the associated physical job stopped.
static String SUBMISSIONTIME
          Key corresponding to a long value which is the number of milliseconds after January 1, 1970, 00:00:00 GMT when the associated physical job was submitted.
 
Method Summary
 void checkpoint()
          Deprecated. Deprecated, this method doesn't fit in the API anymore
 Job cloneJob(HardwareResource resource)
          Deprecated. Deprecated, this method doesn't fit in the API anymore
 int getExitStatus()
          Returns the exit status of a job.
 Map<String,Object> getInfo()
          This method returns an instance of the class Map which contains information about the associated Job.
 AbstractJobDescription getJobDescription()
          Returns the AbstractJobDescription that was used to create this Job.
 int getJobID()
          This method returns the job id, a globally unique identifier for the physical job corresponding to this instance.
 Job.JobState getState()
          This method returns the state of the Job.
 InputStream getStderr()
           
 OutputStream getStdin()
           
 InputStream getStdout()
           
 void hold()
          Put a job on hold, pause it.
 void migrate()
          Deprecated. Deprecated, this method doesn't fit in the API anymore
 void migrate(HardwareResourceDescription hardwareResourceDescription)
          Deprecated. Deprecated, this method doesn't fit in the API anymore
 void resume()
          Resume a job that was paused with the "hold" method.
 void stop()
          Stops the associated physical job.
 String toString()
           
 void unSchedule()
          Deprecated. Deprecated, because there is a race condition here. The job state can change between the call to getState and the call to stop/unSchedule. Use stop instead.
 
Methods inherited from interface org.gridlab.gat.monitoring.Monitorable
addMetricListener, getMeasurement, getMetricDefinitionByName, getMetricDefinitions, removeMetricListener
 
Methods inherited from interface org.gridlab.gat.advert.Advertisable
marshal
 

Field Detail

STATE

static final String STATE
Key corresponding to a value which is the name of the state the job is in. The state strings are literally the same as the name of the constants used, e.g., "RUNNING", or "STOPPED". See getInfo().

See Also:
Constant Field Values

HOSTNAME

static final String HOSTNAME
Key corresponding to a String value which is the name of the host on which the physical job is running, if the job is in the RUNNING state. If the associated job is not in the RUNNING state, the value is null. See getInfo().

See Also:
Constant Field Values

SUBMISSIONTIME

static final String SUBMISSIONTIME
Key corresponding to a long value which is the number of milliseconds after January 1, 1970, 00:00:00 GMT when the associated physical job was submitted. This value is null for a job in the INITIAL state, otherwise it is not null. See getInfo().

See Also:
Constant Field Values

STARTTIME

static final String STARTTIME
Key corresponding to a long value which is the number of milliseconds after January 1, 1970, 00:00:00 GMT when the associated physical job was started. This value is null for a job in the SCHEDULED or INITIAL states, otherwise it is not null. See getInfo().

See Also:
Constant Field Values

STOPTIME

static final String STOPTIME
Key corresponding to a long value which is the number of milliseconds after January 1, 1970, 00:00:00 GMT when the associated physical job stopped. This value is not null for a job in the STOPPED state, otherwise it is null. See getInfo().

See Also:
Constant Field Values

POSTSTAGE_EXCEPTION

static final String POSTSTAGE_EXCEPTION
Key corresponding to an exception value that occurred while poststaging. This key is only present if the application did run but one or more files could not be poststaged. See getInfo().

See Also:
Constant Field Values

ADAPTOR_JOB_ID

static final String ADAPTOR_JOB_ID
Key corresponding to a String value which indicates an adaptor-specific job-id. Present if provided by the adaptor. See getInfo().

See Also:
Constant Field Values
Method Detail

getJobDescription

AbstractJobDescription getJobDescription()
Returns the AbstractJobDescription that was used to create this Job.

Returns:
the JobDescription that belongs to this Job

unSchedule

void unSchedule()
                throws GATInvocationException
Deprecated. Deprecated, because there is a race condition here. The job state can change between the call to getState and the call to stop/unSchedule. Use stop instead.

Stops the associated physical job. Upon a successful call to this method the associated physical job is forcibly terminated. This method can only be called on a job in the SCHEDULED or RUNNING state.

Throws:
GATInvocationException - Thrown upon problems accessing the remote instance

stop

void stop()
          throws GATInvocationException
Stops the associated physical job. Upon a successful call to this method the associated physical job is forcibly terminated. This method can be called in any state. Note that the termination of jobs may take some time.

Throws:
GATInvocationException - Thrown upon problems accessing the remote instance

getState

Job.JobState getState()
This method returns the state of the Job. This is one of the associated public member variables INITIAL, SCHEDULED, RUNNING, STOPPED, ON_HOLD, PRE_STAGING, POST_STAGING, UNKNOWN or SUBMISSSION_ERROR.

Returns:
This method returns the state of the associated Job

getInfo

Map<String,Object> getInfo()
                           throws GATInvocationException
This method returns an instance of the class Map which contains information about the associated Job. This Map contains a set of key/value pairs the key, a String, being the name of the information and the value being the value of the associated named information. The minimum set of keys which the returned Map contains is as follows:

state The key state corresponds to a String value which is the name of the state the job is in. The state strings are literally the same as the name of the constants used, e.g., "RUNNING", or "STOPPED".

hostname The key hostname corresponds to a String value which is the name of the host on which the physical job is running, if the job is in the RUNNING state. If the associated job is not in the RUNNING state, the value is null.

submissiontime The key submissiontime corresponds to a long value which is the number of milliseconds after January 1, 1970, 00:00:00 GMT when the associated physical job was submitted. This value is null for a job in the INITIAL state otherwise it is not null.

starttime The key starttime corresponds to a long value which is the number of milliseconds after January 1, 1970, 00:00:00 GMT when the associated physical job was started. This value is null for a job in the SCHEDULED or INITIAL states otherwise it is not null.

stoptime The key stoptime corresponds to a long value which is the number of milliseconds after January 1, 1970, 00:00:00 GMT when the associated physical job stopped. This value is not null for a job in the STOPPED state otherwise it is null.

poststage.exception This key is present in the map if the application did run, but one or more files could not be post staged. The data value attached to this key is the exception that occurred while post staging.

Other key/value pairs will be in future added to the list of key/value pairs returned in this Map as the need develops.

Returns:
An instance of the class Map which presents information about the associated job.
Throws:
GATInvocationException - Thrown upon problems accessing the remote instance

getJobID

int getJobID()
This method returns the job id, a globally unique identifier for the physical job corresponding to this instance. Some adaptors provide an adaptor specific job id. This can be retrieved by getting the value belonging to the key 'adaptor.job.id' in the Map returned by getInfo().

Returns:
An integer which represents the job ID

checkpoint

void checkpoint()
                throws GATInvocationException
Deprecated. Deprecated, this method doesn't fit in the API anymore

Throws:
GATInvocationException - Thrown upon problems accessing the remote instance

migrate

void migrate()
             throws GATInvocationException
Deprecated. Deprecated, this method doesn't fit in the API anymore

Throws:
GATInvocationException - Thrown upon problems accessing the remote instance

migrate

void migrate(HardwareResourceDescription hardwareResourceDescription)
             throws GATInvocationException
Deprecated. Deprecated, this method doesn't fit in the API anymore

Parameters:
hardwareResourceDescription - A description of the hardware resource to which the physical job corresponding to this Job should be migrated, a HardwareResourceDescription
Throws:
GATInvocationException - Thrown upon problems accessing the remote instance

cloneJob

Job cloneJob(HardwareResource resource)
Deprecated. Deprecated, this method doesn't fit in the API anymore

Parameters:
resource - HarwareResource to run the job on (null means any resource)
Returns:
the clone of the job

hold

void hold()
          throws GATInvocationException
Put a job on hold, pause it. This can be called in SCHEDULED or RUNNING state.

Throws:
GATInvocationException

resume

void resume()
            throws GATInvocationException
Resume a job that was paused with the "hold" method. This can be called only in the ON_HOLD state.

Throws:
GATInvocationException

getExitStatus

int getExitStatus()
                  throws GATInvocationException
Returns the exit status of a job.

Returns:
the exit status of a job.
Throws:
GATInvocationException

toString

String toString()
Overrides:
toString in class Object

getStdout

InputStream getStdout()
                      throws GATInvocationException
Throws:
GATInvocationException

getStderr

InputStream getStderr()
                      throws GATInvocationException
Throws:
GATInvocationException

getStdin

OutputStream getStdin()
                      throws GATInvocationException
Throws:
GATInvocationException