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:

Introduction of new action system, which generally means
move from usage of SystemAction to Action instances.
That document also focuses on declarative actions
usage which is not subject of current change, it will be part of later changes.

Apr 11 '00; affected top-level classes: SystemAction; made by: jglickgetIcon and setIcon now use the interface
Icon rather than the particular implementation
ImageIcon. This corrects an API bug (excessive specificity).
Compatibility:
First broken, later restored binary compatibility in trunk and
boston. Any code explicitly using this calls before may break
(source code may be compatible in many cases; binary compatibility has
been preserved). These calls were known to be used only for
Actions to create presenters; normal code which constructs
SystemActions and implements iconResource should
be unaffected. Actions using the "grouping action" template should check
their getMenuPresenter method which may be
binary-incompatible; it is easy to replace the code with safer code such
as:

Mar 23 '00; affected top-level classes: SystemAction; made by: jglickiconResource may now return null to indicate no
icon. getIcon(true) may be used to get an icon created from
the label if there is no icon specified.

Only some platforms provide an audible notification when user
tries to invoke a disabled action. So instead of Toolkit.beep()
which always plays a sound a new method
Utilities.disabledActionSound() shoud be used instead.

The class Utilities was also split and the
client desktop indepenent parts landed in BaseUtilities.
Although all the constants and methods are still available through Utilities class, it is advised to change the dependencies
and reference them through BaseUtilities.

When the IDE is running under a dark look and feel (UIManager.getBoolean("nb.dark.theme"))
then ImageUtilities will try to load an image or on icon with a "_dark" suffix.
For example "org/netbeans/modulename/toolbaricon_dark.png" or
"org/netbeans/modulename/imagewithoutextension_dark". If such
resource exists it will be used instead of the default one.

@NbBundle.Messages may now be used on fields, useful
in case the field initializer involves some complex construction
requiring a localized message. (Merely storing a localized message
in a String constant is poor practice; inline the field instead.)

Compatibility:

Existing annotations made on classes but only used from a field
within that class will continue to work, but for clarity should
be moved onto the field.

In order to deal with bug #202354 there were some minor tweaks
inside RequestProcessor implementation.

Compatibility:
The changes are supposed to be as compatible as possible. The only
desirable change is that calling cancel(); cancel() on
the same task returns false on the second call now.
In spite of that the changes caused bunch of regressions and it took
a week to stabilize them. That is why they deserve a warning note
in compatibility section.

Javadoc says: Test whether the operating system supports icons on frames (windows).
But window system used this method to decide if small 16x16 or bigger 32x32 icon
should be used for frame (main window). So usage and Javadoc is inconsistent.
All OS support small icon in frame. From JDK 6 it is possible to set multiple size
icons for frame so OS WM selects appropriate size.
I removed useless usage of this method from window system code and this method is
not used elsewhere.

NetBeans preference tree is provided by NetBeans implementation of preferences
which uses userdir as a storage. Both newly added methods return
preferences node from NetBeans preference tree.
Method NbPreferences.root() returns root preference
node.
Method NbPreferences.forModule(Class cls) returns
preference node whose
path depends whether class provided as a parameter
was loaded as a part of any module or not. If so, then absolute path corresponds to slashified
code name base of module. If not, then absolute path corresponds to class's package.
See document
Preferences in NetBeans
to learn more about preferences in NetBeans.

Apr 15 '06; API spec. version: 7.0; affected top-level classes: ErrorManager; made by: jtulach; issues:
#56311ErrorManager
is no longer the recommended way to do logging in NetBeans based
application. Instead NetBeans now fully support logging two JDK's
standard Logger.
See the
NetBeans logging guide
to learn the best practises for logging in NetBeans.
ErrorManager
is still kept around for annotating exceptions with localized
messages and advanced manipulation and its behaviour is fully
backward compatible. However modules are adviced to migrate to
logging whereever
possible.
To migrate your modules you can install Jackpot modules from
autoupdate (if they are not yet part of your IDE) and apply
precreate
javapot error manager rule.
There is one possible incompatibility from end user point of view.
The way to enable logging for certain components when
running inside the whole NetBeans container has changed:
If there is
Logger or
ErrorManager
named org.mymodule.MyComponent then the correct way
to turn the logging is now to invoke NetBeans with
-J-Dorg.mymodule.MyComponent.level=100
(where the possible constants are taken form
a JDK's definition of level).
There is however a certain benefit in this change, the value
of the property (like org.mymodule.MyComponent.level)
can be changed during runtime and thus the logging can be
enabled or disabled dynamically (after changing the value, it is
necessary to call
LogManager.readConfiguration()).

Nov 22 '05; API spec. version: 6.8; affected top-level classes: org.openide.util.RequestProcessor; made by: jtulach; issues:
#68031RequestProcessor.create(Runnable, boolean)
has been added to allow creation of
Task
that has not executed its runnable yet, but looks like it is finished.

Jun 12 '05; API spec. version: 6.4; affected top-level classes: Presenter; made by: mkleint; issues:
#35827
In order to support MacOSX top menus and to fix problems with deprecated JInlineMenu, this new
interface was added that allows to handle dynamic content in
Presenter.Menu
and Presenter.Popup.
If the instance returned by Presenter.Menu/Popup is an instance of
DynamicMenuContent, it's methods are
consulted when creating/updating the menu.

Jun 10 '05; API spec. version: 6.3; affected top-level classes: org.openide.util.RequestProcessor; made by: jtulach; issues:
#33467
When one calls RequestProcessor.Task.cancel(),
the running thread gets interrupted if the
RequestProcessor(string, int, boolean)
constructor is used.
There always was a way how to cancel not yet running Task,
but if the task was already running, one was out of luck. Since now
the thread running the task is interrupted and the Runnable can check
for that and terminate its execution sooner. In the runnable one shall
check for thread interruption and
if true, return immediatelly as in this example:

It is not possible to wait for a limited amount of time for
completion of any task. The RequestProcessor.Task
version is optimized, the Task version ensures that
the sematics will be compatible for all subclasses, even they did
not know about the method at all.

Sep 30 '04; API spec. version: 4.48; affected top-level classes: org.openide.util.Mutex; made by: jtulach; issues:
#49459
A thread can now check whether read or write access on a Mutex
has already been
granted to it and use it to decide whether it is safe to perform
certain operations or delay them.

Sep 2 '04; API spec. version: 4.46; affected top-level classes: SharedClassObject; made by: jtulach; issues:
#20962
The new SharedClassObject.reset method is called
by the infrastructure in moments when an original (at the time
of start) state of an option or any other SharedClassObject
is requested. Interested subclasses are free to implement any kind of clean
they need. The SystemOption provides a default
implementation based on fired property changed events, so
its correctly written subclasses do not need
to do anything.

Jun 7 '04; API spec. version: 4.37; affected top-level classes: org.openide.util.Enumerations; made by: jtulach; issues:
#41166
enum is a keyword in JDK 1.5 and as such it should not be used.
That is the reason why we had to deprecated our
org.openide.util.enum package. We are providing
replacements of the original classes in form of factory methods
org.openide.util.Enumerations.

Aug 12 '03; API spec. version: 4.10; affected top-level classes: ContextGlobalProviderUtilities; made by: jtulach; issues:
#34758
As part of the work on separation of openide.jar into smaller parts
a new interface ContextGlobalProvider and new method
in utilities Utilities.actionsGlobalContext() had to be
added in order to separate the implementation of actions like
CallbackSystemAction and NodeAction from
their dependency on window system.

As part of the work on separation of openide.jar into smaller parts
the WeakListener had to be deprecated as it referenced too
many classes around and replaced by more general WeakListeners
factory class that provides a generic create method and
specialized factory methods just for JDK own interfaces.

Also few factory methods were spread into appropriate packages like
FileUtil.weakFileChangeListener and
NodeOp.weakNodeListener.

Apr 2 '03; API spec. version: 4.3; affected top-level classes: HelpCtx; made by: jtulach; issues:
#32143
A new method for finding HelpCtx (HelpCtx.findHelp(Object))
has been added to replace
the old InstanceSupport.findHelp that has been
separated out from the openide.jar.

Mar 14 '03; API spec. version: 4.1; affected top-level classes: org.openide.util.RequestProcessor; made by: dsimonek
RequestProcessor.Task was made to implement util.Cancellable interface.
No change of implementation at all, RP.Task already had method from
interface implemented, this is just a logical retrofit.

Jan 10 '03; API spec. version: 3.30; affected top-level classes: Utilitiesorg.openide.util.TopologicalSortException; made by: jglick; issues:
#27286
The method Utilities.topologicalSort was added. It should be
faster and probably more robust than the older partialSort
method, which required a Comparator; the new method requires
a list of ordering constraints, which should be O(n + m)
rather than O(n2) (where n is the number of
nodes to sort and m the number of edges). If the graph is
not a DAG a TopologicalSortException is thrown containing
description of unsortable parts of the graph and the best partitial sort
that fullfils as much of ordering constraints as possible. These
information can be used for error reporting and recovery.

Dec 24 '02; API spec. version: 3.26; affected top-level classes: Utilities; made by: jglick; issues:
#29711
Two new utility methods were added which permit easy interconversion between
files and URLs using the file protocol. This task is easy and
safe under JDK 1.4, yet JDK 1.3 lacks a single call to do these tasks which
will handle unusual characters in file names, especially hash marks. The
utility methods use the JDK 1.4 variants when possible, else use specially
coded versions of the JDK 1.3 variants which handle hash marks.
Compatibility:
Existing code which uses the JDK 1.3 method File.toURL should be
examined, as it may be better to call Utilities.toURL.
Similarly, code which gets the path from a URL and calls the File
constructor may need to be changed to call Utilities.toFile.
Such changes should improve robustness of code when used in strangely
named directories.

Dec 15 '02; API spec. version: 3.24; affected top-level classes: UtilitiesSystemAction; made by: jglick; issues:
#22156
Added method Utilities.loadImage(String, boolean)
which works like Utilities.loadImage(String) except
that it will search for localized images. Also
SystemAction.getIcon() will load a localized image now
if there is one.

Nov 11 '02; API spec. version: 3.20; affected top-level classes: HelpCtxServiceTypeSystemActionNewTypePasteType; made by: pnejedly
An interface HelpCtx.Provider with one method getHelpCtx was added
and the logic in HelpCtx.findHelp and InstanceSupport.findHelp
was extended to take this interface into accout.
Various classes with existing getHelpCtx method were retrofitted
to implement this interface.

Nov 3 '02; API spec. version: 3.18; affected top-level classes: ErrorManager; made by: jglick; issues:
#24056
The method ErrorManager.isNotifiable was added to capture
the fact that an error manager implementation might be more aggressive
about displaying stack traces than log messages.
Compatibility:
Existing code which assumes (incorrectly) that isLoggable
can be used for this purpose, or which calls notify at a low
level such as INFORMATIONAL without first checking
isNotifiable for efficiency, should be revised.

Apr 15 '02; API spec. version: 2.12; affected top-level classes: org.openide.util.RequestProcessor; made by: pnejedlySharing of singlethreaded
RequestProcessor.DEFAULT
through the static methods is inherently deadlock-prone,
so the methods are deprecated and their usage should phase out
in the favor of using private RequestProcessors
or the shared multithreaded instance available through the new
static method RequestProcessor.getDefault().

This method allows independent libraries (nodes, filesystems, utilities) to use the ErrorManager without
testing if it is really present. Just call ErrorManager.getDefault () and you can be sure
that a valid instance will be returned.

Also TopManager.getErrorManager is no longer useful (see change) and is now deprecated.
It is also not abstract as it just delegates.
notifyException is similarly deprecated.

Jun 27 '01; API spec. version: 1.17; affected top-level classes: org.openide.util.Mutex
Added a new inner class and a constructor that takes an instance of that
inner class as a parameter. The inner class is Privileged.
Through its public methods one can enter internal states of the
Mutex to which it was passed.

Jul 20 '00; affected top-level classes: org.openide.util.NbBundle; made by: jglick
Added methods getBranding and setBranding.
Normally these should only be called by the core implementation during
startup, not module authors. All methods to look up localized objects
may now also search for branded variants, if applicable.

Apr 11 '00; affected top-level classes: org.openide.util.NbBundleNbBundle.ClassLoaderFinder and
NbBundle.setClassLoaderFinder have been deprecated; they
were quite obsolete.
Compatibility:
First removed, later re-added but deprecated in trunk and
boston. No one outside of NbBundle and the
core implementation should have been using these classes to begin with.

Oct 18 '01; API spec. version: 1.40; affected top-level classes: org.openide.xml.XMLUtil; issues:
#16629toAttribute(String, char, boolean) method replaced by
toAttributeValue(String)
and
toContent(String, boolean) method replaced by
toElementContent(String). These new simplified
signatures and particular semantics should cover 99% usage of
previous ones. See the original additions.
Compatibility:
The original versions of these methods were not in any public release.

A conflict between encoding declared in document and
actual Writer encoding can cause data loss. Suitable
just for UTF-8 and UTF-16 writers.

introduced write(Document, OutputStream, String encoding)

The write method is supposed to be used as an implementation
independent way for writing DOM documents until self-writable
documents specification will be introduced. The self-writability
is considered to be a part of DOM level 3 specs.

Nowadays it is implemented that it can handle following DOM implementations:

Crimson

JAXP 1.0 reference implementation

All others using Apache's serializers if available.

Compatibility:
Any code implementing DOM interfaces could be broken by the level 2
interfaces. Clients of the DOM API should be unaffected.