XMLNode (jOAI Java Documentation v3.3)

java.lang.Object
- org.dlese.dpc.xml.XMLNode

```
public class XMLNode
extends java.lang.Object
```
Creates an object wrapper for JDOM XML elements and for accessing their content. The primary purpose of this class is to provide object mapping between the JDOM tree hierarchy and the HashMap maintained by XMLRecord. Child and parent relationships in the XML element hierarchy are mirrored by the XMLNode structure.
The path strings created and maintained by this class reflect the path that would be traversed through the JDOM tree hierarchy to reach the wrapped element. Path strings are extended as nodes are added, by appending the element's name and its number of occurrence. The path strings then serve as keys to the map maintained by XMLRecord.
Here is an example path:
```
        record:0.technical:0.requirements:1.type:0.langstring:0
 
```
This path identifies the type langstring element belonging to the 2nd technical requirement of the root element record. Here is the corresponding XML:
```
        <record>
        ...
          <technical>
          ...
                <requirements>
                  <type>
                        <langstring />
                  </type>
                  ...
                </requirements>
                <requirements>
                  <type>
                        <langstring>THIS IS THE ONE</langstring>
                  </type>
                  ...
                </requirements>
          ...
          <technical>
        ...
        <record>
 
```
By knowing the path structure, a calling method may ask XMLRecord for any node anywhere in the hierarchy. The node then provides the caller with convenient access methods to the element and its attributes.
Version:

1.0 02/01/01

Author:

Dave Deniman

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.util.ArrayList`	`children` List of child nodes.
`protected org.jdom.Element`	`element` The JDOM XML element this node wraps.
`protected int`	`occurs` Identifies the nth occurence of this node in the parent's children array.
`protected XMLNode`	`parent` The parent node of this one.
`protected java.lang.String`	`path` Identifies the location in the JDOM hierarchy of the wrapped XML element.

Constructor Summary

Constructors
Constructor and Description
`XMLNode(org.jdom.Element element)` Constructor wraps a JDOM Element with a new node.
`XMLNode(org.jdom.Element element, boolean setNormalize)` Constructor wraps a JDOM Element with a new node.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addChild(XMLNode node)` Adds a child node to this one at the correct location, and sets the path.
`void`	`addComment(java.lang.String value)` Adds a comment to the element of this node.
`void`	`clear()`
`protected int`	`findPlace(XMLNode node)` Finds the place where a new node should be inserted.
`java.lang.String`	`getAttribute(java.lang.String attName)` Retrieves a named attribute from the element of this node, if the attribute exists.
`XMLNode`	`getChild(int index)` Gets the child node that lives at a specific index of this node's children array.
`java.util.List`	`getChildren()` Gets the list of children belonging to this node.
`java.lang.String`	`getComment(java.lang.String identifier)` Gets an identified comment from the element of this node, if it exists.
`java.util.List`	`getComments()` Gets all the comments belonging to the element of this node.
`org.jdom.Element`	`getElement()` Retrieves the element of this node.
`java.util.List`	`getLikeChildren(java.lang.String name)`
`java.lang.String`	`getName()` Retrieves the name of the element of this node.
`XMLNode`	`getParent()` Retrieve the node's parent node, which is null if this node wraps the root element.
`java.lang.String`	`getPath()` Returns the path which maps this node's element location in the JDOM tree hierarchy.
`java.lang.String`	`getValue()` Retrieves the textual content of the element of this node.
`boolean`	`isLeaf()` Tests whether this node wraps a leaf element, which is useful for knowing how to add content.
`boolean`	`isRoot()` Tests whether this node wraps the JDOM document root element.
`int`	`likeChildren(java.lang.String nodeName)` Searches the children nodes for an element name and returns the number found.
`boolean`	`removeComment(java.lang.String identifier)` Removes the first identified comment from the element of this node, if one exists.
`void`	`setAttribute(java.lang.String attName, java.lang.String value)` Sets the value of an attribute for the element of this node.
`void`	`setPath(java.lang.String parentPath)` Appends this node's name and number of occurrence to a path.
`void`	`setValue(java.lang.String value)` Sets the textual content of the element of this node, if it is a leaf element.
`java.lang.String`	`toString()` Retrieves the name of the element of this node.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - path
```
protected java.lang.String path
```
    Identifies the location in the JDOM hierarchy of the wrapped XML element.
  - children
```
protected java.util.ArrayList children
```
    List of child nodes.
  - occurs
```
protected int occurs
```
    Identifies the nth occurence of this node in the parent's children array. This is not the same as its index.
  - element
```
protected org.jdom.Element element
```
    The JDOM XML element this node wraps.
  - parent
```
protected XMLNode parent
```
    The parent node of this one.
- Constructor Detail
  - XMLNode
```
public XMLNode(org.jdom.Element element)
```
    Constructor wraps a JDOM Element with a new node.
    
    Parameters:
    
    element - JDOM element to be wrapped.
  - XMLNode
```
public XMLNode(org.jdom.Element element,
               boolean setNormalize)
```
    Constructor wraps a JDOM Element with a new node.
    
    Parameters:
    
    element - JDOM element to be wrapped.
- Method Detail
  - getParent
```
public XMLNode getParent()
```
    Retrieve the node's parent node, which is null if this node wraps the root element.
    
    Returns:
    
    The parent node to this node, or null.
  - clear
```
public void clear()
```
  - addChild
```
public void addChild(XMLNode node)
```
    Adds a child node to this one at the correct location, and sets the path.
    
    Parameters:
    
    node - The node to add.
  - getChild
```
public XMLNode getChild(int index)
```
    Gets the child node that lives at a specific index of this node's children array.
    NOTE: no bounds checking is done in this implementation.
    
    Parameters:
    
    index - An integer identifying the index of the node to return.
    
    Returns:
    
    The child XMLNode at the indexed location.
  - getChildren
```
public java.util.List getChildren()
```
    Gets the list of children belonging to this node.
    
    Returns:
    
    A List containing all the children of this node.
  - getLikeChildren
```
public java.util.List getLikeChildren(java.lang.String name)
```
  - likeChildren
```
public int likeChildren(java.lang.String nodeName)
```
    Searches the children nodes for an element name and returns the number found. This is useful when retrieving multiple occurring elements.
    
    Parameters:
    
    nodeName - The name to search for.
    
    Returns:
    
    The number of matching element names
  - findPlace
```
protected int findPlace(XMLNode node)
```
    Finds the place where a new node should be inserted. JDOM does not provide for inserting elements at a given location, so this helps keep track of a node's location, for constructing the key paths and for inserting like children one after the other.
    
    Parameters:
    
    node - The XMLNode to find the placement for.
    
    Returns:
    
    An integer representing the index location where to insert.
  - getPath
```
public java.lang.String getPath()
```
    Returns the path which maps this node's element location in the JDOM tree hierarchy.
    
    Returns:
    
    The path as a string.
  - setPath
```
public void setPath(java.lang.String parentPath)
```
    Appends this node's name and number of occurrence to a path.
    
    Parameters:
    
    parentPath - The path of the node which is or will be this node's parent.
  - addComment
```
public void addComment(java.lang.String value)
```
    Adds a comment to the element of this node. If other comments already exist then this one is added after the other comments.
    
    Parameters:
    
    value - String comment to be added.
  - getComment
```
public java.lang.String getComment(java.lang.String identifier)
```
    Gets an identified comment from the element of this node, if it exists. If a comment has been added with an identifier, this method will browse the available comments for a match. The identifier can exist anywhere in the comment.
    
    Parameters:
    
    identifier - String to match as an identifier.
    
    Returns:
    
    The comment or an empty string.
  - getComments
```
public java.util.List getComments()
```
    Gets all the comments belonging to the element of this node.
    
    Returns:
    
    List of comments in the order they are read from the element.
  - removeComment
```
public boolean removeComment(java.lang.String identifier)
```
    Removes the first identified comment from the element of this node, if one exists. A comment may be added with an identifier, and this method will browse the available comments for a matching identifier. The identifier can exist anywhere in the comment. Only the first occurrence is removed.
    
    Parameters:
    
    identifier - String to match as an identifier.
    
    Returns:
    
    true if removed, false otherwise
  - isRoot
```
public boolean isRoot()
```
    Tests whether this node wraps the JDOM document root element.
    
    Returns:
    
    true if is root, false otherwise
  - isLeaf
```
public boolean isLeaf()
```
    Tests whether this node wraps a leaf element, which is useful for knowing how to add content. (IMS and DLESE DTDs do not allow text to be added to non-leaf elements.
    
    Returns:
    
    true if is a leaf node, false otherwise
  - toString
```
public java.lang.String toString()
```
    Retrieves the name of the element of this node.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    The name of the wrapped element as a string.
  - getName
```
public java.lang.String getName()
```
    Retrieves the name of the element of this node.
    
    Returns:
    
    The name of the wrapped element, as a string.
  - getElement
```
public org.jdom.Element getElement()
```
    Retrieves the element of this node.
    
    Returns:
    
    The JDOM element of this node.
  - getValue
```
public java.lang.String getValue()
```
    Retrieves the textual content of the element of this node.
    NOTE: This implementation is built on JDOM 4, which provides weak access for reading and writing element content. JDOM 5 has deprecated this approach, and JDOM 6 is even more flexible and robust. Future implementations of this class should reflect the updates in JDOM.
    
    Returns:
    
    The text content of this node's element, or an empty string if there is no text content.
  - setValue
```
public void setValue(java.lang.String value)
```
    Sets the textual content of the element of this node, if it is a leaf element. (The requirement to be a leaf element is an IMS and DLESE DTD requirement, which a more general implementation should not restrict.)
    NOTE: This implementation is built on JDOM 4, which provides weak access for reading and writing element content. JDOM 5 has deprecated this approach, and JDOM 6 is even more flexible and robust. Future implementations of this class should reflect the updates in JDOM.
    
    Parameters:
    
    value - The text to set as content for the element of this node.
  - getAttribute
```
public java.lang.String getAttribute(java.lang.String attName)
```
    Retrieves a named attribute from the element of this node, if the attribute exists.
    
    Parameters:
    
    attName - The name of the attribute to retrieve.
    
    Returns:
    
    The value of the attribute as a string.
  - setAttribute
```
public void setAttribute(java.lang.String attName,
                         java.lang.String value)
```
    Sets the value of an attribute for the element of this node.
    
    Parameters:
    
    attName - The name of the attribute to set.
    
    value - The value to assign to the attribute.

Class XMLNode

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

path

children

occurs

element

parent

Constructor Detail

XMLNode

XMLNode

Method Detail

getParent

clear

addChild

getChild

getChildren

getLikeChildren

likeChildren

findPlace

getPath

setPath

addComment

getComment

getComments

removeComment

isRoot

isLeaf

toString

getName

getElement

getValue

setValue

getAttribute

setAttribute