gishur.core
Class BasicTreeItem

java.lang.Object
  |
  +--gishur.core.BasicTreeItem
All Implemented Interfaces:
java.lang.Cloneable, Cloneable, ControlledCloneable, KeyValueHolder, java.io.Serializable, TreeItem
Direct Known Subclasses:
SimpleTreeItem, StdTreeItem

public class BasicTreeItem
extends java.lang.Object
implements TreeItem, ControlledCloneable, java.io.Serializable

Most simple TreeItem. All methods of TreeItem are implemented correctly. A simple BasicTreeItem is not able to store a key or a value. It is the basis class for SimpleTreeItem and StdTreeItem.

Version:
1.0
Author:
Thomas Wolf
See Also:
Serialized Form

Fields inherited from interface gishur.core.TreeItem
CLEAR_CONNECTIONS, CONNECT, CONNECT_PARENT, LAST_CHILD, LEFT, PARENT, REMOVE, RIGHT, SET_BALANCE, SET_MAX_RANK, SET_OWNER, UNKNOWN
 
Fields inherited from interface gishur.core.KeyValueHolder
SET_KEY, SET_VALUE
 
Fields inherited from interface gishur.core.ControlledCloneable
DEEP, FLAT
 
Constructor Summary
BasicTreeItem(int maxrank)
          Creates a TreeItem that is able to own up to maxrank children.
 
Method Summary
 boolean answerConnect(TreeItem node, int pos)
          Completes the connection process and should thus only be called by connect(TreeItem, int).
 byte balance()
          Returns the balance value of this node.
 TreeItem child(int pos)
          Returns the child-node at position pos within the tree structure.
 boolean clearConnections()
          Clears all connections starting and ending at this TreeItem.
 java.lang.Object clone()
          Clones the object.
 java.lang.Object clone(java.util.Hashtable h, int level)
          Clones the object according to ControlledCloneable.
 boolean connect(TreeItem node, int pos)
          Connects this TreeItem to another one given by node, setting this node as child no.
 boolean cut()
          Cuts the partial tree beginning with this node out of the tree.
 boolean equals(java.lang.Object object)
          Compares two TreeItems.
 Owner getOwningTree()
          Returns the Owner of this ListItem
 boolean isInner()
          Returns true, if this node is an inner node (that means that it has at least one child-node).
 boolean isLeaf()
          Returns true if this node is a leaf (has no children).
 boolean isRoot()
          Returns true, if this node is a root (that means that it has no parent-node).
 java.lang.Object key()
          Returns the stored key of this object.
 int level()
          Returns the level of the tree in wich this TreeItem is positioned.
 int maxRank()
          Returns the maximal rank of this TreeItem.
 int nextChildPos(int pos)
          Returns the position of the first child-node after position pos, which is not null.
 TreeItem parent()
          Returns the father-node within the tree structure.
 int pos(TreeItem child)
          Returns the position of the node child in this node.
 int prevChildPos(int pos)
          Returns the position of the last child-node before or at position pos, which is not null.
 int rank()
          Returns the rank of this node, which is the number of children connected to this node (each node except for the root has only one parent, so the parent does not increase the rank).
 boolean remove()
          Removes the node from the tree.
protected  boolean requestTreeAccess(int accesstype, java.lang.Object argument)
          Asks the Owner for permission to perform an operation of type accesstype with the argument argument.
 boolean setBalance(byte b)
          Sets the balance value, if the Owner permits it.
 boolean setKey(java.lang.Object key)
          Sets the key of this TreeItem.
 boolean setMaxRank(int mr)
          Sets the maximal rank of this node to mr after the Owner was asked for permission.
 boolean setOwningTree(Owner owner)
          Defines the Owner for this TreeItem.
 boolean setValue(java.lang.Object object)
          Stores the object object into this node.
 TreeItem sibling()
          Returns the brother-node.
 java.lang.String toString()
          Overrides Object.toString().
 java.lang.Object value()
          Returns the stored value.
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

BasicTreeItem

public BasicTreeItem(int maxrank)
Creates a TreeItem that is able to own up to maxrank children.
Parameters:
maxrank - maximal rank, that means the maximal number of children-nodes
Method Detail

equals

public boolean equals(java.lang.Object object)
Compares two TreeItems. They are only equal, if their keys are equal in the sense of the java.lang.Object.equals(Object)-method. equals(Object) returns true, if this and object are references to the same object, if object.equals(key()) returns true or if object is a TreeItem and is equal to this TreeItem. This method overrides java.lang.Object.equals(Object).
Overrides:
equals in class java.lang.Object
Parameters:
object - object to compare with this object's key
Returns:
true, if both are equal

toString

public java.lang.String toString()
Overrides Object.toString().
Overrides:
toString in class java.lang.Object

clone

public java.lang.Object clone()
Clones the object. The new TreeItem is not connected and has no owner. The attached keys and values will be cloned as well.
Specified by:
clone in interface TreeItem
Overrides:
clone in class java.lang.Object
Returns:
copy of this TreeItem
Throws:
InternalError - - if the Object could not be cloned properly
See Also:
Cloneable

clone

public java.lang.Object clone(java.util.Hashtable h,
                              int level)
Clones the object according to ControlledCloneable. The new TreeItem is not connected.
Specified by:
clone in interface TreeItem
Parameters:
h - Hashtable to indicate which objects are already cloned
level - indicates how deep the objects should be cloned
Returns:
cloned object
Throws:
InternalError - - if the Object could not be cloned properly
See Also:
ControlledCloneable

setOwningTree

public boolean setOwningTree(Owner owner)
Defines the Owner for this TreeItem. If it is already owned, the old Owner is asked for permission. Additionally, the new owner will be asked for permission. The change takes place if both agree. If the old and the new Owner are the same, true will be returned.
Specified by:
setOwningTree in interface TreeItem
Parameters:
owner - new Owner
Returns:
true, if the owner was set as new Owner successfully

getOwningTree

public Owner getOwningTree()
Returns the Owner of this ListItem
Specified by:
getOwningTree in interface TreeItem
Returns:
the Owner

requestTreeAccess

protected boolean requestTreeAccess(int accesstype,
                                    java.lang.Object argument)
Asks the Owner for permission to perform an operation of type accesstype with the argument argument.
Parameters:
accesstype - type of operation (that means type of access)
argument - argument of the requested operation
Returns:
true, if the Owner allows the operation, false otherwise

balance

public byte balance()
Returns the balance value of this node.
Specified by:
balance in interface TreeItem
Returns:
balance value

setBalance

public boolean setBalance(byte b)
Sets the balance value, if the Owner permits it.
Specified by:
setBalance in interface TreeItem
Parameters:
b - new balance value
Returns:
true, if the operation has been successful, false, if the Owner denied access to the balance value

parent

public TreeItem parent()
Returns the father-node within the tree structure.
Specified by:
parent in interface TreeItem
Returns:
the father-node

child

public TreeItem child(int pos)
Returns the child-node at position pos within the tree structure. If pos==PARENT, the father-node will be returned.
Specified by:
child in interface TreeItem
Parameters:
pos - position of the child-node to be returned
Returns:
the requested child-node

sibling

public TreeItem sibling()
Returns the brother-node. This is especially senseful for binary trees. In other cases, the symmetric brother (which is on position maxRank()-1-_parent.pos(this)) is returned. Liefert den Bruder des aktuellen Knotens. Das macht vor allem Sinn
Specified by:
sibling in interface TreeItem
Returns:
brother-node

pos

public int pos(TreeItem child)
Returns the position of the node child in this node. If PARENT is returned, child is the father-node. If child was not found among the child-nodes of this, UNKNOWN is returned, otherwise the position of child.
Specified by:
pos in interface TreeItem
Parameters:
child - TreeItem whose position as child of this node is requested
Returns:
position of child or PARENT or UNKNOWN

nextChildPos

public int nextChildPos(int pos)
Returns the position of the first child-node after position pos, which is not null. If there is no such child or pos==LAST_CHILD, UNKNOWN is returned. If pos==UNKNOWN or pos==PARENT, the position of the first child which is not null will be returned.
Specified by:
nextChildPos in interface TreeItem
Parameters:
pos - position from which the search for the next child-node starts
Returns:
position of the next child !=null

prevChildPos

public int prevChildPos(int pos)
Returns the position of the last child-node before or at position pos, which is not null. If there is no such node, UNKNOWN will be returned. If pos==LAST_CHILD, pos==UNKNOWN or pos==PARENT, the child!=null with the largest pos value is returned.
Specified by:
prevChildPos in interface TreeItem
Parameters:
pos - position before and at which to search for a child-node
Returns:
postion of the last child which is not null, or UNKNOWN

isLeaf

public boolean isLeaf()
Returns true if this node is a leaf (has no children).
Specified by:
isLeaf in interface TreeItem
Returns:
true, if this node is a leaf

isInner

public boolean isInner()
Returns true, if this node is an inner node (that means that it has at least one child-node).
Specified by:
isInner in interface TreeItem
Returns:
true, if this node has at least one child

isRoot

public boolean isRoot()
Returns true, if this node is a root (that means that it has no parent-node).
Specified by:
isRoot in interface TreeItem
Returns:
true, if this node is a root

rank

public int rank()
Returns the rank of this node, which is the number of children connected to this node (each node except for the root has only one parent, so the parent does not increase the rank).
Specified by:
rank in interface TreeItem
Returns:
number of children connected to this node

maxRank

public int maxRank()
Returns the maximal rank of this TreeItem.
Specified by:
maxRank in interface TreeItem
Returns:
maximal rank

level

public int level()
Returns the level of the tree in wich this TreeItem is positioned. The root is on level 0, their children on level 1 etc.
Specified by:
level in interface TreeItem
Returns:
tree-level of this node

setMaxRank

public boolean setMaxRank(int mr)
Sets the maximal rank of this node to mr after the Owner was asked for permission. If access was granted and the operation has been performed successfully, true is returned.
Specified by:
setMaxRank in interface TreeItem
Parameters:
mr - new maximal rank
Returns:
true, if the Owner allows the operation and it was successfully performed

answerConnect

public boolean answerConnect(TreeItem node,
                             int pos)
Completes the connection process and should thus only be called by connect(TreeItem, int). The Owner must not be asked for permission again (all necessary tests are performed by connect(TreeItem, int), but answerConnect(TreeItem, int) needs to ensure that it was called by connect(TreeItem, int). This is possible by checking if 'half' the connection has been established yet.
Specified by:
answerConnect in interface TreeItem
Parameters:
node - the node which should become the parent for this TreeItem
pos - position to which this TreeItem shall be connected
Returns:
true, if the connection was allowed and successfully performed

connect

public boolean connect(TreeItem node,
                       int pos)
Connects this TreeItem to another one given by node, setting this node as child no. pos to node. It is only possible to connect two nodes belonging to the same structure. To establish a correct connection, answerConnect(TreeItem, int) is called by node. If the connection is not allowed by the Owner or if an error occurrs while connecting, false is returned. If pos==PARENT, node will be ignored and the TreeItem is connected to null as parent.
Specified by:
connect in interface TreeItem
Parameters:
node - node to connect this as child to
pos - the position to which this shall be connected as child of node
Returns:
true, if the connection is allowed and performed successfully

cut

public boolean cut()
Cuts the partial tree beginning with this node out of the tree. The owning tree is asked for permission only by the parent node, if it is allowed to set its son's parent connection to null, all other connections remain untouched.
Specified by:
cut in interface TreeItem
Returns:
true, if cutting off the partial tree was allowed and performed successfully

remove

public boolean remove()
Removes the node from the tree. This is only possible if rank()<2, that means if this node has maximally one child. If it has a child, this will be connected in its parent's position. The balance value is set to 0, if the removal was successful.
Specified by:
remove in interface TreeItem
Returns:
true, if the removal was allowed and successful

clearConnections

public boolean clearConnections()
Clears all connections starting and ending at this TreeItem. Thus the connections will not be removed correctly. In difference to remove() there will be only one request for permission to the Owner! The Owner himself will not be changed. This TreeItem's balance value will be cleared as well.
Specified by:
clearConnections in interface TreeItem
Returns:
true, if successful

key

public java.lang.Object key()
Returns the stored key of this object.
Specified by:
key in interface KeyValueHolder
Returns:
the key

setKey

public boolean setKey(java.lang.Object key)
Sets the key of this TreeItem.
Specified by:
setKey in interface KeyValueHolder
Parameters:
key - new key
Returns:
true, if the action has been allowed and performed successfully

value

public java.lang.Object value()
Returns the stored value.
Specified by:
value in interface KeyValueHolder
Returns:
the value of this TreeItem

setValue

public boolean setValue(java.lang.Object object)
Stores the object object into this node.
Specified by:
setValue in interface KeyValueHolder
Parameters:
object - object to become the new value.
Returns:
true, if the action has been allowed and performed successfully