com.parabon.client
Interface SerializableTask

All Superinterfaces:

java.io.Serializable

public interface SerializableTask
extends java.io.Serializable

The SerializableTask interface is an alternative to Task which provides the ability to automatically serialize a task object created by an application and deserialize for task execution, followed by serialization and subsequent deserialization of results. For most tasks, this interface and the related support in the com.parabon.client provide an easier and more elegant interface for task execution, but may in some cases be slightly less efficient due to increased overhead, and may also be slightly less flexible when byte-by-byte control of task parameters and results is called for.

The order of execution followed for task execution is as follows:

1. The SerializableTask instance is deserialized from either the original task specification via a TaskSpec or a checkpoint created by a previous invocation of this task.
2. The task is executed via the run method, which is provided a SerializableTaskContext implementation through which the task can communicate with the runtime environment.
3. The stop method may be called to request the run method to exit early, throwing a TaskStoppedException.

The SerializedTask can reference instances of the following types, directly of indirectly as part of its object graph, even though these types may not be formally Serializable:

• TaskContext/SerializedTaskContext. A task context object obtained during task runtime may be included in a checkpoint, and will be replaced during deserialization with a reference to the correct SerializableTaskContext for the new execution environment.
• DataBuffer instances obtained via TaskContext.getDataElement. A reference to the applicable data element will be stored as part of the checkpoint, and the data element contents retrieved again during deserialization; the actual data element contents will not be serialized as part of the checkpoint itself, for improved efficiency.
• DataBuffer instances obtained via TaskContext.createDataBuffer.
• ElementProxy instances created on the client side to refer to particular data elements by their IDs will be augmented with the corresponding data element contents during task execution, without requiring a call to TaskContext.getDataElement. These may also be serialized as part of a checkpoint. In addition, data elements referenced via a DataElementProxy will be marked as "required" by the SerializableTaskSpec during task creation without requiring a call to TaskSpec.addRequiredDataElement.
• SerializableTaskContextProxy instances created on the client side will be modified during task execution to use the correct underlying SerializableTaskContext instances for the current execution environment. These may also be serialized as part of a checkpoint.

See Also:

run(com.parabon.client.SerializableTaskContext), stop(), TaskSpec, SerializableTaskContext

Method Summary

java.io.Serializable	run(SerializableTaskContext context) Execute the task normally, either initially or from a checkpoint.
void	stop() Request that the run method stop gracefully (ideally reporting one last checkpoint) by throwing a com.parabon.runtime.TaskStoppedException.

Method Detail

run

java.io.Serializable run(SerializableTaskContext context)
                         throws java.lang.Exception

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.

Parameters:

context - a SerializableTaskContext implementation through which the task can communicate with the runtime environment, in particular to obtain data elements and report progress, checkpoints, and intermediate results.

Returns:

a Serializable object instance containing the task's final results.

Throws:

java.lang.Exception

stop

void stop()

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.