# 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

Modifier and Type
Method
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 ConfigurableLauncher

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

## Method Details

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