org.jrabbit.base.data.structures
Class GroupTree<T>

java.lang.Object
  extended by org.jrabbit.base.data.structures.GroupTree<T>
Type Parameters:
T - The type of object to contain in the group.
All Implemented Interfaces:
java.lang.Iterable<T>

public class GroupTree<T>
extends java.lang.Object
implements java.lang.Iterable<T>

A GroupTree is a storage data structure that allows for recursive organization. It's "grouped" because it's a collection of objects, and it's a "tree" because groups can contain other groups which can contain others, etc. GroupTree is defined so that every group uses its child groups for operations. For example, calling contains() searches down the entire tree. To perform operations on a particular group and not affect its children, use contents() to retrieve the Collection that stores a group's personal list of objects. Likewise, one can access groups further down the tree using the provided getGroup() methods. Iterating through a GroupTree iterates through both the group contents and children - i.e., it runs through the entire tree below the specified group. Finally, a default GroupTree is "downwards only" - there are no methods for moving back up a lit (i.e., moving from a child group to the parent).

Author:
Chris Molini

Nested Class Summary
protected  class GroupTree.GroupTreeIterator
          Defines an iterator that is designed to recursively move through a GroupTree.
 
Field Summary
private  java.util.LinkedHashMap<java.lang.String,GroupTree<T>> children
          The list of subgroups under this group.
private  java.util.LinkedList<T> contents
          The list of references contained in this level of the tree.
 
Constructor Summary
GroupTree()
          Creates a default, empty group tree.
 
Method Summary
 void add(GroupTree<T> group)
          Combines another GroupTree into this one.
 boolean addChild(java.lang.String reference)
          Creates a new group and adds it as a child with the supplied String as an access key.
 boolean addChild(java.lang.String reference, GroupTree<T> group)
          Adds an existing group as a child with the supplied String as an access key.
 java.util.LinkedHashMap<java.lang.String,GroupTree<T>> children()
          Get access to the list of child groups.
 void clear()
          Clears the group and all children.
 GroupTree<T> containing(T object)
          Recursively checks the tree of groups to find the supplied object, and returns the group it is in when found.
 boolean contains(T object)
          Checks whether this group contains an object.
 java.util.LinkedList<T> contents()
          Get access to the objects the group contains.
 GroupTree<T> findChild(java.lang.String key)
          Finds the a child group that has been keyed to the indicated String.
 GroupTree<T> getChild(java.lang.String reference)
          Accesses the appropriate child group.
 boolean isEmpty()
          Checks to see if the tree holds any elements.
 java.util.Iterator<T> iterator()
          Returns an iterator that will go through the tree recursively.
 int numGroups()
          Recursively finds the number of GroupTrees in the tree that includes and extends from this GroupTree.
 void remove(GroupTree<T> group)
          Attempts to remove an entire GroupTree from the list.
 GroupTree<T> removeChild(java.lang.String reference)
          If a group is keyed to the supplied reference, it is removed.
 int size()
          Returns the size of the tree that includes and extends from this GroupTree and all child groups.
 T[] toArray(T[] array)
          Converts the entire tree into an array.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

contents

private java.util.LinkedList<T> contents
The list of references contained in this level of the tree.


children

private java.util.LinkedHashMap<java.lang.String,GroupTree<T>> children
The list of subgroups under this group.

Constructor Detail

GroupTree

public GroupTree()
Creates a default, empty group tree.

Method Detail

contents

public java.util.LinkedList<T> contents()
Get access to the objects the group contains.

Returns:
The LinkedList of objects in a group.

children

public java.util.LinkedHashMap<java.lang.String,GroupTree<T>> children()
Get access to the list of child groups.

Returns:
The LinkedHashMap of lower-level groups.

contains

public boolean contains(T object)
Checks whether this group contains an object. Recursively searches all children.

Parameters:
object - The object to search for.
Returns:
If the object was found.

add

public void add(GroupTree<T> group)
Combines another GroupTree into this one. The contents and the child groups are mixed. If the supplied group contains a mapping that matches a mapping in this group, then the two groups that share the key are mixed. The group that is being added is unchanged.

Parameters:
group - The GroupTree to add.

remove

public void remove(GroupTree<T> group)
Attempts to remove an entire GroupTree from the list. All shared contents are removed. If the Trees share children, then instead of removing those child groups, all shared contents between those two groups are removed, and then children are checked. In this way the method recursively subtracts group contents while leaving the tree of groups intact.

Parameters:
group - The GroupTree to remove.

addChild

public boolean addChild(java.lang.String reference)
Creates a new group and adds it as a child with the supplied String as an access key. The add fails if a group is already keyed to the String.

Parameters:
reference - The key that will retrieve the new group.
Returns:
Whether or not the add was successful.

addChild

public boolean addChild(java.lang.String reference,
                        GroupTree<T> group)
Adds an existing group as a child with the supplied String as an access key. If a group already exists under the supplied key, then the indicated group is combined with the existing entry.

Parameters:
reference - The key that will return the group.
group - The group to add as child group.
Returns:
True if no group existed in that location, and the add simply added a new GroupTree; false if there was a collision and the two groups had to be mixed.

getChild

public GroupTree<T> getChild(java.lang.String reference)
Accesses the appropriate child group.

Parameters:
reference - The key used to access the target group.
Returns:
The group that is keyed to the supplied String. If no group has been keyed, then returns null.

removeChild

public GroupTree<T> removeChild(java.lang.String reference)
If a group is keyed to the supplied reference, it is removed.

Parameters:
reference - The key used to find the target group.
Returns:
The group that was removed. If no object was removed, then returns null.

containing

public GroupTree<T> containing(T object)
Recursively checks the tree of groups to find the supplied object, and returns the group it is in when found.

Parameters:
object - The object to search for.
Returns:
If the group is found, then returns the group that contained it. Otherwise, returns null.

findChild

public GroupTree<T> findChild(java.lang.String key)
Finds the a child group that has been keyed to the indicated String. NOTE: This finds the *first* group under an identical reference. It is perfectly possible for multiple groups to be keyed to similar Strings in different sections of the tree.

Parameters:
key - The reference that identifies the group to find.
Returns:
A GroupTree keyed to the indicated String. If no group in the tree is mapped to the String, then returns null.

clear

public void clear()
Clears the group and all children.


numGroups

public int numGroups()
Recursively finds the number of GroupTrees in the tree that includes and extends from this GroupTree. Does not include number of elements, just the number of groups.

Returns:
How many GroupTrees make up the tree.

size

public int size()
Returns the size of the tree that includes and extends from this GroupTree and all child groups. The size does not include the Groups themselves in the count, but the number of their elements.

Returns:
How many elements this GroupTree contains.

isEmpty

public boolean isEmpty()
Checks to see if the tree holds any elements.

Returns:
If this GroupTree has any elements in any of its groups.

toArray

public T[] toArray(T[] array)
Converts the entire tree into an array.

Parameters:
array - The base array that will be resized to hold all contents.
Returns:
The tree in array form.

iterator

public java.util.Iterator<T> iterator()
Returns an iterator that will go through the tree recursively. NOTE: It is not safe to change the contents of a group while iterating through it.

Specified by:
iterator in interface java.lang.Iterable<T>
Returns:
An iterator through the GroupTree and all children.