All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.gradle.api.Task Maven / Gradle / Ivy

Go to download

Gradle 6.5 API redistribution.

There is a newer version: 8.6
Show newest version
/*
 * Copyright 2010 the original author or authors.
 *
 * Licensed 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.gradle.api;

import groovy.lang.Closure;
import groovy.lang.MissingPropertyException;
import org.gradle.api.logging.Logger;
import org.gradle.api.logging.LoggingManager;
import org.gradle.api.plugins.Convention;
import org.gradle.api.plugins.ExtensionAware;
import org.gradle.api.provider.Property;
import org.gradle.api.provider.Provider;
import org.gradle.api.services.BuildService;
import org.gradle.api.specs.Spec;
import org.gradle.api.tasks.Internal;
import org.gradle.api.tasks.Optional;
import org.gradle.api.tasks.TaskDependency;
import org.gradle.api.tasks.TaskDestroyables;
import org.gradle.api.tasks.TaskInputs;
import org.gradle.api.tasks.TaskLocalState;
import org.gradle.api.tasks.TaskOutputs;
import org.gradle.api.tasks.TaskState;

import javax.annotation.Nullable;
import java.io.File;
import java.time.Duration;
import java.util.List;
import java.util.Set;

/**
 * 
A Task represents a single atomic piece of work for a build, such as compiling classes or generating
 * javadoc.

 *
 * 
Each task belongs to a {@link Project}. You can use the various methods on {@link
 * org.gradle.api.tasks.TaskContainer} to create and lookup task instances. For example, {@link
 * org.gradle.api.tasks.TaskContainer#create(String)} creates an empty task with the given name. You can also use the
 * {@code task} keyword in your build file: 

 * 
 * task myTask
 * task myTask { configure closure }
 * task myTask(type: SomeType)
 * task myTask(type: SomeType) { configure closure }
 * 

 *
 * 
Each task has a name, which can be used to refer to the task within its owning project, and a fully qualified
 * path, which is unique across all tasks in all projects. The path is the concatenation of the owning project's path
 * and the task's name. Path elements are separated using the {@value org.gradle.api.Project#PATH_SEPARATOR}
 * character.

 *
 * 
Task Actions

 *
 * 
A Task is made up of a sequence of {@link Action} objects. When the task is executed, each of the
 * actions is executed in turn, by calling {@link Action#execute}. You can add actions to a task by calling {@link
 * #doFirst(Action)} or {@link #doLast(Action)}.

 *
 * 
Groovy closures can also be used to provide a task action. When the action is executed, the closure is called with
 * the task as parameter.  You can add action closures to a task by calling {@link #doFirst(groovy.lang.Closure)} or
 * {@link #doLast(groovy.lang.Closure)}.

 *
 * 
There are 2 special exceptions which a task action can throw to abort execution and continue without failing the
 * build. A task action can abort execution of the action and continue to the next action of the task by throwing a
 * {@link org.gradle.api.tasks.StopActionException}. A task action can abort execution of the task and continue to the
 * next task by throwing a {@link org.gradle.api.tasks.StopExecutionException}. Using these exceptions allows you to
 * have precondition actions which skip execution of the task, or part of the task, if not true.

 *
 * 
Task Dependencies and Task Ordering

 *
 * 
A task may have dependencies on other tasks or might be scheduled to always run after another task.
 * Gradle ensures that all task dependencies and ordering rules are honored when executing tasks, so that the task is executed after
 * all of its dependencies and any "must run after" tasks have been executed.

 *
 * 
Dependencies to a task are controlled using {@link #dependsOn(Object...)} or {@link #setDependsOn(Iterable)},
 * and {@link #mustRunAfter(Object...)}, {@link #setMustRunAfter(Iterable)}, {@link #shouldRunAfter(Object...)} and
 * {@link #setShouldRunAfter(Iterable)} are used to specify ordering between tasks. You can use objects of any of
 * the following types to specify dependencies and ordering:

 *
 * 
    
 *
 * 
  • A {@code String}, {@code CharSequence} or {@code groovy.lang.GString} task path or name. A relative path is interpreted relative to the task's {@link Project}. This
 * allows you to refer to tasks in other projects.
    • 
 *
 * 
  • A {@link Task}.
    • 
 *
 * 
  • A {@link TaskDependency} object.
    • 
 *
 * 
  • A {@link org.gradle.api.tasks.TaskReference} object.
    • 
 *
 * 
  • A {@link Buildable} object.
    • 
 *
 * 
  • A {@link org.gradle.api.file.RegularFileProperty} or {@link org.gradle.api.file.DirectoryProperty}.
    • 
 *
 * 
  • A {@link Provider} object. May contain any of the types listed here.
    • 
 *
 * 
  • A {@code Iterable}, {@code Collection}, {@code Map} or array. May contain any of the types listed here. The elements of the
 * iterable/collection/map/array are recursively converted to tasks.
    • 
 *
 * 
  • A {@code Callable}. The {@code call()} method may return any of the types listed here. Its return value is
 * recursively converted to tasks. A {@code null} return value is treated as an empty collection.
    • 
 *
 * 
  • A Groovy {@code Closure} or Kotlin function. The closure may take a {@code Task} as parameter. 
 * The closure or function may return any of the types listed here. Its return value is
 * recursively converted to tasks. A {@code null} return value is treated as an empty collection.
    • 
 *
 * 
  • Anything else is treated as an error.
    • 
 *
 * 

 *
 * 
Using a Task in a Build File

 *
 *  
Dynamic Properties

 *
 * 
A {@code Task} has 4 'scopes' for properties. You can access these properties by name from the build file or by
 * calling the {@link #property(String)} method. You can change the value of these properties by calling the {@link #setProperty(String, Object)} method.

 *
 * 
    
 *
 * 
  • The {@code Task} object itself. This includes any property getters and setters declared by the {@code Task}
 * implementation class.  The properties of this scope are readable or writable based on the presence of the
 * corresponding getter and setter methods.
    • 
 *
 * 
  • The extensions added to the task by plugins. Each extension is available as a read-only property with the same
 * name as the extension.
    • 
 *
 * 
  • The convention properties added to the task by plugins. A plugin can add properties and methods to a task through
 * the task's {@link Convention} object.  The properties of this scope may be readable or writable, depending on the convention objects.
    • 
 *
 * 
  • The extra properties of the task. Each task object maintains a map of additional properties. These
 * are arbitrary name -> value pairs which you can use to dynamically add properties to a task object.  Once defined, the properties
 * of this scope are readable and writable.
    • 
 *
 * 

 *
 * 
Dynamic Methods

 *
 * 
A {@link Plugin} may add methods to a {@code Task} using its {@link Convention} object.

 *
 * 
Parallel Execution

 * 

 * By default, tasks are not executed in parallel unless a task is waiting on asynchronous work and another task (which
 * is not dependent) is ready to execute.
 *
 * Parallel execution can be enabled by the --parallel flag when the build is initiated.
 * In parallel mode, the tasks of different projects (i.e. in a multi project build) are able to be executed in parallel.
 */
public interface Task extends Comparable, ExtensionAware {
    String TASK_NAME = "name";

    String TASK_DESCRIPTION = "description";

    String TASK_GROUP = "group";

    String TASK_TYPE = "type";

    String TASK_DEPENDS_ON = "dependsOn";

    String TASK_OVERWRITE = "overwrite";

    String TASK_ACTION = "action";

    /**
     * Constructor arguments for the Task
     *
     * @since 4.7
     */
    String TASK_CONSTRUCTOR_ARGS = "constructorArgs";

    /**
     * 
Returns the name of this task. The name uniquely identifies the task within its {@link Project}.

     *
     * @return The name of the task. Never returns null.
     */
    @Internal
    String getName();

    /**
     * A {@link org.gradle.api.Namer} namer for tasks that returns {@link #getName()}.
     */
    class Namer implements org.gradle.api.Namer {
        @Override
        public String determineName(Task c) {
            return c.getName();
        }
    }

    /**
     * 
Returns the {@link Project} which this task belongs to.

     *
     * @return The project this task belongs to. Never returns null.
     */
    @Internal
    Project getProject();

    /**
     * 
Returns the sequence of {@link Action} objects which will be executed by this task, in the order of
     * execution.

     *
     * @return The task actions in the order they are executed. Returns an empty list if this task has no actions.
     */
    @Internal
    List> getActions();

    /**
     * 
Sets the sequence of {@link Action} objects which will be executed by this task.

     *
     * @param actions The actions.
     */
    void setActions(List> actions);

    /**
     * 
Returns a {@link TaskDependency} which contains all the tasks that this task depends on.

     *
     * @return The dependencies of this task. Never returns null.
     */
    @Internal
    TaskDependency getTaskDependencies();

    /**
     * 
Returns the dependencies of this task.

     *
     * @return The dependencies of this task. Returns an empty set if this task has no dependencies.
     */
    @Internal
    Set getDependsOn();

    /**
     * 
Sets the dependencies of this task. See here for a description of the types of
     * objects which can be used as task dependencies.

     *
     * @param dependsOnTasks The set of task paths.
     */
    void setDependsOn(Iterable dependsOnTasks);

    /**
     * 
Adds the given dependencies to this task. See here for a description of the types
     * of objects which can be used as task dependencies.

     *
     * @param paths The dependencies to add to this task.
     *
     * @return the task object this method is applied to
     */
    Task dependsOn(Object... paths);

    /**
     * 
Execute the task only if the given closure returns true.  The closure will be evaluated at task execution
     * time, not during configuration.  The closure will be passed a single parameter, this task. If the closure returns
     * false, the task will be skipped.

     *
     * 
You may add multiple such predicates. The task is skipped if any of the predicates return false.

     *
     * 
Typical usage:myTask.onlyIf { isProductionEnvironment() }

     *
     * @param onlyIfClosure code to execute to determine if task should be run
     */
    void onlyIf(Closure onlyIfClosure);

    /**
     * 
Execute the task only if the given spec is satisfied. The spec will be evaluated at task execution time, not
     * during configuration. If the Spec is not satisfied, the task will be skipped.

     *
     * 
You may add multiple such predicates. The task is skipped if any of the predicates return false.

     *
     * 
Typical usage (from Java):

     * 
myTask.onlyIf(new Spec<Task>() {
     *    boolean isSatisfiedBy(Task task) {
     *       return isProductionEnvironment();
     *    }
     * });
     * 

     *
     * @param onlyIfSpec specifies if a task should be run
     */
    void onlyIf(Spec onlyIfSpec);

    /**
     * 
Execute the task only if the given closure returns true.  The closure will be evaluated at task execution
     * time, not during configuration.  The closure will be passed a single parameter, this task. If the closure returns
     * false, the task will be skipped.

     *
     * 
The given predicate replaces all such predicates for this task.

     *
     * @param onlyIfClosure code to execute to determine if task should be run
     */
    void setOnlyIf(Closure onlyIfClosure);

    /**
     * 
Execute the task only if the given spec is satisfied. The spec will be evaluated at task execution time, not
     * during configuration. If the Spec is not satisfied, the task will be skipped.

     *
     * 
The given predicate replaces all such predicates for this task.

     *
     * @param onlyIfSpec specifies if a task should be run
     */
    void setOnlyIf(Spec onlyIfSpec);

    /**
     * Returns the execution state of this task. This provides information about the execution of this task, such as
     * whether it has executed, been skipped, has failed, etc.
     *
     * @return The execution state of this task. Never returns null.
     */
    @Internal
    TaskState getState();

    /**
     * Sets whether the task actually did any work.  Most built-in tasks will set this automatically, but
     * it may be useful to manually indicate this for custom user tasks.
     * @param didWork indicates if the task did any work
     */
    void setDidWork(boolean didWork);

    /**
     * 
Checks if the task actually did any work.  Even if a Task executes, it may determine that it has nothing to
     * do.  For example, a compilation task may determine that source files have not changed since the last time a the
     * task was run.

     *
     * @return true if this task did any work
     */
    @Internal
    boolean getDidWork();

    /**
     * 
Returns the path of the task, which is a fully qualified name for the task. The path of a task is the path of
     * its {@link Project} plus the name of the task, separated by :.

     *
     * @return the path of the task, which is equal to the path of the project plus the name of the task.
     */
    @Internal
    String getPath();

    /**
     * 
Adds the given {@link Action} to the beginning of this task's action list.

     *
     * @param action The action to add
     * @return the task object this method is applied to
     */
    Task doFirst(Action action);

    /**
     * 
Adds the given closure to the beginning of this task's action list. The closure is passed this task as a
     * parameter when executed.

     *
     * @param action The action closure to execute.
     * @return This task.
     */
    Task doFirst(Closure action);

    /**
     * 
Adds the given {@link Action} to the beginning of this task's action list.

     *
     * @param actionName An arbitrary string that is used for logging.
     * @param action The action to add
     * @return the task object this method is applied to
     *
     * @since 4.2
     */
    Task doFirst(String actionName, Action action);

    /**
     * 
Adds the given {@link Action} to the end of this task's action list.

     *
     * @param action The action to add.
     * @return the task object this method is applied to
     */
    Task doLast(Action action);

    /**
     * 
Adds the given {@link Action} to the end of this task's action list.

     *
     * @param actionName An arbitrary string that is used for logging.
     * @param action The action to add.
     * @return the task object this method is applied to
     *
     * @since 4.2
     */
    Task doLast(String actionName, Action action);

    /**
     * 
Adds the given closure to the end of this task's action list.  The closure is passed this task as a parameter
     * when executed.

     *
     * @param action The action closure to execute.
     * @return This task.
     */
    Task doLast(Closure action);

    /**
     * 
Returns if this task is enabled or not.

     *
     * @see #setEnabled(boolean)
     */
    @Internal
    boolean getEnabled();

    /**
     * 
Set the enabled state of a task. If a task is disabled none of the its actions are executed. Note that
     * disabling a task does not prevent the execution of the tasks which this task depends on.

     *
     * @param enabled The enabled state of this task (true or false)
     */
    void setEnabled(boolean enabled);

    /**
     * 
Applies the statements of the closure against this task object. The delegate object for the closure is set to
     * this task.

     *
     * @param configureClosure The closure to be applied (can be null).
     * @return This task
     */
    Task configure(Closure configureClosure);

    /**
     * 
Returns the AntBuilder for this task.  You can use this in your build file to execute ant
     * tasks.

     *
     * @return The AntBuilder
     */
    @Internal
    AntBuilder getAnt();

    /**
     * 
Returns the logger for this task. You can use this in your build file to write log messages.

     *
     * @return The logger. Never returns null.
     */
    @Internal
    Logger getLogger();

    /**
     * Returns the {@link org.gradle.api.logging.LoggingManager} which can be used to receive logging and to control the
     * standard output/error capture for this task. By default, System.out is redirected to the Gradle logging system at
     * the QUIET log level, and System.err is redirected at the ERROR log level.
     *
     * @return the LoggingManager. Never returns null.
     */
    @Internal
    LoggingManager getLogging();

    /**
     * 
Returns the value of the given property of this task.  This method locates a property as follows:

     *
     * 
    
     *
     * 
  1. If this task object has a property with the given name, return the value of the property.
    2. 
     *
     * 
  2. If this task has an extension with the given name, return the extension. 
    3. 
     *
     * 
  3. If this task's convention object has a property with the given name, return the value of the property.
    4. 
     *
     * 
  4. If this task has an extra property with the given name, return the value of the property.
    5. 
     *
     * 
  5. If not found, throw {@link MissingPropertyException}
    6. 
     *
     * 

     *
     * @param propertyName The name of the property.
     * @return The value of the property, possibly null.
     * @throws MissingPropertyException When the given property is unknown.
     */
    @Nullable
    Object property(String propertyName) throws MissingPropertyException;

    /**
     * 
Determines if this task has the given property. See here for details of the
     * properties which are available for a task.

     *
     * @param propertyName The name of the property to locate.
     * @return True if this project has the given property, false otherwise.
     */
    boolean hasProperty(String propertyName);

    /**
     * 
Sets a property of this task.  This method searches for a property with the given name in the following
     * locations, and sets the property on the first location where it finds the property.

     *
     * 
    
     *
     * 
  1. The task object itself.  For example, the enabled project property.
    2. 
     *
     * 
  2. The task's convention object.
    3. 
     *
     * 
  3. The task's extra properties.
    4. 
     *
     * 

     *
     * If the property is not found, a {@link groovy.lang.MissingPropertyException} is thrown.
     *
     * @param name The name of the property
     * @param value The value of the property
     */
    void setProperty(String name, Object value) throws MissingPropertyException;

    /**
     * 
Returns the {@link Convention} object for this task. A {@link Plugin} can use the convention object to
     * contribute properties and methods to this task.

     *
     * @return The convention object. Never returns null.
     */
    @Internal
    Convention getConvention();

    /**
     * Returns the description of this task.
     *
     * @return the description. May return null.
     */
    @Internal
    @Nullable
    String getDescription();

    /**
     * Sets a description for this task. This should describe what the task does to the user of the build. The
     * description will be displayed when gradle tasks is called.
     *
     * @param description The description of the task. Might be null.
     */
    void setDescription(@Nullable String description);

    /**
     * Returns the task group which this task belongs to. The task group is used in reports and user interfaces to
     * group related tasks together when presenting a list of tasks to the user.
     *
     * @return The task group for this task. Might be null.
     */
    @Internal
    @Nullable
    String getGroup();

    /**
     * Sets the task group which this task belongs to. The task group is used in reports and user interfaces to
     * group related tasks together when presenting a list of tasks to the user.
     *
     * @param group The task group for this task. Can be null.
     */
    void setGroup(@Nullable String group);

    /**
     * 
Returns the inputs of this task.

     *
     * @return The inputs. Never returns null.
     */
    @Internal
    TaskInputs getInputs();

    /**
     * 
Returns the outputs of this task.

     *
     * @return The outputs. Never returns null.
     */
    @Internal
    TaskOutputs getOutputs();

    /**
     * 
Returns the destroyables of this task.

     * @return The destroyables.  Never returns null.
     *
     * @since 4.0
     */
    @Internal
    TaskDestroyables getDestroyables();

    /**
     * Returns the local state of this task.
     *
     * @since 4.3
     */
    @Internal
    TaskLocalState getLocalState();

    /**
     * 
Returns a directory which this task can use to write temporary files to. Each task instance is provided with a
     * separate temporary directory. There are no guarantees that the contents of this directory will be kept beyond the
     * execution of the task.

     *
     * @return The directory. Never returns null. The directory will already exist.
     */
    @Internal
    File getTemporaryDir();

    /**
     * 
Specifies that this task must run after all of the supplied tasks.

     *
     * 
     * task taskY {
     *     mustRunAfter "taskX"
     * }
     * 

     *
     * 
For each supplied task, this action adds a task 'ordering', and does not specify a 'dependency' between the tasks.
     * As such, it is still possible to execute 'taskY' without first executing the 'taskX' in the example.

     *
     * 
See here for a description of the types of objects which can be used to specify
     * an ordering relationship.

     *
     * @param paths The tasks this task must run after.
     *
     * @return the task object this method is applied to
     */
    Task mustRunAfter(Object... paths);

    /**
     * 
Specifies the set of tasks that this task must run after.

     *
     * 
     * task taskY {
     *     mustRunAfter = ["taskX1", "taskX2"]
     * }
     * 

     *
     * 
For each supplied task, this action adds a task 'ordering', and does not specify a 'dependency' between the tasks.
     * As such, it is still possible to execute 'taskY' without first executing the 'taskX' in the example.

     *
     * 
See here for a description of the types of objects which can be used to specify
     * an ordering relationship.

     *
     * @param mustRunAfter The set of task paths this task must run after.
     */
    void setMustRunAfter(Iterable mustRunAfter);

    /**
     * 
Returns tasks that this task must run after.

     *
     * @return The tasks that this task must run after. Returns an empty set if this task has no tasks it must run after.
     */
    @Internal
    TaskDependency getMustRunAfter();

    /**
     * 
Adds the given finalizer tasks for this task.

     *
     * 
     * task taskY {
     *     finalizedBy "taskX"
     * }
     * 

     *
     * 
See here for a description of the types of objects which can be used to specify
     * a finalizer task.

     *
     * @param paths The tasks that finalize this task.
     *
     * @return the task object this method is applied to
     */
    Task finalizedBy(Object... paths);

    /**
     * 
Specifies the set of finalizer tasks for this task.

     *
     * 
     * task taskY {
     *     finalizedBy = ["taskX1", "taskX2"]
     * }
     * 

     *
     * 
See here for a description of the types of objects which can be used to specify
     * a finalizer task.

     *
     * @param finalizedBy The tasks that finalize this task.
     */
    void setFinalizedBy(Iterable finalizedBy);

    /**
     * 
Returns tasks that finalize this task.

     *
     * @return The tasks that finalize this task. Returns an empty set if there are no finalising tasks for this task.
     */
    @Internal
    TaskDependency getFinalizedBy();

    /**
     * 
Specifies that this task should run after all of the supplied tasks.

     *
     * 
     * task taskY {
     *     shouldRunAfter "taskX"
     * }
     * 

     *
     * 
For each supplied task, this action adds a task 'ordering', and does not specify a 'dependency' between the tasks.
     * As such, it is still possible to execute 'taskY' without first executing the 'taskX' in the example.

     *
     * 
See here for a description of the types of objects which can be used to specify
     * an ordering relationship.

     *
     * @param paths The tasks this task should run after.
     *
     * @return the task object this method is applied to
     */
    TaskDependency shouldRunAfter(Object... paths);

    /**
     * 
Specifies the set of tasks that this task should run after.

     *
     * 
     * task taskY {
     *     shouldRunAfter = ["taskX1", "taskX2"]
     * }
     * 

     *
     * 
For each supplied task, this action adds a task 'ordering', and does not specify a 'dependency' between the tasks.
     * As such, it is still possible to execute 'taskY' without first executing the 'taskX' in the example.

     *
     * 
See here for a description of the types of objects which can be used to specify
     * an ordering relationship.

     *
     * @param shouldRunAfter The set of task paths this task should run after.
     */
    void setShouldRunAfter(Iterable shouldRunAfter);

    /**
     * 
Returns tasks that this task should run after.

     *
     * @return The tasks that this task should run after. Returns an empty set if this task has no tasks it must run after.
     */
    @Internal
    TaskDependency getShouldRunAfter();

    /**
     * 
The timeout of this task.

     *
     * 
     *   task myTask {
     *       timeout = Duration.ofMinutes(10)
     *   }
     * 

     *
     * 

     * The Thread executing this task will be interrupted if the task takes longer than the specified amount of time to run.
     * In order for a task to work properly with this feature, it needs to react to interrupts and must clean up any resources it opened.
     * 

     * 
By default, tasks never time out.

     *
     * @since 5.0
     */
    @Internal
    @Optional
    @Incubating
    Property getTimeout();

    /**
     * Registers a {@link BuildService} that is used by this task.
     *
     * @param service The service provider.
     * @since 6.1
     */
    @Incubating
    void usesService(Provider> service);
}
 















© 2015 - 2024 Weber Informatics LLC | Privacy Policy