public abstract class Children extends Object
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.
| Modifier and Type | Class and Description |
|---|---|
static class |
Children.Array
Implements the storage of node children by an array.
|
static class |
Children.Keys<T>
Implements an array of child nodes associated nonuniquely with keys and sorted by these keys.
|
static class |
Children.Map<T>
Implements the storage of node children by a map.
|
static class |
Children.SortedArray
Maintains a list of children sorted by the provided comparator in an array.
|
static class |
Children.SortedMap<T>
Maintains a list of children sorted by the provided comparator in a map.
|
| Modifier and Type | Field and Description |
|---|---|
static Children |
LEAF
The object representing an empty set of children.
|
static Mutex |
MUTEX
Lock for access to hierarchy of all node lists.
|
| Constructor and Description |
|---|
Children()
Constructor.
|
| Modifier and Type | Method and Description |
|---|---|
abstract boolean |
add(Node[] nodes)
Add nodes to this container but do not call this method.
|
protected void |
addNotify()
Called when children are first asked for nodes.
|
protected Object |
clone()
Handles cloning in the right way, that can be later extended by
subclasses.
|
static <T> Children |
create(ChildFactory<T> factory,
boolean asynchronous)
Create a
Children object using the passed ChildFactory
object. |
static Children |
createLazy(Callable<Children> factory)
Create a lazy children implementation.
|
Node |
findChild(String name)
Find a child node by name.
|
protected Node |
getNode()
Get the parent node of these children.
|
Node |
getNodeAt(int index)
Getter for a child at a given position.
|
Node[] |
getNodes()
Get a (sorted) array of nodes in this list.
|
Node[] |
getNodes(boolean optimalResult)
Get a (sorted) array of nodes in this list.
|
int |
getNodesCount()
Get the number of nodes in the list.
|
int |
getNodesCount(boolean optimalResult)
Get the number of nodes in the list
|
protected boolean |
isInitialized()
Method that can be used to test whether the children content has
ever been used or it is still not initalized.
|
Enumeration<Node> |
nodes()
Get the nodes as an enumeration.
|
abstract boolean |
remove(Node[] nodes)
Remove nodes from the list.
|
protected void |
removeNotify()
Called when all the children Nodes are freed from memory.
|
List<Node> |
snapshot()
Creates an immutable snapshot representing the current view of the nodes
in this children object.
|
public static final Mutex MUTEX
All operations on the hierarchy of nodes (add, remove, etc.) are
done in the Mutex.writeAccess(org.openide.util.Mutex.Action<T>) method of this lock, so if someone
needs for a certain amount of time to forbid modification,
he can execute his code in Mutex.readAccess(org.openide.util.Mutex.Action<T>).
public static final Children LEAF
public static <T> Children create(ChildFactory<T> factory, boolean asynchronous)
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.factory - a factory which will provide child objectsasynchronous - 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.IllegalStateException - if the passed factory has already
been used in a previous call to this methodpublic static Children createLazy(Callable<Children> factory)
factory - The Callable whose call() method
is called just when node's children are really needed.Node constructor and thus allows the client code to decide
what children the node should have when Callable.call() is called.protected final Node getNode()
null if there is none yetprotected Object clone() throws CloneNotSupportedException
Cloneable interface, otherwise this method throws
CloneNotSupportedException.clone in class ObjectCloneable interface is not implementedCloneNotSupportedExceptionpublic abstract boolean add(Node[] nodes)
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 - set of nodes to add to the listtrue if successfully addedpublic abstract boolean remove(Node[] nodes)
nodes - nodes to be removedtrue if the nodes could be removedpublic final Enumeration<Node> nodes()
public Node findChild(String 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.
name - (code) name of child node to find or null if any arbitrary child may
be returnednull if it could not be foundprotected final boolean isInitialized()
Children.addNotify()public final Node getNodeAt(int index)
index - the index of a node we want to know (non negative)public final Node[] getNodes()
Children.addNotify()) before
the nodes are returned.
Warning: not all children
implementations do a complete calculation at
this point, see Children.getNodes(boolean)
public Node[] getNodes(boolean optimalResult)
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()Node will be unable to update its state
before you leave the readAccess().
optimalResult - whether to try to get a fully initialized array
or to simply delegate to Children.getNodes()public final int getNodesCount()
public int getNodesCount(boolean optimalResult)
optimalResult - whether to try to perform full initialization
or to simply delegate to Children.getNodesCount()public final List<Node> snapshot()
Children.getNodes().protected void addNotify()
Children.Keys etc.).Children.isInitialized()protected void removeNotify()
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.