Introduction

This document lists changes made to the 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.

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.projectapi/1 > 1.20

Changes by affected class

org.netbeans.spi.project.ActionProgress

org.netbeans.spi.project.ActionProvider

org.netbeans.spi.project.AuxiliaryProperties

org.netbeans.api.project.ContainedProjectFilter

org.netbeans.spi.project.DependencyProjectProvider

org.netbeans.api.project.FileOwnerQuery

org.netbeans.spi.project.LookupMerger

org.netbeans.spi.project.LookupProvider

org.netbeans.spi.project.support.LookupProviderSupport

org.netbeans.spi.project.MoveOrRenameOperationImplementation

org.netbeans.spi.project.NestedClass

org.netbeans.api.project.ProjectActionContext

org.netbeans.spi.project.ProjectConfiguration

org.netbeans.spi.project.ProjectConfigurationProvider

org.netbeans.spi.project.ProjectContainerProvider

org.netbeans.spi.project.ProjectFactory2

org.netbeans.spi.project.ProjectIconAnnotator

org.netbeans.api.project.ProjectManager

org.netbeans.spi.project.ProjectManagerImplementation

org.netbeans.spi.project.ProjectServiceProvider

org.netbeans.api.project.ProjectUtils

org.netbeans.spi.project.SingleMethod

org.netbeans.api.project.SourceGroup

org.netbeans.api.project.SourceGroupModifier

org.netbeans.spi.project.SourceGroupModifierImplementation

Details of all changes by API and date

Project API

Added action for running tests in parallel

Dec 2 '24; API spec. version: 1.99; affected top-level classes: ContainedProjectFilter ActionProvider NestedClass; made by: petrovic-d

ActionProvider.COMMAND_TEST_PARALLEL was introduced in order to allow running tests in parallel. ContainedProjectFilter was added and it can be used to pass list of projects the project action should apply to. NestedClass was added in order to support nested classes.

Added ProjectActionContext that can pass action-like environment to project queries

Aug 10 '22; API spec. version: 1.89; affected top-level classes: ProjectActionContext; made by: sdedic

ProjectActionContext can be used to inform various project queries about the intended action or environment for which the value is requested. This contract is optional for query implementors.

Added ProjectUtils.get/setActiveConfiguration convenience methods

Aug 10 '22; API spec. version: 1.89; affected top-level classes: ProjectUtils; made by: sdedic

Clients do not need to interact with Project's Lookup and ProjectConfigurationProvider directly, handling missing provider and mutex; they can use the convenience API method.

Added ActionProvider.COMMAND_PRIME that initializes the project for IDE use.

Mar 5 '21; API spec. version: 1.80; made by: sdedic

ActionProvider.COMMAND_PRIME was introduced, so that projects can declare (and enable/disable as needed) an action that "primes" or initializes the project for the IDE. That often includes downloads, or partial build, which may produce messages, and could be automated by project-opening code.

Added ParentProjectProvider and RootProjectProvider to improve project hierarchy discovery

Jan 2 '21; API spec. version: 1.79; made by: lkishalmi; issues: NETBEANS-5204

ParentProjectProvider and RootProjectProvider with correspondig utility methods in RootProjectProvider to improve project hierarchy discovery.

Added a SourceGroupRelativeModifierImplementation to improve source root creation

Mar 20 '17; API spec. version: 1.68; affected top-level classes: LookupProviderSupport; made by: sdedic; issues: #253355

In presence of multiple source roots, e.g. several source folders, or test folders, some of them may be more related to the

Added a LookupMerger for SharabilityQueryImplementation2

Jun 8 '15; API spec. version: 1.64; affected top-level classes: LookupProviderSupport; made by: tzezula; issues: #253355

Added a factory method into the LookupProviderSupport creating a LookupMerger for SharabilityQueryImplementation2.

More information in ProjectManager.Result

Apr 30 '14; API spec. version: 1.60; affected top-level classes: ProjectManager; made by: tstupka; issues: #244126

Introduced ProjectManager.Result.getDisplayName() and ProjectManager.Result.getProjectType() to provide more information about a potential project via ProjectManager.isProject2(FileObject).

SPI interface for ProjectManager

Apr 7 '14; API spec. version: 1.59; affected top-level classes: ProjectManagerImplementation ProjectManager; made by: tzezula; issues: #210465

Added a SPI internface for ProjectManager allowing different implementations of ProjectManager

Nov 20 '13; API spec. version: 1.56; affected top-level classes: DependencyProjectProvider ProjectContainerProvider ProjectUtils; made by: mkleint; issues: #210465

Newly introduced interfaces DependencyProjectProvider and ProjectContainerProvider are meant as less general replacement for SubprojectProvider as they explicitly declaring their contract (DependencyProjectProvider the project's dependency projects and ProjectContainerProvider projects that are build as part of this project). Code using SubprojectProvider currently should evaluate if DependencyProjectProvider or ProjectContainerProvider contracts suit their usage better. Please note that the new interfaces are not mandatory for project types to implement and if it's missing, SubprojectProvider should be used.

New method createCompositeLookup(Lookup, Lookup) in LookupProviderSupport

Sep 26 '12; API spec. version: 1.49; affected top-level classes: LookupProviderSupport; made by: mkleint; issues: #200711

Introducing method LookupProviderSupport.createCompositeLookup(Lookup, Lookup) which is a more freeform variant of already existing method. The first parameter is expected to be the base lookup containing instances to be found in project lookup, the second parameter is a lookup containing just LookupProviders.

New constant UNOWNED in FileOwnerQuery to mark a folder as definitely not owned by any project.

May 30 '12; API spec. version: 1.46; affected top-level classes: FileOwnerQuery; made by: mkleint; issues: #212015

Introducing constant FileOwnerQuery.UNOWNED, a pseudoproject indicating just that a directory is definitely unowned. May be returned by either FileOwnerQueryImplementation.getOwner, in which case null is returned from FileOwnerQuery.getOwner. May also be passed to either FileOwnerQuery.markExternalOwner overload, in which case the standard directory search will be pruned at this point with no result.

Added ActionProgress

Mar 20 '12; API spec. version: 1.43; affected top-level classes: ActionProgress; made by: jglick; issues: #71515

A new callback was added permitting the invoker of a project action to be notified when the action completes.


Compatibility:

ActionProvider implementations should call the new progress listener if possible.

SourceGroup.contains no longer throws IllegalArgumentException

Nov 15 '11; API spec. version: 1.40; affected top-level classes: SourceGroup; made by: jglick; issues: #204271

For convenience and safety, the contains method no longer throws an unchecked exception; it proved infeasible to ensure the precondition even in the face of projects being renamed or deleted or similar dynamic changes to directory structure.


Compatibility:

Implementations previously throwing this exception should just return false now instead. Callers previously catching the exception, or making a special effort to ensure the precondition, no longer need do so.

Added LookupProviderSupport.createActionProviderMerger factory method

Sep 10 '11; API spec. version: 1.38; affected top-level classes: LookupProviderSupport; made by: tzezula; issues: #201737

Added LookupProviderSupport.createActionProviderMerger factory method to create a LookupMerger for merging multiple instances of ActionProvider in the project's Lookup.

Profiler actions are an integral part of the project infrastructure - just like the debugger actions

Mar 27 '11; API spec. version: 1.44; affected top-level classes: ActionProvider; made by: yardus; issues: #203519

In order to be able to fully integrate the profiler with the project infrastructure it is necessary to add three new constants to ActionProvider SPI for profiling a project, profiling a single file and profiling a test for single file.

Added ProjectIconAnnotator

Jun 24 '10; API spec. version: 1.33; affected top-level classes: ProjectIconAnnotator; made by: jbecicka; issues: #171516

A mechanism for changing the project node icon. You can use it for example to add a badge to the project's icon.

Added MoveOrRenameOperationImplementation

Apr 15 '10; API spec. version: 1.31; affected top-level classes: MoveOrRenameOperationImplementation; made by: jglick; issues: #183680

Extended interface giving projects the ability to implement a simple display name change more safely and efficiently.


Compatibility:

Existing implementations of MoveOperationImplementation should be revised to implement the extended interface.

API complement to CacheDirectoryProvider

Jul 21 '09; API spec. version: 1.26; affected top-level classes: ProjectUtils; made by: jglick; issues: #168414

Added ProjectUtils.getCacheDirectory to complement the SPI interface CacheDirectoryProvider.

introduction of SourceGroupModifier, a way to create SourceGroup if missing

Feb 18 '09; API spec. version: 1.24; affected top-level classes: SourceGroupModifier SourceGroupModifierImplementation; made by: mkleint; issues: #102711

SourceGroupModifier provides ways of create specific folders (SourceGroup root folders) in case they don't exist, eg. cannot be retrieved from Sources. The project supporting automated creation of SourceGroup root folders needs to provide SourceGroupModifierImplementation in the project's lookup.

Add annotations @ProjectServiceProvider and @LookupMerger.Registration

Jan 23 '09; API spec. version: 1.23; affected top-level classes: ProjectServiceProvider LookupMerger; made by: jglick; issues: #150194

Added annotations to register entries to project lookup individually. These can be used instead of implementing a LookupProvider. Since the entries are loaded on demand, this can help avoid needless class loading.


Compatibility:

Implementations of LookupProvider should be converted wherever possible.

Provide project icon without actually loading the project

Jan 13 '09; API spec. version: 1.22; affected top-level classes: ProjectManager ProjectFactory2; made by: mkleint; issues: #153923

Introducing ProjectFactory2 that extends ProjectFactory and return ProjectManager.Result instead of a simple boolean value. Also add ProjectManager.isProject2(FileObject) method that can be used by 3rd party modules that need a fast (yet not 100% reliable) way of finding the project icon for a folder.

Add annotation @LookupProvider.Registration

Nov 13 '08; API spec. version: 1.21; affected top-level classes: LookupProvider; made by: mkleint; issues: #152392

Add annotation @LookupProvider.Registration to replace registration in layer files.

Added class SingleMethod

Jul 9 '08; API spec. version: 1.19; affected top-level classes: SingleMethod; made by: mpetras; issues: #137191

Added class SingleMethod, which represents identification of a single method/function in a file. The new class also contains new constants (COMMAND_RUN_SINGLE_TEST_METHOD and COMMAND_DEBUG_SINGLE_TEST_METHOD) corresponding to commands for running debugging test methods.

Added ProjectUtils.getAuxiliaryConfiguration

Jun 9 '08; API spec. version: 1.17; affected top-level classes: ProjectUtils; made by: jglick; issues: #136333

A new API method was introduced to match the AuxiliaryConfiguration SPI interface. The change simplifies caller code, provides a path for future changes in the SPI, and allows project types to avoid providing an explicit implementation of this SPI if the fallback implementation suffices for their needs.


Compatibility:

Modules which formerly looked for AuxiliaryConfiguration directly in project lookup are strongly encouraged to migrate to the new method instead.

Added ProjectUtils.getPreferences.

Jun 9 '08; API spec. version: 1.16; affected top-level classes: ProjectUtils AuxiliaryProperties; made by: jlahoda; issues: #134580

Added new API method ProjectUtils.getPreferences and new SPI interface AuxiliaryProperties.


Compatibility:

Added support for composing project's lookup from multiple sources.

Oct 5 '06; API spec. version: 1.12; affected top-level classes: LookupProvider LookupMerger LookupProviderSupport; made by: mkleint; issues: #83343

Added interfaces and support classes that can be used to compose the project's lookup from multiple 3rd party sources. Framework for creating merged instances included. LookupMerger implementation for Sources added.


Compatibility:

Added support for project configurations

Sep 8 '06; API spec. version: 1.11; affected top-level classes: ProjectConfiguration ProjectConfigurationProvider; made by: jglick; issues: #49652

Added an interface ProjectConfigurationProvider which can be included in a project's lookup to support switchable configurations / profiles.

Added support for project delete/copy/rename/move

Aug 22 '05; API spec. version: 1.7; made by: jlahoda; issues: #61546

Introduced: New method notifyDeleted added to ProjectState. Interfaces DataFilesProviderImplementation, DeleteOperationImplementation, CopyOperationImplementation, MoveOperationImplementation has been added to support project delete/copy/rename/move. Support class ProjectOperations has been added to simplify operations on compound projects.


Compatibility:

The FileOwnerQuery.markExternalOwner allows registration of individal files and URIs

May 27 '05; API spec. version: 1.5; made by: jlahoda; issues: #58313

It is possible to register owner of an individual file using FileOwnerQuery.markExternalOwner. It is possible to register owner of a folder or file using URI, so the folder or file does not have to exist at the time of registration.


Compatibility:

This changes add a new method FileOwnerQuery.markExternalOwner(URI, FileObject, int), and also extends sematics of the existing FileOwnerQuery.markExternalOwner(FileObject, FileObject, int) method to allow registration of individual files.

Switched to major release version 1

Dec 22 '04; API spec. version: 1.3; made by: jglick; issues: #51468

To indicate that this is now considered a stable API, the major release version was incremented to 1 from 0.


Compatibility:

Clients should begin requesting the new version to avoid a warning at startup.