org.apache.tools.ant

Class Task

public abstract class Task extends ProjectComponent

Base class for all tasks. Use Project.createTask to create a new task instance rather than using this class directly for construction.

See Also: Project

Field Summary
protected Targettarget
Target this task belongs to, if any.
protected StringtaskName
Name of this task to be used for logging purposes.
protected StringtaskType
Type of this task.
protected RuntimeConfigurablewrapper
Wrapper for this object, used to configure it at runtime.
Constructor Summary
Task()
Sole constructor.
Method Summary
voidbindToOwner(Task owner)
Bind a task to another; use this when configuring a newly created task to do work on behalf of another.
voidexecute()
Called by the project to let the task do its work.
TargetgetOwningTarget()
Returns the container target of this task.
RuntimeConfigurablegetRuntimeConfigurableWrapper()
Returns the wrapper used for runtime configuration.
StringgetTaskName()
Returns the name to use in logging messages.
StringgetTaskType()
Return the type of task.
protected RuntimeConfigurablegetWrapper()
Return the runtime configurable structure for this task.
protected voidhandleErrorFlush(String output)
Handles an error line by logging it with the WARN priority.
protected voidhandleErrorOutput(String output)
Handles an error output by logging it with the WARN priority.
protected voidhandleFlush(String output)
Handles output by logging it with the INFO priority.
protected inthandleInput(byte[] buffer, int offset, int length)
Handle an input request by this task.
protected voidhandleOutput(String output)
Handles output by logging it with the INFO priority.
voidinit()
Called by the project to let the task initialize properly.
protected booleanisInvalid()
Has this task been marked invalid?
voidlog(String msg)
Logs a message with the default (INFO) priority.
voidlog(String msg, int msgLevel)
Logs a message with the given priority.
voidlog(Throwable t, int msgLevel)
Logs a message with the given priority.
voidlog(String msg, Throwable t, int msgLevel)
Logs a message with the given priority.
voidmaybeConfigure()
Configures this task - if it hasn't been done already.
voidperform()
Performs this task if it's still valid, or gets a replacement version and performs that otherwise.
voidreconfigure()
Force the task to be reconfigured from its RuntimeConfigurable.
voidsetOwningTarget(Target target)
Sets the target container of this task.
voidsetRuntimeConfigurableWrapper(RuntimeConfigurable wrapper)
Sets the wrapper to be used for runtime configuration.
voidsetTaskName(String name)
Sets the name to use in logging messages.
voidsetTaskType(String type)
Sets the name with which the task has been invoked.

Field Detail

target

protected Target target

Deprecated: since 1.6.x. You should not be accessing this variable directly. Please use the getOwningTarget method.

Target this task belongs to, if any.

taskName

protected String taskName

Deprecated: since 1.6.x. You should not be accessing this variable directly. Please use the getTaskName method.

Name of this task to be used for logging purposes. This defaults to the same as the type, but may be overridden by the user. For instance, the name "java" isn't terribly descriptive for a task used within another task - the outer task code can probably provide a better one.

taskType

protected String taskType

Deprecated: since 1.6.x. You should not be accessing this variable directly. Please use the getTaskType method.

Type of this task.

wrapper

protected RuntimeConfigurable wrapper

Deprecated: since 1.6.x. You should not be accessing this variable directly. Please use the getWrapper method.

Wrapper for this object, used to configure it at runtime.

Constructor Detail

Task

public Task()
Sole constructor.

Method Detail

bindToOwner

public final void bindToOwner(Task owner)
Bind a task to another; use this when configuring a newly created task to do work on behalf of another. Project, OwningTarget, TaskName, Location and Description are all copied Important: this method does not call init. If you are creating a task to delegate work to, call init to initialize it.

Parameters: owner owning target

Since: Ant1.7

execute

public void execute()
Called by the project to let the task do its work. This method may be called more than once, if the task is invoked more than once. For example, if target1 and target2 both depend on target3, then running "ant target1 target2" will run all tasks in target3 twice.

Throws: BuildException if something goes wrong with the build.

getOwningTarget

public Target getOwningTarget()
Returns the container target of this task.

Returns: The target containing this task, or null if this task is a top-level task.

getRuntimeConfigurableWrapper

public RuntimeConfigurable getRuntimeConfigurableWrapper()
Returns the wrapper used for runtime configuration.

Returns: the wrapper used for runtime configuration. This method will generate a new wrapper (and cache it) if one isn't set already.

getTaskName

public String getTaskName()
Returns the name to use in logging messages.

Returns: the name to use in logging messages.

getTaskType

public String getTaskType()
Return the type of task.

Returns: the type of task.

getWrapper

protected RuntimeConfigurable getWrapper()
Return the runtime configurable structure for this task.

Returns: the runtime structure for this task.

handleErrorFlush

protected void handleErrorFlush(String output)
Handles an error line by logging it with the WARN priority.

Parameters: output The error output to log. Should not be null.

Since: Ant 1.5.2

handleErrorOutput

protected void handleErrorOutput(String output)
Handles an error output by logging it with the WARN priority.

Parameters: output The error output to log. Should not be null.

handleFlush

protected void handleFlush(String output)
Handles output by logging it with the INFO priority.

Parameters: output The output to log. Should not be null.

Since: Ant 1.5.2

handleInput

protected int handleInput(byte[] buffer, int offset, int length)
Handle an input request by this task.

Parameters: buffer the buffer into which data is to be read. offset the offset into the buffer at which data is stored. length the amount of data to read.

Returns: the number of bytes read.

Throws: IOException if the data cannot be read.

Since: Ant 1.6

handleOutput

protected void handleOutput(String output)
Handles output by logging it with the INFO priority.

Parameters: output The output to log. Should not be null.

init

public void init()
Called by the project to let the task initialize properly. The default implementation is a no-op.

Throws: BuildException if something goes wrong with the build

isInvalid

protected final boolean isInvalid()
Has this task been marked invalid?

Returns: true if this task is no longer valid. A new task should be configured in this case.

Since: Ant 1.5

log

public void log(String msg)
Logs a message with the default (INFO) priority.

Parameters: msg The message to be logged. Should not be null.

log

public void log(String msg, int msgLevel)
Logs a message with the given priority. This delegates the actual logging to the project.

Parameters: msg The message to be logged. Should not be null. msgLevel The message priority at which this message is to be logged.

log

public void log(Throwable t, int msgLevel)
Logs a message with the given priority. This delegates the actual logging to the project.

Parameters: t The exception to be logged. Should not be null. msgLevel The message priority at which this message is to be logged.

Since: 1.7

log

public void log(String msg, Throwable t, int msgLevel)
Logs a message with the given priority. This delegates the actual logging to the project.

Parameters: msg The message to be logged. Should not be null. t The exception to be logged. May be null. msgLevel The message priority at which this message is to be logged.

Since: 1.7

maybeConfigure

public void maybeConfigure()
Configures this task - if it hasn't been done already. If the task has been invalidated, it is replaced with an UnknownElement task which uses the new definition in the project.

Throws: BuildException if the task cannot be configured.

perform

public final void perform()
Performs this task if it's still valid, or gets a replacement version and performs that otherwise. Performing a task consists of firing a task started event, configuring the task, executing it, and then firing task finished event. If a runtime exception is thrown, the task finished event is still fired, but with the exception as the cause.

reconfigure

public void reconfigure()
Force the task to be reconfigured from its RuntimeConfigurable.

setOwningTarget

public void setOwningTarget(Target target)
Sets the target container of this task.

Parameters: target Target in whose scope this task belongs. May be null, indicating a top-level task.

setRuntimeConfigurableWrapper

public void setRuntimeConfigurableWrapper(RuntimeConfigurable wrapper)
Sets the wrapper to be used for runtime configuration. This method should be used only by the ProjectHelper and Ant internals. It is public to allow helper plugins to operate on tasks, normal tasks should never use it.

Parameters: wrapper The wrapper to be used for runtime configuration. May be null, in which case the next call to getRuntimeConfigurableWrapper will generate a new wrapper.

setTaskName

public void setTaskName(String name)
Sets the name to use in logging messages.

Parameters: name The name to use in logging messages. Should not be null.

setTaskType

public void setTaskType(String type)
Sets the name with which the task has been invoked.

Parameters: type The name the task has been invoked as. Should not be null.