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. Each release of Gradle contains a new release of the Tooling API as well.
The Tooling API supports running builds using Gradle version 3.0 and up.
You should note that not all features of the Tooling API are available for all versions of Gradle. Refer to the documentation for each class and method for more details.
Builds using Gradle 5.0 and up require the use of Tooling API version 3.0 or later.
Java version compatibility
The Tooling API requires Java 8 or later. The Gradle version used by builds may have additional Java version requirements.
- Since:
- 1.0-milestone-3
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract ProjectConnection
connect()
Creates a connection to the project in the specified project directory.abstract void
Disconnects all ProjectConnection instances created by this connector.abstract GradleConnector
forProjectDirectory
(File projectDir) Specifies the working directory to use.static CancellationTokenSource
Creates a newCancellationTokenSource
that can be used to cancel one or moreLongRunningOperation
executions.static GradleConnector
Creates a new connector instance.abstract GradleConnector
Specifies to use the Gradle distribution defined by the target Gradle build.abstract GradleConnector
useDistribution
(URI gradleDistribution) Specifies which Gradle distribution to use.abstract GradleConnector
useGradleUserHomeDir
(File gradleUserHomeDir) Specifies the user's Gradle home directory to use.abstract GradleConnector
useGradleVersion
(String gradleVersion) Specifies which Gradle version to use.abstract GradleConnector
useInstallation
(File gradleHome) Specifies which Gradle installation to use.
-
Constructor Details
-
GradleConnector
public GradleConnector()
-
-
Method Details
-
newConnector
Creates a new connector instance.- Returns:
- The instance. Never returns null.
- Since:
- 1.0-milestone-3
-
newCancellationTokenSource
Creates a newCancellationTokenSource
that can be used to cancel one or moreLongRunningOperation
executions.- Returns:
- The instance. Never returns
null
. - Since:
- 2.1
-
useInstallation
Specifies which Gradle installation to use. This replaces any value specified usinguseDistribution(URI)
,useGradleVersion(String)
, oruseBuildDistribution()
. Defaults to a project-specific Gradle version.- Parameters:
gradleHome
- The Gradle installation directory.- Returns:
- this
- Since:
- 1.0-milestone-3
-
useGradleVersion
Specifies which Gradle version to use. The appropriate distribution is downloaded and installed into the user's Gradle home directory. This replaces any value specified usinguseInstallation(File)
,useDistribution(URI)
, oruseBuildDistribution()
. Defaults to a project-specific Gradle version.- Parameters:
gradleVersion
- The version to use.- Returns:
- this
- Since:
- 1.0-milestone-3
-
useDistribution
Specifies which Gradle distribution to use. The appropriate distribution is downloaded and installed into the user's Gradle home directory. This replaces any value specified usinguseInstallation(File)
,useGradleVersion(String)
, oruseBuildDistribution()
. Defaults to a project-specific Gradle version.- Parameters:
gradleDistribution
- The distribution to use.- Returns:
- this
- Since:
- 1.0-milestone-3
-
useBuildDistribution
Specifies to use the Gradle distribution defined by the target Gradle build. The appropriate distribution defined by the target Gradle build is downloaded and installed into the user's Gradle home directory. If the target Gradle build does not define the distribution that it should be built with, the Gradle version of this connector is used. This replaces any value specified usinguseInstallation(File)
,useDistribution(URI)
, oruseGradleVersion(String)
. Acts as the default behavior.- Returns:
- this
- Since:
- 2.3
-
forProjectDirectory
Specifies the working directory to use.- Parameters:
projectDir
- The working directory.- Returns:
- this
- Since:
- 1.0-milestone-3
-
useGradleUserHomeDir
Specifies the user's Gradle home directory to use. Defaults to~/.gradle
.- Parameters:
gradleUserHomeDir
- The user's Gradle home directory to use.- Returns:
- this
- Since:
- 1.0-milestone-3
-
connect
Creates a connection to the project in the specified project directory. You should callProjectConnection.close()
when you are finished with the connection.Note, that the returned instance does not automatically pick up changes if the connection configuration (e.g. the gradle.properties file) changes. It's the client's responsibility to close the connection and create a new one in that scenario.
- Returns:
- The connection. Never return null.
- Throws:
UnsupportedVersionException
- When the target Gradle version does not support this version of the tooling API.GradleConnectionException
- On failure to establish a connection with the target Gradle version.- Since:
- 1.0-milestone-3
-
disconnect
public abstract void disconnect()Disconnects all ProjectConnection instances created by this connector.Calling this method tries to do a best effort to clean up resources used by the tooling API. It tries to cancel any builds and shut down running daemons.
After calling
disconnect
, creating new project connections will be rejected and the existing ones created by this instance will also deny future build operations.- Since:
- 6.5
-