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 FolderInstance

    java.lang.Object
      org.openide.util.Task
          org.openide.loaders.FolderInstance

All Implemented Interfaces:
  Runnable, InstanceCookie, Node.Cookie

Direct Known Subclasses:
  FolderLookup

    public abstract class FolderInstance

extends Task
implements InstanceCookie

Support class for creation of an object from the content of a `DataObject.Container`. It implements `InstanceCookie`, so it can be used as a cookie for a node or data object.

When created on a container and started by invoking run method, it scans its content (in a separate thread) and creates a list of instances from which the new instance of this object should be composed. The object automatically listens to changes of components in the container, and if some change occurs, it allows the subclass to create a new object.

Subclasses shall override the following methods:

1. `createInstance(InstanceCookie[])` (required): this method is called whenever the content has been changed. Its implementation shall build up the data structures and perform the actions required by this implementation.
2. The filter methods `acceptDataObject(DataObject)`, `acceptCookie(InstanceCookie)`, `acceptFolder(DataFolder)` and `acceptContainer(DataObject.Container)` (optional): the standard way is to override one or several of the latter methods. Overriding `acceptDataObject(DataObject)` more deeply modifies the default behavior, because the default implementation of `acceptDataObject(DataObject)` calls the other 3 filter methods. See the method documentation for details.
3. The `InstanceCookie` methods `instanceClass()` (optional but recommended) to inform about the class implemented by the return value of `instanceCreate()`.
4. Advanced subclasses may need to override `postCreationTask(java.lang.Runnable)` and/or `instanceForCookie(org.openide.loaders.DataObject, org.openide.cookies.InstanceCookie)`, but it is not common to need these.

Nested Class Summary

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

Field Summary
`protected DataFolder` | `folder` Folder to work with.

Fields inherited from class org.openide.util.Task
`EMPTY`

Constructor Summary
`FolderInstance(DataFolder df)` Create new folder instance.
`FolderInstance(DataObject.Container container)` A new object that listens on changes in a container.

Method Summary
`protected InstanceCookie` | `acceptContainer(DataObject.Container container)` Allows subclasses to decide how they want to work with an object that implements a DataObject.Container.
`protected InstanceCookie` | `acceptCookie(InstanceCookie cookie)` Allows subclasses to decide whether they want to work with the specified `InstanceCookie` or not.
`protected InstanceCookie` | `acceptDataObject(DataObject dob)` Allows subclasses to decide whether they want to work with the specified `DataObject` or not.
`protected InstanceCookie` | `acceptFolder(DataFolder df)` Allows subclasses to decide how they want to work with a provided folder.
`protected abstract Object` | `createInstance(InstanceCookie[] cookies)` Notifies subclasses that the set of cookies for this folder has changed.
`Class` | `instanceClass()` Returns the root class of all objects.
`Object` | `instanceCreate()` Creates instance.
`void` | `instanceFinished()` Wait for instance initialization to finish.
`protected Object` | `instanceForCookie(DataObject obj, InstanceCookie cookie)` Method that is called when a the folder instance really wants to create an object from provided cookie.
`String` | `instanceName()` The name of the class that we create.
`protected Task` | `postCreationTask(Runnable run)` Invokes the creation of objects in a "safe" thread.
`void` | `recreate()` Starts recreation of the instance in special thread.
`void` | `run()` Synchronously starts the creation of the instance.
`String` | `toString()`
`void` | `waitFinished()` Overrides the instance finished to deal with internal state correctly.

Methods inherited from class org.openide.util.Task
`addTaskListener, isFinished, notifyFinished, notifyRunning, removeTaskListener, waitFinished`

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

Field Detail

### folder

    protected DataFolder folder

  Folder to work with. Non null only if a constructor with DataFolder is used to construct this object.

Constructor Detail

### FolderInstance

    public FolderInstance(DataFolder df)

  Create new folder instance.

  Parameters:
    `df` - data folder to create instances from

### FolderInstance

    public FolderInstance(DataObject.Container container)

  A new object that listens on changes in a container.

  Parameters:
    `container` - the object to associate with
  Since:
    1.11

Method Detail

### instanceName

    public String instanceName()

  The name of the class that we create.

  Specified by:
    `instanceName` in interface `InstanceCookie`
  Returns:
    the name

### instanceClass

    public Class instanceClass()
                        throws IOException,
                               ClassNotFoundException

  Returns the root class of all objects. Supposed to be overriden in subclasses.

  Specified by:
    `instanceClass` in interface `InstanceCookie`
  Returns:
    Object.class
  Throws:
    `IOException` - an I/O error occured
    `ClassNotFoundException` - the class has not been found

### instanceCreate

    public Object instanceCreate()
                          throws IOException,
                                 ClassNotFoundException

  Creates instance.

  Specified by:
    `instanceCreate` in interface `InstanceCookie`
  Returns:
    an object to work with
  Throws:
    `IOException` - an I/O error occured
    `ClassNotFoundException` - the class has not been found

### instanceFinished

    public final void instanceFinished()

  Wait for instance initialization to finish.

### waitFinished

    public void waitFinished()

  Overrides the instance finished to deal with internal state correctly.

  Overrides:
    `waitFinished` in class `Task`

### run

    public void run()

  Synchronously starts the creation of the instance.

  Specified by:
    `run` in interface `Runnable`
  Overrides:
    `run` in class `Task`

### acceptDataObject

    protected InstanceCookie acceptDataObject(DataObject dob)

  Allows subclasses to decide whether they want to work with the specified `DataObject` or not.

  The default implementation roughly performs the following steps:

  1. if `dob` has an `InstanceCookie` `acceptCookie(InstanceCookie)` is called on that cookie
  2. if `dob` has a `DataFolder` cookie, `acceptFolder(DataFolder)` is called on that folder
  3. if `dob` has a `DataObject.Container` cookie, `acceptContainer(DataObject.Container)` is called on that container

  The first of the aforementioned steps which returns a non-`null` cookie and does not throw an exception determines the return value. If none of the steps succeeds, `null` is returned.

  Parameters:
    `dob` - a `DataObject` to test
  Returns:
    the cookie for the `DataObject` or `null` if it should not be used

### acceptCookie

    protected InstanceCookie acceptCookie(InstanceCookie cookie)
                                   throws IOException,
                                          ClassNotFoundException

  Allows subclasses to decide whether they want to work with the specified `InstanceCookie` or not.

  The default implementation simply returns the same cookie, but subclasses may decide to return `null` or a different cookie.

  Compare `acceptDataObject(DataObject)` to learn when this method is called.

  Parameters:
    `cookie` - the instance cookie to test
  Returns:
    the cookie to use or `null` if this cookie should not be used
  Throws:
    `IOException` - if an I/O error occurred calling a cookie method
    `ClassNotFoundException` - if a class is not found in a call to a cookie method

### acceptFolder

    protected InstanceCookie acceptFolder(DataFolder df)

  Allows subclasses to decide how they want to work with a provided folder.

  The default implementation simply calls `acceptContainer(DataObject.Container)`.

  A common override of this method is to return a new `FolderInstance` based on the subfolder, permitting recursion.

  Compare `acceptDataObject(DataObject)` to learn when this method is called.

  Parameters:
    `df` - data folder to create cookie for
  Returns:
    the cookie for this folder or `null` if this folder should not be used

### acceptContainer

    protected InstanceCookie acceptContainer(DataObject.Container container)

  Allows subclasses to decide how they want to work with an object that implements a DataObject.Container.

  By default this returns `null` to indicated that subfolders (as well as `DataShadow`s, etc.) should be ignored.

  A common override of this method is to return a new `FolderInstance` based on the subfolder, permitting recursion.

  Compare `acceptDataObject(DataObject)` to learn when this method is called.

  Parameters:
    `container` - the container to accept or not
  Returns:
    cookie for this container or `null` if this object should be ignored
  Since:
    1.11

### createInstance

    protected abstract Object createInstance(InstanceCookie[] cookies)
                                      throws IOException,
                                             ClassNotFoundException

  Notifies subclasses that the set of cookies for this folder has changed. A new object representing the folder should be created (or the old one updated). Called both upon initialization of the class, and change of its cookies.

  It may be poor style for this method to have side-effects. A common way to use `FolderInstance` is to have this method set some global state which is then used as the resulting instance. Better is to treat the `FolderInstance` as pure SPI and assign it to a variable of type `InstanceCookie`. Then use the `instanceCreate()` method to get the final result. However in some cases there is a singleton live object which must be updated in-place, and it only makes sense to do so here (in which case the `InstanceCookie` methods are unused).

  Parameters:
    `cookies` - updated array of instance cookies for the folder
  Returns:
    object to represent these cookies
  Throws:
    `IOException` - an I/O error occured
    `ClassNotFoundException` - a class has not been found

### instanceForCookie

    protected Object instanceForCookie(DataObject obj,
                                       InstanceCookie cookie)
                                throws IOException,
                                       ClassNotFoundException

  Method that is called when a the folder instance really wants to create an object from provided cookie. It allows subclasses to overwrite the default behaviour (which is to call `InstanceCookie.instanceCreate()`).

  Parameters:
    `obj` - the data object that is the source of the cookie
    `cookie` - the instance cookie to read the instance from
  Throws:
    `IOException` - when there I/O error
    `ClassNotFoundException` - if the class cannot be found

### recreate

    public void recreate()

  Starts recreation of the instance in special thread.

### postCreationTask

    protected Task postCreationTask(Runnable run)

  Invokes the creation of objects in a "safe" thread. This method is for expert subclasses that want to control the thread that the instance is created in.

  The default implementation invokes the creation logic in the request processor in non-blocking mode (no other tasks will block on this).

  Parameters:
    `run` - runnable to run
  Returns:
    task to control the execution of the runnable or null if the runnable is run immediatelly
  Since:
    1.5

### toString

    public String toString()

  Overrides:
    `toString` in class `Task`

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.