org.schmant.task.stub
Class AbstractTask<T extends TaskSpecification<T>>

java.lang.Object
  org.schmant.support.AbstractArgumentChecker
      org.schmant.task.stub.AbstractTask<T>

All Implemented Interfaces:

TaskDependency, LoggingConfigurable<T>, Task, TaskRunnable, TaskSpecification<T>

Direct Known Subclasses:

AbstractActionTask, AbstractExtProcessTask, AbstractGeneratorTask, AbstractSvnTask, CompoundTask

public abstract class AbstractTask<T extends TaskSpecification<T>>
extends AbstractArgumentChecker
implements Task, TaskSpecification<T>

This is an abstract base class that task implementations are encouraged to inherit (either directly or through any of this class' subclasses). It implements all run control logic for tasks.

This class implements the run() method defined by the TaskRunnable interface. Subclasses must implement an runInternal(Report) method. They may also choose to override other methods implemented by this class. See the documentation below for details.

This object also implements TaskSpecification, making all inheriting task objects their own specification objects too.

Since:

0.5

Author:

Karl Gustafsson

Constructor Summary

protected

AbstractTask() Create the task.

Method Summary

boolean	cancel(boolean mayInterruptIfRunning) Cancel a task that has not been run or is running.
void	copyProperties(T spec) Copy the properties to the target object.
Task	createTask() Create a task from this specification object.
protected String	getDefaultLogFooter() Get the default log footer to log after the task has been successfully run if no other log footer is set.
protected String	getDefaultLogHeader() Get the default log header to log (to level INFO) before the task is run if the task user has not set a custom header.
TaskDependency	getDependencyForTasksScheduledByThisTask() This implementation returns this.
Observable	getDependencyObservable() Get an Observable that will notify all observers when this task has been run.
Throwable	getFailureCause() If the task failed, this method can be used to retrieve the failure cause.
protected TwoState<String>	getLogFooter() Get the log footer property.
protected TwoState<String>	getLogHeader() Get the log header property.
Lock	getSatisfiedStateLock() Get the Lock that protects the dependency's satisfied property.
protected T	getThis() Get this cast to its actual type.
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	isSatisfied() Is this dependency satisfied?
boolean	isSuccessful() Was the task successful? (I.e: did it not throw an exception?)
Task	run() This method does the following: Validates the task (see validate(Report)) Runs it (see runInternal(Report)) In case of errors from the runInternal(Report) method, this method logs them and rethrows them as SchmantException:s.
protected abstract void	runInternal(Report r) Subclasses implement this.
T	setLogFooter(String s) Set the task's log footer (the message that is logged to level info after the task has completed successfully).
T	setLogHeader(String s) Set the task's log header (the message that is logged to level info before the task is run).
T	setReportLevel(Level l) Set the Report level to use when running tasks created by this factory.
T	setTraceLogging(boolean b) Enable or disable trace logging for tasks created by this factory.
String	toString() Default implementation for tasks.
protected Collection<String>	validate(Report r) This method may be overridden by subclasses to validate their configuration (including their TaskFactory:s) before the task is run.

Methods inherited from class org.schmant.support.AbstractArgumentChecker

check, check, check, check

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractTask

protected AbstractTask()

Create the task.

This is declared protected. Tasks objects should be created from their factories.

Method Detail

getThis

protected final T getThis()

Get this cast to its actual type. This is useful for returning the right type of this when implementing setter methods that return the called object.

Returns:

this cast to its actual type.

getDependencyObservable

public final Observable getDependencyObservable()

Get an Observable that will notify all observers when this task has been run.

Specified by:

getDependencyObservable in interface TaskDependency

Returns:

An Observable to observe.

setLogHeader

public final T setLogHeader(String s)

Description copied from interface: LoggingConfigurable

Set the task's log header (the message that is logged to level info before the task is run). If no log header is set, the default log header from getDefaultLogHeader() is used.

Specified by:

setLogHeader in interface LoggingConfigurable<T extends TaskSpecification<T>>

Parameters:

s - The log header. Set to null to not log a header.

Returns:

this

getLogHeader

protected final TwoState<String> getLogHeader()

Get the log header property.

Returns:

The log header.

setLogFooter

public final T setLogFooter(String s)

Description copied from interface: LoggingConfigurable

Set the task's log footer (the message that is logged to level info after the task has completed successfully). Set to null to disable the footer.

Specified by:

setLogFooter in interface LoggingConfigurable<T extends TaskSpecification<T>>

Parameters:

s - The footer to log.

Returns:

this

getLogFooter

protected final TwoState<String> getLogFooter()

Get the log footer property.

Returns:

The log footer.

setTraceLogging

public final T setTraceLogging(boolean b)

Description copied from interface: LoggingConfigurable

Enable or disable trace logging for tasks created by this factory. Trace logging means that a task's configuration is printed before it is run.

Task configuration is trace logged if trace logging is enabled for the task itself or for its task factory.

Specified by:

setTraceLogging in interface LoggingConfigurable<T extends TaskSpecification<T>>

Parameters:

b - Set to true to enable trace logging.

Returns:

this.

setReportLevel

public final T setReportLevel(Level l)

Description copied from interface: LoggingConfigurable

Set the Report level to use when running tasks created by this factory.

Specified by:

setReportLevel in interface LoggingConfigurable<T extends TaskSpecification<T>>

Parameters:

l - The report level. If null, the report level will not be modified.

Returns:

this.

isDone

public final boolean isDone()

Description copied from interface: Task

Has this task been run?

Specified by:

isDone in interface Task

Returns:

true if this task has been run.

isSuccessful

public final boolean isSuccessful()

Description copied from interface: Task

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

Specified by:

isSuccessful in interface Task

Returns:

true if the task has been successfully run.

isSatisfied

public final boolean isSatisfied()

Description copied from interface: TaskDependency

Is this dependency satisfied?

Implementation note: This method should be protected by the same lock that can be retrieved by calling TaskDependency.getSatisfiedStateLock().

Specified by:

isSatisfied in interface TaskDependency

Returns:

true if the dependency is satisfied.

cancel

public final boolean cancel(boolean mayInterruptIfRunning)

Description copied from interface: Task

Cancel a task that has not been run or is running.

Specified by:

cancel in interface Task

Parameters:

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

isCancelled

public final boolean isCancelled()

Description copied from interface: Task

Is the task canceled?

Specified by:

isCancelled in interface Task

Returns:

true if the task was canceled.

isInterrupted

public final boolean isInterrupted()

Description copied from interface: Task

Was the task interrupted?

Specified by:

isInterrupted in interface Task

Returns:

true if the task was interrupted.

isRunning

public final boolean isRunning()

Description copied from interface: Task

Is the task currently running?

Specified by:

isRunning in interface Task

Returns:

true if the task has been successfully run.

getFailureCause

public final Throwable getFailureCause()

Description copied from interface: Task

If the task failed, this method can be used to retrieve the failure cause.

Specified by:

getFailureCause in interface Task

Returns:

The failure cause.

getSatisfiedStateLock

public final Lock getSatisfiedStateLock()

Description copied from interface: TaskDependency

Get the Lock that protects the dependency's satisfied property. This lock must be locked before the dependency's satisfied state can be update.

An external class can lock this to ensure that the satisfied state is not updated while it holds the lock.

Specified by:

getSatisfiedStateLock in interface TaskDependency

Returns:

The lock used to protect the satisfied state.

See Also:

TaskDependency.isSatisfied()

getDependencyForTasksScheduledByThisTask

public TaskDependency getDependencyForTasksScheduledByThisTask()

This implementation returns this. Subclasses that use TaskExecutor:s must override this method to return a dependency object for all of its scheduled tasks.

Specified by:

getDependencyForTasksScheduledByThisTask in interface Task

Returns:

this

validate

protected Collection<String> validate(Report r)

This method may be overridden by subclasses to validate their configuration (including their TaskFactory:s) before the task is run.

Validation errors are collected as strings. If this method is overridden, always call super.validate.

Parameters:

r - A report to log warning and debug messages to. Validation errors should not be logged, though. They are logged later.

Returns:

A collection of error messages.

getDefaultLogHeader

protected String getDefaultLogHeader()

Get the default log header to log (to level INFO) before the task is run if the task user has not set a custom header. Subclasses may override this to return better headers.

This is called after validating the task.

Return null to disable logging.

Returns:

"Running " + toString()

getDefaultLogFooter

protected String getDefaultLogFooter()

Get the default log footer to log after the task has been successfully run if no other log footer is set. This implementation returns null (= no logging). Subclasses may override this to return something else.

Returns:

null

runInternal

protected abstract void runInternal(Report r)
                             throws Exception

Subclasses implement this. The task is validate(Report):d before this method is called, see run().

Parameters:

r - The current thread's Report.

Throws:

Exception - On errors.

run

public final Task run()

This method does the following:

1. Validates the task (see validate(Report))
2. Runs it (see runInternal(Report))

In case of errors from the runInternal(Report) method, this method logs them and rethrows them as SchmantException:s.

Specified by:

run in interface TaskRunnable

Returns:

The task that was run.

createTask

public final Task createTask()

Description copied from interface: TaskSpecification

Create a task from this specification object.

This method is called by the task factory. After calling this method, the task factory does not modify the specification any more.

Specified by:

createTask in interface TaskSpecification<T extends TaskSpecification<T>>

Returns:

this.

copyProperties

public void copyProperties(T spec)

Copy the properties to the target object.

Subclasses must override this to copy their properties. The overriding method must call super.copyProperties.

Specified by:

copyProperties in interface TaskSpecification<T extends TaskSpecification<T>>

Parameters:

spec - The specification to copy properties to.

toString

public String toString()

Default implementation for tasks. Task implementations may override this. It is used in the default log header that is written (level INFO) before a task is run.

This implementation just returns the class name.

Overrides:

toString in class Object