uk.ac.sheffield.jast.xml

Class Declaration

java.lang.Object

uk.ac.sheffield.jast.xml.Content

uk.ac.sheffield.jast.xml.Markup

uk.ac.sheffield.jast.xml.Descriptor

uk.ac.sheffield.jast.xml.Declaration

All Implemented Interfaces:

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

public class Declaration
extends Descriptor

Declaration is the XML declaration appearing at the head of every XML file. Declaration is a kind of Descriptor that must appear uniquely in a Document. All XML documents should begin with the XML Declaration, which declares the XML version (by default, 1.0), the character encoding (by default, UTF-8) and optionally a boolean flag indicating whether the XML Document may stand alone (viz. it does not depend on any external DTD file). The Declaration is used by the XML processor to encode or decode XML data using the correct character sets. The tag delimiters for a Declaration are printed in a special way, using <?xml and ?>. No other Markup-node may use "xml" as its name.

The properties of a Declaration are stored as XML attributes; otherwise a Declaration has no other contents. The only legal attribute names are: "version", "encoding" and "standalone". Both Declaration and Instruction nodes have the notion of a target, which is the name of a program used to process the instruction. However, a Declaration always has the target "xml" denoting the XML processor.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
private static java.util.Set<java.lang.String>	legalNames Secret set of legal attribute names for a Declaration.

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

attributeList

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
Declaration() Creates a default XML declaration, setting the version attribute to 1.0 and the character encoding attribute to UTF-8.
Declaration(java.lang.String target) Creates an XML declaration with the given target.

Method Summary

Modifier and Type	Method and Description
Declaration	addAttribute(Attribute node) Adds a uniquely named Attribute to this Declaration.
Declaration	clone() Clones this Declaration node.
java.lang.String	getEncoding() Returns the character encoding declared by this Declaration.
java.lang.String	getTarget() Returns the target of this XML Declaration.
int	getType() Returns the type of this Declaration.
java.lang.String	getVersion() Returns the XML version declared by this Declaration.
boolean	isStandalone() Reports whether the XML Document owning this Declaration stands alone.
Declaration	setEncoding(java.lang.String encoding) Sets the character encoding to be declared by this Declaration.
Declaration	setValue(java.lang.String identifier, java.lang.String value) Sets the value of a named Attribute of this Declaration.
Declaration	setVersion(java.lang.String version) Sets the XML version to be declared by this Declaration.

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

getAttribute, getAttribute, getAttributes, getAttributes, getValue, hasAttributes, removeAttribute, removeAttribute

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

getIdentifier, getName, getNamespace, getPrefix

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

addContent, addContent, descendants, descendants, detach, getComment, getContent, getContent, getContent, getContents, getContents, getDocument, getParent, getText, hasContents, iterator, iterator, removeContent, removeContent, removeContents, setParent, 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

legalNames

private static final java.util.Set<java.lang.String> legalNames

Secret set of legal attribute names for a Declaration.

Constructor Detail

Declaration

public Declaration()

Creates a default XML declaration, setting the version attribute to 1.0 and the character encoding attribute to UTF-8.

Declaration

public Declaration(java.lang.String target)

Creates an XML declaration with the given target. The target can only be the identifier "xml"; ignores any other target.

Parameters:

target - must have the value "xml".

Method Detail

clone

public Declaration clone()

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

Overrides:

clone in class Descriptor

Returns:

a clone of this Declaration node.

getType

public int getType()

Returns the type of this Declaration. Returns the integer constant, DECLARATION, denoting that this is a Declaration node.

Overrides:

getType in class Content

Returns:

the integer constant DECLARATION.

addAttribute

public Declaration addAttribute(Attribute node)

Adds a uniquely named Attribute to this Declaration. If the Attribute has one of the legal names: "version, encoding, standalone", it will either be added, or its value will replace the value of the existing Attribute with the same name. Otherwise, it will be ignored.

Overrides:

addAttribute in class Descriptor

Parameters:

node - the Attribute to set.

Returns:

this Declaration.

setValue

public Declaration setValue(java.lang.String identifier,
                            java.lang.String value)

Sets the value of a named Attribute of this Declaration. If the name is one of the legal names: "version, encoding, standalone", the value of the Attribute with the same name will be replaced, or a new Attribute will be added. Otherwise, it will be ignored.

Overrides:

setValue in class Descriptor

Parameters:

identifier - the Attribute's long identifier, or short name.

value - the Attribute value.

Returns:

this Declaration.

getTarget

public java.lang.String getTarget()

Returns the target of this XML Declaration. The target can only be the identifier "xml". The target cannot be re-set.

Returns:

the identifier "xml".

getVersion

public java.lang.String getVersion()

Returns the XML version declared by this Declaration. By default, this is 1.0. This is a convenient shorthand for fetching the "version" Attribute's value.

Returns:

the XML version.

setVersion

public Declaration setVersion(java.lang.String version)

Sets the XML version to be declared by this Declaration. This should rarely be altered once the Declaration has been created. Whereas a version 1.1 of XML exists, nearly all processors support version 1.0.

Parameters:

version - the new XML version.

Returns:

this Declaration.

getEncoding

public java.lang.String getEncoding()

Returns the character encoding declared by this Declaration. By default, this is UTF-8. This is a convenient shorthand for fetching the "encoding" Attribute's value.

Returns:

the character encoding.

setEncoding

public Declaration setEncoding(java.lang.String encoding)

Sets the character encoding to be declared by this Declaration. The most common character encodings are UTF-8 (the default) and ISO-8859-1 (Latin-1), the encoding for the MIME-type text/xml. This encoding must match the encoding used when reading or writing a Document.

Parameters:

encoding - the character encoding.

Returns:

this Declaration.

isStandalone

public boolean isStandalone()

Reports whether the XML Document owning this Declaration stands alone. By default, if no "standalone" property has been set, returns true, as there is no related Doctype. If a Doctype node has been added to the related Document, then the "standalone" property will be set to one of "yes" (true) or "no" (false), and this method returns that value.

Returns:

true, if the "standalone" property is "yes" or absent.