XML for Java Compatibility API 2.0.13

com.ibm.xml.parser
Class Parser

java.lang.Object
  |
  +--com.ibm.xml.framework.XMLParser
        |
        +--com.ibm.xml.parsers.NonValidatingTXDOMParser
              |
              +--com.ibm.xml.parsers.TXDOMParser
                    |
                    +--com.ibm.xml.parser.Parser

public class Parser
extends com.ibm.xml.parsers.TXDOMParser

This parser provides a backward compatibile API on top of the new parser architecture. This parser should behave the same as the old parser, with the exceptions listed below.

Users of this parser instance should not call any functions in the new parser architecture. Calling methods outside of the old parser API can have unexpected results.

Users who are moving to the new parser architecture but want to use the catalog file format supported by the old parser should use the com.ibm.xml.internal.TXCatalog class.

Not supported: Calling these methods will throw java.lang.IllegalArgumentException.

Not implemented: These methods are present but should not be expected to function the same as in the old parser.

29 1.15 src/com/ibm/xml/parser/Parser.java, parser, xml4j2, xml4j2_0_13 * @version Revision:

See Also:
TXCatalog

Fields inherited from class com.ibm.xml.parsers.NonValidatingTXDOMParser
DEBUG, fCurrentNode, fCurrentParent, fDocument, fDocumentClass, fDocumentType, fEntityPool, fExpandEntityReferences, fNodeStack, fNormalizeTextNodes, fRootElementName, fWithinElement
 
Fields inherited from class com.ibm.xml.framework.XMLParser
fLocale, fNeedReset, fParseInProgress, fResourceBundle, fScanner
 
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 handler)
          Register a handler for receiving control when ANY element tag is recognized by this parser.
 void addElementHandler(ElementHandler handler, java.lang.String elementName)
          Register a handler for receiving control when the specified elementTagName element tag is recognized by this parser.
 void addNoRequiredAttributeHandler(NoRequiredAttributeHandler handler)
          This method is not supported. Register a handler for receiving control when a "no required attribute" event is recognized by this parser.
 void addPIHandler(PIHandler handler)
          Register a handler for receiving control when PIs are recognized by this parser.
 void addPreRootHandler(PreRootHandler handler)
          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()
          This method is not supported. Returns the size of this parser's character-stream-oriented input source buffer.
protected  void handleError(java.lang.String errorKey, java.lang.String errorMsg)
          This method is the basic error handler.
 void loadCatalog(java.io.Reader reader)
          Loads a catalog which provides mapping between public IDs and system IDs.
 void parseDTD(org.xml.sax.InputSource source)
          Parses the specified input source.
 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 reset()
          This method is not part of the Parser API and is called automatically by the parser internals. Resets the parser between calls to parse.
 void setAllowJavaEncodingName(boolean allow)
          Sets whether this parser allows Java encoding names to be specified in place of MIME charset names on xmlEncoding parameters.
 void setElementFactory(TXDocument factory)
          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 end)
          Sets whether this parser terminates processing when an initial error or exception occurs.
 void setErrorNoByteMark(boolean error)
          This method is not supported. Sets whether this parser treats missing byte marks in the input stream as an error, and reports this condition through the defined ErrorListener.
 void setExpandEntityReferences(boolean expand)
          Sets whether EntityReference Nodes are expanded by this parser.
 void setKeepComment(boolean keep)
          Sets whether TXComment Nodes are created by this parser when XML comments are encountered.
 void setPreserveSpace(boolean preserve)
          This method is not supported. Sets, at the document level, whether space is to be preserved in the parsed document.
 void setProcessExternalDTD(boolean process)
          This method is not implemented. Sets whether this parser reads an external subset of DTD, pointed in an ExternalID in DOCTYPE declaration.
 void setProcessNamespace(boolean process)
          Sets whether namespaces are respected by this parser.
 void setReaderBufferSize(int size)
          This method is not supported. Sets the size of this parser's character-stream-oriented input source buffer.
 void setReferenceHandler(ReferenceHandler handler)
          Register a handler for receiving control when a General Reference is recognized by this parser.
 void setTagHandler(TagHandler handler)
          Register a handler for receiving control when tag start and tag end events are recognized by this parser.
 void setWarningNoDoctypeDecl(boolean warning)
          This method is not implemented. Sets whether this parser treats a missing DTD declaration as a warning, and reports this condition through the defined ErrorListener.
 void setWarningNoXMLDecl(boolean warning)
          This method is not implemented. Sets whether this parser treats a missing XML prolog PIs as a warning, and reports this condition through the defined ErrorListener.
 void setWarningRedefinedEntity(boolean warning)
          This method is not implemented. Sets whether this parser treats redefined entities as a warning, and reports this condition through the defined ErrorListener.
 void stop()
          Stops a Parser.readStream() operation.
 
Methods inherited from class com.ibm.xml.parsers.TXDOMParser
resetOrCopy
 
Methods inherited from class com.ibm.xml.parsers.NonValidatingTXDOMParser
attlistDecl, buildCMNode, characters, characters, checkHandlers, comment, doctypeDecl, elementDecl, endDocument, endElement, endEntityReference, endExternalSubset, endInternalSubset, externalEntityDecl, getDocument, getExpandEntityReferences, ignorableWhitespace, ignorableWhitespace, init, internalEntityDecl, notationDecl, processingInstruction, setDocumentClass, setNormalizeTextNodes, startDocument, startElement, startEntityReference, startExternalSubset, startInternalSubset, unparsedEntityDecl
 
Methods inherited from class com.ibm.xml.framework.XMLParser
error, error1, error2, error3, error4, errorHandlingEnabled, getAllowJavaEncodingName, getCheckNamespace, getContinueAfterFatalError, getDocumentHandler, getDocumentTypeHandler, getEntityHandler, getErrorHandler, getErrorMsgString, getLocator, getParserState, getScanner, getValidationHandler, getWarningOnDuplicateAttDef, isFatal, isWarning, loadCatalog, parse, parse, sendCharDataAsCharArray, setCheckNamespace, setContinueAfterFatalError, setDocumentHandler, setDocumentHandler, setDocumentTypeHandler, setDTDHandler, setEntityHandler, setEntityResolver, setErrorHandler, setLocale, setValidationHandler, setWarningOnDuplicateAttDef, useDefaultValidationHandler
 
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
Method Detail

setElementFactory

public void setElementFactory(TXDocument factory)
Sets the code to receive control when the various components of the Document Object Model (DOM) and XML4J need to be created and initialized. When this method is called, readStream() returns the elementFactory.

By default, an instance of TXDocument is used.

Parameters:
factory - Factory to use to create and initialize objects. This must be an instance of TXDocument or a subclass of TXDocument.
See Also:
TXDocument

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(com.ibm.xml.parser.Source), StreamProducer.getInputStream(java.lang.String, java.lang.String, java.lang.String)

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(java.lang.String, java.lang.String, java.lang.String), StreamProducer.closeInputStream(com.ibm.xml.parser.Source)

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(java.lang.String, java.lang.String, java.lang.String), ExternalID, Stderr.loadCatalog(java.io.Reader), StreamProducer.loadCatalog(java.io.Reader)

setTagHandler

public void setTagHandler(TagHandler handler)
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:
handler - Handler to be registered.
See Also:
TagHandler

setReferenceHandler

public void setReferenceHandler(ReferenceHandler handler)
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:
handler - Handler to be registered.
See Also:
ReferenceHandler

addPreRootHandler

public void addPreRootHandler(PreRootHandler handler)
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:
handler - Handler to be registered.
See Also:
PreRootHandler

addPIHandler

public void addPIHandler(PIHandler handler)
Register a handler for receiving control when PIs are recognized by this parser.

By default, no PI handlers are registered to this parser.

Parameters:
handler - Handler to be registered.
See Also:
PIHandler

addElementHandler

public void addElementHandler(ElementHandler handler)
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:
handler - Handler to be registered.
See Also:
ElementHandler

addElementHandler

public void addElementHandler(ElementHandler handler,
                              java.lang.String elementName)
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:
handler - Handler to be registered for the specified elementName.
elementName - 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

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 keep)
Sets whether TXComment Nodes are created by this parser when XML comments are encountered.

By default, TXComment Nodes are created by this parser.

Parameters:
keep - =true means maintain parsed comments; =false means drop comments when creating object tree.
See Also:
TXComment

setExpandEntityReferences

public void setExpandEntityReferences(boolean expand)
Sets whether EntityReference Nodes are expanded by this parser.

By default, EntityReference Nodes are kept.

Parameters:
keep - =true means expanding entity references; =false means maintain entity references.
Overrides:
setExpandEntityReferences in class com.ibm.xml.parsers.NonValidatingTXDOMParser
See Also:
EntityReference, GeneralReference

setProcessExternalDTD

public void setProcessExternalDTD(boolean process)
This method is not implemented.

Sets whether this parser reads an external subset of DTD, pointed in an ExternalID in DOCTYPE declaration.

By default, this parser reads an external subset of DTD.

Parameters:
process - =true means process an external DTD; =false means ignore an external DTD.
See Also:
DTD

setProcessNamespace

public void setProcessNamespace(boolean process)
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:
process - =true means parse for namespaces; =false means ignore namespaces when parsing.
See Also:
Namespace, TXElement, TXAttribute

setAllowJavaEncodingName

public void setAllowJavaEncodingName(boolean allow)
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:
allow - =true means Java encoding names are allowed; =false means MIME charset names must be used.
Overrides:
setAllowJavaEncodingName in class com.ibm.xml.framework.XMLParser
See Also:
TXDocument.setEncoding(java.lang.String), DTD.setEncoding(java.lang.String), MIME2Java

setPreserveSpace

public void setPreserveSpace(boolean preserve)
This method is not supported.

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:
preserve - =true space is to be preserved; =false space is to be ignored.

setEndBy1stError

public void setEndBy1stError(boolean end)
Sets whether this parser terminates processing when an initial error or exception occurs.

By default, this parser stops parsing after an error occurs, as required by the XML specification.

Parameters:
end - =true means initial error or exception ends processing; =false means processing continues until the 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, TXDocument.getDocumentElement(), readDTDStream(java.io.InputStream)

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, TXDocument.getDocumentElement(), readDTDStream(java.io.InputStream)

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, TXDocument.getDocumentElement(), readDTDStream(java.io.InputStream)

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(java.io.InputStream)

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(java.io.InputStream)

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(java.io.InputStream)

parseDTD

public final void parseDTD(org.xml.sax.InputSource source)
                    throws org.xml.sax.SAXException,
                           java.io.IOException
Parses the specified input source.
Parameters:
source - The input source.
Throws:
org.xml.sax.SAXException - Throws exception on SAX error.
java.io.IOException - Throws exception on i/o error.

addNoRequiredAttributeHandler

public void addNoRequiredAttributeHandler(NoRequiredAttributeHandler handler)
This method is not supported.

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:
handler - Handler to be registered.
See Also:
NoRequiredAttributeHandler

setErrorNoByteMark

public void setErrorNoByteMark(boolean error)
This method is not supported.

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:
error - =true means report condition as an error; =false means ignore this condition.

getReaderBufferSize

public int getReaderBufferSize()
This method is not supported.

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(int)

setReaderBufferSize

public void setReaderBufferSize(int size)
This method is not supported.

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:
size - Size of this parser's character-stream-oriented input buffer.
See Also:
getReaderBufferSize()

setWarningRedefinedEntity

public void setWarningRedefinedEntity(boolean warning)
This method is not implemented.

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:
warning - =true means report condition as a warning. =false means ignore this condition.
See Also:
EntityDecl

setWarningNoXMLDecl

public void setWarningNoXMLDecl(boolean warning)
This method is not implemented.

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:
warning - =true means report condition as a warning; =false means ignore this condition.
See Also:
TXPI

setWarningNoDoctypeDecl

public void setWarningNoDoctypeDecl(boolean warning)
This method is not implemented.

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:
warning - =true means report condition as a warning; =false means ignore this condition.
See Also:
DTD

stop

public void stop()
Stops a Parser.readStream() operation. The calling thread will signal that the thread executing in this.readStream() should clean up and return as soon as practical. The calling thread will return immediately. The effect of stop() is sticky, meaning that after stop() has been called, a thread entering readStream() will return immediately. (This helps in the case where the UI thread invokes stop before the processing thread actually enters readStream.

stop affects only the specific instance of the parser (this) on which it is invoked. It is not global; readStream on other parser instances will not be affected.


handleError

protected void handleError(java.lang.String errorKey,
                           java.lang.String errorMsg)
                    throws java.lang.Exception
This method is the basic error handler.
Overrides:
handleError in class com.ibm.xml.framework.XMLParser

reset

public void reset()
This method is not part of the Parser API and is called automatically by the parser internals.

Resets the parser between calls to parse.

Overrides:
reset in class com.ibm.xml.parsers.TXDOMParser

XML for Java Compatibility API 2.0.13