Introduction

This document lists changes made to the Loaders API. Please ask on the dev@openide.netbeans.org mailing list if you have any questions about the details of a change, or are wondering how to convert existing code to be compatible.

Most module authors should start by reading the Upgrade Guide for the current release.

Index of APIs

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

(May 28 '03) Tighter synchronization during copy/move/rename
(May 16 '03) Calls to DataObject constructor restricted

All changes by date

(Jun 11 '04) Added ChangeableDataFilter interface
(May 18 '04) Support for 24x24 icons
(May 12 '04) DataShadow uses URL for storage
(May 3 '04) DataNode.getHtmlDisplayName was implemented
(Sep 9 '03) Two new folder sort modes
(May 28 '03) Tighter synchronization during copy/move/rename
(May 16 '03) Calls to DataObject constructor restricted
(Apr 18 '03) Separated out from the openide

Changes by version

These API specification versions may be used to indicate that a module requires a certain API feature in order to function. For example, if you see here a feature you need which is labelled 1.20, your manifest should contain in its main attributes the line:

OpenIDE-Module-Module-Dependencies: org.openide.loaders > 1.20

(4.16) Added ChangeableDataFilter interface
(4.15) Support for 24x24 icons
(4.14) DataShadow uses URL for storage
(4.13) DataNode.getHtmlDisplayName was implemented
(4.10) Two new folder sort modes
(4.9) Tighter synchronization during copy/move/rename
(4.7) Calls to DataObject constructor restricted
(4.5) Separated out from the openide

Changes by affected class

`org.openide.loaders.ChangeableDataFilter`

(Jun 11 '04) Added ChangeableDataFilter interface

`org.openide.loaders.DataFolder`

(Sep 9 '03) Two new folder sort modes

`org.openide.loaders.DataNode`

(May 3 '04) DataNode.getHtmlDisplayName was implemented

`org.openide.loaders.DataObject`

(May 28 '03) Tighter synchronization during copy/move/rename
(May 16 '03) Calls to DataObject constructor restricted

`org.openide.awt.Toolbar`

(May 18 '04) Support for 24x24 icons

`org.openide.awt.ToolbarPool`

(May 18 '04) Support for 24x24 icons

Details of all changes by API and date

Loaders API

Added `ChangeableDataFilter` interface

Jun 11 '04; API spec. version: 4.16; affected top-level classes: ChangeableDataFilter; made by: phrebejk; issues: #44368

The class FolderChildren was able to filter the children using DataFilter. But the data filter was constant for the entire life of the FolderChildren instance. ChangeableDataFilter class adds the ability to change the filtering strategy, where the change is reflected immediatley in the folder children.

Support for 24x24 icons

May 18 '04; API spec. version: 4.15; affected top-level classes: Toolbar ToolbarPool; made by: mslama; issues: #34574
Toolbar.getBasicHeight() was added to replace Toolbar.BASIC_HEIGHT. ToolbarPool.getPreferredIconSize() and ToolbarPool.setPreferredIconSize(int) were added.

`DataShadow` uses URL for storage

May 12 '04; API spec. version: 4.14; made by: dkonecny; issues: #42091
Two changes in DataShadow. The implementation was changed to store link as URL instead of FileSystem + Path pair. DataShadow declaration was extended and "originalFile" attribute can be defined not only as stringvalue but also as urlvalue.

`DataNode.getHtmlDisplayName` was implemented

May 3 '04; API spec. version: 4.13; affected top-level classes: DataNode; made by: tboudreau; issues: #29466
DataNode now implements getHtmlDisplayName() as follows: If the underlying filesystem implements the new FileSystem.HtmlStatus, it will call FileSystem.HtmlStatus.annotateNameHtml() and return the result. This enables, for example, CVS annotations to be shown with a different font color.

Two new folder sort modes

Sep 9 '03; API spec. version: 4.10; affected top-level classes: DataFolder; made by: jglick; issues: #26667
Two new folder sort modes, LAST_MODIFIED and SIZE, were added.

Tighter synchronization during copy/move/rename

May 28 '03; API spec. version: 4.9; affected top-level classes: DataObject; made by: jtulach; issues: #33750
In previous version of Loaders a thread can access unfinished files copied/moved/createFromTemplated by another Thread. This change prevent such accidental access and provides more robust behaviour to writers of own DataObjects and DataLoaders.

This change has been introduced to make the behaviour safer and more predicatable. Its goal is not to introduce new deadlocks, but everybody writing its own loaders has to keep in mind that it is dangerous to perform a long running operation in the handleCopy, handleMove, handleRename, handleCreateFromTemplate methods.

Calls to DataObject constructor restricted

May 16 '03; API spec. version: 4.7; affected top-level classes: DataObject; made by: jtulach; issues: #33469
In order to fix timing issues in org.openide.loaders package the possibility to invoke DataObject's constructor has been restricted.

There is an OperationListener class in the org.openide.loaders package that shall be notified about every created DataObject. It is easy to be notified when the DataObject is being created, but the notification shall be done when its constructor finishes otherwise magic race conditions can happen, see for example issue 20022. The previous solution was to wait 500ms after the start of DataObject's constructor and notifying the creation than, but of course it means that if the constructor takes longer time, we were in the same problem again.

Because DataObjects shall be created only by DataLoaders in method DataLoader.handleFindDataObject, we can notify each data object when the execution is returning from DataLoader.handleFindDataObject, but in order for the system to work correctly we shall prevent creation of DataObjects outside of this place.

DataObject constructor will throw an exception if invoked outside of DataLoader.handleFindDataObject or MultiFileLoader.createDataObject methods. This is incompatible change, but nobody should really be affected, as creating data objects outside of DataLoader has no real meaning.

Separated out from the openide

Apr 18 '03; API spec. version: 4.5; made by: jtulach; issues: #32937
Classes of org.openide.loaders package were separated out from the whole openide.jar into their own openide-loaders.jar.