uk.ac.sheffield.jast

Class ASTWriter

java.lang.Object

uk.ac.sheffield.jast.Logging

uk.ac.sheffield.jast.BasicWriter

uk.ac.sheffield.jast.ASTWriter

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class ASTWriter
extends BasicWriter

ASTWriter is a serializer that writes out a custom Java AST syntax tree. ASTWriter performs a pre-order traversal of the custom abstract syntax tree (AST), constructed from user-supplied Java classes, and writes out an XML text file representing the AST model. ASTWriter maps Java AST classes to specific XML elements, where classes from different Java packages may be mapped to elements from different XML namespaces. Every AST class must provide an access-API which consists of public get-methods (to access every field). Fields may contain single objects or collections, and are serialized either as attributes (if originally set with a set-method), or as dependent nodes (if originally added with an add-method). These are discovered by reflection; and if they are missing, ASTWriter raises SemanticError exceptions. Fields marked transient or static are not serialized.

ASTWriter uses a low-level XMLStreamer to stream character data to the output stream. XMLWriter always pretty-prints the XML file afresh, using the XMLStreamer's tab setting for indentation. Any XML metadata that is not part of the AST model may be retrieved from the Metadata object that originally recorded the mapping of XML names to Java names, and may be used again to reconstruct the XML names from Java. This Metadata object is typically exported by an ASTWriter and imported into this ASTWriter. If no Metadata is imported, this ASTWriter will use default settings, which assume that the AST classes all come from one package. ASTWriter 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 Marshaller	marshaller The Marshaller that is used to de-construct AST object instances.
private Metadata	metadata A collection of mappings between XML and Java.
private java.util.Deque<java.lang.String>	symbolStack The stack of processed XML symbols.

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

lexicon, streamer

Constructor Summary

Constructors

Constructor and Description
ASTWriter(java.io.File file) Creates an ASTWriter writing to a file, using the default character encoding UTF-8.
ASTWriter(java.io.File file, java.lang.String encoding) Creates an ASTWriter writing to a file, using the specified character encoding.
ASTWriter(java.io.OutputStream stream, java.lang.String encoding) Creates an ASTWriter writing to a basic output stream, using the specified character encoding.
ASTWriter(java.io.Writer writer) Creates an ASTWriter writing to a character writer, using the default ISO-8859-1 (Latin 1) character encoding specified for the MIME-type text/xml.
ASTWriter(java.io.Writer writer, java.lang.String encoding) Creates an ASTWriter 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 ASTWriter.
Metadata	getMetadata() Exports the Metadata used by this ASTWriter.
void	setMetadata(Metadata metadata) Imports the supplied Metadata into this ASTWriter.
void	useDomain(java.lang.String domainName) Instructs this ASTWriter to recognise the named DNS domain.
void	usePackage(java.lang.String packageName) Instructs this ASTWriter to use the named Java package when mapping the default XML namespace.
void	usePackage(java.lang.String packageName, java.lang.String namespace) Instructs this ASTWriter to use the named Java package when mapping a specific XML namespace.
protected void	writeAttribute(java.lang.String nameToken, java.lang.Object value) Optionally writes an attribute in key-value format, if a value exists.
protected void	writeBindings() Optionally writes a Java binding processing instructions after the XML declaration.
protected void	writeBoundNamespaces() Writes out any declarations for XML namespaces that were bound to Java packages.
protected void	writeDeclaration() Writes the required XML declaration at the head of the output data.
protected void	writeDoctype() Optionally writes a doctype declaration before the root element.
void	writeDocument(java.lang.Object syntaxTree) Writes a Java abstract syntax tree to an XML output file or stream.
protected void	writeElement(java.lang.Object object, int indent) Writes an AST object as an XML element.
protected void	writeOriginal(java.lang.Object object, int indent, java.lang.String nameToken) Writes an original AST object.
protected void	writePrintingText(java.lang.Object content, int indent) Writes printing textual content.
protected void	writeReference(java.lang.Object object) Writes an AST object reference.
protected void	writeSchemaReference() Writes out any declarations for an XML schema reference, if one was supplied.
protected void	writeStylesheet() Optionally writes a stylesheet processing instruction after the XML declaration.

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

metadata

private Metadata metadata

A collection of mappings between XML and Java. Stores the mappings between XML name tokens and Java identifiers; and the mappings from XML namespaces to Java package names; and any other XML properties that are part of the metadata, rather than the model.

marshaller

private Marshaller marshaller

The Marshaller that is used to de-construct AST object instances. This uses reflection to discover AST classes and their methods.

symbolStack

private java.util.Deque<java.lang.String> symbolStack

The stack of processed XML symbols. Used only to record the nesting of processing.

Constructor Detail

ASTWriter

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

Creates an ASTWriter 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.

ASTWriter

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

Creates an ASTWriter 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.

ASTWriter

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

Creates an ASTWriter 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.

ASTWriter

public ASTWriter(java.io.Writer writer)

Creates an ASTWriter 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.

ASTWriter

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

Creates an ASTWriter 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 ASTWriter. 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.

getMetadata

public Metadata getMetadata()

Exports the Metadata used by this ASTWriter. Initially, the Metadata contains only the default XML version 1.0 and encoding UTF-8. If the Metadata was previously exported from an ASTReader and imported into this ASTWriter, it will hold the mappings between XML name tokens and Java identifiers; and the mappings between XML namespaces and Java package names; and any other XML properties that are part of the metadata, rather than part of the AST model.

Returns:

the Metadata.

setMetadata

public void setMetadata(Metadata metadata)

Imports the supplied Metadata into this ASTWriter. The Metadata was previously exported from an ASTReader. It is imported here, in order to restore the same mappings between XML name tokens and Java identifiers; and the mappings between XML namespaces and Java package names; and to restore any other XML properties that are part of the metadata, rather than part of the AST model. Use this method to import Metadata into this ASTWriter that was previously exported from an ASTRreader, in order to use the same mappings.

Parameters:

metadata - the Metadata.

useDomain

public void useDomain(java.lang.String domainName)

Instructs this ASTWriter to recognise the named DNS domain. The domain name is supplied in the usual format, e.g. "sheffield.ac.uk". Allows this ASTWriter to recognise when the reversed domain name is used as a prefix in a Java package identifier, which underlies the automatic creation of unique XML namespace URIs for Java packages. This domain is stored in the Metadata.

Parameters:

domainName - a DNS domain name, such as "sheffield.ac.uk"

usePackage

public void usePackage(java.lang.String packageName)

Instructs this ASTWriter to use the named Java package when mapping the default XML namespace. All classes from the given Java package will be mapped to XML elements from the default "xmlns" namespace. The Java package name is supplied in the usual Java format "org.domain.project". This mapping is recorded in the Metadata.

Parameters:

packageName - the Java package name.

usePackage

public void usePackage(java.lang.String packageName,
                       java.lang.String namespace)

Instructs this ASTWriter to use the named Java package when mapping a specific XML namespace. All classes from the given Java package will be mapped to XML elements using the same prefix as the given XML namespace specifier. The Java package name is supplied in the usual Java format "org.domain.project". The XML namespace specifier is supplied either in the default format "xmlns" or the short labelled format "xmlns:abc", where "abc" is the element prefix. This mapping is recorded in the Metadata.

Parameters:

packageName - the Java package name.

namespace - the XML namespace attribute name.

writeDocument

public void writeDocument(java.lang.Object syntaxTree)
                   throws SemanticError,
                          java.io.IOException

Writes a Java abstract syntax tree to an XML output file or stream. The syntax tree is an arbitrary graph of Java objects that conform to the AST class conventions. Checks first whether the declared character encoding matches the encoding used by this ASTWriter's underlying output stream to encode the character data. Writes a well-formed XML document, consisting of an XML declaration, optional doctype declaration and stylesheet processing instruction, followed by an XML tree rooted in a single XML element.

Parameters:

syntaxTree - the root of the graph of AST objects.

Throws:

SemanticError - if AST unpacking conventions are broken.

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

java.io.UnsupportedEncodingException - if the declared character encoding does not match the actual encoding used by the output stream.

writeDeclaration

protected void writeDeclaration()
                         throws java.io.IOException

Writes the required XML declaration at the head of the output data. Writes the special opening tag "<?" followed by the target "xml" and the required version and encoding attributes. Optionally writes the standalone attribute (if defined).

Throws:

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

writeStylesheet

protected void writeStylesheet()
                        throws java.io.IOException

Optionally writes a stylesheet processing instruction after the XML declaration. If a property "stylesheet" was stored in the Metadata, writes a processing instruction with the target "xml-stylesheet", also expecting properties "href", "title" and "type" to be defined in the Metadata (only "href" is compulsory).

Throws:

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

writeBindings

protected void writeBindings()
                      throws java.io.IOException

Optionally writes a Java binding processing instructions after the XML declaration. For each XML namespace stored in the

Throws:

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

writeDoctype

protected void writeDoctype()
                     throws java.io.IOException

Optionally writes a doctype declaration before the root element. If a property "element" was stored in the Metadata, writes a doctype declaration with the value of "root" as its target. Also expects the properties "public", "system" and "grammar" optionally to be defined in the Metadata. If "public" or "system" are defined, the doctype has an external grammar. If "grammar" is defined, it has an internal grammar.

Throws:

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

writeAttribute

protected void writeAttribute(java.lang.String nameToken,
                              java.lang.Object value)
                       throws java.io.IOException

Optionally writes an attribute in key-value format, if a value exists. If the value is non-null, writes the attribute's name, followed by the equals-sign "=", followed by the value, converted to a String. If the value is already a String, seeks to encode any characters or text that may need replacing by entity references. Writes the encoded text in double-quotes (always), escaping any contained quotes.

Parameters:

nameToken - the attribute's XML name.

value - the attribute's value.

Throws:

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

writeElement

protected void writeElement(java.lang.Object object,
                            int indent)
                     throws java.io.IOException

Writes an AST object as an XML element. Writes a newline and indents to the current level. Converts the object's class name back into an XML name token. Writes the opening tag, but then checks whether the object has been seen before. If so, writes a reference-element; and if not, writes out the original element.

Parameters:

object - the AST object.

indent - the indentation level.

Throws:

java.io.IOException - if any output error occurs.

writeOriginal

protected void writeOriginal(java.lang.Object object,
                             int indent,
                             java.lang.String nameToken)
                      throws java.io.IOException

Writes an original AST object. The XML element for this AST object has not been encountered before. If this is the root element at the zero-indentation level, checks whether any namespace declarations for namespaces bound to Java packages need to be defined; and also checks whether an XML schema namespace and reference need to be defined. Maps the object's serialised properties to XML attributes. Maps the object's serialised simple content to text. Maps the object's serialised dependents to children elements. If the object has any dependent contents, writes the contents followed by a closing-tag; otherwise, writes a self-closing tag.

Parameters:

object - the AST object.

indent - the indentation level.

nameToken - the XML element identifier.

Throws:

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

writeReference

protected void writeReference(java.lang.Object object)
                       throws java.io.IOException

Writes an AST object reference. The XML element for this object has already been written once, so writes out an element referring back to the original object. The proxy element has a special attribute "ref" whose integer value is the index of the original object. If the object has a property "name", also writes this out (for the sake of human readers of the resulting XML).

Parameters:

object - the AST object.

Throws:

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

writeBoundNamespaces

protected void writeBoundNamespaces()
                             throws java.io.IOException

Writes out any declarations for XML namespaces that were bound to Java packages. Writes out the relevant default "xmlns" namespace, or labelled "xmlns:abc" namespaces, as attributes of the document's root element. Namespace attributes always appear first, followed by other attributes. A newline is generated after each namespace declaration is written.

Throws:

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

writeSchemaReference

protected void writeSchemaReference()
                             throws java.io.IOException

Writes out any declarations for an XML schema reference, if one was supplied. If the Metadata contains a property "xmlns:xsi", then writes two attributes, one declaring the "xmlns:xsi" namespace, and the other declaring the schema location. This second attribute is named either "xsi:schemaLocation" or "xsi:noNamespaceSchemaLocation", depending on which one was previously supplied. Schema reference attributes always appear second, after other namespace declarations, but before other user-defined attributes. A newline is generated after each schema reference declaration is written.

Throws:

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

writePrintingText

protected void writePrintingText(java.lang.Object content,
                                 int indent)
                          throws java.io.IOException

Writes printing textual content. This is either the sole content of an element (if indent = 0), or part of the contents including other dependents (if indent > 0). Assumes that indentation is required in the latter case, but not in the former. Converts the content to a String; if already a String, seeks to encode the character data.

Parameters:

content - the content of an AST object.

indent - the indentation level.

Throws:

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