uk.ac.sheffield.jast

Class XMLWriter

java.lang.Object

uk.ac.sheffield.jast.Logging

uk.ac.sheffield.jast.BasicWriter

uk.ac.sheffield.jast.XMLWriter

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class XMLWriter
extends BasicWriter

XMLWriter is a serializer that writes out a classic XML document tree. XMLWriter performs a pre-order traversal of the document tree, starting at the root Document node, and writes out an XML text file representing the tree. The tree consists of classic XML nodes such as Declaration, Element, Doctype, Attribute and Text, which are provided in the sub-package uk.ac.sheffield.jast.xml.

XMLWriter uses a low-level XMLStreamer to stream character data to the output stream. By default, XMLWriter pretty-prints the XML file afresh, discarding any formatting whitespace nodes surrounding elements in the document tree. XMLWriter may be requested to preserve the actual layout of the document tree. The output will then depend on whether the tree was originally constructed preserving all whitespace, in which case the output file mirrors the input file; otherwise the output file will be compact, without any extra formatting whitespace. XMLWriter implements the Closeable interface by virtue of inheriting from BasicWriter.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
private Content	current The current content being unpacked.
private boolean	prettyPrint Flag describing whether to pretty print the next XML content.
private boolean	rawLayout Flag describing whether to preserve the layout of the Document.

Fields inherited from class uk.ac.sheffield.jast.BasicWriter

lexicon, streamer

Constructor Summary

Constructors

Constructor and Description
XMLWriter(java.io.File file) Creates an XMLWriter writing to a file, using the default character encoding UTF-8.
XMLWriter(java.io.File file, java.lang.String encoding) Creates an XMLWriter writing to a file, using the specified character encoding.
XMLWriter(java.io.OutputStream stream, java.lang.String encoding) Creates an XMLWriter writing to a basic output stream, using the specified character encoding.
XMLWriter(java.io.Writer writer) Creates an XMLWriter writing to a character writer, using the default ISO-8859-1 (Latin 1) character encoding specified for the MIME-type text/xml.
XMLWriter(java.io.Writer writer, java.lang.String encoding) Creates an XMLWriter writing to a character writer, using the specified character encoding.

Method Summary

Modifier and Type	Method and Description
protected java.lang.String	getContext() Reports the current syntax tree context of this XMLWriter.
void	preserveLayout(boolean value) Instructs this XMLWriter whether to preserve, or ignore, the layout of the Document.
protected void	writeAttribute(Attribute attribute) Writes an Attribute.
protected void	writeComment(Comment comment) Writes a Comment.
protected void	writeContent(Content content, int indent) Writes one kind of Content.
protected void	writeData(Data data) Writes an escaped character Data node.
protected void	writeDeclaration(Declaration directive) Writes out the XML Declaration.
protected void	writeDoctype(Doctype doctype) Writes out a Doctype declaration.
void	writeDocument(Document document) Writes a Document to an XML output file or stream.
protected void	writeElement(Element element, int indent) Writes an Element.
protected void	writeInstruction(Instruction directive) Writes a processing Instruction.
protected void	writeText(Text text) Writes a Text node.

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

checkEncoding, close, endOfStream, flush, getEncoding, getLexicon, getLineNumber, setLexicon

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

current

private Content current

The current content being unpacked.

prettyPrint

private boolean prettyPrint

Flag describing whether to pretty print the next XML content. If raw layout is being preserved, this is always false. Otherwise, this is set to true, unless the last printed content was a Text element. This controls how new lines and indentation are inserted before each marked-up element (but not before Text content). Initially this is false.

rawLayout

private boolean rawLayout

Flag describing whether to preserve the layout of the Document. By default this is false and the Document will be pretty-printed afresh, inserting new layout text. If set to true, the stored layout of the Document will be preserved (whether it has no layout text, or some original layout text).

Constructor Detail

XMLWriter

public XMLWriter(java.io.File file)
          throws java.io.FileNotFoundException,
                 java.io.UnsupportedEncodingException

Creates an XMLWriter writing to a file, using the default character encoding UTF-8. Creates a XMLStreamer writing to the file with the UTF-8 encoding.

Parameters:

file - the output text file.

Throws:

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

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

XMLWriter

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

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

Parameters:

file - the output text file.

encoding - the name of the character encoding.

Throws:

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

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

XMLWriter

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

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

Parameters:

stream - the basic OutputStream.

encoding - the name of the character encoding.

Throws:

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

XMLWriter

public XMLWriter(java.io.Writer writer)

Creates an XMLWriter writing to a character writer, using the default ISO-8859-1 (Latin 1) character encoding specified for the MIME-type text/xml. This character encoding should match the encoding actually used by the Writer, since this is impossible to check. Creates a XMLStreamer writing to the writer with the ISO-8859-1 encoding.

Parameters:

writer - a character Writer.

XMLWriter

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

Creates an XMLWriter writing to a character writer, using the specified character encoding. The character encoding should match the encoding actually used by the Writer, since this is impossible to check. Creates a XMLStreamer writing to the writer with the given encoding.

Parameters:

writer - a character Writer.

encoding - the name of the character encoding.

Method Detail

getContext

protected java.lang.String getContext()

Reports the current syntax tree context of this XMLWriter. Returns a path from the root document to the current node on top of the stack.

Overrides:

getContext in class BasicWriter

Returns:

the current syntax tree context.

preserveLayout

public void preserveLayout(boolean value)

Instructs this XMLWriter whether to preserve, or ignore, the layout of the Document. By default this is false and the Document will be pretty-printed afresh, inserting new layout text. If set to true, the stored layout of the Document will be preserved (whether it has no layout text, or some original layout text).

Parameters:

value - true, to write a Document with all original layout.

writeDocument

public void writeDocument(Document document)
                   throws java.io.UnsupportedEncodingException,
                          SemanticError,
                          java.io.IOException

Writes a Document to an XML output file or stream. Checks first that the Document object is well-formed, having a Declaration and a single root Element; then checks that the Declaration declares the same character encoding as that being used by this XMLWriter's underlying output stream to encode the streamed data.

Parameters:

document - the Document comment.

Throws:

java.io.UnsupportedEncodingException - if the declared encoding does not match the output stream encoding.

SemanticError - if the Document is not well-formed.

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

writeContent

protected void writeContent(Content content,
                            int indent)
                     throws SemanticError,
                            java.io.IOException

Writes one kind of Content. If the content is a Text comment, writes this without formatting. Otherwise, if pretty-printing, writes a newline and indentation to the current level, before writing out the content. Structured content is recorded on a stack during output, for the sake of reporting the context of any errors.

Parameters:

content - one kind of XML content.

indent - the indentation level.

Throws:

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

SemanticError

writeElement

protected void writeElement(Element element,
                            int indent)
                     throws java.io.IOException

Writes an Element. Writes the opening tag, with the identifier and any optional attributes. If the Element has no contents, writes a self-closing tag. Otherwise, recursively writes the contents of the Element at the next level of indentation and finally writes a closing tag with the same Element identifier.

Parameters:

element - the Element.

indent - the indentation level.

Throws:

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

writeDeclaration

protected void writeDeclaration(Declaration directive)
                         throws java.io.IOException

Writes out the XML Declaration. Writes the special opening tag "<?" and the target (always "xml"); and then writes out the content of the directive in attribute-value format. Finally writes the special closing tag "?>".

Parameters:

directive - an XML Declaration.

Throws:

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

writeInstruction

protected void writeInstruction(Instruction directive)
                         throws java.io.IOException

Writes a processing Instruction. Writes the special opening tag "<?" and the target (whether "xml-stylesheet" or some other target); and then writes out the content of the directive in attribute-value format. Finally writes the special closing tag "?>".

Parameters:

directive - a Declaration or an Instruction.

Throws:

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

writeDoctype

protected void writeDoctype(Doctype doctype)
                     throws java.io.IOException

Writes out a Doctype declaration. Writes the special opening tag "<!" and the symbol "DOCTYPE"; and then if this Doctype has an external grammar, writes out one of "SYSTEM" followed by the URI of the DTD file, or "PUBLIC" followed by the FPI and the URI of the DTD file. If this Doctype has an internal grammar, writes the grammar enclosed in brackets "[]". Finally, writes the closing tag ">".

Parameters:

doctype - the Doctype.

Throws:

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

writeComment

protected void writeComment(Comment comment)
                     throws java.io.IOException

Writes a Comment. Writes the special opening tag "".

Parameters:

comment - the Comment.

Throws:

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

writeData

protected void writeData(Data data)
                  throws java.io.IOException

Writes an escaped character Data node. Writes the special opening tag "<[CDATA[", followed by the escaped character data, followed by special closing tag "]]>". The layout of the data follows whatever original format was parsed.

Parameters:

data - the Data.

Throws:

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

writeAttribute

protected void writeAttribute(Attribute attribute)
                       throws java.io.IOException

Writes an Attribute. Writes a single space, followed by the attribute's identifier, followed by the equals sign "=", followed by the attribute's value in double-quotation marks. Encodes the attribute value-string, so that single or double quotes are escaped as character entitites.

Parameters:

attribute - the Attribute.

Throws:

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

writeText

protected void writeText(Text text)
                  throws java.io.IOException

Writes a Text node. Encodes the string contents, so that illegal and special characters are replaced by character entities, and boilerplate text is replaced by string entities defined in the Lexicon. The encoded text is otherwise written in its original format.

Parameters:

text - the Text.

Throws:

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