org.dom4j.io
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 {@link #setXMLReader(XMLReader)}or {@link #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 {@link 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
Version: $Revision: 1.58 $
Nested Class Summary | |
---|---|
protected static class | SAXReader.SAXEntityResolver |
Constructor Summary | |
---|---|
SAXReader() | |
SAXReader(boolean validating) | |
SAXReader(DocumentFactory factory) | |
SAXReader(DocumentFactory factory, boolean validating) | |
SAXReader(XMLReader xmlReader) | |
SAXReader(XMLReader xmlReader, boolean validating) | |
SAXReader(String xmlReaderClassName) | |
SAXReader(String xmlReaderClassName, boolean validating) |
Method Summary | |
---|---|
void | addHandler(String path, ElementHandler handler)
Adds the ElementHandler to be called when the specified
path is encounted.
|
protected void | configureReader(XMLReader reader, DefaultHandler handler)
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 systemId) |
protected XMLReader | createXMLReader()
Factory Method to allow alternate methods of creating and configuring
XMLReader objects
|
protected DispatchHandler | getDispatchHandler() |
DocumentFactory | getDocumentFactory()
DOCUMENT ME!
|
String | getEncoding()
Returns encoding used for InputSource (null means system default
encoding)
|
EntityResolver | getEntityResolver()
Returns the current entity resolver used to resolve entities
|
ErrorHandler | getErrorHandler()
DOCUMENT ME!
|
XMLFilter | getXMLFilter()
Returns the SAX filter being used to filter SAX events.
|
XMLReader | getXMLReader()
DOCUMENT ME!
|
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.
|
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(File file)
Reads a Document from the given |
Document | read(URL url)
Reads a Document from the given |
Document | read(String systemId) Reads a Document from the given URL or filename using SAX. |
Document | read(InputStream in) Reads a Document from the given stream using SAX |
Document | read(Reader reader)
Reads a Document from the given |
Document | read(InputStream in, String systemId) Reads a Document from the given stream using SAX |
Document | read(Reader reader, String systemId)
Reads a Document from the given |
Document | read(InputSource in)
Reads a Document from the given |
void | removeHandler(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(DispatchHandler dispatchHandler) |
void | setDocumentFactory(DocumentFactory documentFactory)
This sets the |
void | setEncoding(String encoding)
Sets encoding used for InputSource (null means system default encoding)
|
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)
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(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 validation)
Sets the validation mode.
|
void | setXMLFilter(XMLFilter filter)
Sets the SAX filter to be used when filtering SAX events
|
void | setXMLReader(XMLReader reader)
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.
|
ElementHandler
to be called when the specified
path is encounted.
Parameters: path
is the path to be handled handler
is the ElementHandler
to be called by the event
based processor.
Parameters: reader DOCUMENT ME! handler DOCUMENT ME!
Throws: DocumentException DOCUMENT ME!
Parameters: reader DOCUMENT ME!
Returns: DOCUMENT ME!
Returns: DOCUMENT ME!
Throws: SAXException DOCUMENT ME!
Returns: the DocumentFactory
used to create document
objects
Returns: encoding used for InputSource
Returns: DOCUMENT ME!
Returns: the ErrorHandler
used by SAX
Returns: the SAX filter being used or null if no SAX filter is installed
Returns: the XMLReader
used to parse SAX events
Throws: SAXException DOCUMENT ME!
Parameters: reader DOCUMENT ME!
Returns: the new XMLFilter if applicable or the original XMLReader if no filter is being used.
Returns: boolean
Returns: whether external DTD declarations should be expanded into the DocumentType object or not.
Returns: whether internal DTD declarations should be expanded into the DocumentType object or not.
Returns: Value of property mergeAdjacentText.
Returns: DOCUMENT ME!
Returns: Value of property stripWhitespaceText.
Returns: the validation mode, true if validating will be done otherwise false.
Reads a Document from the given File
Parameters: file
is the File
to read from.
Returns: the newly created Document instance
Throws: DocumentException if an error occurs during parsing.
Reads a Document from the given URL
using SAX
Parameters: url
URL
to read from.
Returns: the newly created Document instance
Throws: DocumentException if an error occurs during parsing.
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 {@link URL}or a {@link File}instance instead of a {@link
String} to denote the source of the document.
Parameters: systemId is a URL for a document or a file name.
Returns: the newly created Document instance
Throws: DocumentException if an error occurs during parsing.
Reads a Document from the given stream using SAX
Parameters: in
InputStream
to read from.
Returns: the newly created Document instance
Throws: DocumentException if an error occurs during parsing.
Reads a Document from the given Reader
using SAX
Parameters: reader is the reader for the input
Returns: the newly created Document instance
Throws: DocumentException if an error occurs during parsing.
Reads a Document from the given stream using SAX
Parameters: in
InputStream
to read from. systemId
is the URI for the input
Returns: the newly created Document instance
Throws: DocumentException if an error occurs during parsing.
Reads a Document from the given Reader
using SAX
Parameters: reader is the reader for the input systemId is the URI for the input
Returns: the newly created Document instance
Throws: DocumentException if an error occurs during parsing.
Reads a Document from the given InputSource
using SAX
Parameters: in
InputSource
to read from.
Returns: the newly created Document instance
Throws: DocumentException if an error occurs during parsing.
ElementHandler
from the event based processor,
for the specified path.
Parameters: path
is the path to remove the ElementHandler
for.
ElementHandler
instances have been
registered, this will set a default ElementHandler
to be
called for any path which does NOT have a handler registered.
Parameters: handler
is the ElementHandler
to be called by the event
based processor.
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
{@link DocumentFactory}
Parameters: documentFactory
DocumentFactory
used to create DOM4J objects
Parameters: encoding is encoding used for InputSource
Parameters: entityResolver DOCUMENT ME!
ErrorHandler
used by the SAX
XMLReader
.
Parameters: errorHandler
is the ErrorHandler
used by SAX
Parameters: name is the SAX feature name value is the value of the SAX feature
Throws: SAXException if the XMLReader could not be created or the feature could not be changed.
Parameters: ignoreComments whether we should ignore comments or not.
Parameters: include whether or not DTD declarations should be expanded and included into the DocumentType object.
Parameters: include whether or not DTD declarations should be expanded and included into the DocumentType object.
Parameters: mergeAdjacentText New value of property mergeAdjacentText.
Parameters: name is the SAX property name value is the value of the SAX property
Throws: SAXException if the XMLReader could not be created or the property could not be changed.
Parameters: stringInternEnabled DOCUMENT ME!
Parameters: stripWhitespaceText New value of property stripWhitespaceText.
Parameters: validation indicates whether or not validation should occur.
Parameters: filter is the SAX filter to use or null to disable filtering
XMLReader
used to parse SAX events
Parameters: reader
is the XMLReader
to parse SAX events
XMLReader
to be used to parse
SAX events.
Parameters: xmlReaderClassName
is the class name of the XMLReader
to parse SAX
events
Throws: SAXException DOCUMENT ME!