com.parabon.runtime
Interface Task

All Known Implementing Classes:
SerializableTaskWrapper

public interface Task

The Task interface is the central abstraction used to execute a single task. A task intended to run on a provider must provide a central class which extends the Task interface, and must further have a public constructor which required no arguments.

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

  1. An instance of the task's central, or entry-point, class is created. This class must implement the Task interface, and must have a public no-arg constructor.
  2. The task is executed via the run method, which is provided both a TaskContext implementation through which the task can communicate with the runtime environment and a DataBuffer containing task parameters, either those specified initially by the client application via a TaskSpec or else the contents of a checkpoint created by a previous invocation of this task.
  3. The stop method may be called to request the run method to exit early, throwing a TaskStoppedException.

See Also:
run(com.parabon.runtime.TaskContext, com.parabon.runtime.DataBuffer), stop(), TaskSpec, TaskContext

Method Summary
 DataBuffer run(TaskContext context, DataBuffer parameters)
          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

DataBuffer run(TaskContext context,
               DataBuffer parameters)
               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 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

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.

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.

See Also:
TaskContext.shouldStop()