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
  JAXP.
• 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
  • XMLReaders.NONVALIDATING,
    XMLReaders.DTDVALIDATING, XMLReaders.XSDVALIDATING – 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
    org.jdom2.input.sax.SAXHandler
  • 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
• 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
    interface
  • org.jdom2.SlimJDOMFactory – This creates the JDOM2
    content that occupies less memory by reusing string instances