2
Document Object Model (DOM)

An XML document can be viewed as a tree whose nodes consisting of information between start-tags and end-tags. This tree representation, or the Document Object Model (DOM), is formed in memory when the XML parser parses a document. The DOM APIs are contained in the oracle.xml.parser.v2 package.

This chapter discusses the APIs for accessing and navigating this tree and includes the following sections:

• NSResolver Interface
• PrintDriver Interface
• AttrDecl Class
• DTD Class
• ElementDecl Class
• XMLAttr Class
• XMLCDATA Class
• XMLComment Class
• XMLDeclPI Class
• XMLDocument Class
• XMLDocumentFragment Class
• XMLDOMException Class
• XMLDOMImplementation
• XMLElement Class
• XMLEntity Class
• XMLEntityReference Class
• XMLNode Class
• XMLNotation Class
• XMLNSNode Class
• XMLOutputStream Class
• XMLPI Class
• XMLPrintDriver Class
• XMLRangeException Class
• XMLText Class

  See Also: Oracle9i XML Developer's Kits Guide - XDK Oracle9i Supplied Java Packages Reference

---

NSResolver Interface

---

Syntax of NSResolver

public interface NSResolver

---

Description of NSResolver

This interface provides support for resolving Namespaces.

---

Implementing Classes of NSResolver

XMLElement

---

Methods of NSResolver

resolveNamespacePrefix()

Description

Finds and returns the namespace definition in scope for a given namespace prefix; returns null if prefix could not be resolved.

Syntax

public String resolveNamespacePrefix( String prefix);

Parameter	Description
prefix	Namespace prefix to be resolved.

---

PrintDriver Interface

---

Description of PrintDriver

The PrintDriver interface defines methods used to print XML documents represented as DOM trees.

---

Syntax of PrintDriver

public interface PrintDriver

---

Implementing Classes of PrintDriver

XMLPrintDriver

---

Methods of PrintDriver

Table 2-1 Summary of Methods of PintDriver

Method	Description
close()	Closes the output stream or print writer
flush()	Flushes the output stream or print writer
printAttribute()	Prints an XMLAttr node
printAttributeNodes()	Calls print method for each attribute of the XMLElement.
printCDATASection()	Prints an XMLCDATA node.
printChildNodes()	Calls print method for each child of the XMLNode
printComment()	Prints an XMLComment node.
printDoctype()	Prints a DTD.
printDocument()	Prints an XMLDocument.
printDocumentFragment()	Prints an empty XMLDocumentFragment object.
printElement()	Prints an XMLElement.
printEntityReference()	Prints an XMLEntityReference node.
printProcessingInstruction()	Prints an XMLPI node.
printTextNode()	Prints an XMLText node.
setEncoding()	Sets the encoding of the print driver.

close()

Description

Closes the output stream or print writer

Syntax

public void close();

flush()

Description

Flushes the output stream or print writer

Syntax

public void flush();

printAttribute()

Description

Prints an XMLAttr node

Syntax

public void printAttribute( XMLAttr attr);

Parameter	Description
attr	The XMLAttr node.

printAttributeNodes()

Description

Calls print method for each attribute of the XMLElement.

Syntax

public void printAttributeNodes( XMLElement elem);

Parameter	Description
elem	The elem whose attributes are to be printed.

printCDATASection()

Description

Prints an XMLCDATA node.

Syntax

public void printCDATASection( XMLCDATA cdata);

Parameter	Description
cdata	The XMLCDATA node.

printChildNodes()

Description

Calls print method for each child of the XMLNode

Syntax

public void printChildNodes( XMLNode node);

Parameter	Description
node	The node whose children are to be printed.

printComment()

Description

Prints an XMLComment node.

Syntax

public void printComment( XMLComment comment);

Parameter	Description
comment	The comment node.

printDoctype()

Description

Prints a DTD.

Syntax

public void printDoctype( DTD dtd);

Parameter	Description
dtd	The DTD to be printed.

printDocument()

Description

Prints an XMLDocument.

Syntax

public void printDocument( XMLDocument doc);

Parameter	Description
doc	The document to be printed.

printDocumentFragment()

Description

Prints an empty XMLDocumentFragment object.

Syntax

public void printDocumentFragment( XMLDocumentFragment dfrag);

Parameter	Description
dfrag	The document fragment to be printed.

printElement()

Description

Prints an XMLElement.

Syntax

public void printElement( XMLElement elem);

Parameter	Description
elem	The element to be printed.

printEntityReference()

Description

Prints an XMLEntityReference node.

Syntax

public void printEntityReference( XMLEntityReference eref);

Parameter	Description
eref	The XMLEntityReference node to be printed.

printProcessingInstruction()

Description

Prints an XMLPI node.

Syntax

public void printProcessingInstruction( XMLPI pi);

Parameter	Description
pi	The XMLPI node to be printed.

printTextNode()

Description

Prints an XMLText node.

Syntax

public void printTextNode( XMLText text);

Parameter	Description
text	The text node.

setEncoding()

Description

Sets the encoding of the print driver.

Syntax

public void setEncoding( String enc);

Parameter	Description
enc	The encoding of the document being printed.

---

AttrDecl Class

---

Description of AttrDecl

This class hold information about each attribute declared in an attribute list in the Document Type Definition.

---

Syntax of AttrDecl

public class AttrDecl implements java.io.Externalizable
 
oracle.xml.parser.v2.AttrDecl

---

Implemented Interfaces of AttrDecl

java.io.Externalizable, java.io.Serializable

---

Fields of AttrDecl

Table 2-2 Fields of AttrDecl  

Field	Syntax	Description
CDATA	public static final int CDATA	AttType - StringType - CDATA
DEFAULT	public static final int DEFAULT	Attribute presence - Default
ENTITIES	public static final int ENTITIES	AttType - TokenizedType - Entities
ENTITY	public static final int ENTITY	AttType - TokenizedType - Entity
ENUMERATION	public static final int ENUMERATION	AttType - EnumeratedType - Enumeration
FIXED	public static final int FIXED	Attribute presence - Fixed
ID	public static final int ID	AttType - TokenizedType - ID
IDREF	public static final int IDREF	AttType - TokenizedType - ID reference
IDREFS	public static final int IDREFS	AttType - TokenizedType - ID references
IMPLIED	public static final int IMPLIED	Attribute presence - Implied
NMTOKEN	public static final int NMTOKEN	AttType - TokenizedType - Name token
NMTOKENS	public static final int NMTOKENS	AttType - TokenizedType - Name tokens
NOTATION	public static final int NOTATION	AttType - EnumeratedType - Notation
REQUIRED	public static final int REQUIRED	Attribute presence - Required

---

Methods of AttrDecl

Table 2-3 Summary of Methods of AttrDecl  

Methods	Description
AttrDecl()	Default constructor.
getAttrPresence()	Returns attribute presence.
getAttrType()	Returns attribute type.
getDefaultValue()	Returns attribute default value.
getEnumerationValues()	Returns attribute values as an Enumeration.
getNodeName()	Returns the name of the Attr Decl.
getNodeType()	Returns a code representing the type of the underlying object.
readExternal()	Reads the information written in the compressed stream by writeExternal method and restores the object correspondingly.
typeToString()	Returns a string representation of the attribute type.
writeExternal()	Saves the state of the object by creating a binary compressed stream with information about this object.

AttrDecl()

Description

Default constructor. Note that this constructor is used only during deserialization/ decompression of this DOM node. In order to deserialize this node to construct the DOM node from the serialized/ compressed stream, it is required to create a handle of the object.

Syntax

public static final int REQUIRED public  AttrDecl();

getAttrPresence()

Description

Returns attribute presence.

Syntax

public int getAttrPresence();

getAttrType()

Description

Returns attribute type.

Syntax

public int getAttrType();

getDefaultValue()

Description

Returns attribute default value.

Syntax

public String getDefaultValue();

getEnumerationValues()

Description

Returns attribute values as an Enumeration.

Syntax

public java.util.Vector getEnumerationValues();

getNodeName()

Description

Returns the name of the Attr Decl.

Syntax

public String getNodeName();

getNodeType()

Description

Returns a code representing the type of the underlying object.

Syntax

public short getNodeType();

readExternal()

Description

Reads the information written in the compressed stream by writeExternal method and restores the object correspondingly. Throws:

• IOException is thrown when there is an error in reading the input stream.
• ClassNotFoundException is thrown when the class is not found

Syntax

public void readExternal( java.io.ObjectInput i);

Parameter	Description
in	The ObjectInput stream used for reading the compressed stream.

typeToString()

Description

Returns a string representation of the attribute type.

Syntax

public static String typeToString( int type);

Parameter	Description
type	Numerical representation of the attribute type.

writeExternal()

Description

Saves the state of the object by creating a binary compressed stream with information about this object. Throws IOException when there is an exception while writing the serialized/compressed stream.

Syntax

public void writeExternal( java.io.ObjectOutput out);

Parameter	Description
out	The ObjectOutput stream used to write the serialized/ compressed stream.

---

DTD Class

---

Description of DTD

Implements the DOM DocumentType interface and holds the Document Type. Definition information for an XML document.

---

Syntax of DTD

public class DTD implements java.io.Externalizable
 
oracle.xml.parser.v2.DTD

---

Implemented Interfaces of DTD

java.io.Externalizable, java.io.Serializable

---

Methods of DTD

Table 2-4 Summary of Methods of DTD  

Method	Description
DTD()	Default constructor.
findElementDecl()	Finds and returns an element declaration for the given tag name.
findEntity()	Finds and returns a named entity in the DTD; returns null if it is not found.
findNotation()	Retrieves the named notation from the DTD; returns null if it is not found.
getChildNodes()	Returns a NodeList that contains all children of this node.
getElementDecls()	Returns a NamedNodeMap containing the element declarations in the DTD.
getEntities()	Returns a NamedNodeMap containing the general entities, both external and internal, declared in the DTD.
getInternalSubset()	Returns the internal subset of the DTD.
getName()	Returns the name of the DTD, or the name immediately following the DOCTYPE keyword.
getNodeName()	Returns the name of the DTD, or the name immediately following the DOCTYPE keyword.
getNodeType()	Returns a code representing the type of the underlying object.
getNotations()	Returns a NamedNodeMap containing the notations declared in the DTD.
getOwnerImplementation()	Returns the owner of the DTD implementation.
getPublicId()	Returns the public identifier associated with the DTD, if specified.
getRootTag()	Returns the root tag for the DTD.
getSystemId()	Returns the system identifier associated with the DTD, if specified. If the system identifier was not specified, this is null.
hasChildNodes()	Determines whether a node has any children; return false always, as DTD cannot have any overrides method in XMLNode.
normalize()	Normalizes the DTD.
printExternalDTD()	Writes the contents of this document to the given output.
readExternal()	Reads the information written in the compressed stream by writeExternal method and restores the object correspondingly.
setRootTag()	Sets the root tag for the DTD.
writeExternal()	Saves the state of the object by creating a binary compressed stream with information about this object.

DTD()

Description

Default constructor. Note that this constructor is used only during deserialization/decompression of this DOM node. In order to deserialize this node to construct the DOM node from the serialized/ compressed stream, it is required to create a handle of the object.

Syntax

public  DTD();

findElementDecl()

Description

Finds and returns an element declaration for the given tag name.

Syntax

public final ElementDecl findElementDecl( String name);

Parameter	Description
name	The tag name.

findEntity()

Description

Finds and returns a named entity in the DTD; returns null if it is not found.

Syntax

public final org.w3c.dom.Entity findEntity( String n,
                                            boolean par);

Parameter	Description
n	The name of the entity.
par	Boolean indicating if the entity is parameter Entity.

findNotation()

Description

Retrieves the named notation from the DTD; returns null if it is not found.

Syntax

public final org.w3c.dom.Notation findNotation( String name);

Parameter	Description
name	The name of the notation.

getChildNodes()

Description

Return a NodeList that contains all children of this node. If there are no children, this is a NodeList containing no nodes. The content of the returned NodeList is "live" in the sense that, for instance, changes to the children of the node object that it was created from are immediately reflected in the nodes returned by the NodeList accessors; it is not a static snapshot of the content of the node. This is true for every NodeList, including the ones returned by the getElementsByTagName method.

Syntax

public org.w3c.dom.NodeList getChildNodes();

getElementDecls()

Description

Returns a NamedNodeMap containing the element declarations in the DTD. Every node in this map is an ElementDecl object. The element declarations in the DTD The DOM Level 1 does not support editing ElementDecl, therefore ElementDecl cannot be altered in any way.

Syntax

public org.w3c.dom.NamedNodeMap getElementDecls();

getEntities()

Description

Returns a NamedNodeMap containing the general entities, both external and internal, declared in the DTD. Duplicates are discarded. For example in:<!DOCTYPE ex SYSTEM "ex.dtd" [ <!ENTITY foo "foo"> <!ENTITY bar "bar"> <!ENTITY % baz "baz">]> <ex/> the interface provides access to foo and bar but not baz. Every node in this map also implements the Entity interface. The DOM Level 1 does not support editing entities, therefore entities cannot be altered in any way.

Syntax

public org.w3c.dom.NamedNodeMap getEntities();

getInternalSubset()

Description

Returns the internal subset of the DTD.

Syntax

public String getInternalSubset();

getName()

Description

Returns the name of the DTD, or the name immediately following the DOCTYPE keyword.

Syntax

public String getName();

getNodeName()

Description

Returns the name of the DTD; or the name immediately following the DOCTYPE keyword.

Syntax

public String getNodeName();

getNodeType()

Description

Returns a code representing the type of the underlying object.

Syntax

public short getNodeType();

getNotations()

Description

Returns a NamedNodeMap containing the notations declared in the DTD. Duplicates are discarded. Every node in this map also implements the Notation interface. The DOM Level 1 does not support editing notations, therefore notations cannot be altered in any way.

Syntax

public org.w3c.dom.NamedNodeMap getNotations();

getOwnerImplementation()

Description

Returns the owner of the DTD implementation.

Syntax

public XMLDOMImplementation getOwnerImplementation();

getPublicId()

Description

Returns the public identifier associated with the DTD, if specified. If the public identifier was not specified, this is null.

Syntax

public String getPublicId();

getRootTag()

Description

Returns the root tag for the DTD.

Syntax

public String getRootTag();

getSystemId()

Description

Returns the system identifier associated with the DTD, if specified. If the system identifier was not specified, this is null.

Syntax

public String getSystemId();

hasChildNodes()

Description

Determines whether a node has any children; return false always, as DTD cannot have any overrides method in XMLNode.

Syntax

public boolean hasChildNodes();

normalize()

Description

Normalizes the DTD.

Syntax

public void normalize();

printExternalDTD()

Description

Writes the contents of this document to the given output. Throws IOException if an invalid encoding is specified or another error occurs. The options are described in the following table.

Syntax	Description
public void printExternalDTD( java.io.OutputStream out);	Writes the contents of this document to the given output stream.
public void printExternalDTD( java.io.OutputStream out, String enc);	Writes the contents of this document to the given encoded output stream.
public void printExternalDTD( java.io.PrintWriter out);	Writes the contents of this document to the given print writer.

Parameter	Description
out	The output.
enc	Encoding used for the output.

readExternal()

Description

Reads the information written in the compressed stream by writeExternal method and restores the object correspondingly. Throws the following exceptions:

• IOException when there is an error in reading the input stream.
• ClassNotFoundException when the class is not found.

Syntax

public void readExternal( java.io.ObjectInput in);

Parameter	Description
in	The ObjectInput stream used for reading the compressed stream.

setRootTag()

Description

Set the root tag for the DTD

Syntax

public void setRootTag( String root);

Parameter	Description
root	The root tag.

writeExternal()

Description

Saves the state of the object by creating a binary compressed stream with information about this object. Throws IOException when there is an exception while writing the serialized/compressed stream.

Syntax

public void writeExternal( java.io.ObjectOutput out);

Parameter	Description
out	The ObjectOutput stream used to write the serialized/ compressed stream.

---

ElementDecl Class

---

Description of ElementDecl

This class represents an element declaration in a DTD.

---

Syntax of ElementDecl

public class ElementDecl implements java.io.Serializable, java.io.Externalizable
 
oracle.xml.parser.v2.ElementDecl

---

Implemented Interfaces of ElementDecl

java.io.Externalizable, java.io.Serializable

---

Fields of ElementDecl

Table 2-5 Fields of ElementDecl  

Field	Syntax	Description
ANY	public static final byte ANY	Element content type - Children can be any element.
ASTERISK	public static final int ASTERISK	ContentModelParseTreeNode type - "*" node (has one child).
COMMA	public static final int COMMA	ContentModelParseTreeNode type - "," node (has two children).
ELEMENT	public static final int ELEMENT	ContentModelParseTreeNode type - 'leaf' node (has no children).
ELEMENT_DECLARED	public static final int ELEMENT_DECLARED	Node flag to represent element declaration in a DTD.
ELEMENTS	public static final byte ELEMENTS	Element content type - Children can be elements; see Content Model.
EMPTY	public static final byte EMPTY	Element content type - No Children.
ID_ATTR_DECL	public static final int ID_ATTR_DECL	Node flag to represent ID attribute declaration in a DTD.
MIXED	public static final byte MIXED	Element content type - Children can be PCDATA & elements; see Content Model.
OR	public static final int OR	ContentModelParseTreeNode type - "|" node (has two children).
PLUS	public static final int PLUS	ContentModelParseTreeNode type - "+" node (has one children).
QMARK	public static final int QMARK	ContentModelParseTreeNode type - "?" node (has one children).

---

Methods of ElementDecl

Table 2-6 Summary of Methods of ElementDecl

Method	Description
ElementDecl()	Default constructor.
cloneNode()	Returns a duplicate of this node; serves as a generic copy constructor for nodes.
expectedElements()	Returns vector of element names that can be appended to the element.
findAttrDecl()	Returns an attribute declaration object or null if not found
getAttrDecls()	Returns an enumeration of attribute declarations.
getContentElements()	Returns a vector of elements that can be appended to this element.
getContentType()	Returns the content model of element.
getNodeName()	Returns the name of the Element Decl.
getNodeType()	Returns a code representing the type of the underlying object.
getParseTree()	Returns the root node of Content Model Parse Tree.
readExternal()	Reads the information written in the compressed stream by writeExternal method and restores the object correspondingly. Throws the following exceptions:
validateContent()	Validates the content of a element node.
writeExternal()	Saves the state of the object by creating a binary compressed stream with information about this object.

ElementDecl()

Description

Default constructor. Note that this constructor is used only during deserialization/decompression of this DOM node. In order to deserialize this node to construct the DOM node from the serialized/ compressed stream, it is required to create a handle of the object.

Syntax

public  ElementDecl();

cloneNode()

Description

Returns a duplicate of this node; serves as a generic copy constructor for nodes. The duplicate node has no parent (parentNode returns null.). Cloning an Element copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but this method does not copy any text it contains unless it is a deep clone, since the text is contained in a child Text node. Cloning any other type of node simply returns a copy of this node.

Syntax

public org.w3c.dom.Node cloneNode(boolean deep);

Parameter	Description
deep	If true, recursively clone the subtree under the specified node; if false, clone only the node itself (and its attributes, if it is an Element)

expectedElements()

Description

Returns vector of element names that can be appended to the element.

Syntax

public java.util.Vector expectedElements( org.w3c.dom.Element e);

Parameter	Description
e	Element.

findAttrDecl()

Description

Returns an attribute declaration object or null if not found

Syntax

public final AttrDecl findAttrDecl( String name);

Parameter	Description
name	The attribute declaration to find.

getAttrDecls()

Description

Returns an enumeration of attribute declarations.

Syntax

public org.w3c.dom.NamedNodeMap getAttrDecls();

getContentElements()

Description

Returns a vector of elements that can be appended to this element.

Syntax

public final java.util.Vector getContentElements();

getContentType()

Description

Returns the content model of element.

Syntax

public int getContentType();

getNodeName()

Description

Returs the name of the Element Decl.

Syntax

public String getNodeName();

getNodeType()

Description

Returns a code representing the type of the underlying object.

Syntax

public short getNodeType();

getParseTree()

Description

Returns the root node of Content Model Parse Tree. Node.getFirstChild() and Node.getLastChild() return the parse tree branches. Node.getNodeType() and Node.getNodeName() return the parse tree node type and name.

Syntax

public final org.w3c.dom.Node getParseTree();

readExternal()

Description

Reads the information written in the compressed stream by writeExternal method and restores the object correspondingly. Throws the following exceptions:

• IOException when there is an error in reading the input stream.
• ClassNotFoundException when the class is not found.

Syntax

public void readExternal( java.io.ObjectInput in);

Parameter	Description
in	The ObjectInput stream used for reading the compressed stream.

validateContent()

Description

Validates the content of a element node; returns TRUE if valid, FLASE otherwise.

Syntax

public boolean validateContent(org.w3c.dom.Element e);

Parameter	Description
e	Element node to validate.

writeExternal()

Description

Saves the state of the object by creating a binary compressed stream with information about this object. Throws IOException when there is an exception while writing the serialized/compressed stream.

Syntax

public void writeExternal( java.io.ObjectOutput out);

Parameter	Description
out	The ObjectOutput stream used to write the serialized/ compressed stream.

---

XMLAttr Class

---

Description of XMLAttr

This class implements the DOM Attr interface and holds information on each attribute of an element. See also Attr, NodeFactory, DOMParser.setNodeFactory().

---

Syntax of XMLAttr

public class XMLAttr implements oracle.xml.parser.v2.NSName, 
java.io.Externalizable
 
oracle.xml.parser.v2.XMLAttr

---

Implemented Interfaces of XMLAttr

java.io.Externalizable, NSName, oracle.xml.util.NSName, java.io.Serializable

---

Methods of XMLAttr

Table 2-7 Summary of Methods of XMLAttr  

Method	Description
addText()	Adds text to the XMLNode.
cloneNode()	Returns a duplicate of this node; serves as a generic copy constructor for nodes.
getExpandedName()	Returns the fully resolved Name for this attribute.
getLocalName()	Returns the local name of this attribute.
getName()	Returns the attribute name.
getNamespaceURI()	Returns the namespace of the attribute.
getNextAttribute()	Returns the next attribute, if any.
getNextSibling()	Returns the next sibling, if any.
getNodeType()	Returns a code representing the type of the underlying object.
getNodeValue()	Returns the value of this node, depending on its type.
getOwnerElement()	Returns the element which owns this attribute.
getParentNode()	Returns the parent of this node.
getPrefix()	Returns the name space prefix of the element.
getPreviousSibling()	Returns the previous sibling, if any.
getSpecified()	Returns TRUE if the attribute was specified explicitly in the element, FALSE otherwise.
getValue()	Returns the attribute value.
readExternal()	Restores the information written by writeExternal.
setNodeValue()	Sets the value of this node, depending on its type.