JDOM 2.0.6.1 · org.jdom2.input.StAXStreamBuilder

Builds a JDOM Document from a StAX-based XMLStreamReader.

XMLStreamReaders are pre-configured and as a result JDOM is not able to alter whether the input is validated, or whether the Stream has escaped entities or not. These (and other) characteristics are configurable by setting the correct features and properties on the XMLInputFactory when it is used to create the XMLStreamReader.

Useful configuration to set, or know about is:

StAX streams seldom differentiate between Text and CDATA content. You will likely want to configure your StAX factory (XMLInputFactory) with http://java.sun.com/xml/stream/properties/report-cdata-event for the default Java StAX implementation, or the equivalent property for your StAX engine.
The remaining XMLInputFactory settings are likely to work fine at their default values.
StAX is not likely to be your best option if you want a validating parser, at least not with the default (built-in Java implementation in Java6 which does not support it). Consider a SAX parser.

From a JDOM perspective XMLStreamReaders are more efficient than XMLEventReaders. Where possible use an XMLStreamReader.

If you happen to be looking at the source code, pay careful attention to the imports so you know what type of instance is being processed, whether it is a StAX class, or a JDOM class, because there are name conflicts.

Field Summary

Modifier and Type	Field and Description
private JDOMFactory	builderfactory The factory to use for parsing

Constructor Summary

Access	Constructor and Description
public	StAXStreamBuilder()

Method Summary

Modifier and Type	Method and Description
public Document	Returns: `Document` resultant Document object build(XMLStreamReader `XMLStreamReader` to read from reader) This builds a document from the supplied XMLStreamReader.
public List<Content>	Returns: a List of Content that were identified by the supplied filter buildFragments(XMLStreamReader The XMLStreamReader to parse reader, StAXFilter The Filter to use for the Content filter) Read the entire XMLStreamReader and from it build a list of Content that conforms to the rules in the supplied StAXFilter.
public Content	Returns: The JDOM fragment at the current position in the reader fragment(XMLStreamReader The XMLStreamReader to read the next fragment from reader) Read the current XML Fragment from the XMLStreamReader.
public JDOMFactory	Returns: the factory in use getFactory() Returns the current `org.jdom2.JDOMFactory` in use.
private static final Document	Returns: the parsed Document process(final JDOMFactory The `JDOMFactory` to use factory, final XMLStreamReader The XMLStreamReader to read from stream) Create a Document from an XMLStreamReader
private static final Element	processElement(final JDOMFactory factory, final XMLStreamReader reader)
private static final Element	processElementFragment(final JDOMFactory factory, final XMLStreamReader reader)
private static final Content	Returns: the parsed Document processFragment(final JDOMFactory The `JDOMFactory` to use factory, final XMLStreamReader The XMLStreamReader to read from stream) Create a Content from an XMLStreamReader The stream is advanced to the event after the current event (or to the event after the matching END_ELEMENT for an Element fragment).
private List<Content>	processFragments(JDOMFactory factory, XMLStreamReader stream, StAXFilter filter)
private static final Element	processPrunableElement(final JDOMFactory factory, final XMLStreamReader reader, final int topdepth, StAXFilter filter)
public void	setFactory(JDOMFactory `JDOMFactory` to use factory) This sets a custom JDOMFactory for the builder.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

builderfactory	back to summary
private JDOMFactory builderfactory The factory to use for parsing

Constructor Detail

StAXStreamBuilder	back to summary
public StAXStreamBuilder()

Method Detail

build back to summary

build	back to summary
public Document build(XMLStreamReader reader) throws JDOMException This builds a document from the supplied XMLStreamReader. The JDOMContent will be built by the current JDOMFactory. Parameters reader:XMLStreamReader `XMLStreamReader` to read from Returns:Document `Document` resultant Document object Exceptions JDOMException: when errors occur in parsing

public Document build(XMLStreamReader reader) throws JDOMException

This builds a document from the supplied XMLStreamReader.

The JDOMContent will be built by the current JDOMFactory.

Parameters

reader:XMLStreamReader: XMLStreamReader to read from

Returns:Document

Document resultant Document object

Exceptions

JDOMException:: when errors occur in parsing

buildFragments	back to summary
public List<Content> buildFragments(XMLStreamReader reader, StAXFilter filter) throws JDOMException Read the entire XMLStreamReader and from it build a list of Content that conforms to the rules in the supplied StAXFilter. Parameters reader:XMLStreamReader The XMLStreamReader to parse filter:StAXFilter The Filter to use for the Content Returns:List<Content> a List of Content that were identified by the supplied filter Exceptions JDOMException: if there was a parsing problem.

buildFragments

back to summary

public List<Content> buildFragments(XMLStreamReader reader, StAXFilter filter) throws JDOMException

Read the entire XMLStreamReader and from it build a list of Content that conforms to the rules in the supplied StAXFilter.

Parameters

reader:XMLStreamReader: The XMLStreamReader to parse
filter:StAXFilter: The Filter to use for the Content

Returns:List<Content>

a List of Content that were identified by the supplied filter

Exceptions

JDOMException:: if there was a parsing problem.

fragment	back to summary
public Content fragment(XMLStreamReader reader) throws JDOMException Read the current XML Fragment from the XMLStreamReader. The XMLStreamReader must be at some 'content' state, it cannot be at START_DOCUMENT, for example. Parameters reader:XMLStreamReader The XMLStreamReader to read the next fragment from Returns:Content The JDOM fragment at the current position in the reader Exceptions JDOMException: if there is an issue with the state of the XMLStreamReader or some other issue with the processing.

fragment

back to summary

public Content fragment(XMLStreamReader reader) throws JDOMException

Read the current XML Fragment from the XMLStreamReader. The XMLStreamReader must be at some 'content' state, it cannot be at START_DOCUMENT, for example.

Parameters

reader:XMLStreamReader: The XMLStreamReader to read the next fragment from

Returns:Content

The JDOM fragment at the current position in the reader

Exceptions

JDOMException:: if there is an issue with the state of the XMLStreamReader or some other issue with the processing.

getFactory back to summary

getFactory	back to summary
public JDOMFactory getFactory() Returns the current `org.jdom2.JDOMFactory` in use. Returns:JDOMFactory the factory in use

public JDOMFactory getFactory()

Returns the current org.jdom2.JDOMFactory in use.

Returns:JDOMFactory: the factory in use

process back to summary

process	back to summary
private static final Document process(final JDOMFactory factory, final XMLStreamReader stream) throws JDOMException Create a Document from an XMLStreamReader Parameters factory:JDOMFactory The `JDOMFactory` to use stream:XMLStreamReader The XMLStreamReader to read from Returns:Document the parsed Document Exceptions JDOMException: if there is any issue (XMLStreamExceptions are wrapped).

private static final Document process(final JDOMFactory factory, final XMLStreamReader stream) throws JDOMException

Create a Document from an XMLStreamReader

Parameters

factory:JDOMFactory: The JDOMFactory to use
stream:XMLStreamReader: The XMLStreamReader to read from

Returns:Document

the parsed Document

Exceptions

JDOMException:: if there is any issue (XMLStreamExceptions are wrapped).

processElement	back to summary
private static final Element processElement(final JDOMFactory factory, final XMLStreamReader reader)

processElementFragment	back to summary
private static final Element processElementFragment(final JDOMFactory factory, final XMLStreamReader reader) throws XMLStreamException, JDOMException

processFragment back to summary

processFragment	back to summary
private static final Content processFragment(final JDOMFactory factory, final XMLStreamReader stream) throws JDOMException Create a Content from an XMLStreamReader The stream is advanced to the event after the current event (or to the event after the matching END_ELEMENT for an Element fragment). Parameters factory:JDOMFactory The `JDOMFactory` to use stream:XMLStreamReader The XMLStreamReader to read from Returns:Content the parsed Document Exceptions JDOMException: if there is any issue (XMLStreamExceptions are wrapped).

private static final Content processFragment(final JDOMFactory factory, final XMLStreamReader stream) throws JDOMException

Create a Content from an XMLStreamReader The stream is advanced to the event after the current event (or to the event after the matching END_ELEMENT for an Element fragment).

Parameters

factory:JDOMFactory: The JDOMFactory to use
stream:XMLStreamReader: The XMLStreamReader to read from

Returns:Content

the parsed Document

Exceptions

JDOMException:: if there is any issue (XMLStreamExceptions are wrapped).

processFragments	back to summary
private List<Content> processFragments(JDOMFactory factory, XMLStreamReader stream, StAXFilter filter) throws JDOMException

processPrunableElement	back to summary
private static final Element processPrunableElement(final JDOMFactory factory, final XMLStreamReader reader, final int topdepth, StAXFilter filter) throws XMLStreamException, JDOMException

setFactory back to summary

setFactory	back to summary
public void setFactory(JDOMFactory factory) This sets a custom JDOMFactory for the builder. Use this to build the tree with your own subclasses of the JDOM classes. Parameters factory:JDOMFactory `JDOMFactory` to use

public void setFactory(JDOMFactory factory)

This sets a custom JDOMFactory for the builder. Use this to build the tree with your own subclasses of the JDOM classes.

Parameters

factory:JDOMFactory: JDOMFactory to use

public Class StAXStreamBuilder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail