Class XMLDoc

java.lang.Object
  extended by XMLDoc

public class XMLDoc
extends java.lang.Object

The XMLDoc class provides access to the elements and attributes of a specified XML Document object through a simplified interface. Use the default constructor to instantiate an XMLDoc object. You must then use one of the methods setDocument(), newDocument(), or load() to prepare the object for use. Once the Document object is established, you can use XPath expressions to search the member document. You can also append elements, attributes, and other documents into the member document. Finally, you can serialize the document to a specified outputstream object.

Author:
Paul Medlock version 1.0

Field Summary
static int AFTER
           
static int BEFORE
           
static int CHILD
           
private  org.w3c.dom.Document doc
           
private  java.lang.String fileName
           
private  boolean ignore
           
static int REPLACE
           
private  javax.xml.xpath.XPath xpath
           
 
Constructor Summary
XMLDoc()
           
 
Method Summary
 void appendAttribute(org.w3c.dom.Element _parent, java.lang.String _name, java.lang.String _value)
          Use the specified name and value to create and append an attribute to the specified parent element.
 org.w3c.dom.Node appendDoc(org.w3c.dom.Node _context, org.w3c.dom.Document _doc, int _where)
          Clone and append the document element of the specified document to the member document to the specified context node.
 org.w3c.dom.Element appendElement(org.w3c.dom.Element _child)
          Append the specified element as the document element of the document.
 org.w3c.dom.Element appendElement(org.w3c.dom.Element _context, org.w3c.dom.Element _node, int _where)
          Use the specified name to create and append an element to the specified parent element.
 org.w3c.dom.Element appendElement(org.w3c.dom.Element _context, java.lang.String _name, int _where)
          Use the specified name to create and append an element to the specified parent element.
 org.w3c.dom.Element appendElement(org.w3c.dom.Element _context, java.lang.String _name, java.lang.String _value, int _where)
          Use the specified name to create and append an element to the specified parent element.
 org.w3c.dom.Node appendForeignElement(org.w3c.dom.Node _context, org.w3c.dom.Node _node, int _where, boolean _deep)
           
 org.w3c.dom.Element createElement(java.lang.String _name)
          Use the specified name to create an element.
 org.w3c.dom.Element createElement(java.lang.String _name, java.lang.String _value)
          Use the specified name to create an element.
 void flushWhiteSpace()
          Flush ALL text nodes - temporary until setIgnoringElementContentWhitespace works? From my reading on the inet, that will happen when hell freezes over.
 java.lang.String getAttributeValue(org.w3c.dom.Node _node, java.lang.String _name, java.lang.String _default)
          Get the value of the specified attribute for the specified node, which is assumed to be an element.
 org.w3c.dom.Document getDocument()
          Return the member Document object.
 org.w3c.dom.Node getDocumentElement()
          Return the document element
 java.lang.String getFileName()
           
 java.lang.String getValue(org.w3c.dom.Node _context, java.lang.String _path, java.lang.String _default)
          Search the specified context node for a node identified by the specified XPath expression, and obtain the value of the node.
 java.lang.String getValue(java.lang.String _path, java.lang.String _default)
          Search the document for a node identified by the specified XPath expression, and obtain the value of the node.
 boolean hasChildren(org.w3c.dom.Node _node)
          Check if the specified node has children.
 boolean hasPath(org.w3c.dom.Node _context, java.lang.String _path)
          Search the document for a node identified by the specified XPath expression.
 boolean hasPath(java.lang.String _path)
          Search the document for a node identified by the specified XPath expression.
 void ignoreWhiteSpace(boolean _ignore)
          Set the flag to ignore white space.
 boolean load(java.io.InputStream _stream, javax.xml.namespace.NamespaceContext _nc)
          Load the XML document encapsulated by the specified input stream into the member Document object.
 boolean load(java.lang.String _fileName, javax.xml.namespace.NamespaceContext _nc)
          Load the XML configuration document specified by the file name parameter.
 boolean newDocument(javax.xml.namespace.NamespaceContext _nc)
          Create a Document object, and set it as the managed member object.
 void removeAttribute(org.w3c.dom.Element _elem, org.w3c.dom.Attr _attr)
          Remove the specified attribute from the document.
 void removeAttribute(org.w3c.dom.Element _elem, java.lang.String _attr)
          Remove the specified attribute from the document.
 org.w3c.dom.Node removeNode(org.w3c.dom.Node _node)
          Remove the specified node from the document.
 org.w3c.dom.NodeList selectChildren(org.w3c.dom.Node _node)
          Obtain the nodes that are the children of the specified node.
 org.w3c.dom.NodeList selectNodes(org.w3c.dom.Node _context, java.lang.String _path)
          Search the specified context node for the set of nodes identified by the specified XPath expression.
 org.w3c.dom.NodeList selectNodes(java.lang.String _path)
          Search the document for the set of nodes identified by the specified XPath expression.
 org.w3c.dom.Node selectSingleNode(org.w3c.dom.Node _context, java.lang.String _path)
          Search the specified context node for the single node identified by the specified XPath expression.
 org.w3c.dom.Node selectSingleNode(java.lang.String _path)
          Search the document for the single node identified by the specified XPath expression.
 void serialize(java.io.OutputStream _output)
          Serialize the member Document object to the specified output- stream.
 void serialize(java.lang.String _fileName)
          Serialize the member Document object to the specified file.
 boolean setAttributeValue(org.w3c.dom.Node _node, java.lang.String _name, java.lang.String _value)
          Check the value of the specified attribute.
 boolean setDocument(org.w3c.dom.Document _doc, javax.xml.namespace.NamespaceContext _nc)
          Set the member Document to the specified Document object.
 void setNamespaceContext(javax.xml.namespace.NamespaceContext _nc)
           
 void setText(org.w3c.dom.Element _parent, java.lang.String _value)
          Set the text() node of the specified element to the specified value.
 boolean setValue(org.w3c.dom.Node _context, java.lang.String _path, java.lang.String _value)
          Search the specified context node for a node identified by the specified XPath expression, and set its value to the specified value.
 boolean setValue(java.lang.String _path, java.lang.String _value)
          Search the specified context node for a node identified by the specified XPath expression, and set its value to the specified value.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BEFORE

public static final int BEFORE
See Also:
Constant Field Values

REPLACE

public static final int REPLACE
See Also:
Constant Field Values

AFTER

public static final int AFTER
See Also:
Constant Field Values

CHILD

public static final int CHILD
See Also:
Constant Field Values

ignore

private boolean ignore

doc

private org.w3c.dom.Document doc

xpath

private javax.xml.xpath.XPath xpath

fileName

private java.lang.String fileName
Constructor Detail

XMLDoc

public XMLDoc()
Method Detail

getFileName

public java.lang.String getFileName()

setNamespaceContext

public void setNamespaceContext(javax.xml.namespace.NamespaceContext _nc)

ignoreWhiteSpace

public void ignoreWhiteSpace(boolean _ignore)
Set the flag to ignore white space. This method must be called before the document is loaded or otherwise established so that the flushWhiteSpace() method below will operate correctly. The default is to not flushWhiteSpace.

Parameters:
_ignore - should be true to flush the whitespace from the document.

flushWhiteSpace

public void flushWhiteSpace()
Flush ALL text nodes - temporary until setIgnoringElementContentWhitespace works? From my reading on the inet, that will happen when hell freezes over.


serialize

public void serialize(java.io.OutputStream _output)
Serialize the member Document object to the specified output- stream.

Parameters:
_output - names the stream to which to serialize the document.

serialize

public void serialize(java.lang.String _fileName)
Serialize the member Document object to the specified file. Useful for taking a snapshot of the document while debugging.

Parameters:
_fileName - names the file to which to serialize the document.

setDocument

public boolean setDocument(org.w3c.dom.Document _doc,
                           javax.xml.namespace.NamespaceContext _nc)
Set the member Document to the specified Document object. This method initializes the XMLDoc object. If you use this method, do not use the newDocument() or the load() methods. Note that this method assumes JRE 5+.

Parameters:
_doc - specifies the Document object for the XMLDoc to manage.

newDocument

public boolean newDocument(javax.xml.namespace.NamespaceContext _nc)
Create a Document object, and set it as the managed member object. This method initializes the XMLDoc object. If you use this method, do not use the setDocument() or the load() methods. Note that this method assumes JRE 5+.

Returns:
true if the Document object and an XPath worker object are instantiated successfully.

load

public boolean load(java.io.InputStream _stream,
                    javax.xml.namespace.NamespaceContext _nc)
Load the XML document encapsulated by the specified input stream into the member Document object. This method initializes the XMLDoc object. If you use this method, do not use the setDocument() or newDocument() methods. Note that this method assumes JRE 5+.

Parameters:
_stream - is the stream object to load.
Returns:
true if the Document object and an XPath worker object are instantiated successfully.

load

public boolean load(java.lang.String _fileName,
                    javax.xml.namespace.NamespaceContext _nc)
Load the XML configuration document specified by the file name parameter. Also initialize an XPath support object.

Parameters:
_fileName - is the name of the file to be loaded.
Returns:
true if the document is loaded successfully.

getDocument

public org.w3c.dom.Document getDocument()
Return the member Document object.

Returns:
a referemce to the managed Document object.

getDocumentElement

public org.w3c.dom.Node getDocumentElement()
Return the document element

Returns:
the document element.

selectSingleNode

public org.w3c.dom.Node selectSingleNode(org.w3c.dom.Node _context,
                                         java.lang.String _path)
Search the specified context node for the single node identified by the specified XPath expression.

Parameters:
_context - is the node within the document relative to which the XPath expression is evaluated.
_path - is the XPath expression that identifies a single node.
Returns:
null if a node is not found, otherwise the node found.

selectSingleNode

public org.w3c.dom.Node selectSingleNode(java.lang.String _path)
Search the document for the single node identified by the specified XPath expression.

Parameters:
_path - is the XPath expression that identifies a single node.
Returns:
null if a node is not found, otherwise the node found.

selectNodes

public org.w3c.dom.NodeList selectNodes(org.w3c.dom.Node _context,
                                        java.lang.String _path)
Search the specified context node for the set of nodes identified by the specified XPath expression.

Parameters:
_context - is the node within the document relative to which the XPath expression is evaluated.
_path - is the XPath expression that identifies a set of nodes.
Returns:
null if no nodes are found, otherwise a list of the nodes found.

selectNodes

public org.w3c.dom.NodeList selectNodes(java.lang.String _path)
Search the document for the set of nodes identified by the specified XPath expression.

Parameters:
_path - is the XPath expression that identifies a set of nodes.
Returns:
null if no nodes are found, otherwise a list of the nodes found.

selectChildren

public org.w3c.dom.NodeList selectChildren(org.w3c.dom.Node _node)
Obtain the nodes that are the children of the specified node.

Parameters:
_node - is the parent of the desired nodes.
Returns:
null if no nodes are found, otherwise a list of the nodes found.

hasChildren

public boolean hasChildren(org.w3c.dom.Node _node)
Check if the specified node has children.

Parameters:
_node - to check.
Returns:
false if no children, otherwise true.

hasPath

public boolean hasPath(org.w3c.dom.Node _context,
                       java.lang.String _path)
Search the document for a node identified by the specified XPath expression.

Parameters:
_path - is the XPath expression that identifies a node.
Returns:
false if a node is not found, otherwise true.

hasPath

public boolean hasPath(java.lang.String _path)
Search the document for a node identified by the specified XPath expression.

Parameters:
_path - is the XPath expression that identifies a node.
Returns:
false if a node is not found, otherwise true.

getValue

public java.lang.String getValue(org.w3c.dom.Node _context,
                                 java.lang.String _path,
                                 java.lang.String _default)
Search the specified context node for a node identified by the specified XPath expression, and obtain the value of the node. if no node is found, or if the String value of the node is empty, use the value of the specified default.

Parameters:
_context - is the node within the document relative to which the XPath expression is evaluated.
_path - is the XPath expression that identifies a node.
_default - specifies the value to return if the result of the search is empty.
Returns:
the String value of the node, or the default if the node is not found or is empty.

getAttributeValue

public java.lang.String getAttributeValue(org.w3c.dom.Node _node,
                                          java.lang.String _name,
                                          java.lang.String _default)
Get the value of the specified attribute for the specified node, which is assumed to be an element. If the String value of the attribute is empty, use the value of the specified default.

Parameters:
_node - is the element containing the attribute.
_name - is the name of the attribute.
_default - specifies the value to return if the attribute value is empty.
Returns:
the String value of the attribute, or the default if the node is not found or is empty. Use this instead of an XPath expression in a getValue call if you know the element containing the attribute. This is far faster.

setAttributeValue

public boolean setAttributeValue(org.w3c.dom.Node _node,
                                 java.lang.String _name,
                                 java.lang.String _value)
Check the value of the specified attribute. If it is different than the new value, change it and return true. Return false if they are the same.

Parameters:
_node - is the node within the document containing the attribute.
_name - is the name of the attribute to change.
_value - specifies the value to use in setting the attribute value.
Returns:
true if the value of the attribute is changed.

getValue

public java.lang.String getValue(java.lang.String _path,
                                 java.lang.String _default)
Search the document for a node identified by the specified XPath expression, and obtain the value of the node. If no node is found, or if the String value of the node is empty, use the value of the specified default.

Parameters:
_path - is the XPath expression that identifies a node.
_default - specifies the value to return if the result of the search is empty.
Returns:
the String value of the node, or the default if the node is not found or is empty.

setValue

public boolean setValue(java.lang.String _path,
                        java.lang.String _value)
Search the specified context node for a node identified by the specified XPath expression, and set its value to the specified value. Please note: If no node is found, no change is made.

Parameters:
_path - is the XPath expression that identifies a node.
_value - specifies the value to use in setting the node value.
Returns:
true if the specified node is found.

setValue

public boolean setValue(org.w3c.dom.Node _context,
                        java.lang.String _path,
                        java.lang.String _value)
Search the specified context node for a node identified by the specified XPath expression, and set its value to the specified value. Please note: If no node is found, no change is made.

Parameters:
_context - is the node within the document relative to which the XPath expression is evaluated.
_path - is the XPath expression that identifies a node.
_value - specifies the value to use in setting the node value.
Returns:
true if the specified node is found.

createElement

public org.w3c.dom.Element createElement(java.lang.String _name)
Use the specified name to create an element.

Parameters:
_name - is the new element to create.
Returns:
a reference to the new element.

createElement

public org.w3c.dom.Element createElement(java.lang.String _name,
                                         java.lang.String _value)
Use the specified name to create an element.

Parameters:
_name - is the new element to create.
Returns:
a reference to the new element.

appendDoc

public org.w3c.dom.Node appendDoc(org.w3c.dom.Node _context,
                                  org.w3c.dom.Document _doc,
                                  int _where)
Clone and append the document element of the specified document to the member document to the specified context node.

Parameters:
_context - is the node to which to append the document
_doc - is the document whose document element is to be appended.
_where - identifies whether the document element should be appended as a sibling before or after the context, or as a child of the context node.
Returns:
a reference to the new element.

appendForeignElement

public org.w3c.dom.Node appendForeignElement(org.w3c.dom.Node _context,
                                             org.w3c.dom.Node _node,
                                             int _where,
                                             boolean _deep)

appendElement

public org.w3c.dom.Element appendElement(org.w3c.dom.Element _child)
Append the specified element as the document element of the document. Use this method only once.

Parameters:
_child - is the name of the new element.
Returns:
a reference to the new element.

appendElement

public org.w3c.dom.Element appendElement(org.w3c.dom.Element _context,
                                         org.w3c.dom.Element _node,
                                         int _where)
Use the specified name to create and append an element to the specified parent element.

Parameters:
_context - is the element to which to append the new element.
_node - is the new element to append.
_where - specifies the relationship to be established between the context element and the new element.
Returns:
a reference to the new element.

appendElement

public org.w3c.dom.Element appendElement(org.w3c.dom.Element _context,
                                         java.lang.String _name,
                                         int _where)
Use the specified name to create and append an element to the specified parent element.

Parameters:
_context - is the element to which to append the new element.
_name - is the name of the new element to append.
_where - specifies the relationship to be established between the context element and the new element.
Returns:
a reference to the new element.

appendElement

public org.w3c.dom.Element appendElement(org.w3c.dom.Element _context,
                                         java.lang.String _name,
                                         java.lang.String _value,
                                         int _where)
Use the specified name to create and append an element to the specified parent element. Append the specified value (text node) to the new node.

Parameters:
_context - is the element to which to append the new element.
_name - is the name of the new element.
_value - is the string value of the text node to attach to the new element.
_where - specifies the relationship to be established between the context element and the new element.
Returns:
a reference to the new element.

removeNode

public org.w3c.dom.Node removeNode(org.w3c.dom.Node _node)
Remove the specified node from the document.

Parameters:
_node - is the element to remove.
Returns:
a reference to the removed node.

removeAttribute

public void removeAttribute(org.w3c.dom.Element _elem,
                            org.w3c.dom.Attr _attr)
Remove the specified attribute from the document.

Parameters:
_elem - is the element owning the attribute.
_attr - is the attribute to remove.

removeAttribute

public void removeAttribute(org.w3c.dom.Element _elem,
                            java.lang.String _attr)
Remove the specified attribute from the document.

Parameters:
_elem - is the element owning the attribute.
_attr - is the attribute to remove.

appendAttribute

public void appendAttribute(org.w3c.dom.Element _parent,
                            java.lang.String _name,
                            java.lang.String _value)
Use the specified name and value to create and append an attribute to the specified parent element. Note that if the attribute already exists, this method updates the value.

Parameters:
_parent - is the element to which to append the new element as a child.
_name - is the name of the new attribute.
_value - is the string value of the new attribute.

setText

public void setText(org.w3c.dom.Element _parent,
                    java.lang.String _value)
Set the text() node of the specified element to the specified value.

Parameters:
_parent - is the element to assign the text node.
_value - is the string value to set as the text node.