com.jivesoftware.community
Interface CommentTreeWalker

public interface CommentTreeWalker

Allows hierarchical navigation of comments. It closely follows the TreeModel interface in Swing in the hopes of being easier to use.

See Also:

CommentManager

Method Summary

JiveIterator<Comment>	children(Comment parent) Returns an Iterable for all the child comments of the parent.
Comment	getChild(Comment parent, int index) Returns the child of parent at index index in the parent's child array.
int	getChildCount(Comment parent) Returns the number of children of parent.
int	getCommentDepth(Comment comment) Returns the depth of a comment in the comment tree hierarchy.
int	getIndexOfChild(Comment parent, Comment child) Returns the index of child in parent.
Comment	getParent(Comment child) Returns the parent of the child comment.
int	getRecursiveChildCount(Comment parent) Returns the total number of recursive children of a parent.
boolean	isLeaf(Comment node) Returns true if node is a leaf.
JiveIterator<Comment>	recursiveChildren(Comment parent) Returns an Iterable for all child comments (and sub-children, etc) of the parent.
JiveIterator<Comment>	topLevelComments() Returns an iterator of top level comments.

Method Detail

topLevelComments

JiveIterator<Comment> topLevelComments()

Returns an iterator of top level comments.

Returns:

an Iterable of top level comments.

getParent

Comment getParent(Comment child)
                  throws CommentNotFoundException

Returns the parent of the child comment. If the parent does not exist, this method will return null. If the parent does exist, but cannot be loaded, this method will throw a CommentNotFoundException

Parameters:

child - the child comment to return the parent for

Returns:

the parent comment of child.

Throws:

CommentNotFoundException - if child does not have a parent, or if the parent comment could not be loaded for any other reason.

getChild

Comment getChild(Comment parent,
                 int index)
                 throws CommentNotFoundException

Returns the child of parent at index index in the parent's child array. The index must be a valid one, that is: index >= 0, and index < getChildCount(parent). If the index is not valid, this method will return null, otherwise if the child could not be loaded for any other reason, a CommentNotFoundException will be thrown.

Parameters:

parent - the parent comment.

index - the index of the child.

Returns:

the child of parent at index.

Throws:

CommentNotFoundException - if the index was invalid or the child could not be loaded for any other reason.

children

JiveIterator<Comment> children(Comment parent)

Returns an Iterable for all the child comments of the parent. This method only considers direct descendants of the parent comment and not sub-children. To get an iterator for the full hierarchy of children for a parent comment, use the recursiveChildren(Comment) method.

Parameters:

parent - the parent comment.

Returns:

an Iterable for the children of parent.

recursiveChildren

JiveIterator<Comment> recursiveChildren(Comment parent)

Returns an Iterable for all child comments (and sub-children, etc) of the parent. Comments will be returned depth-first. For example, consider the following comment tree:

   1
   |-- 3
   |-- |-- 4
   |-- |-- |-- 7
   |-- |-- |-- |-- 10
   |-- |-- 6
   |-- |-- 8
   |-- 5
 

Calling recursiveChildren(3) on the tree above would return the sequence 4, 7, 10, 6, 8. This method is a powerful way to show all children of a comment, especially in combination with the getCommentDepth(Comment) method.

Parameters:

parent - the parent comment.

Returns:

an Iterable for all the recursive children of the parent.

getCommentDepth

int getCommentDepth(Comment comment)

Returns the depth of a comment in the comment tree hierarchy. The root comment is always at depth 0. For example, consider the following comment tree:

   1
   |-- 3
   |-- |-- 4
   |-- |-- |-- 7
 

The depth of comment 4 is 2, the depth of comment 7 is 3, etc. This method is useful in combination with the recursiveChildren(Comment) Iterable to build a UI of hierarchical comments.

Parameters:

comment - the comment to determine the depth of.

Returns:

the depth of the comment in the comment tree hiearchy.

getChildCount

int getChildCount(Comment parent)

Returns the number of children of parent. Returns 0 if the node is a leaf or if it has no children.

Parameters:

parent - a node in the tree, obtained from this data source.

Returns:

the number of children of the node parent.

getRecursiveChildCount

int getRecursiveChildCount(Comment parent)

Returns the total number of recursive children of a parent. Returns 0 if there are no children. This method is not intended to aid in navigation of a comment tree but is included as an added utility.

Parameters:

parent - the parent comment to return a recursive child count for

Returns:

the recursive count of the children of parent.

getIndexOfChild

int getIndexOfChild(Comment parent,
                    Comment child)

Returns the index of child in parent. This method does not deal with the indexes of sub-children of parents. For example, take the following tree:

   4
   |-- 2
   |-- |-- 1
   |-- |-- 6
   |-- |-- 8
   |-- 5
 

In this example, getIndexOfChild(4, 2) would return 0, getIndexOfChild(4, 5) would return 1, and getIndexOfChild(2, 8) would return 2. getIndexOfChild(4, 8) -- NOT VALID

Parameters:

parent - the parent comment.

child - the child comment to get the index for.

Returns:

the index of child in the list of siblings under parent.

isLeaf

boolean isLeaf(Comment node)

Returns true if node is a leaf. A node is a leaf when it has no children comments.

Parameters:

node - a node in the tree, obtained from this data source

Returns:

true if node is a leaf