org.gradle.tooling

Class GradleConnector

java.lang.Object

org.gradle.tooling.GradleConnector

Direct Known Subclasses:

DefaultGradleConnector

public abstract class GradleConnector
extends Object

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.

Example:

 ProjectConnection connection = GradleConnector.newConnector()
    .forProjectDirectory(new File("someProjectFolder"))
    .connect();

 try {
    connection.newBuild().forTasks("tasks").run();
 } finally {
    connection.close();
 }
 

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.

Constructor Summary

Constructors

Constructor and Description
GradleConnector()

Method Summary

Methods

Modifier and Type	Method and Description
abstract ProjectConnection	connect() Creates a connection to the project in the specified project directory.
abstract GradleConnector	forProjectDirectory(File projectDir) Specifies the working directory to use.
static GradleConnector	newConnector() Creates a new connector instance.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GradleConnector

public GradleConnector()

Method Detail

newConnector

public static GradleConnector newConnector()

Creates a new connector instance.

Returns:

The instance. Never returns null.

useInstallation

public abstract GradleConnector useInstallation(File gradleHome)

Specifies which Gradle installation to use. This replaces any value specified using useDistribution(java.net.URI) or useGradleVersion(String). Defaults to a project-specific Gradle version.

Parameters:

gradleHome - The Gradle installation directory.

Returns:

this

useGradleVersion

public abstract GradleConnector useGradleVersion(String gradleVersion)

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 using useInstallation(java.io.File) or useDistribution(java.net.URI). Defaults to a project-specific Gradle version.

Parameters:

gradleVersion - The version to use.

Returns:

this

useDistribution

public abstract GradleConnector useDistribution(URI gradleDistribution)

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 using useInstallation(java.io.File) or useGradleVersion(String). Defaults to a project-specific Gradle version.

Parameters:

gradleDistribution - The distribution to use.

Returns:

this

forProjectDirectory

public abstract GradleConnector forProjectDirectory(File projectDir)

Specifies the working directory to use.

Parameters:

projectDir - The working directory.

Returns:

this

useGradleUserHomeDir

public abstract GradleConnector useGradleUserHomeDir(File gradleUserHomeDir)

Specifies the user's Gradle home directory to use. Defaults to ~/.gradle.

Parameters:

gradleUserHomeDir - The user's Gradle home directory to use.

Returns:

this

connect

public abstract ProjectConnection connect()
                                   throws GradleConnectionException,
                                          UnsupportedVersionException

Creates a connection to the project in the specified project directory. You should call ProjectConnection.close() when you are finished with the connection.

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.