Class SAXBuilderEngine

  • All Implemented Interfaces:
    SAXEngine

    public class SAXBuilderEngine
    extends java.lang.Object
    implements SAXEngine
    Builds a JDOM document from files, streams, readers, URLs, or a SAX InputSource instance using a SAX parser. This Engine is built by the SAXBuilder based on the state of the SAXBuilder when the engine was produced. It is not possible to reconfigure the engine once built, but it can be reused many times (though not concurrently). This makes it the fastest way to process many multitudes of XML documents (if those documents are all parsed the same way). If you want to process in multiple threads you can safely have one SAXBuilderEngine in each thread on the condition that:
    1. The JDOMFactory is thread-safe (the JDOM-supplied JDOMFactories are)
    2. There is no XMLFilter given to the SAXBuilder, or, if there is, then it is thread-safe.
    3. If you have a custom XMLReaderJDOMFactory that it supplies a new instance of an XMLReader on each call (the JDOM-supplied ones all do).
    4. If you have a custom SAXHandlerFactory that it supplies a new instance of a SAXHanfler on each call (the JDOM-supplied one does)
    Author:
    Rolf Lear
    See Also:
    org.jdom2.input.sax
    • Constructor Summary

      Constructors 
      Constructor Description
      SAXBuilderEngine​(org.xml.sax.XMLReader reader, SAXHandler handler, boolean validating)
      Creates a new SAXBuilderEngine.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Document build​(java.io.File file)
      This builds a document from the supplied filename.
      Document build​(java.io.InputStream in)
      This builds a document from the supplied input stream.
      Document build​(java.io.InputStream in, java.lang.String systemId)
      This builds a document from the supplied input stream.
      Document build​(java.io.Reader characterStream)
      This builds a document from the supplied Reader.
      Document build​(java.io.Reader characterStream, java.lang.String systemId)
      This builds a document from the supplied Reader.
      Document build​(java.lang.String systemId)
      This builds a document from the supplied URI.
      Document build​(java.net.URL url)
      This builds a document from the supplied URL.
      Document build​(org.xml.sax.InputSource in)
      This builds a document from the supplied input source.
      org.xml.sax.DTDHandler getDTDHandler()
      Returns the DTDHandler assigned, or null if none.
      org.xml.sax.EntityResolver getEntityResolver()
      Returns the EntityResolver assigned, or null if none.
      org.xml.sax.ErrorHandler getErrorHandler()
      Returns the ErrorHandler assigned, or null if none.
      boolean getExpandEntities()
      Returns whether or not entities are being expanded into normal text content.
      boolean getIgnoringBoundaryWhitespace()
      Returns whether or not the parser will elminate element content containing only whitespace.
      boolean getIgnoringElementContentWhitespace()
      Returns whether element content whitespace is to be ignored during the build.
      JDOMFactory getJDOMFactory()
      Returns the current JDOMFactory in use.
      boolean isValidating()
      Returns whether validation is to be performed during the build.
      • Methods inherited from class java.lang.Object

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

      • SAXBuilderEngine

        public SAXBuilderEngine​(org.xml.sax.XMLReader reader,
                                SAXHandler handler,
                                boolean validating)
        Creates a new SAXBuilderEngine.
        Parameters:
        reader - The XMLReader this Engine parses with
        handler - The SAXHandler that processes the SAX Events.
        validating - True if this is a validating system.
    • Method Detail

      • isValidating

        public boolean isValidating()
        Description copied from interface: SAXEngine
        Returns whether validation is to be performed during the build.
        Specified by:
        isValidating in interface SAXEngine
        Returns:
        whether validation is to be performed during the build
      • getErrorHandler

        public org.xml.sax.ErrorHandler getErrorHandler()
        Description copied from interface: SAXEngine
        Returns the ErrorHandler assigned, or null if none.
        Specified by:
        getErrorHandler in interface SAXEngine
        Returns:
        the ErrorHandler assigned, or null if none
      • getEntityResolver

        public org.xml.sax.EntityResolver getEntityResolver()
        Description copied from interface: SAXEngine
        Returns the EntityResolver assigned, or null if none.
        Specified by:
        getEntityResolver in interface SAXEngine
        Returns:
        the EntityResolver assigned
      • getDTDHandler

        public org.xml.sax.DTDHandler getDTDHandler()
        Description copied from interface: SAXEngine
        Returns the DTDHandler assigned, or null if none.
        Specified by:
        getDTDHandler in interface SAXEngine
        Returns:
        the DTDHandler assigned
      • getIgnoringElementContentWhitespace

        public boolean getIgnoringElementContentWhitespace()
        Description copied from interface: SAXEngine
        Returns whether element content whitespace is to be ignored during the build.
        Specified by:
        getIgnoringElementContentWhitespace in interface SAXEngine
        Returns:
        whether element content whitespace is to be ignored during the build
      • getIgnoringBoundaryWhitespace

        public boolean getIgnoringBoundaryWhitespace()
        Description copied from interface: SAXEngine
        Returns whether or not the parser will elminate element content containing only whitespace.
        Specified by:
        getIgnoringBoundaryWhitespace in interface SAXEngine
        Returns:
        boolean - whether only whitespace content will be ignored during build.
      • getExpandEntities

        public boolean getExpandEntities()
        Description copied from interface: SAXEngine
        Returns whether or not entities are being expanded into normal text content.
        Specified by:
        getExpandEntities in interface SAXEngine
        Returns:
        whether entities are being expanded
      • build

        public Document build​(org.xml.sax.InputSource in)
                       throws JDOMException,
                              java.io.IOException
        Description copied from interface: SAXEngine
        This builds a document from the supplied input source.
        Specified by:
        build in interface SAXEngine
        Parameters:
        in - InputSource to read from
        Returns:
        Document resultant Document object
        Throws:
        JDOMException - when errors occur in parsing
        java.io.IOException - when an I/O error prevents a document from being fully parsed
      • build

        public Document build​(java.io.InputStream in)
                       throws JDOMException,
                              java.io.IOException
        Description copied from interface: SAXEngine

        This builds a document from the supplied input stream.

        Specified by:
        build in interface SAXEngine
        Parameters:
        in - InputStream to read from
        Returns:
        Document resultant Document object
        Throws:
        JDOMException - when errors occur in parsing
        java.io.IOException - when an I/O error prevents a document from being fully parsed.
      • build

        public Document build​(java.io.File file)
                       throws JDOMException,
                              java.io.IOException
        Description copied from interface: SAXEngine

        This builds a document from the supplied filename.

        Specified by:
        build in interface SAXEngine
        Parameters:
        file - File to read from
        Returns:
        Document resultant Document object
        Throws:
        JDOMException - when errors occur in parsing
        java.io.IOException - when an I/O error prevents a document from being fully parsed
      • build

        public Document build​(java.net.URL url)
                       throws JDOMException,
                              java.io.IOException
        Description copied from interface: SAXEngine

        This builds a document from the supplied URL.

        Specified by:
        build in interface SAXEngine
        Parameters:
        url - URL to read from.
        Returns:
        Document - resultant Document object.
        Throws:
        JDOMException - when errors occur in parsing
        java.io.IOException - when an I/O error prevents a document from being fully parsed.
      • build

        public Document build​(java.io.InputStream in,
                              java.lang.String systemId)
                       throws JDOMException,
                              java.io.IOException
        Description copied from interface: SAXEngine

        This builds a document from the supplied input stream.

        Specified by:
        build in interface SAXEngine
        Parameters:
        in - InputStream to read from.
        systemId - base for resolving relative URIs
        Returns:
        Document resultant Document object
        Throws:
        JDOMException - when errors occur in parsing
        java.io.IOException - when an I/O error prevents a document from being fully parsed
      • build

        public Document build​(java.io.Reader characterStream)
                       throws JDOMException,
                              java.io.IOException
        Description copied from interface: SAXEngine

        This builds a document from the supplied Reader. It's the programmer's responsibility to make sure the reader matches the encoding of the file. It's often easier and safer to use an InputStream rather than a Reader, and to let the parser auto-detect the encoding from the XML declaration.

        Specified by:
        build in interface SAXEngine
        Parameters:
        characterStream - Reader to read from
        Returns:
        Document resultant Document object
        Throws:
        JDOMException - when errors occur in parsing
        java.io.IOException - when an I/O error prevents a document from being fully parsed
      • build

        public Document build​(java.io.Reader characterStream,
                              java.lang.String systemId)
                       throws JDOMException,
                              java.io.IOException
        Description copied from interface: SAXEngine

        This builds a document from the supplied Reader. It's the programmer's responsibility to make sure the reader matches the encoding of the file. It's often easier and safer to use an InputStream rather than a Reader, and to let the parser auto-detect the encoding from the XML declaration.

        Specified by:
        build in interface SAXEngine
        Parameters:
        characterStream - Reader to read from.
        systemId - base for resolving relative URIs
        Returns:
        Document resultant Document object
        Throws:
        JDOMException - when errors occur in parsing
        java.io.IOException - when an I/O error prevents a document from being fully parsed
      • build

        public Document build​(java.lang.String systemId)
                       throws JDOMException,
                              java.io.IOException
        Description copied from interface: SAXEngine

        This builds a document from the supplied URI.

        Specified by:
        build in interface SAXEngine
        Parameters:
        systemId - URI for the input
        Returns:
        Document resultant Document object
        Throws:
        JDOMException - when errors occur in parsing
        java.io.IOException - when an I/O error prevents a document from being fully parsed