FileDocCategorySizeDatePackage
Task.javaAPI DocApache Ant 1.7015445Wed Dec 13 06:16:24 GMT 2006org.apache.tools.ant

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
Project#createTask

Fields Summary
protected Target
target
Target this task belongs to, if any.
protected String
taskName
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.
protected String
taskType
Type of this task.
protected RuntimeConfigurable
wrapper
Wrapper for this object, used to configure it at runtime.
private boolean
invalid
Whether or not this task is invalid. A task becomes invalid if a conflicting class is specified as the implementation for its type.
private UnknownElement
replacement
Replacement element used if this task is invalidated.
Constructors Summary
public Task()
Sole constructor.

    
Methods Summary
public final voidbindToOwner(org.apache.tools.ant.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 {@link Task#init()}. If you are creating a task to delegate work to, call {@link Task#init()} to initialize it.

param
owner owning target
since
Ant1.7

        setProject(owner.getProject());
        setOwningTarget(owner.getOwningTarget());
        setTaskName(owner.getTaskName());
        setDescription(owner.getDescription());
        setLocation(owner.getLocation());
        setTaskType(owner.getTaskType());
    
public voidexecute()
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.

exception
BuildException if something goes wrong with the build.

    
public TargetgetOwningTarget()
Returns the container target of this task.

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

        return target;
    
private UnknownElementgetReplacement()
Creates an UnknownElement that can be used to replace this task. Once this has been created once, it is cached and returned by future calls.

return
the UnknownElement instance for the new definition of this task.

        if (replacement == null) {
            replacement = new UnknownElement(taskType);
            replacement.setProject(getProject());
            replacement.setTaskType(taskType);
            replacement.setTaskName(taskName);
            replacement.setLocation(location);
            replacement.setOwningTarget(target);
            replacement.setRuntimeConfigurableWrapper(wrapper);
            wrapper.setProxy(replacement);
            replaceChildren(wrapper, replacement);
            target.replaceChild(this, replacement);
            replacement.maybeConfigure();
        }
        return replacement;
    
public RuntimeConfigurablegetRuntimeConfigurableWrapper()
Returns the wrapper used for runtime configuration.

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

        if (wrapper == null) {
            wrapper = new RuntimeConfigurable(this, getTaskName());
        }
        return wrapper;
    
public java.lang.StringgetTaskName()
Returns the name to use in logging messages.

return
the name to use in logging messages.

        return taskName;
    
public java.lang.StringgetTaskType()
Return the type of task.

return
the type of task.

        return taskType;
    
protected RuntimeConfigurablegetWrapper()
Return the runtime configurable structure for this task.

return
the runtime structure for this task.

        return wrapper;
    
protected voidhandleErrorFlush(java.lang.String output)
Handles an error line by logging it with the WARN priority.

param
output The error output to log. Should not be null.
since
Ant 1.5.2

        handleErrorOutput(output);
    
protected voidhandleErrorOutput(java.lang.String output)
Handles an error output by logging it with the WARN priority.

param
output The error output to log. Should not be null.

        log(output, Project.MSG_WARN);
    
protected voidhandleFlush(java.lang.String output)
Handles output by logging it with the INFO priority.

param
output The output to log. Should not be null.
since
Ant 1.5.2

        handleOutput(output);
    
protected inthandleInput(byte[] buffer, int offset, int length)
Handle an input request by this task.

param
buffer the buffer into which data is to be read.
param
offset the offset into the buffer at which data is stored.
param
length the amount of data to read.
return
the number of bytes read.
exception
IOException if the data cannot be read.
since
Ant 1.6

        return getProject().defaultInput(buffer, offset, length);
    
protected voidhandleOutput(java.lang.String output)
Handles output by logging it with the INFO priority.

param
output The output to log. Should not be null.

        log(output, Project.MSG_INFO);
    
public voidinit()
Called by the project to let the task initialize properly. The default implementation is a no-op.

exception
BuildException if something goes wrong with the build

    
protected final booleanisInvalid()
Has this task been marked invalid?

return
true if this task is no longer valid. A new task should be configured in this case.
since
Ant 1.5

        return invalid;
    
public voidlog(java.lang.String msg)
Logs a message with the default (INFO) priority.

param
msg The message to be logged. Should not be null.

        log(msg, Project.MSG_INFO);
    
public voidlog(java.lang.String msg, int msgLevel)
Logs a message with the given priority. This delegates the actual logging to the project.

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

        if (getProject() != null) {
            getProject().log(this, msg, msgLevel);
        } else {
            super.log(msg, msgLevel);
        }
    
public voidlog(java.lang.Throwable t, int msgLevel)
Logs a message with the given priority. This delegates the actual logging to the project.

param
t The exception to be logged. Should not be null.
param
msgLevel The message priority at which this message is to be logged.
since
1.7

        if (t != null) {
            log(t.getMessage(), t, msgLevel);
        }
    
public voidlog(java.lang.String msg, java.lang.Throwable t, int msgLevel)
Logs a message with the given priority. This delegates the actual logging to the project.

param
msg The message to be logged. Should not be null.
param
t The exception to be logged. May be null.
param
msgLevel The message priority at which this message is to be logged.
since
1.7

        if (getProject() != null) {
            getProject().log(this, msg, t, msgLevel);
        } else {
            super.log(msg, msgLevel);
        }
    
final voidmarkInvalid()
Marks this task as invalid. Any further use of this task will go through a replacement with the updated definition.

        invalid = true;
    
public voidmaybeConfigure()
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.

exception
BuildException if the task cannot be configured.

        if (!invalid) {
            if (wrapper != null) {
                wrapper.maybeConfigure(getProject());
            }
        } else {
            getReplacement();
        }
    
public final voidperform()
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.

        if (!invalid) {
            getProject().fireTaskStarted(this);
            Throwable reason = null;
            try {
                maybeConfigure();
                DispatchUtils.execute(this);
            } catch (BuildException ex) {
                if (ex.getLocation() == Location.UNKNOWN_LOCATION) {
                    ex.setLocation(getLocation());
                }
                reason = ex;
                throw ex;
            } catch (Exception ex) {
                reason = ex;
                BuildException be = new BuildException(ex);
                be.setLocation(getLocation());
                throw be;
            } catch (Error ex) {
                reason = ex;
                throw ex;
            } finally {
                getProject().fireTaskFinished(this, reason);
            }
        } else {
            UnknownElement ue = getReplacement();
            Task task = ue.getTask();
            task.perform();
        }
    
public voidreconfigure()
Force the task to be reconfigured from its RuntimeConfigurable.

        if (wrapper != null) {
            wrapper.reconfigure(getProject());
        }
    
private voidreplaceChildren(RuntimeConfigurable wrapper, UnknownElement parentElement)
Recursively adds an UnknownElement instance for each child element of replacement.

since
Ant 1.5.1

        Enumeration e = wrapper.getChildren();
        while (e.hasMoreElements()) {
            RuntimeConfigurable childWrapper =
                (RuntimeConfigurable) e.nextElement();
            UnknownElement childElement =
                new UnknownElement(childWrapper.getElementTag());
            parentElement.addChild(childElement);
            childElement.setProject(getProject());
            childElement.setRuntimeConfigurableWrapper(childWrapper);
            childWrapper.setProxy(childElement);
            replaceChildren(childWrapper, childElement);
        }
    
public voidsetOwningTarget(Target target)
Sets the target container of this task.

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

        this.target = target;
    
public voidsetRuntimeConfigurableWrapper(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.

param
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.

        this.wrapper = wrapper;
    
public voidsetTaskName(java.lang.String name)
Sets the name to use in logging messages.

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

        this.taskName = name;
    
public voidsetTaskType(java.lang.String type)
Sets the name with which the task has been invoked.

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

        this.taskType = type;