org.openide.nodes 7.12.1

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

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.


Nested Class Summary
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.
 
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 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.
 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.
 
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

create

public static <T> Children create(ChildFactory<T> factory,
                                  boolean asynchronous)
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
Throws:
IllegalStateException - if the passed factory has already been used in a previous call to this method
Since:
org.openide.nodes 7.1

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

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

getNodeAt

public final Node getNodeAt(int index)
Getter for a child at a given position. If child with such index does not exists it returns null.

Parameters:
index - the index of a node we want to know (non negative)
Returns:
the node at given index or null
Since:
org.openide.nodes 7.5

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

getNodesCount

public int getNodesCount(boolean optimalResult)
Get the number of nodes in the list

Parameters:
optimalResult - whether to try to perform full initialization or to simply delegate to getNodesCount()
Returns:
the count
Since:
org.openide.nodes 7.6

snapshot

public final List<Node> 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 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.

See Also:
isInitialized()

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.


org.openide.nodes 7.12.1

Built on September 10 2010.  |  Portions Copyright 1997-2010 Sun Microsystems, Inc. All rights reserved.