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

- Actions API
- Lookup API
- Utilities API
- XML API

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

- (Oct 18 '01) XML attribute and hexadecimal utilities modified
- (Jan 26 '01) Updated DOM to level 2 and added document writability
- (Apr 11 '00) `SystemAction` refers to `Icon` rather than `ImageIcon`

# All changes by date

- (Nov 22 '05) Ability to create finished RequestProcessor task
- (Nov 11 '05) Less change notifications from ProxyLookup
- (Jun 12 '05) DynamicMenuContent interface added
- (Jun 10 '05) Support for interruption of RequestProcessor tasks
- (Jan 14 '05) `Lookups.exclude` added to simplify writing of lookups that filter content of other lookups
- (Nov 2 '04) New method `task.waitFinished(timeout)` added
- (Oct 29 '04) Added field `OS_FREEBSD` to `Utilities`
- (Sep 30 '04) Added `Mutex.isReadAccess()` and `Mutex.isWriteAcess()`
- (Sep 2 '04) Added `SharedClassObject.reset` method to allow subclasses to implement reset correctly
- (Jun 7 '04) enum package deprecated and replaced by Enumerations factory class
- (May 9 '04) Added ability to order items in META-INF/services/ lookup
- (Sep 2 '03) Support for complicated listeners
- (Aug 12 '03) Global action context as `Lookup`
- (Aug 12 '03) Old `WeakListener` replaced by `WeakListeners` class
- (Jul 9 '03) New `lookupItem()` method in Lookups
- (Apr 2 '03) New method to find HelpCtx
- (Mar 14 '03) Retrofit of interface Cancellable into RequestProcessor.Task
- (Feb 5 '03) Support for asynchronous init of UI components
- (Feb 5 '03) New method Lookups.metaInfServices
- (Jan 10 '03) Improved method for topological sort
- (Jan 8 '03) New Actions system - part I.
- (Jan 7 '03) Folder lookup may be serialized
- (Dec 24 '02) `Utilities.toFile` and `toURL` added
- (Dec 15 '02) Can load localized cached images
- (Dec 2 '02) org.openide.util.Utilities.createProgressCursor added
- (Nov 11 '02) Added interface HelpCtx.Provider
- (Nov 3 '02) `ErrorManager.isNotifiable` added
- (Oct 7 '02) Utilities.activeReferenceQueue()
- (Sep 20 '02) New method Lookups.proxy
- (Aug 19 '02) New interface Lookup.Provider
- (Aug 6 '02) Deprecation of parts of MouseUtils.PopupMenuAdapter
- (Jul 22 '02) Modules can specify the content of Lookup.getDefault in META-INF/services
- (May 28 '02) Added org.openide.util.lookup.Lookups
- (Apr 15 '02) Added RequestProcessor.getDefault(), deprecated static methods in RequestProcessor
- (Feb 26 '02) Added helper methods to aid module developers to write code which works correctly with multiple monitors
- (Jan 17 '02) Added accessibility method ErrorManager.getDefault () that always returns non-null values
- (Oct 18 '01) XML attribute and hexadecimal utilities modified
- (Aug 18 '01) Enhanced usage of ProxyLookup & AbstractLookup.Content
- (Aug 8 '01) XML attribute and hexadecimal utilities added
- (Jul 8 '01) Changes in access protection of proxy lookup
- (Jun 27 '01) Permit privileged access to mutexes to avoid inner classes
- (Jun 1 '01) Lookup service providers package created
- (May 25 '01) Added lookup items and support APIs
- (Apr 27 '01) More flexibility in controlling running of tasks
- (Mar 9 '01) Icon & image cache manager added
- (Mar 5 '01) Special exception thrown to request interaction with user
- (Mar 3 '01) Independent XML API created
- (Mar 1 '01) Lookup system introduced
- (Feb 16 '01) Moved XML static methods into separate inner class
- (Jan 26 '01) Updated DOM to level 2 and added document writability
- (Jan 25 '01) Support for merging icons added
- (Jan 1 '01) Can get a list of localizing suffixes
- (Dec 20 '00) Can register entity resolvers
- (Dec 15 '00) Updated DEC -> Compaq OS names
- (Dec 2 '00) `ErrorManager.isLoggable` added
- (Nov 30 '00) `ServiceType.createClone` added
- (Oct 6 '00) Can find localized variants of extensionless resources
- (Aug 18 '00) Logging and hierarchy support added to `ErrorManager`
- (Aug 11 '00) Proper break iterators used when wrapping text strings
- (Jul 20 '00) Added search for branded variants as part of locale lookup
- (Apr 11 '00) `SystemAction` refers to `Icon` rather than `ImageIcon`
- (Apr 11 '00) Classloader finder for `NbBundle` is obsolete
- (Mar 23 '00) Can create textual icons for actions
- (Mar 9 '00) `SafeException` is a `FoldingIOException`
- Instance content simplifies creation of lookups

# 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

- (6.8) Ability to create finished RequestProcessor task
- (6.7) Less change notifications from ProxyLookup
- (6.4) DynamicMenuContent interface added
- (6.3) Support for interruption of RequestProcessor tasks
- (5.4) `Lookups.exclude` added to simplify writing of lookups that filter content of other lookups
- (5.0) New method `task.waitFinished(timeout)` added
- (4.50) Added field `OS_FREEBSD` to `Utilities`
- (4.48) Added `Mutex.isReadAccess()` and `Mutex.isWriteAcess()`
- (4.46) Added `SharedClassObject.reset` method to allow subclasses to implement reset correctly
- (4.37) enum package deprecated and replaced by Enumerations factory class
- (4.34) Added ability to order items in META-INF/services/ lookup
- (4.12) Support for complicated listeners
- (4.10) Global action context as `Lookup`
- (4.10) Old `WeakListener` replaced by `WeakListeners` class
- (4.8) New `lookupItem()` method in Lookups
- (4.3) New method to find HelpCtx
- (4.1) Retrofit of interface Cancellable into RequestProcessor.Task
- (3.36) Support for asynchronous init of UI components
- (3.35) New method Lookups.metaInfServices
- (3.30) Improved method for topological sort
- (3.29) New Actions system - part I.
- (3.27) Folder lookup may be serialized
- (3.26) `Utilities.toFile` and `toURL` added
- (3.24) Can load localized cached images
- (3.23) org.openide.util.Utilities.createProgressCursor added
- (3.20) Added interface HelpCtx.Provider
- (3.18) `ErrorManager.isNotifiable` added
- (3.11) Utilities.activeReferenceQueue()
- (3.9) New method Lookups.proxy
- (3.6) New interface Lookup.Provider
- (3.4) Deprecation of parts of MouseUtils.PopupMenuAdapter
- (3.3) Modules can specify the content of Lookup.getDefault in META-INF/services
- (2.21) Added org.openide.util.lookup.Lookups
- (2.12) Added RequestProcessor.getDefault(), deprecated static methods in RequestProcessor
- (2.5) Added helper methods to aid module developers to write code which works correctly with multiple monitors
- (2.1) Added accessibility method ErrorManager.getDefault () that always returns non-null values
- (1.40) XML attribute and hexadecimal utilities modified
- (1.31) Enhanced usage of ProxyLookup & AbstractLookup.Content
- (1.29) XML attribute and hexadecimal utilities added
- (1.25) Instance content simplifies creation of lookups
- (1.19) Changes in access protection of proxy lookup
- (1.17) Permit privileged access to mutexes to avoid inner classes
- (1.9) Lookup service providers package created
- (1.8) Added lookup items and support APIs
- (1.5) More flexibility in controlling running of tasks

# Changes by affected class

## `org.openide.util.lookup.AbstractLookup`

- (Nov 11 '05) Less change notifications from ProxyLookup
- (Jan 7 '03) Folder lookup may be serialized
- (Aug 18 '01) Enhanced usage of ProxyLookup & AbstractLookup.Content
- (Jun 1 '01) Lookup service providers package created
- Instance content simplifies creation of lookups

## `org.openide.util.AsyncGUIJob`

- (Feb 5 '03) Support for asynchronous init of UI components

## `org.openide.util.actions.CallbackSystemAction`

- (Jan 8 '03) New Actions system - part I.

## `org.openide.util.Cancellable`

- (Feb 5 '03) Support for asynchronous init of UI components

## `org.openide.util.ContextAwareAction`

- (Jan 8 '03) New Actions system - part I.

## `org.openide.util.ContextGlobalProvider`

- (Aug 12 '03) Global action context as `Lookup`

## `org.openide.xml.EntityCatalog`

- (Mar 3 '01) Independent XML API created
- (Dec 20 '00) Can register entity resolvers

## `org.openide.util.Enumerations`

- (Jun 7 '04) enum package deprecated and replaced by Enumerations factory class

## `org.openide.ErrorManager`

- (Nov 3 '02) `ErrorManager.isNotifiable` added
- (Jan 17 '02) Added accessibility method ErrorManager.getDefault () that always returns non-null values
- (Dec 2 '00) `ErrorManager.isLoggable` added
- (Aug 18 '00) Logging and hierarchy support added to `ErrorManager`

## `org.openide.util.HelpCtx`

- (Apr 2 '03) New method to find HelpCtx
- (Nov 11 '02) Added interface HelpCtx.Provider

## `org.openide.util.lookup.InstanceContent`

- Instance content simplifies creation of lookups

## `org.openide.util.Lookup`

- (Aug 19 '02) New interface Lookup.Provider
- (May 25 '01) Added lookup items and support APIs
- (Mar 1 '01) Lookup system introduced

## `org.openide.util.LookupEvent`

- (Mar 1 '01) Lookup system introduced

## `org.openide.util.LookupListener`

- (Mar 1 '01) Lookup system introduced

## `org.openide.util.lookup.Lookups`

- (Jan 14 '05) `Lookups.exclude` added to simplify writing of lookups that filter content of other lookups
- (May 9 '04) Added ability to order items in META-INF/services/ lookup
- (Jul 9 '03) New `lookupItem()` method in Lookups
- (Feb 5 '03) New method Lookups.metaInfServices
- (Sep 20 '02) New method Lookups.proxy
- (May 28 '02) Added org.openide.util.lookup.Lookups

## `org.openide.util.Mutex`

- (Sep 30 '04) Added `Mutex.isReadAccess()` and `Mutex.isWriteAcess()`
- (Jun 27 '01) Permit privileged access to mutexes to avoid inner classes

## `org.openide.util.NbBundle`

- (Jan 1 '01) Can get a list of localizing suffixes
- (Oct 6 '00) Can find localized variants of extensionless resources
- (Jul 20 '00) Added search for branded variants as part of locale lookup
- (Apr 11 '00) Classloader finder for `NbBundle` is obsolete

## `org.openide.util.datatransfer.NewType`

- (Nov 11 '02) Added interface HelpCtx.Provider

## `org.openide.util.datatransfer.PasteType`

- (Nov 11 '02) Added interface HelpCtx.Provider

## `org.openide.util.actions.Presenter`

- (Jun 12 '05) DynamicMenuContent interface added

## `org.openide.util.lookup.ProxyLookup`

- (Nov 11 '05) Less change notifications from ProxyLookup
- (Jan 7 '03) Folder lookup may be serialized
- (Aug 18 '01) Enhanced usage of ProxyLookup & AbstractLookup.Content
- (Jul 8 '01) Changes in access protection of proxy lookup
- (Jun 1 '01) Lookup service providers package created

## `org.openide.util.RequestProcessor`

- (Nov 22 '05) Ability to create finished RequestProcessor task
- (Jun 10 '05) Support for interruption of RequestProcessor tasks
- (Nov 2 '04) New method `task.waitFinished(timeout)` added
- (Mar 14 '03) Retrofit of interface Cancellable into RequestProcessor.Task
- (Apr 15 '02) Added RequestProcessor.getDefault(), deprecated static methods in RequestProcessor

## `org.openide.util.io.SafeException`

- (Mar 9 '00) `SafeException` is a `FoldingIOException`

## `org.openide.ServiceType`

- (Nov 11 '02) Added interface HelpCtx.Provider
- (Nov 30 '00) `ServiceType.createClone` added

## `org.openide.util.SharedClassObject`

- (Sep 2 '04) Added `SharedClassObject.reset` method to allow subclasses to implement reset correctly

## `org.openide.util.actions.SystemAction`

- (Dec 15 '02) Can load localized cached images
- (Nov 11 '02) Added interface HelpCtx.Provider
- (Apr 11 '00) `SystemAction` refers to `Icon` rather than `ImageIcon`
- (Mar 23 '00) Can create textual icons for actions

## `org.openide.util.Task`

- (Nov 2 '04) New method `task.waitFinished(timeout)` added
- (Apr 27 '01) More flexibility in controlling running of tasks

## `org.openide.util.TopologicalSortException`

- (Jan 10 '03) Improved method for topological sort

## `org.openide.util.UserQuestionException`

- (Mar 5 '01) Special exception thrown to request interaction with user

## `org.openide.util.Utilities`

- (Oct 29 '04) Added field `OS_FREEBSD` to `Utilities`
- (Aug 12 '03) Global action context as `Lookup`
- (Feb 5 '03) Support for asynchronous init of UI components
- (Jan 10 '03) Improved method for topological sort
- (Jan 8 '03) New Actions system - part I.
- (Dec 24 '02) `Utilities.toFile` and `toURL` added
- (Dec 15 '02) Can load localized cached images
- (Dec 2 '02) org.openide.util.Utilities.createProgressCursor added
- (Oct 7 '02) Utilities.activeReferenceQueue()
- (Feb 26 '02) Added helper methods to aid module developers to write code which works correctly with multiple monitors
- (Mar 9 '01) Icon & image cache manager added
- (Jan 25 '01) Support for merging icons added
- (Dec 15 '00) Updated DEC -> Compaq OS names
- (Aug 11 '00) Proper break iterators used when wrapping text strings

## `org.openide.util.WeakListeners`

- (Sep 2 '03) Support for complicated listeners
- (Aug 12 '03) Old `WeakListener` replaced by `WeakListeners` class

## `org.openide.xml.XMLUtil`

- (Oct 18 '01) XML attribute and hexadecimal utilities modified
- (Aug 8 '01) XML attribute and hexadecimal utilities added
- (Mar 3 '01) Independent XML API created
- (Feb 16 '01) Moved XML static methods into separate inner class
- (Jan 26 '01) Updated DOM to level 2 and added document writability

# 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 `SystemAction`s 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 `Collection`s. 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 `RequestProcessor`s 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

- Deprecated all static: `write()`s, `parse()`s, `createDocument()`, `createInputSource()` and `createParser()`s methods.
- Introduced public static inner class named `Util` providing utility methods replacing deprecated ones.

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

- All level 1 `Document`s interfaces became level 2 ones.
- Deprecated `write(Document, Writer)`

  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.

### 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 December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.