GradleConnection (Gradle API 2.14.1)
Date: 2016-07-18

Package: org.gradle.tooling.connection

## [Java] 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

- - ### Methods Summary

    Methods
    Type | Name and description
    --- | ---
    `void` | `close()` Closes this connection.
    `ModelResults<T>` | `getModels(Class<T> modelType)` Fetches a Set of snapshots of the model of the given type for this composite.
    `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.
    `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

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

    - #### public ModelResults<T> getModels(Class<T> modelType)

      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()`

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

    - #### public 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. This method returns immediately, and the result is later passed to the given handler's ResultHandler.onComplete method after fetching all of the composite's models.

      If the operation fails, the handler's ResultHandler.onFailure 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)`

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

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

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

    - #### public BuildLauncher newBuild()

      Creates a launcher which can be used to execute a build.

      Returns:
        The launcher.