org.gradle.tooling.connection

## Interface GradleConnection

-     @Incubating
      public interface GradleConnection

  Represents a connection to a composite Gradle build.

  A composite build is a lightweight assembly of Gradle projects that a developer is working on. These projects may come from different Gradle builds, but when assembled into a composite Gradle is able to coordinate across these projects, so that they appear in some way as a single build unit.

  Operations (fetching models, executing tasks, etc) are performed across all Gradle projects in a composite.

       GradleConnectionBuilder builder = GradleConnector.newGradleConnection();
       builder.addParticipant(new File("someFolder"));
       GradleConnection connection = builder.build();

       try {
          // obtain some information from the build
          ModelResults invocations = connection.models(BuildInvocations.class)
            .get();

          // run some tasks
          BuildInvocations firstBuild = invocations.iterator().next().getModel();
          TaskSelector taskToRun = firstBuild.getTaskSelectors().getAt(0);

          connection.newBuild()
            .forLaunchables(taskToRun)
            .setStandardOutput(System.out)
            .run();

       } finally {
          connection.close();
       }

  Since:
    2.13

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes this connection.
    `<T> ModelResults<T>` | `getModels(Class<T> modelType)` Fetches a Set of snapshots of the model of the given type for this composite.
    `<T> void` | `getModels(Class<T> modelType, ResultHandler<? super ModelResults<T>> handler)` Starts fetching a Set of snapshots of the model of the given type for this composite, passing the result to the given handler when complete.
    `<T> ModelBuilder<ModelResults<T>>` | `models(Class<T> modelType)` Creates a builder which can be used to query the model of the given type for all projects in the composite.
    `BuildLauncher` | `newBuild()` Creates a launcher which can be used to execute a build.

- - ### Method Detail

    - #### getModels

          <T> ModelResults<T> getModels(Class<T> modelType)
                                    throws GradleConnectionException,
                                           IllegalStateException

      Fetches a Set of snapshots of the model of the given type for this composite. This method blocks until the model is available.

      This method is simply a convenience for calling `models(modelType).get()`

      Type Parameters:
        `T` - The model type.
      Parameters:
        `modelType` - The model type.
      Throws:
        `GradleConnectionException` - On failure using the connection.
        `IllegalStateException` - When this connection has been closed or is closing.

    - #### getModels

          <T> void getModels(Class<T> modelType,
                           ResultHandler<? super ModelResults<T>> handler)
                         throws IllegalStateException

      Starts fetching a Set of snapshots of the model of the given type for this composite, passing the result to the given handler when complete. This method returns immediately, and the result is later passed to the given handler's `ResultHandler.onComplete(Object)` method after fetching all of the composite's models.

      If the operation fails, the handler's `ResultHandler.onFailure(GradleConnectionException)` method is called with the appropriate exception. See `getModels(Class)` for a description of the various exceptions that the operation may fail with.

      An operation will fail if there is a problem fetching the model from any of the composite's builds. The handler's `onFailure` method will only be called one time with the first failure.

      This method is simply a convenience for calling `models(modelType).get(handler)`

      Type Parameters:
        `T` - The model type.
      Parameters:
        `modelType` - The model type.
        `handler` - The handler that will be notified of results.
      Throws:
        `IllegalStateException` - When this connection has been closed or is closing.

    - #### models

          <T> ModelBuilder<ModelResults<T>> models(Class<T> modelType)

      Creates a builder which can be used to query the model of the given type for all projects in the composite.

      The set of projects is "live", so that models from projects added to the overall composite after the builder was been created will appear in the results without recreating the builder.

      Any of following models types may be available, depending on the version of Gradle being used by the target build:

      - `GradleBuild`
      - `BuildEnvironment`
      - `GradleProject`
      - `BuildInvocations`
      - `ProjectPublications`
      - `IdeaProject`
      - `BasicIdeaProject`
      - `EclipseProject`
      - `HierarchicalEclipseProject`

      A build may also expose additional custom tooling models. You can use this method to query these models.

      Type Parameters:
        `T` - The model type.
      Parameters:
        `modelType` - The model type.

    - #### newBuild

          BuildLauncher newBuild()

      Creates a launcher which can be used to execute a build.
      Returns:
        The launcher.

    - #### close

          void close()

      Closes this connection. Blocks until any pending operations are complete. Once this method has returned, no more notifications will be delivered by any threads.