Class SAXBuilder
- java.lang.Object
-
- org.jdom2.input.SAXBuilder
-
- All Implemented Interfaces:
SAXEngine
public class SAXBuilder extends java.lang.Object implements SAXEngine
Builds a JDOM Document using a SAX parser.SAXbuilder uses a third-party SAX parser (chosen by JAXP by default, or you can configure it manually) to handle the parsing duties and uses an instance of a SAXHandler to listen to the SAX events in order to construct a document with JDOM content using a JDOMFactory. Information about SAX can be found at http://www.saxproject.org.
For a complete description of how SAXBuilder is used, and how to customise the process you should look at the
org.jdom2.input.sax
package documentation.JDOM users needing to customise the SAX parsing process have traditionally sub-classed this SAXBuilder class. In JDOM2 this should never be necessary. Please read the full documentation of this class,
SAXHandler
,SAXHandlerFactory
,JDOMFactory
, and the package documentation fororg.jdom2.input.sax
before overriding this class. Future versions of JDOM2 may make this class 'final'. I you feel you have a good reason to subclass SAXBuilder please mention it on jdom-interest mailing list so that SAXBuilder can be extended or adapted to handle your use-case.Neither SAXBuilder nor anything derived from SAXBuilder is thread-safe. You must ensure that SAXBuilder is used in a single thread, or that sufficient locking is in place to ensure that SAXBuilder is not concurrently accessed. See the special note on
buildEngine()
.Known issues:
- Author:
- Jason Hunter, Brett McLaughlin, Dan Schaffer, Philip Nelson, Alex Rosen, Rolf Lear
- See Also:
org.jdom2.input.sax
-
-
Constructor Summary
Constructors Constructor Description SAXBuilder()
Creates a new JAXP-based SAXBuilder.SAXBuilder(boolean validate)
Deprecated.useSAXBuilder(XMLReaderJDOMFactory)
with eitherXMLReaders.DTDVALIDATING
orXMLReaders.NONVALIDATING
SAXBuilder(java.lang.String saxDriverClass)
Deprecated.SAXBuilder(java.lang.String saxDriverClass, boolean validate)
Deprecated.SAXBuilder(XMLReaderJDOMFactory readersouce)
Creates a new SAXBuilder with the specified XMLReaderJDOMFactory.SAXBuilder(XMLReaderJDOMFactory xmlreaderfactory, SAXHandlerFactory handlerfactory, JDOMFactory jdomfactory)
Creates a new SAXBuilder.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated 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.SAXEngine
buildEngine()
This method builds a new and reusableSAXEngine
.protected void
configureParser(org.xml.sax.XMLReader parser, SAXHandler contentHandler)
This configures the XMLReader to be used for reading the XML document.protected org.xml.sax.XMLReader
createParser()
Allow overriding classes access to the Parser before it is used in a SAXBuilderEngine.java.lang.String
getDriverClass()
Deprecated.as the driver class is only available in limited situations and anyway it had to be supplied in a constructor as either a direct value or as anXMLReaderSAX2Factory
instance.org.xml.sax.DTDHandler
getDTDHandler()
Returns theDTDHandler
assigned, or null if the assignedSAXHandler
will be used for DTD SAX events.org.xml.sax.EntityResolver
getEntityResolver()
Returns theEntityResolver
assigned, or null if none.org.xml.sax.ErrorHandler
getErrorHandler()
Returns theErrorHandler
assigned, or null if none.boolean
getExpandEntities()
Returns whether or not entities are being expanded into normal text content.JDOMFactory
getFactory()
Deprecated.as it is replaced bygetJDOMFactory()
boolean
getIgnoringBoundaryWhitespace()
Returns whether or not the parser will eliminate element content containing only whitespace.boolean
getIgnoringElementContentWhitespace()
Returns whether element content whitespace is to be ignored during the build.JDOMFactory
getJDOMFactory()
Returns the currentJDOMFactory
in use.boolean
getReuseParser()
Returns whether the contained SAX parser instance is reused across multiple parses.SAXHandlerFactory
getSAXHandlerFactory()
Get the SAXHandlerFactory used to supply SAXHandlers to this SAXBuilder.boolean
getValidation()
Deprecated.in lieu ofisValidating()
org.xml.sax.XMLFilter
getXMLFilter()
Returns theXMLFilter
used during parsing, or null if none.XMLReaderJDOMFactory
getXMLReaderFactory()
Get the current XMLReader factory.boolean
isValidating()
Returns whether validation is to be performed during the build.void
setDTDHandler(org.xml.sax.DTDHandler dtdHandler)
This sets custom DTDHandler for theBuilder
.void
setEntityResolver(org.xml.sax.EntityResolver entityResolver)
This sets custom EntityResolver for theBuilder
.void
setErrorHandler(org.xml.sax.ErrorHandler errorHandler)
This sets custom ErrorHandler for the Builder.void
setExpandEntities(boolean expand)
This sets whether or not to expand entities for the builder.void
setFactory(JDOMFactory factory)
Deprecated.as it is replaced bysetJDOMFactory(JDOMFactory)
void
setFastReconfigure(boolean fastReconfigure)
Deprecated.All reused Parsers are now fast-reconfigured.void
setFeature(java.lang.String name, boolean value)
This sets a feature on the SAX parser.void
setIgnoringBoundaryWhitespace(boolean ignoringBoundaryWhite)
Specifies whether or not the parser should eliminate boundary whitespace, a term that indicates whitespace-only text between element tags.void
setIgnoringElementContentWhitespace(boolean ignoringWhite)
Specifies whether or not the parser should eliminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document.void
setJDOMFactory(JDOMFactory factory)
This sets a custom JDOMFactory for the builder.void
setProperty(java.lang.String name, java.lang.Object value)
This sets a property on the SAX parser.void
setReuseParser(boolean reuseParser)
Specifies whether this builder will reuse the same SAX parser when performing subsequent parses or allocate a new parser for each parse.void
setSAXHandlerFactory(SAXHandlerFactory factory)
Set the SAXHandlerFactory to be used by this SAXBuilder.void
setValidation(boolean validate)
Deprecated.void
setXMLFilter(org.xml.sax.XMLFilter xmlFilter)
This sets a customXMLFilter
for the builder.void
setXMLReaderFactory(XMLReaderJDOMFactory rfac)
Set the current XMLReader factory.
-
-
-
Constructor Detail
-
SAXBuilder
public SAXBuilder()
Creates a new JAXP-based SAXBuilder. The underlying parser will not validate.
-
SAXBuilder
@Deprecated public SAXBuilder(boolean validate)
Deprecated.useSAXBuilder(XMLReaderJDOMFactory)
with eitherXMLReaders.DTDVALIDATING
orXMLReaders.NONVALIDATING
Creates a new JAXP-based SAXBuilder. The underlying parser will validate (using DTD) or not according to the given parameter. If you want Schema validation then use SAXBuilder(XMLReaders.XSDVALIDATOR)- Parameters:
validate
-boolean
indicating if DTD validation should occur.- See Also:
SAXBuilder(XMLReaderJDOMFactory, SAXHandlerFactory, JDOMFactory)
,XMLReaders.NONVALIDATING
,XMLReaders.DTDVALIDATING
,DefaultSAXHandlerFactory
,DefaultJDOMFactory
,for important details on SAXBuilder
-
SAXBuilder
@Deprecated public SAXBuilder(java.lang.String saxDriverClass)
Deprecated.Creates a new SAXBuilder using the specified SAX parser. The underlying parser will not validate.- Parameters:
saxDriverClass
-String
name of SAX Driver to use for parsing.- See Also:
SAXBuilder(XMLReaderJDOMFactory, SAXHandlerFactory, JDOMFactory)
,XMLReaderSAX2Factory
,DefaultSAXHandlerFactory
,DefaultJDOMFactory
,for important details on SAXBuilder
-
SAXBuilder
@Deprecated public SAXBuilder(java.lang.String saxDriverClass, boolean validate)
Deprecated.Creates a new SAXBuilder using the specified SAX2.0 parser source. The underlying parser will validate or not according to the given parameter.- Parameters:
saxDriverClass
-String
name of SAX Driver to use for parsing.validate
-boolean
indicating if validation should occur.- See Also:
SAXBuilder(XMLReaderJDOMFactory, SAXHandlerFactory, JDOMFactory)
,XMLReaderSAX2Factory
,DefaultSAXHandlerFactory
,DefaultJDOMFactory
,for important details on SAXBuilder
-
SAXBuilder
public SAXBuilder(XMLReaderJDOMFactory readersouce)
Creates a new SAXBuilder with the specified XMLReaderJDOMFactory.- Parameters:
readersouce
- theXMLReaderJDOMFactory
that supplies XMLReaders. If the value is null then a Non-Validating JAXP-based SAX2.0 parser will be used.- See Also:
SAXBuilder(XMLReaderJDOMFactory, SAXHandlerFactory, JDOMFactory)
,XMLReaderJDOMFactory
,XMLReaders.NONVALIDATING
,DefaultSAXHandlerFactory
,DefaultJDOMFactory
,for important details on SAXBuilder
-
SAXBuilder
public SAXBuilder(XMLReaderJDOMFactory xmlreaderfactory, SAXHandlerFactory handlerfactory, JDOMFactory jdomfactory)
Creates a new SAXBuilder. This is the base constructor for all other SAXBuilder constructors: they all find a way to create a JDOMXMLReaderFactory and then call this constructor with that factory, and theDefaultSAXHandlerFactory
andDefaultJDOMFactory
.- Parameters:
xmlreaderfactory
- aXMLReaderJDOMFactory
that creates XMLReaders. Specify null for the default.handlerfactory
- aSAXHandlerFactory
that creates SAXHandlers Specify null for the default.jdomfactory
- aJDOMFactory
that creates JDOM Content. Specify null for the default.- See Also:
XMLReaderJDOMFactory
,XMLReaders.NONVALIDATING
,SAXHandlerFactory
,DefaultSAXHandlerFactory
,JDOMFactory
,DefaultJDOMFactory
,for important details on SAXBuilder
-
-
Method Detail
-
getDriverClass
@Deprecated public java.lang.String getDriverClass()
Deprecated.as the driver class is only available in limited situations and anyway it had to be supplied in a constructor as either a direct value or as anXMLReaderSAX2Factory
instance.Returns the driver class assigned in the constructor, or null if none. The driver class is only available if a SAX2 source was specified. This method is available for backward-compatibility with JDOM 1.x- Returns:
- the driver class assigned in the constructor
-
getFactory
@Deprecated public JDOMFactory getFactory()
Deprecated.as it is replaced bygetJDOMFactory()
Returns the currentJDOMFactory
in use.- Returns:
- the factory in use
-
getJDOMFactory
public JDOMFactory getJDOMFactory()
Returns the currentJDOMFactory
in use.- Specified by:
getJDOMFactory
in interfaceSAXEngine
- Returns:
- the factory in use
-
setFactory
@Deprecated public void setFactory(JDOMFactory factory)
Deprecated.as it is replaced bysetJDOMFactory(JDOMFactory)
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
-
setJDOMFactory
public void setJDOMFactory(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
-
getXMLReaderFactory
public XMLReaderJDOMFactory getXMLReaderFactory()
Get the current XMLReader factory.- Returns:
- the current JDOMXMLReaderFactory
-
setXMLReaderFactory
public void setXMLReaderFactory(XMLReaderJDOMFactory rfac)
Set the current XMLReader factory.- Parameters:
rfac
- the JDOMXMLReaderFactory to set. A null rfac will indicate the defaultXMLReaders.NONVALIDATING
-
getSAXHandlerFactory
public SAXHandlerFactory getSAXHandlerFactory()
Get the SAXHandlerFactory used to supply SAXHandlers to this SAXBuilder.- Returns:
- the current SAXHandlerFactory (never null).
-
setSAXHandlerFactory
public void setSAXHandlerFactory(SAXHandlerFactory factory)
Set the SAXHandlerFactory to be used by this SAXBuilder.- Parameters:
factory
- the required SAXHandlerFactory. A null input factory will request theDefaultSAXHandlerFactory
.
-
getValidation
@Deprecated public boolean getValidation()
Deprecated.in lieu ofisValidating()
Returns whether validation is to be performed during the build.- Returns:
- whether validation is to be performed during the build
-
isValidating
public boolean isValidating()
Returns whether validation is to be performed during the build.- Specified by:
isValidating
in interfaceSAXEngine
- Returns:
- whether validation is to be performed during the build
-
setValidation
@Deprecated public void setValidation(boolean validate)
Deprecated.This sets validation for the builder.Do Not Use
JDOM2 introduces the concept of XMLReader factories. The XMLReader is what determines the type of validation. A simple boolean is not enough to indicate what sort of validation is required. The
setXMLReaderFactory(XMLReaderJDOMFactory)
method provides a means to be more specific about validation.For backward compatibility this method has been retained, but its use is discouraged. It does make some logical choices though. The code is equivalent to:
setXMLReaderFactory(XMLReaders.DTDVALIDATING)
for true, andsetXMLReaderFactory(XMLReaders.NONVALIDATING)
for false.- Parameters:
validate
-boolean
indicating whether validation should occur.- See Also:
setXMLReaderFactory(XMLReaderJDOMFactory)
,XMLReaders.NONVALIDATING
,XMLReaders.DTDVALIDATING
-
getErrorHandler
public org.xml.sax.ErrorHandler getErrorHandler()
Returns theErrorHandler
assigned, or null if none. When the SAXBuilder parses a document it will always have an ErrorHandler but it will be an instance ofBuilderErrorHandler
unless you specify a different ErrorHandler insetErrorHandler(ErrorHandler)
. In other words, a null return value from here indicates a default will be used.- Specified by:
getErrorHandler
in interfaceSAXEngine
- Returns:
- the ErrorHandler assigned, or null if SAXBuilder will create a default ErrorHandler when needed.
-
setErrorHandler
public void setErrorHandler(org.xml.sax.ErrorHandler errorHandler)
This sets custom ErrorHandler for the Builder. Setting a null value will indicate SAXBuilder should create a default ErrorHandler when needed.- Parameters:
errorHandler
-ErrorHandler
-
getEntityResolver
public org.xml.sax.EntityResolver getEntityResolver()
Returns theEntityResolver
assigned, or null if none.- Specified by:
getEntityResolver
in interfaceSAXEngine
- Returns:
- the EntityResolver assigned
-
setEntityResolver
public void setEntityResolver(org.xml.sax.EntityResolver entityResolver)
This sets custom EntityResolver for theBuilder
.- Parameters:
entityResolver
-EntityResolver
-
getDTDHandler
public org.xml.sax.DTDHandler getDTDHandler()
Returns theDTDHandler
assigned, or null if the assignedSAXHandler
will be used for DTD SAX events.- Specified by:
getDTDHandler
in interfaceSAXEngine
- Returns:
- the DTDHandler assigned
-
setDTDHandler
public void setDTDHandler(org.xml.sax.DTDHandler dtdHandler)
This sets custom DTDHandler for theBuilder
. Setting a null value indicates that SAXBuilder should use the assigned SAXHandler for DTD processing.- Parameters:
dtdHandler
-DTDHandler
-
getXMLFilter
public org.xml.sax.XMLFilter getXMLFilter()
Returns theXMLFilter
used during parsing, or null if none.- Returns:
- the XMLFilter used during parsing
-
setXMLFilter
public void setXMLFilter(org.xml.sax.XMLFilter xmlFilter)
This sets a customXMLFilter
for the builder.Care should be taken to ensure that the specified xmlFilter is reentrant and thread-safe.
SAXBuilder will set this instance as the parent instance for all XMLReaders that may be created, and these may (depending on SAXBuilder usage) be accessed concurrently. It is the responsibility of the JDOM user to ensure that if the XMLFilter is not thread-safe then neither the SAXBuilder nor any of its SAXEngines are accessed concurrently.
- Parameters:
xmlFilter
- the XMLFilter to use
-
getIgnoringElementContentWhitespace
public boolean getIgnoringElementContentWhitespace()
Returns whether element content whitespace is to be ignored during the build.- Specified by:
getIgnoringElementContentWhitespace
in interfaceSAXEngine
- Returns:
- whether element content whitespace is to be ignored during the build
-
setIgnoringElementContentWhitespace
public void setIgnoringElementContentWhitespace(boolean ignoringWhite)
Specifies whether or not the parser should eliminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document. Only whitespace which is contained within element content that has an element only content model will be eliminated (see XML Rec 3.2.1). For this setting to take effect requires that validation be turned on. The default value of this setting isfalse
.- Parameters:
ignoringWhite
- Whether to ignore ignorable whitespace
-
getIgnoringBoundaryWhitespace
public boolean getIgnoringBoundaryWhitespace()
Returns whether or not the parser will eliminate element content containing only whitespace.- Specified by:
getIgnoringBoundaryWhitespace
in interfaceSAXEngine
- Returns:
boolean
- whether only whitespace content will be ignored during build.- See Also:
setIgnoringBoundaryWhitespace(boolean)
-
setIgnoringBoundaryWhitespace
public void setIgnoringBoundaryWhitespace(boolean ignoringBoundaryWhite)
Specifies whether or not the parser should eliminate boundary whitespace, a term that indicates whitespace-only text between element tags. This feature is a lot likesetIgnoringElementContentWhitespace(boolean)
but this feature is more aggressive and doesn't require validation be turned on. ThesetIgnoringElementContentWhitespace(boolean)
call impacts the SAX parse process while this method impacts the JDOM build process, so it can be beneficial to turn both on for efficiency. For implementation efficiency, this method actually removes all whitespace-only text() nodes. That can, in some cases (like between an element tag and a comment) include whitespace that isn't just boundary whitespace. The default isfalse
.- Parameters:
ignoringBoundaryWhite
- Whether to ignore whitespace-only text nodes
-
getExpandEntities
public boolean getExpandEntities()
Returns whether or not entities are being expanded into normal text content.- Specified by:
getExpandEntities
in interfaceSAXEngine
- Returns:
- whether entities are being expanded
-
setExpandEntities
public void setExpandEntities(boolean expand)
This sets whether or not to expand entities for the builder. A true means to expand entities as normal content. A false means to leave entities unexpanded as
EntityRef
objects. The default is true.When this setting is false, the internal DTD subset is retained; when this setting is true, the internal DTD subset is not retained.
Note that Xerces (at least up to 1.4.4) has a bug where entities in attribute values will be incorrectly reported if this flag is turned off, resulting in entities appearing within element content. When turning entity expansion off either avoid entities in attribute values, or use another parser like Crimson. http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6111
- Parameters:
expand
-boolean
indicating whether entity expansion should occur.
-
getReuseParser
public boolean getReuseParser()
Returns whether the contained SAX parser instance is reused across multiple parses. The default is true.- Returns:
- whether the contained SAX parser instance is reused across multiple parses
-
setReuseParser
public void setReuseParser(boolean reuseParser)
Specifies whether this builder will reuse the same SAX parser when performing subsequent parses or allocate a new parser for each parse. The default value of this setting istrue
(parser reuse).Note: SAX parser instances are not thread safe (they are not even reentrant), and nor are SAXBuilder instances. Setting parser reuse does not imply the parser is thread-safe.
- Parameters:
reuseParser
- Whether to reuse the SAX parser.
-
setFastReconfigure
@Deprecated public void setFastReconfigure(boolean fastReconfigure)
Deprecated.All reused Parsers are now fast-reconfigured. No need to set it.Specifies whether this builder will do fast reconfiguration of the underlying SAX parser when reuseParser is true. This improves performance in cases where SAXBuilders are reused and lots of small documents are frequently parsed. This avoids attempting to set features on the SAX parser each time build() is called which result in SaxNotRecognizedExceptions. This should ONLY be set for builders where this specific case is an issue. The default value of this setting isfalse
(no fast reconfiguration). If reuseParser is false, calling this has no effect.- Parameters:
fastReconfigure
- Whether to do a fast reconfiguration of the parser
-
setFeature
public void setFeature(java.lang.String name, boolean value)
This sets a feature on the SAX parser. See the SAX documentation for more information.NOTE: SAXBuilder requires that some particular features of the SAX parser be set up in certain ways for it to work properly. The list of such features may change in the future. Therefore, the use of this method may cause parsing to break, and even if it doesn't break anything today it might break parsing in a future JDOM version, because what JDOM parsers require may change over time. Use with caution.
JDOM usesXMLReaderJDOMFactory
instances to provide XMLReader instances. If you require special configuration on your XMLReader you should consider extending or implementing an XMLReaderJDOMFactory in theorg.jdom2.input.sax
package.- Parameters:
name
- The feature name, which is a fully-qualified URI.value
- The requested state of the feature (true or false).
-
setProperty
public void setProperty(java.lang.String name, java.lang.Object value)
This sets a property on the SAX parser. See the SAX documentation for more information.NOTE: SAXBuilder requires that some particular properties of the SAX parser be set up in certain ways for it to work properly. The list of such properties may change in the future. Therefore, the use of this method may cause parsing to break, and even if it doesn't break anything today it might break parsing in a future JDOM version, because what JDOM parsers require may change over time. Use with caution.
JDOM usesXMLReaderJDOMFactory
instances to provide XMLReader instances. If you require special configuration on your XMLReader you should consider extending or implementing an XMLReaderJDOMFactory in theorg.jdom2.input.sax
package.- Parameters:
name
- The property name, which is a fully-qualified URI.value
- The requested value for the property.
-
buildEngine
public SAXEngine buildEngine() throws JDOMException
This method builds a new and reusableSAXEngine
. Each time this method is called a new instance of a SAXEngine will be returned.This method is used internally by the various SAXBuilder.build(*) methods (if any configuration has changed) but can also be used as a mechanism for creating SAXEngines to be used in parsing pools or other optimised structures.
- Returns:
- a
SAXEngine
representing the current state of the current SAXBuilder settings. - Throws:
JDOMException
- if there is any problem initialising the engine.
-
createParser
protected org.xml.sax.XMLReader createParser() throws JDOMException
Allow overriding classes access to the Parser before it is used in a SAXBuilderEngine.- Returns:
- a XMLReader parser.
- Throws:
JDOMException
- if there is a problem
-
configureParser
protected void configureParser(org.xml.sax.XMLReader parser, SAXHandler contentHandler) throws JDOMException
This configures the XMLReader to be used for reading the XML document.The default implementation sets various options on the given XMLReader, such as validation, DTD resolution, entity handlers, etc., according to the options that were set (e.g. via
setEntityResolver
) and set various SAX properties and features that are required for JDOM internals. These features may change in future releases, so change this behavior at your own risk.- Parameters:
parser
- the XMLReader to configure.contentHandler
- The SAXHandler to use for the XMLReader- Throws:
JDOMException
- if configuration fails.
-
build
public Document build(org.xml.sax.InputSource in) throws JDOMException, java.io.IOException
This builds a document from the supplied input source.- Specified by:
build
in interfaceSAXEngine
- Parameters:
in
-InputSource
to read from- Returns:
Document
resultant Document object- Throws:
JDOMException
- when errors occur in parsingjava.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
This builds a document from the supplied input stream.
- Specified by:
build
in interfaceSAXEngine
- Parameters:
in
-InputStream
to read from- Returns:
Document
resultant Document object- Throws:
JDOMException
- when errors occur in parsingjava.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
This builds a document from the supplied filename.
- Specified by:
build
in interfaceSAXEngine
- Parameters:
file
-File
to read from- Returns:
Document
resultant Document object- Throws:
JDOMException
- when errors occur in parsingjava.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
This builds a document from the supplied URL.
- Specified by:
build
in interfaceSAXEngine
- Parameters:
url
-URL
to read from.- Returns:
Document
- resultant Document object.- Throws:
JDOMException
- when errors occur in parsingjava.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
This builds a document from the supplied input stream.
- Specified by:
build
in interfaceSAXEngine
- Parameters:
in
-InputStream
to read from.systemId
- base for resolving relative URIs- Returns:
Document
resultant Document object- Throws:
JDOMException
- when errors occur in parsingjava.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
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 interfaceSAXEngine
- Parameters:
characterStream
-Reader
to read from- Returns:
Document
resultant Document object- Throws:
JDOMException
- when errors occur in parsingjava.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
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 interfaceSAXEngine
- Parameters:
characterStream
-Reader
to read from.systemId
- base for resolving relative URIs- Returns:
Document
resultant Document object- Throws:
JDOMException
- when errors occur in parsingjava.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
This builds a document from the supplied URI. The URI is typically a file name, or a URL. Do not use this method for parsing XML content that is in a Java String variable.
- Right:
....build("path/to/file.xml");
- Right:
....build("http://my.example.com/xmlfile");
- Wrong:
....build("<root>data</root>");
....build(new StringReader("<root>data</root>"));
- Specified by:
build
in interfaceSAXEngine
- Parameters:
systemId
- URI for the input- Returns:
Document
resultant Document object- Throws:
JDOMException
- when errors occur in parsingjava.io.IOException
- when an I/O error prevents a document from being fully parsed
- Right:
-
-