ARoad0.gBase
Class NameTreeImpl

java.lang.Object
  extended by ARoad0.gBase.NameTreeImpl
All Implemented Interfaces:
ImmutableNameTree, java.io.Serializable, java.lang.Cloneable
Direct Known Subclasses:
NameISTreeImpl

public class NameTreeImpl
extends java.lang.Object
implements ImmutableNameTree, java.io.Serializable

This class is responsible for managing a fast-methods tree of ImmutableNames. They are not designed to be displayed by the Gui1.CommonPropertyEditor subclasses, but by trees in dedicated Gui1 internal frames. The nodes are ImmutableNames, without any constraint between a node name and its parent node name. The node name may include the parent name or not. However, the current use of this class is to enforce the parent name including. The links between nodes are parent-child relations.

This class reuses the names of the relevant methods in javax.swing.tree.DefaultTreeModel. There is always a non-null name as root. There is no sorting in the children list of a node. A node name cannot be two times in the nametree.

This class is used by the IS trees. It is possible to get new subtrees, that is an independant nametree with a copy of all the indirect children. The NameTree manages mainly nodes and areas. An area is defined as a group of nametree-connected or nametree-unconnected nodes in the nametree, with a specific area name. Areas are used to define virtual structures like a composite ACS which contains several pieces of software running on different servers, and defined in the nametree as classical nodes. The area name cannot be a node name, and areas are put by convention under the nametreee root. Areas may be included in areas, but the nametree does not manage this relation. The visible space (see NameISTree) of an area node always includes this area. Most of the methods are applicable both to nodes and areas, and the exceptions are documented.

A node may have an immutable type. 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. The visible space (see NameISTree) of a node having a hub parent always includes all the children of its parent.

The data structure is optimized for searchings from the root, with no more than 20 nodes in any level. This class does not fire property changes.

See Also:
Serialized Form

Field Summary
static NameTreeImpl EMPTY_INSTANCE
          A reusable empty instance for initialization, to avoid the use of 'new' for temporary values.
protected static int INCREMENT_CAPACITY
           
protected static int INITIAL_CAPACITY
           
protected  java.util.ArrayList[] l_NodeDescriptors_
          array of lists where the index is the level.
protected  java.util.HashMap<ImmutableName,java.util.List<java.lang.String>> m_Areas_
          hashmap of areas: key: area_name, which may be a node name value: String node type at the index 0, and then node names of items in the area
protected  java.util.HashMap<ImmutableName,java.lang.Integer> m_Levels_
          hashmap of node levels: key: node_name value: node level in l_NodeDescriptors_ so, the key set gives all the node names.
protected static int PRIME
           
static java.io.ObjectStreamField[] serialPersistentFields
          standardized variable for the JDK 2 serialization
protected static long serialVersionUID
          arraylists array, one array per level for the root: root_name, node_type, is_hub, nb_of_children, null for each level, arraylist of Object[5] one Object[5] for each node: 0: node name (it is the key), 1: node type, 2: is_hub, 3: nb_of_children (at the lower level), 4: parent name (at the upper level) hashmap of nodes from levels: key: node_name value: node level index of a child: get through a search in the right level vector hashmap of areas: key: area_name value: area nodes list
 
Constructor Summary
NameTreeImpl()
          The default constructor.
NameTreeImpl(ImmutableName _root_name, java.lang.String _node_type, boolean _is_hub)
          Constructor.
 
Method Summary
protected  void addArea(ImmutableName _area, java.lang.String _node_type)
          Adds an empty area in the nametree, which is defined as a set of nodes in the nametree.
protected  void addChild(ImmutableName _parent, ImmutableName _child, java.lang.String _node_type, boolean _is_hub)
          Adds a child as a new node in the nametree.
protected  void addNodeToArea(ImmutableName _area, ImmutableName _node)
          Adds a node to an area in the nametree, only if the new node is a nametree node which is a direct child of an area external node.
 java.lang.Object clone()
           
 boolean equals(java.lang.Object _obj)
          This method compares the node and area lists, not the parent-child relations nor the area elements.
protected  void finalize()
          This method calls finalizeForUser().
protected  void finalizeForUser()
          This method nullify all the nameTree inner properties.
 ImmutableName getChild(ImmutableName _parent, int _index)
          Gets one of the children in the nametree
 int getChildCount(ImmutableName _parent)
          Gets 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)
          Gets the current index of a child in its parent array in the nametree.
 java.util.List<ImmutableName> getL_AllChildren(ImmutableName _parent)
          Gets all the direct and indirect children of a node or area in the nametree.
 java.util.Set<ImmutableName> getL_AreaNames()
          Gets the set of all the nametree area names, if any.
 java.util.List<ImmutableName> getL_AreasOfNode(ImmutableName _name)
          Gets the areas of the nametree the node belongs to.
 java.util.List<ImmutableName> getL_DirectChildren(ImmutableName _parent)
          Gets all the direct children of a node or area in the nametree.
 java.util.List<ImmutableName> getL_NodesOfArea(ImmutableName _name)
          Gets the nodes belonging to an area of the nametree.
 int getLevel(ImmutableName _node)
          Gets the level of a node in the nametree.
 java.util.Map getM_AreaNodes()
          Gets all the areas of this nametree, with their node names.
private  java.lang.Object[] getNodeArray(ImmutableName _node)
          Gets the internal description of a node in the nametree.
 ImmutableName getParent(ImmutableName _child)
          Gets the parent of a nametree node or area.
 ImmutableName getRoot()
          Gets the root of the nametree
 long getSerialVersionUID()
           
 ImmutableNameTree getSubTree(ImmutableName _root)
          Gets an independant subtree from the nametree, with all the indirect children.
 javax.swing.tree.TreePath getTreePath(ImmutableName _startingNode, ImmutableName _endingNode)
          Gets 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 _name)
          Gets the type of the node or the area.
 int hashCode()
           
 boolean isArea(ImmutableName _name)
          Tests a name as area of the nametree.
 boolean isEmpty()
           
 boolean isHubNode(ImmutableName _node)
          Tests if a node of the nametree is set as a 'hub' for its children.
 boolean isLeaf(ImmutableName _node)
          Tests if a node is a leaf of the nametree, in reading its proper children count.
 boolean isNode(ImmutableName _name)
          Tests a name as node of the nametree, including the root.
 int nbOfLevels()
          The returned value is at least '1'.
 int nbOfNodesAndAreas()
           
 java.util.Set<ImmutableName> nodes()
          Gets the set of all the nametree nodes, including the root and excluding the areas.
protected  void removeArea(ImmutableName _area)
          Removes an area in the nametree.
protected  void removeLeaf(ImmutableName _node)
          Remove the internal data for a leaf in the nametree, with an update of the parent, the nametree internal data, the areas, but no removing of the node children.
protected  int removeNodeAndSubTree(ImmutableName _node)
          Removes a node from the nametree (excepting the root), and removes all the subtree which may be associated to the node.
protected  void removeNodeToArea(ImmutableName _area, ImmutableName _node)
          Removes a node in an area in the nametree.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

serialVersionUID

protected static final long serialVersionUID
arraylists array, one array per level for the root: root_name, node_type, is_hub, nb_of_children, null for each level, arraylist of Object[5] one Object[5] for each node: 0: node name (it is the key), 1: node type, 2: is_hub, 3: nb_of_children (at the lower level), 4: parent name (at the upper level) hashmap of nodes from levels: key: node_name value: node level index of a child: get through a search in the right level vector hashmap of areas: key: area_name value: area nodes list

See Also:
Constant Field Values

INITIAL_CAPACITY

protected static final int INITIAL_CAPACITY
See Also:
Constant Field Values

INCREMENT_CAPACITY

protected static final int INCREMENT_CAPACITY
See Also:
Constant Field Values

PRIME

protected static final int PRIME
See Also:
Constant Field Values

l_NodeDescriptors_

protected java.util.ArrayList[] l_NodeDescriptors_
array of lists where the index is the level. in each list, the value is an an array Object[5] for each node description: 0: node name (it is the key), 1: node type, 2: is_hub, 3: nb_of_children, 4: parent name the nametree root is at the index 0, as a single item in the list


m_Levels_

protected java.util.HashMap<ImmutableName,java.lang.Integer> m_Levels_
hashmap of node levels: key: node_name value: node level in l_NodeDescriptors_ so, the key set gives all the node names.


m_Areas_

protected java.util.HashMap<ImmutableName,java.util.List<java.lang.String>> m_Areas_
hashmap of areas: key: area_name, which may be a node name value: String node type at the index 0, and then node names of items in the area


EMPTY_INSTANCE

public static final NameTreeImpl EMPTY_INSTANCE
A reusable empty instance for initialization, to avoid the use of 'new' for temporary values. Caution: never change the state of the returned instance.


serialPersistentFields

public static final java.io.ObjectStreamField[] serialPersistentFields
standardized variable for the JDK 2 serialization

Constructor Detail

NameTreeImpl

public NameTreeImpl()
The default constructor.


NameTreeImpl

public NameTreeImpl(ImmutableName _root_name,
                    java.lang.String _node_type,
                    boolean _is_hub)
             throws CreateError
Constructor. The returned instance is empty if _root_name is null or empty.

Parameters:
_root_name - is the name of the nametree root. Not null.
_node_type - is a type for the root node. May be null.
_is_hub - is true if the root is a node hub, which means that any direct child of this node may have exchanges with any other direct child, if the rights allow them.
Throws:
CreateError - if _root_name is null or empty.
Method Detail

isEmpty

public boolean isEmpty()
Specified by:
isEmpty in interface ImmutableNameTree
Returns:
true if the nametree has null properties, or has only a root as node.

getRoot

public final ImmutableName getRoot()
Gets the root of the nametree

Specified by:
getRoot in interface ImmutableNameTree
Returns:
the nametree root or null if finalized

getSubTree

public final ImmutableNameTree getSubTree(ImmutableName _root)
                                   throws BaseError
Gets an independant 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.

Changes on the returned nametree do not change this nametree. Caution: the subclass does not override this method, so the returned object is never an ImmutableNameISTree.

Specified by:
getSubTree in interface ImmutableNameTree
Parameters:
_root - node of the nametree which will be the returned subtree root. Never the nametree root nor an area.
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, is an area name, does not belong to the nametree, or if non-consistent data is detected.

getM_AreaNodes

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

Specified by:
getM_AreaNodes in interface ImmutableNameTree
Returns:
a Map of node Names. The key is the area name. The value is a clone of the nodes list. May be empty.

nodes

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

Specified by:
nodes in interface ImmutableNameTree
Returns:
ImmutableNames of nodes. Never null.

getL_AreaNames

public final java.util.Set<ImmutableName> getL_AreaNames()
Gets the set of all the nametree area names, if any.

Specified by:
getL_AreaNames in interface ImmutableNameTree
Returns:
ImmutableNames of area names. Never null.

nbOfNodesAndAreas

public final int nbOfNodesAndAreas()
Specified by:
nbOfNodesAndAreas in interface ImmutableNameTree
Returns:
the number of nodes in the nametree, including the root and the areas.

nbOfLevels

public final int nbOfLevels()
The returned value is at least '1'.

Specified by:
nbOfLevels in interface ImmutableNameTree
Returns:
the number of levels in the nametree, including the root and excluding the areas.

isNode

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

Specified by:
isNode in interface ImmutableNameTree
Parameters:
_name - to test
Returns:
true if _name is a nametree node

isArea

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

Specified by:
isArea in interface ImmutableNameTree
Parameters:
_name - to test
Returns:
true if _name is a nametree area

getL_NodesOfArea

public final java.util.List<ImmutableName> getL_NodesOfArea(ImmutableName _name)
Gets the nodes belonging to an area of the nametree. Faster than getAreasOfNode(). The area name cannot be a node name, and areas are put in the nametree, be convention under the root. Areas may be included in areas, but the nametree does not manage this relation. The visible space (see NameISTree) of an area node always includes this area.

Specified by:
getL_NodesOfArea in interface ImmutableNameTree
Parameters:
_name - of an area in the nametree
Returns:
list of the area node names. May be empty. Never null.

getL_AreasOfNode

public final java.util.List<ImmutableName> getL_AreasOfNode(ImmutableName _name)
Gets the areas of the nametree the node belongs to.

Specified by:
getL_AreasOfNode in interface ImmutableNameTree
Parameters:
_name - of a node of the nametree
Returns:
list of the area node names. May be empty.

getLevel

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

Specified by:
getLevel in interface ImmutableNameTree
Parameters:
_node - has to be a nametree node or area
Returns:
the level of _node in the nametree, or -1 if not in the tree

getParent

public final ImmutableName getParent(ImmutableName _child)
Gets the parent of a nametree node or area.

Specified by:
getParent in interface ImmutableNameTree
Parameters:
_child - has to be a nametree node name, or 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

public final ImmutableName getChild(ImmutableName _parent,
                                    int _index)
Gets one of the children in the nametree

Specified by:
getChild in interface ImmutableNameTree
Parameters:
_parent - is a node or area in the nametree
_index - in the parent's child array
Returns:
the copy of child at _index, or null if _parent is not a nametree node, not a parent, or if _index is not in the right values.

getChildCount

public final int getChildCount(ImmutableName _parent)
                        throws BaseError
Gets 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. Call getNodeArray().

Specified by:
getChildCount in interface ImmutableNameTree
Parameters:
_parent - is a node or an area 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

getL_DirectChildren

public final java.util.List<ImmutableName> getL_DirectChildren(ImmutableName _parent)
Gets all the direct children of a node or area in the nametree. The order of the returned childen is the tree index order. Called by getL_AllChildren().

Specified by:
getL_DirectChildren in interface ImmutableNameTree
Parameters:
_parent - is a node or area or the root 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

public final java.util.List<ImmutableName> getL_AllChildren(ImmutableName _parent)
Gets all the direct and indirect children of a node or area in the nametree. The sorting of the returned childen is the decreasing order in levels, so the direct children are the last items in the returned list. This order allows to iterate on the list for removing the nodes, with the garantee that each processed node is a leaf. Calls getL_DirectChildren(). Called by NameISTreeImpl.isParentOfAcsNode(), ISTree.createISTree().

Specified by:
getL_AllChildren in interface ImmutableNameTree
Parameters:
_parent - is a node or area 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)

getIndexInParent

public final int getIndexInParent(ImmutableName _child)
Gets the current index of a child in its parent array in the nametree. Return -1 if _child is the root, if either the child is null or without parent, or not in the nametree. Caution: the convention is to put the areas as first children under the root, before the nodes.

Specified by:
getIndexInParent in interface ImmutableNameTree
Parameters:
_child - is the node or an area we are interrested in
Returns:
the current index of the child in its level, or -1 if there is no parent

getDepthFirstIndexInNameTree

public final 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'. Calls getTreePath() and getIndexInParent().

Specified by:
getDepthFirstIndexInNameTree in interface ImmutableNameTree
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.

getType

public java.lang.String getType(ImmutableName _name)
                         throws BaseError
Gets the type of the node or the area.

Specified by:
getType in interface ImmutableNameTree
Parameters:
_name - of the node or area
Returns:
the type for the node or area. May be null.
Throws:
BaseError - if _name is null or an empty name, or does not belong to the nametree.

isHubNode

public boolean isHubNode(ImmutableName _node)
                  throws BaseError
Tests 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. The visible space (see NameISTree) of a node having a hub parent always includes all the children of its parent. An area is always a hub node.

Specified by:
isHubNode in interface ImmutableNameTree
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.

addChild

protected final void addChild(ImmutableName _parent,
                              ImmutableName _child,
                              java.lang.String _node_type,
                              boolean _is_hub)
                       throws BaseError
Adds a child as a new node in the nametree. Not to use for an area. Overridden by NameISTreeImpl.

Parameters:
_parent - is the parent node of the child in the nametree. Never null.
_child - is the unique name of the new child
_node_type - is a value of the type. May be null.
_is_hub - is true if the child is a node hub, which means that for this node, any direct child may have exchanges with any other direct child, if the rights allow them.
Throws:
BaseError - if _parent is not a node of this nametree, if _child is null, an area name, is already a nametree node, or contains a character that is not a letter

removeNodeAndSubTree

protected final int removeNodeAndSubTree(ImmutableName _node)
                                  throws BaseError
Removes a node from the nametree (excepting the root), and removes all the subtree which may be associated to the node. Does not remove an area. Removes also the node in an ImmutableNameISTree, but does not remove the NameISTree.links where the keys are not strictly the node name. Then, these specific links should be removed independantly.

Parameters:
_node - is a node of the nametree
Returns:
the number of removed nodes, including _node
Throws:
BaseError - if _node is null, or not in the nametree, or is the root

addArea

protected final void addArea(ImmutableName _area,
                             java.lang.String _node_type)
                      throws BaseError
Adds an empty area in the nametree, which is defined as a set of nodes in the nametree. These implied nodes may be in any locations.

Areas are used to define virtual structures like a composite ACS which contains several pieces of software running on different servers, and defined in the nametree as nodes. By convention, an area is put under the root of the nametree.

The area name cannot be a node name, and areas are not explicitly in the nametree. Nevertheless, they are often put graphically under the nametreee root. Areas may be included in areas, but the nametree does not manage this relation. The extended visible space (see NameISTree) of an area node is always ALL_THE_IS_SPACE.

Parameters:
_area - the area name.
_node_type - a value of the type. May be null.
Throws:
BaseError - if _area is already an area name or a node name, or if it contains a character that is not a letter

addNodeToArea

protected final void addNodeToArea(ImmutableName _area,
                                   ImmutableName _node)
                            throws BaseError
Adds a node to an area in the nametree, only if the new node is a nametree node which is a direct child of an area external node.

Parameters:
_area - is the area name
_node - of the nametree to add to the area
Throws:
BaseError - if _node is not a node name of this nametree, if _area is not an area name, if _node is not a direct child of an area external node.

removeNodeToArea

protected final void removeNodeToArea(ImmutableName _area,
                                      ImmutableName _node)
                               throws BaseError
Removes a node in an area in the nametree.

Parameters:
_area - is an area name
_node - of the nametree to remove to the area
Throws:
BaseError - if _areaName is not an area name

removeArea

protected void removeArea(ImmutableName _area)
                   throws BaseError
Removes an area in the nametree.

Parameters:
_area - is an area name
Throws:
BaseError - if _area is not an area name

getTreePath

public final javax.swing.tree.TreePath getTreePath(ImmutableName _startingNode,
                                                   ImmutableName _endingNode)
                                            throws BaseError
Gets the path of nodes between two nodes in the nametree, if one of the two nodes is an indirect child of the other one. This method is faster than getSubTree(), and calls getNodeArray().

Specified by:
getTreePath in interface ImmutableNameTree
Parameters:
_startingNode - is a nametree node. Never an area.
_endingNode - is a nametree node which is at a lower or a greater level than _startingNode. Never an area.
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.

isLeaf

public final boolean isLeaf(ImmutableName _node)
                     throws BaseError
Tests 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().

Specified by:
isLeaf in interface ImmutableNameTree
Parameters:
_node - is a node or an area 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

clone

public java.lang.Object clone()
Overrides:
clone in class java.lang.Object
Returns:
a cloned and no-backed instance of NameTree, with clone of all names.

equals

public boolean equals(java.lang.Object _obj)
This method compares the node and area lists, not the parent-child relations nor the area elements.

Specified by:
equals in interface ImmutableNameTree
Overrides:
equals in class java.lang.Object
Parameters:
_obj - is the object to compare
Returns:
true if the lists of node names and area names are equal

hashCode

public int hashCode()
Specified by:
hashCode in interface ImmutableNameTree
Overrides:
hashCode in class java.lang.Object
Returns:
the hashcode value from the root and the number of nodes.

getSerialVersionUID

public long getSerialVersionUID()
Specified by:
getSerialVersionUID in interface ImmutableNameTree
Returns:
long serial version UID for serialization of the class

finalizeForUser

protected void finalizeForUser()
This method nullify all the nameTree inner properties.


finalize

protected void finalize()
                 throws java.lang.Throwable
This method calls finalizeForUser().

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable

removeLeaf

protected void removeLeaf(ImmutableName _node)
                   throws BaseError
Remove the internal data for a leaf in the nametree, with an update of the parent, the nametree internal data, the areas, but no removing of the node children. The root cannot be removed. Overridden method in NameISTreeImpl.

Parameters:
_node - is a node of the nametree, not an area.
Throws:
BaseError - if _node is the root, or does not belong to the nametree, or is not a leaf, or if the base is not consistent.

getNodeArray

private java.lang.Object[] getNodeArray(ImmutableName _node)
                                 throws BaseError
Gets the internal description of a node in the nametree. Caution: no control on _node, which must be a nametree node, and not an area.

Parameters:
_node - is the node we are interrested in. Never an area.
Returns:
a link to the internal data array where

0: node name (it is the key), 1: node type (may be null), 2: is_hub,

3: nb_of_children, 4: parent name

Throws:
BaseError - if the node does not belong to this nametree.