org.greybird.xmliter
Class DomIterator

java.lang.Object
  |
  +--org.greybird.xmliter.DomIterator

All Implemented Interfaces:

XmlIterator

public class DomIterator

extends java.lang.Object

implements XmlIterator

An XmlIterator that obtains its data from a DOM tree. This class is provided so that the XmlIterator interface may be used with a DOM when one is available.

DomIterator adds less than 3% processing overhead compared to direct use of the DOM API. This percentage is relative to the total time to parse and traverse a document. It comes from the PerformanceTest included with this package.

To use a DomIterator, first obtain a DOM Node that is the parent of the elements and text to be traversed. Typically this is a Document node, but it could also be an Element or a DocumentFragment. Then construct the DomIterator specifying the parent node to be used.

 import javax.xml.parsers.DocumentBuilder;
 import javax.xml.parsers.DocumentBuilderFactory;
 import org.greybird.xmliter.DomIterator;
 import org.greybird.xmliter.XmlIterator;
 import org.w3c.dom.Node;
 ...
 //
 // Parse a document to obtain a Document node.
 //
 DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
 factory.setNamespaceAware(true);
 DocumentBuilder builder = factory.newDocumentBuilder();
 Node document = builder.parse(input);
 //
 // Now use the document to construct a DomIterator.
 //
 XmlIterator iter = new DomIterator(document);
 while (iter.advance()) { ...
 

Constructor Summary

DomIterator(org.w3c.dom.Node parentNode)
Creates a DOM iterator using a given parent node.

Method Summary

boolean	advance() Moves to the next element at the current level and returns true, or returns false if there are no more elements.
boolean	advanceMixed() Moves to the next element or text item at the current level and returns true, or returns false if there are no more items.
java.lang.String	attribute(java.lang.String namespace, java.lang.String name) Returns the value of the attribute with the given name belonging to the current element, or null if no such attribute exists, or null if positioned on a mixed text item.
XmlAttributes	attributes() Returns an iterator over the attributes belonging to the current element, or null if positioned on a mixed text item.
XmlIterator	children() Returns an iterator positioned before the first child of the current element, or null if the current element does not contain any element children, or null if positioned on a mixed text item.
java.lang.String	name() Returns the local name of the current element, or null if positioned on a mixed text item.
java.lang.String	namespace() Returns the namespace URI of the current element, or an empty string if the current element has no namespace, or null if positioned on a mixed text item.
java.lang.String	toString() Returns a string for error reporting that identifies the current element.
java.lang.String	value() Returns the text contained by the current element or text item, or null if positioned on an element that contains one or more element children.

Methods inherited from class java.lang.Object

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

Constructor Detail

DomIterator

public DomIterator(org.w3c.dom.Node parentNode)

Creates a DOM iterator using a given parent node.

Method Detail

advance

public boolean advance()
                throws java.lang.IllegalStateException,
                       java.io.IOException,
                       XmlIteratorException

Description copied from interface: XmlIterator

Moves to the next element at the current level and returns true, or returns false if there are no more elements.

Specified by:

advance in interface XmlIterator

Following copied from interface: org.greybird.xmliter.XmlIterator

Throws:

java.lang.IllegalStateException - if an element would be returned out of depth-first tree order.

java.io.IOException - if an error occurs retrieving input data.

XmlIteratorException - if an error occurs processing input data.

advanceMixed

public boolean advanceMixed()
                     throws java.lang.IllegalStateException,
                            java.io.IOException,
                            XmlIteratorException

Description copied from interface: XmlIterator

Moves to the next element or text item at the current level and returns true, or returns false if there are no more items.

Specified by:

advanceMixed in interface XmlIterator

Following copied from interface: org.greybird.xmliter.XmlIterator

Throws:

java.lang.IllegalStateException - if an element or text item would be returned out of depth-first tree order.

java.io.IOException - if an error occurs retrieving input data.

XmlIteratorException - if an error occurs processing input data.

name

public java.lang.String name()
                      throws java.lang.IllegalStateException

Description copied from interface: XmlIterator

Returns the local name of the current element, or null if positioned on a mixed text item. An empty string will not be returned. Null will not be returned if advance() was called.

Specified by:

name in interface XmlIterator

Following copied from interface: org.greybird.xmliter.XmlIterator

Throws:

java.lang.IllegalStateException - if advance() or advanceMixed() has not yet been called.

namespace

public java.lang.String namespace()
                           throws java.lang.IllegalStateException

Description copied from interface: XmlIterator

Returns the namespace URI of the current element, or an empty string if the current element has no namespace, or null if positioned on a mixed text item.

Specified by:

namespace in interface XmlIterator

Following copied from interface: org.greybird.xmliter.XmlIterator

Throws:

java.lang.IllegalStateException - if advance() or advanceMixed() has not yet been called.

attribute

public java.lang.String attribute(java.lang.String namespace,
                                  java.lang.String name)
                           throws java.lang.IllegalStateException,
                                  java.io.IOException,
                                  XmlIteratorException

Description copied from interface: XmlIterator

Returns the value of the attribute with the given name belonging to the current element, or null if no such attribute exists, or null if positioned on a mixed text item. Namespace nodes are not attributes and are not returned by this method.

WARNING: Unlike the DOM methods Node.getAttribute() and getAttributeNS() this method returns null, not an empty string, when the attribute does not exist.

Specified by:

attribute in interface XmlIterator

Following copied from interface: org.greybird.xmliter.XmlIterator

Parameters:

namespace - is the namespace of the attribute or may be null or an empty string if the attribute has the empty namespace.

name - is the local name of the attribute.

Throws:

java.lang.IllegalStateException - if advance() or advanceMixed() has not yet been called.

java.io.IOException - if an error occurs retrieving input data.

XmlIteratorException - if an error occurs processing input data.

attributes

public XmlAttributes attributes()
                         throws java.lang.IllegalStateException,
                                java.io.IOException,
                                XmlIteratorException

Description copied from interface: XmlIterator

Returns an iterator over the attributes belonging to the current element, or null if positioned on a mixed text item. Namespace nodes are not attributes and are not returned by the iterator.

Specified by:

attributes in interface XmlIterator

Following copied from interface: org.greybird.xmliter.XmlIterator

Throws:

java.lang.IllegalStateException - if advance() or advanceMixed() has not yet been called.

java.io.IOException - if an error occurs retrieving input data.

XmlIteratorException - if an error occurs processing input data.

value

public java.lang.String value()
                       throws java.lang.IllegalStateException,
                              java.io.IOException,
                              XmlIteratorException

Description copied from interface: XmlIterator

Returns the text contained by the current element or text item, or null if positioned on an element that contains one or more element children.

This method always returns the complete text between elements, which may be the result of concatenating multiple SAX character events or DOM text nodes.

Specified by:

value in interface XmlIterator

Following copied from interface: org.greybird.xmliter.XmlIterator

Throws:

java.lang.IllegalStateException - if advance() or advanceMixed() has not yet been called.

java.io.IOException - if an error occurs retrieving input data.

XmlIteratorException - if an error occurs processing input data.

children

public XmlIterator children()
                     throws java.lang.IllegalStateException,
                            java.io.IOException,
                            XmlIteratorException

Description copied from interface: XmlIterator

Returns an iterator positioned before the first child of the current element, or null if the current element does not contain any element children, or null if positioned on a mixed text item. If a non-null iterator is returned, it will always contain at least one element.

If this method is called for an element more than once it will return the same iterator instance as was returned the first time it was called, and therefore the returned iterator may no longer be positioned before its first child.

Specified by:

children in interface XmlIterator

Following copied from interface: org.greybird.xmliter.XmlIterator

Throws:

java.lang.IllegalStateException - if advance() or advanceMixed() has not yet been called.

java.io.IOException - if an error occurs retrieving input data.

XmlIteratorException - if an error occurs processing input data.

toString

public java.lang.String toString()

Description copied from interface: XmlIterator

Returns a string for error reporting that identifies the current element. The returned value should be in square brackets and contain an XPath identifier or an approximation of one for the current element. For example:

[/ns:TopElement/ns:ChildElement]

Specified by:

toString in interface XmlIterator

Overrides:

toString in class java.lang.Object