org.ogf.saga.job
Interface Job

All Superinterfaces:

Async, AsyncAttributes<Job>, Attributes, Cloneable, Future<Void>, Monitorable, Permissions<Job>, SagaObject, Task<Void,Void>

All Known Subinterfaces:

JobSelf

public interface Job
extends Task<Void,Void>, Async, AsyncAttributes<Job>, Permissions<Job>

Jobs are created by a JobService, using a JobDescription. The Job interface extends the Task interface, but jobs don't have an associated Saga object or a result object, so the generic instantiation parameters are Void.

Field Summary

static String	CREATED Attribute name, time stamp of the job creation in the resource manager.
static String	EXECUTIONHOSTS Attribute name, list of host names or IP addresses allocated to run this job.
static String	EXITCODE Attribute name, process exit code.
static String	FINISHED Attribute name, time stamp indicating when the job finished.
static String	JOB_CPUTIME Metric name, number of CPU seconds consumed by the job.
static String	JOB_MEMORYUSE Metric name, current aggregate memory usage of the job.
static String	JOB_PERFORMANCE Metric name, current performance.
static String	JOB_SIGNAL Metric name, fires as a job receives a signal.
static String	JOB_STATE Metric name, fires on state changes of the job.
static String	JOB_STATEDETAIL Metric name, fires as a job changes its state detail.
static String	JOB_VMEMORYUSE Metric name, current aggregate virtual memory usage of the job.
static String	JOBID Attribute name, SAGA representation of the job identifier.
static String	SERVICEURL Attribute name, URL representation of the JobService that created the job.
static String	STARTED Attribute name, time stamp indicating when the job started running.
static String	TERMSIG Attribute name, signal number which caused the job to exit.
static String	WORKINGDIRECTORY Attribute name, working directory on the execution host.

Fields inherited from interface org.ogf.saga.task.Task

TASK_STATE

Fields inherited from interface org.ogf.saga.SagaObject

NO_WAIT, WAIT_FOREVER

Fields inherited from interface org.ogf.saga.attributes.Attributes

BOOL, ENUM, FALSE, FLOAT, INT, STRING, TIME, TRIGGER, TRUE

Method Summary

void	checkpoint() Asks the resource manager to initiate a checkpoint operation on a running job.
Task<Job,Void>	checkpoint(TaskMode mode) Creates a task that asks the resource manager to initiate a checkpoint operation on a running job.
JobDescription	getJobDescription() Retrieves the job description that was used to submit this job instance.
Task<Job,JobDescription>	getJobDescription(TaskMode mode) Creates a task that retrieves the job description that was used to submit this job instance.
InputStream	getStderr() Returns the error stream of this job (which can be read).
Task<Job,InputStream>	getStderr(TaskMode mode) Creates a task that obtains the error stream of this job (which can be read).
OutputStream	getStdin() Returns the input stream of this job (to which can be written).
Task<Job,OutputStream>	getStdin(TaskMode mode) Creates a task that obtains the input stream of this job (to which can be written).
InputStream	getStdout() Returns the output stream of this job (which can be read).
Task<Job,InputStream>	getStdout(TaskMode mode) Creates a task that obtains the output stream of this job (which can be read).
void	migrate(JobDescription jd) Asks the resource manager to migrate a job.
Task<Job,Void>	migrate(TaskMode mode, JobDescription jd) Creates a task that asks the resource manager to migrate a job.
void	resume() Asks the resource manager to perform a resume operation on a suspended job.
Task<Job,Void>	resume(TaskMode mode) Creates a task that asks the resource manager to perform a resume operation on a suspended job.
void	signal(int signum) Asks the resource manager to deliver an arbitrary signal to a dispatched job.
Task<Job,Void>	signal(TaskMode mode, int signum) Creates a task that asks the resource manager to deliver an arbitrary signal to a dispatched job.
void	suspend() Asks the resource manager to perform a suspend operation on a running job.
Task<Job,Void>	suspend(TaskMode mode) Creates a task that asks the resource manager to perform a suspend operation on a running job.

Methods inherited from interface org.ogf.saga.task.Task

cancel, cancel, getObject, getResult, getState, rethrow, run, waitFor, waitFor

Methods inherited from interface org.ogf.saga.SagaObject

clone, getId, getSession

Methods inherited from interface org.ogf.saga.monitoring.Monitorable

addCallback, getMetric, listMetrics, removeCallback

Methods inherited from interface java.util.concurrent.Future

cancel, get, get, isCancelled, isDone

Methods inherited from interface org.ogf.saga.attributes.AsyncAttributes

existsAttribute, findAttributes, getAttribute, getVectorAttribute, isReadOnlyAttribute, isRemovableAttribute, isVectorAttribute, isWritableAttribute, listAttributes, removeAttribute, setAttribute, setVectorAttribute

Methods inherited from interface org.ogf.saga.attributes.Attributes

existsAttribute, findAttributes, getAttribute, getVectorAttribute, isReadOnlyAttribute, isRemovableAttribute, isVectorAttribute, isWritableAttribute, listAttributes, removeAttribute, setAttribute, setVectorAttribute

Methods inherited from interface org.ogf.saga.permissions.Permissions

getGroup, getGroup, getOwner, getOwner, permissionsAllow, permissionsAllow, permissionsCheck, permissionsCheck, permissionsDeny, permissionsDeny

Field Detail

JOBID

static final String JOBID

Attribute name, SAGA representation of the job identifier.

See Also:

Constant Field Values

SERVICEURL

static final String SERVICEURL

Attribute name, URL representation of the JobService that created the job.

See Also:

Constant Field Values

EXECUTIONHOSTS

static final String EXECUTIONHOSTS

Attribute name, list of host names or IP addresses allocated to run this job.

See Also:

Constant Field Values

CREATED

static final String CREATED

Attribute name, time stamp of the job creation in the resource manager.

See Also:

Constant Field Values

STARTED

static final String STARTED

Attribute name, time stamp indicating when the job started running.

See Also:

Constant Field Values

FINISHED

static final String FINISHED

Attribute name, time stamp indicating when the job finished.

See Also:

Constant Field Values

WORKINGDIRECTORY

static final String WORKINGDIRECTORY

Attribute name, working directory on the execution host.

See Also:

Constant Field Values

EXITCODE

static final String EXITCODE

Attribute name, process exit code.

See Also:

Constant Field Values

TERMSIG

static final String TERMSIG

Attribute name, signal number which caused the job to exit.

See Also:

Constant Field Values

JOB_STATE

static final String JOB_STATE

Metric name, fires on state changes of the job.

See Also:

Constant Field Values

JOB_STATEDETAIL

static final String JOB_STATEDETAIL

Metric name, fires as a job changes its state detail.

See Also:

Constant Field Values

JOB_SIGNAL

static final String JOB_SIGNAL

Metric name, fires as a job receives a signal.

See Also:

Constant Field Values

JOB_CPUTIME

static final String JOB_CPUTIME

Metric name, number of CPU seconds consumed by the job.

See Also:

Constant Field Values

JOB_MEMORYUSE

static final String JOB_MEMORYUSE

Metric name, current aggregate memory usage of the job.

See Also:

Constant Field Values

JOB_VMEMORYUSE

static final String JOB_VMEMORYUSE

Metric name, current aggregate virtual memory usage of the job.

See Also:

Constant Field Values

JOB_PERFORMANCE

static final String JOB_PERFORMANCE

Metric name, current performance.

See Also:

Constant Field Values

Method Detail

getJobDescription

JobDescription getJobDescription()
                                 throws NotImplementedException,
                                        AuthenticationFailedException,
                                        AuthorizationFailedException,
                                        PermissionDeniedException,
                                        DoesNotExistException,
                                        TimeoutException,
                                        NoSuccessException

Retrieves the job description that was used to submit this job instance.

Returns:

the job description

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

PermissionDeniedException - is thrown when the method failed because the identity used did not have sufficient permissions to perform the operation successfully.

AuthorizationFailedException - is thrown when none of the available contexts of the used session could be used for successful authorization. This error indicates that the resource could not be accessed at all, and not that an operation was not available due to restricted permissions.

AuthenticationFailedException - is thrown when operation failed because none of the available session contexts could successfully be used for authentication.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

DoesNotExistException - is thrown in cases where the job description is not available, for instance when the job was not submitted through SAGA and the job was obtained using the JobService.getJob(String) call.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

getStdin

OutputStream getStdin()
                      throws NotImplementedException,
                             AuthenticationFailedException,
                             AuthorizationFailedException,
                             PermissionDeniedException,
                             BadParameterException,
                             DoesNotExistException,
                             TimeoutException,
                             IncorrectStateException,
                             NoSuccessException

Returns the input stream of this job (to which can be written).

Returns:

the stream.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

PermissionDeniedException - is thrown when the method failed because the identity used did not have sufficient permissions to perform the operation successfully.

AuthorizationFailedException - is thrown when none of the available contexts of the used session could be used for successful authorization. This error indicates that the resource could not be accessed at all, and not that an operation was not available due to restricted permissions.

AuthenticationFailedException - is thrown when operation failed because none of the available session contexts could successfully be used for authentication.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

DoesNotExistException - is thrown when the stream is not available for some reason.

IncorrectStateException - is thrown when the job is not interactive.

BadParameterException

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

getStdout

InputStream getStdout()
                      throws NotImplementedException,
                             AuthenticationFailedException,
                             AuthorizationFailedException,
                             PermissionDeniedException,
                             BadParameterException,
                             DoesNotExistException,
                             TimeoutException,
                             IncorrectStateException,
                             NoSuccessException

Returns the output stream of this job (which can be read).

Returns:

the stream.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

PermissionDeniedException - is thrown when the method failed because the identity used did not have sufficient permissions to perform the operation successfully.

AuthorizationFailedException - is thrown when none of the available contexts of the used session could be used for successful authorization. This error indicates that the resource could not be accessed at all, and not that an operation was not available due to restricted permissions.

AuthenticationFailedException - is thrown when operation failed because none of the available session contexts could successfully be used for authentication.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

DoesNotExistException - is thrown when the stream is not available for some reason.

IncorrectStateException - is thrown when the job is not interactive.

BadParameterException

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

getStderr

InputStream getStderr()
                      throws NotImplementedException,
                             AuthenticationFailedException,
                             AuthorizationFailedException,
                             PermissionDeniedException,
                             BadParameterException,
                             DoesNotExistException,
                             TimeoutException,
                             IncorrectStateException,
                             NoSuccessException

Returns the error stream of this job (which can be read).

Returns:

the stream.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

PermissionDeniedException - is thrown when the method failed because the identity used did not have sufficient permissions to perform the operation successfully.

AuthorizationFailedException - is thrown when none of the available contexts of the used session could be used for successful authorization. This error indicates that the resource could not be accessed at all, and not that an operation was not available due to restricted permissions.

AuthenticationFailedException - is thrown when operation failed because none of the available session contexts could successfully be used for authentication.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

DoesNotExistException - is thrown when the stream is not available for some reason.

IncorrectStateException - is thrown when the job is not interactive.

BadParameterException

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

suspend

void suspend()
             throws NotImplementedException,
                    AuthenticationFailedException,
                    AuthorizationFailedException,
                    PermissionDeniedException,
                    IncorrectStateException,
                    TimeoutException,
                    NoSuccessException

Asks the resource manager to perform a suspend operation on a running job.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

PermissionDeniedException - is thrown when the method failed because the identity used did not have sufficient permissions to perform the operation successfully.

AuthorizationFailedException - is thrown when none of the available contexts of the used session could be used for successful authorization. This error indicates that the resource could not be accessed at all, and not that an operation was not available due to restricted permissions.

AuthenticationFailedException - is thrown when operation failed because none of the available session contexts could successfully be used for authentication.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

IncorrectStateException - is thrown when the job is not in RUNNING state.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

resume

void resume()
            throws NotImplementedException,
                   AuthenticationFailedException,
                   AuthorizationFailedException,
                   PermissionDeniedException,
                   IncorrectStateException,
                   TimeoutException,
                   NoSuccessException

Asks the resource manager to perform a resume operation on a suspended job.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

PermissionDeniedException - is thrown when the method failed because the identity used did not have sufficient permissions to perform the operation successfully.

AuthorizationFailedException - is thrown when none of the available contexts of the used session could be used for successful authorization. This error indicates that the resource could not be accessed at all, and not that an operation was not available due to restricted permissions.

AuthenticationFailedException - is thrown when operation failed because none of the available session contexts could successfully be used for authentication.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

IncorrectStateException - is thrown when the job is not in SUSPENDED state.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

checkpoint

void checkpoint()
                throws NotImplementedException,
                       AuthenticationFailedException,
                       AuthorizationFailedException,
                       PermissionDeniedException,
                       IncorrectStateException,
                       TimeoutException,
                       NoSuccessException

Asks the resource manager to initiate a checkpoint operation on a running job.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

PermissionDeniedException - is thrown when the method failed because the identity used did not have sufficient permissions to perform the operation successfully.

AuthorizationFailedException - is thrown when none of the available contexts of the used session could be used for successful authorization. This error indicates that the resource could not be accessed at all, and not that an operation was not available due to restricted permissions.

AuthenticationFailedException - is thrown when operation failed because none of the available session contexts could successfully be used for authentication.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

IncorrectStateException - is thrown when the job is not in RUNNING state.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

migrate

void migrate(JobDescription jd)
             throws NotImplementedException,
                    AuthenticationFailedException,
                    AuthorizationFailedException,
                    PermissionDeniedException,
                    BadParameterException,
                    IncorrectStateException,
                    TimeoutException,
                    NoSuccessException

Asks the resource manager to migrate a job.

Parameters:

jd - new job parameters to apply when the job is migrated.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

PermissionDeniedException - is thrown when the method failed because the identity used did not have sufficient permissions to perform the operation successfully.

AuthorizationFailedException - is thrown when none of the available contexts of the used session could be used for successful authorization. This error indicates that the resource could not be accessed at all, and not that an operation was not available due to restricted permissions.

AuthenticationFailedException - is thrown when operation failed because none of the available session contexts could successfully be used for authentication.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

IncorrectStateException - is thrown when the job is not in RUNNING or SUSPENDED state.

BadParameterException - is thrown if there is something wrong with the specified job description.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

signal

void signal(int signum)
            throws NotImplementedException,
                   AuthenticationFailedException,
                   AuthorizationFailedException,
                   PermissionDeniedException,
                   BadParameterException,
                   IncorrectStateException,
                   TimeoutException,
                   NoSuccessException

Asks the resource manager to deliver an arbitrary signal to a dispatched job.

Throws:

NotImplementedException - is thrown if the implementation does not provide an implementation of this method.

PermissionDeniedException - is thrown when the method failed because the identity used did not have sufficient permissions to perform the operation successfully.

AuthorizationFailedException - is thrown when none of the available contexts of the used session could be used for successful authorization. This error indicates that the resource could not be accessed at all, and not that an operation was not available due to restricted permissions.

AuthenticationFailedException - is thrown when operation failed because none of the available session contexts could successfully be used for authentication.

TimeoutException - is thrown when a remote operation did not complete successfully because the network communication or the remote service timed out.

IncorrectStateException - is thrown when the job is not in RUNNING or SUSPENDED state.

BadParameterException - is thrown if the specified signal is not supported by the backend.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

getJobDescription

Task<Job,JobDescription> getJobDescription(TaskMode mode)
                                           throws NotImplementedException

Creates a task that retrieves the job description that was used to submit this job instance.

Parameters:

mode - the task mode.

Returns:

the task.

Throws:

NotImplementedException - is thrown when the task version of this method is not implemented.

getStdin

Task<Job,OutputStream> getStdin(TaskMode mode)
                                throws NotImplementedException

Creates a task that obtains the input stream of this job (to which can be written).

Parameters:

mode - the task mode.

Returns:

the task.

Throws:

NotImplementedException - is thrown when the task version of this method is not implemented.

getStdout

Task<Job,InputStream> getStdout(TaskMode mode)
                                throws NotImplementedException

Creates a task that obtains the output stream of this job (which can be read).

Parameters:

mode - the task mode.

Returns:

the task.

Throws:

NotImplementedException - is thrown when the task version of this method is not implemented.

getStderr

Task<Job,InputStream> getStderr(TaskMode mode)
                                throws NotImplementedException

Creates a task that obtains the error stream of this job (which can be read).

Parameters:

mode - the task mode.

Returns:

the task.

Throws:

NotImplementedException - is thrown when the task version of this method is not implemented.

suspend

Task<Job,Void> suspend(TaskMode mode)
                       throws NotImplementedException

Creates a task that asks the resource manager to perform a suspend operation on a running job.

Parameters:

mode - the task mode.

Returns:

the task.

Throws:

NotImplementedException - is thrown when the task version of this method is not implemented.

resume

Task<Job,Void> resume(TaskMode mode)
                      throws NotImplementedException

Creates a task that asks the resource manager to perform a resume operation on a suspended job.

Parameters:

mode - the task mode.

Returns:

the task.

Throws:

NotImplementedException - is thrown when the task version of this method is not implemented.

checkpoint

Task<Job,Void> checkpoint(TaskMode mode)
                          throws NotImplementedException

Creates a task that asks the resource manager to initiate a checkpoint operation on a running job.

Parameters:

mode - the task mode.

Returns:

the task.

Throws:

NotImplementedException - is thrown when the task version of this method is not implemented.

migrate

Task<Job,Void> migrate(TaskMode mode,
                       JobDescription jd)
                       throws NotImplementedException

Creates a task that asks the resource manager to migrate a job.

Parameters:

jd - new job parameters to apply when the job is migrated.

mode - the task mode.

Returns:

the task.

Throws:

NotImplementedException - is thrown when the task version of this method is not implemented.

signal

Task<Job,Void> signal(TaskMode mode,
                      int signum)
                      throws NotImplementedException

Creates a task that asks the resource manager to deliver an arbitrary signal to a dispatched job.

Parameters:

mode - the task mode.

Returns:

the task.

Throws:

NotImplementedException - is thrown when the task version of this method is not implemented.