com.parabon.client
Class SerializableTaskWrapper

java.lang.Object
  extended by com.parabon.client.SerializableTaskWrapper
All Implemented Interfaces:
SerializableTaskContext, Task, TaskContext

public class SerializableTaskWrapper
extends java.lang.Object
implements Task, SerializableTaskContext

This class should not be used directly; instead, use SerializableTaskAdapter


Constructor Summary
SerializableTaskWrapper()
           
 
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.
protected  DataBuffer getTempBuffer()
           
 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()
          Log a checkpoint which may be used to restart this task at a later time.
 void logCheckpoint(boolean force)
          Log a checkpoint which may be used to restart this task at a later time.
 void logCheckpoint(DataBuffer checkpoint)
          This form of logCheckpoint should not be used for SerializableTasks.
 void logCheckpoint(DataBuffer checkpoint, boolean force)
          This form of logCheckpoint should not be used for SerializableTasks.
 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.
 DataBuffer run(TaskContext context, DataBuffer parameters)
          Execute the task normally, either initially or from a checkpoint.
 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.
 void stop()
          Request that the run method stop gracefully (ideally reporting one last checkpoint) by throwing a com.parabon.runtime.TaskStoppedException.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SerializableTaskWrapper

public SerializableTaskWrapper()
Method Detail

getTempBuffer

protected DataBuffer getTempBuffer()

run

public DataBuffer run(TaskContext context,
                      DataBuffer parameters)
               throws java.lang.Exception
Description copied from interface: Task
Execute the task normally, either initially or from a checkpoint. run should exit normally after the task has successfully completed, or should throw an exception if any error has occurred. Behaviour differs based on the type of exception thrown. If an error occurs in the runtime environment (in cases such as resource limitations or external system errors), the system will attempt to restart the task from the last checkpoint when the problem is solved. A com.parabon.runtime.TaskStoppedException is thrown always and only after the task's stop method is called, and as such are expected by the system; again, the system will restart from the last checkpoint when possible. Any other exception is assumed to be an internal task failure, and as such, the task is considered to be complete and will not be restarted. The error description reported back to the client from such a task exception is set to the value returned by the exception's toString or printStackTrace methods.

Once the task exits its run method, all threads created by the task must have completed and exited. Any action by a running thread after run returns will result in undefined behaviour.

Specified by:
run in interface Task
Parameters:
context - a TaskContext implementation through which the task can communicate with the runtime environment, in particular to obtain data elements and report progress, checkpoints, and intermediate results.
parameters - a read-only DataBuffer containing the task's parameters either as specified by the client application initially via a TaskSpec or else reported as a checkpoint by a running task. Any attempt to modify the contents of this DataBuffer will result in an UnsupportedOperationException.
Returns:
a DataBuffer containing the task's final results. This DataBuffer must have been obtained from the TaskContext during this execution of the task, via either getDataElement or createDataBuffer.
Throws:
java.lang.Exception

stop

public void stop()
Description copied from interface: Task
Request that the run method stop gracefully (ideally reporting one last checkpoint) by throwing a com.parabon.runtime.TaskStoppedException. If the run method does not exit within an unspecified time after stop is called, task threads or the JVM as a whole may be shut down unceremoniously.

A task may query the TaskContext.shouldStop method instead of (or in addition to) implementing this method; both mechanisms provide the same information. If Task.stop has been invoked, then TaskContext.shouldStop will return true, and vice-versa.

Specified by:
stop in interface Task
See Also:
TaskContext.shouldStop()

shouldLogCheckpoint

public boolean shouldLogCheckpoint()
Description copied from interface: TaskContext
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.

Specified by:
shouldLogCheckpoint in interface TaskContext

logCheckpoint

public void logCheckpoint()
Description copied from interface: SerializableTaskContext
Log a checkpoint which may be used to restart this task at a later time. The checkpoint is formed by serializing the associated SerializableTask instance via the Serializable and ObjectOutput interfaces. Serialization will take place before logCheckpoint returns (if at all). Restarting a task from a checkpoint occurs by deserializing the resulting checkpoint and invoking its run method. Hence, logCheckpoint should only be invoked while the task is in a state such that serializaing it is guaranteed to provide a valid checkpoint; the task must remain in this state at least until logCheckpoint returns -- that is, other threads should not change the state of the task while this method is executing.

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

Specified by:
logCheckpoint in interface SerializableTaskContext
See Also:
TaskContext.shouldLogCheckpoint(), SerializableTaskContext.logCheckpoint(boolean)

logCheckpoint

public void logCheckpoint(boolean force)
Description copied from interface: SerializableTaskContext
Log a checkpoint which may be used to restart this task at a later time. The checkpoint is formed by serializing the associated SerializableTask instance via the Serializable and ObjectOutput interfaces. Serialization will take place before logCheckpoint returns (if at all). Restarting a task from a checkpoint occurs by deserializing the resulting checkpoint and invoking its run method. Hence, logCheckpoint should only be invoked while the task is in a state such that serializaing it is guaranteed to provide a valid checkpoint; the task must remain in this state at least until logCheckpoint returns -- that is, other threads should not change the state of the task while this method is executing.

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

Specified by:
logCheckpoint in interface SerializableTaskContext
Parameters:
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:
TaskContext.shouldLogCheckpoint(), SerializableTaskContext.logCheckpoint()

logCheckpoint

public void logCheckpoint(DataBuffer checkpoint)
Description copied from interface: SerializableTaskContext
This form of logCheckpoint should not be used for SerializableTasks. Use SerializableTaskContext.logCheckpoint() instead.

Specified by:
logCheckpoint in interface SerializableTaskContext
Specified by:
logCheckpoint in interface TaskContext
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:
TaskContext.shouldLogCheckpoint(), TaskContext.logCheckpoint(DataBuffer, boolean)

logCheckpoint

public void logCheckpoint(DataBuffer checkpoint,
                          boolean force)
Description copied from interface: SerializableTaskContext
This form of logCheckpoint should not be used for SerializableTasks. Use SerializableTaskContext.logCheckpoint(boolean) instead.

Specified by:
logCheckpoint in interface SerializableTaskContext
Specified by:
logCheckpoint in interface TaskContext
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:
TaskContext.shouldLogCheckpoint(), TaskContext.logCheckpoint(DataBuffer)

createDataBuffer

public DataBuffer createDataBuffer()
Description copied from interface: TaskContext
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.

Specified by:
createDataBuffer in interface TaskContext
See Also:
TaskContext.createDataBuffer(boolean)

createDataBuffer

public DataBuffer createDataBuffer(boolean useDiskHint)
Description copied from interface: TaskContext
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().

Specified by:
createDataBuffer in interface TaskContext
See Also:
TaskContext.createDataBuffer()

getElement

public DataBuffer getElement(java.net.URI uri)
Description copied from interface: TaskContext
Obtain a data element. This method can be invoked as many times as necessary for a given element.

Specified by:
getElement in interface TaskContext
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.

getTempDirectory

public java.io.File getTempDirectory()
                              throws java.lang.SecurityException
Description copied from interface: TaskContext
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.

Specified by:
getTempDirectory in interface TaskContext
Throws:
java.lang.SecurityException - if no temporary directory can be made available

shouldPostIntermediateResults

public boolean shouldPostIntermediateResults()
Description copied from interface: TaskContext
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.

Specified by:
shouldPostIntermediateResults in interface TaskContext

postIntermediateResultsData

public void postIntermediateResultsData(DataBuffer intermediateResults)
Description copied from interface: TaskContext
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.

Specified by:
postIntermediateResultsData in interface TaskContext
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:
TaskContext.createDataBuffer()

postIntermediateResultsData

public void postIntermediateResultsData(double progress,
                                        DataBuffer intermediateResults)
Description copied from interface: TaskContext
Post intermediate results and report progress simultaneously. This method is similar to invoking reportProgress(progress); postIntermediateResultsData(intermediateResults);

Specified by:
postIntermediateResultsData in interface TaskContext
See Also:
TaskContext.reportProgress(double), TaskContext.postIntermediateResultsData(DataBuffer)

postIntermediateResultsObject

public void postIntermediateResultsObject(java.io.Serializable intermediateResults)
Description copied from interface: TaskContext
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.

Specified by:
postIntermediateResultsObject in interface TaskContext
Parameters:
intermediateResults - the intermediate results. Must be a valid Serializable object instance.

postIntermediateResultsObject

public void postIntermediateResultsObject(double progress,
                                          java.io.Serializable intermediateResults)
Description copied from interface: TaskContext
Post intermediate results and report progress simultaneously. This method is similar to invoking reportProgress(progress); postIntermediateResultsObject(intermediateResults);

Specified by:
postIntermediateResultsObject in interface TaskContext
See Also:
TaskContext.reportProgress(double), TaskContext.postIntermediateResultsObject(Serializable)

reportProgress

public void reportProgress(double progress)
Description copied from interface: TaskContext
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.

Specified by:
reportProgress in interface TaskContext

shouldStop

public boolean shouldStop()
Description copied from interface: TaskContext
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.

Specified by:
shouldStop in interface TaskContext
See Also:
Task.stop()