uk.ac.sheffield.jast.build

Class ASTBuilder

java.lang.Object

uk.ac.sheffield.jast.Logging

uk.ac.sheffield.jast.build.BasicBuilder

uk.ac.sheffield.jast.build.ASTBuilder

All Implemented Interfaces:

Builder

public class ASTBuilder
extends BasicBuilder

ASTBuilder is a builder that constructs a custom Java syntax tree. ASTBuilder is one of the Builder components for use with the XMLParser. ASTBuilder constructs a custom abstract syntax tree (AST) consisting of user-defined Java AST classes. ASTBuilder maps XML elements to specific Java AST classes, where elements from different XML namespaces may be mapped to classes from different Java packages. Every AST class must provide a builder-API which consists of set-methods (for setting attributes and content) and add-methods (for attaching element children). These are discovered by reflection; and if they are missing, ASTBuilder raises SemanticError exceptions.

The AST model contains only the information mapped from XML elements and attributes. Any XML metadata that is not part of the model is stored in a Metadata object, which records the mapping of XML names to Java names, and may be used later to reconstruct the XML names from Java. The model is accessed as an instance of the top-level AST class, which can be any kind of Object observing the AST conventions.

While an ASTBuilder cannot validate an arbitrary Java AST (this may only be done for XML-trees), it may be instructed to expand any extra entity references defined in a Doctype, by setting the validation level to EXPAND. The expanded text will be added to the AST model.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
private Metadata	metadata A collection of mappings between XML and Java.
private java.util.Deque<java.lang.Object>	objectStack The stack of created AST objects.
private java.lang.Object	syntaxTree The root of the Java abstract syntax tree.
private Unmarshaller	unmarshaller The Unmarshaller that is used to create and connect AST object instances.

Fields inherited from class uk.ac.sheffield.jast.build.BasicBuilder

lexicon, parser, validation

Constructor Summary

Constructors

Constructor and Description
ASTBuilder() Creates an ASTBuilder.

Method Summary

Modifier and Type	Method and Description
void	addAttribute(java.lang.String identifier, java.lang.String value) Adds an attribute with the given name and value to the current node.
void	addEscapedData(java.lang.String data) Adds escaped character data to the current node.
void	addPrintingText(java.lang.String text) Adds printing character text to the current node.
void	endDeclaration() Finishes processing the XML declaration.
void	endDoctype() Finishes processing an XML doctype declaration.
void	endElement() Finishes constructing an AST node.
java.lang.Object	getDocument() Returns the document that was built by this ASTBuilder.
Metadata	getMetadata() Exports the Metadata created by this build.
void	startDoctype(java.lang.String root) Starts to process an XML doctype declaration.
void	startElement(java.lang.String identifier) Starts to construct the AST node for an element with the given name.
void	startInstruction(java.lang.String target) Starts to process an XML processing instruction.
void	useDomain(java.lang.String domainName) Instructs this ASTBuilder to recognise the named DNS domain.
void	usePackage(java.lang.String packageName) Instructs this ASTBuilder to use the named Java package when mapping the default XML namespace.
void	usePackage(java.lang.String packageName, java.lang.String namespace) Instructs this ASTBuilder to use the named Java package when mapping the given XML namespace.

Methods inherited from class uk.ac.sheffield.jast.build.BasicBuilder

addComment, addLayoutText, checkEncoding, endDocument, endInstruction, endOfStream, getContext, getLexicon, getLineNumber, getParser, setLexicon, setParser, setValidation, startDeclaration, startDocument

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.

unmarshaller

private Unmarshaller unmarshaller

The Unmarshaller that is used to create and connect AST object instances. This uses reflection to discover AST classes and their methods.

objectStack

private java.util.Deque<java.lang.Object> objectStack

The stack of created AST objects. Used only to organise the order of plugging nodes into other nodes.

syntaxTree

private java.lang.Object syntaxTree

The root of the Java abstract syntax tree. This is constantly reset by popping the stack. The last value stored is the root AST object.

Constructor Detail

ASTBuilder

public ASTBuilder()

Creates an ASTBuilder. Initialises the Metadata and the Unmarshaller used to help map the XML to Java objects. Initialises the object stack used to order the created AST objects before they are connected in the syntax tree.

Method Detail

getDocument

public java.lang.Object getDocument()

Returns the document that was built by this ASTBuilder. ASTBuilder returns an object graph, rooted in an instance of the user-defined AST class representing the root of the model. Other XML metadata is not stored as part of the AST model, but in a separate Metadata object.

Specified by:

getDocument in interface Builder

Overrides:

getDocument in class BasicBuilder

Returns:

an object, the root of the AST-tree.

getMetadata

public Metadata getMetadata()

Exports the Metadata created by this build. This holds 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 model.

Returns:

the Metadata.

useDomain

public void useDomain(java.lang.String domainName)

Instructs this ASTBuilder to recognise the named DNS domain. The domain name is supplied in the usual format, e.g. "sheffield.ac.uk". Allows this ASTBuilder 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 ASTBuilder to use the named Java package when mapping the default XML namespace. All XML elements from the default "xmlns" namespace will be mapped to classes from the given Java package. 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 ASTBuilder to use the named Java package when mapping the given XML namespace. All XML elements from the given namespace will be mapped to classes from the given Java package. The Java package name is supplied in the usual Java format "org.domain.project". The XML namespace 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 name.

endDeclaration

public void endDeclaration()
                    throws java.io.UnsupportedEncodingException

Finishes processing the XML declaration. ASTBuilder automatically checks that the declared encoding matches the actual encoding used by the XMLParser. This may also update the character-sets used by the Lexicon.

Specified by:

endDeclaration in interface Builder

Overrides:

endDeclaration in class BasicBuilder

Throws:

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

startInstruction

public void startInstruction(java.lang.String target)

Starts to process an XML processing instruction. The target names an XML processing program, such as "xml-stylesheet". If the target is "xml-stylesheet", stores this under the "stylesheet" metadata property. If the target is "java-binding", stores this under the "binding" metadata property. Otherwise ignores the processing instruction. Only stylesheet and binding instructions are recovered later; other processing instructions are ignored when reconstituting the XML file.

Specified by:

startInstruction in interface Builder

Overrides:

startInstruction in class BasicBuilder

Parameters:

target - the name of the processing instruction.

startDoctype

public void startDoctype(java.lang.String root)

Starts to process an XML doctype declaration. The root is the name of the root element in the document. ASTBuilder checks that the Doctype is unique and is being processed before the main document. Stores the root name under the metadata "root" property.

Specified by:

startDoctype in interface Builder

Overrides:

startDoctype in class BasicBuilder

Parameters:

root - the name of the root element.

endDoctype

public void endDoctype()
                throws java.io.IOException,
                       SyntaxError

Finishes processing an XML doctype declaration. If the validation level is set to EXPAND, DOCTYPE or SCHEMA, the related DTD file will be read for possible extra entity definitions to be included in the Lexicon.

Specified by:

endDoctype in interface Builder

Overrides:

endDoctype in class BasicBuilder

Throws:

java.io.IOException - if reading an external DTD file fails.

SyntaxError - if the DTD syntax is faulty.

startElement

public void startElement(java.lang.String identifier)
                  throws SemanticError

Starts to construct the AST node for an element with the given name. The name may be a long identifier (with prefix) or short name (without prefix). Maps the XML identifier to a legal Java class identifier, then seeks to create a default instance of this AST class. Indexes this object in a map of encountered objects and pushes the object onto the object stack. Does not (yet) add this object as a dependent of its parent on the object stack, since it might be a proxy, acting as a reference to another object. Co-references are resolved later, when processing the "id" and "ref" attributes.

Specified by:

startElement in interface Builder

Overrides:

startElement in class BasicBuilder

Parameters:

identifier - the long identifier, or short name.

Throws:

SemanticError - if no suitable AST class exists, or if its default constructor fails.

endElement

public void endElement()

Finishes constructing an AST node. Pops the AST object off the object stack and attaches the popped object as a dependent of its parent AST object. This attachment is delayed until now, to allow for co-references to be resolved earlier.

Specified by:

endElement in interface Builder

Overrides:

endElement in class BasicBuilder

addAttribute

public void addAttribute(java.lang.String identifier,
                         java.lang.String value)

Adds an attribute with the given name and value to the current node. If the object stack is empty (because no AST object has yet been pushed), or if the identifier is XML namespace-related or XML schema-related, sets a property of the Metadata. If the identifier is one of the reserved names "id" or "ref", performs object identity checking and co-reference resolution, which modifies the object stack. Otherwise, maps the XML identifier to a legal Java field identifier, then seeks to set this field in the AST object. The AST class must provide a suitable public set-method.

Specified by:

addAttribute in interface Builder

Overrides:

addAttribute in class BasicBuilder

Parameters:

identifier - the attribute's name.

value - the attribute's value.

Throws:

SemanticError - if the AST class fails to provide a set-method for this attribute.

addPrintingText

public void addPrintingText(java.lang.String text)

Adds printing character text to the current node. If a current AST node exists, seeks to add the text as the value of this AST class's "content" field; otherwise does nothing. The AST class must provide a method "setContent" to store the text.

Specified by:

addPrintingText in interface Builder

Overrides:

addPrintingText in class BasicBuilder

Parameters:

text - the printing character text.

Throws:

SemanticError - if no content-setting method exists.

addEscapedData

public void addEscapedData(java.lang.String data)

Adds escaped character data to the current node. If a current AST node exists, seeks to add the text as the value of this AST class's "content" field; otherwise, does nothing. The AST class must provide a method "setContent" to store the data.

Specified by:

addEscapedData in interface Builder

Overrides:

addEscapedData in class BasicBuilder

Parameters:

data - the escaped character data.