org.openide.loaders 5.9.22

org.openide.loaders
Class DataObject

java.lang.Object
  extended by org.openide.loaders.DataObject
All Implemented Interfaces:
Serializable, Node.Cookie, HelpCtx.Provider
Direct Known Subclasses:
MultiDataObject

public abstract class DataObject
extends Object
implements Node.Cookie, Serializable, HelpCtx.Provider

Object that represents one or more file objects, with added behavior.

See Also:
Serialized Form

Nested Class Summary
static interface DataObject.Container
          Interface for objects that can contain other data objects.
static class DataObject.Registry
          Registry of modified data objects.
 
Field Summary
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
DataObject(FileObject pf, DataLoader loader)
          Create new data object.
 
Method Summary
 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.
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 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 addPropertyChangeListener(java.beans.PropertyChangeListener).
protected  void fireVetoableChange(String name, Object oldValue, Object newValue)
          Fires vetoable change notification.
 Node.Cookie getCookie(Class c)
          Obtain a cookie from the data object.
protected  Node.Cookie getCookie(DataShadow shadow, Class 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.
 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 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 new data object.

Important notice: The constructor registers this data object in DataObjectPool. The registration is currently delayed by 500 ms. After this time any other thread can obtain this data object using DataObject.find(fileObject) method.

It is recommended to eliminate time-consuming functionality in constructors of DataObject's subclasses.

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 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 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 FileObjects

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 getName().
  2. Base its display name additionally on DataNode.getShowFileExtensions().
  3. Tune its display name and icon according to FileSystem.Status.

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

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:
createFromTemplate(DataFolder,String)

createFromTemplate

public final DataObject createFromTemplate(DataFolder f,
                                           String name)
                                    throws IOException
Create a new object from template. Asks 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

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(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:
PROP_VALID

removeVetoableChangeListener

public void removeVetoableChangeListener(VetoableChangeListener l)
Add a listener to vetoable changes.

Parameters:
l - the listener to remove
See Also:
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 Node.Cookie getCookie(Class 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.

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

getCookie

protected Node.Cookie getCookie(DataShadow shadow,
                                Class 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

org.openide.loaders 5.9.22

Built on July 11 2007.  |  Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.