Package org.gradle.tooling

# Interface BuildController

public interface BuildController
Provides a `BuildAction` various ways to control a Gradle build and access information about the build.

Since:
  1.8

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<M> FetchModelResult<M>`
  `fetch(Class<M> modelType)`
  Fetches a snapshot of the model of the given type for the default project using resilient model fetching.
  `<M, P> FetchModelResult<M>`
  `fetch(Class<M> modelType, @Nullable Class<P> parameterType, @Nullable Action<? super P> parameterInitializer)`
  Fetches a snapshot of the model of the given type using the given parameter using resilient model fetching.
  `<M, P> FetchModelResult<M>`
  `fetch(@Nullable Model target, Class<M> modelType, @Nullable Class<P> parameterType, @Nullable Action<? super P> parameterInitializer)`
  Fetches a snapshot of the model of the given type for the given element using the given parameter with resilient model fetching.
  `<M> FetchModelResult<M>`
  `fetch(Model target, Class<M> modelType)`
  Fetches a snapshot of the model of the given type for the given element using resilient model fetching.
  `<T> @Nullable T`
  `findModel(Class<T> modelType)`
  Fetches a snapshot of the model of the given type, if available.
  `<T, P> @Nullable T`
  `findModel(Class<T> modelType, Class<P> parameterType, Action<? super P> parameterInitializer)`
  Fetches a snapshot of the model of the given type using the given parameter, if available.
  `<T> @Nullable T`
  `findModel(Model target, Class<T> modelType)`
  Fetches a snapshot of the model of the given type, if available.
  `<T, P> @Nullable T`
  `findModel(Model target, Class<T> modelType, Class<P> parameterType, Action<? super P> parameterInitializer)`
  Fetches a snapshot of the model of the given type for the given element using the given parameter, if available.
  `GradleBuild`
  `getBuildModel()`
  Returns an overview of the Gradle build, including some basic details of the projects that make up the build.
  `boolean`
  `getCanQueryProjectModelInParallel(Class<?> modelType)`
  Returns `true` when actions run using `run(Collection)` and that query project models of the given type will run in parallel.
  `<T> T`
  `getModel(Class<T> modelType)`
  Fetches a snapshot of the model of the given type for the default project.
  `<T, P> T`
  `getModel(Class<T> modelType, Class<P> parameterType, Action<? super P> parameterInitializer)`
  Fetches a snapshot of the model of the given type using the given parameter.
  `<T> T`
  `getModel(Model target, Class<T> modelType)`
  Fetches a snapshot of the model of the given type for the given element, usually a Gradle project.
  `<T, P> T`
  `getModel(Model target, Class<T> modelType, Class<P> parameterType, Action<? super P> parameterInitializer)`
  Fetches a snapshot of the model of the given type for the given element using the given parameter.
  `<T> List<T>`
  `run(Collection<? extends BuildAction<? extends T>> actions)`
  Runs the given actions and returns their results.
  `void`
  `send(Object value)`
  Streams an object to the client application.

- ## Method Details

  - ### getModel

    <T> T getModel(Class<T> modelType) throws UnknownModelException
    Fetches a snapshot of the model of the given type for the default project. The default project is generally the project referenced when a `ProjectConnection` is created.

    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.
    Returns:
      The model.
    Throws:
      `UnknownModelException` - When the default project does not support the requested model.
    Since:
      1.8

  - ### findModel

    <T> @Nullable T findModel(Class<T> modelType)
    Fetches a snapshot of the model of the given type, if available.

    See `getModel(Class)` for more details.

    Type Parameters:
      `T` - The model type.
    Parameters:
      `modelType` - The model type.
    Returns:
      The model, or null if not present.

  - ### getBuildModel

    GradleBuild getBuildModel()
    Returns an overview of the Gradle build, including some basic details of the projects that make up the build. This is equivalent to calling `#getModel(GradleBuild.class)`.
    Returns:
      The model.

  - ### getModel

    <T> T getModel(Model target, Class<T> modelType) throws UnknownModelException
    Fetches a snapshot of the model of the given type for the given element, usually a Gradle project.

    The following elements are supported as targets:

    - Any `BasicGradleProject`
    - Any `GradleProject`
    - Any `EclipseProject`
    - Any `IdeaModule`

    See `getModel(Class)` for more details.

    Type Parameters:
      `T` - The model type.
    Parameters:
      `target` - The target element, usually a project.
      `modelType` - The model type.
    Returns:
      The model.
    Throws:
      `UnknownModelException` - When the target project does not support the requested model.

  - ### findModel

    <T> @Nullable T findModel(Model target, Class<T> modelType)
    Fetches a snapshot of the model of the given type, if available.

    See `getModel(Model, Class)` for more details.

    Type Parameters:
      `T` - The model type.
    Parameters:
      `modelType` - The model type.
    Returns:
      The model, or null if not present.

  - ### getModel

    <T, P> T getModel(Class<T> modelType, Class<P> parameterType, Action<? super P> parameterInitializer) throws UnsupportedVersionException, UnknownModelException
    Fetches a snapshot of the model of the given type using the given parameter.

    See `getModel(Model, Class, Class, Action)` for more details.

    Type Parameters:
      `T` - The model type.
      `P` - The parameter type.
    Parameters:
      `modelType` - The model type.
      `parameterType` - The parameter type.
      `parameterInitializer` - Action to configure the parameter
    Returns:
      The model.
    Throws:
      `UnknownModelException` - When the target project does not support the requested model.
      `UnsupportedVersionException` - When the target project does not support the requested model or Gradle version does not support parameterized models.
    Since:
      4.4

  - ### findModel

    <T, P> @Nullable T findModel(Class<T> modelType, Class<P> parameterType, Action<? super P> parameterInitializer)
    Fetches a snapshot of the model of the given type using the given parameter, if available.

    See `getModel(Model, Class, Class, Action)` for more details.

    Type Parameters:
      `T` - The model type.
      `P` - The parameter type.
    Parameters:
      `modelType` - The model type.
      `parameterType` - The parameter type.
      `parameterInitializer` - Action to configure the parameter
    Returns:
      The model.
    Since:
      4.4

  - ### getModel

    <T, P> T getModel(Model target, Class<T> modelType, Class<P> parameterType, Action<? super P> parameterInitializer) throws UnsupportedVersionException, UnknownModelException
    Fetches a snapshot of the model of the given type for the given element using the given parameter.

    The parameter type must be an interface only with getters and setters and no nesting is supported. The Tooling API will create a proxy instance of this interface and use the initializer to run against that instance to configure it and then pass to the model builder.

    See `getModel(Class)` for more details.

    Type Parameters:
      `T` - The model type.
      `P` - The parameter type.
    Parameters:
      `target` - The target element, usually a project.
      `modelType` - The model type.
      `parameterType` - The parameter type.
      `parameterInitializer` - Action to configure the parameter
    Returns:
      The model.
    Throws:
      `UnknownModelException` - When the target project does not support the requested model.
      `UnsupportedVersionException` - When the target project does not support the requested model or Gradle version does not support parameterized models.
    Since:
      4.4

  - ### findModel

    <T, P> @Nullable T findModel(Model target, Class<T> modelType, Class<P> parameterType, Action<? super P> parameterInitializer)
    Fetches a snapshot of the model of the given type for the given element using the given parameter, if available.

    See `getModel(Model, Class, Class, Action)` for more details.

    Type Parameters:
      `T` - The model type.
      `P` - The parameter type.
    Parameters:
      `target` - The target element, usually a project.
      `modelType` - The model type.
      `parameterType` - The parameter type.
      `parameterInitializer` - Action to configure the parameter
    Returns:
      The model.
    Since:
      4.4

  - ### run

    <T> List<T> run(Collection<? extends BuildAction<? extends T>> actions)
    Runs the given actions and returns their results. Attempts to run the actions in parallel, when supported by the Gradle version.

    This method works with all Gradle versions. For versions 6.7 and earlier, the actions are run sequentially rather than in parallel.

    When one or more actions fail with an exception, the exceptions are rethrown by this method and no result is returned.

    Type Parameters:
      `T` - the result type.
    Parameters:
      `actions` - The actions to run.
    Returns:
      The action results. These are returned in the same order as the actions that produce them.
    Since:
      6.8

  - ### getCanQueryProjectModelInParallel

    boolean getCanQueryProjectModelInParallel(Class<?> modelType)
    Returns `true` when actions run using `run(Collection)` and that query project models of the given type will run in parallel. Returns `false` when the models will not be queried in parallel, for example because the target Gradle version does not support parallel execution, or because some build configuration disables the parallel execution, or because the queries are unsafe to perform in parallel.
    Returns:
      `true` when project models may be queried in parallel.
    Since:
      6.8

  - ### send

    void send(Object value)

    Streams an object to the client application.

    The client application can receive objects sent using this method by registering a `StreamedValueListener`. The client application receives objects in the order they were sent, and before it receives the result of the `BuildAction`.

    This method sends the object asynchronously and does not block until the client application has received the object.

    The build action will fail if the client application did not register a listener to receive the streamed objects.

    Since:
      8.6

  - ### fetch

    @Incubating <M> FetchModelResult<M> fetch(Class<M> modelType)
    Fetches a snapshot of the model of the given type for the default project using resilient model fetching.

    See `fetch(Model, Class, Class, Action)` for more details about resilient fetching.

    Type Parameters:
      `M` - The model type.
    Parameters:
      `modelType` - The model type.
    Returns:
      The fetch result.
    Since:
      9.3.0

  - ### fetch

    @Incubating <M> FetchModelResult<M> fetch(Model target, Class<M> modelType)
    Fetches a snapshot of the model of the given type for the given element using resilient model fetching.

    See `fetch(Model, Class, Class, Action)` for more details about resilient fetching.

    Type Parameters:
      `M` - The model type.
    Parameters:
      `target` - The target element, usually a project.
      `modelType` - The model type.
    Returns:
      The fetch result.
    Since:
      9.3.0

  - ### fetch

    @Incubating <M, P> FetchModelResult<M> fetch(Class<M> modelType, @Nullable Class<P> parameterType, @Nullable Action<? super P> parameterInitializer)
    Fetches a snapshot of the model of the given type using the given parameter using resilient model fetching.

    See `fetch(Model, Class, Class, Action)` for more details about resilient fetching.

    Type Parameters:
      `M` - The model type.
      `P` - The parameter type.
    Parameters:
      `modelType` - The model type.
      `parameterType` - The parameter type.
      `parameterInitializer` - Action to configure the parameter
    Returns:
      The fetch result.
    Since:
      9.3.0

  - ### fetch

    @Incubating <M, P> FetchModelResult<M> fetch(@Nullable Model target, Class<M> modelType, @Nullable Class<P> parameterType, @Nullable Action<? super P> parameterInitializer)
    Fetches a snapshot of the model of the given type for the given element using the given parameter with resilient model fetching.

    Unlike `getModel(Model, Class, Class, Action)`, this method uses resilient model fetching which means that if the model cannot be fetched due to an error, the method will not throw an exception. Instead, it returns a `FetchModelResult` that contains either the successfully fetched model or the failure information.

    This is particularly useful when you want to fetch multiple models and continue processing even if some models fail to load, or when you need detailed information about why a model fetch failed.

    Type Parameters:
      `M` - The model type.
      `P` - The parameter type.
    Parameters:
      `target` - The target element, usually a project. Pass `null` to target the default project.
      `modelType` - The model type to fetch.
      `parameterType` - The parameter type used to configure the model fetch. Pass `null` if no parameter is needed.
      `parameterInitializer` - Action to configure the parameter. Pass `null` if no parameter initialization is needed.
    Returns:
      A `FetchModelResult` containing the target, the fetched model (if successful), and any failures that occurred. Check `FetchModelResult.getFailures()` to determine if the fetch was successful.
    Since:
      9.3.0