antliscence/src/main/org/apache/tools/ant/Task.java

/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 */

package org.apache.tools.ant;

import java.io.IOException;
import java.util.Enumeration;

import org.apache.tools.ant.dispatch.DispatchUtils;

/**
 * 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
 */
public abstract class Task extends ProjectComponent {
    // CheckStyle:VisibilityModifier OFF - bc
    /**
     * Target this task belongs to, if any.
     * @deprecated since 1.6.x.
     *             You should not be accessing this variable directly.
     *             Please use the {@link #getOwningTarget()} method.
     */
    protected Target target;

    /**
     * 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.
     * @deprecated since 1.6.x.
     *             You should not be accessing this variable directly.
     *             Please use the {@link #getTaskName()} method.
     */
    protected String taskName;

    /**
     * Type of this task.
     *
     * @deprecated since 1.6.x.
     *             You should not be accessing this variable directly.
     *             Please use the {@link #getTaskType()} method.
     */
    protected String taskType;

    /**
     * Wrapper for this object, used to configure it at runtime.
     *
     * @deprecated since 1.6.x.
     *             You should not be accessing this variable directly.
     *             Please use the {@link #getWrapper()} method.
     */
    protected RuntimeConfigurable wrapper;

    // CheckStyle:VisibilityModifier ON

    /**
     * Whether or not this task is invalid. A task becomes invalid
     * if a conflicting class is specified as the implementation for
     * its type.
     */
    private boolean invalid;

    /**
     * Sets the target container of this task.
     *
     * @param target Target in whose scope this task belongs.
     *               May be <code>null</code>, indicating a top-level task.
     */
    public void setOwningTarget(Target target) {
        this.target = target;
    }

    /**
     * Returns the container target of this task.
     *
     * @return The target containing this task, or <code>null</code> if
     *         this task is a top-level task.
     */
    public Target getOwningTarget() {
        return target;
    }

    /**
     * Sets the name to use in logging messages.
     *
     * @param name The name to use in logging messages.
     *             Should not be <code>null</code>.
     */
    public void setTaskName(String name) {
        this.taskName = name;
    }

    /**
     * Returns the name to use in logging messages.
     *
     * @return the name to use in logging messages.
     */
    public String getTaskName() {
        return taskName;
    }

    /**
     * Sets the name with which the task has been invoked.
     *
     * @param type The name the task has been invoked as.
     *             Should not be <code>null</code>.
     */
    public void setTaskType(String type) {
        this.taskType = type;
    }

    /**
     * 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
     */
    public void init() throws BuildException {
    }

    /**
     * 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 void execute() throws BuildException {
    }

    /**
     * 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.
     */
    public RuntimeConfigurable getRuntimeConfigurableWrapper() {
        if (wrapper == null) {
            wrapper = new RuntimeConfigurable(this, getTaskName());
        }
        return 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 <code>null</code>, in which case the next call
     *                to getRuntimeConfigurableWrapper will generate a new
     *                wrapper.
     */
    public void setRuntimeConfigurableWrapper(RuntimeConfigurable wrapper) {
        this.wrapper = wrapper;
    }

    // TODO: (Jon Skeet) The comment "if it hasn't been done already" may
    // not be strictly true. wrapper.maybeConfigure() won't configure the same
    // attributes/text more than once, but it may well add the children again,
    // unless I've missed something.
    /**
     * 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.
     */
    public void maybeConfigure() throws BuildException {
        if (invalid) {
            getReplacement();
        } else if (wrapper != null) {
            wrapper.maybeConfigure(getProject());
        }
    }

    /**
     * Force the task to be reconfigured from its RuntimeConfigurable.
     */
    public void reconfigure() {
        if (wrapper != null) {
            wrapper.reconfigure(getProject());
        }
    }

    /**
     * Handles output by logging it with the INFO priority.
     *
     * @param output The output to log. Should not be <code>null</code>.
     */
    protected void handleOutput(String output) {
        log(output, Project.MSG_INFO);
    }

    /**
     * Handles output by logging it with the INFO priority.
     *
     * @param output The output to log. Should not be <code>null</code>.
     *
     * @since Ant 1.5.2
     */
    protected void handleFlush(String output) {
        handleOutput(output);
    }

    /**
     * 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
     */
    protected int handleInput(byte[] buffer, int offset, int length)
        throws IOException {
        return getProject().defaultInput(buffer, offset, length);
    }

    /**
     * Handles an error output by logging it with the WARN priority.
     *
     * @param output The error output to log. Should not be <code>null</code>.
     */
    protected void handleErrorOutput(String output) {
        log(output, Project.MSG_WARN);
    }

    /**
     * Handles an error line by logging it with the WARN priority.
     *
     * @param output The error output to log. Should not be <code>null</code>.
     *
     * @since Ant 1.5.2
     */
    protected void handleErrorFlush(String output) {
        handleErrorOutput(output);
    }

    /**
     * Logs a message with the default (INFO) priority.
     *
     * @param msg The message to be logged. Should not be <code>null</code>.
     */
    public void log(String msg) {
        log(msg, Project.MSG_INFO);
    }

    /**
     * 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 <code>null</code>.
     * @param msgLevel The message priority at which this message is to
     *                 be logged.
     */
    public void log(String msg, int msgLevel) {
        if (getProject() == null) {
            super.log(msg, msgLevel);
        } else {
            getProject().log(this, msg, 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 <code>null</code>.
     * @param msgLevel The message priority at which this message is to
     *                 be logged.
     * @since 1.7
     */
    public void log(Throwable t, int msgLevel) {
        if (t != null) {
            log(t.getMessage(), t, 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 <code>null</code>.
     * @param t The exception to be logged. May be <code>null</code>.
     * @param msgLevel The message priority at which this message is to
     *                 be logged.
     * @since 1.7
     */
    public void log(String msg, Throwable t, int msgLevel) {
        if (getProject() == null) {
            super.log(msg, msgLevel);
        } else {
            getProject().log(this, msg, t, msgLevel);
        }
    }

    /**
     * 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.
     */
    public final void perform() {
        if (invalid) {
            UnknownElement ue = getReplacement();
            Task task = ue.getTask();
            task.perform();
        } else {
            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);
            }
        }
    }

    /**
     * Marks this task as invalid. Any further use of this task
     * will go through a replacement with the updated definition.
     */
    final void markInvalid() {
        invalid = true;
    }

    /**
     * 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
     */
    protected final boolean isInvalid() {
        return invalid;
    }

    /**
     * Replacement element used if this task is invalidated.
     */
    private UnknownElement replacement;

    /**
     * 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.
     */
    private UnknownElement getReplacement() {
        if (replacement == null) {
            replacement = new UnknownElement(taskType);
            replacement.setProject(getProject());
            replacement.setTaskType(taskType);
            replacement.setTaskName(taskName);
            replacement.setLocation(getLocation());
            replacement.setOwningTarget(target);
            replacement.setRuntimeConfigurableWrapper(wrapper);
            wrapper.setProxy(replacement);
            replaceChildren(wrapper, replacement);
            target.replaceChild(this, replacement);
            replacement.maybeConfigure();
        }
        return replacement;
    }

    /**
     * Recursively adds an UnknownElement instance for each child
     * element of replacement.
     *
     * @since Ant 1.5.1
     */
    private void replaceChildren(RuntimeConfigurable wrapper,
                                 UnknownElement parentElement) {
        Enumeration<RuntimeConfigurable> e = wrapper.getChildren();
        while (e.hasMoreElements()) {
            RuntimeConfigurable childWrapper = e.nextElement();
            UnknownElement childElement =
                new UnknownElement(childWrapper.getElementTag());
            parentElement.addChild(childElement);
            childElement.setProject(getProject());
            childElement.setRuntimeConfigurableWrapper(childWrapper);
            childWrapper.setProxy(childElement);
            replaceChildren(childWrapper, childElement);
        }
    }

    /**
     * Return the type of task.
     *
     * @return the type of task.
     */
    public String getTaskType() {
        return taskType;
    }

    /**
     * Return the runtime configurable structure for this task.
     *
     * @return the runtime structure for this task.
     */
    protected RuntimeConfigurable getWrapper() {
        return wrapper;
    }

    /**
     * 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
     */
    public final void bindToOwner(Task owner) {
        setProject(owner.getProject());
        setOwningTarget(owner.getOwningTarget());
        setTaskName(owner.getTaskName());
        setDescription(owner.getDescription());
        setLocation(owner.getLocation());
        setTaskType(owner.getTaskType());
    }
}