站内搜索: 请输入搜索关键词
当前页面: 在线文档首页 > NetBeans API Javadoc 5.0.0

Change History for the Modules API - NetBeans API Javadoc 5.0.0

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.

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

Changes by affected class

org.openide.modules.Dependency

org.openide.modules.InstalledFileLocator

org.openide.modules.ModuleInfo

org.openide.modules.ModuleInstall

org.openide.modules.SpecificationVersion

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:

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.

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:

Other minor changes:


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 May 3 2007.  |  Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.