Mike Champion, ArborText
Gavin Nicol, Inso EPS
The DOM Level One (Core) specification defines a set of object definitions that are sufficient to represent a document instance (the objects that occur withing the document itself). This specification is extends the DOM Level One (Core) specification such that document type definitions, entities, CDATA marked sections can also be represented.
The objects and interfaces defined within this document are sufficient to allow validators and other applications that make use of a DTD (Document Type Definition) to be written. For editors, the interfaces defined here will probably be insufficient for fine-grained editing, where information about the document type declaration may be necessary, though structural isomorphism should be easily accomplished.
The DOM Level One (Core) specification defines a set of object definitions that are sufficient to represent a document instance (the objects that occur within the document itself). This specification is extends the DOM Level One (Core) specification such that document type definitions, entities, CDATA marked sections can also be represented.
The objects and interfaces defined within this document are
sufficient to allow validators and other applications that
make use of a DTD (Document Type Definition) to
be written. For editors, the interfaces defined here will
probably be insufficient for fine-grained editing, where
information about the document type declaration
may be necessary, though structural isomorphism should be
easily accomplished.
This section describes the XML specialization of the Node objects. used throughout the DOM.
Interface XMLNodeThe XML implementation of the Node interface adds some methods that are needed to manipulate specific features of XML documents
IDL Definition
interface XMLNode { Node getParentXMLNode(in boolean expandEntities); NodeIterator getChildXMLNodes(in boolean expandEntities); boolean hasChildXMLNodes(in boolean expandEntities); Node getFirstXMLChild(in boolean expandEntities); Node getPreviousXMLSibling(in boolean expandEntities); Node getNextXMLSibling(in boolean expandEntities); EntityReference getEntityReference(); EntityDeclaration getEntityDeclaration(); };Method
getParentXMLNode()
Returns the parent of the given Node instance. If this node is the root of the document object tree, or if this node is not part of a document tree,
null
is returned.
Parameters
expandEntities TRUE if the view of the tree with parsed entities expanded should be navigated, FALSE if the view without parsed entities expanded should be navigated
Return Values
Node The parent of the node.
Exceptions
This method throws no exceptions. Method
getChildXMLNodes()
Returns a NodeIterator object that will enumerate all children of this node. If there are no children, an iterator that will return no nodes is returned. The content of the returned NodeIterator is "live" in the sense that changes to the children of the Node object that it was created from will be immediately reflected in the nodes returned by the iterator; it is not a static snapshot of the content of the Node. Similarly, changes made to the nodes returned by the iterator will be immediately reflected in the tree, including the set of children of the Node that the NodeIterator was created from.
Parameters
expandEntities TRUE if the view of the tree with parsed entities expanded should be navigated, FALSE if the view without parsed entities expanded should be navigated
Return Values
NodeIterator An iterator through the children of the node.
Exceptions
This method throws no exceptions. Method
hasChildXMLNodes()
Returns
true
if the node has any children,false
if the node has no children at all. This method exists both for convenience as well as to allow implementations to be able to bypass object allocation, which may be required for implementinggetChildNodes()
.
Parameters
expandEntities TRUE if the view of the tree with parsed entities expanded should be navigated, FALSE if the view without parsed entities expanded should be navigated
Return Values
boolean True if the node has children.
Exceptions
This method throws no exceptions. Method
getFirstXMLChild()
Returns the first child of a node. If there is no such node,
null
is returned.
Parameters
expandEntities TRUE if the view of the tree with parsed entities expanded should be navigated, FALSE if the view without parsed entities expanded should be navigated
Return Values
Node The first child of the node, or null.
Exceptions
This method throws no exceptions. Method
getPreviousXMLSibling()
Returns the node immediately preceding the current node in a breadth-first traversal of the tree. If there is no such node,
null
is returned.
Parameters
expandEntities TRUE if the view of the tree with parsed entities expanded should be navigated, FALSE if the view without parsed entities expanded should be navigated
Return Values
Node The the node immediately preceeding, or null.
Exceptions
This method throws no exceptions. Method
getNextXMLSibling()
Returns the node immediately following the current node in a breadth-first traversal of the tree. If there is no such node,
null
is returned.
Parameters
expandEntities TRUE if the view of the tree with parsed entities expanded should be navigated, FALSE if the view without parsed entities expanded should be navigated
Return Values
Node The node immediately following, or null.
Exceptions
This method throws no exceptions. Method
getEntityReference()
When navigating XML trees with expandedEntities set to TRUE, the DOM programmer will on occasion get Nodes returned that are part of the expansion of an entity rather than actual nodes in the tree. This method returns the entity reference that generated a particular node, or NULL if it was not part of an entity reference expansion.
Parameters
This method has no parameters.
Return Values
EntityReference The entity reference whose expansion yields a given node, or NULL if the node is not part of an entity expansion.
Exceptions
This method throws no exceptions. Method
getEntityDeclaration()
When navigating XML trees with expandedEntities set to TRUE, the DOM programmer will on occasion get Nodes returned that are part of the expansion of an entity rather than actual nodes in the tree. This method returns the declaration for the entity reference that generated a particular node, or NULL if it was not part of an entity reference expansion.
Parameters
This method has no parameters.
Return Values
EntityDeclaration The entity declaration for a reference whose expansion yields a given node, or NULL if the node is not part of an entity expansion.
Exceptions
This method throws no exceptions.
A Document Type Definition (DTD) defines three things:
From a practical point of view, this means that while all the
information contained within a DTD is available,
not all of the information about what created it is. Parameter
entity references, for example, are assumed to have been
already expanded, and hence, their boundaries are lost.
This section describes the objects that are used to represent the DTD of a document. The objects are not XML specific, though some attributes are specific to HTML DTD's. Such cases are clearly marked.
Interface DocumentTypeInterface ElementDefinitionEach document has a (possibly null) attribute that contains a reference to a
DocumentType
object. TheDocumentType
class provides an interface to access all of the entity declarations, notation declarations, and all the element type declarations.IDL Definition
interface DocumentType { attribute wstring name; attribute Node externalSubset; attribute Node internalSubset; attribute Node generalEntities; attribute Node parameterEntities; attribute Node notations; attribute Node elementTypes; };Attribute
name
The
name
attribute is awstring
that holds the name of DTD; i.e. the name immediately following theDOCTYPE
keyword.Attribute
externalSubset
The
externalSubset
attribute's children reference the list of nodes (definitions) that occurred in the external subset of a document. In this example:it would iterate over all of the declarations that occurred within the
<!DOCTYPE ex SYSTEM "ex.dtd" [ <ex/>ex.dtd
external entity. Note: An iterator interface is used so as to not constrain implementationsAttribute
internalSubset
The internal subset's children constitute all the definitions that occurred within the internal subset of a document (the part that appears within the document instance). For example
if would iterate over a single node: the definition of the
<!DOCTYPE ex SYSTEM "ex.dtd" [ <!ENTITY ex "example"> ]> <ex/>ex
entity. Note: An iterator interface is used so as to not constrain implementationsAttribute
generalEntities
This is a
Node
whose children constitute the set of general entites that were defined within the external and the internal subset. For example in:the interface would provide access to
<!DOCTYPE ex SYSTEM "ex.dtd" [ <!ENTITY foo "foo"> <!ENTITY bar "bar"> <!ENTITY % baz "baz"> ]> <ex/>foo
andbar
but notbaz
. All objects supporting theNode
interface that are accessed though this attribute, will also support theEntity
interface (defined below).Attribute
parameterEntities
This is a
Node
whose children constitute the set of parameter entites that were defined within the external and the internal subset. In the example above, the interface would provide access tobaz
but notfoo
orbar
. All objects supporting theNode
interface that are accessed though this attribute, will also support theEntity
interface (defined below).Attribute
notations
This is a
Node
whose children constitute the set of notations that were defined within the external and the internal subset. All objects supporting theNode
interface that are accessed though this attribute, will also support theNotation
interface (defined below).Attribute
elementTypes
This is a
Node
whose children constitute the set of element types that were defined within the external and the internal subset. All objects supporting theNode
interface that are accessed though this attribute, will also support theElementDefinition
interface (defined below).
Interface PCDATATokenThe definition of each element defined within the external or internal subset (providing it is parsed), will be available through the
elementTypes
attribute of theDocumentType
object. The name, attribute list, and content model are all available for inspection.IDL Definition
interface ElementDefinition : Node { // ContentType const int EMPTY = 1; const int ANY = 2; const int PCDATA = 3; const int MODEL_GROUP = 4; attribute wstring name; attribute int contentType; attribute ModelGroup contentModel; attribute Node attributeDefinitions; attribute Node inclusions; attribute Node exceptions; };Definition group
ContentType
Defined Constants
EMPTY The element is an empty element, and cannot have content.
ANY The element may have character data, or any of the other elements defined within the DTD as content, in any order and sequence.
PCDATA The element can have only PCDATA (Parsed Character Data) as content.
MODEL_GROUP The element has a specific content model associated with it. The model is accessible through the
contentModel
attribute (below).Attribute
name
This is the name of the type of element being defined.
Attribute
contentType
This attribute specifies the type of content of the element.
Attribute
contentModel
If the
contentType
isMODEL_GROUP
, then this will provide access to aModelGroup
(below) object that is the root of the content model object heirarchy for this element. For other content types, this will be null.Attribute
attributeDefinitions
The children of this
Node
consist of the attributes that were defined to be on anElementDefinition
. Each object supporting theNode
interface that is accessed through this attribute will also support theAttributeDefinition
interface.Attribute
inclusions
The children of this define a list of element type names that are included in the content model of this element by the SGML inclusion/exception mechanism (not available from XML, but used in HTML).
Attribute
exceptions
The children of this node define a list of element type names that are excluded from the content model of this element by the SGML inclusion/exception mechanism (not available from XML, but used in HTML).
Interface ElementTokenToken type for the string #PCDATA
IDL Definition
interface PCDATAToken : Node { };
Interface ModelGroupToken for an element declaration.
IDL Definition
interface ElementToken : Node { // OccurrenceType const int OPT = 1; const int PLUS = 2; const int REP = 3; attribute wstring name; attribute int occurrence; };Definition group
OccurrenceType
Defined Constants
OPT The
?
occurrence indicator.PLUS The
+
occurrence indicator.REP The
*
occurrence indicator.Attribute
name
The element type name.
Attribute
occurrence
The number of times this element can occur.
Interface AttributeDefinitionThe
ModelGroup
object represents the content model of anElementDefinition
. The content model is represented as a tree, where each node specifies how its children are connected, and the number of times that it can occur within its parent. Leaf nodes in the tree are eitherPCDATAToken
orElementToken
.IDL Definition
interface ModelGroup : Node { // OccurrenceType const int OPT = 1; const int PLUS = 2; const int REP = 3; // ConnectionType const int OR = 1; const int SEQ = 2; const int AND = 3; attribute int occurrence; attribute int connector; attribute Node tokens; };Definition group
OccurrenceType
Defined Constants
OPT The
?
occurrence indicator.PLUS The
+
occurrence indicator.REP The
*
occurrence indicator.Definition group
ConnectionType
Defined Constants
OR The
|
connection indicator.SEQ The
,
connection indicator.AND The
??
connection indicator.Attribute
occurrence
The number of times this model can occur.
Attribute
connector
Describes how the
tokens
are connected together.Attribute
tokens
The children of this node define the list of tokens in this model group.
Interface NotationThe
AttributeDefinition
interface is used to access information about a particular attribute definition on a given element. Object supporting this interface are available from theElementDefinition
object through theattributeDefinitions
attribute.IDL Definition
interface AttributeDefinition : Node { // DeclaredValueType const int CDATA = 1; const int ID = 2; const int IDREF = 3; const int IDREFS = 4; const int ENTITY = 5; const int ENTITIES = 6; const int NMTOKEN = 7; const int NMTOKENS = 8; const int NOTATION = 9; const int NAME_TOKEN_GROUP = 10; // DefaultValueType const int FIXED = 1; const int REQUIRED = 2; const int IMPLIED = 3; attribute wstring name; attribute StringList allowedTokens; attribute int declaredType; attribute int defaultType; attribute Node defaultValue; };Definition group
DeclaredValueType
Defined Constants
CDATA
ID
IDREF
IDREFS
ENTITY
ENTITIES
NMTOKEN
NMTOKENS
NOTATION
NAME_TOKEN_GROUP
Definition group
DefaultValueType
Defined Constants
FIXED
REQUIRED
IMPLIED
Attribute
name
The name of the attribute.
Attribute
allowedTokens
The list of tokens that are allowed as values. For example, in
this would hold
<!DOCTYPE ex [ <!ELEMENT ex (#PCDATA) > <!ATTLIST ex test (FOO|BAR) "FOO" > ]> <ex></ex>FOO
andBAR
.Attribute
declaredType
This attribute indicates the type of values the attribute may contain.
Attribute
defaultType
This specifies whether the attribute must be specified in the instance, and if it is not, what the attribute value will be if not provided.
Attribute
defaultValue
This provides an interface to a
Node
whose children make up the default value for an attribute. This value is used if the attribute was not given an explicit value in the document instance.
The
Notation
object is used to represent the definition of a notation within a DTD.IDL Definition
interface Notation : Node { attribute wstring name; attribute boolean isPublic; attribute string publicIdentifier; attribute string systemIdentifier; };Attribute
name
This is the name of the notation.
Attribute
isPublic
If a public identifier was specified in the notation declaration, this will be
TRUE
, and thepublicIdentifier
attribute will contain the string for the public identifier.Attribute
publicIdentifier
If a public identifier was specified in the notation declaration, this will hold the public identifier string, otherwise it will be null.
Attribute
systemIdentifier
If a system identifier was specified in the notation declaration, this will hold the system identifier string, otherwise it will be null.
XML contains the notion of "entities" that are declared in the DTD, defined in either internally in a document or in an external file, and referenced one or more places in the document. In any event, entities allow an abstract reference to some arbitrarily large or complex piece of text and markup.
Interface EntityDeclarationInterface EntityReference.
IDL Definition
interface EntityDeclaration { attribute wstring replacementString; attribute DocumentFragmentreplacementSubtree; };Attribute
replacementString
The string that a reference to this entity is replaced with. It may contain markup and entity references. It does not apply to un-parsed entities.
Attribute
replacementSubtree
The parsed subtree that references to this entity would logically point to. All markup in the replacement string is represented as sub-trees, and entity references are expanded.
EntityReference objects are inserted into the initial structure model by the XML processor. XML does not mandate that a non-validating XML processor read and process entity declarations made in the external subset or that are declared in external parameter entities. This means that parsed entitiesthat are declared in the external subset need not be expanded by some classes of applications.
XML contains the notion of " parsed entities" that are declared in the DTD, defined in either internally in a document or in an external file, and referenced one or more places in the document. In any event, parsed entities allow an abstract reference to some arbitrarily large or complex piece of text and markup. Parsed entities are one type of general entity. The other type of general entity that XML defines is the unparsed entity, used for embedding data that is not in XML format in an XML document. it is commonly used for images.
Parameter entities are used in DTDs for similar purposes as parsed entities in document instances; namely they allow an abstract reference to some part of the DTD. XML defines a number of rules about the allowed content of a parameter entity; the reader is referred to the XML specification for details.
IDL Definition
interface EntityReference { attribute boolean isExpanded; void expand(in ); };Attribute
isExpanded
The default view of entities is to be expanded.
Method
expand()
Parameters
Return Values
void
Exceptions
This method throws no exceptions.
XML adds to the range of objects that are available in document instances. These objects defined below.
Interface CDATASectionCDATA sections are used in the document instance, and provide a region in which most of the XML delimiter recognition does not take place. The primary purpose is for including material such as XML fragments, without needing to escape all the delimiters.
The wstring attribute of the Text node holds the text that was contained by the CDATA section. Note that this may contain characters that need to be escaped outside of CDATA sections.
IDL Definition
interface CDATASection : Text { };
interface XMLNode { Node getParentXMLNode(in boolean expandEntities); NodeIterator getChildXMLNodes(in boolean expandEntities); boolean hasChildXMLNodes(in boolean expandEntities); Node getFirstXMLChild(in boolean expandEntities); Node getPreviousXMLSibling(in boolean expandEntities); Node getNextXMLSibling(in boolean expandEntities); EntityReference getEntityReference(); EntityDeclaration getEntityDeclaration(); }; interface DocumentType { attribute wstring name; attribute Node externalSubset; attribute Node internalSubset; attribute Node generalEntities; attribute Node parameterEntities; attribute Node notations; attribute Node elementTypes; }; interface ElementDefinition : Node { // ContentType const int EMPTY = 1; const int ANY = 2; const int PCDATA = 3; const int MODEL_GROUP = 4; attribute wstring name; attribute int contentType; attribute ModelGroup contentModel; attribute Node attributeDefinitions; attribute Node inclusions; attribute Node exceptions; }; interface PCDATAToken : Node { }; interface ElementToken : Node { // OccurrenceType const int OPT = 1; const int PLUS = 2; const int REP = 3; attribute wstring name; attribute int occurrence; }; interface ModelGroup : Node { // OccurrenceType const int OPT = 1; const int PLUS = 2; const int REP = 3; // ConnectionType const int OR = 1; const int SEQ = 2; const int AND = 3; attribute int occurrence; attribute int connector; attribute Node tokens; }; interface AttributeDefinition : Node { // DeclaredValueType const int CDATA = 1; const int ID = 2; const int IDREF = 3; const int IDREFS = 4; const int ENTITY = 5; const int ENTITIES = 6; const int NMTOKEN = 7; const int NMTOKENS = 8; const int NOTATION = 9; const int NAME_TOKEN_GROUP = 10; // DefaultValueType const int FIXED = 1; const int REQUIRED = 2; const int IMPLIED = 3; attribute wstring name; attribute StringList allowedTokens; attribute int declaredType; attribute int defaultType; attribute Node defaultValue; }; interface Notation : Node { attribute wstring name; attribute boolean isPublic; attribute string publicIdentifier; attribute string systemIdentifier; }; interface EntityDeclaration { attribute wstring replacementString; attribute DocumentFragmentreplacementSubtree; }; interface EntityReference { attribute boolean isExpanded; void expand(in ); }; interface CDATASection : Text { };
public interface XMLNode { public Node getParentXMLNode(boolean expandEntities); public NodeIterator getChildXMLNodes(boolean expandEntities); public boolean hasChildXMLNodes(boolean expandEntities); public Node getFirstXMLChild(boolean expandEntities); public Node getPreviousXMLSibling(boolean expandEntities); public Node getNextXMLSibling(boolean expandEntities); public EntityReference getEntityReference(); public EntityDeclaration getEntityDeclaration(); } public interface DocumentType { public String getName(); public void setName(String arg); public Node getExternalSubset(); public void setExternalSubset(Node arg); public Node getInternalSubset(); public void setInternalSubset(Node arg); public Node getGeneralEntities(); public void setGeneralEntities(Node arg); public Node getParameterEntities(); public void setParameterEntities(Node arg); public Node getNotations(); public void setNotations(Node arg); public Node getElementTypes(); public void setElementTypes(Node arg); } public interface ElementDefinition extends Node { // ContentType public static final int EMPTY = 1; public static final int ANY = 2; public static final int PCDATA = 3; public static final int MODEL_GROUP = 4; public String getName(); public void setName(String arg); public int getContentType(); public void setContentType(int arg); public ModelGroup getContentModel(); public void setContentModel(ModelGroup arg); public Node getAttributeDefinitions(); public void setAttributeDefinitions(Node arg); public Node getInclusions(); public void setInclusions(Node arg); public Node getExceptions(); public void setExceptions(Node arg); } public interface PCDATAToken extends Node { } public interface ElementToken extends Node { // OccurrenceType public static final int OPT = 1; public static final int PLUS = 2; public static final int REP = 3; public String getName(); public void setName(String arg); public int getOccurrence(); public void setOccurrence(int arg); } public interface ModelGroup extends Node { // OccurrenceType public static final int OPT = 1; public static final int PLUS = 2; public static final int REP = 3; // ConnectionType public static final int OR = 1; public static final int SEQ = 2; public static final int AND = 3; public int getOccurrence(); public void setOccurrence(int arg); public int getConnector(); public void setConnector(int arg); public Node getTokens(); public void setTokens(Node arg); } public interface AttributeDefinition extends Node { // DeclaredValueType public static final int CDATA = 1; public static final int ID = 2; public static final int IDREF = 3; public static final int IDREFS = 4; public static final int ENTITY = 5; public static final int ENTITIES = 6; public static final int NMTOKEN = 7; public static final int NMTOKENS = 8; public static final int NOTATION = 9; public static final int NAME_TOKEN_GROUP = 10; // DefaultValueType public static final int FIXED = 1; public static final int REQUIRED = 2; public static final int IMPLIED = 3; public String getName(); public void setName(String arg); public String getAllowedTokens(); public void setAllowedTokens(String arg); public int getDeclaredType(); public void setDeclaredType(int arg); public int getDefaultType(); public void setDefaultType(int arg); public Node getDefaultValue(); public void setDefaultValue(Node arg); } public interface Notation extends Node { public String getName(); public void setName(String arg); public boolean getIsPublic(); public void setIsPublic(boolean arg); public String getPublicIdentifier(); public void setPublicIdentifier(String arg); public String getSystemIdentifier(); public void setSystemIdentifier(String arg); } public interface EntityDeclaration { public String getReplacementString(); public void setReplacementString(String arg); public DocumentFragment getReplacementSubtree(); public void setReplacementSubtree(DocumentFragment arg); } public interface EntityReference { public boolean getIsExpanded(); public void setIsExpanded(boolean arg); public void expand( ); } public interface CDATASection extends Text { }
The XMLNode object has the following properties:
- entityReference
- This property is expected to be a EntityReference
- entityDeclaration
- This property is expected to be a EntityDeclaration
The XMLNode object has the following methods:
- getParentXMLNode(expandEntities)
- This method returns a Node. The expandEntities parameter is expected to be of type boolean..
- getChildXMLNodes(expandEntities)
- This method returns a NodeIterator. The expandEntities parameter is expected to be of type boolean..
- hasChildXMLNodes(expandEntities)
- This method returns a boolean. The expandEntities parameter is expected to be of type boolean..
- getFirstXMLChild(expandEntities)
- This method returns a Node. The expandEntities parameter is expected to be of type boolean..
- getPreviousXMLSibling(expandEntities)
- This method returns a Node. The expandEntities parameter is expected to be of type boolean..
- getNextXMLSibling(expandEntities)
- This method returns a Node. The expandEntities parameter is expected to be of type boolean..
The DocumentType object has the following properties:
- name
- This property is expected to be a String
- externalSubset
- This property is expected to be a Node
- internalSubset
- This property is expected to be a Node
- generalEntities
- This property is expected to be a Node
- parameterEntities
- This property is expected to be a Node
- notations
- This property is expected to be a Node
- elementTypes
- This property is expected to be a Node
ElementDefinition has the all the properties and methods of Node as well as the properties and methods defined below.
The ElementDefinition object has the following properties:
- name
- This property is expected to be a String
- contentType
- This property is expected to be a int
- contentModel
- This property is expected to be a ModelGroup
- attributeDefinitions
- This property is expected to be a Node
- inclusions
- This property is expected to be a Node
- exceptions
- This property is expected to be a Node
PCDATAToken has the all the properties and methods of Node as well as the properties and methods defined below.
ElementToken has the all the properties and methods of Node as well as the properties and methods defined below.
The ElementToken object has the following properties:
- name
- This property is expected to be a String
- occurrence
- This property is expected to be a int
ModelGroup has the all the properties and methods of Node as well as the properties and methods defined below.
The ModelGroup object has the following properties:
- occurrence
- This property is expected to be a int
- connector
- This property is expected to be a int
- tokens
- This property is expected to be a Node
AttributeDefinition has the all the properties and methods of Node as well as the properties and methods defined below.
The AttributeDefinition object has the following properties:
- name
- This property is expected to be a String
- allowedTokens
- This property is expected to be a String
- declaredType
- This property is expected to be a int
- defaultType
- This property is expected to be a int
- defaultValue
- This property is expected to be a Node
Notation has the all the properties and methods of Node as well as the properties and methods defined below.
The Notation object has the following properties:
- name
- This property is expected to be a String
- isPublic
- This property is expected to be a boolean
- publicIdentifier
- This property is expected to be a String
- systemIdentifier
- This property is expected to be a String
The EntityDeclaration object has the following properties:
- replacementString
- This property is expected to be a String
- replacementSubtree
- This property is expected to be a DocumentFragment
The EntityReference object has the following properties:
- isExpanded
- This property is expected to be a boolean
The EntityReference object has the following methods:
- expand()
- This method returns a void. The parameter is expected to be of type ..
CDATASection has the all the properties and methods of Text as well as the properties and methods defined below.