org.gradle.tooling

## Interface ModelBuilder<T>

- Type Parameters:
    `T` - The type of model to build
  All Superinterfaces:
    ConfigurableLauncher<ModelBuilder<T>>, LongRunningOperation

      public interface ModelBuilder<T>
      extends ConfigurableLauncher<ModelBuilder<T>>

  A `ModelBuilder` allows you to fetch a snapshot of some model for a project or a build. Instances of `ModelBuilder` are not thread-safe.

  You use a `ModelBuilder` as follows:

  - Create an instance of `ModelBuilder` by calling `ProjectConnection.model(Class)`.
  - Configure the builder as appropriate.
  - Call either `get()` or `get(ResultHandler)` to build the model.
  - Optionally, you can reuse the builder to build the model multiple times.
  Example:

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

       try {
          ModelBuilder<GradleProject> builder = connection.model(GradleProject.class);

          //if you use a different than usual build file name:
          builder.withArguments("--build-file", "theBuild.gradle");

          //configure the standard input in case your build is interactive:
          builder.setStandardInput(new ByteArrayInputStream("consume this!".getBytes()));

          //if you want to listen to the progress events:
          ProgressListener listener = null; // use your implementation
          builder.addProgressListener(listener);

          //get the model:
          GradleProject project = builder.get();

          //query the model for information:
          System.out.println("Available tasks: " + project.getTasks());
       } finally {
          connection.close();
       }

  Since:
    1.0-milestone-3

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ModelBuilder<T>` | `forTasks(Iterable<String> tasks)` Specifies the tasks to execute before building the model.
    `ModelBuilder<T>` | `forTasks(String... tasks)` Specifies the tasks to execute before building the model.
    `T` | `get()` Fetch the model, blocking until it is available.
    `void` | `get(ResultHandler<? super T> handler)` Starts fetching the model, passing the result to the given handler when complete.

    - ### Methods inherited from interface org.gradle.tooling.ConfigurableLauncher

      `addProgressListener, addProgressListener, addProgressListener, addProgressListener, setColorOutput, setJavaHome, setJvmArguments, setJvmArguments, setStandardError, setStandardInput, setStandardOutput, withArguments, withArguments, withCancellationToken`

- - ### Method Detail

    - #### forTasks

          @Incubating
          ModelBuilder<T> forTasks(String... tasks)

      Specifies the tasks to execute before building the model. If not configured, null, or an empty array is passed, then no tasks will be executed.
      Parameters:
        `tasks` - The paths of the tasks to be executed. Relative paths are evaluated relative to the project for which this launcher was created.
      Returns:
        this
      Since:
        1.2

    - #### forTasks

          @Incubating
          ModelBuilder<T> forTasks(Iterable<String> tasks)

      Specifies the tasks to execute before building the model. If not configured, null, or an empty array is passed, then no tasks will be executed.
      Parameters:
        `tasks` - The paths of the tasks to be executed. Relative paths are evaluated relative to the project for which this launcher was created.
      Returns:
        this
      Since:
        2.6

    - #### get

          T get()
                throws GradleConnectionException,
                       IllegalStateException

      Fetch the model, blocking until it is available.
      Returns:
        The model.
      Throws:
        `UnsupportedVersionException` - When the target Gradle version does not support building models.
        `UnknownModelException` - When the target Gradle version or build does not support the requested model.
        `UnsupportedOperationConfigurationException` - When the target Gradle version does not support some requested configuration option such as `ConfigurableLauncher.withArguments(String...)`.
        `UnsupportedBuildArgumentException` - When there is a problem with build arguments provided by `ConfigurableLauncher.withArguments(String...)`.
        `BuildException` - On some failure executing the Gradle build.
        `BuildCancelledException` - When the operation was cancelled before it completed successfully.
        `GradleConnectionException` - On some other failure using the connection.
        `IllegalStateException` - When the connection has been closed or is closing.
      Since:
        1.0-milestone-3

    - #### get

          void get(ResultHandler<? super T> handler)
                   throws IllegalStateException

      Starts fetching the 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 `get()` for a description of the various exceptions that the operation may fail with.

      Parameters:
        `handler` - The handler to supply the result to.
      Throws:
        `IllegalStateException` - When the connection has been closed or is closing.
      Since:
        1.0-milestone-3