uk.ac.sheffield.jast.build

Class XMLBuilder

java.lang.Object

uk.ac.sheffield.jast.Logging

uk.ac.sheffield.jast.build.BasicBuilder

uk.ac.sheffield.jast.build.XMLBuilder

All Implemented Interfaces:

Builder

public class XMLBuilder
extends BasicBuilder

XMLBuilder is a builder that constructs the classic XML syntax tree. XMLBuilder is one of the Builder components for use with the XMLParser. XMLBuilder constructs a classic XML syntax tree (XML) out of Java nodes that directly model the XML types and attributes. XMLBuilder creates a tree rooted in the node Document, consisting of types such as Declaration, Doctype, Element, Attribute and Text. XMLBuilder uses the standard construction API for these nodes, which are all found in the sub-package uk.ac.sheffield.jast.xml.

All the XML model content and metadata are stored as part of the model, which by default is compact (discarding formatting whitespace surrounding XML elements). XMLBuilder may be requested to preserve full native format (keeping all original layout text as extra Text nodes). The model is accessed as an instance of Document.

By default, XMLBuilder will return a well-formed XML Document, or report that the XML syntax was faulty. XMLBuilder may be requested to validate the Document, to ensure that it conforms to some grammar defined by a Doctype, or an XML schema, so long as the Document refers to these. It may also be instructed to expand new entity references as part of a Doctype.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
private Content	current The current Content being constructed by this builder.
private Doctype	doctype The Doctype declaration for the Document, if it exists.
private Document	document The top-level Document constructed by this builder.
private boolean	rawLayout A flag describing whether to preserve the native format of the XML.
private Element	rootElement The root Element for the Document.

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

lexicon, parser, validation

Constructor Summary

Constructors

Constructor and Description
XMLBuilder() Constructs an XMLBuilder.

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	addComment(java.lang.String text) Adds an XML comment to the current node.
void	addEscapedData(java.lang.String data) Adds escaped data to the current node.
void	addLayoutText(java.lang.String text) Adds layout text to the current node.
void	addPrintingText(java.lang.String text) Adds printing text to the current node.
void	endDeclaration() Finishes processing the XML declaration.
void	endDoctype() Finishes processing an XML doctype declaration.
void	endDocument() Finishes processing the XML document.
void	endElement() Finishes processing an XML element.
void	endInstruction() Finishes processing an XML processing instruction.
Document	getDocument() Returns the document that was built by this XMLBuilder.
void	preserveLayout(boolean value) Instructs this XMLBuilder whether to preserve, or ignore layout text.
void	startDeclaration(java.lang.String target) Starts to process the XML declaration.
void	startDoctype(java.lang.String root) Starts to process an XML doctype declaration.
void	startDocument() Starts to construct a Document.
void	startElement(java.lang.String identifier) Starts to process an XML element.
void	startInstruction(java.lang.String target) Starts to process an XML processing instruction.
protected void	validate(Document document) Validates the Document using its own XMLSchema.

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

checkEncoding, endOfStream, getContext, getLexicon, getLineNumber, getParser, setLexicon, setParser, setValidation

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 constructed by this builder. This variable is the top of the stack of elements being processed. It is assigned when pushing a new Content, and reset to the parent of the Content when popping.

document

private Document document

The top-level Document constructed by this builder.

doctype

private Doctype doctype

The Doctype declaration for the Document, if it exists.

rootElement

private Element rootElement

The root Element for the Document.

rawLayout

private boolean rawLayout

A flag describing whether to preserve the native format of the XML. By default, this is false (i.e. layout space will be discarded).

Constructor Detail

XMLBuilder

public XMLBuilder()

Constructs an XMLBuilder.

Method Detail

preserveLayout

public void preserveLayout(boolean value)

Instructs this XMLBuilder whether to preserve, or ignore layout text. If set to false (the default), all formatting white space is discarded. If set to true, extra Text nodes are constructed for all layout.

Parameters:

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

getDocument

public Document getDocument()

Returns the document that was built by this XMLBuilder. XMLBuilder returns a Document object, whose children include the XML Declaration, Instruction and Doctype nodes, as well as the root Element node, which is the root of the DOM-tree.

Specified by:

getDocument in interface Builder

Overrides:

getDocument in class BasicBuilder

Returns:

a Document node, containing the parsed document.

startDocument

public void startDocument()

Starts to construct a Document. XMLBuilder pushes a new Document node onto the content-stack.

Specified by:

startDocument in interface Builder

Overrides:

startDocument in class BasicBuilder

endDocument

public void endDocument()
                 throws java.io.IOException,
                        SyntaxError,
                        SemanticError

Finishes processing the XML document. If the validation level is set to DOCTYPE or SCHEMA, this XMLBuilder will respectively validate the Document against a previously read Doctype, or against an XML Schema, which it will attempt to read after reading the Document. Finally, it will pop the Document node from the stack.

Specified by:

endDocument in interface Builder

Overrides:

endDocument in class BasicBuilder

Throws:

java.io.IOException - when validating, if an XMLSchema could not be read.

SyntaxError - when validating, if a faulty XMLSchema is read.

SemanticError - if the XML document is found to be invalid.

startDeclaration

public void startDeclaration(java.lang.String target)

Starts to process the XML declaration. The target is always the symbol "xml" or "XML". XMLBuilder pushes a new Declaration node onto the content-stack.

Specified by:

startDeclaration in interface Builder

Overrides:

startDeclaration in class BasicBuilder

Parameters:

target - the symbol "xml" or "XML".

endDeclaration

public void endDeclaration()
                    throws java.io.UnsupportedEncodingException

Finishes processing the XML declaration. XMLBuilder 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. XMLBuilder then pops the Declaration node from the content-stack.

Specified by:

endDeclaration in interface Builder

Overrides:

endDeclaration in class BasicBuilder

Throws:

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

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". XMLBuilder pushes a new Instruction node onto the content-stack.

Specified by:

startInstruction in interface Builder

Overrides:

startInstruction in class BasicBuilder

Parameters:

target - the name of the processing instruction.

endInstruction

public void endInstruction()

Finishes processing an XML processing instruction. XMLBuilder just pops the Instruction node from the content-stack.

Specified by:

endInstruction in interface Builder

Overrides:

endInstruction in class BasicBuilder

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. XMLBuilder checks that the Doctype is unique and is being processed before the main Document. It then pushes a new Doctype node onto the content-stack.

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, an external DTD file may be read for possible extra entity definitions to be included in the Lexicon. Finally, this XMLBuilder will pop the Doctype node from the content-stack.

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)

Starts to process an XML element. The identifier is the name of the element, which may optionally include a namespace prefix. XMLBuilder pushes a new Element node onto the content-stack. It also checks that no more than one root Element is created for the Document.

Specified by:

startElement in interface Builder

Overrides:

startElement in class BasicBuilder

Parameters:

identifier - the name of the element.

endElement

public void endElement()

Finishes processing an XML element. XMLBuilder simply pops the Element node from the content-stack.

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. The identifier is the name of the attribute, which may optionally include a namespace prefix. The value is a String representation of the attribute's value, in which all entities have been expanded.

Specified by:

addAttribute in interface Builder

Overrides:

addAttribute in class BasicBuilder

Parameters:

identifier - the name of the attribute.

value - the value of the attribute.

addComment

public void addComment(java.lang.String text)

Adds an XML comment to the current node. XMLBuilder attaches a new Comment node to the current top node in the content-stack.

Specified by:

addComment in interface Builder

Overrides:

addComment in class BasicBuilder

Parameters:

text - the comment text.

addPrintingText

public void addPrintingText(java.lang.String text)

Adds printing text to the current node. XMLBuilder attaches a new Text node, containing the printing text, to the current top node in the content-stack.

Specified by:

addPrintingText in interface Builder

Overrides:

addPrintingText in class BasicBuilder

Parameters:

text - the printing character text.

addLayoutText

public void addLayoutText(java.lang.String text)

Adds layout text to the current node. If native formatting is to be preserved, this XMLBuilder attaches a new Text node, containing the layout text, to the current top node in the content-stack; otherwise it discards the text as unwanted formatting whitespace.

Specified by:

addLayoutText in interface Builder

Overrides:

addLayoutText in class BasicBuilder

Parameters:

text - the formatting whitespace.

addEscapedData

public void addEscapedData(java.lang.String data)

Adds escaped data to the current node. XMLBuilder attaches a new Data node, containing the escaped character data, to the current top node in the content-stack. If the current node is the Doctype, treats the escaped data as the internal grammar subset.

Specified by:

addEscapedData in interface Builder

Overrides:

addEscapedData in class BasicBuilder

Parameters:

data - the escaped character data.

validate

protected void validate(Document document)
                 throws java.io.UnsupportedEncodingException,
                        java.io.IOException,
                        SyntaxError,
                        SemanticError

Validates the Document using its own XMLSchema. If the Document's root Element has a "noNamespaceSchemaLocation" attribute, uses the value of this as the path to the XMLSchema; otherwise, if it has a "schemaLocation" attribute, expects this to be a namespace-qualified schema location and uses the second part of the value as the path. If the path is a URL, opens an XSDReader expecting Latin-1 encoding; otherwise, opens an XSDReader expecting the same encoding as the main XML document. Reads the XMLSchema, closes the reader and then compiles the grammar rules of the XMLSchema.

Parameters:

document - the Document.

Throws:

java.io.UnsupportedEncodingException - if an encoding fault occurs.

java.io.IOException - if any other I/O error occurs.

SyntaxError - if the XML syntax is faulty.

SemanticError - if schema constraints are broken.