org.cybergarage.xml

## Class Node

- java.lang.Object
- - org.cybergarage.xml.Node

-     public class Node
      extends Object

  Represents an XML node with name, value, attributes, and child nodes.

  This class provides a tree-like structure for representing XML documents. Each node can have a name, value, attributes, and child nodes. Nodes can be created independently or as part of an XML document tree.

  Key features:

  - Node name and value management
  - Attribute storage and retrieval
  - Parent-child node relationships
  - XML string output with proper escaping
  - User data attachment for application-specific information

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Node()` Creates a Node with empty UserData and no Parent Node.
    `Node(Node otherNode)` Creates a copy of an existing node.
    `Node(String name)` Creates a Node with specified name.
    `Node(String ns, String name)` Creates a Node with namespace and name.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addAttribute(Attribute attr)` Adds an attribute to this node.
    `void` | `addAttribute(String name, String value)` Adds an attribute with the specified name and value.
    `void` | `addNode(Node node)` Adds a child node to this node.
    `void` | `addValue(String value)` Adds a value to this node's existing value.
    `boolean` | `equals(Object o)`
    `Attribute` | `getAttribute(int index)` Gets the attribute at the specified index.
    `Attribute` | `getAttribute(String name)` Gets the attribute with the specified name.
    `int` | `getAttributeIntegerValue(String name)` Gets the integer value of an attribute with the specified name.
    `String` | `getAttributeValue(String name)` Gets the value of an attribute with the specified name.
    `String` | `getIndentLevelString(int nIndentLevel)` Inovoke `getIndentLevelString(int, String)` with `" "` as String
    `String` | `getIndentLevelString(int nIndentLevel, String space)`
    `int` | `getIndex(String name)` Gets the index of the first child node with the specified name.
    `String` | `getName()` Gets the name of this node.
    `int` | `getNAttributes()` Gets the number of attributes this node has.
    `int` | `getNNodes()` Gets the number of child nodes this node has.
    `Node` | `getNode(int index)` Gets the child node at the specified index.
    `Node` | `getNode(String name)` Gets the first child node with the specified name.
    `Node` | `getNodeEndsWith(String name)` Gets the first child node whose name ends with the specified string.
    `String` | `getNodeValue(String name)` Gets the value of the first child node with the specified name.
    `Node` | `getParentNode()` Gets the parent node of this node.
    `Node` | `getRootNode()` Gets the root node of the tree this node belongs to.
    `Object` | `getUserData()` Gets the user data associated with this node.
    `String` | `getValue()` Gets the value of this node.
    `boolean` | `hasAttributes()` Checks if this node has any attributes.
    `int` | `hashCode()`
    `boolean` | `hasNode(String name)` Checks if this node has a child node with the specified name.
    `boolean` | `hasNodes()` Checks if this node has any child nodes.
    `void` | `insertAttributeAt(Attribute attr, int index)` Inserts an attribute at the specified index.
    `void` | `insertNode(Node node, int index)` Inserts a child node at the specified index.
    `boolean` | `isName(String value)` Checks if this node's name matches the specified value.
    `void` | `output(PrintWriter ps, int indentLevel, boolean hasChildNode)` Outputs this node as XML to the specified print writer with indentation.
    `void` | `outputAttributes(PrintWriter ps)` Outputs this node's attributes to the specified print writer.
    `void` | `print()` Prints this node as XML to standard output.
    `void` | `print(boolean hasChildNode)` Prints this node as XML to standard output.
    `void` | `removeAllAttributes()` Removes all attributes from this node.
    `void` | `removeAllNodes()` Removes all child nodes from this node.
    `boolean` | `removeAttribute(Attribute attr)` Removes the specified attribute from this node.
    `boolean` | `removeAttribute(String name)` Removes the attribute with the specified name from this node.
    `boolean` | `removeNode(Node node)` Removes a child node from this node.
    `boolean` | `removeNode(String name)` Removes the first child node with the specified name.
    `boolean` | `set(Node otherNode)` Copies all properties from another node to this node.
    `void` | `setAttribute(String name, int value)` Sets an attribute value as an integer.
    `void` | `setAttribute(String name, String value)` Sets an attribute value.
    `void` | `setName(String name)` Sets the name of this node.
    `void` | `setName(String ns, String name)` Sets the namespace and name of this node.
    `void` | `setNameSpace(String ns, String value)` Sets a namespace attribute for this node.
    `void` | `setNode(String name)` Ensures a child node with the specified name exists.
    `void` | `setNode(String name, String value)` Ensures a child node with the specified name exists and sets its value.
    `void` | `setParentNode(Node node)` Sets the parent node of this node.
    `void` | `setUserData(Object data)` Sets user data for this node.
    `void` | `setValue(int value)` Sets the value of this node as an integer.
    `void` | `setValue(String value)` Sets the value of this node.
    `String` | `toString()` Gets the XML string representation of this node.
    `String` | `toString(String enc, boolean hasChildNode)` Gets the XML string representation of this node with the specified encoding.
    `String` | `toXMLString()` Gets the XML string representation with all XML characters escaped.
    `String` | `toXMLString(boolean hasChildNode)` Gets the XML string representation with all XML characters escaped.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Node

          public Node()

      Creates a Node with empty UserData and no Parent Node.

    - #### Node

          public Node(Node otherNode)

      Creates a copy of an existing node.
      Parameters:
        `otherNode` - node to copy

    - #### Node

          public Node(String name)

      Creates a Node with specified name.
      Parameters:
        `name` - name to set for the node

    - #### Node

          public Node(String ns,
                      String name)

      Creates a Node with namespace and name.
      Parameters:
        `ns` - namespace prefix
        `name` - name to set for the node

  - ### Method Detail

    - #### addAttribute

          public void addAttribute(Attribute attr)

      Adds an attribute to this node.
      Parameters:
        `attr` - the attribute to add

    - #### addAttribute

          public void addAttribute(String name,
                                   String value)

      Adds an attribute with the specified name and value.
      Parameters:
        `name` - the attribute name
        `value` - the attribute value

    - #### addNode

          public void addNode(Node node)

      Adds a child node to this node.
      Parameters:
        `node` - child node to add

    - #### addValue

          public void addValue(String value)

      Adds a value to this node's existing value.
      Parameters:
        `value` - value to append to existing value

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### getAttribute

          public Attribute getAttribute(int index)

      Gets the attribute at the specified index.
      Parameters:
        `index` - the index of the attribute to retrieve
      Returns:
        the attribute at the specified index

    - #### getAttribute

          public Attribute getAttribute(String name)

      Gets the attribute with the specified name.
      Parameters:
        `name` - the name of the attribute to retrieve
      Returns:
        the attribute with the specified name, or null if not found

    - #### getAttributeIntegerValue

          public int getAttributeIntegerValue(String name)

      Gets the integer value of an attribute with the specified name.
      Parameters:
        `name` - the attribute name
      Returns:
        the attribute value as integer, or 0 if not found or invalid

    - #### getAttributeValue

          public String getAttributeValue(String name)

      Gets the value of an attribute with the specified name.
      Parameters:
        `name` - the attribute name
      Returns:
        the attribute value, or empty string if not found

    - #### getIndentLevelString

          public String getIndentLevelString(int nIndentLevel)

      Inovoke `getIndentLevelString(int, String)` with `" "` as String
      See Also:
        `getIndentLevelString(int, String)`

    - #### getIndentLevelString

          public String getIndentLevelString(int nIndentLevel,
                                             String space)

      Parameters:
        `nIndentLevel` - the level of indentation to produce
        `space` - the String to use for the intendation
      Returns:
        an indentation String

    - #### getIndex

          public int getIndex(String name)

      Gets the index of the first child node with the specified name.
      Parameters:
        `name` - the name of the child node to find
      Returns:
        the index of the child node, or -1 if not found

    - #### getName

          public String getName()

      Gets the name of this node.
      Returns:
        name of the node

    - #### getNAttributes

          public int getNAttributes()

      Gets the number of attributes this node has.
      Returns:
        the number of attributes

    - #### getNNodes

          public int getNNodes()

      Gets the number of child nodes this node has.
      Returns:
        the number of child nodes

    - #### getNode

          public Node getNode(int index)

      Gets the child node at the specified index.
      Parameters:
        `index` - the index of the child node to retrieve
      Returns:
        the child node at the specified index

    - #### getNode

          public Node getNode(String name)

      Gets the first child node with the specified name.
      Parameters:
        `name` - the name of the child node to retrieve
      Returns:
        the child node with the specified name, or null if not found

    - #### getNodeEndsWith

          public Node getNodeEndsWith(String name)

      Gets the first child node whose name ends with the specified string.
      Parameters:
        `name` - the suffix to match
      Returns:
        the first child node with name ending with the specified string, or null if not found

    - #### getNodeValue

          public String getNodeValue(String name)

      Gets the value of the first child node with the specified name.
      Parameters:
        `name` - the name of the child node
      Returns:
        the value of the child node, or empty string if not found

    - #### getParentNode

          public Node getParentNode()

      Gets the parent node of this node.
      Returns:
        the parent node, or null if this node has no parent

    - #### getRootNode

          public Node getRootNode()

      Gets the root node of the tree this node belongs to.
      Returns:
        the root node, or this node if it has no parent

    - #### getUserData

          public Object getUserData()

      Gets the user data associated with this node.
      Returns:
        user data object, or null if not set

    - #### getValue

          public String getValue()

      Gets the value of this node.
      Returns:
        value of the node

    - #### hasAttributes

          public boolean hasAttributes()

      Checks if this node has any attributes.
      Returns:
        true if this node has attributes, false otherwise

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### hasNode

          public boolean hasNode(String name)

      Checks if this node has a child node with the specified name.
      Parameters:
        `name` - the name of the child node to check for
      Returns:
        true if a child node with the specified name exists, false otherwise

    - #### hasNodes

          public boolean hasNodes()

      Checks if this node has any child nodes.
      Returns:
        true if this node has child nodes, false otherwise

    - #### insertAttributeAt

          public void insertAttributeAt(Attribute attr,
                                        int index)

      Inserts an attribute at the specified index.
      Parameters:
        `attr` - the attribute to insert
        `index` - the index at which to insert the attribute

    - #### insertNode

          public void insertNode(Node node,
                                 int index)

      Inserts a child node at the specified index.
      Parameters:
        `node` - the child node to insert
        `index` - the index at which to insert the node

    - #### isName

          public boolean isName(String value)

      Checks if this node's name matches the specified value.
      Parameters:
        `value` - the name to compare against
      Returns:
        true if the names match, false otherwise

    - #### output

          public void output(PrintWriter ps,
                             int indentLevel,
                             boolean hasChildNode)

      Outputs this node as XML to the specified print writer with indentation.
      Parameters:
        `ps` - the print writer to output to
        `indentLevel` - the indentation level for this node
        `hasChildNode` - whether to treat this node as having child nodes

    - #### outputAttributes

          public void outputAttributes(PrintWriter ps)

      Outputs this node's attributes to the specified print writer.
      Parameters:
        `ps` - the print writer to output to

    - #### print

          public void print()

      Prints this node as XML to standard output.

    - #### print

          public void print(boolean hasChildNode)

      Prints this node as XML to standard output.
      Parameters:
        `hasChildNode` - whether to treat this node as having child nodes

    - #### removeAllAttributes

          public void removeAllAttributes()

      Removes all attributes from this node.

    - #### removeAllNodes

          public void removeAllNodes()

      Removes all child nodes from this node.

    - #### removeAttribute

          public boolean removeAttribute(Attribute attr)

      Removes the specified attribute from this node.
      Parameters:
        `attr` - the attribute to remove
      Returns:
        true if the attribute was removed, false if not found

    - #### removeAttribute

          public boolean removeAttribute(String name)

      Removes the attribute with the specified name from this node.
      Parameters:
        `name` - the name of the attribute to remove
      Returns:
        true if the attribute was removed, false if not found

    - #### removeNode

          public boolean removeNode(Node node)

      Removes a child node from this node.
      Parameters:
        `node` - child node to remove
      Returns:
        true if node was removed, false if not found

    - #### removeNode

          public boolean removeNode(String name)

      Removes the first child node with the specified name.
      Parameters:
        `name` - the name of the child node to remove
      Returns:
        true if the node was removed, false if not found

    - #### set

          public boolean set(Node otherNode)

      Copies all properties from another node to this node. This includes name, value, attributes, and child nodes.
      Parameters:
        `otherNode` - the node to copy from
      Returns:
        true if the copy was successful, false if otherNode is null

    - #### setAttribute

          public void setAttribute(String name,
                                   int value)

      Sets an attribute value as an integer. If the attribute already exists, its value is updated. If it doesn't exist, a new attribute is created.
      Parameters:
        `name` - the attribute name
        `value` - the integer attribute value

    - #### setAttribute

          public void setAttribute(String name,
                                   String value)

      Sets an attribute value. If the attribute already exists, its value is updated. If it doesn't exist, a new attribute is created.
      Parameters:
        `name` - the attribute name
        `value` - the attribute value

    - #### setName

          public void setName(String name)

      Sets the name of this node.
      Parameters:
        `name` - name to set for the node

    - #### setName

          public void setName(String ns,
                              String name)

      Sets the namespace and name of this node.
      Parameters:
        `ns` - namespace prefix
        `name` - name to set for the node

    - #### setNameSpace

          public void setNameSpace(String ns,
                                   String value)

      Sets a namespace attribute for this node.
      Parameters:
        `ns` - the namespace prefix
        `value` - the namespace URI

    - #### setNode

          public void setNode(String name)

      Ensures a child node with the specified name exists. If a child node with the name already exists, this method does nothing. If not, a new child node with the specified name is created and added.
      Parameters:
        `name` - the name of the child node to ensure exists

    - #### setNode

          public void setNode(String name,
                              String value)

      Ensures a child node with the specified name exists and sets its value. If a child node with the name already exists, its value is updated. If not, a new child node with the specified name and value is created and added.
      Parameters:
        `name` - the name of the child node
        `value` - the value to set for the child node

    - #### setParentNode

          public void setParentNode(Node node)

      Sets the parent node of this node.
      Parameters:
        `node` - the parent node, or null if this node has no parent

    - #### setUserData

          public void setUserData(Object data)

      Sets user data for this node.
      Parameters:
        `data` - user data object to associate with this node

    - #### setValue

          public void setValue(int value)

      Sets the value of this node as an integer.
      Parameters:
        `value` - integer value to set for the node

    - #### setValue

          public void setValue(String value)

      Sets the value of this node.
      Parameters:
        `value` - value to set for the node

    - #### toString

          public String toString()

      Gets the XML string representation of this node.
      Overrides:
        `toString` in class `Object`
      Returns:
        XML string using UTF-8 encoding

    - #### toString

          public String toString(String enc,
                                 boolean hasChildNode)

      Gets the XML string representation of this node with the specified encoding.
      Parameters:
        `enc` - the character encoding to use, or null for default
        `hasChildNode` - whether to treat this node as having child nodes
      Returns:
        the XML string representation

    - #### toXMLString

          public String toXMLString()

      Gets the XML string representation with all XML characters escaped. This is useful for embedding XML within XML.
      Returns:
        the escaped XML string

    - #### toXMLString

          public String toXMLString(boolean hasChildNode)

      Gets the XML string representation with all XML characters escaped. This is useful for embedding XML within XML.
      Parameters:
        `hasChildNode` - whether to treat this node as having child nodes
      Returns:
        the escaped XML string