org.gradle.tooling - api

api / org.gradle.tooling

Package org.gradle.tooling

Types

BuildAction	`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.
BuildActionExecuter	`interface BuildActionExecuter<T : Any> : ConfigurableLauncher<BuildActionExecuter<T>>` Used to execute a BuildAction in the build process.
BuildController	`interface BuildController` Provides a BuildAction various ways to control a Gradle build and access information about the build.
BuildLauncher	`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: Create an instance of `BuildLauncher` by calling `org.gradle.tooling.ProjectConnection#newBuild()`. Configure the launcher as appropriate. Call either `#run()` or `#run(ResultHandler)` to execute the build. Optionally, you can reuse the launcher to launch additional builds. Example: 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(); }
CancellationToken	`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.
CancellationTokenSource	`interface CancellationTokenSource` A `CancellationTokenSource` allows you to issue cancellation requests to one or more org.gradle.tooling.LongRunningOperation instances. To use a token source: Create a token source using `GradleConnector#newCancellationTokenSource()`. Attach the token to one or more operations using `org.gradle.tooling.LongRunningOperation#withCancellationToken(CancellationToken)`. You need to do this before you start the operation. Later, you can cancel the associated operations by calling `#cancel()` on this token source. All implementations of this interface are required to be thread safe.
ConfigurableLauncher	`interface ConfigurableLauncher<T : ConfigurableLauncher<ConfigurableLauncher<*>>> : LongRunningOperation` A `ConfigurableLauncher` allows you to configure a long running operation.
Failure	`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.
GradleConnector	`abstract class GradleConnector` A `GradleConnector` is the main entry point to the Gradle tooling API. You use this API as follows: Call `#newConnector()` to create a new connector instance. Configure the connector. You must call `#forProjectDirectory(java.io.File)` to specify which project you wish to connect to. Other methods are optional. Call `#connect()` to create the connection to a project. When finished with the connection, call `ProjectConnection#close()` to clean up. Example: `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.
IntermediateResultHandler	`interface IntermediateResultHandler<T : Any>` A handler for an intermediate result obtained by a BuildActionExecuter.
LongRunningOperation	`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.
ModelBuilder	`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: Create an instance of `ModelBuilder` by calling `org.gradle.tooling.ProjectConnection#model(Class)`. Configure the builder as appropriate. Call either `#get()` or `#get(ResultHandler)` to build the model. Optionally, you can reuse the builder to build the model multiple times. Example: 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(); }
ProgressEvent	`interface ProgressEvent` Some information about a piece of work of a long running operation.
ProgressListener	`interface ProgressListener` A listener which is notified as some long running operation makes progress.
ProjectConnection	`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.
ResultHandler	`interface ResultHandler<T : Any>` A handler for an asynchronous operation which returns an object of type T.
TestLauncher	`interface TestLauncher : ConfigurableLauncher<TestLauncher>` A `TestLauncher` allows you to execute tests in a Gradle build.

Exceptions

BuildActionFailureException	`open class BuildActionFailureException : GradleConnectionException` Thrown when a BuildAction fails.
BuildCancelledException	`open class BuildCancelledException : GradleConnectionException` Thrown when a org.gradle.tooling.LongRunningOperation is cancelled before the operation completes.
BuildException	`open class BuildException : GradleConnectionException` Thrown when a Gradle build fails or when a model cannot be built.
GradleConnectionException	`open class GradleConnectionException : RuntimeException` Thrown when there is some problem using a Gradle connection.
ListenerFailedException	`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.
TestExecutionException	`open class TestExecutionException : GradleConnectionException` Thrown when the org.gradle.tooling.TestLauncher cannot run tests, or when one or more tests fail.
UnknownModelException	`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.
UnsupportedVersionException	`open class UnsupportedVersionException : GradleConnectionException` Thrown when the target Gradle version does not support a particular feature.