SAXReader
creates a DOM4J tree from SAX parsing events.
The actual SAX parser that is used by this class is configurable so you can
use your favourite SAX parser if you wish. DOM4J comes configured with its
own SAX parser so you do not need to worry about configuring the SAX parser.
To explicitly configure the SAX parser that is used via Java code you can use
a constructor or use the
setXMLReader(XMLReader)
or
setXMLReaderClassName(String)
methods.
If the parser is not specified explicitly then the standard SAX policy of
using the
org.xml.sax.driver
system property is used to
determine the implementation class of
XMLReader
.
If the
org.xml.sax.driver
system property is not defined then
JAXP is used via reflection (so that DOM4J is not explicitly dependent on the
JAXP classes) to load the JAXP configured SAXParser. If there is any error
creating a JAXP SAXParser an informational message is output and then the
default (Aelfred) SAX parser is used instead.
If you are trying to use JAXP to explicitly set your SAX parser and are
experiencing problems, you can turn on verbose error reporting by defining
the system property
org.dom4j.verbose
to be "true" which will
output a more detailed description of why JAXP could not find a SAX parser
For more information on JAXP please go to
Sun's Java & XML site
SAXReader
public SAXReader()
SAXReader
public SAXReader(String xmlReaderClassName)
throws SAXException
SAXReader
public SAXReader(String xmlReaderClassName,
boolean validating)
throws SAXException
SAXReader
public SAXReader(XMLReader xmlReader)
SAXReader
public SAXReader(XMLReader xmlReader,
boolean validating)
SAXReader
public SAXReader(boolean validating)
addHandler
public void addHandler(String path,
ElementHandler handler)
Adds the ElementHandler
to be called when the specified
path is encounted.
path
- is the path to be handledhandler
- is the ElementHandler
to be called by the event
based processor.
configureReader
protected void configureReader(XMLReader reader,
DefaultHandler handler)
throws DocumentException
Configures the XMLReader before use
reader
- DOCUMENT ME!handler
- DOCUMENT ME!
createContentHandler
protected SAXContentHandler createContentHandler(XMLReader reader)
Factory Method to allow user derived SAXContentHandler objects to be used
createDefaultEntityResolver
protected EntityResolver createDefaultEntityResolver(String systemId)
createXMLReader
protected XMLReader createXMLReader()
throws SAXException
Factory Method to allow alternate methods of creating and configuring
XMLReader objects
getDispatchHandler
protected org.dom4j.io.DispatchHandler getDispatchHandler()
getDocumentFactory
public DocumentFactory getDocumentFactory()
DOCUMENT ME!
- the
DocumentFactory
used to create document
objects
getEncoding
public String getEncoding()
Returns encoding used for InputSource (null means system default
encoding)
- encoding used for InputSource
getEntityResolver
public EntityResolver getEntityResolver()
Returns the current entity resolver used to resolve entities
getErrorHandler
public ErrorHandler getErrorHandler()
DOCUMENT ME!
- the
ErrorHandler
used by SAX
getXMLFilter
public XMLFilter getXMLFilter()
Returns the SAX filter being used to filter SAX events.
- the SAX filter being used or null if no SAX filter is installed
getXMLReader
public XMLReader getXMLReader()
throws SAXException
DOCUMENT ME!
- the
XMLReader
used to parse SAX events
installXMLFilter
protected XMLReader installXMLFilter(XMLReader reader)
Installs any XMLFilter objects required to allow the SAX event stream to
be filtered and preprocessed before it gets to dom4j.
- the new XMLFilter if applicable or the original XMLReader if no
filter is being used.
isIgnoreComments
public boolean isIgnoreComments()
Returns whether we should ignore comments or not.
isIncludeExternalDTDDeclarations
public boolean isIncludeExternalDTDDeclarations()
DOCUMENT ME!
- whether external DTD declarations should be expanded into the
DocumentType object or not.
isIncludeInternalDTDDeclarations
public boolean isIncludeInternalDTDDeclarations()
DOCUMENT ME!
- whether internal DTD declarations should be expanded into the
DocumentType object or not.
isMergeAdjacentText
public boolean isMergeAdjacentText()
Returns whether adjacent text nodes should be merged together.
- Value of property mergeAdjacentText.
isStringInternEnabled
public boolean isStringInternEnabled()
Sets whether String interning is enabled or disabled for element &
attribute names and namespace URIs. This proprety is enabled by default.
isStripWhitespaceText
public boolean isStripWhitespaceText()
Sets whether whitespace between element start and end tags should be
ignored
- Value of property stripWhitespaceText.
isValidating
public boolean isValidating()
DOCUMENT ME!
- the validation mode, true if validating will be done otherwise
false.
read
public Document read(File file)
throws DocumentException
Reads a Document from the given File
file
- is the File
to read from.
- the newly created Document instance
read
public Document read(InputSource in)
throws DocumentException
Reads a Document from the given InputSource
using SAX
in
- InputSource
to read from.
- the newly created Document instance
read
public Document read(InputStream in)
throws DocumentException
Reads a Document from the given stream using SAX
in
- InputStream
to read from.
- the newly created Document instance
read
public Document read(InputStream in,
String systemId)
throws DocumentException
Reads a Document from the given stream using SAX
in
- InputStream
to read from.systemId
- is the URI for the input
- the newly created Document instance
read
public Document read(Reader reader)
throws DocumentException
Reads a Document from the given Reader
using SAX
reader
- is the reader for the input
- the newly created Document instance
read
public Document read(Reader reader,
String systemId)
throws DocumentException
Reads a Document from the given Reader
using SAX
reader
- is the reader for the inputsystemId
- is the URI for the input
- the newly created Document instance
read
public Document read(String systemId)
throws DocumentException
Reads a Document from the given URL or filename using SAX.
If the systemId contains a
':'
character then it is
assumed to be a URL otherwise its assumed to be a file name. If you want
finer grained control over this mechansim then please explicitly pass in
either a
URL
or a
File
instance instead of a
String
to denote the source of the document.
systemId
- is a URL for a document or a file name.
- the newly created Document instance
read
public Document read(URL url)
throws DocumentException
Reads a Document from the given URL
using SAX
- the newly created Document instance
removeHandler
public void removeHandler(String path)
Removes the ElementHandler
from the event based processor,
for the specified path.
path
- is the path to remove the ElementHandler
for.
resetHandlers
public void resetHandlers()
This method clears out all the existing handlers and default handler
setting things back as if no handler existed. Useful when reusing an
object instance.
setDefaultHandler
public void setDefaultHandler(ElementHandler handler)
When multiple ElementHandler
instances have been
registered, this will set a default ElementHandler
to be
called for any path which does NOT have a handler registered.
handler
- is the ElementHandler
to be called by the event
based processor.
setDispatchHandler
protected void setDispatchHandler(org.dom4j.io.DispatchHandler dispatchHandler)
setDocumentFactory
public void setDocumentFactory(DocumentFactory documentFactory)
This sets the
DocumentFactory
used to create new
documents. This method allows the building of custom DOM4J tree objects
to be implemented easily using a custom derivation of
DocumentFactory
documentFactory
- DocumentFactory
used to create DOM4J objects
setEncoding
public void setEncoding(String encoding)
Sets encoding used for InputSource (null means system default encoding)
encoding
- is encoding used for InputSource
setEntityResolver
public void setEntityResolver(EntityResolver entityResolver)
Sets the entity resolver used to resolve entities.
entityResolver
- DOCUMENT ME!
setErrorHandler
public void setErrorHandler(ErrorHandler errorHandler)
Sets the ErrorHandler
used by the SAX
XMLReader
.
errorHandler
- is the ErrorHandler
used by SAX
setFeature
public void setFeature(String name,
boolean value)
throws SAXException
Sets a SAX feature on the underlying SAX parser. This can be useful to
set parser-specific features. Though use this method with caution as it
has the possibility of breaking the standard behaviour. An alternative to
calling this method is to correctly configure an XMLReader object
instance and call the
setXMLReader(XMLReader)
method
name
- is the SAX feature namevalue
- is the value of the SAX feature
setIgnoreComments
public void setIgnoreComments(boolean ignoreComments)
Sets whether we should ignore comments or not.
ignoreComments
- whether we should ignore comments or not.
setIncludeExternalDTDDeclarations
public void setIncludeExternalDTDDeclarations(boolean include)
Sets whether DTD external declarations should be expanded into the
DocumentType object or not.
include
- whether or not DTD declarations should be expanded and
included into the DocumentType object.
setIncludeInternalDTDDeclarations
public void setIncludeInternalDTDDeclarations(boolean include)
Sets whether internal DTD declarations should be expanded into the
DocumentType object or not.
include
- whether or not DTD declarations should be expanded and
included into the DocumentType object.
setMergeAdjacentText
public void setMergeAdjacentText(boolean mergeAdjacentText)
Sets whether or not adjacent text nodes should be merged together when
parsing.
mergeAdjacentText
- New value of property mergeAdjacentText.
setProperty
public void setProperty(String name,
Object value)
throws SAXException
Allows a SAX property to be set on the underlying SAX parser. This can be
useful to set parser-specific properties such as the location of schema
or DTD resources. Though use this method with caution as it has the
possibility of breaking the standard behaviour. An alternative to calling
this method is to correctly configure an XMLReader object instance and
call the
setXMLReader(XMLReader)
method
name
- is the SAX property namevalue
- is the value of the SAX property
setStringInternEnabled
public void setStringInternEnabled(boolean stringInternEnabled)
Sets whether String interning is enabled or disabled for element &
attribute names and namespace URIs
stringInternEnabled
- DOCUMENT ME!
setStripWhitespaceText
public void setStripWhitespaceText(boolean stripWhitespaceText)
Sets whether whitespace between element start and end tags should be
ignored.
stripWhitespaceText
- New value of property stripWhitespaceText.
setValidation
public void setValidation(boolean validation)
Sets the validation mode.
validation
- indicates whether or not validation should occur.
setXMLFilter
public void setXMLFilter(XMLFilter filter)
Sets the SAX filter to be used when filtering SAX events
filter
- is the SAX filter to use or null to disable filtering
setXMLReader
public void setXMLReader(XMLReader reader)
Sets the XMLReader
used to parse SAX events
reader
- is the XMLReader
to parse SAX events
setXMLReaderClassName
public void setXMLReaderClassName(String xmlReaderClassName)
throws SAXException
Sets the class name of the XMLReader
to be used to parse
SAX events.
xmlReaderClassName
- is the class name of the XMLReader
to parse SAX
events