org.squashtest.tm.domain.library.structures

Class LibraryTree<IDENT,T extends TreeNode<IDENT,T>>

java.lang.Object

org.squashtest.tm.domain.library.structures.LibraryTree<IDENT,T>

public class LibraryTree<IDENT,T extends TreeNode<IDENT,T>>
extends Object

This tree can have multiple roots and internally its structure is layered. The details are :

• This is a layered tree : the layer n is the collection of nodes of depth n. Just like nodes, layers can be accessed via the proper methods.
• There may be more than one node at layer 0. ie, the root(s),
• The parent of a node of layer n belongs to layer n-1, except for layer 0,
• The order of two nodes within the same layer is undefined (weak ordering).

The implementation is simple because its only purpose is to provide a structure to store data in. The structure is the very goal here so its not supposed to be structurally modified or rebalanced : its built once and for all.

Author:

bsiri

See Also:

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LibraryTree.SimpleNode<T>
class	LibraryTree.TreeNodePair A TreeNodePair is a scaffolding class which is mainly used when initializing a tree.

Field Summary

Fields

Modifier and Type	Field and Description
protected Map<Integer,List<T>>	layers

Constructor Summary

Constructors

Constructor and Description
LibraryTree()

Method Summary

Methods

Modifier and Type	Method and Description
void	addNode(IDENT parentKey, T childNode) Same than addNode(TreeNodePair), but the TreeNodePair parameter will be built using the parameter provided here.
void	addNode(LibraryTree.TreeNodePair newPair) Given a TreeNodePair (see documentation of the inner class for details), will add the child node to the tree.
void	addNodes(List<LibraryTree.TreeNodePair> unsortedFlatTree) Accepts a list of TreeNodePair and will add all the nodes in that list (see TreeNodePair and TreeNode).
<X> List<X>	collect(org.apache.commons.collections.Transformer transformer) That method will gather arbitrary informations on every single nodes and return the list of the gathered informations.
List<IDENT>	collectKeys() short hand for collect(Transformer) with a Transformer returning the data.key for each nodes.
protected T	createNewNode(T parent, int depth, T newNode)
void	cut(IDENT key) removes a node and its subtree
void	doBottomUp(org.apache.commons.collections.Closure closure) Accepts a Closure that will be applied on the nodes using bottom-up exploration.
void	doTopDown(org.apache.commons.collections.Closure closure) Accepts a Closure that will be applied on the nodes using top-down exploration.
List<T>	getAllNodes()
int	getDepth() return the depth of the tree, ie how many layers does the tree count.
List<T>	getLayer(Integer depth) Given an integer, returns the layer at the corresponding depth in the tree.
List<T>	getLeaves()
T	getNode(IDENT key) Accepts a identifier - aka key - and returns the corresponding node if found.
List<T>	getRootNodes()
boolean	mayRemove(IDENT key) Says whether the given node may be removed (ie it has no children)
void	merge(List<T> mergeData) Accepts a list of TreeNodes and use their data to update existing nodes data.
LibraryTree.TreeNodePair	newPair() Returns a new instance of a TreeNodePair.
LibraryTree.TreeNodePair	newPair(IDENT parentKey, T child) An initializing version of newPair().
void	remove(IDENT key) Will remove the node having this key if it is childress.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

layers

protected final Map<Integer,List<T extends TreeNode<IDENT,T>>> layers

Constructor Detail

LibraryTree

public LibraryTree()

Method Detail

getLayer

public List<T> getLayer(Integer depth)

Given an integer, returns the layer at the corresponding depth in the tree. That integer must be comprised within the acceptable bounds of that tree, ie 0 and getDepth(). The layer is returned as a list of nodes.

Parameters:

depth - the depth of the layer we want an access to.

Returns:

the layer as a list of nodes.

Throws:

IndexOutOfBoundsException

addNode

public void addNode(LibraryTree.TreeNodePair newPair)

Given a TreeNodePair (see documentation of the inner class for details), will add the child node to the tree. If the child node have no parents it will be added to layer 0 (ie, new root). Else, the child node will belong to the layer following its parent's layer.

Parameters:

newPair - a TreeNodePair with informations regarding parent and child node included.

Throws:

NoSuchElementException - if a parent node cannot be found.

addNode

public void addNode(IDENT parentKey,
           T childNode)

Same than addNode(TreeNodePair), but the TreeNodePair parameter will be built using the parameter provided here.

Parameters:

parentKey - the key designating the parent node.

childNode - the child we want eventually to insert.

addNodes

public void addNodes(List<LibraryTree.TreeNodePair> unsortedFlatTree)

Accepts a list of TreeNodePair and will add all the nodes in that list (see TreeNodePair and TreeNode). Such list can be called a flat tree and passing one to this method is a convenient way for tree initialization. You do not need to pass the TreeNodePairs in any order : the method will take care of inserting them in the correct order (ie parents before children).

Parameters:

unsortedData - the flat representation of the tree.

See Also:

#sortData(List)}, TreeNode, TreeNodePair

getNode

public T getNode(IDENT key)

Accepts a identifier - aka key - and returns the corresponding node if found.

Parameters:

key - the key identifying a node

Returns:

the node if found

Throws:

NoSuchElementException - if the node was not found.

doBottomUp

public void doBottomUp(org.apache.commons.collections.Closure closure)

Accepts a Closure that will be applied on the nodes using bottom-up exploration. The method will walk up the tree :

• layer n+1 will be treated before layer n (reverse order)
• nodes within a given layer will be treated regardless their ordering

Parameters:

closure - code to apply on the nodes.

doTopDown

public void doTopDown(org.apache.commons.collections.Closure closure)

Accepts a Closure that will be applied on the nodes using top-down exploration. The method will walk down the tree :

• the layer n will be treated before layer n+1 (natural order)
• nodes within a given layer will be treated regardless their ordering

Parameters:

closure - code to apply on the nodes.

merge

public void merge(List<T> mergeData)

Accepts a list of TreeNodes and use their data to update existing nodes data. The TreeNodes of the input list are merely carrying informations : the key property will identify actual nodes in the tree and the rest of their data will be used to update the found nodes.

The particulars of how data will be merged depends on how the TreeNodes implement TreeNode.updateWith(TreeNode).

Throws:

NoSuchElementException - if one of the node was not found.

collect

public <X> List<X> collect(org.apache.commons.collections.Transformer transformer)

That method will gather arbitrary informations on every single nodes and return the list of the gathered informations. What will be gathered and how it is done is defined in the Transformer parameter. The tree will be processed top-down, ie, walked down (see doTopDown(Closure)).

Type Parameters:

X - the type of the data returned by the transformer.

Parameters:

transformer - the code to be applied over all the nodes.

Returns:

the list of the gathered data.

collectKeys

public List<IDENT> collectKeys()

short hand for collect(Transformer) with a Transformer returning the data.key for each nodes.

Returns:

the list of the node keys.

getAllNodes

public List<T> getAllNodes()

Returns:

all the nodes.

getRootNodes

public List<T> getRootNodes()

getLeaves

public List<T> getLeaves()

mayRemove

public boolean mayRemove(IDENT key)

Says whether the given node may be removed (ie it has no children)

Parameters:

key -

remove

public void remove(IDENT key)

Will remove the node having this key if it is childress. If it has children, throws a RuntimeException

Parameters:

key -

cut

public void cut(IDENT key)

removes a node and its subtree

Parameters:

key -

getDepth

public int getDepth()

return the depth of the tree, ie how many layers does the tree count.

Returns:

the depth.

createNewNode

protected T createNewNode(T parent,
              int depth,
              T newNode)

newPair

public LibraryTree.TreeNodePair newPair()

Returns a new instance of a TreeNodePair. Basically the same thing than calling TreeNodePair constructors, that method exists mainly for semantic reasons (it guarantees that the returned TreeNodePair instance is compatible with the tree (regarding generic types).

Returns:

a new instance of a TreeNodePair.

newPair

public LibraryTree.TreeNodePair newPair(IDENT parentKey,
                               T child)

An initializing version of newPair().

Parameters:

parentKey - the identifier of the parent node.

child - the child node.

Returns:

an initialized instance of TreeNodePair.