Contents | Package | Class | Tree | Deprecated | Index | Help | XML for Java
PREV | NEXT | SHOW LISTS | HIDE LISTS |

# Class com.ibm.xml.parser.Parser

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

public class Parser
extends java.lang.Object

Parser is the XML4J parser that examines an XML document and generates an object tree of Document Object Model (DOM) Nodes. Details of these Nodes are provided by the references below.

Version:
  1.1
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.
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 ends job by the first error.
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

Method Detail

### 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

### 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 print() 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

### 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 ends job by the first error.

  By default, this parser continues parsing after an error occurs

### 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

Contents | Package | Class | Tree | Deprecated | Index | Help |
PREV | NEXT | SHOW LISTS | HIDE LISTS |