org.squashtest.csp.tm.domain.library.structures
Class LibraryTree<T extends TreeNode<T>>

java.lang.Object
  org.squashtest.csp.tm.domain.library.structures.LibraryTree<T>

public class LibraryTree<T extends TreeNode<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

class

LibraryTree.TreeNodePair A TreeNodePair is a scaffolding class which is mainly used when initializing a tree.

Field Summary

protected Map<Integer,List<T>>

layers

Constructor Summary

LibraryTree()

Method Summary

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	addNode(Long parentKey, T childNode) Same than addNode(TreeNodePair), but the TreeNodePair parameter will be built using the parameter provided here.
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<Long>	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	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.
T	getNode(Long key) Accepts a identifier - aka key - and returns the corresponding node if found.
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(Long parentKey, T child) An initializing version of newPair().
protected List<LibraryTree.TreeNodePair>	sortData(List<LibraryTree.TreeNodePair> unsortedData) This method accepts a list of TreeNodePair and returns the sorted version of that list.

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<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(Long 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

sortData

protected List<LibraryTree.TreeNodePair> sortData(List<LibraryTree.TreeNodePair> unsortedData)

This method accepts a list of TreeNodePair and returns the sorted version of that list. Sorting means here that nodes will be grouped by layers and the layer will be ordered.

For each TreeNodePair d from the input list:

• if there are no pair x such as d.parent == x.child.key (d's parent is not part of the output list), then d.child is inserted first
• if there is a node x such as d.parent == x.child.key (d's parent is part of the output list) then d is inserted at position(x)+1

x is taken from the output list. Note : the output implements a weak order. ie if two data have the same key their belong to the same layer of the tree, but their precise order within that layer is undefined.

Parameters:

unsortedData - an unsorted list of TreeNodePair

Returns:

the sorted list of TreeNodePair

See Also:

TreeNode, TreeNodePair.

getNode

public T getNode(Long 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<Long> 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.

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(Long 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.