org.apache.click.extras.tree
Class TreeNode

java.lang.Object
  extended by org.apache.click.extras.tree.TreeNode
All Implemented Interfaces:
Serializable

public class TreeNode
extends Object
implements Serializable

Provides an implementation of a Tree model.

TreeNode's are used to store hierarchical data representations for example directories, subdirectories and files.

Nodes must have a unique id. If nodes do not have a unique id, the tree might behave erratic.

Each node can store a user defined value of type Object.

Nodes contain a reference to their parent node as well as their children.

Two types of leaf nodes are supported by this implementation. A leaf node can either support the addition of new child nodes or not. An example of a leaf node where children are supported is a directory. A directory can be empty, meaning it is a leaf node, but files and subdirectories can be added as children. Another type of of leaf node does not support the addition of child nodes. A file would be an example of such a node. A file does not support the addition of new files or subdirectories as children. By default newly created nodes supports the addition of child nodes. Use the appropriate constructor to disable the support of child nodes, or call setChildrenSupported(boolean).

Note: Since each TreeNode must have a unique id within the tree, a default id is generated if one is not provided in the constructors. Id's are generated by an instance of Random. The current implementation generates a Long using random.nextLong(). This means a total of 2 64 numbers can be generated.

See Also:
Serialized Form

Constructor Summary
TreeNode()
          Creates a default node with no value or id.
TreeNode(Object value)
          Creates a node and sets the value to the specified argument.
TreeNode(Object value, String id)
          Creates a node and sets the value and id to the specified arguments.
TreeNode(Object value, String id, boolean childrenSupported)
          Creates a node and sets the value, id and childrenSupported to the specified arguments.
TreeNode(Object value, String id, TreeNode parent)
          Deprecated. use TreeNode(java.lang.Object, java.lang.String) instead and add to parent node through add(org.apache.click.extras.tree.TreeNode). Creates a node and sets the value, id and parent to the specified arguments.
TreeNode(Object value, String id, TreeNode parent, boolean childrenSupported)
          Deprecated. use TreeNode(java.lang.Object, java.lang.String, boolean) instead and add to parent node through add(org.apache.click.extras.tree.TreeNode). Creates a node and sets the value, id and parent to the specified arguments.
 
Method Summary
 void add(int index, TreeNode child)
          Adds the specified node at the specified index as a child of this node and sets the child's parent to this node.
 void add(TreeNode child)
          Adds the specified node as a child of this node and sets the child's parent to this node.
 void addChildOnly(int index, TreeNode child)
          Adds the specified node at the specified index as a child of this node but does NOT set the child's parent to this node.
 void addChildOnly(TreeNode child)
          Adds the specified node as a child of this node but does NOT set the child's parent to this node.
 void cacheTreeDepth(int depth)
          Stores the specified depth in a variable for fast retrieval.
 int calcTreeDepth()
          Calculate and return the depth of the tree where this node is set as the root of the calculation.
 int calcTreeDepth(boolean useCacheIfSet)
          Calculate and return the depth of the tree where this node is set as the root of the calculation.
 boolean equals(Object thatObject)
          Checks if this node's id is equals to the specified node's id.
 List<TreeNode> getChildren()
          Returns a unmodifiable list of this nodes children.
 String getIcon()
          Returns the TreeNode's custom icon.
 String getId()
          Returns this node's id value.
 int getLevel()
          Returns this node's level in the tree structure.
 TreeNode getParent()
          Returns this node's parent object or null if parent is not specified.
 Object getValue()
          Return this node's value.
 boolean hasChildren()
          Returns true if this node has any children nodes false otherwise.
 int hashCode()
          Returns the hashCode value for this node.
 boolean isChildrenSupported()
          Returns true if this node supports children, false otherwise.
 boolean isExpanded()
          Returns true if this node is currently in the expanded state, false otherwise.
 boolean isLastChild()
          Returns true if either this node is the last child of its parent, or this node is the root node.
 boolean isLeaf()
          Returns true if this node does not have any children, false otherwise.
 boolean isRoot()
          Returns true if this node is the root node.
 boolean isSelected()
          Returns true if this node is currently in the selected state, false otherwise.
 void remove(TreeNode child)
          Removes the specified node from the list of children and sets child's parent node to null.
 void setChildrenSupported(boolean childrenSupported)
          Sets whether this node supports child nodes or not.
 void setIcon(String icon)
          Set a custom icon for this TreeNode.
 void setId(String id)
          Set this node's new id value.
 void setParent(TreeNode parent)
          Sets this node's parent to the specified argument.
 void setValue(Object value)
          Set this node's value.
 String toString()
          Renders a string representation of this node.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TreeNode

public TreeNode()
Creates a default node with no value or id.

Note: a default random id is generated using a static instance of Random.


TreeNode

public TreeNode(Object value)
Creates a node and sets the value to the specified argument.

Note: a default random id is generated using a static instance of Random.

Parameters:
value - the nodes value

TreeNode

public TreeNode(Object value,
                String id)
Creates a node and sets the value and id to the specified arguments.

Parameters:
value - the nodes value
id - the nodes id

TreeNode

public TreeNode(Object value,
                String id,
                TreeNode parent)
Deprecated. use TreeNode(java.lang.Object, java.lang.String) instead and add to parent node through add(org.apache.click.extras.tree.TreeNode). Creates a node and sets the value, id and parent to the specified arguments.

Parameters:
value - the nodes value
id - the nodes id
parent - specifies the parent of this node

TreeNode

public TreeNode(Object value,
                String id,
                boolean childrenSupported)
Creates a node and sets the value, id and childrenSupported to the specified arguments.

Parameters:
value - the nodes value
id - the nodes id
childrenSupported - indicates if the treeNode supports child nodes or not.

TreeNode

public TreeNode(Object value,
                String id,
                TreeNode parent,
                boolean childrenSupported)
Deprecated. use TreeNode(java.lang.Object, java.lang.String, boolean) instead and add to parent node through add(org.apache.click.extras.tree.TreeNode). Creates a node and sets the value, id and parent to the specified arguments.

Parameters:
value - the nodes value
id - the nodes id
parent - specifies the parent of this node
childrenSupported - indicates if the treeNode supports child nodes or not.
Method Detail

getParent

public TreeNode getParent()
Returns this node's parent object or null if parent is not specified.

Returns:
TreeNode this node's parent or null if parent is not specified

setParent

public void setParent(TreeNode parent)
Sets this node's parent to the specified argument. This node is not added to the parent's children.

Parameters:
parent - this node's parent object

getValue

public Object getValue()
Return this node's value.

Returns:
this node's value

setValue

public void setValue(Object value)
Set this node's value.

Parameters:
value - the new value of this node

isLeaf

public boolean isLeaf()
Returns true if this node does not have any children, false otherwise.

Returns:
true if this node is a leaf node, false otherwise.

isChildrenSupported

public boolean isChildrenSupported()
Returns true if this node supports children, false otherwise.

Returns:
true if this node supports children, false otherwise.

setChildrenSupported

public void setChildrenSupported(boolean childrenSupported)
Sets whether this node supports child nodes or not. If set to false this method will remove all this node's children.

Parameters:
childrenSupported - whether this node supports children or not

getId

public String getId()
Returns this node's id value.

Returns:
this node's id value

setId

public void setId(String id)
Set this node's new id value.

Parameters:
id - this node's new id value

getChildren

public List<TreeNode> getChildren()
Returns a unmodifiable list of this nodes children.

Returns:
the unmodifiable list of children.

isSelected

public boolean isSelected()
Returns true if this node is currently in the selected state, false otherwise.

Returns:
true if this node is currently selected, false otherwise.

isExpanded

public boolean isExpanded()
Returns true if this node is currently in the expanded state, false otherwise.

Returns:
true if this node is currently expanded, false otherwise.

getIcon

public String getIcon()
Returns the TreeNode's custom icon.

Returns:
the TreeNode's custom icon
See Also:
setIcon(java.lang.String)

setIcon

public void setIcon(String icon)
Set a custom icon for this TreeNode.

The icon will be set as the src attribute of an HTML img element. Ensure the icon value specifies the full path to the actual icon resource.

For example:

 public TreeNode createNodes() {
     // Retrieve the web application context path
     String contextPath = getContext().getRequest().getContextPath();

     TreeNode book = new TreeNode("book");

     TreeNode chapter = new TreeNode("chapter", "1", book);

     // Specify the full path to the chapter.png icon
     chapter.setIcon(contextPath + "/assets/chapter.png");
     ...

     return book;
 } 

Parameters:
icon - the TreeNode icon

add

public void add(TreeNode child)
Adds the specified node as a child of this node and sets the child's parent to this node.

Parameters:
child - child node to add
Throws:
IllegalArgumentException - if the argument is null or if this node does not support child nodes

add

public void add(int index,
                TreeNode child)
Adds the specified node at the specified index as a child of this node and sets the child's parent to this node.

Parameters:
index - the index at which specified child must be added
child - child node to add
Throws:
IllegalArgumentException - if the argument is null or if this node does not support child nodes

addChildOnly

public void addChildOnly(TreeNode child)
Adds the specified node as a child of this node but does NOT set the child's parent to this node.

Parameters:
child - child node to add
Throws:
IllegalArgumentException - if the argument is null or if this node does not support child nodes

addChildOnly

public void addChildOnly(int index,
                         TreeNode child)
Adds the specified node at the specified index as a child of this node but does NOT set the child's parent to this node.

Parameters:
index - of the child node to add to
child - child node to add
Throws:
IllegalArgumentException - if the argument is null or if this node does not support child nodes

remove

public void remove(TreeNode child)
Removes the specified node from the list of children and sets child's parent node to null.

Parameters:
child - child node to remove from this nodes children
Throws:
IllegalArgumentException - if the argument is null

isRoot

public boolean isRoot()
Returns true if this node is the root node. The root is the node with a null parent.

Returns:
boolean true if this node is root, false otherwise

hasChildren

public boolean hasChildren()
Returns true if this node has any children nodes false otherwise.

Returns:
true if this node has any children false otherwise

isLastChild

public boolean isLastChild()
Returns true if either this node is the last child of its parent, or this node is the root node. Else it returns false.

Returns:
true if this node is the last child of its parent or the root node, false otherwise.

calcTreeDepth

public int calcTreeDepth()
Calculate and return the depth of the tree where this node is set as the root of the calculation.

This method guarantees to recalculate the depth of the tree and will not use the cached value if it was set using cacheTreeDepth(int).

Time complexity: This method performs in O(n) where n is the number of nodes in the tree. In other words no optimized algorithm is used by this method.

Returns:
depth of the tree
See Also:
cacheTreeDepth(int)

calcTreeDepth

public int calcTreeDepth(boolean useCacheIfSet)
Calculate and return the depth of the tree where this node is set as the root of the calculation.

If the argument useCacheIfSet is true, this method will return the cached value that was set by cacheTreeDepth(int). If useCacheIfSet is false this method will recalculate the depth of the tree.

Time complexity: This method performs in O(n) where n is the number of nodes in the tree. In other words no optimized algorithm is used by this method.

Parameters:
useCacheIfSet - if true use the cached value if it was set, else recalculate the depth
Returns:
depth of the tree
See Also:
cacheTreeDepth(int)

cacheTreeDepth

public void cacheTreeDepth(int depth)
Stores the specified depth in a variable for fast retrieval. The cached depth can be retrieved by calling calcTreeDepth(boolean) with 'true'.

Parameters:
depth - this node's depth to cache
See Also:
calcTreeDepth(boolean)

getLevel

public int getLevel()
Returns this node's level in the tree structure.

Returns:
int indicating this node's level

equals

public boolean equals(Object thatObject)
Checks if this node's id is equals to the specified node's id. Two tree node's are the same if they have the same id.

Overrides:
equals in class Object
Parameters:
thatObject - the specified object to check for equality
Returns:
true if this node's id is equal to the specified node's id
See Also:
Object.equals(Object)

hashCode

public int hashCode()
Returns the hashCode value for this node. The hashCode is calculated from the node's id.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.hashCode()

toString

public String toString()
Renders a string representation of this node.

Overrides:
toString in class Object
Returns:
string representation of this node