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

java.lang.Object
  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