org.compass.core.xml.jdom.converter.support
Class StAXBuilder

java.lang.Object
  extended by org.compass.core.xml.jdom.converter.support.StAXBuilder

public class StAXBuilder
extends Object

Builds a JDOM org.jdom.Document using a XMLStreamReader.

Author:
kimchy

Nested Class Summary
static class StAXBuilder.IndentRemover
           
 
Field Summary
(package private) static HashMap<String,Integer> attrTypes
          Map that contains conversion from textual attribute types StAX uses, to int values JDOM uses.
protected  boolean cfgIgnoreWS
          Whether ignorable white space should be ignored, ie not added in the resulting JDOM tree.
protected  StAXTextModifier textModifier
          Object that will be used when trying to remove indentation white space: if so, the object is consulted to figure out what consistutes indentation white space, as well as about context in which such white space is to be removed.
 
Constructor Summary
StAXBuilder()
          Default constructor.
 
Method Summary
 org.jdom.Document build(javax.xml.stream.XMLStreamReader r)
          This will build a JDOM tree given a StAX stream reader.
protected  void buildTree(org.jdom.JDOMFactory f, javax.xml.stream.XMLStreamReader r, org.jdom.Document doc, StAXTextModifier tmod)
          This takes a XMLStreamReader and builds up a JDOM tree.
 org.jdom.JDOMFactory getFactory()
          Returns the current JDOMFactory in use, if one has been previously set with setFactory(org.jdom.JDOMFactory), otherwise null.
protected  boolean isIndentationWhitespace(javax.xml.stream.XMLStreamReader r)
          Method called when option is turned on; to determine if current CHARACTERS event looks like it might be used for indentation purposes (it is all white space, and is either immediately after a start element, or could be immediately before a start element).
static void main(String[] args)
          Trivial test driver for testing functionality.
 void setFactory(org.jdom.JDOMFactory f)
           
 void setIgnoreWhitespace(boolean state)
          Method used to set value of cfgIgnoreWS; that is, to make parser either remove ignorable white space (true), or to include it (false).
 void setRemoveIndentation(boolean state)
          Method used to enable or disable automatic heuristic removal of indentation white If set to true, the builder will try to remove white space that seems to be used for indentation purposes; otherwise it will not try to do any removal.
 void setTextModifier(StAXTextModifier mod)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

attrTypes

static final HashMap<String,Integer> attrTypes
Map that contains conversion from textual attribute types StAX uses, to int values JDOM uses.


cfgIgnoreWS

protected boolean cfgIgnoreWS
Whether ignorable white space should be ignored, ie not added in the resulting JDOM tree. If true, it will be ignored; if false, it will be added in the tree. Default value if false.


textModifier

protected StAXTextModifier textModifier
Object that will be used when trying to remove indentation white space: if so, the object is consulted to figure out what consistutes indentation white space, as well as about context in which such white space is to be removed.

Note that only such text events (CHARACTERS) are considered that are not known to be fully ignorable (ignorable white space would be reported as SPACE) by this removal process. SPACE events can be trimmed simply by setting cfgIgnoreWS to true.

Constructor Detail

StAXBuilder

public StAXBuilder()
Default constructor.

Method Detail

setFactory

public void setFactory(org.jdom.JDOMFactory f)

setTextModifier

public void setTextModifier(StAXTextModifier mod)

setIgnoreWhitespace

public void setIgnoreWhitespace(boolean state)
Method used to set value of cfgIgnoreWS; that is, to make parser either remove ignorable white space (true), or to include it (false).

Whether all-whitespace text segment is ignorable white space or not is based on DTD read in, as per XML specifications (white space is only significant in mixed content or pure text elements).


setRemoveIndentation

public void setRemoveIndentation(boolean state)
Method used to enable or disable automatic heuristic removal of indentation white If set to true, the builder will try to remove white space that seems to be used for indentation purposes; otherwise it will not try to do any removal.

Note that this setting only applies to all-whitespace segments that have NOT been determined to be ignorable white space (either because DTD is not available, or because such white space is in mixed or text-only element content). As such it is a heuristics that should only be enabled when application knows that such white space removal does not cause problems.

Also note that internally the method calls setTextModifier(org.compass.core.xml.jdom.converter.support.StAXTextModifier) with either the default text modifier (true), or with null (false).


getFactory

public org.jdom.JDOMFactory getFactory()
Returns the current JDOMFactory in use, if one has been previously set with setFactory(org.jdom.JDOMFactory), otherwise null.

Returns:
the factory builder will use

build

public org.jdom.Document build(javax.xml.stream.XMLStreamReader r)
                        throws javax.xml.stream.XMLStreamException
This will build a JDOM tree given a StAX stream reader.

Parameters:
r - Stream reader from which input is read.
Returns:
Document - JDOM document object.
Throws:
javax.xml.stream.XMLStreamException - If the reader threw such exception (to indicate a parsing or I/O problem)

buildTree

protected void buildTree(org.jdom.JDOMFactory f,
                         javax.xml.stream.XMLStreamReader r,
                         org.jdom.Document doc,
                         StAXTextModifier tmod)
                  throws javax.xml.stream.XMLStreamException
This takes a XMLStreamReader and builds up a JDOM tree. Recursion has been eliminated by using nodes' parent/child relationship; this improves performance somewhat (classic recursion-by-iteration-and-explicit stack transformation)

Parameters:
f - Node factory to use for creating JDOM nodes
r - Stream reader to use for reading the document from which to build the tree
doc - JDOM Document being built.
tmod - Text modifier to use for modifying content of text nodes (CHARACTERS, not CDATA), if any; null if no modifications are needed (modifier is usually used for trimming unnecessary but non-ignorable white space).
Throws:
javax.xml.stream.XMLStreamException

isIndentationWhitespace

protected boolean isIndentationWhitespace(javax.xml.stream.XMLStreamReader r)
                                   throws javax.xml.stream.XMLStreamException
Method called when option is turned on; to determine if current CHARACTERS event looks like it might be used for indentation purposes (it is all white space, and is either immediately after a start element, or could be immediately before a start element).

The default implementation just checks whether the text segment (known to be all white space) starts with a linefeed character.

Throws:
javax.xml.stream.XMLStreamException

main

public static void main(String[] args)
                 throws Exception
Trivial test driver for testing functionality.

Throws:
Exception


Copyright (c) 2004-2008 The Compass Project.