Overview (Datasystems API)

Datasystems API
Package	Description
org.openide.actions
org.openide.awt
org.openide.loaders	Datasystems are the logical layer between a filesystem and higher-level file-oriented operations.
org.openide.text

This module provides API (read more) that works on top of file objects and gives each file a logical behaviour - icon, name, operations, etc.

What is New (see all changes)?

Jun 15 '21 DataFolder createFromTemplate improvements
DataFolder.createFromTemplate honors passed in parameters for all its children, unless special CreateFromTemplateHandler takes over the instantiation process.
Jan 20 '21 Rebrand defaults for Save/Close Editor Dialogs
A branding API to disable showing on close and on save editor dialogs - ASK_OnSaving & ASK_OnClosing.
Mar 1 '20 Support lazy creation of TargetFolder.

Creation of TargetFolder can be deferred by using TemplateWizard.setTargetFolderLazy(Supplier<DataFolder>) .
Sep 27 '18 Separate template handling
Now it's possible to register actions with toggle property into Toolbar to get a toggle button.
Oct 21 '15 Introduces SortMode for natural sorting.

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.

Use Cases

A lot of usecases is described in the javadoc. Here is the list of some faqs:

Using Scripting and Templating Languages

Often many people require ability to create a "clever" template - e.g. write piece of simple text and at the time of its processing do some advanced changes to it using either scripting or templating languages.

This traditionally used to be a bit complicated task, however since version 6.1 there are new interfaces can be registered as a services in a lookup and it is reponsible for handling the whole copy of the template file(s) to the destination folder. and can be registered as a services in a lookup and it is reponsible for providing "hints" - e.g. map mapping strings to various objects. and these interfaces allow anyone to extend the behaviour during creation of new files without writing new DataLoader and co.

The support was moved to a new module; please see api.templates module for more information.

How to add action to folder's popup menu?

The actions that the default folder loader shows in its popup menu are read from a layer folder Loaders/folder/any/Actions so if any module wishes to extend, hide or reorder some of them it can just register its actions there. As code like this does:

    <folder name="Loaders" >
        <folder name="folder" >
            <folder name="any" >
                <folder name="Actions" >
                    <file name="org-mymodule-MyAction.instance" >
                        <attr name="instanceCreate" stringvalue="org.mymodule.MyAction" />
                    </file>
                </folder>
            </folder>
        </folder>
    </folder>

As described in general actions registration tutorial.

This functionality is available since version 5.0 of the loaders module. Please use OpenIDE-Module-Module-Dependencies: org.openide.loaders > 5.0 in your module dependencies.

In version 5.8 all the standard loaders were changed to read actions from layer:

The actions that the standard XML loader shows in its popup menu are read from a layer folder Loaders/text/xml/Actions
The actions that the loader for unrecognized files shows in its popup menu are read from a layer folder Loaders/content/unknown/Actions
The actions that the loader for instance and settings files shows in its popup menu are read from a layer folder Loaders/application/x-nbsettings/Actions

How to allow others to enhance actions of your loader?

If you want other modules to enhance or modify actions that are visible on DataObjects produced by your DataLoader and you are either using DataNode or its subclass, you can just override protected String actionsContext() method to return non-null location of context in layers from where to read the actions.

The usual value should match Loaders/mime/type/Actions scheme, for example java is using Loaders/text/x-java/Actions, but the name can be arbitrary.

This functionality is available since version 5.0 of the loaders module. Please use OpenIDE-Module-Module-Dependencies: org.openide.loaders > 5.0 in your module dependencies.

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...

Group of java interfaces

Interface Name	In/Out	Stability	Specified in What Document?
LoadersAPI	Exported	Official	.../openide/loaders/doc-files/api.html

Group of lookup interfaces

Interface Name

In/Out

Stability

Specified in What Document?

org.openide.loaders.CreateFromTemplateHandler

Exported

Deprecated

.../loaders/CreateFromTemplateHandler.html

can be registered as a services in a lookup and it is reponsible for handling the whole copy of the template file(s) to the destination folder.

org.openide.loaders.CreateFromTemplateAttributesProvider

Exported

Deprecated

.../

can be registered as a services in a lookup and it is reponsible for providing "hints" - e.g. map mapping strings to various objects.

Group of layer interfaces

Interface Name	In/Out	Stability	Specified in What Document?
Loaders-folder-any-Actions	Exported	Stable	The actions that the default folder loader shows in its popup menu are read from a layer folder `Loaders/folder/any/Actions` so if any module wishes to extend, hide or reorder some of them it can just register its actions there.
Loaders-text-xml-Actions	Exported	Stable	The actions that the standard XML loader shows in its popup menu are read from a layer folder `Loaders/text/xml/Actions`
Loaders-content-unknown-Actions	Exported	Stable	The actions that the loader for unrecognized files shows in its popup menu are read from a layer folder `Loaders/content/unknown/Actions`
Loaders-application-x-nbsettings-Actions	Exported	Stable	The actions that the loader for instance and settings files shows in its popup menu are read from a layer folder `Loaders/application/x-nbsettings/Actions`
Loaders-mime-type-Factories	Exported	Stable	.../org/openide/loaders/doc-files/api.html Loaders are registered in the layer in folder `Loaders/mime/type/Factories`.
PrivilegedTemplates	Exported	Under Development	A folder Privileged offers to other module possibility add own templates.
RecentTemplates	Exported	Private	A folder Recent stores a set of recently used templates, it's not open to other module.
Menu	Exported	Stable	The main menu of the application is composed by reading `Menu/` folder in the layer. A sub folder is treated as a sub menu. Instances of individual files (usually `.instance` or `.shadow`) may then represent Action or JMenuItem or JSeparator. Since version 7.44 one can attach `property-prefix` attribute to every folder. Then all the file attributes are scanned and if some of them start with the specified prefix they are placed a client properties on the JMenu instance (after stripping the prefix off).

Group of property interfaces

Interface Name	In/Out	Stability	Specified in What Document?
NetBeansAttrAssignedLoader	Exported	Stable	Extended attribute for holding the class of the loader that should be used to recognize a file object before the normal processing takes place.
NetBeansAttrAssignedLoaderModule	Exported	Private	Extended attribute which may be used in addition to EA_ASSIGNED_LOADER which indicates the code name base of the module that installed that preferred loader. If the indicated module is not installed, ignore the loader request. See #13816.
template	Exported	Stable	If set to Boolean.TRUE the file is recognized as template and its instantiation is allowed.
isRemoteAndSlow	Exported	Friend	If the file attribute `isRemoteAndSlow` is `true` on a folder, the New File wizard will avoid asking for its children.
templateWizardURL	Exported	Stable	Attribute that defines a template wizard description page (type `URL` to HTML).
templateWizardIterator	Exported	Stable	Attribute that defines a custom template wizard iterator (type `TemplateWizard.Iterator`).
originalFile	Exported	Stable	Path to the target file in its filesystem (type `String`).
originalFileSystem	Exported	Stable	System name of filesystem of target file (type `String`; default is same as that of shadow).
UseOwnName	Exported	Private	if true, the DataShadow name is used instead of original's name, affects DataShadows of filesystem roots only
simple	Exported	Stable	templates and folders under `Templates/` folder can be annotated with <attr name="simple" boolvalue="false"< if they are supposed to be hidden in Template Manager. If a folder is annotated with this attribute, it is also hidden in standard New File wizard.
PartialOrders	Exported	Stable	Read the list of intended partial orders from disk. Each element is a string of the form `a/b` for `a`, `b` filenames with extension, where `a` should come before `b`. The value of the attribute must be of type `Boolean`; ignored unless `true`.
OpenIDE-Folder-SortMode	Exported	Private	Extended attribute for order of children. The values are "F", "N", "C", "0" (type `String`).
OpenIDE-Folder-Order	Exported	Private	Extended attribute for order of children - stores list of file names separated by '/' (type `String`).
EA-OpenIDE-Connection	Exported	Private	Extended attribute to store (ArrayList of Type and Node.Handle). Used by Java synchronization feature at least; generally, `ConnectionCookie`.
DataFolder.Index.reorderable	Exported	Friend	If set to `Boolean.TRUE` on a folder not in the system filesystem, make its node reorderable.
wizard.anything	Exported	Stable	When TemplateWizard invokes DataObject.createFromTemplate, it passes as argument all its properties to it with prefix `wizard.`. That way they are available to underlaying scripting and templating engines.

Group of systemproperty interfaces

Interface Name	In/Out	Stability	Specified in What Document?
org.openide.loaders.FolderChildren.delayedCreation	Exported	Under Development	Since 7.25 the `DataFolder.getNodeDelegate()` tries to prevent creation of DataObject in AWT dispatch thread. Rather it creates dummy node with name derived from the name of the file and simplified content of lookup: FileObject - the file that the node represents Node - the node itself, but without any important properties DataObject - created on the fly, very inefficient, if requested from AWT dispatch thread, it prints a warning. Consider using just FileObject. The creation of real node is scheduled to background and as soon as the DataObject and its Node are ready, the initial dummy node is replaced by the real one. This whole system is slightly incompatible and may complicate creation of filtered views over the node hierarchy (one needs to be ready to really dynamics changes). That is why it is possible to disable the new delayed system by starting the system with `-Dorg.openide.loaders.FolderChildren.delayedCreation=false`. Use this property as a temporary fix for your problems, but consider fixing your code to support the delayed mode in the future.
org.openide.loaders.FolderList.refresh.interval	Exported	Private	The value of type integer determines the number of milliseconds between successive refreshes of contents of a folder. Can be used to tweak performance of folder refresh. Defaults to 10.
netbeans.dataobject.insecure.operation	Exported	Friend	If set to true, the `DataObject.copy, move, createFromTemplate` are executed in insecure way. That means that other threads can access the products of such operation before it finishes. This is a friend contract with projects, that need to do such strange things. Will be removed when they fix it.

Group of javax.swing.UIManager interfaces

Interface Name	In/Out	Stability	Specified in What Document?
Nb.Explorer.Folder.icon	Exported	Under Development	Icon or Image for closed folder.
Nb.Explorer.Folder.openedIcon	Exported	Under Development	Icon or Image for opened folder.
Tree.openedIcon	Exported	Under Development	Fallback Icon or Image for opened folder.
Tree.closedIcon	Exported	Under Development	Fallback Icon or Image for folder.

Group of branding interfaces

Interface Name In/Out Stability Specified in What Document?

org.netbeans.modules.openide.loaders.ASK_OnSaving

Exported

Stable

Control on save yes/no dialog in DataEditorSupport by setting the ASK_OnSaving key in org/netbeans/modules/openide/loaders/Bundle.properties to yes or no in a branding file in your application.

org.netbeans.modules.openide.loaders.ASK_OnClosing

Exported

Stable

Control on close yes/no dialog in DataEditorSupport by setting the ASK_OnClosing key in org/netbeans/modules/openide/loaders/Bundle.properties to yes or no in a branding file in your application.

Group of preferences interfaces

Interface Name In/Out Stability Specified in What Document?

org.openide.actions.FileSystemRefreshAction.manual

Exported

Under Development

If NbPreferences.root().node("org/openide/actions/FileSystemRefreshAction").getBoolean("manual", false) returns true, then FileSystemRefreshAction is displayed in popup menu of folders.

Implementation Details

Where are the sources for the module?

The sources for the module are in the Apache Git repositories or in the GitHub repositories.

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

XXX no answer for deploy-dependencies

Read more about the implementation in the answers to architecture questions.

Datasystems APIOfficial

What is New (see all changes)?

Use Cases

Using Scripting and Templating Languages

How to add action to folder's popup menu?

How to allow others to enhance actions of your loader?

Exported Interfaces

Group of java interfaces

Group of lookup interfaces

Group of layer interfaces

Group of property interfaces

Group of systemproperty interfaces

Group of javax.swing.UIManager interfaces

Group of branding interfaces

Group of preferences interfaces

Implementation Details

Where are the sources for the module?

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

Datasystems API
Official