org.zkoss.idom.input

Class SAXBuilder

java.lang.Object

org.zkoss.idom.input.SAXBuilder

public class SAXBuilder
extends java.lang.Object

The builder based on SAX parsers.

A new instance of SAXHandler is created and configured each time one of the build methods is called.

Author:

tomyeh

See Also:

SAXHandler

Constructor Summary

Constructors

Constructor and Description
SAXBuilder(boolean nsaware, boolean validate) Constructor that creates the parser on-the-fly.
SAXBuilder(boolean nsaware, boolean validate, boolean smartIgnore) Constructor that creates the parser on-the-fly, that accepts an additional option, smartIgnore.
SAXBuilder(javax.xml.parsers.SAXParser parser) Constructor which reuses a parser.

Method Summary

Methods

Modifier and Type	Method and Description
Document	build(java.io.File src) Build an iDOM tree from a file.
Document	build(org.xml.sax.InputSource src) Build an iDOM tree from a input source.
Document	build(java.io.InputStream src) Build an iDOM tree from a input stream.
Document	build(java.io.Reader src) Build an iDOM tree from a Reader.
Document	build(java.lang.String uri) Build an iDOM tree from a URI string.
Document	build(java.net.URL url) Build an iDOM tree from a URL.
org.xml.sax.EntityResolver	getEntityResolver() Gets the org.xml.sax.EntityResolver.
org.xml.sax.ErrorHandler	getErrorHandler() Gets the org.xml.sax.ErrorHandler.
IDOMFactory	getIDOMFactory() Gets the iDOM factory.
javax.xml.parsers.SAXParser	getParser() Gets the SAX parser.
boolean	isCoalescing() Indicates whether or not the factory is configured to produce parsers which converts CDATA to Text and appends it to the adjacent (if any) Text node.
boolean	isExpandEntityReferences() Tests whether to expand entity reference nodes.
boolean	isIgnoringComments() Indicates whether or not the factory is configured to produce parsers which ignores comments.
boolean	isIgnoringElementContentWhitespace() Tests whether to ignore whitespaces in element content.
boolean	isNamespaceAware() Tests whether or not this parser is configured to understand namespaces.
boolean	isValidating() Tests whether or not this parser is configured to validate XML documents.
protected SAXHandler	newHandler() Creates a SAX Handler.
void	setCoalescing(boolean coalescing) Specifies that the parser produced by this code will convert CDATA to Text and append it to the adjacent (if any) text.
void	setEntityResolver(org.xml.sax.EntityResolver er) Specifies the org.xml.sax.EntityResolver to be used to resolve entities present in the XML document to be parsed.
void	setErrorHandler(org.xml.sax.ErrorHandler eh) Specifies the org.xml.sax.ErrorHandler to be used to report errors present in the XML document to be parsed.
void	setExpandEntityReferences(boolean expand) Sets whether to expand entities during parsing.
void	setIDOMFactory(IDOMFactory factory) Sets the iDOM factory.
void	setIgnoringComments(boolean ignoreComments) Specifies that the parser produced by this code will ignore comments.
void	setIgnoringElementContentWhitespace(boolean ignore) Sets whether the parser should eliminate whitespace in element content.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SAXBuilder

public SAXBuilder(javax.xml.parsers.SAXParser parser)

Constructor which reuses a parser.

SAXBuilder

public SAXBuilder(boolean nsaware,
          boolean validate)
           throws javax.xml.parsers.ParserConfigurationException,
                  org.xml.sax.SAXException

Constructor that creates the parser on-the-fly.

Parameters:

nsaware - whether the parser is namespace aware

validate - whether the parser shall validate the document

Throws:

javax.xml.parsers.ParserConfigurationException - if a parser cannot be created which satisfies the requested configuration.

org.xml.sax.SAXException

See Also:

SAXBuilder(boolean, boolean, boolean)

SAXBuilder

public SAXBuilder(boolean nsaware,
          boolean validate,
          boolean smartIgnore)
           throws javax.xml.parsers.ParserConfigurationException,
                  org.xml.sax.SAXException

Constructor that creates the parser on-the-fly, that accepts an additional option, smartIgnore.

When parsing XML for input purpose only, it is better to use this constructor with smartIgnore true, and then comments will be ignored CDATA will be coalesced with TEXT. A smaller DOM tree is formed.

Parameters:

nsaware - whether the parser is namespace aware

validate - whether the parser shall validate the document

smartIgnore - whether to ignore comments and ignorable-whitespace (if validate is true), and to coalesce

Throws:

javax.xml.parsers.ParserConfigurationException - if a parser cannot be created which satisfies the requested configuration.

org.xml.sax.SAXException

Method Detail

isIgnoringElementContentWhitespace

public final boolean isIgnoringElementContentWhitespace()

Tests whether to ignore whitespaces in element content.

setIgnoringElementContentWhitespace

public final void setIgnoringElementContentWhitespace(boolean ignore)

Sets whether the parser should eliminate whitespace in element content. They are known as "ignorable whitespace". Only whitespace which is contained within element content that has an element only content model will be eliminated (see XML Rec 2.10).

For this setting to take effect requires that validation be turned on.

Default: false.

Parameters:

ignore - Whether to ignore whitespaces in element content.

isExpandEntityReferences

public final boolean isExpandEntityReferences()

Tests whether to expand entity reference nodes.

setExpandEntityReferences

public final void setExpandEntityReferences(boolean expand)

Sets whether to expand entities during parsing. A true means to expand entities as normal content. A false means to leave entities unexpanded as EntityReference objects.

Default: true.

Parameters:

expand - whether entity expansion should occur.

isCoalescing

public final boolean isCoalescing()

Indicates whether or not the factory is configured to produce parsers which converts CDATA to Text and appends it to the adjacent (if any) Text node.

Default: false.

Returns:

true if the factory is configured to produce parsers which converts CDATA nodes to Text nodes and appends it to the adjacent (if any) Text node; false otherwise.

setCoalescing

public final void setCoalescing(boolean coalescing)

Specifies that the parser produced by this code will convert CDATA to Text and append it to the adjacent (if any) text.

Default: false.

isIgnoringComments

public final boolean isIgnoringComments()

Indicates whether or not the factory is configured to produce parsers which ignores comments.

Default: false.

Returns:

true if the factory is configured to produce parsers which ignores comments; false otherwise.

setIgnoringComments

public final void setIgnoringComments(boolean ignoreComments)

Specifies that the parser produced by this code will ignore comments.

Default: false.

setErrorHandler

public final void setErrorHandler(org.xml.sax.ErrorHandler eh)

Specifies the org.xml.sax.ErrorHandler to be used to report errors present in the XML document to be parsed.

Default: null -- to use the default implementation and behavior.

getErrorHandler

public final org.xml.sax.ErrorHandler getErrorHandler()

Gets the org.xml.sax.ErrorHandler.

Returns:

the error handler; null to use the default implementation

setEntityResolver

public final void setEntityResolver(org.xml.sax.EntityResolver er)

Specifies the org.xml.sax.EntityResolver to be used to resolve entities present in the XML document to be parsed.

Default: null -- to use the default implementation and behavior.

getEntityResolver

public final org.xml.sax.EntityResolver getEntityResolver()

Gets the org.xml.sax.EntityResolver.

Returns:

the entity resolver; null to use the default implementation

isNamespaceAware

public final boolean isNamespaceAware()

Tests whether or not this parser is configured to understand namespaces.

isValidating

public final boolean isValidating()

Tests whether or not this parser is configured to validate XML documents.

getIDOMFactory

public final IDOMFactory getIDOMFactory()

Gets the iDOM factory. Null for DefaultIDOMFactory.THE.

setIDOMFactory

public final void setIDOMFactory(IDOMFactory factory)

Sets the iDOM factory. Null for DefaultIDOMFactory.THE.

getParser

public final javax.xml.parsers.SAXParser getParser()

Gets the SAX parser.

build

public final Document build(java.io.File src)
                     throws org.xml.sax.SAXException,
                            java.io.IOException

Build an iDOM tree from a file.

Throws:

org.xml.sax.SAXException

java.io.IOException

build

public final Document build(java.io.InputStream src)
                     throws org.xml.sax.SAXException,
                            java.io.IOException

Build an iDOM tree from a input stream.

Throws:

org.xml.sax.SAXException

java.io.IOException

build

public final Document build(org.xml.sax.InputSource src)
                     throws org.xml.sax.SAXException,
                            java.io.IOException

Build an iDOM tree from a input source.

Throws:

org.xml.sax.SAXException

java.io.IOException

build

public final Document build(java.lang.String uri)
                     throws org.xml.sax.SAXException,
                            java.io.IOException

Build an iDOM tree from a URI string.

Throws:

org.xml.sax.SAXException

java.io.IOException

build

public final Document build(java.net.URL url)
                     throws org.xml.sax.SAXException,
                            java.io.IOException

Build an iDOM tree from a URL.

Throws:

org.xml.sax.SAXException

java.io.IOException

build

public final Document build(java.io.Reader src)
                     throws org.xml.sax.SAXException,
                            java.io.IOException

Build an iDOM tree from a Reader.

Throws:

org.xml.sax.SAXException

java.io.IOException

newHandler

protected SAXHandler newHandler()
                         throws org.xml.sax.SAXException

Creates a SAX Handler. Deriving class might override to provide a subclass of SAXHandler.

Throws:

org.xml.sax.SAXException