org.schmant.task
Interface Task

All Superinterfaces:
TaskDependency, TaskRunnable
All Known Subinterfaces:
ExtProcessTask<T>
All Known Implementing Classes:
AbstractActionTask, AbstractAddTextTask, AbstractCallbackRecursiveActionTask, AbstractCallbackRecursiveProcessTask, AbstractExtJavaTask, AbstractExtJvmTask, AbstractExtProcessTask, AbstractGeneratorTask, AbstractJarTask, AbstractJavacTask, AbstractJavadocTask, AbstractJavaZipTask, AbstractLinkInsertionTask, AbstractParseXmlTask, AbstractProcessOneFileTask, AbstractProcessTask, AbstractProxyTask, AbstractSvnCommitTask, AbstractSvnTask, AbstractTask, AbstractTextInsertionTask, AbstractXmlCatalogActionTask, AbstractZipTask, AddSystemIdToCatalogTask, AddUriToCatalogTask, AntTask, ApiLinksTask, ArgumentInterpreterLinksTask, At4JZipTask, BZip2Task, ChmodTask, ClosureTask, CompoundTask, CopyTask, DeleteTask, DomParseXmlTask, EarTask, ErrorIgnoringTask, ExtFindbugsTask, ExtJarSignerTask, ExtJavacTask, ExtJavadocTask, ExtJavaTask, ExtJUnit4Task, ExtProcessTask, ForEachSourceTask, FormatCharacterFileTask, GZipTask, HtmlLinkValidationTask, IncludeFilesTask, JarTask, Jdk6JavacTask, LzmaTask, MoveTask, RecursiveActionTask, RecursiveProcessTask, RedirectReportTask, ReplaceSourceFileTask, SchemaFactoryTask, SchmantTaskrefTask, SvnExportTask, SvnUrlToUrlCopyTask, TarTask, TaskFactoryLinksTask, TemplateCompilerTask, TextAppendTask, TextPrependTask, TextReplaceTask, TimedExecutionTask, TreeCopyTask, TreeDeleteTask, WarTask, XsltTask, ZipTask

public interface Task
extends TaskDependency, TaskRunnable

This is the interface for a Schmant task. It defines task run control methods and methods to query the task about its state. A task may have the following states:

  1. Before running – The task is being configured by its TaskFactory or is waiting for its turn to run in a TaskExecutor.
  2. Running – The task is running.
  3. Successful – The task has been run and it completed without errors.
  4. Failed – The task has been run, but an error occurred.
  5. Canceled – The task was canceled while or before it was running.

The task's internal state (is running? has run? canceled?) is protected by the satisfied state lock defined in TaskDependency. (Tasks that inherit AbstractTask get that for free.)

Some run control methods are inspired by the methods in java.util.concurrent.Future. This class does not extend Future, though, since tasks do not necessarily produce a result.

A Task object is always created by a task-specific TaskFactory. The task factory has setter methods that build scripts can use to configure the task. The setter methods configure a task-specific TaskSpecification object. When the task is configured, the build script calls TaskFactory.create() to create a Task object based on the configured TaskSpecification. (In practice, the Task and the TaskSpecification objects are the same.)

Task objects are always read only.

Some tasks implement the Producer interface. When running one of those tasks, an object is produced that can be retrieved from the Producer.get() method.

All methods in this interface are implemented by AbstractTask. Task implementations are encouraged to inherit that class (or any of its subclasses).

A task implementation is responsible for logging all errors (even Error:s) to its thread's Report.

Tasks are encouraged to implement a good toString method since that is used for error reporting.

Since:
0.5
Author:
Karl Gustafsson

Method Summary
 boolean cancel(boolean mayInterruptIfRunning)
          Cancel a task that has not been run or is running.
 TaskDependency getDependencyForTasksScheduledByThisTask()
          If this task schedules other tasks in a TaskExecutor, this method returns a dependency object that is satisfied when all those tasks have been run.
 Throwable getFailureCause()
          If the task failed, this method can be used to retrieve the failure cause.
 boolean isCancelled()
          Is the task canceled?
 boolean isDone()
          Has this task been run?
 boolean isInterrupted()
          Was the task interrupted?
 boolean isRunning()
          Is the task currently running?
 boolean isSuccessful()
          Was the task successful? (I.e: did it not throw an exception?)
 
Methods inherited from interface org.schmant.run.TaskDependency
getDependencyObservable, getSatisfiedStateLock, isSatisfied
 
Methods inherited from interface org.schmant.task.TaskRunnable
run
 

Method Detail

isDone

boolean isDone()
Has this task been run?

Returns:
true if this task has been run.

cancel

boolean cancel(boolean mayInterruptIfRunning)
Cancel a task that has not been run or is running.

Parameters:
mayInterruptIfRunning - Should the task be interrupted if it is running?

isCancelled

boolean isCancelled()
Is the task canceled?

Returns:
true if the task was canceled.

isSuccessful

boolean isSuccessful()
Was the task successful? (I.e: did it not throw an exception?)

Returns:
true if the task has been successfully run.

isInterrupted

boolean isInterrupted()
Was the task interrupted?

Returns:
true if the task was interrupted.

isRunning

boolean isRunning()
Is the task currently running?

Returns:
true if the task has been successfully run.

getFailureCause

Throwable getFailureCause()
If the task failed, this method can be used to retrieve the failure cause.

Returns:
The failure cause.

getDependencyForTasksScheduledByThisTask

TaskDependency getDependencyForTasksScheduledByThisTask()
If this task schedules other tasks in a TaskExecutor, this method returns a dependency object that is satisfied when all those tasks have been run. If not, the returned dependency object is satisfied when this task has been run.

Returns:
A dependency object for tasks scheduled by this task.