|PREV PACKAGE NEXT PACKAGE||FRAMES NO FRAMES|
|AbstractReaderXSDFactory.SchemaFactoryProvider||Simple interface makes it easier to pass logic around in static methods.|
|SAXEngine||SAXEngine provides an interface to interact with either the SAXBuilder or the SAXBuilderEngine.|
|SAXHandlerFactory||Provides SAXBuilder with SAXHandler instances to support SAX parsing.|
|XMLReaderJDOMFactory||This interface can be used to supply custom XMLReaders to
|AbstractReaderXSDFactory||This AbstractReaderJDOMFactory class returns XMLReaders configured to validate against the supplied XML Schema (XSD) instance.|
|BuilderErrorHandler||The standard JDOM error handler implementation.|
|DefaultSAXHandlerFactory||This SAXHandlerFactory instance provides default-configured SAXHandler instances for all non-custom situations.|
|SAXBuilderEngine||Builds a JDOM document from files, streams, readers, URLs, or a SAX
|SAXHandler||A support class for
|XMLReaderJAXPFactory||Create XMLReaders directly from the javax.xml.parsers.SAXParserFactory API using an explicit implementation of the parser instead of relying on the default JAXP search path.|
|XMLReaderSAX2Factory||Create XMLReaders directly from the SAX2.0 API using a SAX Driver class name or the default SAX2.0 location process.|
|XMLReaderXSDFactory||This XMLReaderJDOMFactory class returns XMLReaders configured to validate against the supplied XML Schema (XSD) instance.|
|XMLReaders||An enumeration of
Support classes for building JDOM documents and content using SAX parsers.
SAXBuilder class parses input and produces JDOM
output. It does this using three 'pillars' of functionality, which when combined
constitute a 'parse'.
The three pillars are:
SAXBuilder provides a central location where these three pillars are configured. Some configuration settings require coordinated changes to both the SAX parser and the SAX handler, and SAXBuilder ensures the coordination is maintained.
SAXBuilder.SAXBuilder(XMLReaderJDOMFactory, SAXHandlerFactory, org.jdom2.JDOMFactory)
SAXBuilder.SAXBuilder()that chooses a non-validating JAXP sourced XMLReader Factory
XMLReaders.NONVALIDATINGwhich it mates with a Default
SAXHandlerfactory, and the
XMLReaderJDOMFactorywill be used but still use the default SAXHandler and JDOMFactory values.
In addition to the different ways of creating an XML parser, there have also been updates to the way the actual SAX parsing API is exposed to Java (the Java interface). The SAX specification was revised with version 2.0. The 'new' SAX version introduced the XMLReader concept, which replaces the XMLParser concept. These two concepts aim to accomplish the same goal, but do it in different ways.
JDOM 2.x requires an XMLReader (SAX 2.0) interface, thus your XML parser needs to be compatible with SAX 2.0 (for the XMLReader), but should be accessible through JAXP which is the more modern and flexible access system.
The purpose of the XMLReaderJDOMFactory Pillar is to give the SAXBuilder an
XMLReader instance (a SAX 2.0 parser). To get an XMLReader the
SAXBuilder delegates to the
XMLReader instances can be created in a few different ways, and also they can be set to perform the SAX parse in a number of different ways. The classes in this package are designed to make it easier and faster to locate the XMLReader that is suitable for the XML parsing you intend to do. At the same time, if the parsing you intend to do is outside the normal bounds of how JDOM is used, you still have the functionality to create a completely custom mechanism for setting the XMLReader for SAXBuilder.
There are two typical ways to specify and create an XMLReader instance: using JAXP, and using the SAX2.0 API. If necessary you can also create direct instances of XMLReader implementations using 'new' constructors, but each SAX implementation has different class names for their SAX drivers so doing raw constructors is not portable and not recommended.
Where possible it is recommended that you use the JAXP mechanism for obtaining XMLReaders because:
XMLReadersenumeration. These members are 'singletons' that can be used in a multi-threaded and concurrent way to provide XMLReaders that are configured correctly for the respective behaviour.
To parse with a specific (rather than the default) JAXP-based XML Parser
you can use the
XMLReaderJAXPFactory. This factory
can optionally be set to do DTD validation during the parse.
To validate using an arbitrary external Schema you can use the
XMLReaderSchemaFactory to create an instance for
the particular Schema you want to validate against. Because this requires an
input Schema it cannot be constructed as a singleton like the others. There
are constructors that allow you to use a specific (rather than the default)
XMLReaderXSDFactory is a special case of
XMLReaderSchemaFactory which internally uses an efficient mechanism to
compile Schema instances from one or many input XSD documents which can come
from multiple sources. There are constructors that allow you to use a specific
(rather than the default) JAXP-compatible parser.
It should be noted that it is preferable to use JAXP in JDOM because it is a more flexible API that allows more portable code to be created. The JAXP interface in JDOM is also able to support a wider array of functionality out-of-the-box, but the same functionality would require SAX-implementation specific configuration.
JDOM does not provide a pre-configured way to do XML Schema validation through the SAX2.0 API though. The SAX 2.0 API does not expose a convenient way to configure different SAX implementations in a consistent way, so it is up to the JDOM user to wrap the XMLReaderSAX2Factory in such a way that it reconfigures the XMLReader to be appropriate for the task at hand.
XMLReaderJDOMFactoryto provide XMLReaders configured as you like them. It will probably be best if you wrap an existing implementation with your custom code though in order to get the best results fastest.
Note that the existing JDOM implementations described above all set the generated XMLReaders to be namespace-aware and to supply namespace-prefixes. Custom implementations should also ensure that this is set unless you absolutely know what you are doing.
SAXHandlerFactorypillar. It is unusual for a JDOM user to need to customise the manner in which this happens, but, in the event that you do you can create a subclass of the SAXHandler class, and then create an instance of the SAXHandlerFactory that returns new subclass instances. This new factory can become a pillar in SAXBuilder and supply custom SAXHandlers to the parse process.
DefaultJDOMFactory. This factory validates the values being used to create JDOM content. There is also the
UncheckedJDOMFactorywhich does not validate the data, so it should only be used if you are absolutely certain that your SAX source can never provide illegal content. You may have other reasons for creating a custom JDOMFactory such as if you need to create custom versions of JDOM Content like a custom Element subclass.
SAXBuilderto identify what can (by default) be changed easily. Remember, if you have anything that needs to be customised beyond what SAXBuilder offers you can always replace a pillar with a custom implementation.
The setup process involves obtaining an XMLReader from the XMLReaderJDOMFactory and a SAXHandler (configured to use the JDOMFactory) from the SAXHandlerFactory. These two instances are then configured to meet the settings specified on SAXBuilder, and once configured they are 'compiled' in to a SAXBuilderEngine.
The SAXBuilderEngine is a non-configurable 'embodiment' of the configuration of the SAXBuilder when the engine was created, and it contains the entire 'workflow' necessary to parse the input in to JDOM content. Further, it is a guarantee that the XMLReader and SAXHandler instances in the SAXBuilderEngine are never shared with any other engine or entity (assuming that the respective factories never issue the same instances multiple times). There is no guarantee made for the JDOMFactory being unique for each SAXBuilderEngine, but JDOMFactory instances are supposed to be reentrant/thread-safe.
The 'parse' phase starts once the setup phase is complete and the SAXBuilderEngine has been created. The created engine is used to parse the input, and the resulting Document is returned to the client.
The 'reset' phase happens after the completion of the 'parse' phase, and it resets the SAXBuilderEngine to its initial state, ready to process the next parse request.
JDOM2 uses the new SAXBuilderEngine to represent the state of the SAXBuilder at the moment prior to the parse. SAXBuilder will then 'remember' and reuse this exact SAXBuilderEngine until something changes in the SAXBuilder configuration. As soon as the configuration changes in any way the engine will be forgotten and a new one will be created when the SAXBuilder next parses a document.
If you turn off parser reuse with
SAXBuilder.setReuseParser(boolean) then SAXBuilder will
immediately forget the engine, and it will also forget it after each build (i.e.
SAXBuilder will create a new SAXBuilderEngine each parse).
It follows then that as long as you do not change the SAXBuilder configuration then the SAXBuilder will always reuse the same SAXBuilderEngine. This is very efficient because there is no configuration management between parses, and the procedure completely eliminates the 'setup' component for all but the first parse.
SAXBuilder.buildEngine()and you can get a newly created SAXBuilderEngine instance. The SAXBuilderEngine has the same 'build' methods as SAXBuilder, and these are exposed as the
SAXEngineinterface. Both SAXBuilder and SAXBuilderEngine implement the SAXEngine interface. Thus, if you use Parser pools you can pool either the SAXBuilder or the SAXBuilderEngine in the same pool.
It is most likely though that what you will want to do is to create a single
SAXBuilder that represents the configuration you want, and then you can use this
single SAXBuilder to create multiple SAXEngines as you need them in the pool by
SAXBuilder sb = new SAXBuilder(); Document doc = sb.build(new File("file.xml"));
Create a DTD validating SAXBuilder and parse a document:
SAXBuilder sb = new SAXBuilder(XMLReaders.DTDVALIDATING); Document doc = sb.build(new File("file.xml"));Create an XSD (XML Schema) validating SAXBuilder using the XSD references inside the XML document and parse a document:
SAXBuilder sb = new SAXBuilder(XMLReaders.XSDVALIDATING); Document doc = sb.build(new File("file.xml"));
Create an XSD (XML Schema) validating SAXBuilder the hard way (see the next
example for an easier way) using an external XSD and parse a document
SchemaFactory schemafac = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI); Schema schema = schemafac.newSchema(new File("myschema.xsd")); XMLReaderJDOMFactory factory = new XMLReaderSchemaFactory(schema); SAXBuilder sb = new SAXBuilder(factory); Document doc = sb.build(new File("file.xml"));
Create an XSD (XML Schema) validating SAXBuilder the easy way
File xsdfile = new File("myschema.xsd"); XMLReaderJDOMFactory factory = new XMLReaderXSDFactory(xsdfile); SAXBuilder sb = new SAXBuilder(factory); Document doc = sb.build(new File("file.xml"));
|PREV PACKAGE NEXT PACKAGE||FRAMES NO FRAMES|