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.

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:

Feb 18 '16; API spec. version: 7.45; affected top-level classes: DestroyableNodesFactory; made by: phejl; issues:
#257941ChildFactory
is useful for creating node children lazily on a background thread,
and for simplifying working with Children.Keys. One oversight in
the original API was providing for notification that the nodes created
by the ChildFactory are no longer in use and should clean up any
resources.

DestroyableNodesFactory is an abstract class which adds
destroyNodes methods to ChildFactory.Detachable.

Nov 25 '08; API spec. version: 7.7; affected top-level classes: ChildFactory; made by: tboudreau; issues:
#153347ChildFactory
is useful for creating node children lazily on a background thread,
and for simplifying working with Children.Keys. One oversight in
the original API was providing for notification that the ChildFactory
is no longer in use and should clean up any resources and detach
any listeners it can.

ChildFactory.Detachable is an abstract class which adds
addNotify() and removeNotify() methods to ChildFactory. addNotify()
is called immediately before the first call to createKeys() after
creation or a call to removeNotify().

Aug 4 '08; API spec. version: 7.7; affected top-level classes: ChildrenNodeMemberEventNodeReorderEvent; made by: t_h; issues:
#121913Children.Keys
with lazy behavior can be created by using Children.Keys(boolean lazy).
Children.getNodesCount(boolean optimalResult) can be
used instead of Children.getNodes(boolean optimalResult)
for children "initialization". While keeping same behavior as
Children.getNodes(boolean optimalResult) for "default"
(non-lazy) implementation it allows full initialization without need to
create all nodes. Children.snapshot() creates an immutable snapshot representing
the current view of the nodes in this children object. Such snapshots are available in
NodeMemberEvent and
NodeReorderEvent
via getSnapshot() and provide information about state of nodes
in time when events were emited.

Jun 1 '07; API spec. version: 7.1; made by: tboudreau; issues:
#91529
Added the class
ChildFactory
and the method
Children.create(ChildFactory factory, boolean asynchronous)
to the API. This simplifies creation of Node children which need
to be computed on a background thread for performance reasons.
Anyone wishing to do this can simply extend ChildFactory and
pass that to Children.create() to automatically get a Node that will
display a Please Wait child node when first expanded. A ChildFactory
can either compute all child nodes, or batch them in multiple
passes.

ChildFactory can also be used to implement synchronous children,
by setting the asynchronous parameter passed to
Children.create() to false. This could replace most
common usages of Children.Keys, and make it easy to switch to
asynchronous child computation if that is determined to be
necessary for performance reasons.

Nov 6 '06; API spec. version: 7.0; affected top-level classes: CookieSet; made by: jtulach; issues:
#62707
New method
CookieSet.createGeneric has been added. It allows to create
an instance of
CookieSet that can contain any object, not just
Cookies.
This addition change is accompanied with two additional changes:
CookieSet now implements
Lookup.Provider and thus has a method getLookup to
allow queries for of its content.
Also there is a new method
assign(clazz, instances) that allows to add/remove
plain old java objects to the CookieSet.

Jul 14 '05; API spec. version: 6.5; affected top-level classes: AbstractNode; made by: pnejedly; issues:
#53461
Adding possibility for AbstractNode to use PNG files
as icons. Adding new final method
setIconBaseWithExtension(String baseExt)
which replaces the original method for manipulating icon base,
setIconBase(String).
The original (now deprecated) method stil works the same way,
using ".gif" as extension
The original method setIconBase(String) delegates
to the new one, using the default extension.

Feb 13 '04; API spec. version: 4.25; affected top-level classes: FilterNode; made by: pnejedly; issues:
#31006
From this version, the FilterNode by default delegates all
getValue(String) and setValue(String, Object)
calls the to the original node. Also, FilterNode now exports two
new constants, FilterNode.DELEGATE_SET_VALUE and
FilterNode.DELEGATE_GET_VALUE, which can be used to control
the delegation of the above mentioned methods.

Jul 16 '03; API spec. version: 4.9; affected top-level classes: Nodeorg.openide.explorer.propertysheet.InplaceEditororg.openide.explorer.propertysheet.PropertyEnvorg.openide.explorer.propertysheet.PropertySheetorg.openide.explorer.propertysheet.PropertySheetSettings; made by: tboudreau; issues:
#29447
New interface that allows a property editor to supply an inline editor
for the new property sheet added, as part of merging the new property
sheet. A method, registerInplaceEditorFactory() has been added to PropertyEnv to allow
modules to supply an inplace editor globally for all properties of a
given type; also, Node.Property objects may supply a custom inplace editor
instance via the hint "inplaceEditor" in getValue(String).

PropertySheetSettings is an old SystemOption subclass that offers
settings that affect the display of the property sheet. These settings
are irrelevant to the new property sheet.

In order to provide some performance optimizations, it was
necessary to un-final the class PropertyEnv. However, it
should be treated as final outside the package - there should
never be a need to subclass it. A note has been added to
its javadoc to this effect.

A non-normative hint may now be supplied by instances of Node.PropertySet
to return a localized display name for a tab which the property sheet
should use for displaying that and any other property sets which share
the name: "tabName".

Feb 26 '03; affected top-level classes: NodeOp; made by: pzavadsky; issues:
#31476
The utility method NodeOp.findActions(Nodep[]) is changed
the way it returns an empty array instead of null (for the cases
there are no actions found). Also javadoc is refined in that sense.
Compatibility:
In fact this is just a slight refinement of the API intoduced by 3.29 change.

Nov 8 '02; API spec. version: 3.19; affected top-level classes: Node; made by: dstrupl
Method public boolean isDefaultValue() has been added to class Node.Property.
The idea behind this is to visually mark modified properties in the property sheet.
If the method returns false it means that the value has been modified by the user
and visual feedback will be shown. The reason why the default impl is
returning true is to make the old properties (properties using previous
version of the API) look the same as they did before the change.

Oct 3 '02; API spec. version: 3.11; affected top-level classes: Node; made by: jtulach; issues:
#26790
Node has been extended to provide method getLookup that allows better
querying possibilities than the old Node.getCookie method. New constructors
have been provided to allow to pass a Lookup instance to newly created
node. In such case Node.getCookie delegates to the provided instance,
otherwise Node.getLookup delegates to Node.getCookie content.

Jul 15 '02; API spec. version: 3.1; affected top-level classes: Node; made by: phrebejkNode has new method setChildren(Children) which allows
to change the Children of given Node. Node also fires
new PropertyChangeEvent(PROP_LEAF) whenever changing
children from non-LEAF to LEAF and vice-versa.

May 2 '02; API spec. version: 2.17; affected top-level classes: Children; made by: pnejedlyAdded an additional getNodes() method when the API
user can specify whether he need the most right result.
The method is needed for code-based navigation through nodes,
like scripting, and for testability.
SPI implementors can implement it better.

Feb 28 '02; API spec. version: 2.6; affected top-level classes: CookieSet; made by: dstrupl; issues:
#15373 The API for CookieSet was not symmetrical. You could add factories but there
was no way to remove them.

Oct 11 '01; API spec. version: 1.37; affected top-level classes: IndexIndexedCustomizer; made by: jglick; issues:
#9323
The static method Index.Support.showIndexedCustomizer(Index)
was added to provide a simpler way of displaying a dialog to reorder a
set of nodes based on an index cookie. Unlike direct use of the
IndexedCustomizer dialog, it interacts smoothly with the
IDE's window system.
Compatibility:
Code using IndexedCustomizer directly (as a dialog) should
consider using the new method instead.

Oct 8 '01; API spec. version: 1.36; affected top-level classes: Node; made by: phrebejk; issues:
#15495Method protected final boolean hasPropertyChangeListeners() added
to the class Node. Method returns true if at least one PropertyChangeListener
is attached to the Node. At the same time changes were made to optimize the number
of attached listeners so calling this method should have some information value.

May 19 '01; affected top-level classes: AbstractNode; made by: jglickgetCookieSet now protected, not public. Logically it should
never have been public, since each object is responsible for providing its
own set of cookies as it sees fit, and making it possible for anyone to
retrieve and modify its cookie set without its explicit permission
violates this modularity. Also setCookieSet deprecated.
Compatibility:
Subclasses of the node should have the responsibility of adding
or removing cookies. See further notes under
MultiDataObject.
Binary-compatible

Mar 15 '01; affected top-level classes: Children; made by: jtulachcreateNodes(Object key) can now return null if
the key should have no nodes to represent it. The purpose is to reduce the
number of useless created objects.

Mar 6 '01; affected top-level classes: Index
Added method protected Index.KeyChildren.lock() which returns an object that is
used as a synchronization lock when working the the list object provided
in constructor.

Jan 30 '01; affected top-level classes: Node; made by: jglickNode.PropertySet and Node.Property may now have
the FeatureDescriptor property helpID set on
them (to a String) help ID) which may be used in the property
sheet.

Aug 9 '00; affected top-level classes: NodeOp
Changed method findContextMenuImpl. In case of constructing
menu from node which for some reason has more than one occurrence of the
same SystemAction no menu item was created. Now one menu item
will be created for such an action, where the first occurrence is taken
into account.

May 2 '00; affected top-level classes: Index
New class that should simplify displaying and reordering of nodes
representing java.util.List. Automatically provide
implementation of Index to reorder content of the list.

May 2 '00; affected top-level classes: NodeOpsetDefaultActions deprecated.
Compatibility:
First removed, later re-added but deprecated in trunk and
boston. Only technically incompatible: could always only be
called once, otherwise a SecurityException would be thrown.

Mar 9 '00; affected top-level classes: DefaultHandle; made by: jglickDefaultHandle rewritten. Now stores just handle of direct
parent, so that intervening nodes have the opportunity to supply their own
handles.
Compatibility:
It never actually worked before anyway; no module could have
successfully used the previous behavior and be broken by the
change.

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
BeanInfos 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 BeanInfos
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:

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.