org.dom4j.io

Class SAXReader

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 setXMLReaderor setXMLReaderClassName 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

Version: $Revision: 1.58 $

Author: James Strachan

Nested Class Summary
protected static classSAXReader.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
voidaddHandler(String path, ElementHandler handler)
Adds the ElementHandler to be called when the specified path is encounted.
protected voidconfigureReader(XMLReader reader, DefaultHandler handler)
Configures the XMLReader before use
protected SAXContentHandlercreateContentHandler(XMLReader reader)
Factory Method to allow user derived SAXContentHandler objects to be used
protected EntityResolvercreateDefaultEntityResolver(String systemId)
protected XMLReadercreateXMLReader()
Factory Method to allow alternate methods of creating and configuring XMLReader objects
protected DispatchHandlergetDispatchHandler()
DocumentFactorygetDocumentFactory()
DOCUMENT ME!
StringgetEncoding()
Returns encoding used for InputSource (null means system default encoding)
EntityResolvergetEntityResolver()
Returns the current entity resolver used to resolve entities
ErrorHandlergetErrorHandler()
DOCUMENT ME!
XMLFiltergetXMLFilter()
Returns the SAX filter being used to filter SAX events.
XMLReadergetXMLReader()
DOCUMENT ME!
protected XMLReaderinstallXMLFilter(XMLReader reader)
Installs any XMLFilter objects required to allow the SAX event stream to be filtered and preprocessed before it gets to dom4j.
booleanisIgnoreComments()
Returns whether we should ignore comments or not.
booleanisIncludeExternalDTDDeclarations()
DOCUMENT ME!
booleanisIncludeInternalDTDDeclarations()
DOCUMENT ME!
booleanisMergeAdjacentText()
Returns whether adjacent text nodes should be merged together.
booleanisStringInternEnabled()
Sets whether String interning is enabled or disabled for element & attribute names and namespace URIs.
booleanisStripWhitespaceText()
Sets whether whitespace between element start and end tags should be ignored
booleanisValidating()
DOCUMENT ME!
Documentread(File file)

Reads a Document from the given File

Documentread(URL url)

Reads a Document from the given URL using SAX

Documentread(String systemId)

Reads a Document from the given URL or filename using SAX.

Documentread(InputStream in)

Reads a Document from the given stream using SAX

Documentread(Reader reader)

Reads a Document from the given Reader using SAX

Documentread(InputStream in, String systemId)

Reads a Document from the given stream using SAX

Documentread(Reader reader, String systemId)

Reads a Document from the given Reader using SAX

Documentread(InputSource in)

Reads a Document from the given InputSource using SAX

voidremoveHandler(String path)
Removes the ElementHandler from the event based processor, for the specified path.
voidresetHandlers()
This method clears out all the existing handlers and default handler setting things back as if no handler existed.
voidsetDefaultHandler(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 voidsetDispatchHandler(DispatchHandler dispatchHandler)
voidsetDocumentFactory(DocumentFactory documentFactory)

This sets the DocumentFactory used to create new documents.

voidsetEncoding(String encoding)
Sets encoding used for InputSource (null means system default encoding)
voidsetEntityResolver(EntityResolver entityResolver)
Sets the entity resolver used to resolve entities.
voidsetErrorHandler(ErrorHandler errorHandler)
Sets the ErrorHandler used by the SAX XMLReader.
voidsetFeature(String name, boolean value)
Sets a SAX feature on the underlying SAX parser.
voidsetIgnoreComments(boolean ignoreComments)
Sets whether we should ignore comments or not.
voidsetIncludeExternalDTDDeclarations(boolean include)
Sets whether DTD external declarations should be expanded into the DocumentType object or not.
voidsetIncludeInternalDTDDeclarations(boolean include)
Sets whether internal DTD declarations should be expanded into the DocumentType object or not.
voidsetMergeAdjacentText(boolean mergeAdjacentText)
Sets whether or not adjacent text nodes should be merged together when parsing.
voidsetProperty(String name, Object value)
Allows a SAX property to be set on the underlying SAX parser.
voidsetStringInternEnabled(boolean stringInternEnabled)
Sets whether String interning is enabled or disabled for element & attribute names and namespace URIs
voidsetStripWhitespaceText(boolean stripWhitespaceText)
Sets whether whitespace between element start and end tags should be ignored.
voidsetValidation(boolean validation)
Sets the validation mode.
voidsetXMLFilter(XMLFilter filter)
Sets the SAX filter to be used when filtering SAX events
voidsetXMLReader(XMLReader reader)
Sets the XMLReader used to parse SAX events
voidsetXMLReaderClassName(String xmlReaderClassName)
Sets the class name of the XMLReader to be used to parse SAX events.

Constructor Detail

SAXReader

public SAXReader()

SAXReader

public SAXReader(boolean validating)

SAXReader

public SAXReader(DocumentFactory factory)

SAXReader

public SAXReader(DocumentFactory factory, boolean validating)

SAXReader

public SAXReader(XMLReader xmlReader)

SAXReader

public SAXReader(XMLReader xmlReader, boolean validating)

SAXReader

public SAXReader(String xmlReaderClassName)

SAXReader

public SAXReader(String xmlReaderClassName, boolean validating)

Method Detail

addHandler

public void addHandler(String path, ElementHandler handler)
Adds the 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.

configureReader

protected void configureReader(XMLReader reader, DefaultHandler handler)
Configures the XMLReader before use

Parameters: reader DOCUMENT ME! handler DOCUMENT ME!

Throws: DocumentException DOCUMENT ME!

createContentHandler

protected SAXContentHandler createContentHandler(XMLReader reader)
Factory Method to allow user derived SAXContentHandler objects to be used

Parameters: reader DOCUMENT ME!

Returns: DOCUMENT ME!

createDefaultEntityResolver

protected EntityResolver createDefaultEntityResolver(String systemId)

createXMLReader

protected XMLReader createXMLReader()
Factory Method to allow alternate methods of creating and configuring XMLReader objects

Returns: DOCUMENT ME!

Throws: SAXException DOCUMENT ME!

getDispatchHandler

protected DispatchHandler getDispatchHandler()

getDocumentFactory

public DocumentFactory getDocumentFactory()
DOCUMENT ME!

Returns: the DocumentFactory used to create document objects

getEncoding

public String getEncoding()
Returns encoding used for InputSource (null means system default encoding)

Returns: encoding used for InputSource

getEntityResolver

public EntityResolver getEntityResolver()
Returns the current entity resolver used to resolve entities

Returns: DOCUMENT ME!

getErrorHandler

public ErrorHandler getErrorHandler()
DOCUMENT ME!

Returns: the ErrorHandler used by SAX

getXMLFilter

public XMLFilter getXMLFilter()
Returns the SAX filter being used to filter SAX events.

Returns: the SAX filter being used or null if no SAX filter is installed

getXMLReader

public XMLReader getXMLReader()
DOCUMENT ME!

Returns: the XMLReader used to parse SAX events

Throws: SAXException DOCUMENT ME!

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.

Parameters: reader DOCUMENT ME!

Returns: 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.

Returns: boolean

isIncludeExternalDTDDeclarations

public boolean isIncludeExternalDTDDeclarations()
DOCUMENT ME!

Returns: whether external DTD declarations should be expanded into the DocumentType object or not.

isIncludeInternalDTDDeclarations

public boolean isIncludeInternalDTDDeclarations()
DOCUMENT ME!

Returns: 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.

Returns: 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.

Returns: DOCUMENT ME!

isStripWhitespaceText

public boolean isStripWhitespaceText()
Sets whether whitespace between element start and end tags should be ignored

Returns: Value of property stripWhitespaceText.

isValidating

public boolean isValidating()
DOCUMENT ME!

Returns: the validation mode, true if validating will be done otherwise false.

read

public Document read(File file)

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.

read

public Document read(URL url)

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.

read

public Document read(String systemId)

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 URLor a Fileinstance instead of a 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.

read

public Document read(InputStream in)

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.

read

public Document read(Reader reader)

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.

read

public Document read(InputStream in, String systemId)

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.

read

public Document read(Reader reader, String systemId)

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.

read

public Document read(InputSource in)

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.

removeHandler

public void removeHandler(String path)
Removes the ElementHandler from the event based processor, for the specified path.

Parameters: 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.

Parameters: handler is the ElementHandler to be called by the event based processor.

setDispatchHandler

protected void setDispatchHandler(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

Parameters: documentFactory DocumentFactory used to create DOM4J objects

setEncoding

public void setEncoding(String encoding)
Sets encoding used for InputSource (null means system default encoding)

Parameters: encoding is encoding used for InputSource

setEntityResolver

public void setEntityResolver(EntityResolver entityResolver)
Sets the entity resolver used to resolve entities.

Parameters: entityResolver DOCUMENT ME!

setErrorHandler

public void setErrorHandler(ErrorHandler errorHandler)
Sets the ErrorHandler used by the SAX XMLReader.

Parameters: errorHandler is the ErrorHandler used by SAX

setFeature

public void setFeature(String name, boolean value)
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 setXMLReadermethod

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.

setIgnoreComments

public void setIgnoreComments(boolean ignoreComments)
Sets whether we should ignore comments or not.

Parameters: 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.

Parameters: 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.

Parameters: 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.

Parameters: mergeAdjacentText New value of property mergeAdjacentText.

setProperty

public void setProperty(String name, Object value)
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 setXMLReadermethod

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.

setStringInternEnabled

public void setStringInternEnabled(boolean stringInternEnabled)
Sets whether String interning is enabled or disabled for element & attribute names and namespace URIs

Parameters: stringInternEnabled DOCUMENT ME!

setStripWhitespaceText

public void setStripWhitespaceText(boolean stripWhitespaceText)
Sets whether whitespace between element start and end tags should be ignored.

Parameters: stripWhitespaceText New value of property stripWhitespaceText.

setValidation

public void setValidation(boolean validation)
Sets the validation mode.

Parameters: 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

Parameters: 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

Parameters: reader is the XMLReader to parse SAX events

setXMLReaderClassName

public void setXMLReaderClassName(String xmlReaderClassName)
Sets the class name of the 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!

Copyright B) 2005 MetaStuff Ltd. All Rights Reserved. Hosted by

SourceForge