gumbo.util.relation
Interface TreeNode

All Superinterfaces:

Delegatable, Disposable, Relation

All Known Implementing Classes:

AbstractTreeNode, TreeNodes.TreeNodeImm, TreeNodes.TreeNodeWrapper

public interface TreeNode

extends Relation

An "abstract" tree node relation in a tree (parent-child) data relationship. A parent may have none or more non-null children; and, a child may have none (orphan) or one parent. Supports both set and list types of children stores.

Uses the "mixed delegation" pattern, which allows parent and child delegators to use this tree node as a public delegate, but with navigation methods (accessors) handling delegators, not tree nodes. A side effect of mixed delegation, however, is that mutators handle tree nodes, not delegates.

This tree node does not require a "true" acyclic tree. If used to implement a true tree, note that cycle checking can be expensive. As such, true tree implementations must either check if a relation causes a cycle before any mutation (see TreeNodes.isAcyclic()), or they can perform easy checks and be tolerant of cycles, such as when tracing ancestors or descendants.

Version:

$Revision: 1.2 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Method Summary

void	addChild(int index, TreeNode child) Adds a child to this parent.
void	addChild(TreeNode child) Adds a child to this parent.
TreeNode	findTreeNode(java.lang.Object delegator) Convenience method for getting the tree node corresponding to a delegator in this tree node's relationship.
Group	getChildren() Gets an immutable view of this parent's children.
java.lang.Object	getParent() Gets the parent of this child relation.
boolean	hasChildren() Returns true if this parent has any children, false if none.
void	implSetParent(TreeNode parent) Used by the system to mutually set the parent of this child.
void	removeChild(TreeNode child) Removes a child from this parent, and makes the child an orphan.

Methods inherited from interface gumbo.util.relation.Relation

canFindRelation, findRelation, getAddedConnectionOut, getRelationship, getRemovingConnectionOut, implReadConnections, implWriteConnections, setRelationship

Methods inherited from interface gumbo.util.Disposable

dispose, isDisposed

Methods inherited from interface gumbo.util.Delegatable

getDelegator, initDelegator, isDelegatorInited

Method Detail

getParent

public java.lang.Object getParent()

Gets the parent of this child relation.

Returns:

Parent delegator. Null if none (an orphan child).

addChild

public void addChild(TreeNode child)

Adds a child to this parent. The child must be an orphan (no parent). If the children store is a list the child is added to the end. Unless otherwise noted, the parent and child must be in the same relationship, the connect change is type TreeNodeConnection.

Parameters:

child - Child relation. Never null. Unless otherwise noted, duplicates are the same as a new child. Note that a SetList children store will throw an exception for duplicates.

Throws:

java.lang.IllegalStateException - The child already has a parent.

addChild

public void addChild(int index,
                     TreeNode child)

Adds a child to this parent. The child must be an orphan (no parent). The child is inserted at a given position in the child list, with children at and after this position being shifted towards the end. Unless otherwise noted, the parent and child must be in the same relationship.

Parameters:

index - List index (>=0, <=size). If <0, same as addChild(Object) regardless of children store type.

child - Child relation. Never null. Unless otherwise noted, duplicates are ignored. Note that a SetList children store will throw an exception for duplicates.

Throws:

java.lang.IllegalStateException - The child already has a parent.

java.lang.UnsupportedOperationException - The children store is not a list.

removeChild

public void removeChild(TreeNode child)

Removes a child from this parent, and makes the child an orphan. Unless otherwise noted, the parent and child will remain in the same relationship.

Parameters:

child - Child relation. Never null. Unless otherwise noted, a missing child is ignored.

hasChildren

public boolean hasChildren()

Returns true if this parent has any children, false if none.

Returns:

The result.

getChildren

public Group getChildren()

Gets an immutable view of this parent's children. When possible, use hasChildren() instead of this view to minimize lazy builds.

Returns:

The non-null child delegators (Object). Never null. Unless otherwise noted, this is a singleton immutable view.

findTreeNode

public TreeNode findTreeNode(java.lang.Object delegator)

Convenience method for getting the tree node corresponding to a delegator in this tree node's relationship.

Parameters:

delegator - The delegator. Never null.

Returns:

The delegator's tree node. Never null.

Throws:

java.lang.IllegalArgumentException - Delegator is null.

java.lang.IllegalStateException - This relation is not in a relationship.

implSetParent

public void implSetParent(TreeNode parent)

Used by the system to mutually set the parent of this child. By convention, performs checking but affects no other state.

Parameters:

parent - Parent relation. Null if none (orphan).