org.openide.loaders 5.9.22

org.openide.loaders
Class FolderInstance

java.lang.Object
  extended by org.openide.util.Task
      extended by 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 DataShadows, 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

org.openide.loaders 5.9.22

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