Package org.gradle.tooling

# Interface BuildActionExecuter<T>

Type Parameters:
  `T` - The type of result produced by this executer.

All Superinterfaces:
  `ConfigurableLauncher<BuildActionExecuter<T>>`, `LongRunningOperation`

public interface BuildActionExecuter<T> extends ConfigurableLauncher<BuildActionExecuter<T>>
Used to execute a `BuildAction` in the build process.

Since:
  1.8

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `BuildActionExecuter.Builder`
  Builder for a build action that hooks into different phases of the build.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `BuildActionExecuter<T>`
  `forTasks(Iterable<String> tasks)`
  Specifies the tasks to execute before executing the BuildAction.
  `BuildActionExecuter<T>`
  `forTasks(String... tasks)`
  Specifies the tasks to execute before executing the BuildAction.
  `T`
  `run()`
  Runs the action, blocking until its result is available.
  `void`
  `run(ResultHandler<? super T> handler)`
  Starts executing the action, passing the result to the given handler when complete.
  `void`
  `setStreamedValueListener(StreamedValueListener listener)`
  Sets the listener to use to streamed values sent from the action via `BuildController.send(Object)`.

  ### Methods inherited from interface org.gradle.tooling.ConfigurableLauncher

  `addArguments, addArguments, addJvmArguments, addJvmArguments, addProgressListener, addProgressListener, addProgressListener, addProgressListener, setColorOutput, setEnvironmentVariables, setJavaHome, setJvmArguments, setJvmArguments, setStandardError, setStandardInput, setStandardOutput, withArguments, withArguments, withCancellationToken, withDetailedFailure, withSystemProperties`

- ## Method Details

  - ### setStreamedValueListener

    void setStreamedValueListener(StreamedValueListener listener)
    Sets the listener to use to streamed values sent from the action via `BuildController.send(Object)`. Replaces the current listener.
    Since:
      8.6

  - ### forTasks

    BuildActionExecuter<T> forTasks(String... tasks)

    Specifies the tasks to execute before executing the BuildAction.

    If not configured or a null array, then no tasks will be executed. If an empty array, the default tasks for the build will be executed.

    If the target Gradle version is >=6.8 then you can execute tasks from included builds. You can target tasks from included builds by specifying the task identity path (i.e. `':included-build-name:subproject-name:taskName'`).

    Parameters:
      `tasks` - The paths of the tasks to be executed. Relative paths are evaluated relative to the project for which this launcher was created. An empty list will run the project's default tasks.
    Returns:
      this
    Since:
      3.5

  - ### forTasks

    BuildActionExecuter<T> forTasks(Iterable<String> tasks)

    Specifies the tasks to execute before executing the BuildAction.

    If not configured or a null iterable, then no tasks will be executed. If an empty iterable, the default tasks for the build will be executed.

    If the target Gradle version is >=6.8 then you can execute tasks from included builds. You can target tasks from included builds by specifying the task identity path (i.e. `':included-build-name:subproject-name:taskName'`).

    Parameters:
      `tasks` - The paths of the tasks to be executed. Relative paths are evaluated relative to the project for which this launcher was created. An empty list will run the project's default tasks.
    Returns:
      this
    Since:
      3.5

  - ### run

    T run() throws GradleConnectionException, IllegalStateException
    Runs the action, blocking until its result is available.
    Throws:
      `UnsupportedVersionException` - When the target Gradle version does not support build action execution.
      `UnsupportedOperationConfigurationException` - When the target Gradle version does not support some requested configuration option.
      `UnsupportedBuildArgumentException` - When there is a problem with build arguments provided by `ConfigurableLauncher.withArguments(String...)`.
      `BuildActionFailureException` - When the build action fails with an exception.
      `BuildCancelledException` - When the operation was cancelled before it completed successfully.
      `BuildException` - On some failure executing the Gradle build.
      `GradleConnectionException` - On some other failure using the connection.
      `IllegalStateException` - When the connection has been closed or is closing.
    Since:
      1.8

  - ### run

    void run(ResultHandler<? super T> handler) throws IllegalStateException
    Starts executing the action, passing the result to the given handler when complete. This method returns immediately, and the result is later passed to the given handler's `ResultHandler.onComplete(Object)` method.

    If the operation fails, the handler's `ResultHandler.onFailure(GradleConnectionException)` method is called with the appropriate exception. See `run()` for a description of the various exceptions that the operation may fail with.

    Parameters:
      `handler` - The handler to supply the result to.
    Throws:
      `IllegalStateException` - When the connection has been closed or is closing.
    Since:
      1.8