uk.ac.sheffield.jast

Class BasicWriter

java.lang.Object

uk.ac.sheffield.jast.Logging

uk.ac.sheffield.jast.BasicWriter

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

Direct Known Subclasses:

ASTWriter, XMLWriter

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

BasicWriter is an abstract writer that formats XML data for any output sink. BasicWriter encapsulates an XMLStreamer used for writing the output. Descendants include XMLWriter, which writes a DOM tree of standard XML nodes to a well-formed XML file; and ASTWriter, which writes a tree of user-define AST-compliant Java classes to a well-formed XML file.

BasicWriter implements the internal Logging interface for reporting the context of errors, and manages the encapsulated XMLStreamer, and the Lexicon used by its descendants. The Lexicon defines the mapping from XML entity references to escaped characters or abbreviated boilerplate text. BasicWriter 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 Lexicon	lexicon The Lexicon used by this BasicWriter to encode escaped character data.
protected XMLStreamer	streamer The XMLStreamer used by this BasicWriter to stream the output data.

Constructor Summary

Constructors

Constructor and Description
BasicWriter(XMLStreamer streamer) Creates a BasicWriter using a XMLStreamer to stream the written data.

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 encode the XML file.
void	close() Closes this BasicWriter writer.
protected boolean	endOfStream() Secretly reports whether the end of the underlying XMLStreamer was reached prematurely.
void	flush() Flushes this BasicWriter writer.
protected java.lang.String	getContext() Returns the XML context in which any kind of error was detected.
java.lang.String	getEncoding() Reports the character encoding used by this BasicWriter.
Lexicon	getLexicon() Returns the Lexicon used by this BasicWriter for encoding escaped characters and boilerplate text.
int	getLineNumber() Reports the current line number of this BasicWriter.
void	setLexicon(Lexicon lexicon) Replaces the Lexicon used by this BasicWriter for encoding escaped characters and boilerplate text.

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

streamer

protected XMLStreamer streamer

The XMLStreamer used by this BasicWriter to stream the output data.

lexicon

protected Lexicon lexicon

The Lexicon used by this BasicWriter to encode escaped character data.

Constructor Detail

BasicWriter

public BasicWriter(XMLStreamer streamer)

Creates a BasicWriter using a XMLStreamer to stream the written data.

Parameters:

streamer - the underlying character streamer.

Method Detail

close

public void close()
           throws java.io.IOException

Closes this BasicWriter writer. Closes the underlying XMLStreamer output stream. This method should always be called after writing 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.

flush

public void flush()
           throws java.io.IOException

Flushes this BasicWriter writer. Flushes the underlying XMLStreamer output stream.

Throws:

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

getEncoding

public java.lang.String getEncoding()

Reports the character encoding used by this BasicWriter. This is the same as the character encoding used by this BasicWriter's XMLStreamer.

Returns:

the character encoding.

getLineNumber

public int getLineNumber()

Reports the current line number of this BasicWriter. This is the same as the current line number of this BasicWriter's XMLStreamer.

Specified by:

getLineNumber in class Logging

Returns:

the current line number.

getContext

protected java.lang.String getContext()

Returns the XML context in which any kind of error was detected. The default implementation returns an empty String. This is redefined in each subclass of BasicWriter, according to the type of syntax tree that is traversed.

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 underlying XMLStreamer was reached prematurely. Always returns false, since it is not possible for an output stream to end prematurely.

Specified by:

endOfStream in class Logging

Returns:

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

getLexicon

public Lexicon getLexicon()

Returns the Lexicon used by this BasicWriter for encoding 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 BasicWriter.

setLexicon

public void setLexicon(Lexicon lexicon)

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

Parameters:

lexicon - the Lexicon to use instead.

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 encode the XML file. This method is called before writing the XML document, when the encoding attribute has been set.

Parameters:

declared - the character encoding in the XML declaration.

actual - the character encoding used by the streamer.

Throws:

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