public class SAXReader
extends java.lang.Object
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
Modifier and Type | Class and Description |
---|---|
protected static class |
SAXReader.SAXEntityResolver |
Constructor and Description |
---|
SAXReader()
This method internally calls
SAXParserFactory .newInstance().newSAXParser().getXMLReader() or XMLReaderFactory.createXMLReader() . |
SAXReader(boolean validating)
This method internally calls
SAXParserFactory .newInstance().newSAXParser().getXMLReader() or XMLReaderFactory.createXMLReader() . |
SAXReader(DocumentFactory factory)
This method internally calls
SAXParserFactory .newInstance().newSAXParser().getXMLReader() or XMLReaderFactory.createXMLReader() . |
SAXReader(DocumentFactory factory,
boolean validating)
This method internally calls
SAXParserFactory .newInstance().newSAXParser().getXMLReader() or XMLReaderFactory.createXMLReader() . |
SAXReader(java.lang.String xmlReaderClassName) |
SAXReader(java.lang.String xmlReaderClassName,
boolean validating) |
SAXReader(org.xml.sax.XMLReader xmlReader) |
SAXReader(org.xml.sax.XMLReader xmlReader,
boolean validating) |
Modifier and Type | Method and Description |
---|---|
void |
addHandler(java.lang.String path,
ElementHandler handler)
Adds the
ElementHandler to be called when the specified
path is encounted. |
protected void |
configureReader(org.xml.sax.XMLReader reader,
org.xml.sax.helpers.DefaultHandler handler)
Configures the XMLReader before use
|
protected SAXContentHandler |
createContentHandler(org.xml.sax.XMLReader reader)
Factory Method to allow user derived SAXContentHandler objects to be used
|
static SAXReader |
createDefault() |
protected org.xml.sax.EntityResolver |
createDefaultEntityResolver(java.lang.String systemId) |
protected org.xml.sax.XMLReader |
createXMLReader()
Factory Method to allow alternate methods of creating and configuring
XMLReader objects
|
protected org.dom4j.io.DispatchHandler |
getDispatchHandler() |
DocumentFactory |
getDocumentFactory()
DOCUMENT ME!
|
java.lang.String |
getEncoding()
Returns encoding used for InputSource (null means system default
encoding)
|
org.xml.sax.EntityResolver |
getEntityResolver()
Returns the current entity resolver used to resolve entities
|
org.xml.sax.ErrorHandler |
getErrorHandler()
DOCUMENT ME!
|
org.xml.sax.XMLFilter |
getXMLFilter()
Returns the SAX filter being used to filter SAX events.
|
org.xml.sax.XMLReader |
getXMLReader()
DOCUMENT ME!
|
protected org.xml.sax.XMLReader |
installXMLFilter(org.xml.sax.XMLReader reader)
Installs any XMLFilter objects required to allow the SAX event stream to
be filtered and preprocessed before it gets to dom4j.
|
boolean |
isIgnoreComments()
Returns whether we should ignore comments or not.
|
boolean |
isIncludeExternalDTDDeclarations()
DOCUMENT ME!
|
boolean |
isIncludeInternalDTDDeclarations()
DOCUMENT ME!
|
boolean |
isMergeAdjacentText()
Returns whether adjacent text nodes should be merged together.
|
boolean |
isStringInternEnabled()
Sets whether String interning is enabled or disabled for element &
attribute names and namespace URIs.
|
boolean |
isStripWhitespaceText()
Sets whether whitespace between element start and end tags should be
ignored
|
boolean |
isValidating()
DOCUMENT ME!
|
Document |
read(java.io.File file)
Reads a Document from the given
File
|
Document |
read(org.xml.sax.InputSource in)
Reads a Document from the given
InputSource using SAX
|
Document |
read(java.io.InputStream in)
Reads a Document from the given stream using SAX
|
Document |
read(java.io.InputStream in,
java.lang.String systemId)
Reads a Document from the given stream using SAX
|
Document |
read(java.io.Reader reader)
Reads a Document from the given
Reader using SAX |
Document |
read(java.io.Reader reader,
java.lang.String systemId)
Reads a Document from the given
Reader using SAX
|
Document |
read(java.lang.String systemId)
Reads a Document from the given URL or filename using SAX.
|
Document |
read(java.net.URL url)
Reads a Document from the given
URL using SAX
|
void |
removeHandler(java.lang.String path)
Removes the
ElementHandler from the event based processor,
for the specified path. |
void |
resetHandlers()
This method clears out all the existing handlers and default handler
setting things back as if no handler existed.
|
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. |
protected void |
setDispatchHandler(org.dom4j.io.DispatchHandler dispatchHandler) |
void |
setDocumentFactory(DocumentFactory documentFactory)
This sets the
DocumentFactory used to create new
documents. |
void |
setEncoding(java.lang.String encoding)
Sets encoding used for InputSource (null means system default encoding)
|
void |
setEntityResolver(org.xml.sax.EntityResolver entityResolver)
Sets the entity resolver used to resolve entities.
|
void |
setErrorHandler(org.xml.sax.ErrorHandler errorHandler)
Sets the
ErrorHandler used by the SAX
XMLReader . |
void |
setFeature(java.lang.String name,
boolean value)
Sets a SAX feature on the underlying SAX parser.
|
void |
setIgnoreComments(boolean ignoreComments)
Sets whether we should ignore comments or not.
|
void |
setIncludeExternalDTDDeclarations(boolean include)
Sets whether DTD external declarations should be expanded into the
DocumentType object or not.
|
void |
setIncludeInternalDTDDeclarations(boolean include)
Sets whether internal DTD declarations should be expanded into the
DocumentType object or not.
|
void |
setMergeAdjacentText(boolean mergeAdjacentText)
Sets whether or not adjacent text nodes should be merged together when
parsing.
|
void |
setProperty(java.lang.String name,
java.lang.Object value)
Allows a SAX property to be set on the underlying SAX parser.
|
void |
setStringInternEnabled(boolean stringInternEnabled)
Sets whether String interning is enabled or disabled for element &
attribute names and namespace URIs
|
void |
setStripWhitespaceText(boolean stripWhitespaceText)
Sets whether whitespace between element start and end tags should be
ignored.
|
void |
setValidation(boolean validation)
Sets the validation mode.
|
void |
setXMLFilter(org.xml.sax.XMLFilter filter)
Sets the SAX filter to be used when filtering SAX events
|
void |
setXMLReader(org.xml.sax.XMLReader reader)
Sets the
XMLReader used to parse SAX events |
void |
setXMLReaderClassName(java.lang.String xmlReaderClassName)
Sets the class name of the
XMLReader to be used to parse
SAX events. |
public SAXReader()
SAXParserFactory
.newInstance().newSAXParser().getXMLReader()
or XMLReaderFactory.createXMLReader()
.
Be sure to configure returned reader if the default configuration does not suit you. Consider setting the following properties:
reader.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false); reader.setFeature("http://xml.org/sax/features/external-general-entities", false); reader.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
public SAXReader(boolean validating)
SAXParserFactory
.newInstance().newSAXParser().getXMLReader()
or XMLReaderFactory.createXMLReader()
.
Be sure to configure returned reader if the default configuration does not suit you. Consider setting the following properties:
reader.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false); reader.setFeature("http://xml.org/sax/features/external-general-entities", false); reader.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
validating
- public SAXReader(DocumentFactory factory)
SAXParserFactory
.newInstance().newSAXParser().getXMLReader()
or XMLReaderFactory.createXMLReader()
.
Be sure to configure returned reader if the default configuration does not suit you. Consider setting the following properties:
reader.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false); reader.setFeature("http://xml.org/sax/features/external-general-entities", false); reader.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
factory
- public SAXReader(DocumentFactory factory, boolean validating)
SAXParserFactory
.newInstance().newSAXParser().getXMLReader()
or XMLReaderFactory.createXMLReader()
.
Be sure to configure returned reader if the default configuration does not suit you. Consider setting the following properties:
reader.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false); reader.setFeature("http://xml.org/sax/features/external-general-entities", false); reader.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
factory
- validating
- public SAXReader(org.xml.sax.XMLReader xmlReader)
public SAXReader(org.xml.sax.XMLReader xmlReader, boolean validating)
public SAXReader(java.lang.String xmlReaderClassName) throws org.xml.sax.SAXException
org.xml.sax.SAXException
public SAXReader(java.lang.String xmlReaderClassName, boolean validating) throws org.xml.sax.SAXException
org.xml.sax.SAXException
public static SAXReader createDefault()
public void setProperty(java.lang.String name, java.lang.Object value) throws org.xml.sax.SAXException
setXMLReader(XMLReader)
methodname
- is the SAX property namevalue
- is the value of the SAX propertyorg.xml.sax.SAXException
- if the XMLReader could not be created or the property could
not be changed.public void setFeature(java.lang.String name, boolean value) throws org.xml.sax.SAXException
setXMLReader(XMLReader)
methodname
- is the SAX feature namevalue
- is the value of the SAX featureorg.xml.sax.SAXException
- if the XMLReader could not be created or the feature could
not be changed.public Document read(java.io.File file) throws DocumentException
Reads a Document from the given File
file
- is the File
to read from.DocumentException
- if an error occurs during parsing.public Document read(java.net.URL url) throws DocumentException
Reads a Document from the given URL
using SAX
url
- URL
to read from.DocumentException
- if an error occurs during parsing.public Document read(java.lang.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.DocumentException
- if an error occurs during parsing.public Document read(java.io.InputStream in) throws DocumentException
Reads a Document from the given stream using SAX
in
- InputStream
to read from.DocumentException
- if an error occurs during parsing.public Document read(java.io.Reader reader) throws DocumentException
Reader
using SAXreader
- is the reader for the inputDocumentException
- if an error occurs during parsing.public Document read(java.io.InputStream in, java.lang.String systemId) throws DocumentException
Reads a Document from the given stream using SAX
in
- InputStream
to read from.systemId
- is the URI for the inputDocumentException
- if an error occurs during parsing.public Document read(java.io.Reader reader, java.lang.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 inputDocumentException
- if an error occurs during parsing.public Document read(org.xml.sax.InputSource in) throws DocumentException
Reads a Document from the given InputSource
using SAX
in
- InputSource
to read from.DocumentException
- if an error occurs during parsing.public boolean isValidating()
public void setValidation(boolean validation)
validation
- indicates whether or not validation should occur.public boolean isIncludeInternalDTDDeclarations()
public void setIncludeInternalDTDDeclarations(boolean include)
include
- whether or not DTD declarations should be expanded and
included into the DocumentType object.public boolean isIncludeExternalDTDDeclarations()
public void setIncludeExternalDTDDeclarations(boolean include)
include
- whether or not DTD declarations should be expanded and
included into the DocumentType object.public boolean isStringInternEnabled()
public void setStringInternEnabled(boolean stringInternEnabled)
stringInternEnabled
- DOCUMENT ME!public boolean isMergeAdjacentText()
public void setMergeAdjacentText(boolean mergeAdjacentText)
mergeAdjacentText
- New value of property mergeAdjacentText.public boolean isStripWhitespaceText()
public void setStripWhitespaceText(boolean stripWhitespaceText)
stripWhitespaceText
- New value of property stripWhitespaceText.public boolean isIgnoreComments()
public void setIgnoreComments(boolean ignoreComments)
ignoreComments
- whether we should ignore comments or not.public DocumentFactory getDocumentFactory()
DocumentFactory
used to create document
objectspublic 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 objectspublic org.xml.sax.ErrorHandler getErrorHandler()
ErrorHandler
used by SAXpublic void setErrorHandler(org.xml.sax.ErrorHandler errorHandler)
ErrorHandler
used by the SAX
XMLReader
.errorHandler
- is the ErrorHandler
used by SAXpublic org.xml.sax.EntityResolver getEntityResolver()
public void setEntityResolver(org.xml.sax.EntityResolver entityResolver)
entityResolver
- DOCUMENT ME!public org.xml.sax.XMLReader getXMLReader() throws org.xml.sax.SAXException
XMLReader
used to parse SAX eventsorg.xml.sax.SAXException
- DOCUMENT ME!public void setXMLReader(org.xml.sax.XMLReader reader)
XMLReader
used to parse SAX eventsreader
- is the XMLReader
to parse SAX eventspublic java.lang.String getEncoding()
public void setEncoding(java.lang.String encoding)
encoding
- is encoding used for InputSourcepublic void setXMLReaderClassName(java.lang.String xmlReaderClassName) throws org.xml.sax.SAXException
XMLReader
to be used to parse
SAX events.xmlReaderClassName
- is the class name of the XMLReader
to parse SAX
eventsorg.xml.sax.SAXException
- DOCUMENT ME!public void addHandler(java.lang.String path, ElementHandler handler)
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.public void removeHandler(java.lang.String path)
ElementHandler
from the event based processor,
for the specified path.path
- is the path to remove the ElementHandler
for.public void setDefaultHandler(ElementHandler handler)
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.public void resetHandlers()
public org.xml.sax.XMLFilter getXMLFilter()
public void setXMLFilter(org.xml.sax.XMLFilter filter)
filter
- is the SAX filter to use or null to disable filteringprotected org.xml.sax.XMLReader installXMLFilter(org.xml.sax.XMLReader reader)
reader
- DOCUMENT ME!protected org.dom4j.io.DispatchHandler getDispatchHandler()
protected void setDispatchHandler(org.dom4j.io.DispatchHandler dispatchHandler)
protected org.xml.sax.XMLReader createXMLReader() throws org.xml.sax.SAXException
org.xml.sax.SAXException
- DOCUMENT ME!protected void configureReader(org.xml.sax.XMLReader reader, org.xml.sax.helpers.DefaultHandler handler) throws DocumentException
reader
- DOCUMENT ME!handler
- DOCUMENT ME!DocumentException
- DOCUMENT ME!protected SAXContentHandler createContentHandler(org.xml.sax.XMLReader reader)
reader
- DOCUMENT ME!protected org.xml.sax.EntityResolver createDefaultEntityResolver(java.lang.String systemId)