InstanceDataObject (Datasystems API)

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

All Implemented Interfaces:

org.openide.cookies.InstanceCookie, org.openide.cookies.InstanceCookie.Of, org.openide.nodes.Node.Cookie
```
public class InstanceDataObject
extends MultiDataObject
implements org.openide.cookies.InstanceCookie.Of
```
A data object whose only purpose is to supply InstanceCookie. The instances are created by default instantiation; the name of the class to instantiate is stored on disk, typically right in the file name.
This data object is generally used to configure menus and toolbars, though it could be used in any situation requiring instances to be present in a folder; for example, anything using FolderInstance.
Typical instance classes are subclasses of SystemAction to make menu items or toolbar buttons; JSeparator for a menu separator; or JToolBar.Separator for a toolbar separator.
Use create(org.openide.loaders.DataFolder, java.lang.String, java.lang.String) and remove(org.openide.loaders.DataFolder, java.lang.String, java.lang.String) to make the objects. Better yet, use an XML filesystem to install them declaratively.
Instance data object by default recognizes all files with .instance suffix. Such file can have associated optional file attributes:

instanceCreate
instantionalized Object (e.g. created by methodvalue at XML filesystem)
instanceOf
String that is tokenized at ':', ',', ';' and whitespace boundaries. Resulting tokens represent class names that created instance is instanceof. Utilizing it may improve performance.
(optional file attributes documented since 3.34).

See Also:

Serialized Form

Nested Class Summary
- Nested classes/interfaces inherited from class org.openide.loaders.DataObject
  DataObject.Container, DataObject.Factory, DataObject.Registration, DataObject.Registrations, DataObject.Registry
- Nested classes/interfaces inherited from interface org.openide.cookies.InstanceCookie
  org.openide.cookies.InstanceCookie.Of
- Nested classes/interfaces inherited from class org.openide.loaders.MultiDataObject
  MultiDataObject.Entry

Field Summary

Fields
Modifier and Type Field Description

static java.lang.String INSTANCE
File extension for instance data objects.
- Fields inherited from class org.openide.loaders.DataObject
  PROP_COOKIE, PROP_FILES, PROP_HELP, PROP_MODIFIED, PROP_NAME, PROP_PRIMARY_FILE, PROP_TEMPLATE, PROP_VALID

Fields
Modifier and Type	Field	Description
`static java.lang.String`	`INSTANCE`	File extension for instance data objects.

Constructor Summary

Constructors
Constructor Description

InstanceDataObject(org.openide.filesystems.FileObject pf, MultiFileLoader loader)
Create a new instance.

Constructors
Constructor	Description
`InstanceDataObject(org.openide.filesystems.FileObject pf, MultiFileLoader loader)`	Create a new instance.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`static InstanceDataObject`	`create(DataFolder folder, java.lang.String name, java.lang.Class<?> clazz)`	Create a new `InstanceDataObject` in a given folder.
`static InstanceDataObject`	`create(DataFolder folder, java.lang.String name, java.lang.Object instance, org.openide.modules.ModuleInfo info)`	Create a new `InstanceDataObject` containing settings in a given folder.
`static InstanceDataObject`	`create(DataFolder folder, java.lang.String name, java.lang.Object instance, org.openide.modules.ModuleInfo info, boolean create)`	Create a new `InstanceDataObject` containing settings in a given folder.
`static InstanceDataObject`	`create(DataFolder folder, java.lang.String name, java.lang.String className)`	Create a new `InstanceDataObject` in a given folder.
`protected org.openide.nodes.Node`	`createNodeDelegate()`	Provides node that should represent this data object.
`protected void`	`dispose()`	Allows subclasses to discard the object.
`static InstanceDataObject`	`find(DataFolder folder, java.lang.String name, java.lang.Class<?> clazz)`	Finds instance of specified name in a given folder.
`static InstanceDataObject`	`find(DataFolder folder, java.lang.String name, java.lang.String className)`	Finds instance of specified name in a given folder.
`<T extends org.openide.nodes.Node.Cookie> T`	`getCookie(java.lang.Class<T> clazz)`	Look for a cookie in the current cookie set matching the requested class.
`org.openide.util.HelpCtx`	`getHelpCtx()`	Get help context for this object.
`org.openide.util.Lookup`	`getLookup()`	Represents a context of the data object.
`java.lang.String`	`getName()`	Get the name of the data object.
`protected DataObject`	`handleCopy(DataFolder df)`	Copies primary and secondary files to new folder.
`protected DataObject`	`handleCreateFromTemplate(DataFolder df, java.lang.String name)`	Create a new data object from template (implemented in subclasses).
`protected void`	`handleDelete()`	Delete this object (implemented by subclasses).
`protected org.openide.filesystems.FileObject`	`handleRename(java.lang.String name)`	Rename this object (implemented in subclasses).
`java.lang.Class<?>`	`instanceClass()`
`java.lang.Object`	`instanceCreate()`
`java.lang.String`	`instanceName()`
`boolean`	`instanceOf(java.lang.Class<?> type)`	Query if this instance can create object of given type.
`static boolean`	`remove(DataFolder folder, java.lang.String name, java.lang.Class<?> clazz)`	Remove an existing instance data object.
`static boolean`	`remove(DataFolder folder, java.lang.String name, java.lang.String className)`	Remove an existing instance data object.

Methods inherited from class org.openide.loaders.DataObject
addPropertyChangeListener, addVetoableChangeListener, copy, createFromTemplate, createFromTemplate, createFromTemplate, createShadow, delete, find, firePropertyChange, fireVetoableChange, getCookie, getFolder, getLoader, getNodeDelegate, getPrimaryFile, getRegistry, handleCreateShadow, isModified, isShadowAllowed, isTemplate, isValid, markFiles, move, removePropertyChangeListener, removeVetoableChangeListener, rename, setModified, setTemplate, setValid, toString, writeReplace

Methods inherited from class org.openide.loaders.MultiDataObject
addSecondaryEntry, associateLookup, files, findSecondaryEntry, getCookieSet, getMultiFileLoader, getPrimaryEntry, handleCopyRename, handleMove, isCopyAllowed, isDeleteAllowed, isMoveAllowed, isRenameAllowed, registerEditor, registerEntry, removeSecondaryEntry, secondaryEntries, setCookieSet, takePrimaryFileLock

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

- Field Detail
  - INSTANCE
```
public static final java.lang.String INSTANCE
```
    File extension for instance data objects.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - InstanceDataObject
```
public InstanceDataObject(org.openide.filesystems.FileObject pf,
                          MultiFileLoader loader)
                   throws DataObjectExistsException
```
    Create a new instance. Do not use this to make instances; use create(org.openide.loaders.DataFolder, java.lang.String, java.lang.String).
    
    Parameters:
    
    pf - primary file object for this data object
    
    loader - the loader
    
    Throws:
    
    DataObjectExistsException - if it already exists
- Method Detail
  - find
```
public static InstanceDataObject find(DataFolder folder,
                                      java.lang.String name,
                                      java.lang.String className)
```
    Finds instance of specified name in a given folder.
    
    Parameters:
    
    folder - the folder to create the instance data object in
    
    name - the name to give to the object (can be null if no special name besides the class name is needed)
    
    className - the name of the class the new object should provide an instance of
    
    Returns:
    
    the found instance data object or null if it does not exist
  - find
```
public static InstanceDataObject find(DataFolder folder,
                                      java.lang.String name,
                                      java.lang.Class<?> clazz)
```
    Finds instance of specified name in a given folder.
    
    Parameters:
    
    folder - the folder to create the instance data object in
    
    name - the name to give to the object (can be null if no special name besides the class name is needed)
    
    clazz - the class to create instance for (see class header for details)
    
    Returns:
    
    the found instance data object or null if it does not exist
  - create
```
public static InstanceDataObject create(DataFolder folder,
                                        java.lang.String name,
                                        java.lang.String className)
                                 throws java.io.IOException
```
    Create a new InstanceDataObject in a given folder. If object with specified name already exists, it is returned. You should specify the name if there is a chance another file of the same instance class already exists in the folder; or just to provide a more descriptive name, which will appear in the Explorer for example.
    Note: use of XML layers to install instances is generally preferred.
    
    Parameters:
    
    folder - the folder to create the instance data object in
    
    name - the name to give to the object (can be null if no special name besides the class name is needed) but name cannot be empty
    
    className - the name of the class the new object should provide an instance of (see class header for details)
    
    Returns:
    
    the newly created or existing instance data object
    
    Throws:
    
    java.io.IOException - if the file cannot be created
  - create
```
public static InstanceDataObject create(DataFolder folder,
                                        java.lang.String name,
                                        java.lang.Class<?> clazz)
                                 throws java.io.IOException
```
    Create a new InstanceDataObject in a given folder. If object with specified name already exists, it is returned. You should specify the name if there is a chance another file of the same instance class already exists in the folder; or just to provide a more descriptive name, which will appear in the Explorer for example.
    Note: use of XML layers to install instances is generally preferred.
    
    Parameters:
    
    folder - the folder to create the instance data object in
    
    name - the name to give to the object (can be null if no special name besides the class name is needed)
    
    clazz - the class to create instance for (see class header for details)
    
    Returns:
    
    the newly created or existing instance data object
    
    Throws:
    
    java.io.IOException - if the file cannot be created
  - create
```
public static InstanceDataObject create(DataFolder folder,
                                        java.lang.String name,
                                        java.lang.Object instance,
                                        org.openide.modules.ModuleInfo info)
                                 throws java.io.IOException
```
    Create a new InstanceDataObject containing settings in a given folder. If object with specified name already exists, it is returned. If the module info is null then the origin module info of an instance class is tried to find out.
    Note: use of XML layers to install instances is generally preferred.
    
    Parameters:
    
    folder - the folder to create the instance data object in
    
    name - the name to give to the object (can be null if no special name besides the class name is needed) but name cannot be empty
    
    instance - the serializable instance
    
    info - the module info describing the settings provenance (can be null)
    
    Returns:
    
    the newly created or existing instance data object
    
    Throws:
    
    java.io.IOException - if the file cannot be created
    
    Since:
    
    1.28
  - create
```
public static InstanceDataObject create(DataFolder folder,
                                        java.lang.String name,
                                        java.lang.Object instance,
                                        org.openide.modules.ModuleInfo info,
                                        boolean create)
                                 throws java.io.IOException
```
    Create a new InstanceDataObject containing settings in a given folder. If the module info is null then the origin module info of an instance class is tried to find out.
    Note: use of XML layers to install instances is generally preferred.
    
    Parameters:
    
    folder - the folder to create the instance data object in
    
    name - the name to give to the object (can be null if no special name besides the class name is needed) but name cannot be empty
    
    instance - the serializable instance
    
    info - the module info describing the settings provenance (can be null)
    
    create - true - always create new file; false - store to existing file if exist
    
    Returns:
    
    the newly created or existing instance data object
    
    Throws:
    
    java.io.IOException - if the file cannot be created
    
    Since:
    
    2.9
  - remove
```
public static boolean remove(DataFolder folder,
                             java.lang.String name,
                             java.lang.String className)
```
    Remove an existing instance data object. If you have the exact file name, just call DataObject.delete(); this method lets you delete an instance you do not have an exact record of the file name for, based on the same information used to create it.
    Note: use of XML layers to install instances is generally preferred.
    
    Parameters:
    
    folder - the folder to remove the file from
    
    name - the name of the instance (can be null)
    
    className - the name of class the object referred to (see class header for details)
    
    Returns:
    
    true if the instance was succesfully removed, false if not
  - remove
```
public static boolean remove(DataFolder folder,
                             java.lang.String name,
                             java.lang.Class<?> clazz)
```
    Remove an existing instance data object. If you have the exact file name, just call DataObject.delete(); this method lets you delete an instance you do not have an exact record of the file name for, based on the same information used to create it.
    Note: use of XML layers to install instances is generally preferred.
    
    Parameters:
    
    folder - the folder to remove the file from
    
    name - the name of the instance (can be null)
    
    clazz - the class the object referred to (see class header for details)
    
    Returns:
    
    true if the instance was succesfully removed, false if not
  - getHelpCtx
```
public org.openide.util.HelpCtx getHelpCtx()
```
    Description copied from class: DataObject
    
    Get help context for this object.
    
    Overrides:
    
    getHelpCtx in class MultiDataObject
    
    Returns:
    
    the help context
  - createNodeDelegate
```
protected org.openide.nodes.Node createNodeDelegate()
```
    Description copied from class: MultiDataObject
    
    Provides node that should represent this data object.
    
    Overrides:
    
    createNodeDelegate in class MultiDataObject
    
    Returns:
    
    the node representation
    
    See Also:
    
    DataNode
  - getCookie
```
public <T extends org.openide.nodes.Node.Cookie> T getCookie(java.lang.Class<T> clazz)
```
    Description copied from class: MultiDataObject
    
    Look for a cookie in the current cookie set matching the requested class.
    
    Overrides:
    
    getCookie in class MultiDataObject
    
    Parameters:
    
    clazz - the class to look for
    
    Returns:
    
    an instance of that class, or null if this class of cookie is not supported
  - getLookup
```
public org.openide.util.Lookup getLookup()
```
    Description copied from class: DataObject
    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.
    Overrides:
    
    getLookup in class MultiDataObject
    
    Returns:
    
    lookup representing this data object and its content
  - instanceName
```
public java.lang.String instanceName()
```
    Specified by:
    
    instanceName in interface org.openide.cookies.InstanceCookie
  - instanceClass
```
public java.lang.Class<?> instanceClass()
                                 throws java.io.IOException,
                                        java.lang.ClassNotFoundException
```
    Specified by:
    
    instanceClass in interface org.openide.cookies.InstanceCookie
    
    Throws:
    
    java.io.IOException
    
    java.lang.ClassNotFoundException
  - instanceOf
```
public boolean instanceOf(java.lang.Class<?> type)
```
    Query if this instance can create object of given type.
    
    Specified by:
    
    instanceOf in interface org.openide.cookies.InstanceCookie.Of
    
    Parameters:
    
    type - the type to create
    
    Returns:
    
    true or false
  - instanceCreate
```
public java.lang.Object instanceCreate()
                                throws java.io.IOException,
                                       java.lang.ClassNotFoundException
```
    Specified by:
    
    instanceCreate in interface org.openide.cookies.InstanceCookie
    
    Throws:
    
    java.io.IOException
    
    java.lang.ClassNotFoundException
  - getName
```
public java.lang.String getName()
```
    Description copied from class: DataObject
    
    Get the name of the data object.
    The default implementation uses the name of the primary file.
    
    Overrides:
    
    getName in class DataObject
    
    Returns:
    
    the name
  - handleRename
```
protected org.openide.filesystems.FileObject handleRename(java.lang.String name)
                                                   throws java.io.IOException
```
    Description copied from class: DataObject
    
    Rename this object (implemented in subclasses).
    
    Overrides:
    
    handleRename in class MultiDataObject
    
    Parameters:
    
    name - name to rename the object to
    
    Returns:
    
    new primary file of the object
    
    Throws:
    
    java.io.IOException - if an error occures
  - handleCreateFromTemplate
```
protected DataObject handleCreateFromTemplate(DataFolder df,
                                              java.lang.String name)
                                       throws java.io.IOException
```
    Description copied from class: DataObject
    
    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.
    
    Overrides:
    
    handleCreateFromTemplate in class MultiDataObject
    
    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:
    
    java.io.IOException - if an error occured
  - handleCopy
```
protected DataObject handleCopy(DataFolder df)
                         throws java.io.IOException
```
    Description copied from class: MultiDataObject
    
    Copies primary and secondary files to new folder. May ask for user confirmation before overwriting.
    
    Overrides:
    
    handleCopy in class MultiDataObject
    
    Parameters:
    
    df - the new folder
    
    Returns:
    
    data object for the new primary
    
    Throws:
    
    java.io.IOException - if there was a problem copying
    
    org.openide.util.UserCancelException - if the user cancelled the copy
  - dispose
```
protected void dispose()
```
    Description copied from class: DataObject
    
    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.
    
    Overrides:
    
    dispose in class DataObject
  - handleDelete
```
protected void handleDelete()
                     throws java.io.IOException
```
    Description copied from class: DataObject
    
    Delete this object (implemented by subclasses).
    
    Overrides:
    
    handleDelete in class MultiDataObject
    
    Throws:
    
    java.io.IOException - if an error occures

Class InstanceDataObject

Nested Class Summary

Nested classes/interfaces inherited from class org.openide.loaders.DataObject

Nested classes/interfaces inherited from interface org.openide.cookies.InstanceCookie

Nested classes/interfaces inherited from class org.openide.loaders.MultiDataObject

Field Summary

Fields inherited from class org.openide.loaders.DataObject

Constructor Summary

Method Summary

Methods inherited from class org.openide.loaders.DataObject

Methods inherited from class org.openide.loaders.MultiDataObject

Methods inherited from class java.lang.Object

Field Detail

INSTANCE

Constructor Detail

InstanceDataObject

Method Detail

find

find

create

create

create

create

remove

remove

getHelpCtx

createNodeDelegate

getCookie

getLookup

instanceName

instanceClass

instanceOf

instanceCreate

getName

handleRename

handleCreateFromTemplate

handleCopy

dispose

handleDelete