uk.ac.sheffield.jast.xml

Class Document

java.lang.Object

uk.ac.sheffield.jast.xml.Content

uk.ac.sheffield.jast.xml.Document

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Iterable<Content>

Direct Known Subclasses:

XMLSchema

public class Document
extends Content

Document is the node standing for a complete XML Document. Document is the in-memory representation of an XML text file. At the top level, it contains a Declaration node, representing the mandatory XML header, and a single Element, representing the root of the XML tree. It may also contain a Doctype declaration and further Instruction, Text and Comment nodes. (Text is white space layout text, if this is being preserved). Since Document is the ultimate root of the XML tree, it is the only node that may not be added as a kind of Content under other nodes in the XML tree.

XMLReader returns an instance of Document when it successfully reads an XML text file. The Document provides in-memory Java access to all parts of the XML document, through the APIs of the different classes of node in the XML tree, such as Element, Text, Data and Comment. A Document may also be constructed in memory directly by Java programs and then written to an XML text file using XMLWriter.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
private static int	CONTENT_LIST_LENGTH The default length of this Document's content list.
private java.util.List<Content>	contentList The list of this Document's contents, initialised by default to hold up to eight content-nodes, including possible layout text.
private static Filter	documentContent A Filter accepting the legal kinds of node that may be supplied as the contents of a Document.

Fields inherited from class uk.ac.sheffield.jast.xml.Content

ATTRIBUTE, COMMENT, DATA, DECLARATION, DOCTYPE, DOCUMENT, ELEMENT, INSTRUCTION, TEXT, UNDEFINED

Constructor Summary

Constructors

Constructor and Description
Document() Creates a default empty Document with the standard XML Declaration.
Document(Declaration declaration) Creates a custom empty Document with the supplied XML Declaration.
Document(Declaration declaration, Element root) Creates a custom Document with the supplied root Element.
Document(Element root) Creates a default Document with the supplied root Element.

Method Summary

Modifier and Type	Method and Description
Document	addContent(Content node) Adds a Content node to this Document.
Document	clone() Clones this Document node.
private Document	deepCopy(Document other) Secret method to deep copy a partly-cloned Document.
java.util.List<Content>	getContents() Returns all of this Document's contents, of any type.
Declaration	getDeclaration() Returns the XML declaration for this Document.
Doctype	getDoctype() Returns any Doctype associated with this Document.
java.lang.String	getEncoding() Returns the character set encoding of this Document, by default UTF-8.
Element	getRootElement() Returns the single root Element, the principal content of this Document.
int	getType() Returns the type of this Content.
java.lang.String	getVersion() Returns the XML version of this Document, by default 1.0.
boolean	hasContents() Reports whether this Document has any contents.
boolean	isStandalone() Reports whether this XML Document stands alone.
boolean	isWellFormed() Reports if this Document is well-formed.
Content	removeContent(Content node) Removes a Content node from this Document's immediate contents.
private void	replaceUnique(Content node) Secret method to replace or add a uniquely-occurring Content node in this Document.
Document	setDeclaration(Declaration declaration) Sets the XML declaration associated with this Document.
Document	setDoctype(Doctype doctype) Sets the optional XML Doctype associated with this Document.
Document	setEncoding(java.lang.String encoding) Sets the character encoding associated with this Document.
protected void	setParent(Content node) Disallows adding this Document to any other Content node.
Document	setRootElement(Element root) Sets the root Element of this Document.
Document	setVersion(java.lang.String version) Sets the XML version associated with this Document.

Methods inherited from class uk.ac.sheffield.jast.xml.Content

addAttribute, addContent, descendants, descendants, detach, getAttributes, getComment, getContent, getContent, getContent, getContents, getDocument, getIdentifier, getParent, getText, iterator, iterator, removeContent, removeContents, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

CONTENT_LIST_LENGTH

private static final int CONTENT_LIST_LENGTH

The default length of this Document's content list.

See Also:

Constant Field Values

documentContent

private static final Filter documentContent

A Filter accepting the legal kinds of node that may be supplied as the contents of a Document.

contentList

private java.util.List<Content> contentList

The list of this Document's contents, initialised by default to hold up to eight content-nodes, including possible layout text.

Constructor Detail

Document

public Document()

Creates a default empty Document with the standard XML Declaration. The standard XML Declaration uses XML version 1.0 and the UTF-8 character set. This constructor is used by parsers that build the Document incrementally.

Document

public Document(Declaration declaration)
         throws SemanticError

Creates a custom empty Document with the supplied XML Declaration. This constructor is used when a Document needs to accept data in a different character set from the default UTF-8 encoding.

Parameters:

declaration - the XML declaration.

Throws:

SemanticError - if the header is not a valid XML declaration.

Document

public Document(Element root)

Creates a default Document with the supplied root Element. This constructor is used when building a default Document in memory, with an existing root Element. It installs the standard XML declaration and the supplied Element as the root of the Document.

Parameters:

root - the root Element.

Document

public Document(Declaration declaration,
                Element root)
         throws SemanticError

Creates a custom Document with the supplied root Element. This constructor is used when building a custom Document in memory, with a custom XML declaration and an existing root Element. Installs the XML declaration and the Element as the root of the Document.

Parameters:

declaration - the XML Declaration.

root - the root Element.

Throws:

SemanticError - if the header is not a valid XML declaration.

Method Detail

replaceUnique

private void replaceUnique(Content node)

Secret method to replace or add a uniquely-occurring Content node in this Document. The Content node is either the Declaration, a Doctype or the root Element node, all of which are unique in this Document. When changed, they must be replaced using this method, to ensure their uniqueness.

Parameters:

node - the new uniquely-occurring Content node.

deepCopy

private Document deepCopy(Document other)

Secret method to deep copy a partly-cloned Document. This Document is a shallow clone of the other Document. This method clones a true copy of the other Document's content list and installs it in this clone.

Parameters:

other - the Document to be deep copied.

Returns:

this Document, after deep-copying the other.

setParent

protected void setParent(Content node)
                  throws SemanticError

Disallows adding this Document to any other Content node. Stops this Document from setting another node as its parent; hence this Document may not be added as the content of any other Content node.

Overrides:

setParent in class Content

Parameters:

node - the desired parent node, possibly null.

Throws:

SemanticError - deliberately.

clone

public Document clone()

Clones this Document node. Returns a deep copy of this Document, in which the content list has been recursively cloned.

Overrides:

clone in class Content

Returns:

a clone of this Document node.

getType

public int getType()

Returns the type of this Content. Returns the integer constant, DOCUMENT, denoting that this is a Document.

Overrides:

getType in class Content

Returns:

the integer constant DOCUMENT.

addContent

public Document addContent(Content node)
                    throws SemanticError

Adds a Content node to this Document. This method allows parsers to add different kinds of legal content (Directive, Instruction, Element, Doctype, Text, Comment) as these are encountered in an XML file. Only one copy of the XML Declaration, the optional Doctype and the root Element may be added, replacing any previous versions of these unique nodes. Multiple copies of other kinds of node, such as Comment or layout Text nodes, may be added, interleaved with other nodes.

Overrides:

addContent in class Content

Parameters:

node - a Content node.

Returns:

this Document.

Throws:

SemanticError - if a Declaration is an invalid XML declaration, or a root Element conflicts with the root specified by a Doctype declaration.

removeContent

public Content removeContent(Content node)

Removes a Content node from this Document's immediate contents. So long as the node is not the compulsory XML declaration, seeks to remove the node from this Document's content list. If the node is removed successfully, returns the node; otherwise returns null. Note that removing the root Element will mean that this Document is no longer well formed.

Overrides:

removeContent in class Content

Parameters:

node - another Content node.

Returns:

node, if it was removed, or null otherwise.

hasContents

public boolean hasContents()

Reports whether this Document has any contents. By default, returns true, since this Document always has at least the Directive containing the XML declaration.

Overrides:

hasContents in class Content

Returns:

true, if this Document has contents, otherwise false.

getContents

public java.util.List<Content> getContents()

Returns all of this Document's contents, of any type. The result is a list containing the Directive, an optional Doctype, optional Comments, a root Element (if added), optional Process nodes and optional layout Text nodes interleaving these, if formatting whitespace was preserved.

Overrides:

getContents in class Content

Returns:

a List of this Document's contents.

getDeclaration

public Declaration getDeclaration()

Returns the XML declaration for this Document. This is always created by default, but may be re-set by a client program, or when an XML file is parsed. This special Declaration always contains the XML "version" attribute and the character "encoding" attribute, and may contain the "standalone" attribute (if a Doctype node is also added).

Returns:

the XML Declaration.

getDoctype

public Doctype getDoctype()

Returns any Doctype associated with this Document. A Doctype node may optionally be attached to this Document, particularly if this Document is to be validated. The Doctype node may either refer to an external DTD file, or may contain further nested declarations defining the kinds of Element that will be allowed in this Document.

Returns:

a Doctype, or null if none exists.

getRootElement

public Element getRootElement()

Returns the single root Element, the principal content of this Document. The root Element is the start of the XML tree of data contained within this Document, which may be explored using the API of the Element class. A well-formed Document must contain exactly one root Element. This Document is created by default without a root element, which is either constructed by a program, or provided by parsing an XML file to create the root Element.

Returns:

the root Element, or null if none exists (yet).

getVersion

public java.lang.String getVersion()

Returns the XML version of this Document, by default 1.0. This method is provided for convenience and is equivalent to getDeclaration().getVersion().

Returns:

the XML version of this Document.

getEncoding

public java.lang.String getEncoding()

Returns the character set encoding of this Document, by default UTF-8. This method is provided for convenience and is equivalent to getDeclaration().getEncoding().

Returns:

the character set encoding of this Document.

isWellFormed

public boolean isWellFormed()

Reports if this Document is well-formed. This Document is well-formed if it contains a Directive and root Element. This method may be used by a parser to determine if the accept-condition has been reached.

Returns:

true, if this Document is well-formed, otherwise false.

isStandalone

public boolean isStandalone()

Reports whether this XML Document stands alone. This Document can stand alone if it does not depend on any external DTD (Document Type Definition) file. This method is a convenient shorthand for the expression getDeclaration().isStandalone().

Returns:

true, if this XML Document may stand alone.

setDeclaration

public Document setDeclaration(Declaration declaration)
                        throws SemanticError

Sets the XML declaration associated with this Document. The given Declaration is inserted at the head of this Document's contents, replacing any default XML declaration. If this Document has a Doctype, then the Declaration's "standalone" attribute will also be set to "yes" if the Doctype is self-contained, or "no" if it refers to an external DTD.

Parameters:

declaration - the new XML declaration.

Returns:

this Document.

Throws:

SemanticError - if an invalid XML declaration is supplied.

setDoctype

public Document setDoctype(Doctype doctype)

Sets the optional XML Doctype associated with this Document. If this Document is to be validated, a Doctype (or XMLSchema) may be supplied. At most one Doctype may be supplied, replacing any previous Doctype. Checks for name-consistency with the Document's root Element, if one exists. This is the only validity check that is performed by default. Adding a Doctype will set the "standalone" attribute of the XML declaration to "yes", if the Doctype is self-contained, or "no" if it refers to an external DTD file. Ignores any null Doctype argument.

Parameters:

doctype - the Doctype node.

Returns:

this Document.

Throws:

SemanticError - if a mismatch is detected between the expected and actual name of the current root Element.

setRootElement

public Document setRootElement(Element root)
                        throws SemanticError

Sets the root Element of this Document. This Document may be created temporarily without a root Element, but it is not well-formed until it has one. At most one root Element may be supplied, replacing any previous root Element. Checks for name-consistency with the Doctype, if one was supplied. This is the only validity check that is performed by default. A null root Element argument is ignored.

Parameters:

root - the root Element.

Returns:

this Document.

Throws:

SemanticError - if a mismatch is detected between the actual and expected name of the supplied root Element.

setVersion

public Document setVersion(java.lang.String version)

Sets the XML version associated with this Document. This method is provided for convenience and is equivalent to getDeclaration().setVersion(version)

Parameters:

version - the XML version, typically "1.0".

Returns:

this Document.

setEncoding

public Document setEncoding(java.lang.String encoding)

Sets the character encoding associated with this Document. This method is provided for convenience and is equivalent to getDeclaration().setEncoding(encoding).

Parameters:

encoding - the character encoding, for example "UTF-8".

Returns:

this Document.