ARoad0.gBaseInterface
Interface ImmutableNameTree

All Superinterfaces:
java.lang.Cloneable
All Known Subinterfaces:
ImmutableNameISTree
All Known Implementing Classes:
NameISTreeImpl, NameTreeImpl

public interface ImmutableNameTree
extends java.lang.Cloneable

This class is responsible for managing a tree of ImmutableNames for all the base objects. The nodes are ImmutableNames, but there is no constraint between a node name and its parent node name (that is, the node name may integer the parent name or not). The links between nodes are parent-child relations.

This interface uses the relevant methods of javax.swing.tree.DefaultTreeModel. There is always a non-null name as root. There is no order in the children list of a node. An name cannot be a node twice in the same nametree.

This class is used by IS, component and ACS trees. It is possible to get subtrees, that is a new nametree with all the indirect children. It is also possible to get areas. Area is defined as a group of connected nodes in the nametree, with a single root, which is used for mapping components to a virtual structure like an IS domain.


Method Summary
 boolean equals(java.lang.Object _obj)
          This method compare the node lists, not the parent-child relations.
 ImmutableName getChild(ImmutableName _parent, int _index)
          Get one of the children in the nametree
 int getChildCount(ImmutableName _parent)
          Get the number of children for a node in the nametree, in reading its proper children count.
 int getDepthFirstIndexInNameTree(ImmutableName _child)
          Gets the current index of a child in its nametree, as the child appears in the IS structure o the GUI, following a depth-first order.
 int getIndexInParent(ImmutableName _child)
          Returns the current index of a child in its parent array in the nametree.
 java.util.List<ImmutableName> getL_AllChildren(ImmutableName _parent)
          Get all the direct and indirect children of a node in the nametree.
 java.util.Set<ImmutableName> getL_AreaNames()
          Get the set of all the nametree areas, if any.
 java.util.List<ImmutableName> getL_AreasOfNode(ImmutableName _name)
          Get the areas of the nametree, the node belongs to.
 java.util.List<ImmutableName> getL_DirectChildren(ImmutableName _parent)
          Get all the direct children of a node in the nametree.
 java.util.List<ImmutableName> getL_NodesOfArea(ImmutableName _name)
          Get the nodes belonging to an area of the nametree.
 int getLevel(ImmutableName _node)
          Get the level of a node in the nametree.
 java.util.Map getM_AreaNodes()
          Get all the areas of this nametree, with their node names.
 ImmutableName getParent(ImmutableName _child)
          Get the parent of a nametree node.
 ImmutableName getRoot()
          Get the root of the nametree
 long getSerialVersionUID()
           
 ImmutableNameTree getSubTree(ImmutableName _root)
          Get a subtree from the nametree, with all the indirect children.
 javax.swing.tree.TreePath getTreePath(ImmutableName _startingNode, ImmutableName _endingNode)
          Get the path of nodes between two nodes in the nametree, if one of the two nodes is an indirect child of the other one.
 java.lang.String getType(ImmutableName _node)
          Get the type of the node.
 int hashCode()
           
 boolean isArea(ImmutableName _name)
          Test a name as area of the nametree.
 boolean isEmpty()
           
 boolean isHubNode(ImmutableName _node)
          Test if a node of the nametree is set as a 'hub' for its children.
 boolean isLeaf(ImmutableName _node)
          Test if a node is a leaf of the nametree, in reading its proper children count.
 boolean isNode(ImmutableName _name)
          Test a name as node of the nametree, including the root.
 int nbOfLevels()
           
 int nbOfNodesAndAreas()
           
 java.util.Set<ImmutableName> nodes()
          Get the set of all the nametree nodes, including the root and excluding the areas.
 

Method Detail

isEmpty

boolean isEmpty()
Returns:
true if the nametree has null properties, or has only a root as node.

getRoot

ImmutableName getRoot()
Get the root of the nametree

Returns:
the nametree root

getSubTree

ImmutableNameTree getSubTree(ImmutableName _root)
                             throws BaseError
Get a subtree from the nametree, with all the indirect children. This method is a good test of the nametree code bugs, and throws an Error when unconsistent data is detected. Caution: change on the returned nametree does not change this nametree.

Parameters:
_root - this non-null node of the nametree is the subtree root, which is not the nametree root.
Returns:
a deep copy of the subtree where _root is the new tree root.
Throws:
BaseError - if the root is the nametree root, null, empty, does not belong to the nametree, or if non-consistent data is detected.

getTreePath

javax.swing.tree.TreePath getTreePath(ImmutableName _startingNode,
                                      ImmutableName _endingNode)
                                      throws BaseError
Get the path of nodes between two nodes in the nametree, if one of the two nodes is an indirect child of the other one.

Parameters:
_startingNode - is a nametree node
_endingNode - is a nametree node which is at a lower or a greater level than _startingNode
Returns:
the TreePath of node names, including the two arguments, and the first one (index 0) is the node in the lower nametree level. Null if there is no tree path. Contains only _startingNode if the two nodes are equals.
Throws:
BaseError - if one of the two arguments does not belong to the nametree, or if the nametree data is not consistent.

nodes

java.util.Set<ImmutableName> nodes()
Get the set of all the nametree nodes, including the root and excluding the areas.

Returns:
node names. Never null.

getL_AreaNames

java.util.Set<ImmutableName> getL_AreaNames()
Get the set of all the nametree areas, if any.

Returns:
area names. Never null.

getM_AreaNodes

java.util.Map getM_AreaNodes()
Get all the areas of this nametree, with their node names.

Returns:
a Map of node Names. The key is the area name. May be empty.

nbOfNodesAndAreas

int nbOfNodesAndAreas()
Returns:
the number of nodes in the nametree, including the root and excluding the areas.

nbOfLevels

int nbOfLevels()
Returns:
the number of levels in the nametree, including the root.

isNode

boolean isNode(ImmutableName _name)
Test a name as node of the nametree, including the root.

Parameters:
_name - to test
Returns:
true if _name is a nametree node

isArea

boolean isArea(ImmutableName _name)
Test a name as area of the nametree.

Parameters:
_name - to test
Returns:
true if _name is a nametree area

getL_NodesOfArea

java.util.List<ImmutableName> getL_NodesOfArea(ImmutableName _name)
Get the nodes belonging to an area of the nametree.

Parameters:
_name - of an area of the nametree
Returns:
list for the area node names. May be empty.

getL_AreasOfNode

java.util.List<ImmutableName> getL_AreasOfNode(ImmutableName _name)
Get the areas of the nametree, the node belongs to.

Parameters:
_name - of a node of the nametree
Returns:
a deep copy of the list for the node areas. May be empty.

getLevel

int getLevel(ImmutableName _node)
Get the level of a node in the nametree. The root is at the level 0.

Parameters:
_node - has to be a nametree node
Returns:
the level of _node in the nametree, or -1 if not in the tree

getParent

ImmutableName getParent(ImmutableName _child)
Get the parent of a nametree node.

Parameters:
_child - has to be a nametree node name, not an area name
Returns:
the copy of parent in the nametree, or null if _child is null, empty, an area name, the root or it is not a nametree node

getChild

ImmutableName getChild(ImmutableName _parent,
                       int _index)
Get one of the children in the nametree

Parameters:
_parent - is a parent in the nametree
_index - in the parent's child array
Returns:
the child of _parent at _index, or null if _parent is not a nametree node, not a parent, or if _index is negative

getL_DirectChildren

java.util.List<ImmutableName> getL_DirectChildren(ImmutableName _parent)
Get all the direct children of a node in the nametree. The order of the returned childen is the tree index order.

Parameters:
_parent - is a node in the nametree
Returns:
clones of ImmutableNames. Null if _parent is not a node of the nametree. Empty if _parent is a leaf.
See Also:
getL_AllChildren(ARoad0.gBaseInterface.ImmutableName)

getL_AllChildren

java.util.List<ImmutableName> getL_AllChildren(ImmutableName _parent)
Get all the direct and indirect children of a node in the nametree. The order of the returned childen is the increasing order in levels, so the direct children are the first items in the returned list.

Parameters:
_parent - is a node in the nametree
Returns:
clones of ImmutableNames. Null if _parent is not a node of the nametree. Empty if _parent is a leaf.
See Also:
getL_DirectChildren(ARoad0.gBaseInterface.ImmutableName)

getType

java.lang.String getType(ImmutableName _node)
                         throws BaseError
Get the type of the node.

Returns:
the node type.
Throws:
BaseError - if _node is null or an empty name, or does not belong to the nametree.

isHubNode

boolean isHubNode(ImmutableName _node)
                  throws BaseError
Test if a node of the nametree is set as a 'hub' for its children. A node may be a hub, which means that for this node, any direct child may have exchanges with any other direct child. For a non-hub node, exchanges between its children are not allowed. This concept is extended in NameLinkTree by the visible space property.

Returns:
true if the node is a hub.
Throws:
BaseError - if _node is null or an empty name, or does not belong to the nametree.

getChildCount

int getChildCount(ImmutableName _parent)
                  throws BaseError
Get the number of children for a node in the nametree, in reading its proper children count. Generally speaking, this method is faster than getChildren() which searches children in the level above the parent level.

Parameters:
_parent - is a node in the nametree
Returns:
the number of children for the parent
Throws:
BaseError - if the parent is null or does not belong to the nametree

isLeaf

boolean isLeaf(ImmutableName _node)
               throws BaseError
Test if a node is a leaf of the nametree, in reading its proper children count. Generally speaking, this method is faster than getChildren() which searches children in the level above the parent level. Call getChildCount().

Parameters:
_node - is a node to test
Returns:
true if _node is a leaf, without any child
Throws:
BaseError - if the node is null or does not belong to the nametree

getIndexInParent

int getIndexInParent(ImmutableName _child)
Returns the current index of a child in its parent array in the nametree. Returns -1 if _child is the root, if either the child is null or without parent, or not in the nametree.

Parameters:
_child - is the node we are interested in
Returns:
the current index of the child in its level

getDepthFirstIndexInNameTree

int getDepthFirstIndexInNameTree(ImmutableName _child)
                                 throws BaseError
Gets the current index of a child in its nametree, as the child appears in the IS structure o the GUI, following a depth-first order. For the level n, the index contains the value (getIndexInParent() + 1) for the ancestor of this level n. The number of digits into the index is always the number of levels in the nametree. '0' means there is no ancestor at this level. The nametree root has the index '10...0'. For instance, a typical suite of indexes this method should return, in a sequence of calls for all the nodes of a nametree having 4 levels, is: '1000', '1100', '1110', '1120', '1121', '1122', '1200', '1210', '1211'. This is the suite for a nametree having under the root '1000', two nodes with the indexes '1100' and '1200', 4 children and indirect children under '1100', and 2 children and indirect children under '1200'.

Parameters:
_child - is the node or an area of the nametree
Returns:
the current index of the child in the nametree, for traversing the tree in a depth-first order.
Throws:
BaseError - if the arguments does not belong to the nametree, or if the nametree data is not consistent.

equals

boolean equals(java.lang.Object _obj)
This method compare the node lists, not the parent-child relations.

Overrides:
equals in class java.lang.Object
Parameters:
_obj - is the object to compare
Returns:
true if the list of nodes is equal

hashCode

int hashCode()
Overrides:
hashCode in class java.lang.Object
Returns:
the hashcode value for the root.

getSerialVersionUID

long getSerialVersionUID()
Returns:
long serial version UID for serialization of the class