Implement project synchronization API

[donat]

Overview

Plugins need a simple way to import and synchronize Gradle projects with the workspace. For example, the Spring Tool Suite offers Spring project creation with Gradle.

Design

There are two major use cases: importing external projects into the workspace and updating existing workspace project configuration to be in sync with the Gradle build. The fundamental difference between is how the import settings (Gradle distribution, Gradle user home, etc) are handled. When importing the project the import settings are enforced, whereas during the project synchronization the existing settings are used.

Class hierarchy

The GradleWorkspace service lets users obtain references to Gradle builds. getBuild(IProject) loads a Gradle build from the workspace with the existing build configuration. createBuild(BuildConfiguration) creates a new Gradle build with the target configuration. Those methods don’t change the state of the workspace, they just return a reference to the builds.

interface GradleWorkspace {
    ...
    GradleBuild getBuild(IProject project)
    GradleBuild createBuild(BuildConfiguration configuration)
}

GradleBuild is the interface to interact with the builds. The synchronize() method executes the project synchronization and describes the results in the return value both for successful and failed invocations. An exception is only thrown upon invalid parameters.

interface GradleBuild {
    SynchronizationResult synchronize(IProgressMonitor monitor)
}

SynchronizationResult describes the outcome of the synchronization.

interface SynchronizationResult {
    IStatus getStatus()
}

Test coverage

• Importing valid projects
  • When the workspace is empty then all projects are included
  • When project name already used in workspace then the synchronization fails and only root project is imported
  • The current Gradle workspace setting is used for the synchronization
• Importing invalid projects
  • When root project with a custom name is on the default location then the synchronization fails and no projects are imported
  • When subproject with a custom name is on the default location then synchronization fails and only the root project is imported
  • When there is an error in Gradle build then the synchronization fails and only the root project is imported
• Synchronizing existing projects
  • When an existing project is being synchronized then the synchronization uses the current build configuration
• Cancellation
  • When cancellation is called then the synchronization stops after current work item is finished
• Invalid input
  • When createBuild() is invoked with a null argument then a runtime exception is thrown.
  • When createBuild() is invoked with a nonexisting file argument then a runtime exception is thrown.
  • When synchronize() is called with a null build identifier then a runtime exception is called.
  • When synchronize() is called with a null progress monitor then the synchronization succeeds correctly.
• Concurrency and scheduling rules
  • When the current thread has no scheduling rule then the synchronization should use the workspace root rule.
  • When the current thread has a custom scheduling rule then the rule should be replaced with a multiple containing the current rule and the workspace root rule.
  • When the current thread has the workspace root scheduling rule already then it should be unchanged during the synchronization.
  • When multiple synchronization actions are started at the same time then the synchronization should execute one-by-one, sequentially.