Skip navigation links

Introduction

This document lists changes made to the Gradle Project API.


Index of APIs

Incompatible changes by date

Fuller descriptions of all changes can be found below (follow links).

Not all deprecations are listed here, assuming that the deprecated APIs continue to essentially work. For a full deprecation list, please consult the Javadoc.

All changes by date

Changes by version

These API specification versions may be used to indicate that a module requires a certain API feature in order to function. For example, if you see here a feature you need which is labelled 1.20, your manifest should contain in its main attributes the line:

OpenIDE-Module-Module-Dependencies: org.netbeans.modules.gradle/0 > 1.20

Changes by affected class

org.netbeans.modules.gradle.api.execute.ActionMapping

org.netbeans.modules.gradle.api.BuildPropertiesSupport

org.netbeans.modules.gradle.spi.actions.GradleActionsProvider

org.netbeans.modules.gradle.api.GradleBaseProject

org.netbeans.modules.gradle.api.GradleConfiguration

org.netbeans.modules.gradle.api.execute.GradleExecConfiguration

org.netbeans.modules.gradle.api.GradleTask

org.netbeans.modules.gradle.spi.execute.JavaRuntimeManager

org.netbeans.modules.gradle.api.NbGradleProject

org.netbeans.modules.gradle.api.execute.RunConfig

org.netbeans.modules.gradle.api.execute.RunUtils

org.netbeans.modules.gradle.spi.newproject.TemplateOperation


Details of all changes by API and date


Gradle Project API

Gradle project problems have severity and stacktraces

Nov 13 '23; API spec. version: 2.38; made by: sdedic

Reports from the NB tooling gradle plugin are now annotated by severity.

Some Gradle Settings Removed from Use

Oct 2 '23; API spec. version: 2.36; affected top-level classes: TemplateOperation; made by: lkishalmi

Setting the following properties: startDaemonOnStart, silentInstall, and noRebuild are no longer in use. Their setters are no-ops,their getters returning false.

The gradleVersion setting has also been deprecated, in favor of using Gradle Wrapper as a way to specify the Gradle Version used for a project. It is still possible to use specific version of Gradle by using custom Gradle version. The getter for the gradleVersion returns the version of the Gradle Tooling API bundled with the IDE.

Method to set the Gradle version when initalizing the wrapper

Aug 14 '23; API spec. version: 2.34; affected top-level classes: TemplateOperation; made by: neilcsmith

Added additional addWrapperInit method allowing to request a specific version or version label when initializing the Gradle wrapper.

Adding JavaRuntimeManager abstracting the Gradle Runtime from Java Platform

Jan 13 '23; API spec. version: 2.32; affected top-level classes: JavaRuntimeManager RunUtils; made by: lkishalmi

Introduced a JavaRuntimeManager to create abstraction between the necessary runtime that Gradle needs (just a Java home) and the actual JavaPlatform which is provided by the modules in the Java cluster.

JavaRuntime is bound to be the root project of a project tree from now. The ID of the active rintime is stored in the gradle.properties of the root project under the property name netbeans.hint.jdkPlatform.

There are two new methods provided in RunUtils to get and set the active runtime of a project.

Representing external tasks

Oct 11 '22; API spec. version: 2.29; affected top-level classes: GradleTask; made by: sdedic
Tasks declared by other projects are marked as 'external'. Tasks can report their declaring project's path.

New APIs that provide access to values of build properties and tasks.

Oct 4 '22; API spec. version: 2.28; affected top-level classes: GradleBaseProject BuildPropertiesSupport; made by: sdedic

Gradle buildscript objects are introspected from within the gradle instance. All active plugins are enumerated. Extensions are detected. An API is provided to get dependent task, or a closure of the dependents, and to check tasks' type to identify tasks of interest. See GradleBaseProject.getTaskPredecessors() and GradleBaseProject.isTaskInstanceOf()

Certain task and extension property values can be accessed by APIs, that allows NetBean plugins to access configuration of tasks within the script. See BuildPropertiesSupport.

Expose regular Lookup in NbGradleProject.

Oct 4 '22; API spec. version: 2.28; affected top-level classes: NbGradleProject RunUtils; made by: sdedic

NbGradleProject offered just projectLookup(Class), that cannot return more instances or deliver change events. A regular Lookup instance, that switch when the project reloads is now available from NbGradleProject.refreshableProjectLookup().

Minor API changes giving access to a complete RunConfig for a project action or an action mapping.

Rich exception reports are exported from Gradle process.

Aug 20 '22; API spec. version: 2.27; made by: sdedic
Errors are transferred including their causes and script location(s), so the IDE may provide better messages or hints.

The new class GradleReport that contain this information is available from GradleBaseProject.getProblems() method.

Allow to inspect dependency tree

Aug 12 '22; API spec. version: 2.27; affected top-level classes: GradleBaseProject GradleConfiguration; made by: sdedic
Gradle APIs allow to list dependencies as a flat list, mixing the 4th+ party dependencies in. The API extension allows to inspect the dependency structure and determine what configuration the dependency originates from.

GradleFiles.Kind.VERSION_CATALOG introduced

Jul 15 '22; API spec. version: 2.25; affected top-level classes: NbGradleProject; made by: lkishalmi
GradleFiles.Kind.VERSION_CATALOG was addedd to represent $rootDir/gradle.libs.versions.toml file of the project. GradleFiles.getKind(VERSION_CATALOG) can be used to retrieve the represented file. (The file might not exists though.)

GradleFiles can be obtained from API

Apr 30 '22; API spec. version: 2.24; affected top-level classes: NbGradleProject; made by: sdedic
GradleFiles can be obtained from NbGradleProject instance. Gradle project users can use GradleFiles to get important files or pathnames in the project.

GradleCommandLine Flag, Parameter, and Property implements GradleOptionItem interface

Feb 17 '22; API spec. version: 2.23; made by: lkishalmi

Added GradleOptionItem interface to GradleCommandLine in order to support a common interface for Flaf, Parameter, and Property enums.

GradleCommandLine also can be aware of the GradleDistribution it is plan to be used with, so it got a few new constructors supporting that.

RunUtils.getCompatibleGradleDistribution is added to help retrieve the closest Gradle distribution a project could use to invoke Gradle build actions.

NetBeans Tooling plugin recognizes "runWorkingDir" and "runEnvironment" properties.

Sep 23 '21; API spec. version: 2.21; made by: entlicher
Introduced runWorkingDir and runEnvironment project properties that can be passed to NetBeans Tooling plugin in order to inject user parameters into gradle JavaExec task configurations. The property runWorkingDir shall contain an absolute path of the working directory. The property runEnvironment shall contain possibly quoted space-separated expressions of VAR_NAME=VAR_VALUE, or !VAR_NAME. The VAR_NAME=VAR_VALUE sets environment variable VAR_NAME to value VAR_VALUE and !VAR_NAME removes variable VAR_NAME from the set of environment variables.

Request project creation via Gradle init.

Aug 8 '21; API spec. version: 2.20; affected top-level classes: TemplateOperation; made by: sdedic
Use createGradleInit to ask Gradle to create new project using its init functionality.

Action can be disabled for a configuration.

Jun 19 '21; affected top-level classes: ActionMapping; made by: sdedic
GradleActionsProviders may disable action in a provided configuration, for example if the configured environment does not permit the action to be run.

Support for Project Configurations

May 30 '21; API spec. version: 2.13; affected top-level classes: GradleExecConfiguration RunUtils RunConfig GradleActionsProvider; made by: sdedic

Concept of ProjectConfigurations was implemented for Gradle projects with GradleExecConfiguration class. Configurations can be created by the user and are stored in project private/shared configuration storage. Configurations can be contributed by Plugins using GradleActionsProvider. A configuration can be activated or explicitly requested for action invocation..

Actions can have different ActionMappings in individual Configurations, user-defined or provided for specific configuration by GradleActionsProvider.

Action providers can be added fully declarative, using XML layer: See DefaultGradleActionsProvider.forProjectLayer

Added API to reload Gradle project information.

Apr 18 '21; API spec. version: 2.11; affected top-level classes: NbGradleProject; made by: sdedic; issues: NETBEANS-5627
Project information can be refreshed to a desired quality using NbGradleProject.toQuality. The caller may chain after reload completes or block until the project is loaded.

GradleDistributionManager can detect local Gradle Distributions

Apr 12 '21; API spec. version: 2.10; made by: lkishalmi
Added GradleDistributionManager.availableLocalDistributions() method to help detection the already available GradleDistribution-s installed in the system.

NetBeans Tooling plugin recognizes "runJvmArgs" property

Mar 27 '21; API spec. version: 2.9; made by: sdedic
Introduced runJvmArgs project property that can be passed to NetBeans Tooling plugin in order to inject user JVM parameters into gradle JavaExec task configurations. The property value shall contain whitespace-separated JVM arguments.

Project trust dialog can be customized by branding

Mar 3 '21; API spec. version: 2.8; made by: sdedic
Branding API can be used to select and order options present in "Trust Gradle project for execution" confirmation dialog. See RunUtils.isProjectTrusted.

Make ProjectActionMappingProvider available for other modules.

Jan 1 '21; API spec. version: 2.7; made by: lkishalmi

Experimental settings, openLazy and disableDiskCache in GradleSettings made deprecated and no longer affect the IDE behavior.

Make ProjectActionMappingProvider available for other modules.

Oct 15 '20; API spec. version: 2.6; made by: lkishalmi

Made ProjectActionMappingProvider available for other modules, so they either can provide an alternative implementation or most probably able to take a sneak peek on the current action configuration.

In order to make other modules interpret the action mapping in context RunUtils got a new evaluateActionArgs utility method which can replace tokens provided in ActionMapping arguments.

Finally to support this token replacement, ReplaceTokenProvider got a new static method replaceTokens.

Default for reusing tabs

Oct 15 '20; API spec. version: 2.5; made by: jtulach

Introducing branding APIs to configure default value for reusing tabs in Gradle projects.

GradleFiles SPI has the methods to deal with the buildSrc project.

Oct 7 '20; API spec. version: 2.4; made by: lkishalmi

GradleFiles.isBuildSrcProject() was added to detect if a project id a buildSrc project, and a new file Kind has been introduced BUILD_SRC.

Expose Gradle ProjectConnection through Project's Lookup.

Aug 21 '20; API spec. version: 2.4; made by: lkishalmi

Gradle's ProjectConnection is now available on the project lookup, making possible for modules to interact with Gradle in deeper level.

Expose GradleDistribution manager as an API.

Aug 21 '20; API spec. version: 2.4; made by: lkishalmi

Starting to give the project more freedom over control of their GradleDistribution in use, the previously non-API GradleDistributionManager got a review and got moved into execution apis. Together with the GradleDistributionProvider (API/SPI) it is possible to fetch information on the Gradle Distribution used in the project.

GradleDistributionProvider has a default implementation it is not necessary to implement it. With that new interface the RunUtils.evaluateGradleDistribution() got deprecated.

Remove Java Platform dependency.

Jul 15 '20; API spec. version: 2.3; made by: lkishalmi

Due to recent movement and the plan to support Gradle native projects as well in the future the dependency on Java Platform module has been removed.

The removal affects RunUtils.getActivePlatform methods. The method returns a Pair with null as second which indicates a broken Platform. This is for keeping the binary compatibility only. These methods shall be not used at all. There is no replacement planned for these API functions.

Added GradleJavaPlatformProvider which can be put into the project lookup, to be able to specify the JDK to be used for Gradle build execution.

Introduce Trust relationship with Gradle Projects to prevent unintentional Gradle invocation.

Jun 24 '20; API spec. version: 2.2; made by: lkishalmi

Gradle projects are maintaining a trust attribute from now. This trust is based on the NetBeans user directory and the a secret placed in the Gradle Root project directory.

Trusting any project of a multi-project Gradle build means trust all project in that multi-project project, as the trust is placed on the root project.

This change is backported to version 2.0.1 as well.

Added RunUtils.isProjectTrusted(Project,boolean) where plugin can check if a project is trusted or request one time trust with interactive mode.

There is no API/SPI to mark a project trusted/untrusted. Projects are not trusted by default, but become trusted once a priming build is requested or a Gradle task is invoked as a result of an user action.

Added GradleSettings.GradleExecutionRule with setter ad getter in GradleSettings as a global option to how to treat automatic Gradle Execution globally.

Move Gradle Tooling API to a separate module.

Apr 4 '20; API spec. version: 2.0; made by: lkishalmi; issues: NETBEANS-4118

The Gradle Tooling API has been removed from this module to its own into: org.netbeans.modules.libs.gradle

Modules depending on previous versions of this module need an additional dependency on the new library module. The main reason behind this split is that it is easier to do Gradle Tooling API update in the future.

                    <dependency>
                        <code-name-base>org.netbeans.modules.libs.gradle</code-name-base>
                        <compile-dependency/>
                        <run-dependency>
                            <release-version>6</release-version>
                            <specification-version>6.3</specification-version>
                        </run-dependency>
                    </dependency>
                

Note: The specification version of the org.netbeans.modules.libs.gradle module is matching the provided Gradle Tooling API version. The release version number follows the major version.

Besides of the library removal the source code provided in this module are backward compatible.

Added RunUtils.cancelGradle(RunConfig) to allow plugins to cancel an executed Gradle process.

Oct 22 '19; API spec. version: 1.4; affected top-level classes: RunUtils; made by: lkishalmi; issues: NETBEANS-3279

Added RunUtils.cancelGradle(RunConfig) to allow plugins to cancel an executed Gradle process.