simple.util.xml
Class Traverser

java.lang.Object
  extended by simple.util.xml.Traverser
Direct Known Subclasses:
PrefixResolver

public abstract class Traverser
extends java.lang.Object

The Traverser object is used to parse an XML document in a simple element by element manner. This makes use of KDOM to parse and represent the document as a tree. Once the tree has been created each element is processed from the KDOM in order, that is, first come first served. This provides a SAX like parsing model using KDOM, this allows simple parsing with optional KDOM usage.

Author:
Niall Gallagher

Constructor Summary
protected Traverser()
          Constructor for the Traverser object this is used to create a new instance with a new document builder object.
 
Method Summary
protected  void commit(Node node)
          Once an element and all its child elements have been processed this method is invoked to close the processing of the element.
protected  void finish()
          When all elements of the KDOM have been traversed this method is used to perform post processing of the collected data.
 void parse(org.kxml2.kdom.Element source)
          This is used to parse the provided KDOM element.
 void parse(java.io.File source)
          This is used to parse the provided source document.
 void parse(java.io.File source, java.lang.String charset)
          This is used to parse the provided source document.
 void parse(java.io.InputStream source)
          This is used to parse the provided source document.
 void parse(java.io.InputStream source, java.lang.String charset)
          This is used to parse the provided source document.
 void parse(Node source)
          This method is provided as a convinience for parsing the node provided.
 void parse(java.io.Reader source)
          This is used to parse the provided source document.
 void parse(java.lang.String source)
          This is used to parse the provided source document.
protected abstract  void process(Node node)
          This is used to process an element from the KDOM document.
protected abstract  void start()
          This is used to initialize the XML parser.
protected  void traverse(org.kxml2.kdom.Element node)
          This method is used to traverse all KDOM nodes acquired.
protected  void traverse(org.kxml2.kdom.Element node, int count)
          This method is used to traverse all KDOM nodes acquired.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Traverser

protected Traverser()
Constructor for the Traverser object this is used to create a new instance with a new document builder object. This will simply query a document builder factory for a default implementation, which it will use to parse all KDOM documents.

Method Detail

parse

public void parse(java.lang.String source)
           throws java.lang.Exception
This is used to parse the provided source document. This will parse the provided document source using KDOM and then traverse each element encountered within the KDOM object such that it can be processed in a sequential manner. If the source is not a valid XML document a parsing exception it thrown.

Parameters:
source - this is the XML document source to be parsed
Throws:
java.lang.Exception

parse

public void parse(java.io.File source)
           throws java.lang.Exception
This is used to parse the provided source document. This will parse the provided document source using KDOM and then traverse each element encountered within the KDOM object such that it can be processed in a sequential manner. If the source is not a valid XML document a parsing exception it thrown.

Parameters:
source - this is the XML document source file to parse
Throws:
java.lang.Exception

parse

public void parse(java.io.File source,
                  java.lang.String charset)
           throws java.lang.Exception
This is used to parse the provided source document. This will parse the provided document source using KDOM and then traverse each element encountered within the KDOM object such that it can be processed in a sequential manner. If the source is not a valid XML document a parsing exception it thrown.

Parameters:
source - this is the XML document source file to parse
charset - this is the character set to read the XML with
Throws:
java.lang.Exception

parse

public void parse(java.io.InputStream source)
           throws java.lang.Exception
This is used to parse the provided source document. This will parse the provided document source using KDOM and then traverse each element encountered within the KDOM object such that it can be processed in a sequential manner. If the source is not a valid XML document a parsing exception it thrown.

Parameters:
source - this is the XML document source to be parsed
Throws:
java.lang.Exception

parse

public void parse(java.io.InputStream source,
                  java.lang.String charset)
           throws java.lang.Exception
This is used to parse the provided source document. This will parse the provided document source using KDOM and then traverse each element encountered within the KDOM object such that it can be processed in a sequential manner. If the source is not a valid XML document a parsing exception it thrown.

Parameters:
source - this is the XML document source to be parsed
charset - this is the charset to read the stream with
Throws:
java.lang.Exception

parse

public void parse(java.io.Reader source)
           throws java.lang.Exception
This is used to parse the provided source document. This will parse the provided document source using KDOM and then traverse each element encountered within the KDOM object such that it can be processed in a sequential manner. If the source is not a valid XML document a parsing exception it thrown.

Parameters:
source - this is the XML document source to be parsed
Throws:
java.lang.Exception

parse

public void parse(org.kxml2.kdom.Element source)
           throws java.lang.Exception
This is used to parse the provided KDOM element. In order to parse a KDOM element sucessfully the parser needs to initialize itself, before processing the XML elements. This will ensure that the start method is invoked before the KDOM object is traversed. Once the traversal has finished the parser can commit all data using the finish method.

Parameters:
source - this is the XML document that is to be parsed
Throws:
java.lang.Exception

parse

public void parse(Node source)
           throws java.lang.Exception
This method is provided as a convinience for parsing the node provided. This will simply call parse(Element) with the element taken from the given node. This will be used if an XML parser wishes to delegate to another, which can be done by simply invoking this method with a visited node

Parameters:
source - this is the XML element thay is to be parsed
Throws:
java.lang.Exception

traverse

protected void traverse(org.kxml2.kdom.Element node)
                 throws java.lang.Exception
This method is used to traverse all KDOM nodes acquired. This allows the document to be processed element by element. Each node is extracted and processed from the provided object in order of appearence. So data is build up sequentially and the parsing procedure can construct its view of the XML document.

Parameters:
node - this is the KDOM element to be traversed
Throws:
java.lang.Exception

traverse

protected void traverse(org.kxml2.kdom.Element node,
                        int count)
                 throws java.lang.Exception
This method is used to traverse all KDOM nodes acquired. This allows the document to be processed element by element. Each node is extracted and processed from the provided object in order of appearence. So data is build up sequentially and the parsing procedure can construct its view of the XML document.

Parameters:
node - this is the KDOM node list to be traversed
count - this is the number of elements to traverse
Throws:
java.lang.Exception

commit

protected void commit(Node node)
               throws java.lang.Exception
Once an element and all its child elements have been processed this method is invoked to close the processing of the element. This is useful when data accumulated needs to be committed. It allows properties and attributes collected during the processing of the element used for larger data structures.

Parameters:
node - this is the node that has just finished traversal
Throws:
java.lang.Exception

finish

protected void finish()
               throws java.lang.Exception
When all elements of the KDOM have been traversed this method is used to perform post processing of the collected data. This is used to commit any lingering data structures and to perform operations other than those involved in parsing.

Throws:
java.lang.Exception

start

protected abstract void start()
                       throws java.lang.Exception
This is used to initialize the XML parser. This is invoked before any of the elements are processed. It allows all data structures to be created for processing and collecting the attributes and values of processed elements. This is abstract and must be implemented by an XML parser object.

Throws:
java.lang.Exception

process

protected abstract void process(Node node)
                         throws java.lang.Exception
This is used to process an element from the KDOM document. The element provided to this method can be used to collect data which can later be used to construct data structures based on the XML document. Typically an implementation of this will examine the node name and process the element based on that.

Parameters:
node - this is the node that is to be processed by this
Throws:
java.lang.Exception