org.coinjema.collections
Class HashTree<T>

java.lang.Object
  org.coinjema.collections.HashTree<T>

All Implemented Interfaces:

Serializable, Map<T,HashTree<T>>

Direct Known Subclasses:

ListedHashTree, SortedHashTree

public class HashTree<T>
extends Object
implements Serializable, Map<T,HashTree<T>>

This class is used to create a tree structure of objects. Each element in the tree is also a key to the next node down in the tree. It provides many ways to add objects and branches, as well as many ways to retrieve.

HashTree implements the Map interface for convenience reasons. The main difference between a Map and a HashTree is that the HashTree organizes the data into a recursive tree structure, and provides the means to manipulate that structure.

Of special interest is the traverse(HashTreeTraverser) method, which provides an expedient way to traverse any HashTree by implementing the HashTreeTraverser interface in order to perform some operation on the tree, or to extract information from the tree.

Version:

$Revision: 1.6 $ Updated on: $Date: 2006/05/22 18:28:15 $

Author:

Michael Stover (mstover1 at apache.org)

See Also:

HashTreeTraverser, SearchByClass, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Field Summary

protected Map<T,HashTree<T>>

data

Constructor Summary

HashTree()
Creates an empty new HashTree.

HashTree(Collection<? extends T> keys)
Creates a new HashTree and adds all the objects in the given collection as top-level nodes in the tree.

HashTree(T key)
Creates a new HashTree and adds the given object as a top-level node.

HashTree(T[] keys)
Creates a new HashTree and adds all the objects in the given array as top-level nodes in the tree.

Method Summary

void	add(Collection<? extends T> keys) Adds a bunch of keys into the HashTree at the current level.
void	add(Collection<? extends T> treePath, Collection<? extends T> values) Adds a series of nodes into the HashTree using the given path.
HashTree<T>	add(Collection<? extends T> treePath, T value) Adds a series of nodes into the HashTree using the given path.
void	add(Collection<? extends T> treePath, T[] values) Adds a series of nodes into the HashTree using the given path.
void	add(HashTree<? extends T> newTree) Adds all the nodes and branches of the given tree to this tree.
HashTree<T>	add(T key) Adds an key into the HashTree at the current level.
void	add(T[] keys) Adds all the given objects as nodes at the current level.
void	add(T[] treePath, Collection<? extends T> values) Adds a series of nodes into the HashTree using the given path.
void	add(T[] treePath, HashTree<? extends T> subTree)
HashTree<T>	add(T[] treePath, T value)
void	add(T[] treePath, T[] values) Adds a series of nodes into the HashTree using the given path.
void	add(T key, Collection<? extends T> values) Adds a key as a node at the current level and then adds all the objects in the second argument as nodes of the new node.
void	add(T key, HashTree<? extends T> subTree) Adds a key as a node at the current level and then adds the given HashTree to that new node.
HashTree<T>	add(T key, T value) Adds a key and it's value in the HashTree.
void	add(T key, T[] values) Adds a key and it's values in the HashTree.
protected HashTree<T>	addTreePath(Collection<? extends T> treePath)
void	clear() Clears the HashTree of all contents.
HashTree<T>	clone() Create a clone of this HashTree.
protected void	cloneTree(HashTree<T> newTree)
boolean	containsKey(Object o) If the HashTree contains the given object as a key at the top level, then a true result is returned, otherwise false.
boolean	containsValue(Object value) Implemented as required by the Map interface, but is not very useful here.
protected HashTree<T>	createNewTree() Creates a new tree.
protected HashTree<T>	createNewTree(Collection<? extends T> values) Creates a new tree.
protected HashTree<T>	createNewTree(T key) Creates a new tree.
Set<Map.Entry<T,HashTree<T>>>	entrySet()
boolean	equals(Object o) Compares all objects in the tree and verifies that the two trees contain the same objects at the same tree levels.
HashTree<T>	get(Object key)
T	getObject()
T	getObject(Collection<?> keys)
T	getObject(T... keys)
T	getObject(T key) Returns the first object of the tree associated with the given key.
HashTree<T>	getTree(Collection<?> treePath) Gets the HashTree object mapped to the last key in the SortedSet by recursing through the HashTree structure one key at a time.
HashTree<T>	getTree(Object key) Gets the HashTree mapped to the given key.
HashTree<T>	getTree(Object[] treePath) Gets the HashTree object mapped to the last key in the array by recursing through the HashTree structure one key at a time.
protected HashTree<T>	getTreePath(Collection<?> treePath)
int	hashCode() Returns a hashcode for this HashTree.
boolean	isEmpty() If the HashTree is empty, true is returned, false otherwise.
Set<T>	keySet()
Collection<T>	list() Gets a Collection of all keys in the current HashTree node.
Collection<T>	list(Collection<?> treePath) Recurses down into the HashTree stucture using each subsequent key in the List of keys, and returns the Set of keys of the HashTree object at the end of the recursion.
Collection<T>	list(Object key) Gets a Set of all keys in the HashTree mapped to the given key of the current HashTree object (in other words, one level down.
Collection<T>	list(Object[] treePath) Recurses down into the HashTree stucture using each subsequent key in the array of keys, and returns the Set of keys of the HashTree object at the end of the recursion.
HashTree<T>	put(T key, HashTree<T> val)
void	putAll(Map<? extends T,? extends HashTree<T>> input)
HashTree<T>	remove(Object key) Removes the entire branch specified by the given key.
HashTree<T>	remove(Object[] path)
void	replace(Object currentKey, T newKey) Finds the given current key, and replaces it with the given new key.
HashTree<T>	search(Object key) Searches the HashTree structure for the given key.
void	set(Collection<? extends T> values) Sets the nodes of the current tree to be the objects of the given collection.
void	set(Collection<? extends T> treePath, Collection<? extends T> values) Sets a series of keys into the HashTree.
void	set(Collection<? extends T> treePath, HashTree<T> t)
void	set(Collection<? extends T> treePath, T[] values) Sets a series of keys into the HashTree.
void	set(HashTree<T> t)
void	set(T[] treePath, Collection<? extends T> values) Sets a series of keys into the HashTree.
void	set(T[] path, HashTree<T> t)
void	set(T[] treePath, T[] values) Sets a series of keys into the HashTree.
void	set(T key, Collection<? extends T> values) Sets a key and its values in the HashTree.
void	set(T key, HashTree<T> t) Sets a key into the current tree and assigns it a HashTree as its subtree.
void	set(T key, T value) Sets a key and it's value in the HashTree.
void	set(T key, T[] values) Sets a key and it's values in the HashTree.
int	size() Returns the number of top-level entries in the HashTree.
String	toString()
void	traverse(HashTreeTraverser<T> visitor) Allows any implementation of the HashTreeTraverser interface to easily traverse (depth-first) all the nodes of the HashTree.
Collection<HashTree<T>>	values()

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

data

protected Map<T,HashTree<T>> data

Constructor Detail

HashTree

public HashTree()

Creates an empty new HashTree.

HashTree

public HashTree(T key)

Creates a new HashTree and adds the given object as a top-level node.

Parameters:

key -

HashTree

public HashTree(Collection<? extends T> keys)

Creates a new HashTree and adds all the objects in the given collection as top-level nodes in the tree.

Parameters:

keys - a collection of objects to be added to the created HashTree.

HashTree

public HashTree(T[] keys)

Creates a new HashTree and adds all the objects in the given array as top-level nodes in the tree.

Method Detail

containsValue

public boolean containsValue(Object value)

Implemented as required by the Map interface, but is not very useful here. All 'values' in a HashTree are HashTree's themselves.

Specified by:

containsValue in interface Map<T,HashTree<T>>

Parameters:

value - Object to be tested as a value.

Returns:

True if the HashTree contains the value, false otherwise.

See Also:

Map.containsValue(Object)

clear

public void clear()

Clears the HashTree of all contents.

Specified by:

clear in interface Map<T,HashTree<T>>

See Also:

Map.clear()

add

public void add(T key,
                HashTree<? extends T> subTree)

Adds a key as a node at the current level and then adds the given HashTree to that new node.

Parameters:

key - key to create in this tree

subTree - sub tree to add to the node created for the first argument.

add

public void add(HashTree<? extends T> newTree)

Adds all the nodes and branches of the given tree to this tree. Is like merging two trees. Duplicates are ignored.

Parameters:

newTree -

containsKey

public boolean containsKey(Object o)

If the HashTree contains the given object as a key at the top level, then a true result is returned, otherwise false.

Specified by:

containsKey in interface Map<T,HashTree<T>>

Parameters:

o - Object to be tested as a key.

Returns:

True if the HashTree contains the key, false otherwise.

See Also:

Map.containsKey(Object)

isEmpty

public boolean isEmpty()

If the HashTree is empty, true is returned, false otherwise.

Specified by:

isEmpty in interface Map<T,HashTree<T>>

Returns:

True if HashTree is empty, false otherwise.

set

public void set(T key,
                T value)

Sets a key and it's value in the HashTree. It actually sets up a key, and then creates a node for the key and sets the value to the new node, as a key. Any previous nodes that existed under the given key are lost.

Parameters:

key - key to be set up

value - value to be set up as a key in the secondary node

set

public void set(T key,
                HashTree<T> t)

Sets a key into the current tree and assigns it a HashTree as its subtree. Any previous entries under the given key are removed.

Parameters:

key - key to be set up

t - HashTree that the key maps to

set

public void set(T[] path,
                HashTree<T> t)

set

public void set(T key,
                T[] values)

Sets a key and it's values in the HashTree. It sets up a key in the current node, and then creates a node for that key, and sets all the values in the array as keys in the new node. Any keys previously held under the given key are lost.

Parameters:

key - Key to be set up

values - Array of objects to be added as keys in the secondary node

set

public void set(T key,
                Collection<? extends T> values)

Sets a key and its values in the HashTree. It sets up a key in the current node, and then creates a node for that key, and set all the values in the array as keys in the new node. Any keys previously held under the given key are removed.

Parameters:

key - key to be set up

values - Collection of objects to be added as keys in the secondary node

set

public void set(T[] treePath,
                T[] values)

Sets a series of keys into the HashTree. It sets up the first object in the key array as a key in the current node, recurses into the next HashTree node through that key and adds the second object in the array. Continues recursing in this manner until the end of the first array is reached, at which point all the values of the second array are set as keys to the bottom-most node. All previous keys of that bottom-most node are removed.

Parameters:

treePath - array of keys to put into HashTree

values - array of values to be added as keys to bottom-most node

set

public void set(T[] treePath,
                Collection<? extends T> values)

Sets a series of keys into the HashTree. It sets up the first object in the key array as a key in the current node, recurses into the next HashTree node through that key and adds the second object in the array. Continues recursing in this manner until the end of the first array is reached, at which point all the values of the Collection of values are set as keys to the bottom-most node. Any keys previously held by the bottom-most node are lost.

Parameters:

treePath - array of keys to put into HashTree

values - Collection of values to be added as keys to bottom-most node

set

public void set(Collection<? extends T> treePath,
                T[] values)

Sets a series of keys into the HashTree. It sets up the first object in the key list as a key in the current node, recurses into the next HashTree node through that key and adds the second object in the list. Continues recursing in this manner until the end of the first list is reached, at which point all the values of the array of values are set as keys to the bottom-most node. Any previously existing keys of that bottom node are removed.

Parameters:

treePath - collection of keys to put into HashTree

values - array of values to be added as keys to bottom-most node

set

public void set(Collection<? extends T> values)

Sets the nodes of the current tree to be the objects of the given collection. Any nodes previously in the tree are removed.

Parameters:

values - Collection of objects to set as nodes.

set

public void set(Collection<? extends T> treePath,
                Collection<? extends T> values)

Sets a series of keys into the HashTree. It sets up the first object in the key list as a key in the current node, recurses into the next HashTree node through that key and adds the second object in the list. Continues recursing in this manner until the end of the first list is reached, at which point all the values of the Collection of values are set as keys to the bottom-most node. Any previously existing keys of that bottom node are lost.

Parameters:

treePath - list of keys to put into HashTree

values - collection of values to be added as keys to bottom-most node

set

public void set(Collection<? extends T> treePath,
                HashTree<T> t)

set

public void set(HashTree<T> t)

add

public HashTree<T> add(T key)

Adds an key into the HashTree at the current level.

Parameters:

key - key to be added to HashTree

add

public void add(T[] keys)

Adds all the given objects as nodes at the current level.

Parameters:

keys - Array of Keys to be added to HashTree.

add

public void add(Collection<? extends T> keys)

Adds a bunch of keys into the HashTree at the current level.

Parameters:

keys - Collection of Keys to be added to HashTree.

add

public HashTree<T> add(T key,
                       T value)

Adds a key and it's value in the HashTree. The first argument becomes a node at the current level, and the second argument becomes a node of it.

Parameters:

key - key to be added

value - value to be added as a key in the secondary node

add

public void add(T key,
                T[] values)

Adds a key and it's values in the HashTree. The first argument becomes a node at the current level, and adds all the values in the array to the new node.

Parameters:

key - key to be added

values - array of objects to be added as keys in the secondary node

add

public void add(T key,
                Collection<? extends T> values)

Adds a key as a node at the current level and then adds all the objects in the second argument as nodes of the new node.

Parameters:

key - key to be added

values - Collection of objects to be added as keys in the secondary node

add

public void add(T[] treePath,
                T[] values)

Adds a series of nodes into the HashTree using the given path. The first argument is an array that represents a path to a specific node in the tree. If the path doesn't already exist, it is created (the objects are added along the way). At the path, all the objects in the second argument are added as nodes.

Parameters:

treePath - an array of objects representing a path

values - array of values to be added as keys to bottom-most node

add

public void add(T[] treePath,
                Collection<? extends T> values)

Adds a series of nodes into the HashTree using the given path. The first argument is an array that represents a path to a specific node in the tree. If the path doesn't already exist, it is created (the objects are added along the way). At the path, all the objects in the second argument are added as nodes.

Parameters:

treePath - an array of objects representing a path

values - collection of values to be added as keys to bottom-most node

add

public HashTree<T> add(T[] treePath,
                       T value)

add

public void add(Collection<? extends T> treePath,
                T[] values)

Adds a series of nodes into the HashTree using the given path. The first argument is a List that represents a path to a specific node in the tree. If the path doesn't already exist, it is created (the objects are added along the way). At the path, all the objects in the second argument are added as nodes.

Parameters:

treePath - a list of objects representing a path

values - array of values to be added as keys to bottom-most node

add

public HashTree<T> add(Collection<? extends T> treePath,
                       T value)

Adds a series of nodes into the HashTree using the given path. The first argument is a List that represents a path to a specific node in the tree. If the path doesn't already exist, it is created (the objects are added along the way). At the path, the object in the second argument is added as a node.

Parameters:

treePath - a list of objects representing a path

value - Object to add as a node to bottom-most node

add

public void add(T[] treePath,
                HashTree<? extends T> subTree)

add

public void add(Collection<? extends T> treePath,
                Collection<? extends T> values)

Adds a series of nodes into the HashTree using the given path. The first argument is a SortedSet that represents a path to a specific node in the tree. If the path doesn't already exist, it is created (the objects are added along the way). At the path, all the objects in the second argument are added as nodes.

Parameters:

treePath - a SortedSet of objects representing a path

values - Collection of values to be added as keys to bottom-most node

addTreePath

protected HashTree<T> addTreePath(Collection<? extends T> treePath)

getTree

public HashTree<T> getTree(Object key)

Gets the HashTree mapped to the given key.

Parameters:

key - Key used to find appropriate HashTree()

getObject

public T getObject(T key)

Returns the first object of the tree associated with the given key. This is a convenience method that essentially accomplishes the same as getArray()[0]. Returns null if the key is not found or the end tree has zero elements.

Parameters:

key -

Returns:

getObject

public T getObject()

getObject

public T getObject(T... keys)

getObject

public T getObject(Collection<?> keys)

getTree

public HashTree<T> getTree(Object[] treePath)

Gets the HashTree object mapped to the last key in the array by recursing through the HashTree structure one key at a time.

Parameters:

treePath - array of keys.

Returns:

HashTree at the end of the recursion.

clone

public HashTree<T> clone()

Create a clone of this HashTree. This is not a deep clone (ie, the contents of the tree are not cloned).

Overrides:

clone in class Object

See Also:

Object.clone()

cloneTree

protected void cloneTree(HashTree<T> newTree)

createNewTree

protected HashTree<T> createNewTree()

Creates a new tree. This method exists to allow inheriting classes to generate the appropriate types of nodes. For instance, when a node is added, it's value is a HashTree. Rather than directly calling the HashTree() constructor, the createNewTree() method is called. Inheriting classes should override these methods and create the appropriate subclass of HashTree.

Returns:

HashTree

createNewTree

protected HashTree<T> createNewTree(T key)

Creates a new tree. This method exists to allow inheriting classes to generate the appropriate types of nodes. For instance, when a node is added, it's value is a HashTree. Rather than directly calling the HashTree() constructor, the createNewTree() method is called. Inheriting classes should override these methods and create the appropriate subclass of HashTree.

Returns:

HashTree

createNewTree

protected HashTree<T> createNewTree(Collection<? extends T> values)

Creates a new tree. This method exists to allow inheriting classes to generate the appropriate types of nodes. For instance, when a node is added, it's value is a HashTree. Rather than directly calling the HashTree() constructor, the createNewTree() method is called. Inheriting classes should override these methods and create the appropriate subclass of HashTree.

Returns:

HashTree

getTree

public HashTree<T> getTree(Collection<?> treePath)

Gets the HashTree object mapped to the last key in the SortedSet by recursing through the HashTree structure one key at a time.

Parameters:

treePath - Collection of keys

Returns:

HashTree at the end of the recursion

list

public Collection<T> list()

Gets a Collection of all keys in the current HashTree node. If the HashTree represented a file system, this would be like getting a collection of all the files in the current folder.

Returns:

Set of all keys in this HashTree

list

public Collection<T> list(Object key)

Gets a Set of all keys in the HashTree mapped to the given key of the current HashTree object (in other words, one level down. If the HashTree represented a file system, this would like getting a list of all files in a sub-directory (of the current directory) specified by the key argument.

Parameters:

key - key used to find HashTree to get list of

Returns:

Set of all keys in found HashTree.

remove

public HashTree<T> remove(Object key)

Removes the entire branch specified by the given key.

Specified by:

remove in interface Map<T,HashTree<T>>

See Also:

Map.remove(Object)

remove

public HashTree<T> remove(Object[] path)

list

public Collection<T> list(Object[] treePath)

Recurses down into the HashTree stucture using each subsequent key in the array of keys, and returns the Set of keys of the HashTree object at the end of the recursion. If the HashTree represented a file system, this would be like getting a list of all the files in a directory specified by the treePath, relative from the current directory.

Parameters:

treePath - Array of keys used to recurse into HashTree structure

Returns:

Set of all keys found in end HashTree

list

public Collection<T> list(Collection<?> treePath)

Recurses down into the HashTree stucture using each subsequent key in the List of keys, and returns the Set of keys of the HashTree object at the end of the recursion. If the HashTree represented a file system, this would be like getting a list of all the files in a directory specified by the treePath, relative from the current directory.

Parameters:

treePath - List of keys used to recurse into HashTree structure

Returns:

Set of all keys found in end HashTree

replace

public void replace(Object currentKey,
                    T newKey)

Finds the given current key, and replaces it with the given new key. Any tree structure found under the original key is moved to the new key.

getTreePath

protected HashTree<T> getTreePath(Collection<?> treePath)

hashCode

public int hashCode()

Returns a hashcode for this HashTree.

Specified by:

hashCode in interface Map<T,HashTree<T>>

Overrides:

hashCode in class Object

See Also:

Object.hashCode()

equals

public boolean equals(Object o)

Compares all objects in the tree and verifies that the two trees contain the same objects at the same tree levels. Returns true if they do, false otherwise.

Specified by:

equals in interface Map<T,HashTree<T>>

Overrides:

equals in class Object

Parameters:

o - Object to be compared against

See Also:

Object.equals(Object)

search

public HashTree<T> search(Object key)

Searches the HashTree structure for the given key. If it finds the key, it returns the HashTree mapped to the key. If it finds nothing, it returns null.

Parameters:

key - Key to search for

Returns:

HashTree mapped to key, if found, otherwise null

size

public int size()

Returns the number of top-level entries in the HashTree.

Specified by:

size in interface Map<T,HashTree<T>>

See Also:

Map.size()

traverse

public void traverse(HashTreeTraverser<T> visitor)

Allows any implementation of the HashTreeTraverser interface to easily traverse (depth-first) all the nodes of the HashTree. The Traverser implementation will be given notification of each node visited.

See Also:

HashTreeTraverser

toString

public String toString()

Overrides:

toString in class Object

get

public HashTree<T> get(Object key)

Specified by:

get in interface Map<T,HashTree<T>>

put

public HashTree<T> put(T key,
                       HashTree<T> val)

Specified by:

put in interface Map<T,HashTree<T>>

entrySet

public Set<Map.Entry<T,HashTree<T>>> entrySet()

Specified by:

entrySet in interface Map<T,HashTree<T>>

keySet

public Set<T> keySet()

Specified by:

keySet in interface Map<T,HashTree<T>>

values

public Collection<HashTree<T>> values()

Specified by:

values in interface Map<T,HashTree<T>>

putAll

public void putAll(Map<? extends T,? extends HashTree<T>> input)

Specified by:

putAll in interface Map<T,HashTree<T>>