info.monitorenter.cpdetector.util.collections
Interface ITreeNode

All Known Implementing Classes:

ITreeNode.DefaultTreeNode, TreeNodeUniqueChildren

public interface ITreeNode

Basic interface for a tree node. It is an approach at node-level instead of a procedural interface from outside. Working with a tree from outside very often is not as fast and incurs additional memory constumption for saving states and partial results (no recursion may keep traversal-related data on the heap, but the current positions for step-operations has to saved). Supporting an "outside-interface" for a tree is recommended by using a visitor pattern but may also be done in a classical way.

Every node of the tree may carry a so-called "user-Object". While the structure of the tree models the relation of these objects, they themselve contain the data needed.

Author:

Achim Westermann

Nested Class Summary

static class

ITreeNode.DefaultTreeNode Plain-forward implementation of the ITreeNodeinterface.

Field Summary

static ITreeNode

ROOT Returned from getParent() of the root node of the tree.

Method Summary

ITreeNode	addChild(Object userObject) Comfortable method for adding child nodes.
boolean	addChildNode(ITreeNode node) Adds the given ITreeNode to the set of this instances childs.
boolean	addChildNodes(ITreeNode[] nodes) Adds all given ITreeNode instances to the set of this instances childs.
ITreeNode[]	addChildren(Object[] userObjects) Adds all given Objects to newly instanciated ITreeNode instances that are added to the set of this instances childs.
boolean	contains(Object userObject) Find out, wether a certain "user" Object is carried by any of this ITreeNodes subtree.
boolean	containsNode(ITreeNode node) Find out, wether the given ITreeNode is a member of this node's subtree.
boolean	equals(Object o) Convenience method recommended for usage by implemenations.
List	getAllChildren() Get all child nodes of the ITreeNode.
int	getChildCount() Returns the amount of child ITreeNodes of this ITreeNode.
Iterator	getChilds() The Iteratorreturned will not traverse the whole subtree but only the direct child nodes of this ITreeNode.
ITreeNode	getParent() Get the parent node of this ITreeNode.
void	getPathFromRoot(List l)
int	getSubtreeCount() Get the amount of direct and indirect childs of this ITreeNode.
Object	getUserObject() Returns the "user" Object that may be carried by the ITreeNode, or null, if no one was assigned.
void	getUserObjectPathFromRoot(List l)
boolean	isLeaf() Find out, wether this ITreeNode is a childless leaf.
boolean	isMarked() Check, wether this ITreeNode is marked.
boolean	isRoot() Find out, wether there is no path to a higher parental node from this ITreeNode.
void	mark() Marks this ITreeNode instance (e.g.
ITreeNode	newInstance() Generic operations in default implementations may need to allocate new instances but have to choose the right type to support the provided invariants.
ITreeNode	remove(Object userObject) Remove the ITreeNode and it's whole subree! in this node's subtree, that contains a user Object equal to the given argument.
List	removeAllChildren() Remove all child nodes of the ITreeNode.
boolean	removeChild(ITreeNode node) Remove the given ITreeNode from this node.
void	setParent(ITreeNode parent) This method should not be called from outside.
Object	setUserObject(Object store) Assigns the "user" Object that may be carried by the ITreeNode.
void	unmark() Unmarks this ITreeNode instance (e.g.

Field Detail

ROOT

static final ITreeNode ROOT

Returned from getParent() of the root node of the tree.

Method Detail

getUserObject

Object getUserObject()

Returns the "user" Object that may be carried by the ITreeNode, or null, if no one was assigned.

Returns:

The user Object carried by this treenode or null, if no one was assigned.

setUserObject

Object setUserObject(Object store)

Assigns the "user" Object that may be carried by the ITreeNode.

Returns:

The previous user Object that was carried or null, if no one was assigned.

mark

void mark()

Marks this ITreeNode instance (e.g. for being visited or invisible). Marking may be used to traverse the tree in an asynchronous manner from outside (TreeIterator) or for other desireable tasks.

Subsequent calls to this method should not change the state to "unmarked".

unmark

void unmark()

Unmarks this ITreeNode instance (e.g. for being visited or invisible). Marking may be used to traverse the tree in an asynchronous manner from outside (TreeIterator) or for other desireable tasks.

Subsequent calls to this method should not change the state to "marked".

isMarked

boolean isMarked()

Check, wether this ITreeNode is marked.

Returns:

True, if this ITreeNode is marked, false else.

getChildCount

int getChildCount()

Returns the amount of child ITreeNodes of this ITreeNode.

getSubtreeCount

int getSubtreeCount()

Get the amount of direct and indirect childs of this ITreeNode.

Returns:

The total amount of all ITreeNode instances of this subtree (including this node).

getChilds

Iterator getChilds()

The Iteratorreturned will not traverse the whole subtree but only the direct child nodes of this ITreeNode.

Returns:

An Iteratorover the direct childs of this ITreeNode.

getParent

ITreeNode getParent()

Get the parent node of this ITreeNode. If the TreeNode has no parent node (e.g. a member of an implementation for the parent node is null), ROOThas to be returned.

Returns:

The parent ITreeNode of this node or ROOT, if this node is the root.

setParent

void setParent(ITreeNode parent)

This method should not be called from outside. It is a callback for the method addChildNode(ITreeNode)and should be used by implementations of that method but not any further. Else inconsistencies could occur: A node thinks it is the father of another node which itself does not know about that relation any more (remove itself from the old parent member's list could avoid it).

Parameters:

parent - The new parental node.

addChildNode

boolean addChildNode(ITreeNode node)

Adds the given ITreeNode to the set of this instances childs. Note, that the given node has to get to know, that it has a new parent (implementation detail).

Parameters:

node - The new child ITreeNode whose parent this instance will become.

Returns:

True, if the operation was succesful: For example some implementations (e.g. with support for unique user Objects in childs on the same level with the same parent node) may dissallow duplicate child nodes.

addChildNodes

boolean addChildNodes(ITreeNode[] nodes)

Adds all given ITreeNode instances to the set of this instances childs. This operation should delegate to addChildNode(ITreeNode).

Parameters:

nodes - An arry of ITreeNode instances.

Returns:

True, if all childs could be added (null instances are skipped), false else.

addChild

ITreeNode addChild(Object userObject)

Comfortable method for adding child nodes. Could be expressed as:

 ...
 ITreeNode ret = new <TreeNodeImpl>(m_userObject);
 if(this.addChildNode(ret){
   return ret;
 }
 else{
   return null;
 }
 ...
 

Parameters:

userObject - The Object that should be carried by the new ITreeNode or null, if no one is desired.

Returns:

The newly allocated ITreeNode or null, if the operation failed .

addChildren

ITreeNode[] addChildren(Object[] userObjects)

Adds all given Objects to newly instanciated ITreeNode instances that are added to the set of this instances childs. This operation should delegate to addChild(Object).

Parameters:

userObjects - An arry of Objects instances which will become the m_userObject members of the newly created ITreeNode instances.

Returns:

An array containing all new ITreeNode instances created (they contain the user objects).

removeChild

boolean removeChild(ITreeNode node)

Remove the given ITreeNode from this node. If the operation is successful the given node will not have any parent node (e.g. null for parent member) but be the root node of it's subtree.

The operation may fail, if the given ITreeNode is no child of this node, or the implementation permits the removal.

Parameters:

node - A child of this ITreeNode (by the means of the equals(Object)operation) .

Returns:

True, if the removal was successful, false if not.

remove

ITreeNode remove(Object userObject)

Remove the ITreeNode and it's whole subree! in this node's subtree, that contains a user Object equal to the given argument. The search is performed in a recursive manner quitting when the first removal could be performed.

Parameters:

userObject - The user Object identifying the treenode to remove.

Returns:

The TreeNode (being the new root of it's subtree) that was removed from this node's subtree or null, if no ITreeNode contained an equal user Object.

removeAllChildren

List removeAllChildren()

Remove all child nodes of the ITreeNode.

Returns:

A Listcontaining all removed child nodes. An empty List should be provided instead of null!

getAllChildren

List getAllChildren()

Get all child nodes of the ITreeNode.

Returns:

A Listcontaining all child nodes. An empty List should be provided instead of null!

contains

boolean contains(Object userObject)

Find out, wether a certain "user" Object is carried by any of this ITreeNodes subtree.

Parameters:

userObject - Any Object, that might be contained in this tree - Identification is done by the means of the Objects Object.equals(Object)- method.

Returns:

True, if any node of this subtree (including this ITreeNode contained a user Object that was equal to the given argument.

containsNode

boolean containsNode(ITreeNode node)

Find out, wether the given ITreeNode is a member of this node's subtree.

Parameters:

node - A ITreeNode that migth possibly linked to (or be) this instance by the means of the equals operation.

Returns:

True, if an ITreeNode equal to the argument was found in the subtree started by this node.

See Also:

equals(Object)

isLeaf

boolean isLeaf()

Find out, wether this ITreeNode is a childless leaf.

Returns:

True, if this ITreeNode has no child nodes.

isRoot

boolean isRoot()

Find out, wether there is no path to a higher parental node from this ITreeNode.

Returns:

True if this poor node is an orphan.

getPathFromRoot

void getPathFromRoot(List l)

Parameters:

l - An empty List: After this call it will be filled with ITreeNodeinstances starting from the root node to the current node that is invoked.

getUserObjectPathFromRoot

void getUserObjectPathFromRoot(List l)

Parameters:

l - An empty List: After this call it will be filled with the getUserObject()instances starting from the root node to the current node that was invoked.

equals

boolean equals(Object o)

Convenience method recommended for usage by implemenations.

Overrides:

equals in class Object

Parameters:

o - Possibly a ITreeNode that has to be checked for equality.

Returns:

True, if your implementation judges both instances equal.

See Also:

containsNode(ITreeNode node), removeChild(ITreeNode node)

newInstance

ITreeNode newInstance()

Generic operations in default implementations may need to allocate new instances but have to choose the right type to support the provided invariants.

If you provide a subclass that has invariants you should overload this.

Returns:

A new allocated instance of the concrete impelementation.