org.dlese.dpc.xml

Class XMLRecord

java.lang.Object

org.dlese.dpc.xml.XMLRecord

public class XMLRecord
extends java.lang.Object

Creates a wrapper implementation for accessing a JDOM XML document and for mapping the JDOM elements to a local HashMap. JDOM provides the capability to parse, create, edit and write XML documents, however it lacks an efficient method for locating individual elements, as well as needing some help with controlling where new elements get inserted and how comments get processed. It should be noted that only a limited subset of JDOM's capability is actually utilized by this implementation.

Individual JDOM XML elements are wrapped in XMLNode objects before being stored in the local HashMap. The map key for each XMLNode is a dot delimited string formed from the paths through the JDOM hierarchy, obtained when reading in the XML template. Key paths are constructed and described in the XMLNode details.

Currently, XMLRecord is instantiated with an XML file, to provide the mappings from the JDOM tree to the local HashMap. The JDOM document is created, and that document's root element is wrapped in an XMLNode. Then each child element is recursively processed. As each child element is processed, it is likewise wrapped in an XMLNode, its key path is constructed, and then is inserted into the map. Each node maintains the proper parent-child relations.

Version:

1.0 02/01/01

Author:

Dave Deniman

Field Summary

Fields

Modifier and Type	Field and Description
protected org.jdom.Document	doc The JDOM document this record maps.
protected java.lang.StringBuffer	footnote A special comment intended as the final comment in the XML file.
protected java.util.HashMap	map Maps reference pointers to elements in the XML hierarchy.
protected XMLNode	root The root node of this XMLRecord.
protected java.io.File	xmlFile The source XML file used to identify the XML hierarchy.

Constructor Summary

Constructors

Constructor and Description
XMLRecord(java.io.File file) Accepts an XML file and maps its XML structure to a HashMap.

Method Summary

Modifier and Type	Method and Description
void	addNode(XMLNode parent, org.jdom.Element element) Adds a JDOM element to the current record.
void	addNodes(java.lang.String name, XMLNode parent, int num) Adds one or more like elements to the current record.
protected void	cleanMap(XMLNode node) Called by removeNodes to remove a node and its children from the local map.
void	clear()
protected void	clearMap(XMLNode node)
java.lang.String	getFootnote() Getter method for the XML footnote comment.
XMLNode	getNode(java.lang.String name) Returns a node of the current record, or null if the node does not exist.
XMLNode	getRoot() Returns the root node of the current record.
boolean	outputRecord() Ouputs the current record to xmlFile, which is the same file used to create the current record unless outputRecord(newfile) has been called.
boolean	outputRecord(java.lang.String newfile) A convenience method for outputting the current record to a given filename.
protected void	process(XMLNode parentNode) Recursively iterates through the children XML elements, wrapping each in an XMLNode and adding the created node to the local map.
protected void	processComments() Process the document's (as opposed to an element's) comments for purposes of extracting the footnote.
void	removeNodes(java.lang.String name, XMLNode parent, int num) Removes one or more like elements from the parent XMLNode.
void	setFootnote(java.lang.String value) Setter method for the XML footnote comment.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

root

protected XMLNode root

The root node of this XMLRecord.

doc

protected org.jdom.Document doc

The JDOM document this record maps.

map

protected java.util.HashMap map

Maps reference pointers to elements in the XML hierarchy.

xmlFile

protected java.io.File xmlFile

The source XML file used to identify the XML hierarchy.

footnote

protected java.lang.StringBuffer footnote

A special comment intended as the final comment in the XML file.

Constructor Detail

XMLRecord

public XMLRecord(java.io.File file)
          throws java.lang.Exception

Accepts an XML file and maps its XML structure to a HashMap.

Parameters:

file - A well-formed XML file.

Throws:

java.lang.Exception

Method Detail

clear

public void clear()

clearMap

protected void clearMap(XMLNode node)

process

protected void process(XMLNode parentNode)

Recursively iterates through the children XML elements, wrapping each in an XMLNode and adding the created node to the local map. Element parent/child relationships are maintained.

If called on the root node, this method effectively builds the entire map. If called on a subordinate node, then it will build only the local sub-hierarchy.

Parameters:

parentNode - The node from which to start processing.

outputRecord

public boolean outputRecord(java.lang.String newfile)

A convenience method for outputting the current record to a given filename. Typically, the class is instantiated with an XML file, and the no argument outputRecord method used to write the record to that same file. This method, however, reassigns the protected member xmlFile in order to write to a new file. This is done in the case when an XML template file is used, and the template should be preserved.

Parameters:

newfile - String representing the filename or absolute filename of the new file to write.

Returns:

true if succeeded, false otherwise

outputRecord

public boolean outputRecord()

Ouputs the current record to xmlFile, which is the same file used to create the current record unless outputRecord(newfile) has been called. Once that method is called, xmlFileis changed, and subsequent calls to this method will output to the new file.

Returns:

true if succeeded, false otherwise

getRoot

public XMLNode getRoot()

Returns the root node of the current record.

Returns:

The XMLNode wrapper for the JDOM document root element

getNode

public XMLNode getNode(java.lang.String name)

Returns a node of the current record, or null if the node does not exist. The node is identified by its path in the JDOM tree. See XMLNode for details on path construction.

Parameters:

name - String representing the node path in the JDOM tree.

Returns:

XMLNode wrapper for the element requested

addNode

public void addNode(XMLNode parent,
                    org.jdom.Element element)

Adds a JDOM element to the current record. The element is added to parent XMLNode, so parent is assumed to exist within the current record. The element may be a complex element with mixed content. The element is added after like elements if other like elements are already attached to this parent node, otherwise it is added at the end of the parent node's list of children elements. After adding the element, the element is wrapped in an XMLNode and processed (added to the local map).

NOTE: Both parent and element are assumed to be non-null in the current implementation, future implementations will provide this assertion check.

Parameters:

parent - XMLNode that this element should be added to.

element - A new JDOM element to add to this parent node.

addNodes

public void addNodes(java.lang.String name,
                     XMLNode parent,
                     int num)

Adds one or more like elements to the current record. The elements are added to the parent XMLNode, and it is assumed that there already exists one such element as a child to the parent node. If no such like element exists, then it should be created and the addNode method called first. Then invoke this method to add multiples of the same element as new XMLNodes in the local map. Once the elements are added as nodes to the map, their content may be defined.

NOTE: New elements are created as copies of existing elements, which means their text content cannot be assumed empty.

Parameters:

name - String representing the name of like elements to add.

parent - XMLNode that the like elements should be added to.

num - Number of like elements to add.

removeNodes

public void removeNodes(java.lang.String name,
                        XMLNode parent,
                        int num)

Removes one or more like elements from the parent XMLNode. No more elements can be removed than what exists, and no errors are generated if an attempt to do so is made. The wrapping nodes are also removed from the local map, preserving the integrity of the relationship with the JDOM tree.

Parameters:

name - String representing the name of the like elements.

parent - XMLNode that the like elements should be removed from.

num - Number of like elements to remove.

cleanMap

protected void cleanMap(XMLNode node)

Called by removeNodes to remove a node and its children from the local map.

Parameters:

node - XMLNode to be removed.

getFootnote

public java.lang.String getFootnote()

Getter method for the XML footnote comment. The footnote is read from and written to the end of the XML file as an XML comment. Look at the source for implementation details, because the same strategy could be applied to include additional comments, such as headers, other footers, or specifc labeled comments to elements.

Returns:

String representing the footnote comment.

setFootnote

public void setFootnote(java.lang.String value)

Setter method for the XML footnote comment. The footnote is read from and written to the end of the XML file as an XML comment. Look at the source for implementation details, because the same strategy could be applied to include additional comments, such as headers, other footers, or specifc labeled comments to elements.

Parameters:

value - String representing the footnote comment to add.

processComments

protected void processComments()

Process the document's (as opposed to an element's) comments for purposes of extracting the footnote. Also fixes a bug in JDOM which adds extraneous spaces to comments each time they get processed.