Builds a JDOM Document from a StAX-based XMLEventReader.
XMLEventReaders are pre-configured and as a result JDOM is not able to
alter whether the input is validated, or whether the Events have 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 Events 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.