Skip navigation links


This document lists changes made to the Loaders API. Please ask on the 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

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: org.openide.loaders > 1.20

Changes by affected class

























Details of all changes by API and date

Loaders AWT Extensions

Separate template handling

Sep 27 '18; API spec. version: 7.70; affected top-level classes: Toolbar; made by: mentlicher; issues: #
Now it's possible to register actions with toggle property into Toolbar to get a toggle button.

Control what client properties pulldown menus have

Dec 21 '12; API spec. version: 7.44; affected top-level classes: MenuBar; made by: jtulach; issues: #222138

Layer declaration of a menu can influence what client properties the actual JMenu instances will have. More details.


Sep 3 '11; API spec. version: 7.30; affected top-level classes: ToolbarPool; made by: jtulach; issues: #192207

One can find out if ToolbarPool is initialized.

lookup(DataObject.class) fallback

Jun 21 '11; API spec. version: 7.26; affected top-level classes: FileSystemAction; made by: tstupka

In FileSystemAction.createMenu(boolean popUp, Lookup lookup) fallback on .lookup(DataObject.class) in case the given lookup contains no nodes.

FileEncodingQuery registered per MIME type takes preceedence

Apr 7 '10; API spec. version: 7.14; made by: jtulach; issues: #102629

FileEncodingQuery implementations registered in Editors/text/mime/ folders are queried even before the actual DataObject has been created from template. This allows data loaders with static encoding to register such FileEncodingQuery implementation there and be active while the object is being constructed.

Added AcceleratorBinding

Feb 20 '10; API spec. version: 7.13; affected top-level classes: org.openide.awt.AcceleratorBinding; made by: jglick; issues: #180543

Added a new class to help with action accelerators. Should not be used by typical modules.

(Moved into the org.openide.awt module as of 7.34.)

Deprecation of Toolbar drag and drop API

Nov 28 '08; API spec. version: 7.5; affected top-level classes: Toolbar ToolbarPool; made by: saubrecht; issues: #59242

Deprecated methods related to Toolbar drag and drop.

Enhanced the org.openide.awt.MenuBar to understand Components.

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

Rebrand defaults for Save/Close Editor Dialogs

Jan 20 '21; API spec. version: 7.80; affected top-level classes: DataEditorSupport; made by: jtulach
A branding API to disable showing on close and on save editor dialogs - ASK_OnSaving & ASK_OnClosing.

Introduces system property to change file size threshold.

Aug 23 '13; API spec. version: 7.51; affected top-level classes: DataEditorSupport; made by: igor_nikiforov; issues: #213882

We need a way to replace hardcoded "1024 * 1024" constant for file size, as in native space 1Mb file is rather common situation. So org.openide.text.big.file.size system property is introduced, which allows to set this threshhold in megabytes. The default threshold is 1Mb.

DataEditorSupport constructor with Lookup parameter

Jul 11 '11; API spec. version: 7.28; affected top-level classes: DataEditorSupport; made by: jtulach; issues: #199416

One can control what Lookup will be associated with DataEditorSupport.

DataEditorSupport.create(...., Callable<Pane>)

Jun 1 '11; API spec. version: 7.23; affected top-level classes: DataEditorSupport; made by: jtulach

New create factory method to allow creation of different CloneableEditorSupport.Pane implementations than the default CloneableEditor.

Added annotateName and toolTip to DataEditorSupport

Sep 3 '09; API spec. version: 7.7; affected top-level classes: DataEditorSupport; made by: jglick; issues: #171428

Added two convenience methods permitting modules with nonstandard editor-like windows to use the regular modified and read-only status annotations.


Overrides of messageHtmlName should be reconsidered. Calls to messageName should be paired with calls to messageHtmlName and messageToolTip.

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

DataFolder createFromTemplate improvements

Jun 15 '21; API spec. version: 7.82; affected top-level classes: DataFolder; made by: jtulach
DataFolder.createFromTemplate honors passed in parameters for all its children, unless special CreateFromTemplateHandler takes over the instantiation process.

Support lazy creation of TargetFolder.

Mar 1 '20; API spec. version: 7.76; affected top-level classes: TemplateWizard; made by: errael; issues: NETBEANS-3918

Creation of TargetFolder can be deferred by using TemplateWizard.setTargetFolderLazy(Supplier<DataFolder>) .

Introduces SortMode for natural sorting.

Oct 21 '15; API spec. version: 7.65; affected top-level classes: DataFolder; made by: jhavlin; issues: #242226

Added support for natural sorting of DataObjects. This means that the sort is case insensitive and number sequences are sorted by value rather than lexicographically.

Separate template handling

Oct 14 '14; API spec. version: 7.59; affected top-level classes: CreateFromTemplateAttributesProvider CreateFromTemplateHandler; made by: sdedic; issues: #
Template handling need not depend on Data System APIs, should be available for clients that only know FileSystems. Relevant interfaces moved to openide.filesystems.templates module; see javadoc for FileBuilder for details.

Introduce targetName for templates.

Jan 29 '14; API spec. version: 7.56; affected top-level classes: org.netbeans.api.templates.TemplateRegistration; made by: jhavlin; issues: #239028

By default, files created from templates have name preinitialized to "new" + template name. TemplateRegistration.targetName can be used to customize how the file name will be preinitialized.

Introduces SortMode for sorting by file extension.

Oct 10 '13; API spec. version: 7.54; affected top-level classes: DataFolder; made by: jhavlin; issues: #230821

It's possible to sort files using sort mode "By Type", which means using SortMode.CLASS. It may be confusing, as users expect that the files will be sorted by file type, i.e. by extension. "By Type" was renamed to "By Class" and new sort mode "By Extension" (SortMode.EXTENSIONS) was added.

Allow registration of templates which do not require a Project instance

Jan 25 '13; API spec. version: 7.46; affected top-level classes: org.netbeans.api.templates.TemplateRegistration; made by: 280Z28; issues: #186943

Templates may be registered with requireProject = false in the annotation to indicate the template does not require a Project instance to be created. These templates show in the New File dialog even when no project is open in the IDE.

Introduced DataShadow.findOriginal which extracts the original file from a FileObject representing a shadow/link.

Nov 23 '12; API spec. version: 7.42; affected top-level classes: DataShadow; made by: sdedic
Target FileObject can be obtained, instead of DataObject. The target may be invalid, or otherwise unsuitable for DataObject creation. Use this method to just dereference the shadow file.

Introduced DataObject.Registration and DataObject.Registrations

Jan 23 '12; API spec. version: 7.36; affected top-level classes: DataObject; made by: skygo; issues: #207219 #208670

Introduced a new annotation for registering DataObject.

Introduced Template

Jul 25 '11; API spec. version: 7.29; affected top-level classes: org.netbeans.api.templates.TemplateRegistration org.netbeans.api.templates.TemplateRegistrations; made by: jglick; issues: #200175

Introduced a new annotation for registering (file or project) templates.

Simpler way to subclass MultiDataObject

Jun 21 '11; API spec. version: 7.27; affected top-level classes: MultiDataObject; made by: jtulach

New way to subclass MultiDataObject: override int associateLookup() to return 1. In constructor call registerEditor("your/mimetype", ...) to get default editor support. No need to override any other methods to get well performing MultiDataObject.

Compatibility: Added registerEditor method which might clash with some existing method in subclasses, although it is hopefully not very likely.

Children for DataFolder are more effective

Jun 10 '11; API spec. version: 7.25; affected top-level classes: DataFolder; made by: jtulach; issues: #199391

The nodes view over a DataFolder now creates real nodes in background which provides better performance on slow, remote filesystems.

Compatibility: Not fully compatible. In case your application desperately needs the original mode, use the org.openide.loaders.FolderChildren.delayedCreation property.

Removed org.openide.loaders.DataFolder.lazy

Oct 7 '10; API spec. version: 7.19; affected top-level classes: DataFolder; made by: jtulach

The private API to honor org.openide.loaders.DataFolder.lazy property has been removed, as being obsolete.

Added CreateFromTemplateHandler.FREE_FILE_EXTENSION

Apr 13 '10; API spec. version: 7.16; affected top-level classes: CreateFromTemplateHandler; made by: jglick; issues: #141886

Introduced a parameter that may be specified on templates to permit the user to pick a file extension.


Existing CreateFromTemplateHandler implementations are encouraged to honor the parameter.

New constructor of XMLDataObject

Nov 9 '09; API spec. version: 7.10; affected top-level classes: XMLDataObject; made by: jtulach; issues: #175750

New constructor for subclasses of XMLDataObject.

Faster Filtering based on FileObjects

Oct 30 '08; API spec. version: 7.4; affected top-level classes: DataFilter; made by: jtulach; issues: #150747

DataFilter interface used to support filtering based on DataObjects. With the introduction of more effective nodes, this is slowing down the visualization of folders significantly. That is why we introduce new pre-filter which can operate on FileObjects, whithout the need to instantiate DataObjects.

Changes in FolderLookup are delivered in dedicated thread

Jun 27 '08; API spec. version: 7.2; affected top-level classes: FolderLookup; made by: jtulach; issues: #134297

Changes found in FolderLookup are delivered in their own thread. This is a change to previous behaviour which used the Folder recognizer thread for event delivery. That could cause deadlocks, if malicious code decided to do something wild in the resultChanged method.

DataObjects without DataLoaders

Jun 11 '08; API spec. version: 7.1; affected top-level classes: DataLoaderPool; made by: jtulach; issues: #91665

There is new method to register new DataObject types without the need to write own DataLoader. Use DataLoaderPool.factory method.

Loaders are registered in layer files

May 26 '08; API spec. version: 7.0; affected top-level classes: DataObject DataLoader; made by: jtulach; issues: #91665

There is new registration scheme for DataLoaders.

XMLDataObject no longer enforces text/xml as document mimetype

Feb 20 '08; API spec. version: 6.9; affected top-level classes: XMLDataObject; made by: mkleint

Whenever possible the editor support and editor components will use the underlying FileObject's mimetype (as resolved by the mimetype resolvers).

Prefixing attributes from TemplateWizard with wizard.

Aug 14 '07; API spec. version: 6.7; affected top-level classes: TemplateWizard; made by: jtulach; issues: #109569

When TemplateWizard invokes DataObject.createFromTemplate, it passes as argument all its properties to it with wizard. as a prefix. That way they are available to underlying scripting and templating engines.

Templates may use ${encoding} and ${nameAndExt} properties

Aug 1 '07; API spec. version: 6.6; made by: mfukala; issues: #110910

Templates may use ${encoding} and ${nameAndExt} properties in their bodies to be substituted to the real encoding of the template instance file as well as the actual name (with extension) of the file, being created.

Folders may be ordered by numeric position

Jun 16 '07; API spec. version: 6.5; made by: jglick; issues: #103187

Folders may now be ordered by setting the position attribute on files within the folder, which should have a numeric value. The original relative ordering constraints are now deprecated but still work.

SaveAsCapable interface defines the ability to save DataObject under a different file name and/or extension

Mar 30 '07; API spec. version: 6.3; affected top-level classes: SaveAsCapable DataObject DataEditorSupport; made by: saubrecht; issues: #20147

The DataEditorSupport adds default implementation of SaveAsCapable interface to the CookieSet of DataObjects created by UniFileLoaders. The default implementation calls copyRename method on the DataObject.

DataEditorSupport uses FileEncodingQuery to read or write document in correct encoding

Mar 14 '07; API spec. version: 6.2; affected top-level classes: DataEditorSupport; made by: tzezula; issues: #42638

The DataEditorSupport overides the loadFromStreamToKit and saveFromKitToStream methods. In these methods it uses FileEncodingQuery to find out the encoding of the file, creates the Reader or Writer with obtained encoding and calls or EditorKit.write.

Integration with scripting and templating

Feb 8 '07; API spec. version: 6.3; affected top-level classes: DataObject CreateFromTemplateHandler CreateFromTemplateAttributesProvider; made by: jtulach; issues: #13250

Two new interfaces - CreateFromTemplateHandler and CreateFromTemplateAttributesProvider to enhance the abilities of data object to be created with parametrized values. Also new method createFromTemplate taking extra map of named arguments has been added, so users can pass the data object additional info that can be processed during instantiation of the template.

This is particallary useful when using scripting and templating languages during create from template operation.

DataNode.getLookup contains FileObject, DataObject has getLookup()

Nov 2 '06; API spec. version: 6.0; affected top-level classes: DataNode DataObject; made by: jtulach; issues: #62707

Since now, each DataNode constructed without using own lookup, shall have FileObject(s) associated with its DataObject available in its own lookup. Also a DataObject has been retrofitted to implement a Lookup.Provider interface and thus have its getLookup method that can be used instead of the old getCookie one.

Folders in IDE can accept files dragged from outside, files and folders in IDE can be dragged and dropped to external applications.

May 30 '06; API spec. version: 5.11; affected top-level classes: DataNode DataFolder; made by: saubrecht; issues: #35228

Class DataNode add additional DataFlavors to its Transferable which means that any file or folder can be dragged from the IDE and dropped to any external application that supports file drag and drop operations. The same functionality applies to Copy/Cut and Paste operations.

Class DataFolder.FolderNode now supports file-type DataFlavors so when a file(s) is dropped to a folder node in the IDE then the file is copied into that folder. If the file is a Java source file then the appropriate refactoring will fire up as well.

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.