gumbo.util.relation
Class AbstractTreeNode

java.lang.Object
  |
  +--gumbo.util.AbstractDisposable
        |
        +--gumbo.util.AbstractDelegatable
              |
              +--gumbo.util.AbstractDelegatable.Serial
                    |
                    +--gumbo.util.relation.AbstractRelation
                          |
                          +--gumbo.util.relation.AbstractTreeNode

All Implemented Interfaces:

Delegatable, Disposable, Relation, java.io.Serializable, TreeNode

Direct Known Subclasses:

AbstractTreeNode.Auto, TestTreeNode

public class AbstractTreeNode

extends AbstractRelation

implements TreeNode

A full implementation of the IntersectionTreeNode interface (see also AbstractTreeNodeDelegator).

To extend this class, implementors typically only need to override checkAddChild() and checkRemoveChild(). If overridden, the super method should be chained last to assure that the relation constract is satisfied. If mutators are overridden without superclass chaining be sure to check if this object is disposed, and to call checkAddChild() and checkRemoveChild(), as appropriate. Also, be sure the mutation is mutual (child added to parent, parent set in child).

The default implementation does not implement tree cycle checking, which is expensive, but does make checks for self-parent and self-child. If desired, use TreeNodes.isTreeValid() before creating a relationship to assure the new tree is acyclic.

Version:

$Revision: 1.2 $

Author:

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

See Also:

Serialized Form

Nested Class Summary

static class	AbstractTreeNode.Auto An AbstractTreeNode that automatically sets the relationship of relations (parent or child) when a connection is created, with the dead relation taking on the relationship of the live one.
static class	AbstractTreeNode.Global An AbstractTreeNode.Auto that uses a singleton (global) relationship, and throws an exception if the relationship is changed.

Nested classes inherited from class gumbo.util.AbstractDelegatable

Constructor Summary

AbstractTreeNode(Relationship relationship)
Creates an instance with an uninitialized delegator.

Method Summary

void	addChild(int index, TreeNode childR) Ignores null and duplicate unless constrained by checkAddChild(), or the children store.
void	addChild(TreeNode childR) Forwards to addChild(int, IntersectionTreeNode)
protected void	checkAddChild(TreeNode childR) Called by the system before adding a child to this parent.
protected void	checkChild(java.lang.Object child) Called by the system to check a child involved in a connection to this relation.
protected void	checkParent(java.lang.Object parent) Called by the system to check a parent involved in a connection to this relation.
protected void	checkRemoveChild(TreeNode childR) Called by the system before removing a child from this parent.
protected void	checkSetParent(TreeNode parentR) Called by the system before setting the parent of this child.
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.
protected Group	getChildrenGroup() Gets the mutable children group.
java.lang.Object	getParent() Gets the parent of this child relation.
TreeNode	getTreeNode() Gets an immutable view of this tree node.
boolean	hasChildren() Returns true if this parent has any children, false if none.
protected void	implDispose() Disconnects this tree node from its parent and children.
void	implReadConnections(java.io.ObjectInputStream s) Called by the system during deserialization when this relation should read its connection references from the serial input stream.
void	implSetParent(TreeNode parentR) Ignores null unless constrained by checkSetParent().
void	implWriteConnections(java.io.ObjectOutputStream s) Called by the system during serialization when this relation should write its connection references to the serial output stream.
protected java.util.Collection	newChildrenStore() Called by the system when it needs to lazily build the child store.
void	removeChild(TreeNode childR) Ignores null and missing unless constrained by checkRemoveChild().
java.lang.String	toString()

Methods inherited from class gumbo.util.relation.AbstractRelation

canFindRelation, checkClearedRelationship, checkRelation, checkSettingRelationship, findRelation, getAddedConnectionOut, getRelationship, getRemovingConnectionOut, initedDelegator, setRelationship

Methods inherited from class gumbo.util.AbstractDelegatable

getDelegator, initDelegator, initingDelegator, isDelegatorInited

Methods inherited from class gumbo.util.AbstractDisposable

dispose, isDisposed

Methods inherited from class java.lang.Object

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

Methods inherited from interface gumbo.util.relation.Relation

canFindRelation, findRelation, getAddedConnectionOut, getRelationship, getRemovingConnectionOut, setRelationship

Methods inherited from interface gumbo.util.Disposable

dispose, isDisposed

Methods inherited from interface gumbo.util.Delegatable

getDelegator, initDelegator, isDelegatorInited

Constructor Detail

AbstractTreeNode

public AbstractTreeNode(Relationship relationship)

Creates an instance with an uninitialized delegator. Must call initDelegator() before using this delegate, such as new AbstractTreeNode(r).initDelegator(d).

Parameters:

relationship - This relation's relationship. Null if none (a dead relation).

Method Detail

getTreeNode

public TreeNode getTreeNode()

Gets an immutable view of this tree node.

Returns:

This tree node (of Object). Never null.

newChildrenStore

protected java.util.Collection newChildrenStore()

Called by the system when it needs to lazily build the child store. Defaults to a SetList (ordered and unique children). Override as needed with a different collection type.

Returns:

A new empty store. Never null.

getChildrenGroup

protected final Group getChildrenGroup()

Gets the mutable children group.

Returns:

Reference to the children group. Never null.

checkParent

protected void checkParent(java.lang.Object parent)

Called by the system to check a parent involved in a connection to this relation. Assume checkRelation() has been called. The default implementation throws an exception if parent is null.

Parameters:

parent - Parent delegator. Possibly null.

checkSetParent

protected void checkSetParent(TreeNode parentR)

Called by the system before setting the parent of this child. The default implementation calls checkRelation() first, checkParent() last, and inbetween it does nothing if parent is null, and throws an exception if parent is this child node, this child has a parent, or if parent and child are not in the same relationship.

Parameters:

parentR - New parent relation. Null if none (orphan).

checkChild

protected void checkChild(java.lang.Object child)

Called by the system to check a child involved in a connection to this relation. Assume checkRelation() has been called. The default implementation throws an exception if child is null.

Parameters:

child - Child delegator. Possibly null.

checkAddChild

protected void checkAddChild(TreeNode childR)

Called by the system before adding a child to this parent. The default implementation calls checkRelation() first, checkChild() last, and inbetween it throws an exception if child is null, child is this parent node, child has a parent, or if parent and child are not in the same relationship.

Parameters:

childR - Child relation. Possibly null or duplicate.

checkRemoveChild

protected void checkRemoveChild(TreeNode childR)

Called by the system before removing a child from this parent. The default implementation calls checkRelation() first, checkChild() last, and inbetween it throws an exception if child is null, or if parent and child are not in the same relationship.

Parameters:

childR - Child relation. Possibly null or missing.

getParent

public java.lang.Object getParent()

Description copied from interface: TreeNode

Gets the parent of this child relation.

Specified by:

getParent in interface TreeNode

Returns:

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

addChild

public void addChild(TreeNode childR)

Forwards to addChild(int, IntersectionTreeNode)

Specified by:

addChild in interface TreeNode

Parameters:

childR - 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.

addChild

public void addChild(int index,
                     TreeNode childR)

Ignores null and duplicate unless constrained by checkAddChild(), or the children store.

Specified by:

addChild in interface TreeNode

Parameters:

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

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

removeChild

public void removeChild(TreeNode childR)

Ignores null and missing unless constrained by checkRemoveChild().

Specified by:

removeChild in interface TreeNode

Parameters:

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

hasChildren

public boolean hasChildren()

Description copied from interface: TreeNode

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

Specified by:

hasChildren in interface TreeNode

Returns:

The result.

getChildren

public Group getChildren()

Description copied from interface: TreeNode

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

Specified by:

getChildren in interface TreeNode

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)

Description copied from interface: TreeNode

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

Specified by:

findTreeNode in interface TreeNode

Parameters:

delegator - The delegator. Never null.

Returns:

The delegator's tree node. Never null.

implSetParent

public void implSetParent(TreeNode parentR)

Ignores null unless constrained by checkSetParent().

Specified by:

implSetParent in interface TreeNode

Parameters:

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

implWriteConnections

public void implWriteConnections(java.io.ObjectOutputStream s)
                          throws java.io.IOException,
                                 java.lang.ClassNotFoundException

Description copied from interface: Relation

Called by the system during serialization when this relation should write its connection references to the serial output stream. Connection references must be declared as transient so that they are written only by this method, which is called after all relationship objects (delegators and relations) have been written during normal serialization.

Specified by:

implWriteConnections in interface Relation

Parameters:

s - Output stream. Never null.

java.io.IOException

java.lang.ClassNotFoundException

implReadConnections

public void implReadConnections(java.io.ObjectInputStream s)
                         throws java.io.IOException,
                                java.lang.ClassNotFoundException

Description copied from interface: Relation

Called by the system during deserialization when this relation should read its connection references from the serial input stream. Connection references must be declared as transient so that they are read only by this method, which is called after all relationship objects (delegators and relations) have been read during normal serialization.

Specified by:

implReadConnections in interface Relation

Parameters:

s - Output stream. Never null.

java.io.IOException

java.lang.ClassNotFoundException

implDispose

protected void implDispose()

Disconnects this tree node from its parent and children.

Overrides:

implDispose in class AbstractRelation

toString

public java.lang.String toString()

Overrides:

toString in class AbstractRelation