org.openide.loaders
Class FolderInstance

java.lang.Object
  |
  +--org.openide.util.Task
        |
        +--org.openide.loaders.FolderInstance

All Implemented Interfaces:

InstanceCookie, Node.Cookie, Runnable

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.

Inner classes inherited from class org.openide.cookies.InstanceCookie

InstanceCookie.Of, InstanceCookie.Origin

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.
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, toString

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

acceptDataObject

protected InstanceCookie acceptDataObject(DataObject dob)

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

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.

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.

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 should be ignored.

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.

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 cookie.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.

run

public void run()

Synchronously starts the creation of the instance.

Overrides:

run in class Task

postCreationTask

protected Task postCreationTask(Runnable run)

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

Default implementation uses request processor static private in this class.

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