org.dlese.dpc.xml.XMLNode

public class XMLNode extends 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

Description

protected 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 String

path

Identifies the location in the JDOM hierarchy of the wrapped XML element.
Constructor Summary

Constructors

Constructor

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

Modifier and Type

Method

Description

void

addChild(XMLNode node)

Adds a child node to this one at the correct location, and sets the path.

void

addComment(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.

String

getAttribute(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.

List

getChildren()

Gets the list of children belonging to this node.

String

getComment(String identifier)

Gets an identified comment from the element of this node, if it exists.

List

getComments()

Gets all the comments belonging to the element of this node.

org.jdom.Element

getElement()

Retrieves the element of this node.

List

getLikeChildren(String name)

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.

String

getPath()

Returns the path which maps this node's element location in the JDOM tree hierarchy.

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(String nodeName)

Searches the children nodes for an element name and returns the number found.

boolean

removeComment(String identifier)

Removes the first identified comment from the element of this node, if one exists.

void

setAttribute(String attName, String value)

Sets the value of an attribute for the element of this node.

void

setPath(String parentPath)

Appends this node's name and number of occurrence to a path.

void

setValue(String value)

Sets the textual content of the element of this node, if it is a leaf element.

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 Details
- path
  
  protected String path
  
  Identifies the location in the JDOM hierarchy of the wrapped XML element.
- children
  
  protected 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 Details
- 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 Details
- 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 List getChildren()
  
  Gets the list of children belonging to this node.
  
  Returns:
  
  A List containing all the children of this node.
- getLikeChildren
  
  public List getLikeChildren(String name)
- likeChildren
  
  public int likeChildren(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 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(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(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 String getComment(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 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(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 String toString()
  
  Retrieves the name of the element of this node.
  
  Overrides:
  
  toString in class Object
  
  Returns:
  
  The name of the wrapped element as a string.
- getName
  
  public 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 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(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 String getAttribute(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(String attName, 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 Details

path

children

occurs

element

parent

Constructor Details

XMLNode

XMLNode

Method Details

getParent

clear

addChild

getChild

getChildren

getLikeChildren

likeChildren

findPlace

getPath

setPath

addComment

getComment

getComments

removeComment

isRoot

isLeaf

toString

getName

getElement

getValue

setValue

getAttribute

setAttribute