Overview

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

# Index of APIs

- Loaders AWT Extensions
- Loaders Editor Extensions
- 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

- (Oct 26 '05) All standard loaders reads their data from the layer
- (Sep 19 '05) New DataNode constructor that takes Lookup
- (May 11 '05) Introduction of a new interface FolderRenameHandler which allows plugging into `DataFolder.FolderNode.setName()`
- (Mar 9 '05) A factory method to simplify creation of `DataEditorSupport`
- (Feb 7 '05) Added `DataLoaderPool.getDefault()`
- (Nov 23 '04) Actions for `DataLoader` can be specified in a layer
- (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
- (Jul 15 '02) Enhanced the `org.openide.awt.MenuBar` to understand `Component`s.

# 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

- (5.8) All standard loaders reads their data from the layer
- (5.6) New DataNode constructor that takes Lookup
- (5.4) Introduction of a new interface FolderRenameHandler which allows plugging into `DataFolder.FolderNode.setName()`
- (5.2) A factory method to simplify creation of `DataEditorSupport`
- (5.1) Added `DataLoaderPool.getDefault()`
- (5.0) Actions for `DataLoader` can be specified in a layer
- (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
- (3.2) Enhanced the `org.openide.awt.MenuBar` to understand `Component`s.

# Changes by affected class

## `org.openide.loaders.ChangeableDataFilter`

- (Jun 11 '04) Added `ChangeableDataFilter` interface

## `org.openide.text.DataEditorSupport`

- (Mar 9 '05) A factory method to simplify creation of `DataEditorSupport`

## `org.openide.loaders.DataFolder`

- (Sep 9 '03) Two new folder sort modes

## `org.openide.loaders.DataLoader`

- (Nov 23 '04) Actions for `DataLoader` can be specified in a layer

## `org.openide.loaders.DataLoaderPool`

- (Oct 26 '05) All standard loaders reads their data from the layer
- (Feb 7 '05) Added `DataLoaderPool.getDefault()`

## `org.openide.loaders.DataNode`

- (Sep 19 '05) New DataNode constructor that takes Lookup
- (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.loaders.FolderRenameHandler`

- (May 11 '05) Introduction of a new interface FolderRenameHandler which allows plugging into `DataFolder.FolderNode.setName()`

## `org.openide.awt.MenuBar`

- (Jul 15 '02) Enhanced the `org.openide.awt.MenuBar` to understand `Component`s.

## `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 AWT Extensions

### Enhanced the `org.openide.awt.MenuBar` to understand `Component`s.

Jul 15 '02; API spec. version: 3.2; affected top-level classes: `MenuBar`; made by: pnejedly
This is not the Java API change but rather a change in treating of the content of the folder from which the `MenuBar` is built. Prevoiusly only folders were recognized and turned into top-level menus. Now also `Component` instances found in the folder are directly added to the resulting `MenuBar` and `Presenter.Toolbar` instances are asked for the presentation component and added to the `MenuBar`.

## Loaders Editor Extensions

### A factory method to simplify creation of `DataEditorSupport`

Mar 9 '05; API spec. version: 5.2; affected top-level classes: `DataEditorSupport`; made by: jtulach; issues: #17081

Many people subclass `DataEditorSupport` to provide editing ability for data objects. The great majority of them wish to provide an editor cookie and with standard semantics for open, modify, save, undo, close, reload, etc. By using the `DataEditorSupport.create` factory method this task is simplified to two lines of code.

## Loaders API

### All standard loaders reads their data from the layer

Oct 26 '05; API spec. version: 5.8; affected top-level classes: `DataLoaderPool`; made by: jtulach; issues: #64200

Default loaders, default XML loader and instances loader read their actions from `Loaders/content/unknown/Actions`, `Loaders/text/xml/Actions` and `Loaders/application/x-nbsettings/Actions`.

### New DataNode constructor that takes Lookup

Sep 19 '05; API spec. version: 5.6; affected top-level classes: `DataNode`; made by: jtulach; issues: #61824
It was not possible to use DataNode with own Lookup as the constructor that takes it was available only on Node and there was no way to pass it thru DataNode.

### Introduction of a new interface FolderRenameHandler which allows plugging into `DataFolder.FolderNode.setName()`

May 11 '05; API spec. version: 5.4; affected top-level classes: `FolderRenameHandler`; made by: jbecicka; issues: #53295
Refactoring needs to handle rename of DataFolder's Node. It is allowed through FolderRenameHandler. Any client can put it's FolderRenameHandler into Lookup (only one instance is allowed). Implementation of FolderNode.setName() will use this instance to handle rename request.

### Added `DataLoaderPool.getDefault()`

Feb 7 '05; API spec. version: 5.1; affected top-level classes: `DataLoaderPool`; made by: jtulach; issues: #41650

`DataLoaderPool` now has a new method `getDefault()` to allow simple access to the default system loader pool.

### Actions for `DataLoader` can be specified in a layer

Nov 23 '04; API spec. version: 5.0; affected top-level classes: `DataLoader`; made by: jtulach; issues: #45137

`DataLoader` now has a new method `protected String actionsContext()` which by default returns `null` but can be overriden to identify name of a place on default file system where layers can store instances of `javax.swing.Action` that will then be used as a return value of `DataNode.getActions(boolean)`. This allows smooth extensibility of one data object's node with actions from other modules.

The change is compatible, as if one does not override this method, the behaviour remains the same as it used to be. If the method is overridden and returns non-null value, the `DataLoader.setActions` uses the given context to store the actions into it.

The standard loader for folder use `Loaders/folder/any/Actions` as its context, so any module who wishes to add anything to its popup menu, may register actions layer file like any regular actions just into the folder `Loaders/folder/any/Actions`.

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

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.