fri.util.database.jpa.tree.nestedsets
Class NestedSetsTreeDao

java.lang.Object
  extended by fri.util.database.jpa.tree.AbstractTreeDao<NestedSetsTreeNode>
      extended by fri.util.database.jpa.tree.nestedsets.NestedSetsTreeDao
All Implemented Interfaces:
TreeDao<NestedSetsTreeNode>
Direct Known Subclasses:
TemporalNestedSetsTreeDao

public class NestedSetsTreeDao
extends AbstractTreeDao<NestedSetsTreeNode>

Data-access-object for a hierarchical representation of records (nodes), using one database table, having no parent reference in children. A nested-sets tree will always maintain child positions, meaning children lists have a defined order which can only be changed by a move().

A nested-sets tree maintains its structure by "left" and "right" indexes on every node. The left index represents the depth-first traversal order. The right index is (left + 1) for a leaf child, for a folder it is (right + 1) of the child it follows according to depth-first traversal. For a root, left index is 1, right index is (number of nodes * 2). See links in TreeDao for more information.

Note: as the temporal derivation obtains a state, all write-methods here are synchronized.

Author:
Fritz Ritzberger, 08.10.2011
See Also:
NestedSetsTreeNode, TreeDao

Nested Class Summary
 
Nested classes/interfaces inherited from interface fri.util.database.jpa.tree.TreeDao
TreeDao.CopiedNodeRenamer<N extends TreeNode>
 
Field Summary
 
Fields inherited from class fri.util.database.jpa.tree.AbstractTreeDao
session
 
Fields inherited from interface fri.util.database.jpa.tree.TreeDao
UNDEFINED_POSITION
 
Constructor Summary
NestedSetsTreeDao(java.lang.Class<? extends NestedSetsTreeNode> entityClass, DbSession session)
           
NestedSetsTreeDao(java.lang.Class<? extends NestedSetsTreeNode> entityClass, java.lang.String entityName, DbSession session)
           
 
Method Summary
 NestedSetsTreeNode addChild(NestedSetsTreeNode parent, NestedSetsTreeNode child)
          Adds to end of children of given parent.
 NestedSetsTreeNode addChildAt(NestedSetsTreeNode parent, NestedSetsTreeNode child, int position)
          Adds at specified position to children of given parent.
 NestedSetsTreeNode addChildBefore(NestedSetsTreeNode sibling, NestedSetsTreeNode child)
          Adds to children before given sibling, sibling is pushed backwards in children list.
protected  void beforeFindQuery(java.lang.String tableAlias, java.lang.StringBuilder queryText, java.util.List<java.lang.Object> parameters, boolean whereWasAppended)
          Does nothing.
 NestedSetsTreeNode copy(NestedSetsTreeNode node, NestedSetsTreeNode parent, NestedSetsTreeNode copiedNodeTemplate)
          Copies the given node to end of children list of parent.
 NestedSetsTreeNode copyBefore(NestedSetsTreeNode node, NestedSetsTreeNode sibling, NestedSetsTreeNode copiedNodeTemplate)
          Copies the given node to position of given sibling, pushing sibling backwards in list.
protected  void copyOrMovePreconditions(NestedSetsTreeNode relativeNode, NestedSetsTreeNode nodeToMove)
          Throws IllegalArgumentException when copy or move could not performed, checks if tree would be copied/moved into itself.
 NestedSetsTreeNode copyTo(NestedSetsTreeNode node, NestedSetsTreeNode parent, int position, NestedSetsTreeNode copiedNodeTemplate)
          Copies the given node to given position in children list of parent.
 NestedSetsTreeNode copyToBeRoot(NestedSetsTreeNode child, NestedSetsTreeNode copiedNodeTemplate)
          Copies a tree to be a root.
 NestedSetsTreeNode createRoot(NestedSetsTreeNode root)
          Creates a tree root node.
 java.util.List<NestedSetsTreeNode> find(NestedSetsTreeNode parent, java.util.Map<java.lang.String,java.lang.Object> criteria)
          Convenience finder method.
 NestedSetsTreeNode find(java.io.Serializable id)
          
 java.util.List<NestedSetsTreeNode> findDirectChildren(java.util.List<NestedSetsTreeNode> subNodes)
          Finds a children list from a predefined list of nodes under a parent which is first in list.
 java.util.List<NestedSetsTreeNode> findSubTree(NestedSetsTreeNode parent, java.util.List<NestedSetsTreeNode> tree)
          Finds a sub-tree list from a predefined list of nodes under a parent.
 int getChildCount(NestedSetsTreeNode parent)
          
protected  java.util.List<NestedSetsTreeNode> getChildListForInsertion(NestedSetsTreeNode parent)
           
 java.util.List<NestedSetsTreeNode> getChildren(NestedSetsTreeNode parent)
          Gives the children of passed parent.
 int getLevel(NestedSetsTreeNode node)
          
 NestedSetsTreeNode getParent(NestedSetsTreeNode node)
          
 java.util.List<NestedSetsTreeNode> getPath(NestedSetsTreeNode node)
          
 NestedSetsTreeNode getRoot(NestedSetsTreeNode node)
          
 java.util.List<NestedSetsTreeNode> getRoots()
          
protected  java.util.List<NestedSetsTreeNode> getSubTreeDepthFirstForCopy(NestedSetsTreeNode nodeToCopy)
           
 java.util.List<NestedSetsTreeNode> getTree(NestedSetsTreeNode parent)
          Reads a tree or sub-tree, including all children.
 java.util.List<NestedSetsTreeNode> getTreeCacheable(NestedSetsTreeNode parent)
          Reads a tree or sub-tree, including all children, which can be cached and passed back into findSubTree() or findDirectChildren().
 boolean isChildOf(NestedSetsTreeNode child, NestedSetsTreeNode parent)
          
 boolean isEqualToOrChildOf(NestedSetsTreeNode child, NestedSetsTreeNode parent)
          
 boolean isLeaf(NestedSetsTreeNode node)
          
protected  boolean isNextChild(int nextChildLeft, NestedSetsTreeNode node, int currentChildRight, java.util.List<NestedSetsTreeNode> subNodes, int currentIndex)
           
 boolean isRoot(NestedSetsTreeNode entity)
          
protected  boolean isValidFilterChild(NestedSetsTreeNode entity)
          Called by filterChildren() from getChildren().
 void move(NestedSetsTreeNode node, NestedSetsTreeNode newParent)
          Moves the given node to end of children list of parent.
 void moveBefore(NestedSetsTreeNode node, NestedSetsTreeNode sibling)
          Moves the given node to position of given sibling, pushing sibling backwards in list.
 void moveTo(NestedSetsTreeNode node, NestedSetsTreeNode parent, int position)
          Moves the given node to given position in children list of parent.
 void moveToBeRoot(NestedSetsTreeNode child)
          Moves a sub-tree to be a root.
 void remove(NestedSetsTreeNode node)
          Removes the tree under given node, including the node.
protected  void remove(NestedSetsTreeNode node, int removedNodesCount)
          Removes given children.
 void removeAll()
          Removes all roots, including the nodes below them.
 int size(NestedSetsTreeNode entity)
          
 void update(NestedSetsTreeNode entity)
          Updates the given persistent object.
 
Methods inherited from class fri.util.database.jpa.tree.AbstractTreeDao
appendInvalidityCondition, appendValidityCondition, applyCopiedNodeRenamer, assertUpdate, beforeFindQuery, buildAliasedPropertyName, buildIndexedPlaceHolder, checkUniqueConstraint, checkUniqueness, equal, getUniqueTreeConstraint, getValidFromPropertyName, getValidToPropertyName, isPersistent, isValid, nodeEntityName, pathEntityName, refresh, save, setCheckUniqueConstraintOnUpdate, setCopiedNodeRenamer, setUniqueTreeConstraint, shouldCheckUniqueConstraintOnUpdate, validFrom, validTo, validToOnRemove
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

NestedSetsTreeDao

public NestedSetsTreeDao(java.lang.Class<? extends NestedSetsTreeNode> entityClass,
                         DbSession session)
Parameters:
entityClass - the persistence class representing the tree, implementing NestedSetsTreeNode.
dbSession - the database layer abstraction to be used for persistence actions. Its simpleName will be used as table name for queries.

NestedSetsTreeDao

public NestedSetsTreeDao(java.lang.Class<? extends NestedSetsTreeNode> entityClass,
                         java.lang.String entityName,
                         DbSession session)
Parameters:
entityClass - the persistence class representing the tree table, implementing NestedSetsTreeNode.
entityName - the JPQL entity name of the database table to be used for queries, normally entityClass.getSimpleName().
dbSession - the database layer abstraction to be used for persistence actions.
Method Detail

find

public NestedSetsTreeNode find(java.io.Serializable id)

Returns:
the object by identity (primary key) from database.

update

public void update(NestedSetsTreeNode entity)
            throws UniqueConstraintViolationException
Updates the given persistent object. This performs explicit constraint checking when checkUniqueConstraintsOnUpdate is true (default is false).

Throws:
UniqueConstraintViolationException - when given entity is not unique.

isRoot

public final boolean isRoot(NestedSetsTreeNode entity)

Returns:
true if passed node is persistent and a root.

createRoot

public NestedSetsTreeNode createRoot(NestedSetsTreeNode root)
                              throws UniqueConstraintViolationException
Creates a tree root node.

Throws:
UniqueConstraintViolationException - when uniqueness would be violated.

getRoots

public java.util.List<NestedSetsTreeNode> getRoots()

Returns:
all tree root nodes.

removeAll

public void removeAll()
Removes all roots, including the nodes below them. Thus clears the table.


size

public int size(NestedSetsTreeNode entity)

Returns:
the count of all nodes of any depth below given node, including itself.

getTree

public java.util.List<NestedSetsTreeNode> getTree(NestedSetsTreeNode parent)
Reads a tree or sub-tree, including all children. The result is NOT EXPECTED to be used with findSubTree() or findDirectChildren()!

Parameters:
parent - the parent of the tree to read, can also be root of the tree.
Returns:
all tree nodes under given parent, including parent.

getTreeCacheable

public java.util.List<NestedSetsTreeNode> getTreeCacheable(NestedSetsTreeNode parent)
Reads a tree or sub-tree, including all children, which can be cached and passed back into findSubTree() or findDirectChildren(). Mind that any cached tree could be out-of-sync with database when another client performs changes.

Parameters:
parent - the parent of the tree to read, can also be root of the tree.
Returns:
all tree nodes under given parent, including parent, in depth-first order.

isLeaf

public boolean isLeaf(NestedSetsTreeNode node)

Returns:
true when given node has no children, i.e. is not a container-node.

getChildCount

public int getChildCount(NestedSetsTreeNode parent)

Returns:
the number of direct children of given parent node.

getChildren

public java.util.List<NestedSetsTreeNode> getChildren(NestedSetsTreeNode parent)
Gives the children of passed parent. This method reads the full subtree under parent. Removing from returned list will not remove that child from tree but cause an exception.

Returns:
the ordered list of direct children under given parent.

findDirectChildren

public java.util.List<NestedSetsTreeNode> findDirectChildren(java.util.List<NestedSetsTreeNode> subNodes)
Finds a children list from a predefined list of nodes under a parent which is first in list. This might help analyzing and caching tree lists.

Parameters:
subNodes - a list of nodes from which to extract the direct child list, parent at head of list.
Returns:
a list of direct children of the the parent node that is first in list.

isNextChild

protected boolean isNextChild(int nextChildLeft,
                              NestedSetsTreeNode node,
                              int currentChildRight,
                              java.util.List<NestedSetsTreeNode> subNodes,
                              int currentIndex)
Returns:
true if node-left is nextChildLeft. Override this when left-indexes have gaps.

findSubTree

public final java.util.List<NestedSetsTreeNode> findSubTree(NestedSetsTreeNode parent,
                                                            java.util.List<NestedSetsTreeNode> tree)
Finds a sub-tree list from a predefined list of nodes under a parent. This might help analyzing and caching tree lists.

Parameters:
parent - the parent node to search a sub-tree for, contained somewhere in the given list of nodes.
tree - a list of nodes from which to extract a sub-tree, containing the given parent.
Returns:
a list of nodes under the passed parent node.

isValidFilterChild

protected boolean isValidFilterChild(NestedSetsTreeNode entity)
Called by filterChildren() from getChildren(). Always returns true because this is not a temporal implementation. To be overridden.


getRoot

public NestedSetsTreeNode getRoot(NestedSetsTreeNode node)

Returns:
the root node of given node. Root has itself as root.

getParent

public NestedSetsTreeNode getParent(NestedSetsTreeNode node)

Returns:
the parent node of given node. Root has null as parent.

getPath

public java.util.List<NestedSetsTreeNode> getPath(NestedSetsTreeNode node)

Returns:
all parent nodes of given node, i.e. its path from root to (exclusive) node. Root will return an empty list.

getLevel

public int getLevel(NestedSetsTreeNode node)

Returns:
the depth of given node. Root has level 0.

isEqualToOrChildOf

public boolean isEqualToOrChildOf(NestedSetsTreeNode child,
                                  NestedSetsTreeNode parent)

Returns:
true when child is in the tree under parent, or parent is equal to child, else false.

isChildOf

public boolean isChildOf(NestedSetsTreeNode child,
                         NestedSetsTreeNode parent)

Returns:
true when child is in the tree under parent and not parent, else false.

addChild

public NestedSetsTreeNode addChild(NestedSetsTreeNode parent,
                                   NestedSetsTreeNode child)
                            throws UniqueConstraintViolationException
Adds to end of children of given parent.

Throws:
UniqueConstraintViolationException - when uniqueness would be violated.

addChildAt

public NestedSetsTreeNode addChildAt(NestedSetsTreeNode parent,
                                     NestedSetsTreeNode child,
                                     int position)
                              throws UniqueConstraintViolationException
Adds at specified position to children of given parent.

position - -1 for append, else target position in child list.
Throws:
UniqueConstraintViolationException - when uniqueness would be violated.

addChildBefore

public NestedSetsTreeNode addChildBefore(NestedSetsTreeNode sibling,
                                         NestedSetsTreeNode child)
                                  throws UniqueConstraintViolationException
Adds to children before given sibling, sibling is pushed backwards in children list.

Throws:
UniqueConstraintViolationException - when uniqueness would be violated.

remove

public void remove(NestedSetsTreeNode node)
Removes the tree under given node, including the node. Node can also be a root.


move

public void move(NestedSetsTreeNode node,
                 NestedSetsTreeNode newParent)
          throws UniqueConstraintViolationException
Moves the given node to end of children list of parent. When source is identical with target, nothing happens.

Throws:
UniqueConstraintViolationException

moveTo

public void moveTo(NestedSetsTreeNode node,
                   NestedSetsTreeNode parent,
                   int position)
            throws UniqueConstraintViolationException
Moves the given node to given position in children list of parent. When source is identical with target, nothing happens.

Throws:
UniqueConstraintViolationException

moveBefore

public void moveBefore(NestedSetsTreeNode node,
                       NestedSetsTreeNode sibling)
                throws UniqueConstraintViolationException
Moves the given node to position of given sibling, pushing sibling backwards in list. When source is identical with target, nothing happens.

Throws:
UniqueConstraintViolationException

moveToBeRoot

public void moveToBeRoot(NestedSetsTreeNode child)
                  throws UniqueConstraintViolationException
Moves a sub-tree to be a root. This means it is removed from its previous root. When child is already a root, nothing happens.

Throws:
UniqueConstraintViolationException - when unique constraint(s) for roots would be violated.

copy

public NestedSetsTreeNode copy(NestedSetsTreeNode node,
                               NestedSetsTreeNode parent,
                               NestedSetsTreeNode copiedNodeTemplate)
                        throws UniqueConstraintViolationException
Copies the given node to end of children list of parent. When source is identical with target, the node will be be copied to the position of its originator.

Parameters:
node - the node to be copied.
copiedNodeTemplate - a template for the copied node containing altered properties, can be null.
Throws:
UniqueConstraintViolationException - when uniqueness would be violated.

copyTo

public NestedSetsTreeNode copyTo(NestedSetsTreeNode node,
                                 NestedSetsTreeNode parent,
                                 int position,
                                 NestedSetsTreeNode copiedNodeTemplate)
                          throws UniqueConstraintViolationException
Copies the given node to given position in children list of parent. When source is identical with target, the node will be be copied to the position of its originator.

Parameters:
node - the node to be copied.
parent - the parent-node of the children the node should be copied into.
position - the 0-n index the node should obtain within children of parent.
copiedNodeTemplate - a template for the copied node containing altered properties, can be null.
Throws:
UniqueConstraintViolationException - when uniqueness would be violated.

copyBefore

public NestedSetsTreeNode copyBefore(NestedSetsTreeNode node,
                                     NestedSetsTreeNode sibling,
                                     NestedSetsTreeNode copiedNodeTemplate)
                              throws UniqueConstraintViolationException
Copies the given node to position of given sibling, pushing sibling backwards in list. When source is identical with target, the node will be be copied to the position of its originator.

Parameters:
node - the node to be copied.
sibling - the target node the copied node should push backwards in children list.
copiedNodeTemplate - a template for the copied node containing altered properties, can be null.
Throws:
UniqueConstraintViolationException - when uniqueness would be violated.

copyToBeRoot

public NestedSetsTreeNode copyToBeRoot(NestedSetsTreeNode child,
                                       NestedSetsTreeNode copiedNodeTemplate)
                                throws UniqueConstraintViolationException
Copies a tree to be a root. This means it is removed from its previous root. When child is already a root, the node will be be copied to be another root.

Parameters:
child - the node to copy to be a root.
copiedNodeTemplate - a template for the copied node containing altered properties, can be null.
Throws:
UniqueConstraintViolationException - when unique constraint(s) for roots would be violated.

find

public java.util.List<NestedSetsTreeNode> find(NestedSetsTreeNode parent,
                                               java.util.Map<java.lang.String,java.lang.Object> criteria)
Convenience finder method. All criteria will be AND'ed.

Parameters:
parent - the parent under which to search, can be null.
criteria - a name/value mapping for the nodes to be found under given tree.
Returns:
tree nodes with given criteria.

beforeFindQuery

protected void beforeFindQuery(java.lang.String tableAlias,
                               java.lang.StringBuilder queryText,
                               java.util.List<java.lang.Object> parameters,
                               boolean whereWasAppended)
Does nothing. Override to append temporal conditions. Called from all querying methods. This method is expected to first append a WHERE when whereWasAppended is false, or an AND when whereWasAppended is true.


remove

protected void remove(NestedSetsTreeNode node,
                      int removedNodesCount)
Removes given children. To be overridden by subclasses.


getChildListForInsertion

protected java.util.List<NestedSetsTreeNode> getChildListForInsertion(NestedSetsTreeNode parent)
Returns:
children list of given parent, called from insertionParameters(), to be overridden by subclasses.

copyOrMovePreconditions

protected void copyOrMovePreconditions(NestedSetsTreeNode relativeNode,
                                       NestedSetsTreeNode nodeToMove)
Description copied from class: AbstractTreeDao
Throws IllegalArgumentException when copy or move could not performed, checks if tree would be copied/moved into itself.

Overrides:
copyOrMovePreconditions in class AbstractTreeDao<NestedSetsTreeNode>

getSubTreeDepthFirstForCopy

protected java.util.List<NestedSetsTreeNode> getSubTreeDepthFirstForCopy(NestedSetsTreeNode nodeToCopy)
Returns:
the tree under given node when copying, to be overridden.