Overview

# Introduction

## What do the Dates Mean?

The supplied dates indicate when the API change was made, on the CVS trunk. From this you can generally tell whether the change should be present in a given build or not; for trunk builds, simply whether it was made before or after the change; for builds on a stabilization branch, whether the branch was made before or after the given date. In some cases corresponding API changes have been made both in the trunk and in an in-progress stabilization branch, if they were needed for a bug fix; this ought to be marked in this list.

- The `release41` branch was made on Apr 03 '05 for use in the NetBeans 4.1 release. Specification versions: 6.0 begins after this point.
- The `release40` branch was made on Nov 01 '04 for use in the NetBeans 4.0 release. Specification versions: 5.0 begins after this point.

# Index of APIs

- Modules API
- Uncategorized changes

# 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.

- (Jun 7 '05) Branding files used during startup have new location
- (May 7 '04) Removed compatibility handling of deprecated manifest sections
- (Nov 1 '02) API separation, phase II
- (Oct 15 '02) API separation, phase I

# All changes by date

- (Jul 7 '05) Enhanced support for OS specific modules
- (Jun 7 '05) Branding files used during startup have new location
- (Jun 4 '05) `openide.jar` is gone, update your module dependencies!
- (Apr 11 '05) Friend Modules
- (Aug 11 '04) Allow a module to be run only on some class of operating systems
- (May 7 '04) Removed compatibility handling of deprecated manifest sections
- (Dec 25 '03) Added method `ModuleInfo.getClassLoader()`
- (Dec 18 '03) Added ModuleInfo.getBuildVersion()
- (Jan 27 '03) Modules can declare their own dependency transformations
- (Nov 13 '02) Added `InstalledFileLocator`
- (Nov 1 '02) API separation, phase II
- (Oct 16 '02) Possible to deprecate an entire module
- (Oct 15 '02) API separation, phase I
- (Oct 7 '02) Module dependencies no longer considered transitive for purposes of classloading
- (May 16 '02) Modules can declare their public packages
- (May 8 '02) `Thread.contextClassLoader` defaults to `TopManager.systemClassLoader`
- (Jan 29 '02) Provides-requires semantics for module dependencies
- (Jan 29 '02) Ranged major release version dependencies
- (Jan 22 '02) JavaHelp split into a separate module
- (Aug 17 '01) Format of modules XML folder defined
- (Jul 31 '01) Can determine which module owns a given class
- (Jul 20 '01) Can supply localized messages for failed dependencies
- (Jul 16 '01) New module installer API
- (Apr 29 '01) JavaHelp may be registered via layer
- (Mar 8 '01) Can get the class implementing a manifest section
- (Feb 9 '01) Added long description for modules
- (Jan 22 '01) Can get JavaHelp help set reference as resource rather than URL
- (Jan 18 '01) Display category for modules
- (Dec 21 '00) Short description for modules
- (Nov 23 '00) Get layer as a resource, not URL
- (Nov 22 '00) Permit abbreviated sample class names in package dependencies
- (Nov 12 '00) Package-accessible classloader
- (Nov 2 '00) Support layer specification in a module manifest
- (Aug 27 '00) Manipulation of classloader used by a module
- (Mar 28 '00) `ModuleDescription` constructor may specify a classloader

# 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.openide.modules > 1.20

- (6.3) Enhanced support for OS specific modules
- (6.2) Branding files used during startup have new location
- (6.2) `openide.jar` is gone, update your module dependencies!
- (6.1) Friend Modules
- (4.48) Removed compatibility handling of deprecated manifest sections
- (4.44) Allow a module to be run only on some class of operating systems
- (4.21) Added method `ModuleInfo.getClassLoader()`
- (4.18) Added ModuleInfo.getBuildVersion()
- (3.33) Modules can declare their own dependency transformations
- (3.21) Added `InstalledFileLocator`
- (3.17) API separation, phase II
- (3.15) Possible to deprecate an entire module
- (3.14) API separation, phase I
- (3.12) Module dependencies no longer considered transitive for purposes of classloading
- (2.19) Modules can declare their public packages
- (2.3) Provides-requires semantics for module dependencies
- (2.3) Ranged major release version dependencies
- (2.2) JavaHelp split into a separate module
- (1.31) Format of modules XML folder defined
- (1.28) Can determine which module owns a given class
- (1.26) Can supply localized messages for failed dependencies
- (1.24) New module installer API
- (1.6) JavaHelp may be registered via layer

# Changes by affected class

## `org.openide.modules.Dependency`

- (Jan 29 '02) Provides-requires semantics for module dependencies
- (Jan 29 '02) Ranged major release version dependencies
- (Jul 16 '01) New module installer API

## `org.openide.modules.InstalledFileLocator`

- (Nov 13 '02) Added `InstalledFileLocator`

## `org.openide.modules.ModuleInfo`

- (Dec 25 '03) Added method `ModuleInfo.getClassLoader()`
- (Dec 18 '03) Added ModuleInfo.getBuildVersion()
- (Jan 29 '02) Provides-requires semantics for module dependencies
- (Jul 31 '01) Can determine which module owns a given class
- (Jul 20 '01) Can supply localized messages for failed dependencies
- (Jul 16 '01) New module installer API

## `org.openide.modules.ModuleInstall`

- (Jul 16 '01) New module installer API

## `org.openide.modules.SpecificationVersion`

- (Jul 16 '01) New module installer API

# Details of all changes by API and date

## Modules API

### Enhanced support for OS specific modules

Jul 7 '05; API spec. version: 6.3; made by: jtulach; issues: #50943
Modules can now express dependency on more operating system types than those that were available previously. Now there is `org.openide.modules.os.PlainUnix` token for all unixes but MacOSX and `org.openide.modules.os.OS2` for OS/2. For more details read here.

### Branding files used during startup have new location

Jun 7 '05; API spec. version: 6.2; made by: jtulach
Due to split of openide.jar some important branding files used during startup change their location. Especially the to splash screen picture, location and color of progress bar and the application icon are now in `org.netbeans.core.startup` package. Here is an example of the branding as used by NetBeans IDE.

### `openide.jar` is gone, update your module dependencies!

Jun 4 '05; API spec. version: 6.2; made by: jtulach; issues: #58258

The monolithic `openide.jar` has been split into many small JAR files and most of them were made autoload modules. That means they are loaded only on demand, which is going to simplify end of life of parts that are no longer needed.

The layout of files on disk changed and their content as well, but these changes shall have no effect on classes from `org.openide` packages during runtime. Modules using them will run unmodified. Althrough there will be printed warnings about upgraded module dependencies - one is adviced to use ant fix-dependencies in his projectized module to modify the `nbproject/project.xml`. The manifest's `OpenIDE-Module-IDE-Dependencies` attribute is deprecated and shall no longer be used. Enumerate the individual split submodules instead, as is done by the fix-dependencies task. Moreover one can depend on `OpenIDE-Module-Requires: org.openide.modules.ModuleFormat1` to express that it requires current format of module manifests - this tag is automatically inserted when running in projectized system.

The current layout of platform cluster directory is:

- `lib/boot.jar` contains what it used to have together with module system runtime independent of other NetBeans APIs.
- `lib/org-openide-util.jar` is next to boot.jar to provide the basic infrastructure used by boot.jar.
- `lib/org-openide-modules.jar` provides the APIs that the boot.jar implements.
- `core/core.jar` is loaded dynamically by the boot.jar and contains most of the startup code and the NetBeans dependent part of module system. For its implementation it needs filesystems which are along as well.
- `core/org-openide-filesystems.jar` the filesystems API is needed for the standard launch code to read module config files and listen to changes in their amount or content.
- `modules/org-openide-nodes.jar` and other openide libraries are now turned into real modules.
- `modules/org-netbeans-core.jar` is also a module and contains the rest of original core.jar. It is likely that this one is going to be split even more, as the UI could be separated to core/ui, etc.

### Friend Modules

Apr 11 '05; API spec. version: 6.1; made by: jtulach; issues: #54123
A module can now restrict the list of modules that can access its public packages, by enumerating their code names in manifest.

### Allow a module to be run only on some class of operating systems

Aug 11 '04; API spec. version: 4.44; made by: jtulach; issues: #46833
Modules can now declare that they run only on a specific version of operating system by requesting a presence of `org.openide.modules.os.MacOSX`, `org.openide.modules.os.Unix` or `org.openide.modules.os.Windows` token in their manifest:

                    OpenIDE-Module-Requires: org.openide.modules.os.Unix

Such a module will then be enabled only on specified class of operating systems. See also the modules api description.

### Removed compatibility handling of deprecated manifest sections

May 7 '04; API spec. version: 4.48; made by: jglick

Previously, a number of module manifest sections (e.g. `OpenIDE-Module-Class: FileSystem`) had been deprecated in favor of XML-layer-based installation, but a compatibility layer was left in place to permit old modules to still function as before. This layer has been removed.

Manifest-based installation of JavaHelp help sets was also removed.

Compatibility:

Modules which did not remove these manifest sections before must do so for NetBeans 4.0.

### Added method `ModuleInfo.getClassLoader()`

Dec 25 '03; API spec. version: 4.21; affected top-level classes: `ModuleInfo`; made by: jglick; issues: #38330
Added a new method `ModuleInfo.getClassLoader()` making it possible to find a Java class loader associated with an enabled module.
Compatibility: Note that although the new method is effectively abstract, this is a compatible change insofar as no one outside of the core module system should be subclassing `ModuleInfo`.

### Added ModuleInfo.getBuildVersion()

Dec 18 '03; API spec. version: 4.18; affected top-level classes: `ModuleInfo`; made by: jtulach; issues: #36064
The implementation version and the build number of modules can now be different. One can keep `OpenIDE-Module-Implementation-Version` unchanged to allow implementation dependencies and still identify the actual build version by specifying `OpenIDE-Module-Build-Version`. If omited the build version is equal to implementation version.

### Modules can declare their own dependency transformations

Jan 27 '03; API spec. version: 3.33; made by: jglick; issues: #30161

Modules may now declare their own transformations of module dependencies using a declarative XML syntax in the folder `ModuleAutoDeps/` in the system filesystem. This is useful for being able to manage major refactorings of functionality in a manner that will retain binary compatibility.

### Added `InstalledFileLocator`

Nov 13 '02; API spec. version: 3.21; affected top-level classes: `InstalledFileLocator`; made by: jglick; issues: #28683
This new service permits modules to find disk files associated with their installation. For example, files packed into an NBM alongside the module could be found in this way. Using the locator is both safer and more convenient than checking undocumented system properties or resorting to other tricks. Note that the NBM format is still not specified by the Open APIs; however, if there is a packaging format in use, then there should be a matching locator implementation that locates files bundled by it.
Compatibility: Existing module code which searches system properties such as `netbeans.home` and `netbeans.user` should be replaced with calls to the new supported API.

### Possible to deprecate an entire module

Oct 16 '02; API spec. version: 3.15; made by: jglick
The new manifest attribute `OpenIDE-Module-Deprecated` and localized attribute `OpenIDE-Module-Deprecation-Message` may be used to warn clients of an obsolete API module.

### Module dependencies no longer considered transitive for purposes of classloading

Oct 7 '02; API spec. version: 3.12; made by: jglick; issues: #27853
Prior to this change, if module B depends on module A, where A provides some public packages (implicitly or explicitly), and module C depends on module B, then module C could use public packages from A. Now it cannot, unless it also declares an explicit dependency on A.
Compatibility: Modules which fail to declare an API dependency on `IDE/1 > 3.12` or above will behave according to the old semantics: they may load classes and resources from undeclared indirect parent modules. But if they declare an API dependency on 3.12 or higher, the new semantics apply.

### Modules can declare their public packages

May 16 '02; API spec. version: 2.19; made by: jglick; issues: #19621

Modules which provide Java-level APIs to other modules can now specify which packages should be considered part of the public API. Other packages are blocked from client modules.

Utilizing this feature for already released modules is very dangerous. See issue #31637 for details.

### `Thread.contextClassLoader` defaults to `TopManager.systemClassLoader`

May 8 '02; made by: jglick; issues: #20663
The context class loader for all threads now defaults to the system class loader, capable of loading from modules and their extensions as well as the startup classpath. This is especially useful for modules bundling NetBeans-independent libraries such as JAXP which use the context class loader as a default whenever no particular class loader is specified to some registration mechanism.

### Provides-requires semantics for module dependencies

Jan 29 '02; API spec. version: 2.3; affected top-level classes: `Dependency` `ModuleInfo`; made by: jglick; issues: #18781
The manifest attributes `OpenIDE-Module-Provides` and `OpenIDE-Module-Requires` were introduced. These permit modules to depend on capabilities offered by other modules, without explicitly naming who the provider will be.

### Ranged major release version dependencies

Jan 29 '02; API spec. version: 2.3; affected top-level classes: `Dependency`; made by: jglick; issues: #19714
Module dependencies may now specify a range of major release versions, to indicate that the dependency is valid for all mentioned major releases. Though the API-providing module may have had some incompatible changes, none of them were found to be relevant to the depending module.

### JavaHelp split into a separate module

Jan 22 '02; API spec. version: 2.2; made by: jglick; issues: #19620 #27776

JavaHelp support is now in a separate module, `org.netbeans.modules.javahelp/1`. This module includes the `javax.help.**` packages, and it provides the token `org.netbeans.api.javahelp.Help` which signifies the ability to display help, for example using `TopManager.showHelp`, or by querying Lookup for an instance of `Help`.

New modules (declaring a dependency on APIs after 2.2) which wish to provide a helpset should continue to do so via XML layer, and need only require the token `org.netbeans.api.javahelp.Help`. New modules wishing to display help can either require this token and use `TopManager.showHelp`, or depend on the `org.netbeans.modules.javahelp/1` API module, require the token, query Lookup for an instance of `Help`, and use its methods directly. New modules wishing to use the `javax.help.**` packages directly should declare a dependency on the `org.netbeans.modules.javahelp/1` module rather than using a package dependency.

Compatibility:

Existing modules (with an API dependency earlier than 2.2, or none at all) for compatibility are given an automatic dependency on the `org.netbeans.api.javahelp.Help` token. Additionally, if they declared a package dependency on `javax.help.**`, they are given an automatic dependency on the `org.netbeans.modules.javahelp/1` module.

(Note: the automatic conversion of the package dependency is implemented by issue #27776, which was not fixed for the NetBeans 3.4 release, but will be for NetBeans 3.4.1. NetBeans 3.4 did, however, add automatic dependencies on the token, by far the more common case.)

Both layer- and manifest-based installation of help sets continue to be supported; manifest-based installation is still deprecated.

### Format of modules XML folder defined

Aug 17 '01; API spec. version: 1.31; made by: jglick; issues: #13921
Some aspects of the contents of the system `Modules/` folder and its XML files are now defined. Additionally, certain kinds of changes (module enablement or disablement) are now permitted to these XML files.

### Can determine which module owns a given class

Jul 31 '01; API spec. version: 1.28; affected top-level classes: `ModuleInfo`; made by: jpokorsky
Added `owns(Class)` to determine if the provided class was loaded as a part of the module.

### Can supply localized messages for failed dependencies

Jul 20 '01; API spec. version: 1.26; affected top-level classes: `ModuleInfo`; made by: jglick
Permitting main attributes `OpenIDE-Module-Module-Dependency-Message` and `OpenIDE-Module-Package-Dependency-Message`.

### New module installer API

Jul 16 '01; API spec. version: 1.24; affected top-level classes: `ModuleInfo` `Dependency` `SpecificationVersion` `ModuleInstall`; made by: jglick
New module installer and corresponding API enhancements. `ModuleDescription`, `ManifestSection`, and `IllegalModuleException` deprecated. `ModuleInfo`, `Dependency`, `SpecificationVersion`, and `ModuleInstall.validate` added. Module information available from lookup. Localized properties may be stored in bundles.

### JavaHelp may be registered via layer

Apr 29 '01; API spec. version: 1.6; made by: jglick
Added ability to specify JavaHelp help sets and links from layer, or generally XML file.

### Can get the class implementing a manifest section

Mar 8 '01
Added method `getSectionClass()`.

### Added long description for modules

Feb 9 '01; made by: jglick
Added `getLongDescription` and `TAG_LONG_DESCRIPTION`.

### Can get JavaHelp help set reference as resource rather than URL

Jan 22 '01; made by: jglick
Added `getDescriptionResource`. Retrieving as URL deprecated.

### Display category for modules

Jan 18 '01; made by: jglick
Added `getDisplayCategory` and `TAG_CATEGORY`.

### Short description for modules

Dec 21 '00; made by: jglick
Added `getShortDescription` and `TAG_SHORT_DESCRIPTION`.

### Get layer as a resource, not URL

Nov 23 '00; made by: jglick
`getLayerResource()` added. Thus all locale variants of a layer may be merged together. Retrieval as URL is deprecated.

### Permit abbreviated sample class names in package dependencies

Nov 22 '00; made by: jglick
Slight extension to package dependency syntax to allow abbreviated sample name.

### Package-accessible classloader

Nov 12 '00; made by: jglick
Inner interface `PackageAccessibleClassLoader` added to make it easier to check package dependencies. Package dependencies which include sample classes are now permitted.

### Support layer specification in a module manifest

Nov 2 '00; made by: jglick
Now also understands `OpenIDE-Module-Layer` tag that can specify a resource path to XMLFileSystem that is provided by the module. Also added method `getLayer()` that returns the URL of XML filesystem if provided.

### Manipulation of classloader used by a module

Aug 27 '00; made by: jglick
Added methods `getClassLoader`, `setClassLoader` and `getBadClasses`.

### `ModuleDescription` constructor may specify a classloader

Mar 28 '00; made by: jglick
Constructors may now specify a classloader to use rather than setting it later.

## Uncategorized changes

### API separation, phase II

Nov 1 '02; API spec. version: 3.17; made by: jglick; issues: #19443

Three sections of the Open APIs were split into new autoload modules.

- The module `org.openide.compiler` (version 1.0) contains the Compiler API and some other classes directly related to it.

- The module `org.openide.execution` (version 1.0) contains the Execution API and some other classes directly related to it.

- The module `org.openide.io` (version 1.0) contains `InputOutput` and related classes (formerly part of the Window System API, and still physically in the `org.openide.windows` package).

New modules wishing to use these APIs must declare regular module dependencies on them. Future changes in these APIs will be documented separately.

Furthermore, modules wishing to use certain services must `OpenIDE-Module-Require` them if appropriate:

- `org.openide.compiler.CompilationEngine`, in order to call `CompilationEngine.getDefault()`, or safely use `AbstractCompileAction` or one of its subclasses, or call `CompilerJob.start()`, or use `BeanInfo`s for Compiler API classes, etc.

- `org.openide.execution.ExecutionEngine`, in order to call `ExecutionEngine.getDefault()`, or safely use `ExecuteAction`, or call `Executor.execute(...)`, or use `BeanInfo`s for Execution API classes, etc.

- `org.openide.windows.IOProvider`, in order to call `IOProvider.getDefault()`.

Other minor changes:

- Registration of URL stream handler factories using `NbfsStreamHandlerFactory.register(...)` is deprecated. Simply create an instance of `URLStreamHandlerFactory` and add it to Lookup instead.

- The method `FileUtil.nbfsURLStreamHandler` was added, but is not intended for use by modules.

- All uses of `ExecInfo` are deprecated as they abuse the distinction between Filesystems and the user classpath. Use and override only `Executor.execute(DataObject)`. Similarly, `ThreadExecutor` is deprecated for the time being because it suffers from similar problems.

- Direct use of `NbfsURLConnection` is deprecated in favor of the more general `URLMapper` from the Filesystems API.

- Package dependencies on `org.netbeans.lib.terminalemulator` must be replaced with module dependencies on a new autoload module `org.netbeans.lib.terminalemulator` (version 1.0).

- Several static convenience methods have been added to `AbstractCompileAction`. Of most interest is `prepareJobFor`. Module code should no longer assume that `DataFolder` has a `CompilerCookie` which recursively compiles the folder and subfolders (according to depth); while it is still true, for reasons of compatibility, new code should use `prepareJobFor` to create a compiler job from a folder.

Compatibility:

Module authors using the now-separated APIs will need to adjust their compilation classpaths to include the new JAR files. Modules wishing to use recent APIs and declaring a current openide specification version dependency will need to explicitly declare dependencies on these new APIs if there are any.

For compatibility, modules with no declared Open APIs dependency, or declared on a version prior to 3.17, will have their dependencies automatically refined as if to include the declarations:

    OpenIDE-Module-Module-Dependencies: org.openide.compiler > 1.0,
      org.openide.execution > 1.0, org.openide.io > 1.0
    OpenIDE-Module-Requires: org.openide.compiler.CompilationEngine,
      org.openide.execution.ExecutionEngine, org.openide.windows.IOProvider

And any package dependencies from old modules on `org.netbeans.lib.terminalemulator` will be converted to module dependencies.

Binary-compatible

### API separation, phase I

Oct 15 '02; API spec. version: 3.14; made by: jglick; issues: #19443 #20898

Many classes were moved to a separate module, `openide-deprecated.jar`, not available to modules by default. Uses of these classes in modules should be cleaned up whenever possible.

Additionally, the entire contents of `org.openide.src.*` and `org.openide.src.nodes.*`, as well as `org.openide.cookies.SourceCookie` and some associated property editors, were moved to a separate module.

The most common apparent symptom for module authors will be the absence of `TopManager`. Most methods in this class have been replaced by newer utility classes in a straightforward manner. See the Upgrade Guide.

Compatibility:

The deprecated classes continue to be available in the module `org.openide.deprecated` which you may depend on it you cannot remove uses of the deprecated APIs. In order for `TopManager.getDefault()` to work, you must also require the token `org.openide.TopManager`, which is provided by an unspecified module. The deprecated API module and its implementation module are autoloads, meaning they will not be loaded unless some module still requires them.

Similarly, the Java Hierarchy API was moved to the module `org.openide.src` which you should depend on in order to use this API.

For compatibility, the above three dependencies are added to your module automatically in case it either requests no specific API version at all, or requests an API version prior to 3.14. Modules requesting APIs 3.14 or higher must declare these dependencies explicitly if they in fact need them.

Binary-compatible

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.