uk.ac.sheffield.jast

Class XMLStreamer

java.lang.Object

java.io.Writer

java.io.BufferedWriter

uk.ac.sheffield.jast.XMLStreamer

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.Appendable, java.lang.AutoCloseable

public class XMLStreamer
extends java.io.BufferedWriter

XMLStreamer is a kind of BufferedWriter that writes XML to any output sink. XMLStreamer is an efficient buffered output streamer that writes XML data to a File, or any kind of basic, or character-based output stream. It is a subclass of BufferedWriter, so writing will be to a buffer of the default size, which is occasionally flushed during output and always flushed upon closing. XMLStreamer receives streaming instructions from a BasicWriter, or a descendant, which has the task of converting an in-memory Java syntax tree into text for output.

In addition to basic character and string writing operations, XMLStreamer inherits the newLine() method (from BufferedWriter) and supplies an indent(int) method to indent the current line to an indentation level. The number of tab spaces to use for each level of indentation may be set. XMLStreamer keeps track of the current output line number, for the sake of error reporting. XMLStreamer implements the Closeable interface by virtue of inheriting from BufferedWriter.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.String	encoding The name of the character set used when encoding characters into bytes.
private boolean	isStandardOutput Secret flag to determine whether the wrapped stream is System.out, used to block closing the standard output stream.
private int	lineNumber The current line number in the output file.
private java.lang.String	tabString The size of a single tabulation used for indentation.

Fields inherited from class java.io.Writer

lock

Constructor Summary

Constructors

Constructor and Description
XMLStreamer(java.io.File file, java.lang.String encoding) Creates an XMLStreamer writing to a file, using a specified character encoding.
XMLStreamer(java.io.OutputStream stream, java.lang.String encoding) Creates an XMLStreamer writing to a basic OutputStream, using a specified character encoding.
XMLStreamer(java.io.Writer writer, java.lang.String encoding) Creates an XMLStreamer writing to a character Writer, using a given character encoding.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this XMLStreamer.
java.lang.String	getEncoding() Returns the character encoding used by this XMLStreamer.
int	getLineNumber() Returns the line number in the output stream.
java.lang.String	getTabString() Returns the current tabulation string.
void	indent(int level) Writes an indentation to the specified indentation level.
void	newLine() Writes a newline according to the operating system platform.
void	setTabString(java.lang.String tabString) Sets the current tabulation string.

Methods inherited from class java.io.BufferedWriter

flush, write, write, write

Methods inherited from class java.io.Writer

append, append, append, write, write

Methods inherited from class java.lang.Object

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

Field Detail

isStandardOutput

private boolean isStandardOutput

Secret flag to determine whether the wrapped stream is System.out, used to block closing the standard output stream.

encoding

private java.lang.String encoding

The name of the character set used when encoding characters into bytes. By default, we assume this is UTF-8, but clients can ask to use other character set encodings, such as ISO-8859-1 (Latin-1).

tabString

private java.lang.String tabString

The size of a single tabulation used for indentation. By default, this is two space characters.

lineNumber

private int lineNumber

The current line number in the output file.

Constructor Detail

XMLStreamer

public XMLStreamer(java.io.File file,
                   java.lang.String encoding)
            throws java.io.FileNotFoundException,
                   java.io.UnsupportedEncodingException

Creates an XMLStreamer writing to a file, using a specified character encoding. Recognised encodings include UTF-8, UTF-16, ISO-8859-1 (Latin-1) and others. Creates this buffered XMLStreamer, writing to an OutputStreamWriter with the given encoding, writing to a basic FileOutputStream opened on the file.

Parameters:

file - the output file.

encoding - the name of the character encoding.

Throws:

java.io.FileNotFoundException - if the file cannot be opened.

java.io.UnsupportedEncodingException - if the character encoding is not supported.

XMLStreamer

public XMLStreamer(java.io.OutputStream stream,
                   java.lang.String encoding)
            throws java.io.UnsupportedEncodingException

Creates an XMLStreamer writing to a basic OutputStream, using a specified character encoding. Recognised encodings include UTF-8, UTF-16, ISO-8859-1 (Latin-1) and others. Creates this buffered XMLStreamer, writing to an OutputStreamWriter with the given encoding, writing to the basic OutputStream.

Parameters:

stream - the basic OutputStream.

encoding - the name of the character encoding.

Throws:

java.io.UnsupportedEncodingException - if the character encoding is not supported.

XMLStreamer

public XMLStreamer(java.io.Writer writer,
                   java.lang.String encoding)

Creates an XMLStreamer writing to a character Writer, using a given character encoding. Recognised encodings include UTF-8, UTF-16, ISO-8859-1 (Latin-1) and others. The character encoding must match that used by the Writer, for consistency. Creates this buffered XMLStreamer wrapping the writer.

Parameters:

writer - the character Writer.

encoding - the name of the character encoding.

Method Detail

getEncoding

public java.lang.String getEncoding()

Returns the character encoding used by this XMLStreamer.

Returns:

the name of the character encoding.

getTabString

public java.lang.String getTabString()

Returns the current tabulation string. By default this is two space characters long.

Returns:

the tabulation string.

setTabString

public void setTabString(java.lang.String tabString)

Sets the current tabulation string. Changes the number of spaces used for each level of indentation. By default, the tabulation string is two character spaces long.

Parameters:

tabString - the new tabulation string.

close

public void close()
           throws java.io.IOException

Closes this XMLStreamer. Closes the underlying output stream, unless that stream is System.out, in which case it is flushed instead. The standard output stream is closed at program termination.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class java.io.BufferedWriter

Throws:

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

newLine

public void newLine()
             throws java.io.IOException

Writes a newline according to the operating system platform.

Overrides:

newLine in class java.io.BufferedWriter

Throws:

java.io.IOException - if an output error occurs while writing.

indent

public void indent(int level)
            throws java.io.IOException

Writes an indentation to the specified indentation level. Writes the current tabulation string the specified number of times.

Parameters:

level - the indentation level.

Throws:

java.io.IOException - if an output error occurs while writing.

getLineNumber

public int getLineNumber()

Returns the line number in the output stream. Line numbering starts at line 1, so reports one more than the line number of the underlying stream.

Returns:

the line number in the output stream.