com.jivesoftware.community
Interface TreeWalker

public interface TreeWalker

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

See Also:

ForumThread

Method Summary

ForumMessage	getChild(ForumMessage parent, int index) Returns the child of parent at index index in the parent's child array.
int	getChildCount(ForumMessage parent) Returns the number of children of parent.
JiveIterator<ForumMessage>	getChildren(ForumMessage parent) Returns an Iterable for all the child messages of the parent.
int	getIndexOfChild(ForumMessage parent, ForumMessage child) Returns the index of child in parent.
int	getMessageDepth(ForumMessage message) Returns the depth of a message in the message tree hierarchy.
ForumMessage	getParent(ForumMessage child) Returns the parent of the child ForumMessage.
int	getRecursiveChildCount(ForumMessage parent) Returns the total number of recursive children of a parent.
JiveIterator<ForumMessage>	getRecursiveChildren(ForumMessage parent) Returns an Iterable for all child messages (and sub-children, etc) of the parent.
JiveIterator<ForumMessage>	getRecursiveMessages() Returns an Iterable for all messages in the thread in depth-first order.
ForumMessage	getRoot() Returns the root of the tree.
boolean	hasParent(ForumMessage child) Returns true if the child message has a parent message.
boolean	isLeaf(ForumMessage node) Returns true if node is a leaf.

Method Detail

getRoot

ForumMessage getRoot()

Returns the root of the tree. Returns null only if the tree has no nodes.

Returns:

the root of the tree

hasParent

boolean hasParent(ForumMessage child)

Returns true if the child message has a parent message.

Parameters:

child - the message.

Returns:

true if the message has a parent.

getParent

ForumMessage getParent(ForumMessage child)
                       throws ForumMessageNotFoundException

Returns the parent of the child ForumMessage.

Returns:

the parent message of child.

Throws:

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

getChild

ForumMessage getChild(ForumMessage parent,
                      int index)
                      throws ForumMessageNotFoundException

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, or if the child could not be loaded for any other reason, a ForumMessageNotFoundException will be thrown.

Parameters:

parent - the parent message.

index - the index of the child.

Returns:

the child of parent at index.

Throws:

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

getChildren

JiveIterator<ForumMessage> getChildren(ForumMessage parent)

Returns an Iterable for all the child messages of the parent. This method only considers direct descendants of the parent message and not sub-children. To get an iterable for the full hierarchy of children for a parent message, use the getRecursiveChildren(ForumMessage) method.

Parameters:

parent - the parent message.

Returns:

an Iterable for the children of parent.

getRecursiveMessages

JiveIterator<ForumMessage> getRecursiveMessages()

Returns an Iterable for all messages in the thread in depth-first order. For example, consider the following message tree:

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

Calling getRecursiveMessages() on the tree above would return the sequence 1, 3, 4, 7, 10, 6, 8, 5. This method is a powerful way to show the full tree of messages, especially in combination with the getMessageDepth(ForumMessage) method.

Returns:

an Iterable for all messages in the thread in depth-first order.

getRecursiveChildren

JiveIterator<ForumMessage> getRecursiveChildren(ForumMessage parent)

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

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

Calling getRecursiveChildren(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 message, especially in combination with the getMessageDepth(ForumMessage) method.

Parameters:

parent - the parent message.

Returns:

an Iterable for all the recursive children of the parent.

getMessageDepth

int getMessageDepth(ForumMessage message)

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

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

The depth of message 4 is 2, the depth of message 7 is 3, etc. This method is useful in combination with the getRecursiveChildren(ForumMessage) Iterable to build a UI of hierarchical messages.

Parameters:

message - the message to determine the depth of.

Returns:

the depth of the message in the message tree hiearchy.

getChildCount

int getChildCount(ForumMessage 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(ForumMessage 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 Thread but is included as an added utility.

Returns:

the recursive count of the children of parent.

getIndexOfChild

int getIndexOfChild(ForumMessage parent,
                    ForumMessage 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 message.

child - the child message to get the index for.

Returns:

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

isLeaf

boolean isLeaf(ForumMessage node)

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

Parameters:

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

Returns:

true if node is a leaf