Class Children

Factory for the child Nodes of a Node. Every Node has a Children object.
Children are initially un-initialized, and child Nodes are created on
demand when, for example, the Node is expanded in an Explorer view.
If you know your Node has no child nodes, pass Children.LEAF.
Typically a Children object will create a Collection of objects from
some data model, and create one or more Nodes for each object on demand.
If initializing the list of children of a Node is time-consuming (i.e. it
does I/O, parses a file or some other expensive operation), implement
ChildFactory and pass it to Children.create (theFactory, true) to have
the child nodes be computed asynchronously on a background thread.

In almost all cases you want to subclass ChildFactory and pass it to
Children.create(), or subclass Children.Keys.
Subclassing Children directly is not recommended.

Constructor Detail

Children

Method Detail

create

Create a Children object using the passed ChildFactory
object. The ChildFactory will be asked to create a list
of model objects that are the children; then for each object in the list,
ChildFactory.createNodesForKey(T) will be called to instantiate
one or more Nodes for that object.

Parameters:

factory - a factory which will provide child objects

asynchronous - If true, the factory will always be called to
create the list of keys on
a background thread, displaying a "Please Wait" child node until
some or all child nodes have been computed. If so,
when it is expanded, the node that owns
the returned Children object will display a "Please Wait"
node while the children are computed in the background. Pass true
for any case where computing child nodes is expensive and should
not be done in the event thread.

Returns:

a children object which
will invoke the factory instance as needed to supply model
objects and child nodes for it

clone

Handles cloning in the right way, that can be later extended by
subclasses. Of course each subclass that wishes to support cloning
must implement the Cloneable interface, otherwise this method throws
CloneNotSupportedException.

add

Add nodes to this container but do not call this method.
If you think you need to do this probably you really wanted to use
Children.Keys.setKeys(java.util.Collection<? extends T>) instead.
The parent node of these nodes
is changed to the parent node of this list. Each node can be added
only once. If there is some reason a node cannot be added, for example
if the node expects only a special type of subnodes, the method should
do nothing and return false to signal that the addition has not been successful.

This method should be implemented by subclasses to filter some nodes, etc.

nodes

findChild

Find a child node by name.
This may be overridden in subclasses to provide a more advanced way of finding the
child, but the default implementation simply scans through the list of nodes
to find the first one with the requested name.

Normally the list of nodes should have been computed by the time this returns,
but see Children.getNodes() for an important caveat as to why this may not
be doing what you want and what to do instead.

Parameters:

name - (code) name of child node to find or null if any arbitrary child may
be returned

Returns:

the node or null if it could not be found

isInitialized

protected final boolean isInitialized()

Method that can be used to test whether the children content has
ever been used or it is still not initalized.

getNodes

Get a (sorted) array of nodes in this list.
This method is usefull if you need a fully initialized array of nodes
for things like MenuView, node navigation from scripts/tests and so on.
But in general if you are trying to get useful data by calling
this method, you are probably doing something wrong.
Usually you should be asking some underlying model
for information, not the nodes for children. For example,
DataFolder.getChildren()
is a much more appropriate way to get what you want for the case of folder children.
If you're extending children, you should make sure this method
will return a complete list of nodes. The default implementation will do
this correctly so long as your subclass implement findChild(null)
to initialize all subnodes.

Note:You should not call this method from inside
Children.MUTEX.readAccess().
If you do so, the Node will be unable to update its state
before you leave the readAccess().

Parameters:

optimalResult - whether to try to get a fully initialized array
or to simply delegate to Children.getNodes()

snapshot

Creates an immutable snapshot representing the current view of the nodes
in this children object. This is No attempt is made to extract incorrect or invalid
nodes from the list, as a result, the value may not be exactly the same
as returned by Children.getNodes().

Returns:

immutable and unmodifiable list of nodes in this children object

Since:

7.7

addNotify

protected void addNotify()

Called when children are first asked for nodes.
Typical implementations at this time calculate
their node list (or keys for Children.Keys etc.).
Notice: call to getNodes() inside of this method will return
an empty array of nodes.

removeNotify

protected void removeNotify()

Called when all the children Nodes are freed from memory.
Typical implementations at this time clear all the keys
(in case of Children.Keys) etc.
Note that this is usually not the best place for unregistering
listeners, etc., as listeners usually keep the child nodes
in memory, preventing them from being collected, thus preventing
this method to be called in the first place.