org.jtrim2.taskgraph.TaskGraphExecutor Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jtrim-task-graph Show documentation
JTrim Task Graph
There is a newer version: 2.0.7
package org.jtrim2.taskgraph;

import java.util.concurrent.CompletionStage;
import org.jtrim2.cancel.CancellationToken;

/**
 * Defines a executor which executes an already built task execution graph. It is not required
 * that the graph is already physically built before prior calling the {@code execute} method.
 * However, a particular instance of {@code TaskGraphExecutor} always implies an actual graph
 * (even if it was not built yet) to be executed.
 * 
 * It is possible to declare some nodes whose output are to be passed to the
 * {@code CompletionStage} of the task graph execution via the {@link #properties() properties()}
 * of the {@code TaskGraphExecutor}.
 *
 * 
Thread safety
 * The methods of this class are not expected to be callable from multiple threads concurrently.
 *
 * Synchronization transparency
 * The methods of this class are not required to be synchronization transparent.
 *
 * @see TaskGraphExecutors
 */
public interface TaskGraphExecutor {
    /**
     * Returns the properties used for executing the task graph. The properties must be set
     * before calling the {@link #execute(CancellationToken) execute} method.
     *
     * @return the properties used for executing the task graph. This method never returns
     *   {@code null}.
     */
    public TaskGraphExecutorProperties.Builder properties();

    /**
     * Starts executing the associated task graph and will notify the returned {@code CompletionStage}
     * once task execution terminates.
     * 
     * If the {@link TaskGraphExecutorProperties#isDeliverResultOnFailure() deliverResultOnFailure}
     * property is {@code true}, the {@code CompletionStage} will never be completed exceptionally.
     * However, if it is {@code false}, the possible exceptional results are:
     * 

     *  {@link TaskGraphExecutionException}: At least one node failed with an exception.
     *  
     *   {@link org.jtrim2.cancel.OperationCanceledException OperationCanceledException}:
     *   The execution was canceled before it could have been completed and no nodes failed
     *   with an unexpected exception (i.e., not {@code OperationCanceledException}).
     *  
     *  
     *   Any other exception: When some unexpected issues prevented the task graph execution
     *   to complete.
     *  
     * //TaskGraphExecutionException
     *
     * @param cancelToken the {@code CancellationToken} which can be used to cancel the execution
     *   of the task graph. The framework will make a best effort to cancel the execution.
     *   However, there is no guarantee that cancellation request will be fulfilled. If cancellation succeeds,
     *   the {@code CompletionStage} will complete exceptionally with an
     *   {@link org.jtrim2.cancel.OperationCanceledException OperationCanceledException}.
     * @return the {@code CompletionStage} which is notified whenever the task graph execution terminates
     *   (normally or abnormally). This method never returns {@code null}.
     */
    public CompletionStage execute(CancellationToken cancelToken);
}