uk.ac.sheffield.jast

Class BasicReader

java.lang.Object

uk.ac.sheffield.jast.Logging

uk.ac.sheffield.jast.BasicReader

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

Direct Known Subclasses:

ASTReader, DTDReader, XMLReader

public abstract class BasicReader
extends Logging
implements java.io.Closeable

BasicReader is the abstract ancestor of pull-parsers that construct syntax trees. BasicReader is the foundation for pull-parsers that construct different kinds of syntax tree. Descendants include: XMLReader, which constructs a DOM tree of standard XML nodes from the input file; ASTReader, which constructs an AST tree of user-defined AST-compliant Java classes from the input file; and DTDReader, which compiles a set of Doctype grammar rules from the input file.

BasicReader implements the internal Logging interface for reporting the context of errors, and manages the underlying BasicScanner, and the Lexicon used by its descendants. The BasicScanner serves up the stream of tokens to all subclasses. The Lexicon defines the mapping from XML entity references to escaped characters or abbreviated boilerplate text. A DTDReader may add extra entity reference definitions to the Lexicon, before handing this back to an XMLReader or ASTReader. BasicReader implements the Closeable interface, so may be used in try-with-resources blocks (since JDK 1.7).

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
protected int	lastToken The lookahead token last read from the Scanner.
protected Lexicon	lexicon The lexicon used by this BasicReader to decode entity references.
protected BasicScanner	scanner The scanner used by this BasicReader to scan the input data.
protected Validation	validation An enumerated type describing the level of automatic validation to perform.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BasicReader(BasicScanner scanner) Creates a BasicReader reading tokens from a BasicScanner created by the subclass.
protected	BasicReader(BasicScanner scanner, Lexicon lexicon) Creates a BasicReader reading tokens from a BasicScanner created by the subclass, and using a given Lexicon to decode entity references.

Method Summary

Modifier and Type	Method and Description
protected void	checkEncoding(java.lang.String declared, java.lang.String actual) Checks that the declared character encoding matches the actual character encoding used to decode the XML file.
void	close() Closes this BasicReader reader.
protected boolean	endOfStream() Secretly reports whether the end of the input stream has been reached.
protected java.lang.String	getContext() Reports the XML document context in which an error was detected.
java.lang.String	getEncoding() Reports the character encoding used by this BasicReader.
Lexicon	getLexicon() Returns the Lexicon used by this BasicReader for decoding escaped characters and boilerplate text.
protected int	getLineNumber() Reports the current line number reached by this BasicReader.
protected java.lang.String	parseQuotedValue() Parses the quoted value of an XML attribute.
void	setLexicon(Lexicon lexicon) Replaces the Lexicon used by this BasicReader for decoding escaped characters and boilerplate text.
void	setValidation(Validation validation) Sets the level of automatic validation performed by XML/AST readers.

Methods inherited from class uk.ac.sheffield.jast.Logging

encodingError, semanticError, syntaxError

Methods inherited from class java.lang.Object

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

Field Detail

scanner

protected BasicScanner scanner

The scanner used by this BasicReader to scan the input data.

lexicon

protected Lexicon lexicon

The lexicon used by this BasicReader to decode entity references.

validation

protected Validation validation

An enumerated type describing the level of automatic validation to perform. IGNORE is the default; EXPAND causes XML readers to read associated DTDs (internal/external) and expand entity declarations; DOCTYPE causes XML readers to perform full validation from the compiled doctype grammar; SCHEMA causes XML readers to read an XMLSchema from an external file, and then perform full validation from the compiled XMLSchema grammar.

lastToken

protected int lastToken

The lookahead token last read from the Scanner.

Constructor Detail

BasicReader

protected BasicReader(BasicScanner scanner,
                      Lexicon lexicon)

Creates a BasicReader reading tokens from a BasicScanner created by the subclass, and using a given Lexicon to decode entity references.

Parameters:

scanner - the BasicScanner.

lexicon - the Lexicon.

BasicReader

protected BasicReader(BasicScanner scanner)

Creates a BasicReader reading tokens from a BasicScanner created by the subclass. Installs the BasicScanner; and creates a default Lexicon to decode the standard five entity references.

Parameters:

scanner - the BasicScanner.

Method Detail

close

public void close()
           throws java.io.IOException

Closes this BasicReader reader. Closes the underlying Scanner input stream. This method should always be called after reading has completed.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException - if an I/O fault occurs during closing.

getEncoding

public java.lang.String getEncoding()

Reports the character encoding used by this BasicReader. This is the same as the character encoding used by this BasicReader's XMLScanner.

Returns:

the character encoding.

checkEncoding

protected void checkEncoding(java.lang.String declared,
                             java.lang.String actual)
                      throws java.io.UnsupportedEncodingException

Checks that the declared character encoding matches the actual character encoding used to decode the XML file. This method is called at the end of processing the XML declaration. This reader also updates the character-sets to be used by the Lexicon, if the Latin-1 encoding ISO-8859-1 was declared.

Parameters:

declared - the character encoding in the XML declaration.

actual - the character encoding used by the parser.

Throws:

java.io.UnsupportedEncodingException - if the encodings don't match.

getLineNumber

protected int getLineNumber()

Reports the current line number reached by this BasicReader. This is one line behind the current line reached by the underlying XMLScanner, which will have consumed tokens up to the end of the line. Line numbering starts at line 1.

Specified by:

getLineNumber in class Logging

Returns:

the current line number.

getContext

protected java.lang.String getContext()

Reports the XML document context in which an error was detected. This is the same as the context of this BasicReader's XMLScanner.

Specified by:

getContext in class Logging

Returns:

the context, in the style of XPath.

endOfStream

protected boolean endOfStream()

Secretly reports whether the end of the input stream has been reached. Delegates to the underlying XMLScanner.

Specified by:

endOfStream in class Logging

Returns:

true, if the end of the stream has been reached.

setValidation

public void setValidation(Validation validation)

Sets the level of automatic validation performed by XML/AST readers. The default is IGNORE, which instructs readers to ignore all DTD and XSD indicators. EXPAND instructs readers first to read a DTD file to obtain extra entity definitions, before processing the XML file. DOCTYPE instructs readers also to perform full validation from the compiled Doctype grammar. SCHEMA instructs readers instead to read an XMLSchema from an external schema file, and perform full validation from the compiled XMLSchema grammar.

Parameters:

validation - one of: IGNORE, EXPAND, DOCTYPE, SCHEMA.

getLexicon

public Lexicon getLexicon()

Returns the Lexicon used by this BasicReader for decoding escaped characters and boilerplate text. The returned Lexicon may be updated directly and does not have to be replaced afterwards.

Returns:

the Lexicon used by this BasicReader.

setLexicon

public void setLexicon(Lexicon lexicon)

Replaces the Lexicon used by this BasicReader for decoding escaped characters and boilerplate text. The supplied Lexicon will be used instead of this BasicReader's original Lexicon.

Parameters:

lexicon - the Lexicon to use instead.

parseQuotedValue

protected java.lang.String parseQuotedValue()
                                     throws java.io.IOException,
                                            SyntaxError

Parses the quoted value of an XML attribute. Returns the decoded value-string after checking that quotation-marks are matched.

Returns:

the value-string.

Throws:

java.io.IOException - if the token stream fails.

SyntaxError - if the XML syntax is faulty.