api / org.gradle.tooling

Package org.gradle.tooling



interface BuildAction<T : Any> : Serializable

An action that executes against a Gradle build and produces a result of type T.

You can execute a BuildAction using the ProjectConnection#action(BuildAction) method.


interface BuildActionExecuter<T : Any> : ConfigurableLauncher<BuildActionExecuter<T>>

Used to execute a BuildAction in the build process.


interface BuildController

Provides a BuildAction various ways to control a Gradle build and access information about the build.


interface BuildLauncher : ConfigurableLauncher<BuildLauncher>

A BuildLauncher allows you to configure and execute a Gradle build.

Instances of BuildLauncher are not thread-safe. You use a BuildLauncher as follows:

 ProjectConnection connection = GradleConnector.newConnector() .forProjectDirectory(new File("someFolder")) .connect(); try { BuildLauncher build = connection.newBuild(); //select tasks to run: build.forTasks("clean", "test"); //include some build arguments: build.withArguments("-i", "--project-dir", "someProjectDir"); //configure the standard input: build.setStandardInput(new ByteArrayInputStream("consume this!".getBytes())); //in case you want the build to use java different than default: build.setJavaHome(new File("/path/to/java")); //if your build needs crazy amounts of memory: build.setJvmArguments("-Xmx2048m", "-XX:MaxPermSize=512m"); //if you want to listen to the progress events: ProgressListener listener = null; // use your implementation build.addProgressListener(listener); //kick the build off: build.run(); } finally { connection.close(); } 


interface CancellationToken

Token that propagates notification that an operation should be cancelled. See org.gradle.tooling.CancellationTokenSource for details.

All implementations of this interface are required to be thread safe.


interface CancellationTokenSource

A CancellationTokenSource allows you to issue cancellation requests to one or more org.gradle.tooling.LongRunningOperation instances. To use a token source:

All implementations of this interface are required to be thread safe.


interface ConfigurableLauncher<T : ConfigurableLauncher<ConfigurableLauncher<*>>> : LongRunningOperation

A ConfigurableLauncher allows you to configure a long running operation.


interface Failure

Represents a failure. Failures are similar to exceptions but carry less information (only a message, a description and a cause) so they can be used in a wider scope than just the JVM where the exception failed.


abstract class GradleConnector

A GradleConnector is the main entry point to the Gradle tooling API. You use this API as follows:

  1. Call #newConnector() to create a new connector instance.
  2. Configure the connector. You must call #forProjectDirectory(java.io.File) to specify which project you wish to connect to. Other methods are optional.
  3. Call #connect() to create the connection to a project.
  4. When finished with the connection, call ProjectConnection#close() to clean up.


 ProjectConnection connection = GradleConnector.newConnector() .forProjectDirectory(new File("someProjectFolder")) .connect(); try { connection.newBuild().forTasks("tasks").run(); } finally { connection.close(); } 

The connection will use the version of Gradle that the target build is configured to use, for example in the Gradle wrapper properties file. When no Gradle version is defined for the build, the connection will use the tooling API's version as the Gradle version to run the build. Generally, you should avoid configuring a Gradle distribution or version and instead use the default provided by the tooling API.

Similarly, the connection will use the JVM and JVM arguments that the target build is configured to use, for example in the gradle.properties file. When no JVM or JVM arguments are defined for the build, the connection will use the current JVM and some default JVM arguments.

GradleConnector instances are not thread-safe. If you want to use a GradleConnector concurrently you must always create a new instance for each thread using #newConnector(). Note, however, the ProjectConnection instances that a connector creates are completely thread-safe.

Gradle version compatibility

The Tooling API is both forwards and backwards compatible with other versions of Gradle. It supports execution of Gradle builds that use older or newer versions of Gradle.

The current version of the Tooling API supports running builds using Gradle versions 1.2.

You should note that not all features of the Tooling API are available for all versions of Gradle. For example, build cancellation is only available for builds using Gradle 2.1 and later. Refer to the documentation for each class and method for more details.

The current Gradle version can be used from Tooling API versions 2.0 or later.

Java version compatibility

The Tooling API requires Java 8 or later. Java 7 is currently still supported but will be removed in Gradle 5.0. The Gradle version used by builds may have additional Java version requirements.


interface IntermediateResultHandler<T : Any>

A handler for an intermediate result obtained by a BuildActionExecuter.


interface LongRunningOperation

Offers ways to communicate both ways with a Gradle operation, be it building a model or running tasks.

Enables tracking progress via listeners that will receive events from the Gradle operation.

Allows providing standard output streams that will receive output if the Gradle operation writes to standard streams.

Allows providing standard input that can be consumed by the gradle operation (useful for interactive builds).

Enables configuring the build run / model request with options like the Java home or JVM arguments. Those settings might not be supported by the target Gradle version. Refer to Javadoc for those methods to understand what kind of exception throw and when is it thrown.


interface ModelBuilder<T : Any> : ConfigurableLauncher<ModelBuilder<T>>

A ModelBuilder allows you to fetch a snapshot of some model for a project or a build. Instances of ModelBuilder are not thread-safe.

You use a ModelBuilder as follows:

 ProjectConnection connection = GradleConnector.newConnector() .forProjectDirectory(new File("someFolder")) .connect(); try { ModelBuilder<GradleProject> builder = connection.model(GradleProject.class); //if you use a different than usual build file name: builder.withArguments("--build-file", "theBuild.gradle"); //configure the standard input in case your build is interactive: builder.setStandardInput(new ByteArrayInputStream("consume this!".getBytes())); //if you want to listen to the progress events: ProgressListener listener = null; // use your implementation builder.addProgressListener(listener); //get the model: GradleProject project = builder.get(); //query the model for information: System.out.println("Available tasks: " + project.getTasks()); } finally { connection.close(); } 


interface ProgressEvent

Some information about a piece of work of a long running operation.


interface ProgressListener

A listener which is notified as some long running operation makes progress.


interface ProjectConnection : Closeable

Represents a long-lived connection to a Gradle project. You obtain an instance of a ProjectConnection by using org.gradle.tooling.GradleConnector#connect().

 try (ProjectConnection connection = GradleConnector.newConnector() .forProjectDirectory(new File("someFolder")) .connect()) { //obtain some information from the build BuildEnvironment environment = connection.model(BuildEnvironment.class).get(); //run some tasks connection.newBuild() .forTasks("tasks") .setStandardOutput(System.out) .run(); } 
Thread safety information

All implementations of ProjectConnection are thread-safe, and may be shared by any number of threads.

All notifications from a given ProjectConnection instance are delivered by a single thread at a time. Note, however, that the delivery thread may change over time.


interface ResultHandler<T : Any>

A handler for an asynchronous operation which returns an object of type T.


interface TestLauncher : ConfigurableLauncher<TestLauncher>

A TestLauncher allows you to execute tests in a Gradle build.



open class BuildActionFailureException : GradleConnectionException

Thrown when a BuildAction fails.


open class BuildCancelledException : GradleConnectionException

Thrown when a org.gradle.tooling.LongRunningOperation is cancelled before the operation completes.


open class BuildException : GradleConnectionException

Thrown when a Gradle build fails or when a model cannot be built.


open class GradleConnectionException : RuntimeException

Thrown when there is some problem using a Gradle connection.


open class ListenerFailedException : GradleConnectionException

Thrown whenever a listener fails with an exception, which in general implies that the build completed like it should, but that one of the listeners failed with an exception.


open class TestExecutionException : GradleConnectionException

Thrown when the org.gradle.tooling.TestLauncher cannot run tests, or when one or more tests fail.


open class UnknownModelException : UnsupportedVersionException

Thrown when the client is trying to acquire a model that is unknown to the Tooling API.

The exception extends UnsupportedVersionException only for backwards compatibility reasons.


open class UnsupportedVersionException : GradleConnectionException

Thrown when the target Gradle version does not support a particular feature.