org.gradle.tooling

## Class GradleConnector

- java.lang.Object
- - org.gradle.tooling.GradleConnector

-     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.

  Since:
    1.0-milestone-3

- - ### 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 CancellationTokenSource` | `newCancellationTokenSource()` Creates a new `CancellationTokenSource` that can be used to cancel one or more `LongRunningOperation` executions.
    `static GradleConnector` | `newConnector()` Creates a new connector instance.
    `abstract GradleConnector` | `useBuildDistribution()` 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.

    - ### 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.
      Since:
        1.0-milestone-3

    - #### newCancellationTokenSource

          public static CancellationTokenSource newCancellationTokenSource()

      Creates a new `CancellationTokenSource` that can be used to cancel one or more `LongRunningOperation` executions.
      Returns:
        The instance. Never returns `null`.
      Since:
        2.1

    - #### useInstallation

          public abstract GradleConnector useInstallation(File gradleHome)

      Specifies which Gradle installation to use. This replaces any value specified using `useDistribution(URI)`, `useGradleVersion(String)`, or `useBuildDistribution()`. Defaults to a project-specific Gradle version.
      Parameters:
        `gradleHome` - The Gradle installation directory.
      Returns:
        this
      Since:
        1.0-milestone-3

    - #### 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(File)`, `useDistribution(URI)`, or `useBuildDistribution()`. Defaults to a project-specific Gradle version.
      Parameters:
        `gradleVersion` - The version to use.
      Returns:
        this
      Since:
        1.0-milestone-3

    - #### 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(File)`, `useGradleVersion(String)`, or `useBuildDistribution()`. Defaults to a project-specific Gradle version.
      Parameters:
        `gradleDistribution` - The distribution to use.
      Returns:
        this
      Since:
        1.0-milestone-3

    - #### useBuildDistribution

          public abstract GradleConnector 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 using `useInstallation(File)`, `useDistribution(URI)`, or `useGradleVersion(String)`. Acts as the default behavior.
      Returns:
        this
      Since:
        2.3

    - #### forProjectDirectory

          public abstract GradleConnector forProjectDirectory(File projectDir)

      Specifies the working directory to use.
      Parameters:
        `projectDir` - The working directory.
      Returns:
        this
      Since:
        1.0-milestone-3

    - #### 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
      Since:
        1.0-milestone-3

    - #### connect

          public abstract ProjectConnection connect()
                                             throws GradleConnectionException

      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.
      Since:
        1.0-milestone-3