Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.loaders 5.9.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.openide.loaders
Class InstanceDataObject

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

All Implemented Interfaces:
  Serializable, InstanceCookie, InstanceCookie.Of, Node.Cookie, HelpCtx.Provider

    public class InstanceDataObject

extends MultiDataObject
implements 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.MultiDataObject
`MultiDataObject.Entry`

Nested classes/interfaces inherited from class org.openide.loaders.DataObject
`DataObject.Container, DataObject.Registry`

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

Field Summary
`static 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`

Constructor Summary
`InstanceDataObject(FileObject pf, MultiFileLoader loader)` Create a new instance.

Method Summary
`static InstanceDataObject` | `create(DataFolder folder, String name, Class clazz)` Create a new `InstanceDataObject` in a given folder.
`static InstanceDataObject` | `create(DataFolder folder, String name, Object instance, ModuleInfo info)` Create a new `InstanceDataObject` containing settings in a given folder.
`static InstanceDataObject` | `create(DataFolder folder, String name, Object instance, ModuleInfo info, boolean create)` Create a new `InstanceDataObject` containing settings in a given folder.
`static InstanceDataObject` | `create(DataFolder folder, String name, String className)` Create a new `InstanceDataObject` in a given folder.
`protected Node` | `createNodeDelegate()` Provides node that should represent this data object.
`protected void` | `dispose()` Allows subclasses to discard the object.
`static InstanceDataObject` | `find(DataFolder folder, String name, Class clazz)` Finds instance of specified name in a given folder.
`static InstanceDataObject` | `find(DataFolder folder, String name, String className)` Finds instance of specified name in a given folder.
`Node.Cookie` | `getCookie(Class clazz)` Look for a cookie in the current cookie set matching the requested class.
`HelpCtx` | `getHelpCtx()` Get help context for this object.
`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, String name)` Create a new data object from template (implemented in subclasses).
`protected void` | `handleDelete()` Delete this object (implemented by subclasses).
`protected FileObject` | `handleRename(String name)` Rename this object (implemented in subclasses).
`Class` | `instanceClass()`
`Object` | `instanceCreate()`
`String` | `instanceName()`
`boolean` | `instanceOf(Class type)` Query if this instance can create object of given type.
`static boolean` | `remove(DataFolder folder, String name, Class clazz)` Remove an existing instance data object.
`static boolean` | `remove(DataFolder folder, String name, String className)` Remove an existing instance data object.

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

Methods inherited from class org.openide.loaders.DataObject
`addPropertyChangeListener, addVetoableChangeListener, copy, 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 java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### INSTANCE

    public static final String INSTANCE

  File extension for instance data objects.

  See Also:
    Constant Field Values

Constructor Detail

### InstanceDataObject

    public InstanceDataObject(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,
                                          String name,
                                          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,
                                          String name,
                                          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,
                                            String name,
                                            String className)
                                     throws 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:
    `IOException` - if the file cannot be created

### create

    public static InstanceDataObject create(DataFolder folder,
                                            String name,
                                            Class clazz)
                                     throws 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:
    `IOException` - if the file cannot be created

### create

    public static InstanceDataObject create(DataFolder folder,
                                            String name,
                                            Object instance,
                                            ModuleInfo info)
                                     throws 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:
    `IOException` - if the file cannot be created
  Since:
    1.28

### create

    public static InstanceDataObject create(DataFolder folder,
                                            String name,
                                            Object instance,
                                            ModuleInfo info,
                                            boolean create)
                                     throws 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:
    `IOException` - if the file cannot be created
  Since:
    2.9

### remove

    public static boolean remove(DataFolder folder,
                                 String name,
                                 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,
                                 String name,
                                 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 HelpCtx getHelpCtx()

  Description copied from class: `DataObject`
  Get help context for this object.

  Specified by:
    `getHelpCtx` in interface `HelpCtx.Provider`
  Overrides:
    `getHelpCtx` in class `MultiDataObject`
  Returns:
    the help context

### createNodeDelegate

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

### instanceName

    public String instanceName()

  Specified by:
    `instanceName` in interface `InstanceCookie`

### instanceClass

    public Class instanceClass()
                        throws IOException,
                               ClassNotFoundException

  Specified by:
    `instanceClass` in interface `InstanceCookie`
  Throws:
    `IOException`
    `ClassNotFoundException`

### instanceOf

    public boolean instanceOf(Class type)

  Query if this instance can create object of given type.

  Specified by:
    `instanceOf` in interface `InstanceCookie.Of`
  Parameters:
    `type` - the type to create
  Returns:
    true or false

### instanceCreate

    public Object instanceCreate()
                          throws IOException,
                                 ClassNotFoundException

  Specified by:
    `instanceCreate` in interface `InstanceCookie`
  Throws:
    `IOException`
    `ClassNotFoundException`

### getName

    public 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 FileObject handleRename(String name)
                               throws 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:
    `IOException` - if an error occures

### handleCreateFromTemplate

    protected DataObject handleCreateFromTemplate(DataFolder df,
                                                  String name)
                                           throws 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:
    `IOException` - if an error occured

### handleCopy

    protected DataObject handleCopy(DataFolder df)
                             throws 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:
    `IOException` - if there was a problem copying

### 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 IOException

  Description copied from class: `DataObject`
  Delete this object (implemented by subclasses).

  Overrides:
    `handleDelete` in class `MultiDataObject`
  Throws:
    `IOException` - if an error occures

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.loaders 5.9.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.