com.parabon.runtime
Interface TaskContext

All Known Subinterfaces:

SerializableTaskContext

All Known Implementing Classes:

SerializableTaskContextProxy, SerializableTaskContextProxy.Placeholder, SerializableTaskWrapper

public interface TaskContext

Provides a single channel of communication from a running task instance to the runtime system. Provided services include retrieving data elements, reporting progress, and logging checkpoints.

Method Summary

DataBuffer	createDataBuffer() Create a data buffer for the task to use internally.
DataBuffer	createDataBuffer(boolean useDiskHint) Similar to createDataBuffer(), but tends to create a buffer stored either entirely on disk or entirely in memory as specified by the supplied hint.
DataBuffer	getElement(java.net.URI uri) Obtain a data element.
java.io.File	getTempDirectory() Returns the path of a temporary directory for the task's use with read, write, delete and execute permissions on the directory and all of its files and subdirectories, recursively.
void	logCheckpoint(DataBuffer checkpoint) Log a checkpoint which may be used to restart this task at a later time.
void	logCheckpoint(DataBuffer checkpoint, boolean force) Log a checkpoint which may be used to restart this task at a later time.
void	postIntermediateResultsData(DataBuffer intermediateResults) Post intermediate results.
void	postIntermediateResultsData(double progress, DataBuffer intermediateResults) Post intermediate results and report progress simultaneously.
void	postIntermediateResultsObject(double progress, java.io.Serializable intermediateResults) Post intermediate results and report progress simultaneously.
void	postIntermediateResultsObject(java.io.Serializable intermediateResults) Post intermediate results.
void	reportProgress(double progress) Report progress, replacing all previous progress reports.
boolean	shouldLogCheckpoint() Provides a hint as to whether a checkpoint should be logged.
boolean	shouldPostIntermediateResults() Provides a hint as to whether intermediate results should be posted.
boolean	shouldStop() Reports whether the task should stop immediately, throwing a TaskStoppedException from the Task.run method.

Method Detail

getElement

DataBuffer getElement(java.net.URI uri)

Obtain a data element. This method can be invoked as many times as necessary for a given element.

Returns:

a read-only DataBuffer, or null if an element which was not marked as required for this task is requested. Any attempt to modify the contents of this DataBuffer will result in an UnsupportedOperationException.

createDataBuffer

DataBuffer createDataBuffer()

Create a data buffer for the task to use internally. The created buffer can be freely modified and can be passed to postIntermediateResults and logCheckpoint as well as being returned from Task.run containing final results. The data buffer's contents will be maintained until either release is invoked on the buffer, the task completes, or the task is restarted.

The runtime will decide whether to store this data buffer entirely on disk, entirely in memory, or a dynamic mixture of these.

See Also:

createDataBuffer(boolean)

createDataBuffer

DataBuffer createDataBuffer(boolean useDiskHint)

Similar to createDataBuffer(), but tends to create a buffer stored either entirely on disk or entirely in memory as specified by the supplied hint. Note that the hint may not be used; this method's behaviour is not guaranteed to be any different from that of createDataBuffer().

See Also:

createDataBuffer()

reportProgress

void reportProgress(double progress)

Report progress, replacing all previous progress reports. The supplied progress value may or may not be reported back to the server independently of checkpoints or results.

Progress is an optional hint to the runtime system as well as the initiating client, and can enhance scheduling performance as well as providing a human-understandable measure of a task's completion.. It is defined to be a monotonically nondecreasing positive function (that is, it never goes down); any other behaviour can result in reduced scheduling efficiency. If restarting from a checkpoint, the first progress reported (if any) must be equal to or greater than the last progress reported before that checkpoint was created (if any).

Many tasks report progress such that it varies linearly from 0 to 1; when practical, this behaviour is recommended. However, this is not desirable nor even possible for all tasks. It is suggested that tasks which do not (for whatever reason) employ this convention, then they should report progress values greater than 1.0 -- that is, the first progress reported should be greater than 1.0, and all subsequent progress reports greater still than that. This way, when generic applications or components are observing progress without any information about what type of progress values are reported by a given task, they can use a value between 0 and 1 as a hint that the progress will vary linearly through this range and hence can, for example, display graphical progress bars or percentages, and compute estimated completion times. Note that this is merely a convention, however, and need not be obeyed at the task developer's discretion.

shouldPostIntermediateResults

boolean shouldPostIntermediateResults()

Provides a hint as to whether intermediate results should be posted. Returns true if sufficient time has passed since the last intermediate results to be worth sending new ones, determined based on factors such as maximum intermediate results frequency.

postIntermediateResultsData

void postIntermediateResultsData(DataBuffer intermediateResults)

Post intermediate results. These results will replace all previous intermediate results. Intermediate results may consist of detailed status information, partial results, or any other information which may be of use to the client. Note, however, that intermediate results are generally not retained after new intermediate results or final results are reported, and no guarantee is provided that any intermediate results will be reported back to the client.

Parameters:

intermediateResults - the intermediate results. Must be a DataBuffer instance obtained by the task during the current run (that is, since the run method was invoked on the current task instance, based on either initial parameters or a checkpoint) via createDataBuffer, or getDataElement methods of this TaskContext, or as a parameter to the task's own run method. This task retains ownership of the DataBuffer and can freely modify it after this method returns without affecting the contents of the reported intermediate results.

See Also:

createDataBuffer()

postIntermediateResultsData

void postIntermediateResultsData(double progress,
                                 DataBuffer intermediateResults)

Post intermediate results and report progress simultaneously. This method is similar to invoking reportProgress(progress); postIntermediateResultsData(intermediateResults);

See Also:

reportProgress(double), postIntermediateResultsData(DataBuffer)

postIntermediateResultsObject

void postIntermediateResultsObject(java.io.Serializable intermediateResults)

Post intermediate results. These results will replace all previous intermediate results. Intermediate results may consist of detailed status information, partial results, or any other information which may be of use to the client. Note, however, that intermediate results are generally not retained after new intermediate results or final results are reported, and no guarantee is provided that any intermediate results will be reported back to the client.

Parameters:

intermediateResults - the intermediate results. Must be a valid Serializable object instance.

postIntermediateResultsObject

void postIntermediateResultsObject(double progress,
                                   java.io.Serializable intermediateResults)

Post intermediate results and report progress simultaneously. This method is similar to invoking reportProgress(progress); postIntermediateResultsObject(intermediateResults);

See Also:

reportProgress(double), postIntermediateResultsObject(Serializable)

shouldLogCheckpoint

boolean shouldLogCheckpoint()

Provides a hint as to whether a checkpoint should be logged. Returns true if sufficient time has passed since the last checkpoint to be worth creating a new checkpoint, determined based on factors such as how long previous checkpoints have taken to be saved.

logCheckpoint

void logCheckpoint(DataBuffer checkpoint)

Log a checkpoint which may be used to restart this task at a later time. Restarting a task from a checkpoint occurs by creating a new instance of the task class and invoking its run method with a DataBuffer containing the contents of a checkpoint instead of the initial parameters of a task. The checkpoint may or may not be reported back to the server or the client, and may or may not be saved locally on the provider. Reporting checkpoints ensures that interrupted tasks can be restarted from the last reported checkpoint rather than the initial state; in extreme cases, tasks which do not report checkpoints (or report them too infrequently) may never complete because of interruptions.

This method will tend to return immediately without logging a checkpoint if shouldLogCheckpoint returns false.

Equivalent to logCheckpoint(checkpoint, false).

Parameters:

checkpoint - a buffer containing all state necessary to define task. This task retains ownership of the DataBuffer and can freely modify it after this method returns without affecting the substance of the checkpoint.

See Also:

shouldLogCheckpoint(), logCheckpoint(DataBuffer, boolean)

logCheckpoint

void logCheckpoint(DataBuffer checkpoint,
                   boolean force)

Log a checkpoint which may be used to restart this task at a later time. Restarting a task from a checkpoint occurs by creating a new instance of the task class and invoking its run() method with a DataBuffer containing the contents of a checkpoint instead of the initial parameters of a task. The checkpoint may or may not be reported back to the server or the client, and may or may not be saved locally on the provider. Reporting checkpoints ensures that interrupted tasks can be restarted from the last reported checkpoint rather than the initial state; in extreme cases, tasks which do not report checkpoints (or report them too infrequently) may never complete because of interruptions.

If force is true, this routine will tend to log a checkpoint even if shouldLogCheckpoint is false. This functionality is useful when, for instance, the task is only able to generate checkpoints at certain infrequent points, and another checkpoint may not be available for a while; in this case, the task's knowledge is more important than the system's checkpoint-logging efficiency heuristics. Note, however, that the system may decide not to save or transmit a checkpoint even when force is true. When force is false, this method is equivalent to logCheckpoint(checkpoint).

Parameters:

checkpoint - a buffer containing all state necessary to define task. This task retains ownership of the DataBuffer and can freely modify it after this method returns without affecting the substance of the checkpoint.

force - true if the method should attempt to save a checkpoint even though shouldLogCheckpoint returns false. This flag is only a hint, however, and the system may override it.

See Also:

shouldLogCheckpoint(), logCheckpoint(DataBuffer)

getTempDirectory

java.io.File getTempDirectory()
                              throws java.lang.SecurityException

Returns the path of a temporary directory for the task's use with read, write, delete and execute permissions on the directory and all of its files and subdirectories, recursively.

Throws:

java.lang.SecurityException - if no temporary directory can be made available

shouldStop

boolean shouldStop()

Reports whether the task should stop immediately, throwing a TaskStoppedException from the Task.run method. A task may call this method instead of (or in addition to) implementing the Task.stop method; both mechanisms provide a means for a task to stop gracefully, optionally logging a final checkpoint, etc before exiting. If shouldStop returns true, then Task.stop has already been or will soon be called as well, and vice-versa.

See Also:

Task.stop()