GradleConnector (Gradle API 2.14)
Date: 2016-06-14

Package: org.gradle.tooling

## [Java] Class GradleConnector

- org.gradle.tooling.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.

  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.propertes` 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.0-milestone-8 and later. Support for versions from 1.0-milestone-8 to 1.1 is deprecated and will be removed from the Tooling API in Gradle 3.0.

  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 1.2 or later. Support for Tooling API versions 1.2 to 1.12 is deprecated and will be removed in Gradle 3.0

  ## Java version compatibility

  The Tooling API requires Java 6 or later. Support for Java 6 is currently deprecated and will be removed in Gradle 3.0.

  Since:
    1.0-milestone-3

- - ### Methods Summary

    Methods
    Type | Name and description
    --- | ---
    `ProjectConnection` | `connect()` Creates a connection to the project in the specified project directory.
    `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.
    `static GradleConnectionBuilder` | `newGradleConnection()` Creates a new connection builder instance for creating Gradle composite builds.
    `GradleConnector` | `useBuildDistribution()` Specifies to use the Gradle distribution defined by the target Gradle build.
    `GradleConnector` | `useDistribution(URI gradleDistribution)` Specifies which Gradle distribution to use.
    `GradleConnector` | `useGradleUserHomeDir(File gradleUserHomeDir)` Specifies the user's Gradle home directory to use.
    `GradleConnector` | `useGradleVersion(String gradleVersion)` Specifies which Gradle version to use.
    `GradleConnector` | `useInstallation(File gradleHome)` Specifies which Gradle installation to use.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- - ### Method Detail

    - #### public ProjectConnection connect()

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

      throws:
        UnsupportedVersionException When the target Gradle version does not support this version of the tooling API.
      throws:
        GradleConnectionException On failure to establish a connection with the target Gradle version.
      Returns:
        The connection. Never return null.
      Since:
        1.0-milestone-3

    - #### public GradleConnector forProjectDirectory(File projectDir)

      Specifies the working directory to use.

      Parameters:
        `projectDir` - The working directory.
      Returns:
        this
      Since:
        1.0-milestone-3

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

    - #### public static GradleConnector newConnector()

      Creates a new connector instance.

      Returns:
        The instance. Never returns null.
      Since:
        1.0-milestone-3

    - #### @Incubating public static GradleConnectionBuilder newGradleConnection()

      Creates a new connection builder instance for creating Gradle composite builds.

      Returns:
        The instance. Never returns null.
      Since:
        2.13

    - #### public 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

    - #### public 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

    - #### public 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

    - #### public 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

    - #### public 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