Class ChildFactory<T>

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
createKeys(List <T>) 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
createNodesForKey(T),
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.

Constructor Detail

ChildFactory

Method Detail

createNodeForKey

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

Create Nodes for a given key object (one from the List
passed to createKeys(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

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

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().

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