Package org.gradle.tooling

Interface ProjectConnection

  • All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable
    public interface ProjectConnection
extends java.io.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​(java.lang.Class<T> modelType)
      Fetches a snapshot of the model of the given type for this project.
      <T> void getModel​(java.lang.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​(java.lang.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.
      void notifyDaemonsAboutChangedPaths​(java.util.List<java.nio.file.Path> changedPaths)
      Notifies all daemons about file changes made by an external process, like an IDE.

    • Method Detail

      • getModel

        <T> T getModel​(java.lang.Class<T> modelType)
        throws GradleConnectionException,
               java.lang.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.
        java.lang.IllegalStateException - When this connection has been closed or is closing.
        Since:
        1.0-milestone-3

      • getModel

        <T> void getModel​(java.lang.Class<T> modelType,
                  ResultHandler<? super T> handler)
           throws java.lang.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:
        java.lang.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 3.0 or later.

        Returns:
        The launcher.
        Since:
        2.6

      • 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

        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

      • notifyDaemonsAboutChangedPaths

        void notifyDaemonsAboutChangedPaths​(java.util.List<java.nio.file.Path> changedPaths)
        Notifies all daemons about file changes made by an external process, like an IDE.

        The daemons will use this information to update the retained file system state.

        The method should be invoked on every change done by the external process. For example, an IDE should notify Gradle when the user saves a changed file, or after some refactoring finished. This will guarantee that Gradle picks up changes when trigerring a build, even if the file system is too slow to notify file watchers. The caller shouldn't notify Gradle about changes detected by using other file watchers, since Gradle already will be using its own file watcher.

        The paths which are passed in need to be absolute, canonicalized paths. For a delete, the deleted path should be passed. For a rename, the old and the new path should be passed. When creating a new file, the path to the file should be passed.

        The call is synchronous, i.e. the method ensures that the changed paths are taken into account by the daemon after it returned. This ensures that for every build started after this method has been called knows about the changed paths.

        If the version of Gradle does not support virtual file system retention (i.e. < 6.1), then the operation is a no-op.

        Parameters:
        changedPaths - Absolute paths which have been changed by the external process.
        Throws:
        java.lang.IllegalArgumentException - When the paths are not absolute.
        UnsupportedVersionException - When the target Gradle version is <= 2.5.
        GradleConnectionException - On some other failure using the connection.
        Since:
        6.1

      • 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 java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Since:
        1.0-milestone-3