Class com.ibm.xml.parser.Parser

java.lang.Object
    |
    +----com.ibm.xml.parser.Parser

public class Parser

extends java.lang.Object

Version:

Revision: 17 1.5 src/com/ibm/xml/parser/Parser.java, xml4jsrc, xml4j-jtcsv, xml4j_1_0_4

See Also:

TXDocument, TXDocumentContext, TXElement, TXText, TXComment, TXPI, NamespacePI, StylesheetPI, TXCDATASection, TXNotation, TXAttributeList, TXAttribute, DTD, ElementDecl, Attlist, AttDef, Entity

Constructor Summary

Parser(java.lang.String name) Constructor when using the default ErrorListener and StreamProducer.

Parser(java.lang.String name, ErrorListener errorListener, StreamProducer streamProducer) Constructor when NOT using the default ErrorListener or StreamProducer.

 

Method Summary
void	addElementHandler(ElementHandler elementHandler) Register a handler for receiving control when ANY element tag is recognized by this parser.
void	addElementHandler(ElementHandler elementHandler, java.lang.String elementTagName) Register a handler for receiving control when the specified elementTagName element tag is recognized by this parser.
void	addNoRequiredAttributeHandler(NoRequiredAttributeHandler noRequiredAttributeHandler) Register a handler for receiving control when a "no required attribute" event is recognized by this parser.
void	addPIHandler(PIHandler piHandler) Register a handler for receiving control when PIs are recognized by this parser.
void	addPreRootHandler(PreRootHandler preRootHandler) Register a handler for receiving control from this parser after the internal and/or external DTD subsets are parsed, but before the document's root Element is parsed.
void	closeInputStream(Source source) Removes the input stream currently in use.
Source	getInputStream(java.lang.String name, java.lang.String publicID, java.lang.String systemID) Returns the source of the input stream (could be a character stream or a byte stream) based on the entity specified by the system ID and/or public ID, and the streamProducer specified when this parser was constructed.
int	getNumberOfErrors() Returns the number of errors and exceptions currently encountered by this parser.
int	getNumberOfWarnings() Returns the number of warnings currently encountered by this parser.
int	getReaderBufferSize() Returns the size of this parser's character-stream-oriented input source buffer.
void	loadCatalog(java.io.Reader reader) Loads a catalog which provides mapping between public IDs and system IDs.
DTD	readDTDStream(java.io.InputStream inputStream) Returns a parsed external DTD subset based on the specified inputStream.
DTD	readDTDStream(java.io.Reader reader) Returns a parsed external DTD subset based on the specified reader.
DTD	readDTDStream(Source source) Returns a parsed external DTD subset based on the specified source.
TXDocument	readStream(java.io.InputStream inputStream) Returns a parsed XML document based on the specified inputStream.
TXDocument	readStream(java.io.Reader reader) Returns a parsed XML document based on the specified reader.
TXDocument	readStream(Source source) Returns a parsed XML document based on the specified source.
void	setAllowJavaEncodingName(boolean isAllowJavaEncodingName) Sets whether this parser allows Java encoding names to be specified in place of MIME charset names on xmlEncoding parameters.
void	setElementFactory(ElementFactory elementFactory) Sets the code to receive control when the various components of the Document Object Model (DOM) and XML4J need to be created and initialized.
void	setEndBy1stError(boolean isEndBy1stError) Sets whether this parser terminates processing when an initial error or exception occurs.
void	setErrorNoByteMark(boolean isErrorNoByteMark) Sets whether this parser treats missing byte marks in the input stream as an error, and reports this condition through the defined ErrorListener.
void	setKeepComment(boolean isKeepComment) Sets whether TXComment Nodes are created by this parser when XML comments are encountered.
void	setLocale(java.util.Locale locale) Sets a locale for error and warning messages.
void	setPreserveSpace(boolean isPreserveSpace) Sets, at the document level, whether space is to be preserved in the parsed document.
void	setProcessNamespace(boolean isProcessNamespace) Sets whether namespaces are respected by this parser.
void	setReaderBufferSize(int readerBufferSize) Sets the size of this parser's character-stream-oriented input source buffer.
void	setReferenceHandler(ReferenceHandler referenceHandler) Register a handler for receiving control when a General Reference is recognized by this parser.
void	setTagHandler(TagHandler tagHandler) Register a handler for receiving control when tag start and tag end events are recognized by this parser.
void	setWarningNoDoctypeDecl(boolean isWarningNoDoctypeDecl) Sets whether this parser treats a missing DTD declaration as a warning, and reports this condition through the defined ErrorListener.
void	setWarningNoXMLDecl(boolean isWarningNoXMLDecl) Sets whether this parser treats a missing XML prolog PIs as a warning, and reports this condition through the defined ErrorListener.
void	setWarningRedefinedEntity(boolean isWarningRedefinedEntity) Sets whether this parser treats redefined entities as a warning, and reports this condition through the defined ErrorListener.

 

Methods inherited from class java.lang.Object

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

 

Constructor Detail

Parser

public Parser(java.lang.String name)

Constructor when using the default ErrorListener and StreamProducer. The default ErrorListener and StreamProducer are defined by the Stderr class.

Parameters:

name - URL or filespec to use as the default input stream; if a filespec is provided, this value can include a drive and directory spec. This value is also used to associate a name with errors reported to the default error listener that have a file parameter =null.

See Also:

Stderr, ErrorListener, StreamProducer

Parser

public Parser(java.lang.String name,
              ErrorListener errorListener,
              StreamProducer streamProducer)

Constructor when NOT using the default ErrorListener or StreamProducer. The default ErrorListener and StreamProducer are defined by the Stderr class.

Parameters:

name - This parameter is only used if either errorListener or streamProducer are allowed to default. If streamProducer is allowed to default, this value is the URL or filespec to use as the default input stream; if a filespec is provided, this value can include a drive and directory spec. If errorListener is allowed to default, this value is used to associate a name with errors reported to the default error listener that have a file parameter =null.

errorListener - Handler for error and warning events that are recognized by this parser, or null if to use the default listener.

streamProducer - Mechanism for manipulating this parser's input stream, or null if to use the default stream producer.

See Also:

Stderr, ErrorListener, StreamProducer

setLocale

public void setLocale(java.util.Locale locale)

Sets a locale for error and warning messages.

By default, the current user locale's resource bundle is used. If no messages exist for the requested locale, US English messages are used.

Parameters:

locale - A Java Locale object.

setElementFactory

public void setElementFactory(ElementFactory elementFactory)

Sets the code to receive control when the various components of the Document Object Model (DOM) and XML4J need to be created and initialized. By default, the DefaultElementFactory is used.

Parameters:

elementFactory - Factory to use to create and initialize objects.

See Also:

ElementFactory, DefaultElementFactory

getInputStream

public Source getInputStream(java.lang.String name,
                             java.lang.String publicID,
                             java.lang.String systemID) throws java.io.IOException

Returns the source of the input stream (could be a character stream or a byte stream) based on the entity specified by the system ID and/or public ID, and the streamProducer specified when this parser was constructed.

Parameters:

name - The name to be associated with the input stream. For example, this name could be the public ID of an external ID, or a local filename.

publicID - Entity's public ID, or null if no public ID (see ExternalID for details).

systemID - Entity's system ID.

Returns:

The resolved source of the input stream, or null if unable to resolve.

Throws:

java.io.IOException - Thrown if unable to open the source defined by the specified IDs.

See Also:

ExternalID, closeInputStream, getInputStream

closeInputStream

public void closeInputStream(Source source)

Removes the input stream currently in use.

Parameters:

source - Source of the input stream to be closed.

See Also:

getInputStream, closeInputStream

loadCatalog

public void loadCatalog(java.io.Reader reader) throws java.io.IOException

Loads a catalog which provides mapping between public IDs and system IDs.

Parameters:

reader - Character input stream reader.

Throws:

java.io.IOException - Thrown if reader is invalid.

See Also:

getInputStream, ExternalID, loadCatalog, loadCatalog

setTagHandler

public void setTagHandler(TagHandler tagHandler)

Register a handler for receiving control when tag start and tag end events are recognized by this parser. By default, no tag handler is registered to this parser.

Parameters:

tagHandler - Handler to be registered.

See Also:

TagHandler

setReferenceHandler

public void setReferenceHandler(ReferenceHandler referenceHandler)

Register a handler for receiving control when a General Reference is recognized by this parser. By default, no reference handler is registered to this parser.

Parameters:

referenceHandler - Handler to be registered.

See Also:

ReferenceHandler

addPreRootHandler

public void addPreRootHandler(PreRootHandler preRootHandler)

Register a handler for receiving control from this parser after the internal and/or external DTD subsets are parsed, but before the document's root Element is parsed. By default, no preroot handlers are registered to this parser.

Parameters:

preRootHandler - Handler to be registered.

See Also:

PreRootHandler

addPIHandler

public void addPIHandler(PIHandler piHandler)

Register a handler for receiving control when PIs are recognized by this parser. By default, no PI handlers are registered to this parser.

Parameters:

piHandler - Handler to be registered.

See Also:

PIHandler

addElementHandler

public void addElementHandler(ElementHandler elementHandler)

Register a handler for receiving control when ANY element tag is recognized by this parser. By default, no element handlers are registered to this parser.

Parameters:

elementHandler - Handler to be registered.

See Also:

ElementHandler

addElementHandler

public void addElementHandler(ElementHandler elementHandler,
                              java.lang.String elementTagName)

Register a handler for receiving control when the specified elementTagName element tag is recognized by this parser. By default, no element handlers are registered to this parser.

Parameters:

elementHandler - Handler to be registered for the specified elementTagName.

elementTagName - Element name to be watched for by this parser. If the Element's name has a namespace prefix, that prefix should be included.

See Also:

ElementHandler

addNoRequiredAttributeHandler

public void addNoRequiredAttributeHandler(NoRequiredAttributeHandler noRequiredAttributeHandler)

Register a handler for receiving control when a "no required attribute" event is recognized by this parser. A "no required attribute" event occurs when an Element is parsed and a required Attribute for this Element is not seen; Attributes are declared as required as part of the internal and/or external DTD declaration of the XML document.

By default, no required attribute handlers are registered to this parser.

Parameters:

noRequiredAttributeHandler - Handler to be registered.

See Also:

NoRequiredAttributeHandler

getNumberOfErrors

public int getNumberOfErrors()

Returns the number of errors and exceptions currently encountered by this parser. Warning messages do not count in this number.

Returns:

Number of errors and exceptions encountered by this parser.

See Also:

ErrorListener

getNumberOfWarnings

public int getNumberOfWarnings()

Returns the number of warnings currently encountered by this parser.

Returns:

Number of warnings encountered by this parser.

See Also:

ErrorListener

setKeepComment

public void setKeepComment(boolean isKeepComment)

Sets whether TXComment Nodes are created by this parser when XML comments are encountered.

By default, TXComment Nodes are created by this parser.

Parameters:

isKeepComment - =true means maintain parsed comments; =false means drop comments when creating object tree.

See Also:

TXComment

setProcessNamespace

public void setProcessNamespace(boolean isProcessNamespace)

Sets whether namespaces are respected by this parser. Namespace notation can occur on the names of TXElement, TXPI, and TXAttribute Nodes. If namespaces are respected, the methods defined by the Namespace interface will function properly in these Nodes.

By default, namespaces are NOT respected by this parser.

Parameters:

isProcessNamespace - =true means parse for namespaces; =false means ignore namespaces when parsing.

See Also:

Namespace, TXElement, TXPI, TXAttribute

setAllowJavaEncodingName

public void setAllowJavaEncodingName(boolean isAllowJavaEncodingName)

Sets whether this parser allows Java encoding names to be specified in place of MIME charset names on xmlEncoding parameters. The MIME2Java class is provided to facilitate conversion when Java encoding names are not allowed.

By default, Java encoding names are NOT allowed on xmlEncoding parameters by this parser.

Parameters:

isAllowJavaEncodingName - =true means Java encoding names are allowed; =false means MIME charset names must be used.

See Also:

setEncoding, setEncoding, MIME2Java

setPreserveSpace

public void setPreserveSpace(boolean isPreserveSpace)

Sets, at the document level, whether space is to be preserved in the parsed document. Regardless of the value of isPreserveSpace, this parser will preserve whitespace. This value is used, for example, to determine if space is to be preserved in Text Nodes during printWithFormat() operations. Note that the document-level value will be overridden at the Node level if this parser recognizes a xml:space attribute.

By default, space is not to be preserved in the parsed document.

Parameters:

isPreserveSpace - =true space is to be preserved; =false space is to be ignored.

See Also:

setPreserveSpace, setIsIgnorableWhitespace, printWithFormat

setErrorNoByteMark

public void setErrorNoByteMark(boolean isErrorNoByteMark)

Sets whether this parser treats missing byte marks in the input stream as an error, and reports this condition through the defined ErrorListener.

By default, this condition is reported by this parser as an error.

Parameters:

isErrorNoByteMark - =true means report condition as an error; =false means ignore this condition.

setWarningRedefinedEntity

public void setWarningRedefinedEntity(boolean isWarningRedefinedEntity)

Sets whether this parser treats redefined entities as a warning, and reports this condition through the defined ErrorListener.

By default, this condition is reported by this parser as a warning.

Parameters:

isWarningRedefinedEntity - =true means report condition as a warning; =false means ignore this condition.

See Also:

Entity

setWarningNoXMLDecl

public void setWarningNoXMLDecl(boolean isWarningNoXMLDecl)

Sets whether this parser treats a missing XML prolog PIs as a warning, and reports this condition through the defined ErrorListener.

By default, this condition is reported by this parser as a warning.

Parameters:

isWarningNoXMLDecl - =true means report condition as a warning; =false means ignore this condition.

See Also:

TXPI

setWarningNoDoctypeDecl

public void setWarningNoDoctypeDecl(boolean isWarningNoDoctypeDecl)

Sets whether this parser treats a missing DTD declaration as a warning, and reports this condition through the defined ErrorListener.

By default, this condition is NOT reported by this parser as a warning.

Parameters:

isWarningNoXMLDecl - =true means report condition as a warning; =false means ignore this condition.

See Also:

DTD

setEndBy1stError

public void setEndBy1stError(boolean isEndBy1stError)

Sets whether this parser terminates processing when an initial error or exception occurs.

By default, this parser continues parsing after an error occurs.

Parameters:

isEndBy1stError - =true means initial error or exception ends processing; =false means processing continues until document is fully parsed.

readStream

public TXDocument readStream(java.io.InputStream inputStream)

Returns a parsed XML document based on the specified inputStream. The returned document can then be accessed by methods such as TXDocument#getDocumentElement.

Once this method is invoked, the parser instance is of no further use, and should NOT be reused.

Parameters:

inputStream - Byte-stream-oriented data source.

Returns:

Parsed XML document (should never be null).

See Also:

Source, getDocumentElement, readDTDStream

readStream

public TXDocument readStream(java.io.Reader reader)

Returns a parsed XML document based on the specified reader. The returned document can then be accessed by methods such as TXDocument#getDocumentElement.

Once this method is invoked, the parser instance is of no further use, and should NOT be reused.

Parameters:

reader - Character-stream-oriented data source.

Returns:

Parsed XML document (should never be null).

See Also:

Source, getDocumentElement, readDTDStream

readStream

public TXDocument readStream(Source source)

Returns a parsed XML document based on the specified source. The returned document can then be accessed by methods such as TXDocument#getDocumentElement.

Once this method is invoked, the parser instance is of no further use, and should NOT be reused.

Parameters:

source - Byte-stream-oriented or character-stream-oriented data source.

Returns:

Parsed XML document (should never be null).

See Also:

Source, getDocumentElement, readDTDStream

readDTDStream

public DTD readDTDStream(java.io.InputStream inputStream) throws java.io.IOException

Returns a parsed external DTD subset based on the specified inputStream. The returned document can then be accessed by methods such as DTD#externalElements.

Once this method is invoked, the parser instance is of no further use, and should NOT be reused.

Parameters:

inputStream - Byte-stream-oriented data source.

Returns:

Parsed DTD (should never be null).

See Also:

Source, DTD, readStream

readDTDStream

public DTD readDTDStream(java.io.Reader reader) throws java.io.IOException

Returns a parsed external DTD subset based on the specified reader. The returned document can then be accessed by methods such as DTD#externalElements.

Once this method is invoked, the parser instance is of no further use, and should NOT be reused.

Parameters:

reader - Character-stream-oriented data source.

Returns:

Parsed DTD (should never be null).

See Also:

Source, DTD, readStream

readDTDStream

public DTD readDTDStream(Source source) throws java.io.IOException

Returns a parsed external DTD subset based on the specified source. The returned document can then be accessed by methods such as DTD#externalElements.

Once this method is invoked, the parser instance is of no further use, and should NOT be reused.

Parameters:

source - Byte-stream-oriented or character-stream-oriented data source.

Returns:

Parsed DTD (should never be null).

See Also:

Source, DTD, readStream

getReaderBufferSize

public int getReaderBufferSize()

Returns the size of this parser's character-stream-oriented input source buffer. Characters are buffered during I/O in order to provide efficient reading. This method has no meaning for byte-stream-oriented input sources.

Returns:

Size of this parser's character-stream-oriented input buffer.

See Also:

setReaderBufferSize

setReaderBufferSize

public void setReaderBufferSize(int readerBufferSize)

Sets the size of this parser's character-stream-oriented input source buffer. Characters are buffered during I/O in order to provide efficient reading. This method has no meaning for byte-stream-oriented input sources.

The default buffer size is large enough for most purposes.

Parameters:

readerBufferSize - Size of this parser's character-stream-oriented input buffer.

See Also:

getReaderBufferSize