org.dlese.dpc.xml
Class XMLNode

java.lang.Object
  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

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

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

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 Detail

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

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.