DataObject (Datasystems API)

java.lang.Object
- org.openide.loaders.DataObject

All Implemented Interfaces:

Serializable, Node.Cookie, HelpCtx.Provider, Lookup.Provider

Direct Known Subclasses:

MultiDataObject
```
public abstract class DataObject
extends Object
implements Node.Cookie, Serializable, HelpCtx.Provider, Lookup.Provider
```
Object that represents one or more file objects, with added behavior accessible though DataObject.getLookup() lookup pattern. Since version 6.0 this class implements Lookup.Provider.

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`DataObject.Container` Interface for objects that can contain other data objects.
`static interface`	`DataObject.Factory` Factory interface for converting file object to data objects.
`static interface`	`DataObject.Registration` Registers new file type into the system.
`static interface`	`DataObject.Registrations` May be used to allow multiple `DataObject.Registration` at one place.
`static class`	`DataObject.Registry` Registry of modified data objects.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`PROP_COOKIE` Name of the property used during notification of changes in the set of cookies attached to this object.
`static String`	`PROP_FILES` Name of files property.
`static String`	`PROP_HELP` Name of the help context property.
`static String`	`PROP_MODIFIED` Name of the modified property.
`static String`	`PROP_NAME` Name of the name property.
`static String`	`PROP_PRIMARY_FILE` Name of primary file property.
`static String`	`PROP_TEMPLATE` Name of the template property.
`static String`	`PROP_VALID` Name of valid property.

Constructor Summary

Constructors
Constructor and Description

DataObject(FileObject pf, DataLoader loader)
Create a new data object.

Constructors
Constructor and Description
`DataObject(FileObject pf, DataLoader loader)` Create a new data object.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addPropertyChangeListener(PropertyChangeListener l)` Add a property change listener.
`void`	`addVetoableChangeListener(VetoableChangeListener l)` Add a listener to vetoable changes.
`DataObject`	`copy(DataFolder f)` Copy this object to a folder.
`DataObject`	`createFromTemplate(DataFolder f)` Create a new object from template (with a name depending on the template).
`DataObject`	`createFromTemplate(DataFolder f, String name)` Create a new object from template.
`DataObject`	`createFromTemplate(DataFolder f, String name, Map<String,? extends Object> parameters)` More generic way how to instantiate a `DataObject`.
`protected Node`	`createNodeDelegate()` Provides node that should represent this data object.
`DataShadow`	`createShadow(DataFolder f)` Creates shadow for this object in specified folder.
`void`	`delete()` Delete this object.
`protected void`	`dispose()` Allows subclasses to discard the object.
`Set<FileObject>`	`files()` Get all contained files.
`static DataObject`	`find(FileObject fo)` Finds the data object for a specified file object.
`protected void`	`firePropertyChange(String name, Object oldValue, Object newValue)` Fires property change notification to all listeners registered via `DataObject.addPropertyChangeListener(java.beans.PropertyChangeListener)`.
`protected void`	`fireVetoableChange(String name, Object oldValue, Object newValue)` Fires vetoable change notification.
`<T extends Node.Cookie> T`	`getCookie(Class<T> c)` Obtain a cookie from the data object.
`protected <T extends 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.
`DataFolder`	`getFolder()` Get the folder this data object is stored in.
`abstract HelpCtx`	`getHelpCtx()` Get help context for this object.
`DataLoader`	`getLoader()` Get the loader that created this data object.
`Lookup`	`getLookup()` Represents a context of the data object.
`String`	`getName()` Get the name of the data object.
`Node`	`getNodeDelegate()` Get the node delegate.
`FileObject`	`getPrimaryFile()` Get the primary file for this data object.
`static DataObject.Registry`	`getRegistry()` Get the registry containing all modified objects.
`protected abstract DataObject`	`handleCopy(DataFolder f)` Copy this object to a folder (implemented by subclasses).
`protected DataObject`	`handleCopyRename(DataFolder f, String name, String ext)` Copy and rename this object to a folder (implemented by subclasses).
`protected abstract DataObject`	`handleCreateFromTemplate(DataFolder df, String name)` Create a new data object from template (implemented in subclasses).
`protected DataShadow`	`handleCreateShadow(DataFolder f)` Creates shadow for this object in specified folder (overridable in subclasses).
`protected abstract void`	`handleDelete()` Delete this object (implemented by subclasses).
`protected abstract FileObject`	`handleMove(DataFolder df)` Move this object to another folder (implemented in subclasses).
`protected abstract FileObject`	`handleRename(String name)` Rename this object (implemented in subclasses).
`abstract boolean`	`isCopyAllowed()` Test whether the object may be copied.
`abstract boolean`	`isDeleteAllowed()` Test whether the object may be deleted.
`boolean`	`isModified()` Test whether the object is modified.
`abstract boolean`	`isMoveAllowed()` Test whether the object may be moved.
`abstract boolean`	`isRenameAllowed()` Test whether the object may be renamed.
`boolean`	`isShadowAllowed()` Test whether the object may create shadows.
`boolean`	`isTemplate()` Get the template status of this data object.
`boolean`	`isValid()` Test whether the data object is still valid and usable.
`protected void`	`markFiles()` Mark all contained files as belonging to this loader.
`void`	`move(DataFolder df)` Move this object to another folder.
`void`	`removePropertyChangeListener(PropertyChangeListener l)` Remove a property change listener.
`void`	`removeVetoableChangeListener(VetoableChangeListener l)` Add a listener to vetoable changes.
`void`	`rename(String name)` Rename this object.
`void`	`setModified(boolean modif)` Set whether the object is considered modified.
`void`	`setTemplate(boolean newTempl)` Set the template status of this data object.
`void`	`setValid(boolean valid)` Setter that allows to destroy this data object.
`protected FileLock`	`takePrimaryFileLock()` Obtains lock for primary file.
`String`	`toString()`
`Object`	`writeReplace()` The Serialization replacement for this object stores the primary file instead.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - PROP_TEMPLATE
```
public static final String PROP_TEMPLATE
```
    Name of the template property.
    
    See Also:
    
    Constant Field Values
  - PROP_NAME
```
public static final String PROP_NAME
```
    Name of the name property.
    
    See Also:
    
    Constant Field Values
  - PROP_HELP
```
public static final String PROP_HELP
```
    Name of the help context property.
    
    See Also:
    
    Constant Field Values
  - PROP_MODIFIED
```
public static final String PROP_MODIFIED
```
    Name of the modified property.
    
    See Also:
    
    Constant Field Values
  - PROP_COOKIE
```
public static final String PROP_COOKIE
```
    Name of the property used during notification of changes in the set of cookies attached to this object.
    
    See Also:
    
    Constant Field Values
  - PROP_VALID
```
public static final String PROP_VALID
```
    Name of valid property. Allows listening to deletion or disposal of the data object.
    
    See Also:
    
    Constant Field Values
  - 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:
    
    Constant Field Values
  - PROP_FILES
```
public static final String PROP_FILES
```
    Name of files property. Allows listening to set of files handled by this object.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - DataObject
```
public DataObject(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 Detail
  - 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 DataObject.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<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 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:
    
    Datasystems API - Node Delegates
  - createNodeDelegate
```
protected 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 DataObject.getName().
    2. Base its display name additionally on DataNode.getShowFileExtensions().
    Returns:
    
    the node delegate (without parent) for this data object
    
    See Also:
    
    Datasystems API - Creating a node delegate
  - takePrimaryFileLock
```
protected 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 HelpCtx getHelpCtx()
```
    Get help context for this object.
    
    Specified by:
    
    getHelpCtx in interface HelpCtx.Provider
    
    Returns:
    
    the help context
  - getPrimaryFile
```
public final 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(org.openide.nodes.Node) in this method.
    
    Returns:
    
    the primary file
  - find
```
public static DataObject find(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 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 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:
    
    DataObject.createFromTemplate(DataFolder,String)
  - createFromTemplate
```
public final DataObject createFromTemplate(DataFolder f,
                                           String name)
                                    throws IOException
```
    Create a new object from template. Asks DataObject.handleCreateFromTemplate(org.openide.loaders.DataFolder, java.lang.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 DataObject.addPropertyChangeListener(java.beans.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:
    
    DataObject.PROP_VALID
  - removeVetoableChangeListener
```
public void removeVetoableChangeListener(VetoableChangeListener l)
```
    Add a listener to vetoable changes.
    
    Parameters:
    
    l - the listener to remove
    
    See Also:
    
    DataObject.PROP_VALID
  - 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 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 DataObject.getCookie(java.lang.Class<T>) method and DataObject.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 Lookup getLookup()
```
    Represents a context of the data object. This method is a more general replacement for DataObject.getCookie(java.lang.Class<T>) 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 DataObject.getCookie(java.lang.Class<T>) method and DataObject.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 Lookup.Provider
    
    Returns:
    
    lookup representing this data object and its content
    
    Since:
    
    6.0
  - getCookie
```
protected <T extends 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:
    
    clazz - class to search for
    
    shadow - the shadow for which is asking
    
    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

Class DataObject

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PROP_TEMPLATE

PROP_NAME

PROP_HELP

PROP_MODIFIED

PROP_COOKIE

PROP_VALID

PROP_PRIMARY_FILE

PROP_FILES

Constructor Detail

DataObject

Method Detail

dispose

setValid

isValid

getLoader

markFiles

files

getNodeDelegate

createNodeDelegate

takePrimaryFileLock

setTemplate

isTemplate

isDeleteAllowed

isCopyAllowed

isMoveAllowed

isShadowAllowed

isRenameAllowed

isModified

setModified

getHelpCtx

getPrimaryFile

find

getRegistry

getName

toString

getFolder

copy

handleCopy

handleCopyRename

delete

handleDelete

rename

handleRename

move

handleMove

handleCreateShadow

createShadow

createFromTemplate

createFromTemplate

createFromTemplate

handleCreateFromTemplate

addPropertyChangeListener

removePropertyChangeListener

firePropertyChange

addVetoableChangeListener

removeVetoableChangeListener

fireVetoableChange

getCookie

getLookup

getCookie

writeReplace