org.eclipse.core.internal.dtree
Class AbstractDataTree

java.lang.Object
  org.eclipse.core.internal.dtree.AbstractDataTree

Direct Known Subclasses:

DataTree, DeltaDataTree

public abstract class AbstractDataTree
extends java.lang.Object

Data trees can be viewed as generic multi-leaf trees. The tree points to a single rootNode, and each node can contain an arbitrary number of children.

Internally, data trees can be either complete trees (DataTree class), or delta trees (DeltaDataTree class). A DataTree is a stand-alone tree that contains all its own data. A DeltaDataTree only stores the differences between itself and its parent tree. This sparse representation allows the API user to retain chains of delta trees that represent incremental changes to a system. Using the delta trees, the user can undo changes to a tree by going up to the parent tree.

Both representations of the tree support the same API, so the user of a tree never needs to know if they're dealing with a complete tree or a chain of deltas. Delta trees support an extended API of delta operations. See the DeltaDataTree class for details.

See Also:

DataTree, DeltaDataTree

Constructor Summary

AbstractDataTree()
Creates a new empty tree

Method Summary

abstract AbstractDataTreeNode	copyCompleteSubtree(org.eclipse.core.runtime.IPath key) Returns a copy of the node subtree rooted at the given key.
abstract void	createChild(org.eclipse.core.runtime.IPath parentKey, java.lang.String localName) Creates a new child in the tree.
abstract void	createChild(org.eclipse.core.runtime.IPath parentKey, java.lang.String localName, java.lang.Object object) Creates a new child in the tree.
abstract void	createSubtree(org.eclipse.core.runtime.IPath key, AbstractDataTreeNode subtree) Creates or replaces a subtree in the tree.
abstract void	deleteChild(org.eclipse.core.runtime.IPath parentKey, java.lang.String localName) Deletes a child from the tree.
abstract void	empty() Initializes the receiver so that it is a complete, empty tree.
org.eclipse.core.runtime.IPath	getChild(org.eclipse.core.runtime.IPath parentKey, int index) Returns the key of a node in the tree.
int	getChildCount(org.eclipse.core.runtime.IPath parentKey) Returns the number of children of a node
org.eclipse.core.runtime.IPath[]	getChildren(org.eclipse.core.runtime.IPath parentKey) Returns the keys of all children of a node.
abstract java.lang.Object	getData(org.eclipse.core.runtime.IPath key) Returns the data of a node.
java.lang.String	getNameOfChild(org.eclipse.core.runtime.IPath parentKey, int index) Returns the local name of a node in the tree
abstract java.lang.String[]	getNamesOfChildren(org.eclipse.core.runtime.IPath parentKey) Returns the local names for the children of a node
void	immutable() Makes the tree immutable
abstract boolean	includes(org.eclipse.core.runtime.IPath key) Returns true if the receiver includes a node with the given key, false otherwise.
boolean	isImmutable() Returns true if the tree is immutable, and false otherwise.
abstract DataTreeLookup	lookup(org.eclipse.core.runtime.IPath key) Returns an object containing: - a flag indicating whether the specified node was found - the data for the node, if it was found
org.eclipse.core.runtime.IPath	rootKey() Returns the key of the root node.
abstract void	setData(org.eclipse.core.runtime.IPath key, java.lang.Object data) Sets the data of a node.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractDataTree

public AbstractDataTree()

Creates a new empty tree

Method Detail

copyCompleteSubtree

public abstract AbstractDataTreeNode copyCompleteSubtree(org.eclipse.core.runtime.IPath key)

Returns a copy of the node subtree rooted at the given key.

createChild

public abstract void createChild(org.eclipse.core.runtime.IPath parentKey,
                                 java.lang.String localName)

Creates a new child in the tree. If a child with such a name exists, it is replaced with the new child

Parameters:

parentKey - key of parent for new child.

localName - name for new child.

Throws:

ObjectNotFoundException - parentKey does not exist in the receiver

java.lang.RuntimeException - receiver is immutable

createChild

public abstract void createChild(org.eclipse.core.runtime.IPath parentKey,
                                 java.lang.String localName,
                                 java.lang.Object object)

Creates a new child in the tree. If a child with such a name exists, it is replaced with the new child

Parameters:

parentKey - key of parent for new child.

localName - name for new child.

object - the data for the new child

Throws:

ObjectNotFoundException - parentKey does not exist in the receiver

java.lang.RuntimeException - receiver is immutable

createSubtree

public abstract void createSubtree(org.eclipse.core.runtime.IPath key,
                                   AbstractDataTreeNode subtree)

Creates or replaces a subtree in the tree. The parent node must exist.

Parameters:

key - key of parent of subtree to create/replace

subtree - new subtree to add to tree

Throws:

java.lang.RuntimeException - receiver is immutable

deleteChild

public abstract void deleteChild(org.eclipse.core.runtime.IPath parentKey,
                                 java.lang.String localName)

Deletes a child from the tree.

Note: this method requires both parentKey and localName, making it impossible to delete the root node.

Parameters:

parentKey - parent of node to delete.

localName - name of node to delete.

Throws:

ObjectNotFoundException - a child of parentKey with name localName does not exist in the receiver

java.lang.RuntimeException - receiver is immutable

empty

public abstract void empty()

Initializes the receiver so that it is a complete, empty tree. The result does not represent a delta on another tree. An empty tree is defined to have a root node with null data and no children.

getChild

public org.eclipse.core.runtime.IPath getChild(org.eclipse.core.runtime.IPath parentKey,
                                               int index)

Returns the key of a node in the tree.

Parameters:

parentKey - parent of child to retrieve.

index - index of the child to retrieve in its parent.

Throws:

ObjectNotFoundException - parentKey does not exist in the receiver

java.lang.ArrayIndexOutOfBoundsException - if no child with the given index (runtime exception)

getChildCount

public int getChildCount(org.eclipse.core.runtime.IPath parentKey)

Returns the number of children of a node

Parameters:

parentKey - key of the node for which we want to retreive the number of children

Throws:

ObjectNotFoundException - parentKey does not exist in the receiver

getChildren

public org.eclipse.core.runtime.IPath[] getChildren(org.eclipse.core.runtime.IPath parentKey)

Returns the keys of all children of a node.

Parameters:

parentKey - key of parent whose children we want to retrieve.

Throws:

ObjectNotFoundException - parentKey does not exist in the receiver

getData

public abstract java.lang.Object getData(org.eclipse.core.runtime.IPath key)

Returns the data of a node.

Parameters:

key - key of node for which we want to retrieve data.

Throws:

ObjectNotFoundException - key does not exist in the receiver

getNameOfChild

public java.lang.String getNameOfChild(org.eclipse.core.runtime.IPath parentKey,
                                       int index)

Returns the local name of a node in the tree

Parameters:

parentKey - parent of node whose name we want to retrieve

index - index of node in its parent

Throws:

ObjectNotFoundException - parentKey does not exist in the receiver

java.lang.ArrayIndexOutOfBoundsException - if no child with the given index

getNamesOfChildren

public abstract java.lang.String[] getNamesOfChildren(org.eclipse.core.runtime.IPath parentKey)

Returns the local names for the children of a node

Parameters:

parentKey - key of node whose children we want to retrieve

Throws:

ObjectNotFoundException - parentKey does not exist in the receiver

immutable

public void immutable()

Makes the tree immutable

includes

public abstract boolean includes(org.eclipse.core.runtime.IPath key)

Returns true if the receiver includes a node with the given key, false otherwise.

Parameters:

key - key of node to find

isImmutable

public boolean isImmutable()

Returns true if the tree is immutable, and false otherwise.

lookup

public abstract DataTreeLookup lookup(org.eclipse.core.runtime.IPath key)

Returns an object containing: - a flag indicating whether the specified node was found - the data for the node, if it was found

Parameters:

key - key of node for which we want to retrieve data.

rootKey

public org.eclipse.core.runtime.IPath rootKey()

Returns the key of the root node.

setData

public abstract void setData(org.eclipse.core.runtime.IPath key,
                             java.lang.Object data)

Sets the data of a node.

Parameters:

key - key of node for which to set data

data - new data value for node

Throws:

ObjectNotFoundException - the nodeKey does not exist in the receiver

java.lang.IllegalArgumentException - receiver is immutable