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.
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.
org.openide.loaders.DataFolder.lazy
FolderLookup are delivered in dedicated thread
DataShadow.findOriginal which extracts the original file from
a FileObject representing a shadow/link.
DataObject.Registration and DataObject.Registrations
ToolbarPool.isFinished
Template
org.openide.loaders.DataFolder.lazy
CreateFromTemplateHandler.FREE_FILE_EXTENSION
AcceleratorBinding
annotateName and toolTip to DataEditorSupport
FolderLookup are delivered in dedicated thread
wizard.
DataFolder.FolderNode.setName()
DataEditorSupport
DataLoaderPool.getDefault()
DataLoader can be specified in a layer
ChangeableDataFilter interface
DataShadow uses URL for storage
DataNode.getHtmlDisplayName was implemented
org.openide.awt.MenuBar
to understand Components.
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
DataShadow.findOriginal which extracts the original file from
a FileObject representing a shadow/link.
DataObject.Registration and DataObject.Registrations
ToolbarPool.isFinished
Template
org.openide.loaders.DataFolder.lazy
CreateFromTemplateHandler.FREE_FILE_EXTENSION
AcceleratorBinding
annotateName and toolTip to DataEditorSupport
FolderLookup are delivered in dedicated thread
wizard.
DataFolder.FolderNode.setName()
DataEditorSupport
DataLoaderPool.getDefault()
DataLoader can be specified in a layer
ChangeableDataFilter interface
DataShadow uses URL for storage
DataNode.getHtmlDisplayName was implemented
org.openide.awt.MenuBar
to understand Components.
org.openide.awt.AcceleratorBinding
AcceleratorBinding
org.openide.loaders.ChangeableDataFilter
ChangeableDataFilter interface
org.openide.loaders.CreateFromTemplateAttributesProvider
org.openide.loaders.CreateFromTemplateHandler
CreateFromTemplateHandler.FREE_FILE_EXTENSION
org.openide.text.DataEditorSupport
annotateName and toolTip to DataEditorSupport
DataEditorSupport
org.openide.loaders.DataFilter
org.openide.loaders.DataFolder
org.openide.loaders.DataFolder.lazy
org.openide.loaders.DataLoader
DataLoader can be specified in a layer
org.openide.loaders.DataLoaderPool
DataLoaderPool.getDefault()
org.openide.loaders.DataNode
DataNode.getHtmlDisplayName was implemented
org.openide.loaders.DataObject
DataObject.Registration and DataObject.Registrations
org.openide.loaders.DataShadow
DataShadow.findOriginal which extracts the original file from
a FileObject representing a shadow/link.
org.openide.actions.FileSystemAction
org.openide.loaders.FolderLookup
org.openide.loaders.FolderRenameHandler
DataFolder.FolderNode.setName()
org.openide.awt.MenuBar
org.openide.awt.MenuBar
to understand Components.
org.openide.loaders.MultiDataObject
org.openide.loaders.SaveAsCapable
org.netbeans.api.templates.TemplateRegistration
Template
org.netbeans.api.templates.TemplateRegistrations
Template
org.openide.loaders.TemplateWizard
org.openide.awt.Toolbar
org.openide.awt.ToolbarPool
ToolbarPool.isFinished
org.openide.loaders.XMLDataObject
Toolbar; made by: mentlicher; issues:
#
MenuBar; made by: jtulach; issues:
#222138
Layer declaration of a menu can influence what client properties the actual JMenu instances will have. More details.
ToolbarPool.isFinished
ToolbarPool; made by: jtulach; issues:
#192207
One can find out if ToolbarPool is initialized.
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 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.
AcceleratorBinding
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.)
Toolbar ToolbarPool; made by: saubrecht; issues:
#59242
Deprecated methods related to Toolbar drag and drop.
org.openide.awt.MenuBar
to understand Components.
MenuBar; made by: pnejedly
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.
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; made by: jtulach; issues:
#199416
One can control what Lookup will be associated with DataEditorSupport.
DataEditorSupport; made by: jtulach
New create factory method to allow creation
of different CloneableEditorSupport.Pane implementations
than the default CloneableEditor.
annotateName and toolTip to DataEditorSupport
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.
DataEditorSupport
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.
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.
CreateFromTemplateAttributesProvider CreateFromTemplateHandler; made by: sdedic; issues:
#
openide.filesystems.templates module; see javadoc for
FileBuilder for details.
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.
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.
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.
DataShadow.findOriginal which extracts the original file from
a FileObject representing a shadow/link.
DataShadow; made by: sdedic
DataObject.Registration and DataObject.Registrations
DataObject; made by: skygo; issues:
#207219
#208670
Introduced a new annotation for registering DataObject.
Template
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.
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.
registerEditor method which might clash
with some existing method in subclasses, although it is
hopefully not very likely.
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.
org.openide.loaders.DataFolder.lazy
DataFolder; made by: jtulach
The private API to honor
org.openide.loaders.DataFolder.lazy property
has been removed, as being obsolete.
CreateFromTemplateHandler.FREE_FILE_EXTENSION
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.
XMLDataObject; made by: jtulach; issues:
#175750
New constructor for subclasses of XMLDataObject.
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.
FolderLookup are delivered in dedicated thread
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.
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.
DataObject DataLoader; made by: jtulach; issues:
#91665
There is new
registration
scheme for DataLoaders.
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).
wizard.
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 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 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 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; 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 EditorKit.read or EditorKit.write.
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 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.
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.
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.
DataNode; made by: jtulach; issues:
#61824
DataFolder.FolderNode.setName()
FolderRenameHandler; made by: jbecicka; issues:
#53295
DataLoaderPool.getDefault()
DataLoaderPool; made by: jtulach; issues:
#41650
DataLoaderPool now has a new method getDefault()
to allow simple access to the default system loader pool.
DataLoader can be specified in a layer
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.
ChangeableDataFilter interface
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.
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
DataNode.getHtmlDisplayName was implemented
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.
DataFolder; made by: jglick; issues:
#26667
LAST_MODIFIED and
SIZE, were added.
DataObject; made by: jtulach; issues:
#33750
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.
DataObject; made by: jtulach; issues:
#33469
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.
org.openide.loaders package were separated
out from the whole openide.jar into their own openide-loaders.jar.