org.openide.nodes 6.7.22

org.openide.nodes
Class Children

java.lang.Object
  extended by org.openide.nodes.Children
Direct Known Subclasses:
Children.Array, Children.Map

public abstract class Children
extends Object

Container for array of nodes. Can be associated with a node and then all children in the array have that node set as a parent, and this list will be returned as the node's children.

Probably you want to subclass Children.Keys. Subclassing Children directly is not recommended.


Nested Class Summary
static class Children.Array
          Implements the storage of node children by an array.
static class Children.Keys
          Implements an array of child nodes associated nonuniquely with keys and sorted by these keys.
static class Children.Map
          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
          Maintains a list of children sorted by the provided comparator in a map.
 
Field Summary
static Children LEAF
          The object representing an empty set of children.
static Mutex MUTEX
          Lock for access to hierarchy of all node lists.
 
Constructor Summary
Children()
          Constructor.
 
Method Summary
abstract  boolean add(Node[] nodes)
          Add nodes this container.
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.
 Node findChild(String name)
          Find a child node by name.
protected  Node getNode()
          Get the parent node of these children.
 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.
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 nodes()
          Get the nodes as an enumeration.
abstract  boolean remove(Node[] nodes)
          Remove nodes from the list.
protected  void removeNotify()
          Called when the list of nodes for this children object is no longer needed by the IDE.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MUTEX

public static final Mutex MUTEX
Lock for access to hierarchy of all node lists. Anyone who needs to ensure that there will not be shared accesses to hierarchy nodes can use this mutex.

All operations on the hierarchy of nodes (add, remove, etc.) are done in the Mutex.writeAccess(org.openide.util.Mutex.Action) 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).


LEAF

public static final Children LEAF
The object representing an empty set of children. Should be used to represent the children of leaf nodes. The same object may be used by all such nodes.

Constructor Detail

Children

public Children()
Constructor.

Method Detail

getNode

protected final Node getNode()
Get the parent node of these children.

Returns:
the node attached to this children object, or null if there is none yet

clone

protected Object clone()
                throws CloneNotSupportedException
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.

Overrides:
clone in class Object
Returns:
cloned version of this object, with the same class, uninitialized and without a parent node *exception CloneNotSupportedException if Cloneable interface is not implemented
Throws:
CloneNotSupportedException

add

public abstract boolean add(Node[] nodes)
Add nodes this container. 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.

Parameters:
nodes - set of nodes to add to the list
Returns:
true if successfully added

remove

public abstract boolean remove(Node[] nodes)
Remove nodes from the list. Only nodes that are present are removed.

Parameters:
nodes - nodes to be removed
Returns:
true if the nodes could be removed

nodes

public final Enumeration nodes()
Get the nodes as an enumeration.

Returns:
enumeration of Nodes

findChild

public Node findChild(String name)
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 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.

Returns:
true if children has been used before
See Also:
addNotify()

getNodes

public final Node[] getNodes()
Get a (sorted) array of nodes in this list. If the children object is not yet initialized, it will be (using addNotify()) before the nodes are returned.

Warning: not all children implementations do a complete calculation at this point, see getNodes(boolean)

Returns:
array of nodes

getNodes

public Node[] getNodes(boolean optimalResult)
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 getNodes()
Returns:
array of nodes
Since:
2.17

getNodesCount

public final int getNodesCount()
Get the number of nodes in the list.

Returns:
the count

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.

See Also:
isInitialized()

removeNotify

protected void removeNotify()
Called when the list of nodes for this children object is no longer needed by the IDE. Typical implementations at this time remove all children to save memory (or clear the keys for Children.Keys etc.).


org.openide.nodes 6.7.22

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