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:

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.