public class SAXReader extends 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 |
Modifier and Type | Field and Description |
---|---|
private DispatchHandler |
dispatchHandler
DispatchHandler to call when each
Element is encountered |
private EntityResolver |
entityResolver
The entity resolver
|
private ErrorHandler |
errorHandler
ErrorHandler class to use
|
private DocumentFactory |
factory
DocumentFactory used to create new document objects |
private boolean |
includeExternalDTDDeclarations
Should external DTD declarations be expanded into a List in the DTD
|
private boolean |
includeInternalDTDDeclarations
Should internal DTD declarations be expanded into a List in the DTD
|
private boolean |
mergeAdjacentText
Whether adjacent text nodes should be merged
|
private boolean |
stringInternEnabled
Should element & attribute names and namespace URIs be interned?
|
private boolean |
stripWhitespaceText
Holds value of property stripWhitespaceText.
|
private boolean |
validating
Whether validation should occur
|
private XMLFilter |
xmlFilter
The SAX filter used to filter SAX events
|
private XMLReader |
xmlReader
XMLReader used to parse the SAX events |
Constructor and Description |
---|
SAXReader() |
SAXReader(boolean validating) |
SAXReader(DocumentFactory factory) |
SAXReader(DocumentFactory factory,
boolean validating) |
SAXReader(String xmlReaderClassName) |
SAXReader(String xmlReaderClassName,
boolean validating) |
SAXReader(XMLReader xmlReader) |
SAXReader(XMLReader xmlReader,
boolean validating) |
Modifier and Type | Method and Description |
---|---|
void |
addHandler(String path,
ElementHandler handler)
Adds the
ElementHandler to be called when the
specified path is encounted. |
protected void |
configureReader(XMLReader reader,
DefaultHandler contentHandler)
Configures the XMLReader before use
|
protected SAXContentHandler |
createContentHandler(XMLReader reader)
Factory Method to allow user derived SAXContentHandler objects to be used
|
protected EntityResolver |
createDefaultEntityResolver(String documentSystemId) |
protected XMLReader |
createXMLReader()
Factory Method to allow alternate methods of
creating and configuring XMLReader objects
|
protected DispatchHandler |
getDispatchHandler() |
DocumentFactory |
getDocumentFactory() |
EntityResolver |
getEntityResolver()
Returns the current entity resolver used to resolve entities
|
ErrorHandler |
getErrorHandler() |
XMLFilter |
getXMLFilter()
Returns the SAX filter being used to filter SAX events.
|
XMLReader |
getXMLReader() |
protected XMLReader |
installXMLFilter(XMLReader xmlReader)
Installs any XMLFilter objects required to allow the SAX event stream
to be filtered and preprocessed before it gets to dom4j.
|
boolean |
isIncludeExternalDTDDeclarations() |
boolean |
isIncludeInternalDTDDeclarations() |
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 |
read(File file)
Reads a Document from the given
File |
Document |
read(InputSource in)
Reads a Document from the given
InputSource using SAX |
Document |
read(InputStream in)
Reads a Document from the given stream using SAX
|
Document |
read(InputStream in,
String systemId)
Reads a Document from the given stream using SAX
|
Document |
read(Reader reader)
Reads a Document from the given
Reader using SAX |
Document |
read(Reader reader,
String SystemId)
Reads a Document from the given
Reader using SAX |
Document |
read(String systemId)
Reads a Document from the given URL or filename using SAX.
|
Document |
read(URL url)
Reads a Document from the given
URL using SAX |
void |
removeHandler(String path)
Removes the
ElementHandler from the event based
processor, for the specified path. |
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(DispatchHandler dispatchHandler) |
void |
setDocumentFactory(DocumentFactory factory)
This sets the
DocumentFactory used to create new documents. |
void |
setEntityResolver(EntityResolver entityResolver)
Sets the entity resolver used to resolve entities.
|
void |
setErrorHandler(ErrorHandler errorHandler)
Sets the
ErrorHandler used by the SAX
XMLReader . |
void |
setFeature(String name,
boolean value)
Allows a SAX featuer on the underlying SAX parser.
|
void |
setIncludeExternalDTDDeclarations(boolean includeExternalDTDDeclarations)
Sets whether DTD external declarations should be expanded into the DocumentType
object or not.
|
void |
setIncludeInternalDTDDeclarations(boolean includeInternalDTDDeclarations)
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(String name,
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 validating)
Sets the validation mode.
|
void |
setXMLFilter(XMLFilter xmlFilter)
Sets the SAX filter to be used when filtering SAX events
|
void |
setXMLReader(XMLReader xmlReader)
Sets the
XMLReader used to parse SAX events |
void |
setXMLReaderClassName(String xmlReaderClassName)
Sets the class name of the
XMLReader to be used
to parse SAX events. |
private DocumentFactory factory
DocumentFactory
used to create new document objectsprivate boolean validating
private DispatchHandler dispatchHandler
Element
is encounteredprivate ErrorHandler errorHandler
private EntityResolver entityResolver
private boolean stringInternEnabled
private boolean includeInternalDTDDeclarations
private boolean includeExternalDTDDeclarations
private boolean mergeAdjacentText
private boolean stripWhitespaceText
public SAXReader()
public SAXReader(boolean validating)
public SAXReader(DocumentFactory factory)
public SAXReader(DocumentFactory factory, boolean validating)
public SAXReader(String xmlReaderClassName) throws SAXException
SAXException
public SAXReader(String xmlReaderClassName, boolean validating) throws SAXException
SAXException
public void setProperty(String name, Object value) throws SAXException
setXMLReader(XMLReader)
methodSAXException
- if the XMLReader could not be created or
the property could not be changed.public void setFeature(String name, boolean value) throws SAXException
setXMLReader(XMLReader)
methodSAXException
- if the XMLReader could not be created or
the feature could not be changed.public Document read(File file) throws DocumentException, MalformedURLException
Reads a Document from the given File
file
- is the File
to read from.DocumentException
- if an error occurs during parsing.MalformedURLException
- if a URL could not be made for the given Filepublic Document read(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(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(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(Reader reader) throws DocumentException
Reads a Document from the given Reader
using SAX
reader
- is the reader for the inputDocumentException
- if an error occurs during parsing.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 inputDocumentException
- if an error occurs during parsing.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 inputDocumentException
- if an error occurs during parsing.public Document read(InputSource in) throws DocumentException
Reads a Document from the given InputSource
using SAX
in
- InputSource
to read from.systemId
- is the URI for the inputDocumentException
- if an error occurs during parsing.public boolean isValidating()
public void setValidation(boolean validating)
validating
- indicates whether or not validation should occur.public boolean isIncludeInternalDTDDeclarations()
public void setIncludeInternalDTDDeclarations(boolean includeInternalDTDDeclarations)
includeInternalDTDDeclarations
- whether or not DTD declarations should be expanded
and included into the DocumentType object.public boolean isIncludeExternalDTDDeclarations()
public void setIncludeExternalDTDDeclarations(boolean includeExternalDTDDeclarations)
includeInternalDTDDeclarations
- whether or not DTD declarations should be expanded
and included into the DocumentType object.public boolean isStringInternEnabled()
public void setStringInternEnabled(boolean stringInternEnabled)
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 DocumentFactory getDocumentFactory()
DocumentFactory
used to create document objectspublic void setDocumentFactory(DocumentFactory factory)
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
factory
- DocumentFactory
used to create DOM4J objectspublic ErrorHandler getErrorHandler()
ErrorHandler
used by SAXpublic void setErrorHandler(ErrorHandler errorHandler)
ErrorHandler
used by the SAX
XMLReader
.errorHandler
- is the ErrorHandler
used by SAXpublic EntityResolver getEntityResolver()
public void setEntityResolver(EntityResolver entityResolver)
public XMLReader getXMLReader() throws SAXException
XMLReader
used to parse SAX eventsSAXException
public void setXMLReader(XMLReader xmlReader)
XMLReader
used to parse SAX eventsxmlReader
- is the XMLReader
to parse SAX eventspublic void setXMLReaderClassName(String xmlReaderClassName) throws SAXException
XMLReader
to be used
to parse SAX events.xmlReaderClassName
- is the class name of the XMLReader
to parse SAX eventsSAXException
public void addHandler(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(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 XMLFilter getXMLFilter()
public void setXMLFilter(XMLFilter xmlFilter)
xmlFilter
- is the SAX filter to use or null to disable filteringprotected XMLReader installXMLFilter(XMLReader xmlReader)
protected DispatchHandler getDispatchHandler()
protected void setDispatchHandler(DispatchHandler dispatchHandler)
protected XMLReader createXMLReader() throws SAXException
SAXException
protected void configureReader(XMLReader reader, DefaultHandler contentHandler) throws DocumentException
DocumentException
protected SAXContentHandler createContentHandler(XMLReader reader)
protected EntityResolver createDefaultEntityResolver(String documentSystemId)
WebARTS Library Licensed Under the GNU - General Public License. Other Libraries licensed under their respective Open Source Licenses