Java XML – JDOM2 – SAXBuilder

The Plot

SAXBuilder provides methods to build JDOM2 Documents using a
third party SAX Parser. It has three parts

  • A SAX Parser to parse the XML document. The default Parser is
  • A SAX Handler to handle SAX events.
  • A JDOM2 Factory to build the JDOM2 Document

This tutorial introduces the various classes that form part of the SAXBuilder suite. The understanding of these classes is important if you want to customize any part of the process. i.e. if you want to validate the XML (DTD, XMLSchema, etc.), if you want to use a different SAX parser or if you want your own SAXHandler or JDOM2 Factory.

The Actors (Classes)

  • SAXBuilder – This is what the tutorial is all about.
    The following constructors are available:

    • SAXBuilder() – Uses the default parser, SAX Handler and
      JDOM2 Factory
    • SAXBuilder(final XMLReaderJDOMFactory readersouce) – Specify
      a factory to create an XMLReader. Users can also specify any of the
      three enum singletons : XMLReaders.NONVALIDATING,
      XMLReaders.DTDVALIDATING and XMLReaders.XSDVALIDATING. What this
      does is tell the parsers whether it should be validating the XML and
      if it should use DTD or XSD for validation.
    • SAXBuilder(final XMLReaderJDOMFactory xmlreaderfactory,
      final SAXHandlerFactory handlerfactory,final JDOMFactory
      jdomfactory) – Uses custom factories for parsing, SAX event handling
      and JDOM2 document building

    The most important methods are build(…). When you call the
    build methods the builder will first get the SAXEngine and then call
    the build method of the SAXEngine. The build method of the SAXEngine
    calls the parser to parse the xml. The SAXEngine has access to the
    SAXHandler and JDOM2 Factory and it starts building the JDOM2 Document
    as it parses the XML

  • SAXBuilderEngine – This is created by the SAXBuilder
    and it parses the XML and builds a JDOM2 Document. In high performance
    applications you can reuse the SAXBuilderEngine multiple times without
    any parser reconfiguration overhead, and you can create multiple
    SAXBuilderEngine instances from a single configured SAXBuilder.
  • XMLReaderJDOMFactory – This factory creates the
    XMLReaders (parsers). The createXMLReader()
    method creates the XMLReaders. This method is called by the SAXBuilder
    when it builds the SAXEngine.There are five implementations provided
    (though you can add your own custom ones if needed). Three of them are
    singletons of the enum org.jdom2.input.sax.XMLReaders. Lets
    look at them first

      – These are
      singleton enums for performance and convenience. They use the
      standard Java JAXP process for identifying and instantiating the XML
      parser to use, and the different singletons will either perform no
      XML Validation (just the regular well-formedness checks), DTD
      Validation, or XMLSchema validation.
    • org.jdom2.input.sax.XMLReaderSchemaFactory
      – Use this factory if you want to create an XMLReader that uses an
      external schema for validation. The schema can be any schema that is
      supported by SAX.
    • org.jdom2.input.sax.XMLReaderXSDFactory
      – Use this factory if you want to create an XMLReader that uses an
      external XML Schema for validation
  • SAXHandlerFactory – Instances of this factory are
    responsible for creating Handlers that handle SAX events (fired by the
    SAX Parser). Let us look at the various classes that take part in SAX
    event handling process

    • DefaultSAXHandlerFactory – This is the default
      implementation of SAXHandlerFactory. It returns the
      DefaultSAXHandler which is just a wrapper over
    • SAXHandler – This class is responsible for handling
      SAX events produced by the XMLReader. It also takes in the
      JDOMFactory. If the XMLReader supports document locator for line and
      column number then the SAXHandler will supply that to the
  • JDOMFactory– This is the last piece of the puzzle.
    Instances of this factory create the JDOM2 Classes that are part of
    the JDOM2 structure. The important classes are :

    • org.jdom2.DefaultJDOMFactory – This creates the
      standard JDOM2 classes.
    • org.jdom2.LocatedJDOMFactory – This creates the JDOM2
      classes that have implemented the org.jdom2.located.Located
    • org.jdom2.SlimJDOMFactory – This creates the JDOM2
      content that occupies less memory by reusing string instances

Leave a Comment