Class DataObject

java.lang.Object
org.openide.loaders.DataObject
All Implemented Interfaces:
Serializable, org.openide.nodes.Node.Cookie, org.openide.util.HelpCtx.Provider, org.openide.util.Lookup.Provider
Direct Known Subclasses:
MultiDataObject
public abstract class DataObject extends Object implements org.openide.nodes.Node.Cookie, Serializable, org.openide.util.HelpCtx.Provider, org.openide.util.Lookup.Provider
Object that represents one or more file objects, with added behavior accessible though getLookup() lookup pattern. Since version 6.0 this class implements Lookup.Provider.
See Also:

  • Field Details

    • PROP_TEMPLATE

      public static final String PROP_TEMPLATE
      Name of the template property.
      See Also:

    • PROP_NAME

      public static final String PROP_NAME
      Name of the name property.
      See Also:

    • PROP_HELP

      public static final String PROP_HELP
      Name of the help context property.
      See Also:

    • PROP_MODIFIED

      public static final String PROP_MODIFIED
      Name of the modified property.
      See Also:

    • PROP_VALID

      public static final String PROP_VALID
      Name of valid property. Allows listening to deletion or disposal of the data object.
      See Also:

    • PROP_PRIMARY_FILE

      public static final String PROP_PRIMARY_FILE
      Name of primary file property. Primary file is changed when the object is moved
      See Also:

    • PROP_FILES

      public static final String PROP_FILES
      Name of files property. Allows listening to set of files handled by this object.
      See Also:

  • Constructor Details

    • DataObject

      public DataObject(org.openide.filesystems.FileObject pf, DataLoader loader) throws DataObjectExistsException
      Create a new data object.
      Parameters:
      pf - primary file object for this data object
      loader - loader that created the data object
      Throws:
      DataObjectExistsException - if there is already a data object for this primary file

  • Method Details

    • dispose

      protected void dispose()
      Allows subclasses to discard the object. When an object is discarded, it is released from the list of objects registered in the system. Then the contents of the parent folder (if it still exists) are rescanned, which may result in the creation of a new data object for the primary file.

      The normal use of this method is to change the type of a data object. Because this would usually only be invoked from the original data object, it is protected.

    • setValid

      public void setValid(boolean valid) throws PropertyVetoException
      Setter that allows to destroy this data object. Because such operation can be dangerous and not always possible (if the data object is opened in editor) it can be vetoed. Either by this data object or by any vetoable listener attached to this object (like editor support)
      Parameters:
      valid - should be false
      Throws:
      PropertyVetoException - if the invalidation has been vetoed

    • isValid

      public final boolean isValid()
      Test whether the data object is still valid and usable.

      The object can become invalid when it is deleted, its files are deleted, or dispose() is called.

      When the validity of the object changes a property change event is fired, so anyone can listen and be notified when the object is deleted/disposed.

    • getLoader

      public final DataLoader getLoader()
      Get the loader that created this data object.
      Returns:
      the data loader

    • markFiles

      protected final void markFiles() throws IOException
      Mark all contained files as belonging to this loader. If the files are rescanned (e.g. after a disposal), the current data loader will be given preference.
      Throws:
      IOException

    • files

      public Set<org.openide.filesystems.FileObject> files()
      Get all contained files. These file objects should ideally have had the important flag set appropriately.

      The default implementation returns a set consisting only of the primary file.

      Returns:
      set of files

    • getNodeDelegate

      public final org.openide.nodes.Node getNodeDelegate()
      Get the node delegate. Either creates it (if it does not already exist) or returns a previously created instance of it.
      Returns:
      the node delegate (without parent) for this data object
      See Also:

    • createNodeDelegate

      protected org.openide.nodes.Node createNodeDelegate()
      Provides node that should represent this data object.

      The default implementation creates an instance of DataNode. Most subclasses will override this method to provide a DataNode (usually subclassed).

      This method is called only once per data object.

      It is strongly recommended that the resulting node will, when asked for the cookie DataObject.class, return this same data object.

      It is also recommended that the node:

      1. Base its name on getName().
      2. Base its display name additionally on DataNode.getShowFileExtensions().
      Returns:
      the node delegate (without parent) for this data object
      See Also:

    • takePrimaryFileLock

      protected org.openide.filesystems.FileLock takePrimaryFileLock() throws IOException
      Obtains lock for primary file.
      Returns:
      the lock
      Throws:
      IOException - if taking the lock fails

    • setTemplate

      public final void setTemplate(boolean newTempl) throws IOException
      Set the template status of this data object.
      Parameters:
      newTempl - true if the object should be a template
      Throws:
      IOException - if setting the template state fails

    • isTemplate

      public final boolean isTemplate()
      Get the template status of this data object.
      Returns:
      true if it is a template

    • isDeleteAllowed

      public abstract boolean isDeleteAllowed()
      Test whether the object may be deleted.
      Returns:
      true if it may

    • isCopyAllowed

      public abstract boolean isCopyAllowed()
      Test whether the object may be copied.
      Returns:
      true if it may

    • isMoveAllowed

      public abstract boolean isMoveAllowed()
      Test whether the object may be moved.
      Returns:
      true if it may

    • isShadowAllowed

      public boolean isShadowAllowed()
      Test whether the object may create shadows.

      The default implementation returns true.

      Returns:
      true if it may

    • isRenameAllowed

      public abstract boolean isRenameAllowed()
      Test whether the object may be renamed.
      Returns:
      true if it may

    • isModified

      public boolean isModified()
      Test whether the object is modified.
      Returns:
      true if it is modified

    • setModified

      public void setModified(boolean modif)
      Set whether the object is considered modified. Also fires a change event. If the new value is true, the data object is added into a registry of opened data objects. If the new value is false, the data object is removed from the registry.

    • getHelpCtx

      public abstract org.openide.util.HelpCtx getHelpCtx()
      Get help context for this object.
      Specified by:
      getHelpCtx in interface org.openide.util.HelpCtx.Provider
      Returns:
      the help context

    • getPrimaryFile

      public final org.openide.filesystems.FileObject getPrimaryFile()
      Get the primary file for this data object. For example, Java source uses *.java and *.class files but the primary one is always *.java. Please note that two data objects are equivalent if they use the same primary file.

      Warning: do not call Node.getHandle() or DefaultHandle.createHandle(Node) in this method.

      Returns:
      the primary file

    • find

      public static DataObject find(org.openide.filesystems.FileObject fo) throws DataObjectNotFoundException
      Finds the data object for a specified file object.
      Parameters:
      fo - file object
      Returns:
      the data object for that file
      Throws:
      DataObjectNotFoundException - if the file does not have a data object

    • getRegistry

      public static DataObject.Registry getRegistry()
      Get the registry containing all modified objects.
      Returns:
      the registry

    • getName

      public String getName()
      Get the name of the data object.

      The default implementation uses the name of the primary file.

      Returns:
      the name

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getFolder

      public final DataFolder getFolder()
      Get the folder this data object is stored in.
      Returns:
      the folder; null if the primary file is the root of its filesystem

    • copy

      public final DataObject copy(DataFolder f) throws IOException
      Copy this object to a folder. The copy of the object is required to be deletable and movable.

      An event is fired, and atomicity is implemented.

      Parameters:
      f - the folder to copy the object to
      Returns:
      the new object
      Throws:
      IOException - if something went wrong

    • handleCopy

      protected abstract DataObject handleCopy(DataFolder f) throws IOException
      Copy this object to a folder (implemented by subclasses).
      Parameters:
      f - target folder
      Returns:
      the new data object
      Throws:
      IOException - if an error occures

    • handleCopyRename

      protected DataObject handleCopyRename(DataFolder f, String name, String ext) throws IOException
      Copy and rename this object to a folder (implemented by subclasses).
      Parameters:
      f - target folder
      name - new file name
      ext - new file extension
      Returns:
      the new data object
      Throws:
      IOException - if an error occures or the file cannot be copied/renamed
      Since:
      6.3

    • delete

      public final void delete() throws IOException
      Delete this object.

      Events are fired and atomicity is implemented.

      Throws:
      IOException - if an error occures

    • handleDelete

      protected abstract void handleDelete() throws IOException
      Delete this object (implemented by subclasses).
      Throws:
      IOException - if an error occures

    • rename

      public final void rename(String name) throws IOException
      Rename this object.

      Events are fired and atomicity is implemented.

      Parameters:
      name - the new name
      Throws:
      IOException - if an error occurs

    • handleRename

      protected abstract org.openide.filesystems.FileObject handleRename(String name) throws IOException
      Rename this object (implemented in subclasses).
      Parameters:
      name - name to rename the object to
      Returns:
      new primary file of the object
      Throws:
      IOException - if an error occures

    • move

      public final void move(DataFolder df) throws IOException
      Move this object to another folder.

      An event is fired and atomicity is implemented.

      Parameters:
      df - folder to move object to
      Throws:
      IOException - if an error occurs

    • handleMove

      protected abstract org.openide.filesystems.FileObject handleMove(DataFolder df) throws IOException
      Move this object to another folder (implemented in subclasses).
      Parameters:
      df - target data folder
      Returns:
      new primary file of the object
      Throws:
      IOException - if an error occures

    • handleCreateShadow

      protected DataShadow handleCreateShadow(DataFolder f) throws IOException
      Creates shadow for this object in specified folder (overridable in subclasses).

      The default implementation creates a reference data shadow and pastes it into the specified folder.

      Parameters:
      f - the folder to create a shortcut in
      Returns:
      the shadow
      Throws:
      IOException

    • createShadow

      public final DataShadow createShadow(DataFolder f) throws IOException
      Creates shadow for this object in specified folder.

      An event is fired and atomicity is implemented.

      Parameters:
      f - the folder to create shortcut in
      Returns:
      the shadow
      Throws:
      IOException

    • createFromTemplate

      public final DataObject createFromTemplate(DataFolder f) throws IOException
      Create a new object from template (with a name depending on the template).
      Parameters:
      f - folder to create object in
      Returns:
      new data object based on this one
      Throws:
      IOException - if an error occured
      See Also:

    • createFromTemplate

      public final DataObject createFromTemplate(DataFolder f, String name) throws IOException
      Create a new object from template. Asks handleCreateFromTemplate(DataFolder, String).
      Parameters:
      f - folder to create object in
      name - name of object that should be created, or null if the name should be same as that of the template (or otherwise mechanically generated)
      Returns:
      the new data object
      Throws:
      IOException - if an error occured

    • createFromTemplate

      public final DataObject createFromTemplate(DataFolder f, String name, Map<String, ? extends Object> parameters) throws IOException
      More generic way how to instantiate a DataObject. One can not only specify its name, but also pass a map of parameters that can influence the copying of the stream.
      Parameters:
      f - folder to create object in
      name - name of object that should be created, or null if the name should be same as that of the template (or otherwise mechanically generated)
      parameters - map of named objects that are going to be used when creating the new object
      Returns:
      the new data object
      Throws:
      IOException - if an error occured
      Since:
      6.1

    • handleCreateFromTemplate

      protected abstract DataObject handleCreateFromTemplate(DataFolder df, String name) throws IOException
      Create a new data object from template (implemented in subclasses). This method should copy the content of the template to the destination folder and assign a new name to the new object.
      Parameters:
      df - data folder to create object in
      name - name to give to the new object (or null if the name should be chosen according to the template)
      Returns:
      the new data object
      Throws:
      IOException - if an error occured

    • addPropertyChangeListener

      public void addPropertyChangeListener(PropertyChangeListener l)
      Add a property change listener.
      Parameters:
      l - the listener to add

    • removePropertyChangeListener

      public void removePropertyChangeListener(PropertyChangeListener l)
      Remove a property change listener.
      Parameters:
      l - the listener to remove

    • firePropertyChange

      protected final void firePropertyChange(String name, Object oldValue, Object newValue)
      Fires property change notification to all listeners registered via addPropertyChangeListener(PropertyChangeListener).
      Parameters:
      name - of property
      oldValue - old value
      newValue - new value

    • addVetoableChangeListener

      public void addVetoableChangeListener(VetoableChangeListener l)
      Add a listener to vetoable changes.
      Parameters:
      l - the listener to add
      See Also:

    • removeVetoableChangeListener

      public void removeVetoableChangeListener(VetoableChangeListener l)
      Add a listener to vetoable changes.
      Parameters:
      l - the listener to remove
      See Also:

    • fireVetoableChange

      protected final void fireVetoableChange(String name, Object oldValue, Object newValue) throws PropertyVetoException
      Fires vetoable change notification.
      Parameters:
      name - of property
      oldValue - old value
      newValue - new value
      Throws:
      PropertyVetoException - if the change has been vetoed

    • getCookie

      public <T extends org.openide.nodes.Node.Cookie> T getCookie(Class<T> c)
      Obtain a cookie from the data object. May be overridden by subclasses to extend the behaviour of data objects.

      The default implementation tests if this object is of the requested class and if so, returns it.

      Warning: the getCookie(Class) method and getLookup() method are ment to be interchangable - e.g. if you override one of them be sure to override also the other and try as much as possible to keep the same content in each of them. The default implementation tries to do that as much as possible.

      Parameters:
      c - class of requested cookie
      Returns:
      a cookie or null if such cookies are not supported

    • getLookup

      public org.openide.util.Lookup getLookup()
      Represents a context of the data object. This method is a more general replacement for getCookie(Class) and should preferably be used instead of the old method. The default implementation inside a data object returns the getNodeDelegate().getLookup() - which is the most compatible behaviour with previous versions. However this code has significant potential to deadlocks. That is why the preferred advice is to override the method to: 
       class MyDataObject extends MultiDataObject {
   public @Override Lookup getLookup() {
     return getCookieSet().getLookup();
   }
 }

      Warning: the getCookie(Class) method and getLookup() method are ment to be interchangable - e.g. if you override one of them be sure to override also the other and try as much as possible to keep the same content in each of them. The default implementation tries to do that as much as possible.

      Specified by:
      getLookup in interface org.openide.util.Lookup.Provider
      Returns:
      lookup representing this data object and its content
      Since:
      6.0

    • getCookie

      protected <T extends org.openide.nodes.Node.Cookie> T getCookie(DataShadow shadow, Class<T> clazz)
      When a request for a cookie is done on a DataShadow of this DataObject this methods gets called (by default) so the DataObject knows which DataShadow is asking and extract some information from the shadow itself.

      Subclasses can override this method with better logic, but the default implementation just delegates to getCookie (Class).

      Parameters:
      shadow - the shadow for which is asking
      clazz - class to search for
      Returns:
      the cookie or null
      Since:
      1.16

    • writeReplace

      public Object writeReplace()
      The Serialization replacement for this object stores the primary file instead.
      Returns:
      a replacement