org.openide.nodes

Class ChildFactory<T>

java.lang.Object

org.openide.nodes.ChildFactory<T>

Type Parameters:

T - The type of objects in the keys collection

Direct Known Subclasses:

ChildFactory.Detachable

public abstract class ChildFactory<T>
extends Object

Factory used to create Children objects. Children objects supply child Nodes for a Node. Usage is to write a class that extends ChildFactory and pass that to Children.create(). When the Node is expanded or its children are programmatically requested, the ChildFactory.createKeys(java.util.List) method will be invoked to create the List of objects to be modelled as Nodes. Later, on demand, each object from the List will be passed in turn to ChildFactory.createNodesForKey(java.lang.Object), which may return an array of zero or more Nodes for the object.

A ChildFactory can be used either to create typical Children object, or one which will be initialized on a background thread (providing a "Please Wait" Node in the meantime). It can be used most simple cases that Children.Keys has been historically used for, and makes it easy to change a Children object to compute its keys asynchronously if that is needed for performance reasons.

Only one ChildFactory object may be used per Children object; if you wish to have multiple Nodes modelling children produced by a single ChildFactory, use @link FilterNode to wrap the Node that owns the Children object for this ChildFactory.

To use, simply override ChildFactory.createKeys(java.util.List) and ChildFactory.createNodesForKey(java.lang.Object) or ChildFactory.createNodeForKey(java.lang.Object).

Since:

org.openide.nodes 7.1

See Also:

Children.create(ChildFactory, boolean)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ChildFactory.Detachable<T> Subclass of ChildFactory with lifecycle methods which will be called on first use and last use.

Constructor Summary

Constructors

Constructor and Description
ChildFactory()

Method Summary

Modifier and Type	Method and Description
protected abstract boolean	createKeys(List<T> toPopulate) Create a list of keys which can be individually passed to createNodes() to create child Nodes.
protected Node	createNodeForKey(T key) Create a Node for a given key that was put into the list passed into createKeys().
protected Node[]	createNodesForKey(T key) Create Nodes for a given key object (one from the List passed to ChildFactory.createKeys(java.util.List)).
protected Node	createWaitNode() Create the Node that should be shown while the keys are being computed on a background thread.
protected void	refresh(boolean immediate) Call this method when the list of objects being modelled by the has changed and the child Nodes of this Node should be updated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ChildFactory

public ChildFactory()

Method Detail

createNodeForKey

protected Node createNodeForKey(T key)

Create a Node for a given key that was put into the list passed into createKeys(). Either override this method if there will always be 0 or 1 nodes per key, or createNodesForKey() if there may be more than one. The default implementation throws an AssertionError. If you override createNodesForKey() and do not call super, then you do not need to override this method; but at least one of the two must be overridden.

Parameters:

key - An object that was previously put into the list passed to createKeys()

Returns:

A node, or null if no node should be shown for this object.

createNodesForKey

protected Node[] createNodesForKey(T key)

Create Nodes for a given key object (one from the List passed to ChildFactory.createKeys(java.util.List)). The default implementation simply delegates to createNodeForKey and returns the result of that call in an array of nodes.

Most Children objects have a 1:1 mapping between keys and nodes. For convenience in that situation, simply override createNodeForKey(T).

Parameters:

key - An object from the list returned by asynchCreateKeys()

Returns:

null if no nodes, or zero or more Nodes to represent this key

createKeys

protected abstract boolean createKeys(List<T> toPopulate)

Create a list of keys which can be individually passed to createNodes() to create child Nodes. Implementations of this method should regularly check Thread.interrupted(), and if it returns true (meaning the parent Node was collapsed or destroyed), stop creating keys immediately and return true. This method is guaranteed not to be called on the AWT event thread if this ChildFactory was passed to Children.create() with the asynchronous parameter set to true. If not, then no guarantees are made as to what the calling thread is.

Returning false is tricky since there is no way to tell whether the loop has been restarted except by examining what is already in the list. As of 7.27 it is generally unnecessary since calls to List.add(Object) will immediately display the new element as well as checking for interruption.

Parameters:

toPopulate - A list to add key objects to

Returns:

true if the list of keys has been completely populated, false if the list has only been partially populated and this method should be called again to batch more keys

refresh

protected final void refresh(boolean immediate)

Call this method when the list of objects being modelled by the has changed and the child Nodes of this Node should be updated. The boolean argument is a hint to the refresh mechanism (which will cause createKeys() to be invoked again) that it is safe to synchronously recreate.

Parameters:

immediate - If true, the refresh should occur in the calling thread (be careful not to be holding any locks that might deadlock with your key/child creation methods if you pass true). Note that this parameter is only meaningful when using an asynchronous children instance (i.e. true was passed as the second parameter to Children.create()). If the Children object for this ChildFactory is called with immediate true on the AWT event dispatch thread, and it is an asynchronous Children object, this parameter will be ignored and computation will be scheduled on a background thread.

createWaitNode

protected Node createWaitNode()

Create the Node that should be shown while the keys are being computed on a background thread. This method will not be called if this ChildFactory is used for a synchronous children which does not compute its keys on a background thread. Whether an instance is synchronous or not is determined by a parameter to Children.create(ChildFactory, boolean).

To show no node at all when the Children object is initially expanded in the UI, simply return null.

The default implementation returns a Node that shows an hourglass cursor and the localized text "Please Wait...".

Returns:

A Node, or null if no wait node should be shown.