Package org.gradle.tooling

## Interface ProjectConnection

- All Superinterfaces:
    `AutoCloseable`, `Closeable`

      public interface ProjectConnection
      extends Closeable

  Represents a long-lived connection to a Gradle project. You obtain an instance of a `ProjectConnection` by using `GradleConnector.connect()`.

       try (ProjectConnection connection = GradleConnector.newConnector()
              .forProjectDirectory(new File("someFolder"))
              .connect()) {

          //obtain some information from the build
          BuildEnvironment environment = connection.model(BuildEnvironment.class).get();

          //run some tasks
          connection.newBuild()
            .forTasks("tasks")
            .setStandardOutput(System.out)
            .run();

       }

  ### Thread safety information

  All implementations of `ProjectConnection` are thread-safe, and may be shared by any number of threads.

  All notifications from a given `ProjectConnection` instance are delivered by a single thread at a time. Note, however, that the delivery thread may change over time.

  Since:
    1.0-milestone-3

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `BuildActionExecuter.Builder` | `action()` | Creates a builder for an executer which can be used to run actions in different phases of the build.
    `<T> BuildActionExecuter<T>` | `action​(BuildAction<T> buildAction)` | Creates an executer which can be used to run the given action when the build has finished.
    `void` | `close()` | Closes this connection.
    `<T> T` | `getModel​(Class<T> modelType)` | Fetches a snapshot of the model of the given type for this project.
    `<T> void` | `getModel​(Class<T> modelType, ResultHandler<? super T> handler)` | Starts fetching a snapshot of the given model, passing the result to the given handler when complete.
    `<T> ModelBuilder<T>` | `model​(Class<T> modelType)` | Creates a builder which can be used to query the model of the given type.
    `BuildLauncher` | `newBuild()` | Creates a launcher which can be used to execute a build.
    `TestLauncher` | `newTestLauncher()` | Creates a test launcher which can be used to execute tests.

- - ### Method Detail

    - #### getModel

          <T> T getModel​(Class<T> modelType)
                  throws GradleConnectionException,
                         IllegalStateException

      Fetches a snapshot of the model of the given type for this project. This method blocks until the model is available.

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

      Type Parameters:
        `T` - The model type.
      Parameters:
        `modelType` - The model type.
      Returns:
        The model.
      Throws:
        `UnsupportedVersionException` - When the target Gradle version does not support the given model.
        `UnknownModelException` - When the target Gradle version or build does not support the requested model.
        `BuildException` - On some failure executing the Gradle build, in order to build the model.
        `GradleConnectionException` - On some other failure using the connection.
        `IllegalStateException` - When this connection has been closed or is closing.
      Since:
        1.0-milestone-3

    - #### getModel

          <T> void getModel​(Class<T> modelType,
                            ResultHandler<? super T> handler)
                     throws IllegalStateException

      Starts fetching a snapshot of the given model, 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.

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

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

      Type Parameters:
        `T` - The model type.
      Parameters:
        `modelType` - The model type.
        `handler` - The handler to pass the result to.
      Throws:
        `IllegalStateException` - When this connection has been closed or is closing.
      Since:
        1.0-milestone-3

    - #### newBuild

          BuildLauncher newBuild()

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

      Requires Gradle 1.0-milestone-8 or later.

      Returns:
        The launcher.
      Since:
        1.0-milestone-3

    - #### newTestLauncher

          TestLauncher newTestLauncher()

      Creates a test launcher which can be used to execute tests.

      Requires Gradle 2.6 or later.

      Returns:
        The launcher.
      Since:
        2.6

    - #### model

          <T> ModelBuilder<T> model​(Class<T> modelType)

      Creates a builder which can be used to query the model of the given type.

      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.

      Requires Gradle 1.0-milestone-8 or later.

      Type Parameters:
        `T` - The model type.
      Parameters:
        `modelType` - The model type
      Returns:
        The builder.
      Since:
        1.0-milestone-3

    - #### action

          <T> BuildActionExecuter<T> action​(BuildAction<T> buildAction)

      Creates an executer which can be used to run the given action when the build has finished. The action is serialized into the build process and executed, then its result is serialized back to the caller.

      Requires Gradle 1.8 or later.

      Type Parameters:
        `T` - The result type.
      Parameters:
        `buildAction` - The action to run.
      Returns:
        The builder.
      Since:
        1.8
      See Also:
        `if you want to hook into different points of the build lifecycle.`

    - #### action

          @Incubating
          BuildActionExecuter.Builder action()

      Creates a builder for an executer which can be used to run actions in different phases of the build. The actions are serialized into the build process and executed, then its result is serialized back to the caller.

      Requires Gradle 4.8 or later.

      Returns:
        The builder.
      Since:
        4.8

    - #### 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.
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `Closeable`
      Since:
        1.0-milestone-3