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: $codebase > 1.20

Changes by affected class

org.openide.util.lookup.AbstractLookup

org.openide.util.AsyncGUIJob

org.openide.util.actions.CallbackSystemAction

org.openide.util.Cancellable

org.openide.util.ContextAwareAction

org.openide.util.ContextGlobalProvider

org.openide.xml.EntityCatalog

org.openide.util.Enumerations

org.openide.ErrorManager

org.openide.util.HelpCtx

org.openide.util.lookup.InstanceContent

org.openide.util.Lookup

org.openide.util.LookupEvent

org.openide.util.LookupListener

org.openide.util.lookup.Lookups

org.openide.util.Mutex

org.openide.util.NbBundle

org.openide.util.datatransfer.NewType

org.openide.util.datatransfer.PasteType

org.openide.util.actions.Presenter

org.openide.util.lookup.ProxyLookup

org.openide.util.RequestProcessor

org.openide.util.io.SafeException

org.openide.ServiceType

org.openide.util.SharedClassObject

org.openide.util.actions.SystemAction

org.openide.util.Task

org.openide.util.TopologicalSortException

org.openide.util.UserQuestionException

org.openide.util.Utilities

org.openide.util.WeakListeners

org.openide.xml.XMLUtil


Details of all changes by API and date


Actions API

New Actions system - part I.

Jan 8 '03; API spec. version: 3.29; affected top-level classes: ContextAwareAction Utilities CallbackSystemAction; made by: jtulach pzavadsky; issues: #27868

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.

SystemAction refers to Icon rather than ImageIcon

Apr 11 '00; affected top-level classes: SystemAction; made by: jglick
getIcon 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:

// ....

private static Icon icon = null;
// ....

public JMenuItem getMenuPresenter() {
    JMenu menu = new JMenu(getName ());
    if (icon == null) {
        icon = new ImageIcon(MyAction.class.getResource(iconResource()));
    }
    menu.setIcon(icon);
    // ....


Binary-compatible

Can create textual icons for actions

Mar 23 '00; affected top-level classes: SystemAction; made by: jglick
iconResource 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.

Lookup API

Less change notifications from ProxyLookup

Nov 11 '05; API spec. version: 6.7; affected top-level classes: ProxyLookup AbstractLookup; made by: jtulach; issues: #68031
ProxyLookup.setLookups used to fire LookupEvent every time it was called. Now it always checks whether there was a change to the previous state. This will reduce the number of events delivered when a small change is made. Also results from both ProxyLookup and AbstractLookup were modified to return immutable Collections. So do not try to modify them. It was always documented that the results, are immutable and also it was never said that a change is delivered when there is no change in the result, so this is considered compatible change, even it is know that at least one piece of code in NetBeans relied on this behaviour.

Lookups.exclude added to simplify writing of lookups that filter content of other lookups

Jan 14 '05; API spec. version: 5.4; affected top-level classes: Lookups; made by: jtulach; issues: #53058

New method that takes lookup and set of classes and return new lookup which contains everything from the original one except instances of the specified classes has been added.

Added ability to order items in META-INF/services/ lookup

May 9 '04; API spec. version: 4.34; affected top-level classes: Lookups; made by: dkonecny; issues: #41606
Items in META-INF/services/ lookup can be followed by advisory "position" attribute. The resulting lookup will list first items with lower position value. Items without position attribute will be listed last. See documentation for more details on format.

New lookupItem() method in Lookups

Jul 9 '03; API spec. version: 4.8; affected top-level classes: Lookups; made by: vstejskal
New method that returns Lookup.Item implementation for given instance and key identifying that instance in the lookup. This method is useful when writing Looks which need to return some cookies (Collection of Lookup.Items).

New method Lookups.metaInfServices

Feb 5 '03; API spec. version: 3.35; affected top-level classes: Lookups; made by: dstrupl; issues: #29126
A lookup that implements the JDK1.3 JAR services mechanism and delegates to META-INF/services/name.of.class files. This lookup was (is) used by core and the core had to use reflection to create an instance. Moreover can be usefull for module authors and in standalone library.

Folder lookup may be serialized

Jan 7 '03; API spec. version: 3.27; affected top-level classes: AbstractLookup ProxyLookup; made by: jglick; issues: #20190
To implement lookup caching, some lookup implementations are now serializable: AbstractLookup as well as FolderLookup's lookup. ProxyLookup has a protected subclass constructor permitting subclasses to be serializable.
Compatibility: Modules which rely on a data object under Services/ gaining or losing InstanceCookie between sessions may not work correctly with the cache. This is probably very rare.

ErrorManager.isNotifiable added

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.

New method Lookups.proxy

Sep 20 '02; API spec. version: 3.9; affected top-level classes: Lookups; made by: dstrupl; issues: #27425
Creates a lookup that delegates to another one but that one can change from time to time. The returned lookup checks every time somebody calls lookup or lookupItem method whether the provider still returns the same lookup. If not, it updates state of all Lookup.Results that it created (and that still exists).

Modules can specify the content of Lookup.getDefault in META-INF/services

Jul 22 '02; API spec. version: 3.3; made by: jtulach
The content of Lookup.getDefault() can be specified by a standard JDK registration mechanism, using JARs' META-INF/services directory. This is suitable for services that do not change, do not require user modification and that need to be ready soon during initialization of the system.

Added org.openide.util.lookup.Lookups

May 28 '02; API spec. version: 2.21; affected top-level classes: Lookups; made by: dstrupl; issues: #20550
New utility class added. The class cannot be instantiated and contains following static methods:

public static Lookup singleton(Object objectToLookup);
public static Lookup fixed(Object[] objectsToLookup);
public static Lookup fixed(Object[] keys, InstanceContent.Convertor convertor);
The methods return an instance of simple lookup implementation that holds the objects passed a parameter.

Enhanced usage of ProxyLookup & AbstractLookup.Content

Aug 18 '01; API spec. version: 1.31; affected top-level classes: AbstractLookup ProxyLookup; made by: jtulach
AbstractLookup.Content made public to allow its usage for objects that do not subclass AbstractLookup. ProxyLookup.beforeLookup added so subclasses can update themselves (call setLookups (...)) before the actual lookup is performed.

Changes in access protection of proxy lookup

Jul 8 '01; API spec. version: 1.19; affected top-level classes: ProxyLookup
ProxyLookup.setLookups made protected instead of public so nobody can misuse the method except the creator of the object and ProxyLookup.getLookups added. ProxyLookup made non final.
Compatibility: Changes to newly added feature.

Lookup service providers package created

Jun 1 '01; API spec. version: 1.9; affected top-level classes: AbstractLookup ProxyLookup; affected packages: org.openide.util.lookup; made by: jtulach
Package org.openide.util.lookup created, should hold SPI interfaces for lookup. Initially filled with AbstractLookup which introduces AbstractLookup.Pair and with ProxyLookup.

Added lookup items and support APIs

May 25 '01; API spec. version: 1.8; affected top-level classes: Lookup; made by: jtulach
Lookup enhanced. Interface Lookup.Item and additional methods to access it also added.

Lookup system introduced

Mar 1 '01; affected top-level classes: Lookup LookupEvent LookupListener; made by: jtulach
Better version of Lookup introduced. There is a org.openide.util.Lookup with bunch of inner classes and org.openide.util.LookupListener and org.openide.util.LookupEvent.

ServiceType.createClone added

Nov 30 '00; affected top-level classes: ServiceType
public final ServiceType createClone() added.
Compatibility: Subclasses are encouraged to implement Cloneable.

Instance content simplifies creation of lookups

(date unknown); API spec. version: 1.25; affected top-level classes: AbstractLookup InstanceContent; made by: jtulach
Added AbstractLookup.Content which can be passed to an abstract lookup in its constructor and used to control the contents easily. Also InstanceLookup provides the common easy implementation.

Utilities API

Ability to create finished RequestProcessor task

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

DynamicMenuContent interface added

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.

Support for interruption of RequestProcessor tasks

Jun 10 '05; API spec. version: 6.3; affected top-level classes: 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:
public void run () {
  while (veryLongTimeLook) {
    doAPieceOfIt ();

    if (Thread.interrupted ()) return;
  }
}

New method task.waitFinished(timeout) added

Nov 2 '04; API spec. version: 5.0; affected top-level classes: Task RequestProcessor; made by: jtulach; issues: #16849

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.

Added field OS_FREEBSD to Utilities

Oct 29 '04; API spec. version: 4.50; affected top-level classes: Utilities; made by: jrechtacek

FreeBSD was not recognized as Unix OS. Utilities has been enlarged with new field OS_FREEBSD, part of OS Unix mask. Utilities.isUnix() now returns true for applications run on FreeBSD.

Added Mutex.isReadAccess() and Mutex.isWriteAcess()

Sep 30 '04; API spec. version: 4.48; affected top-level classes: 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.

Added SharedClassObject.reset method to allow subclasses to implement reset correctly

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.

enum package deprecated and replaced by Enumerations factory class

Jun 7 '04; API spec. version: 4.37; affected top-level classes: 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.

Support for complicated listeners

Sep 2 '03; API spec. version: 4.12; affected top-level classes: WeakListeners; made by: jtulach; issues: #35726
Improved support for hierarchic listeners (aka NamingListener vs. ObjectChangeListener from javax.naming.event package).

Global action context as Lookup

Aug 12 '03; API spec. version: 4.10; affected top-level classes: ContextGlobalProvider Utilities; 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.

Old WeakListener replaced by WeakListeners class

Aug 12 '03; API spec. version: 4.10; affected top-level classes: WeakListeners; made by: jtulach; issues: #34758

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.

New method to find HelpCtx

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.

Retrofit of interface Cancellable into RequestProcessor.Task

Mar 14 '03; API spec. version: 4.1; affected top-level classes: 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.

Support for asynchronous init of UI components

Feb 5 '03; API spec. version: 3.36; affected top-level classes: AsyncGUIJob Cancellable Utilities; made by: dsimonek; issues: #30604

Performance related API addition, allows clients to write asynchronous initialization of UI components easily by providing AsyncGUIJob implementation. Also introduced Cancellable ability. Utilities.attachInitJob couples init job with target UI component.

Improved method for topological sort

Jan 10 '03; API spec. version: 3.30; affected top-level classes: Utilities 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.

Utilities.toFile and toURL added

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.

Can load localized cached images

Dec 15 '02; API spec. version: 3.24; affected top-level classes: Utilities SystemAction; 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.

org.openide.util.Utilities.createProgressCursor added

Dec 2 '02; API spec. version: 3.23; affected top-level classes: Utilities; made by: dsimonek
Method java.awt.Cursor createProgressCursor(java.awt.Component comp) was added into Utilities class. Method creates mouse cursor suitable for components which are busy, but still reacts to the input events. (don't block UI).

Added interface HelpCtx.Provider

Nov 11 '02; API spec. version: 3.20; affected top-level classes: HelpCtx ServiceType SystemAction NewType PasteType; 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.

Utilities.activeReferenceQueue()

Oct 7 '02; API spec. version: 3.11; affected top-level classes: Utilities; made by: jtulach; issues: #27238
Active java.util.ref.ReferenceQueue that polls for all enqued instances (that should implement Runnable) and invokes their run method to do actual cleanup.

New interface Lookup.Provider

Aug 19 '02; API spec. version: 3.6; affected top-level classes: Lookup; made by: dstrupl; issues: #26275
An object can have method getLookup if there is a need to provide local loookup instance. To recognize objects with such a facility we are introducing interface Lookup.Provider with only one method: getLookup.

Deprecation of parts of MouseUtils.PopupMenuAdapter

Aug 6 '02; API spec. version: 3.4; made by: dsimonek
Constructor MouseUtils.PopupMenuAdapter(int) and public static field DEFAULT_THESHOLD are now obsoleted, performs no action. PopupMenuAdapter now delegates to isPopupTrigger crossplatform call, should be constructed via default constructor.

Added RequestProcessor.getDefault(), deprecated static methods in RequestProcessor

Apr 15 '02; API spec. version: 2.12; affected top-level classes: RequestProcessor; made by: pnejedly
Sharing 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().

Added helper methods to aid module developers to write code which works correctly with multiple monitors

Feb 26 '02; API spec. version: 2.5; affected top-level classes: Utilities; made by: ttran; issues: #20882
The added methods are

public static Rectangle getUsableScreenBounds();
public static Rectangle getUsableScreenBounds(GraphicsConfiguration gconf);
public static Rectangle findCenterBounds(Dimension componentSize);
One should use these methods instead of calling Toolkit.getScreenSize(). For the same reason Utilities.getScreenSize() is now deprecated.

Added accessibility method ErrorManager.getDefault () that always returns non-null values

Jan 17 '02; API spec. version: 2.1; affected top-level classes: ErrorManager; made by: jtulach; issues: #16854

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.

Permit privileged access to mutexes to avoid inner classes

Jun 27 '01; API spec. version: 1.17; affected top-level classes: 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.

More flexibility in controlling running of tasks

Apr 27 '01; API spec. version: 1.5; affected top-level classes: Task
Task has new protected constructor for subclasses and methods notifyRunning () and also non-final version of waitFinished ().

Icon & image cache manager added

Mar 9 '01; affected top-level classes: Utilities
Loading icons and images can be done through Utilities.loadImage() that uses cache to avoid duplicate loading of images. mergeImages uses the cache, too, for the results of merge.

Special exception thrown to request interaction with user

Mar 5 '01; affected top-level classes: UserQuestionException
Added the first revision. This exception is thrown when a process is about to perform some action that requires user confirmation.

Support for merging icons added

Jan 25 '01; affected top-level classes: Utilities
Added method mergeImages(Image image1, Image image2, int x, int y) for merging images.

Can get a list of localizing suffixes

Jan 1 '01; affected top-level classes: NbBundle; made by: jglick
getLocalizingSuffixes added.

Updated DEC -> Compaq OS names

Dec 15 '00; affected top-level classes: Utilities
Operating system OS_DEC changed to OS_TRU64, and added OS_VMS.

ErrorManager.isLoggable added

Dec 2 '00; affected top-level classes: ErrorManager
isLoggable(int severity) added to ErrorManager.

Can find localized variants of extensionless resources

Oct 6 '00; affected top-level classes: NbBundle; made by: jglick
getLocalizedFile now accepts null extensions to suppress the addition of a dot to the resource name.

Logging and hierarchy support added to ErrorManager

Aug 18 '00; affected top-level classes: ErrorManager
getInstance(String name), log(int severity, String s), and log(String s) added to ErrorManager.

Proper break iterators used when wrapping text strings

Aug 11 '00; affected top-level classes: Utilities
Added method wrapString which uses BreakIterator instead of a flag and a heuristic solution. wrapString(String,int,boolean,boolean) deprecated.
Compatibility: Deprecated version first removed, later re-added with deprecation in the trunk.

Added search for branded variants as part of locale lookup

Jul 20 '00; affected top-level classes: 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.

Classloader finder for NbBundle is obsolete

Apr 11 '00; affected top-level classes: NbBundle
NbBundle.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.

SafeException is a FoldingIOException

Mar 9 '00; affected top-level classes: SafeException
Now extends FoldingIOException, meaning that it should delegate the detail message, etc. to the original.

XML API

XML attribute and hexadecimal utilities modified

Oct 18 '01; API spec. version: 1.40; affected top-level classes: XMLUtil; issues: #16629
toAttribute(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.

XML attribute and hexadecimal utilities added

Aug 8 '01; API spec. version: 1.29; affected top-level classes: XMLUtil
toAttribute(String, char, boolean), toContent(String, boolean), toHex(byte[], int, int) and fromHex(char[], int, int) methods added.

Independent XML API created

Mar 3 '01; affected top-level classes: XMLUtil EntityCatalog; affected packages: org.openide.xml; made by: pkuzel
XMLUtil utility class introduced. The class provides set of static methods useful for XML processing. EntityCatalog class introduced. It provides access to entity mapping registrations provided by installed modules.

Moved XML static methods into separate inner class

Feb 16 '01; affected top-level classes: XMLUtil; made by: pkuzel

Compatibility: XMLDataObject.Util itself deprecated on Mar 3 '01 in favor of XMLUtil .

Updated DOM to level 2 and added document writability

Jan 26 '01; affected top-level classes: XMLUtil; made by: pkuzel

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

Can register entity resolvers

Dec 20 '00; affected top-level classes: EntityCatalog
addEntityResolver and removeEntityResolver added. These methods allow a user to develop own implementation of functionality similar to registerCatalogEntry. E.g. a user can register EntityResolver that reads data from persistent catalog avoiding bunch of calls to the register method in module restore code.
Compatibility: Subsequently deprecated on Mar 3 '01 by EntityCatalog .

Built on July 11 2007.  |  Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.