Class StAXEventBuilder


  • public class StAXEventBuilder
    extends java.lang.Object
    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.

    Author:
    Rolf Lear
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Document build​(javax.xml.stream.XMLEventReader events)
      This builds a document from the supplied XMLEventReader.
      JDOMFactory getFactory()
      Returns the current JDOMFactory in use.
      void setFactory​(JDOMFactory factory)
      This sets a custom JDOMFactory for the builder.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • StAXEventBuilder

        public StAXEventBuilder()
    • Method Detail

      • getFactory

        public JDOMFactory getFactory()
        Returns the current JDOMFactory in use.
        Returns:
        the factory in use
      • setFactory

        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 to use
      • build

        public Document build​(javax.xml.stream.XMLEventReader events)
                       throws JDOMException
        This builds a document from the supplied XMLEventReader.

        The JDOMContent will be built by the current JDOMFactory.

        Parameters:
        events - XMLEventReader to read from
        Returns:
        Document resultant Document object
        Throws:
        JDOMException - when errors occur in parsing