StreamParser (NetPhantom® 7.7 Java API Specification)

java.lang.Object
- org.openxml.parser.StreamParser

All Implemented Interfaces:

EntityResolver, Locator

Direct Known Subclasses:

ContentParser
```
public abstract class StreamParser
extends Object
implements Locator, EntityResolver
```
Implements layers 0 and 1 of the parser architecture, reading characters and tokens from the input stream. In addition implements support for reading the stream location and for reporting errors.
This parser is created by a derived class. The init(org.xml.sax.InputSource) method must be called before the parser is used or re-used (the parser is re-entrant).
The input stream is consumed through the readChar() and pushBack() methods that work on the value of the state variable _curChar. This single variable is constantly reused by all the higher level methods to denote the last character read, so be careful in how you use it.
Tokens are read by a variaty of low level methods and stored in the state variable _tokenText. Once again, this signle variable is constantly reused by all the higher level methods to contain the last read token, so be careful in how you use it. This variable is of type FastString, an optimized version of StringBuffer that can be reused perpetually by calling FastString.setLength(int) with zero.
Generally methods should document the expected states of _curChar and _tokenText on entry and on exit and whether they change them. To make the parser efficient, some methods will leave either variable with an undertermined value, others will levae these variables with the next value to be processed. It is important to pay attention to details.
The #Locator interface is implemented to return indication of the parser's location in the input stream (identifier, line number, etc).
All the error reporting methods are implemented at this layer. Errors are generated from a resource file (see Resources where the actual error message is held. The error message is selected by some generic name, either by calling (message(java.lang.String)) or by formatting argument values directly into the message (format(java.lang.String, java.lang.Object)).
Errors are generally reported at one of four levels:
- Warnings rarely cause the parser to stop and are reported through warning(java.lang.String)
- Validity errors that are not mere warnings might cause the parser to stop and are reported through error(int, java.lang.String) with the level VALIDITY
- Well formed errors might cause the parser to stop and are reported through error(int, java.lang.String) with the level WELL_FORMED
- Fatal errors always cause the parser to stop and are reported through fatalError(java.lang.Exception)
An error handler can be associated with this parser. If the error handler is ErrorReport, the extended error features will be used. If no error handler is used, warnings are ignored, errors and fatal errors will throw an exception and stop the parser.
Author:

Assaf Arkin

See Also:

Parser, ErrorReport, Resources, FastString

Field Summary

Fields
Modifier and Type	Field and Description
`protected int`	`_curChar` Holds the last character read by `readChar()`, or the next character to be pushed back (see `pushBack()`).
`protected FastString`	`_tokenText` Holds the contents of the last token read by one of the token reading methods.
`protected static char`	`CR` Carriage return.
`protected static int`	`EOF` Indicates that end of file (or the input stream) has been reached and no more character are availble.
`protected static char`	`LF` Line feed.
`protected static char`	`SPACE` Space.
`protected static short`	`TOKEN_CDATA` CDATA section token.
`protected static short`	`TOKEN_CLOSE_TAG` Close tag token.
`protected static short`	`TOKEN_COMMENT` Comment token.
`protected static short`	`TOKEN_DTD` DTD token.
`protected static short`	`TOKEN_ENTITY_REF` Entity reference token.
`protected static short`	`TOKEN_EOF` End of input.
`protected static short`	`TOKEN_OPEN_TAG` Open tag token.
`protected static short`	`TOKEN_PE_REF` Parameter entity reference.
`protected static short`	`TOKEN_PI` Processing instruction token.
`protected static short`	`TOKEN_SECTION` DTD section token.
`protected static short`	`TOKEN_SECTION_END` DTD section token end.
`protected static short`	`TOKEN_TEXT` Textual token.
`protected static int`	`VALIDITY` Error level used for reporting validity errors.
`protected static int`	`WELL_FORMED` Error level used for reporting well formed errors.

Constructor Summary

Constructors
Modifier Constructor and Description

protected StreamParser()
Protected constructor only accessible from derived class.

Constructors
Modifier	Constructor and Description
`protected`	`StreamParser()` Protected constructor only accessible from derived class.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected boolean`	`canReadName(String name)` Returns true if the specified name can be read and consumes it all.
`protected void`	`close()` Closes the input stream.
`protected void`	`error(int errorLevel, String message)` Reports a parser error.
`protected void`	`fatalError(Exception except)` Reports a fatal error.
`protected String`	`format(String message, Object arg1)` Format a message from the resource file based on the selected locale and given argument.
`protected String`	`format(String message, Object arg1, Object arg2)` Format a message from the resource file based on the selected locale and given arguments.
`protected String`	`format(String message, Object arg1, Object arg2, Object arg3)` Format a message from the resource file based on the selected locale and given arguments.
`int`	`getColumnNumber()`
`ErrorHandler`	`getErrorHandler()` Returns the error handler associated with this parser (if any).
`SAXException`	`getLastException()` Returns the last error issued by the parser.
`int`	`getLineNumber()`
`String`	`getPublicId()`
`protected Reader`	`getReader()` Returns the reader used for accessing the underlying input stream.
`String`	`getSystemId()`
`protected void`	`init(InputSource input)` Initializes the parser to parse a new document.
`protected boolean`	`isClosed()` Returns true if the document has been fully parsed and the parsed has been closed.
`protected boolean`	`isNamePart(int ch)` Returns true if character is part of a valid name.
`protected boolean`	`isNamePartFirst(int ch)`
`protected boolean`	`isSpace(int ch)` Returns true if character is a whitespace.
`protected boolean`	`isTokenAllSpace()` Returns true if the token is all whitespace.
`protected boolean`	`isWarning()` Returns true if warning should be issued.
`protected String`	`message(String message)` Return a message from the resource file based on the selected locale.
`protected void`	`pushBack()` Push back the last character read into `_curChar`.
`protected void`	`pushBack(int ch)` Push back a single character.
`void`	`pushBack(String pushStr)`
`protected void`	`pushBackToken()` Pushes back the token contained in `_tokenText`.
`protected int`	`readChar()` Reads and returns a single character from the input stream.
`protected boolean`	`readTokenName()` Reads a valid token name and places it in `_tokenText`.
`protected boolean`	`readTokenNameCur()` Reads a valid token name and places it in `_tokenText`.
`protected boolean`	`readTokenQuoted()` Reads the quoted identifier token.
`InputSource`	`resolveEntity(String publicId, String systemId)`
`protected void`	`setEncoding(String encoding)` Changes the encoding of the input stream.
`void`	`setErrorHandler(ErrorHandler handler)` Associates this parser with an error handler.
`void`	`setLocale(Locale locale)` Set the locale for error messages.
`protected void`	`skipSpace()`
`protected void`	`warning(String message)` Reports a warning.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - EOF
```
protected static final int EOF
```
    Indicates that end of file (or the input stream) has been reached and no more character are availble. This character is invalid. It is legal to push is back, though.
    
    See Also:
    
    Constant Field Values
  - LF
```
protected static final char LF
```
    Line feed. Character code 0x0A.
    
    See Also:
    
    Constant Field Values
  - CR
```
protected static final char CR
```
    Carriage return. Character code 0x0D.
    
    See Also:
    
    Constant Field Values
  - SPACE
```
protected static final char SPACE
```
    Space. Character code 0x20.
    
    See Also:
    
    Constant Field Values
  - TOKEN_EOF
```
protected static final short TOKEN_EOF
```
    End of input. This token indicates that the end of the input stream (for this entity) has been reached. Reading past this token will always return this token.
    
    See Also:
    
    Constant Field Values
  - TOKEN_TEXT
```
protected static final short TOKEN_TEXT
```
    Textual token. _tokenText contains the plain text. This token is generally used to construct a Text node when appearing in the content.
    
    See Also:
    
    Constant Field Values
  - TOKEN_ENTITY_REF
```
protected static final short TOKEN_ENTITY_REF
```
    Entity reference token. _tokenText contains the entity name. This token is generally used to construct a EntityReference node.
    
    See Also:
    
    Constant Field Values
  - TOKEN_OPEN_TAG
```
protected static final short TOKEN_OPEN_TAG
```
    Open tag token. _tokenText contains the tag name. This token is generally used to construct a Element node. Only the tag name is read, the attributes and terminating '>' should be read separately (see ContentParser.parseAttributes(java.lang.String)).
    
    See Also:
    
    Constant Field Values
  - TOKEN_CLOSE_TAG
```
protected static final short TOKEN_CLOSE_TAG
```
    Close tag token. _tokenText contains the tag name. This token is generally used to construct a Element node. The entire closing tag has been consumed.
    
    See Also:
    
    Constant Field Values
  - TOKEN_COMMENT
```
protected static final short TOKEN_COMMENT
```
    Comment token. _tokenText contains the comment text (if in mode #MODE_STORE_COMMENT). This token is generally used to construct a Comment node.
    
    See Also:
    
    Constant Field Values
  - TOKEN_PI
```
protected static final short TOKEN_PI
```
    Processing instruction token. _tokenText contains the processing instruction (if in mode #MODE_STORE_PI). This token is generally used to construct a ProcessingInstruction node.
    
    See Also:
    
    Constant Field Values
  - TOKEN_CDATA
```
protected static final short TOKEN_CDATA
```
    CDATA section token. _tokenText contains the CDATA contents. This token is generally used to construct a CDATASection node.
    
    See Also:
    
    Constant Field Values
  - TOKEN_DTD
```
protected static final short TOKEN_DTD
```
    DTD token. _tokenText contains the DTD entity type (whatever comes after '
    
    See Also:
    
    Constant Field Values
  - TOKEN_SECTION
```
protected static final short TOKEN_SECTION
```
    DTD section token. Indicates a 'TOKEN_CDATA would have been returned. This token is valid only in the external DTD subset.
    
    See Also:
    
    Constant Field Values
  - TOKEN_SECTION_END
```
protected static final short TOKEN_SECTION_END
```
    DTD section token end. Indicates a ']]>' that terminates an 'INCLUDE' or 'IGNORE' section. The 'CDATA' terminator is always consumed for the TOKEN_CDATA token. This token is valid only in the external DTD.
    
    See Also:
    
    Constant Field Values
  - TOKEN_PE_REF
```
protected static final short TOKEN_PE_REF
```
    Parameter entity reference. _tokenText contains the entity name. This token is valid only in the DTD.
    
    See Also:
    
    Constant Field Values
  - WELL_FORMED
```
protected static final int WELL_FORMED
```
    Error level used for reporting well formed errors.
    
    See Also:
    
    Constant Field Values
  - VALIDITY
```
protected static final int VALIDITY
```
    Error level used for reporting validity errors.
    
    See Also:
    
    Constant Field Values
  - _curChar
```
protected int _curChar
```
    Holds the last character read by readChar(), or the next character to be pushed back (see pushBack()). Set to EOF if end of input stream has been reached.
    This is a state variable. Methods that use it directly or indirectly must be alert to its present value and usage. General value on entry/exit is specified in the method comment.
  - _tokenText
```
protected FastString _tokenText
```
    Holds the contents of the last token read by one of the token reading methods. Set to TOKEN_EOF if end of input stream has been reached. Many methods read, modify and possibly return values in _tokenText, so its value should not be assumed to remain constant between method calls.
    A FastString is allocated and constantly reused by resetting its length to zero. In some instances, it is replaced with an alternative FastString object. IT IS IMPORTANT that no other variable will reference this string.
    This is a state variable. Methods that use it directly or indirectly must be alert to its present state and usage and must reset it as needed. General value on entry/exit is specified in the method comment.
- Constructor Detail
  - StreamParser
```
protected StreamParser()
```
    Protected constructor only accessible from derived class.
- Method Detail
  - init
```
protected void init(InputSource input)
             throws SAXException,
                    IOException
```
    Initializes the parser to parse a new document. Must be called before any parsing occurs and must provide input stream or reader.
    The input source is expected to provide the public and system identifiers of the document for the purpose of error reporting and relative external entity resolving. No checking is done on their validity.
    The input source must specify either an input stream or a reader. If neither is specified, an exception is thrown. If a reader is specified, it is used for consuming the source document. If an input stream is specified, it is preferred to the reader and the specified encoding is used to convert it. If the specified encoding is not supported, an exception is thrown. If no encoding is specified, the default UTF-8 is used.
    Note, the input source is expected to be available to the parser for the entire duration of parsing the document.
    
    Parameters:
    
    input - The input source to parse
    
    Throws:
    
    SAXException - The input source cannot be used
    
    IOException
  - readTokenQuoted
```
protected final boolean readTokenQuoted()
                                 throws SAXException
```
    Reads the quoted identifier token. Quotes can be either single or double, but both opening and closing quotes must be identical. Everything inbetween the quotes is stored in _tokenText. Returns true if a quoted value was found (i.e. opening quote followed on the input stream).
    
    Returns:
    
    True if quoted value was found
    
    Throws:
    
    SAXException - A low-level error has been encountered
  - readTokenName
```
protected final boolean readTokenName()
                               throws SAXException
```
    Reads a valid token name and places it in _tokenText. If a valid name can be read, it is placed in _tokenText and true is returned, otherwise false is returned and the input stream is not affected.
    A valid token name is defined as consisting of any letter, underscore or colon, followed by zero or more letters and digits, underscores, hyphens, colons and periods. Unlike other languages, letters and digits can be specified in all Unicode supported languages.
    _curChar does not contain a valid value on either entry or exit from this method.
    
    Returns:
    
    True if valid name of at least one character found
    
    Throws:
    
    SAXException - A low-level error has been encountered
  - readTokenNameCur
```
protected final boolean readTokenNameCur()
                                  throws SAXException
```
    Reads a valid token name and places it in _tokenText. If a valid name can be read, it is placed in _tokenText and true is returned, otherwise false is returned and the input stream is not affected.
    A valid token name is defined as consisting of any letter, underscore or colon, followed by zero or more letters and digits, underscores, hyphens, colons and periods. Unlike other languages, letters and digits can be specified in all Unicode supported languages.
    {@link #_curChar) contains the last character read (first token character) on entry, but does not contain a valid value on exit.
    
    Returns:
    
    True if valid name of at least one character found
    
    Throws:
    
    SAXException - A low-level error has been encountered
  - canReadName
```
protected final boolean canReadName(String name)
                             throws SAXException
```
    Returns true if the specified name can be read and consumes it all. Attempts to read the name in its entirety. If the name is read, it is consumed from the input stream and the method returns true. If the name is not read, the input stream is not affected and the method return false.
    
    Returns:
    
    True if the name was read and consumed in its entirety
    
    Throws:
    
    SAXException - A low-level error has been encountered
  - isTokenAllSpace
```
protected final boolean isTokenAllSpace()
```
    Returns true if the token is all whitespace. The token is contained in _tokenText and all its characters must be whitespace as defined by isSpace(int).
    
    Returns:
    
    True if _tokenText is all whitespace
  - isNamePart
```
protected final boolean isNamePart(int ch)
```
    Returns true if character is part of a valid name. The first flag indicates whether character is expected to be the first or any other in the name.
    Valid names are defined as consisting of any letter, underscore or colon, followed by zero or more letters and digits, underscores, hyphens, colons and periods. Unlike other languages, letters and digits can be specified in all Unicode supported languages.
    Test performed on _curChar.
    
    Parameters:
    
    first - True if first letter in the name
    
    Returns:
    
    True if character is valid in name context
  - isNamePartFirst
```
protected final boolean isNamePartFirst(int ch)
```
  - isSpace
```
protected final boolean isSpace(int ch)
```
    Returns true if character is a whitespace. Space (0x20), tab (0x09), line feed (0x0A), carriage return (0x0D) are defined as whitespaces. Test performed on _curChar.
    
    Parameters:
    
    ch - The character to check
    
    Returns:
    
    True if character is a whitespace
  - skipSpace
```
protected final void skipSpace()
                        throws SAXException
```
    Throws:
    
    SAXException
  - pushBackToken
```
protected final void pushBackToken()
```
    Pushes back the token contained in _tokenText. The value of _tokenText is identical on entry and exit. The value of _curChar is unaffected.
  - readChar
```
protected final int readChar()
                      throws SAXException
```
    Reads and returns a single character from the input stream. If characters were pushed back they are returned in the same order they were pushed (LIFO). If end of input stream has been reached, EOF is returned. The returned character is also available in the _curChar variable.
    Line breaks (LF, CR and CR+LF) are returned as a single line feed (0x0A) character.
    
    Returns:
    
    A single character read from the input stream, also available in _curChar
    
    Throws:
    
    SAXException - An I/O exception has been encountered when reading from the input stream
  - pushBack
```
protected final void pushBack()
```
    Push back the last character read into _curChar. The pushed back character will be returned when readChar() is called next. Any number of characters can be pushed back. The push back buffer is a LIFO stack, so text should be pushed back in reverse order. It is not an error to push back the value EOF.
  - pushBack
```
protected final void pushBack(int ch)
```
    Push back a single character. The pushed back character will be returned when readChar() is called next. Any number of characters can be pushed back. The push back buffer is a LIFO stack, so text should be pushed back in reverse order. It is not an error to push back the value EOF.
    
    Parameters:
    
    ch - The character to push back
  - pushBack
```
public void pushBack(String pushStr)
```
  - setEncoding
```
protected final void setEncoding(String encoding)
                          throws SAXException
```
    Changes the encoding of the input stream. This is only effective if an input stream was specified and not a reader.
    
    Throws:
    
    SAXException
  - getReader
```
protected final Reader getReader()
```
    Returns the reader used for accessing the underlying input stream.
    
    Returns:
    
    Reader used by this parser
  - close
```
protected final void close()
```
    Closes the input stream. Any read operation following this closing will result in an I/O exception.
  - isClosed
```
protected final boolean isClosed()
```
    Returns true if the document has been fully parsed and the parsed has been closed. Parsing operations should be rejected when the parser is closed. The parser is closed by calling the close() method.
    
    Returns:
    
    True if parser has been closed
  - getLineNumber
```
public final int getLineNumber()
```
    Specified by:
    
    getLineNumber in interface Locator
  - getColumnNumber
```
public final int getColumnNumber()
```
    Specified by:
    
    getColumnNumber in interface Locator
  - getSystemId
```
public final String getSystemId()
```
    Specified by:
    
    getSystemId in interface Locator
  - getPublicId
```
public final String getPublicId()
```
    Specified by:
    
    getPublicId in interface Locator
  - resolveEntity
```
public InputSource resolveEntity(String publicId,
                                 String systemId)
                          throws IOException,
                                 SAXException
```
    Specified by:
    
    resolveEntity in interface EntityResolver
    
    Throws:
    
    IOException
    
    SAXException
  - getLastException
```
public final SAXException getLastException()
```
    Returns the last error issued by the parser. This might be any error or fatal exception that was thrown or not thrown by the parser. Warnings are not returned.
    
    Returns:
    
    The last error issued, or null
  - setErrorHandler
```
public final void setErrorHandler(ErrorHandler handler)
```
    Associates this parser with an error handler. By default the parser creates and users an ErrorReport for reporting errors. Some applications may wish to provide their own error handler, by calling this method. If the handler is set to null, all errors encountered in the code will throw an exception and stop the parser.
    
    Parameters:
    
    handler - The new error handler to use, or null
    
    See Also:
    
    ErrorHandler, ErrorReport
  - getErrorHandler
```
public final ErrorHandler getErrorHandler()
```
    Returns the error handler associated with this parser (if any). By default this is an ErrorReport.
    
    Returns:
    
    The error handler of this parser, or null
    
    See Also:
    
    ErrorHandler
  - setLocale
```
public final void setLocale(Locale locale)
```
    Set the locale for error messages. If a resource file for this locale exists, messages will be formatted in this locale.
    
    Parameters:
    
    locale - The locale to use, null for the system default
  - isWarning
```
protected final boolean isWarning()
```
    Returns true if warning should be issued. Use this method to avoid creating warning messages when there is no error handler, or the error handler is not interested in them.
    
    Returns:
    
    True if error handler interested in warnings
  - warning
```
protected final void warning(String message)
                      throws SAXException
```
    Reports a warning. A warning is not an error and is not supposed to be thrown, but the SAX error handler can throw an exception.
    
    Parameters:
    
    message - The warning message
    
    Throws:
    
    SAXException - The error handler might respond by throwing an exception that will stop the parser
  - error
```
protected final void error(int errorLevel,
                           String message)
                    throws SAXException
```
    Reports a parser error. Errors fall under a number of severity levels. Depending on the level the error handler may or may not throw an exception and stop the parser. Error levels are not supported by SAX.
    
    Parameters:
    
    errorLevel - The error level
    
    message - The error message
    
    Throws:
    
    SAXException - The error handler might respond by throwing an exception that will stop the parser
  - fatalError
```
protected final void fatalError(Exception except)
                         throws SAXException
```
    Reports a fatal error. A fatal error will always throw an exception and stop the parser. The exception is a SAX exception which encapsulates the original exception.
    
    Parameters:
    
    except - The fatal exception
    
    Throws:
    
    SAXException - The error handler will respond by throwing an exception that will stop the parser
  - message
```
protected final String message(String message)
```
    Return a message from the resource file based on the selected locale. This is a convenience method hiding Resources.message(java.lang.String) with a locale known to the parser.
    
    Parameters:
    
    message - The message identifier
    
    Returns:
    
    The local-specific message text
  - format
```
protected final String format(String message,
                              Object arg1)
```
    Format a message from the resource file based on the selected locale and given argument. This is a convenience method hiding Resources.format(java.lang.String, java.lang.Object) with a locale known to the parser.
    
    Parameters:
    
    message - The message identifier
    
    arg1 - The first argument
    
    Returns:
    
    The local-specific message text
  - format
```
protected final String format(String message,
                              Object arg1,
                              Object arg2)
```
    Format a message from the resource file based on the selected locale and given arguments. This is a convenience method hiding Resources.format(java.lang.String, java.lang.Object) with a locale known to the parser.
    
    Parameters:
    
    message - The message identifier
    
    arg1 - The first argument
    
    arg2 - The second argument
    
    Returns:
    
    The local-specific message text
  - format
```
protected final String format(String message,
                              Object arg1,
                              Object arg2,
                              Object arg3)
```
    Format a message from the resource file based on the selected locale and given arguments. This is a convenience method hiding Resources.format(java.lang.String, java.lang.Object) with a locale known to the parser.
    
    Parameters:
    
    message - The message identifier
    
    arg1 - The first argument
    
    arg2 - The second argument
    
    arg3 - The third argument
    
    Returns:
    
    The local-specific message text

Class StreamParser

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EOF

LF

CR

SPACE

TOKEN_EOF

TOKEN_TEXT

TOKEN_ENTITY_REF

TOKEN_OPEN_TAG

TOKEN_CLOSE_TAG

TOKEN_COMMENT

TOKEN_PI

TOKEN_CDATA

TOKEN_DTD

TOKEN_SECTION

TOKEN_SECTION_END

TOKEN_PE_REF

WELL_FORMED

VALIDITY

_curChar

_tokenText

Constructor Detail

StreamParser

Method Detail

init

readTokenQuoted

readTokenName

readTokenNameCur

canReadName

isTokenAllSpace

isNamePart

isNamePartFirst

isSpace

skipSpace

pushBackToken

readChar

pushBack

pushBack

pushBack

setEncoding

getReader

close

isClosed

getLineNumber

getColumnNumber

getSystemId

getPublicId

resolveEntity

getLastException

setErrorHandler

getErrorHandler

setLocale

isWarning

warning

error

fatalError

message

format

format

format