25
PL/SQL DOM API for XMLType

The Extensible Markup Language (XML) Parser for PL/SQL, found in the DBMS_XMLDOM Package, is used to access XMLType objects and both schema-based and nonschema-based documents.

This chapter details the following:

DBMS_XMLDOM Package

Description of DBMS_XMLDOM

The Document Object Model (DOM) is an application programming interface (API) for HTML and XML documents. It defines the logical structure of documents and the way a document is accessed and manipulated. In the DOM specification, the term "document" is used in the broad sense. XML is increasingly being used as a way of representing many different kinds of information that may be stored in diverse systems, and much of this would traditionally be seen as data rather than as documents. Nevertheless, XML presents this data as documents, and the DOM may be used to manage this data.

With the Document Object Model, programmers can build documents, navigate their structure, and add, modify, or delete elements and content. Anything found in an HTML or XML document can be accessed, changed, deleted, or added using the Document Object Model, with a few exceptions. In particular, the DOM interfaces for the XML internal and external subsets have not yet been specified.

One important objective of the W3C specification for the Document Object Model is to provide a standard programming interface that can be used in a wide variety of environments and applications. The DOM is designed to be used with any programming language. Since the DOM standard is object-oriented, for this PL/SQL adaptation, some changes had to be made:

Various DOM interfaces such as Node, Element, and so on, have equivalent PL/SQL types DOMNode, DOMElement, and so on, respectively.
Various DOMException codes such as WRONG_DOCUMENT_ERR, HIERARCHY_REQUEST_ERR, and so on, have similarly named PL/SQL exceptions
Various DOM Node type codes such as ELEMENT_NODE, ATTRIBUTE_NODE, and so on, have similarly named PL/SQL constants

Methods defined on a DOM type become functions or procedures that accept it as a parameter. For example, to perform appendChild on a DOM Node n, the appendChild() PL/SQL function is provided,

        FUNCTION appendChild( n DOMNode, 
                               newChild IN DOMNode)
                               RETURN DOMNode;

and to perform setAttribute on a DOM Element elem, the setAttribute() PL/SQL procedure is provided:

            PROCEDURE setAttribute( elem DOMElement,
                                    name IN VARCHAR2,
                                    value IN VARCHAR2);

DOM defines an inheritance hierarchy. For example, Document, Element, and Attr are defined to be subtypes of Node. Thus, a method defined in the Node interface should be available in these as well. Since, such inheritance is not directly possible in PL/SQL, the makeNode functions need to be invoked on different DOM types to convert these into a DOMNode. The appropriate functions or procedures that accept DOMNodes can then be called to operate on these types. If, subsequently, type specific functionality is desired, the DOMNode can be converted back into the type by using the make*() functions, where DOM* is the desired DOM type.

The implementation of this PL/SQL DOM interface followed the DOM standard of revision REC-DOM-Level-1-19981001. The types and methods described in this document are made available by the PL/SQL package DBMS_XMLDOM.

Before database startup, the read-from and write-to directories in the initialization.ORA file must be specified; for example:
```
          UTL_FILE_DIR=/mypath/insidemypath
```

The read-from and write-to files must be on the server file system.

Types of DBMS_XMLDOM

The following types are defined for DBMS_XMLDOM.DOMTYPE:

Table 25-1 DBMS_XMLDOM Types

Type	Description
DOMNode	Implements the DOM Node interface.
DOMNamedNodeMap	Implements the DOM NamedNodeMap interface.
DOMNodeList	Implements the DOM NodeList interface.
DOMAttr	Implements the DOM Attribute interface.
DOMCDataSection	Implements the DOM CDataSection interface.
DOMCharacterData	Implements the DOM Character Data interface.
DOMComment	Implements the DOM Comment interface.
DOMDocumentFragment	Implements the DOM DocumentFragment interface.
DOMElement	Implements the DOM Element interface.
DOMEntity	Implements the DOM Entity interface.
DOMEntityReference	Implements the DOM EntityReference interface.
DOMNotation	Implements the DOM Notation interface.
DOMProcessingInstruction	Implements the DOM Processing instruction interface.
DOMText	Implements the DOM Text interface.
DOMImplementation	Implements the DOM DOMImplementation interface.
DOMDocumentType	Implements the DOM Document Type interface.
DOMDocument	Implements the DOM Document interface.

Defined Constants of DBMS_XMLDOM

The constants listed in Table 25-2 are defined for DBMS_XMLDOM. For example, when a request such as getNodeType(myNode) is made, the returned type will be one of the following constants.

Table 25-2 Defined Constants for DBMS_XMLDDOM

Constant	Description
ELEMENT_NODE	The Node is an Element.
ATTRIBUTE_NODE	The Node is an Attribute.
TEXT_NODE	The Node is a Text node.
CDATA_SECTION_NODE	The Node is a CDataSection.
ENTITY_REFERENCE_NODE	The Node is an Entity Reference.
ENTITY_NODE	The Node is an Entity.
PROCESSING_INSTRUCTION_NODE	The Node is a Processing Instruction.
COMMENT_NODE	The Node is a Comment.
DOCUMENT_NODE	The Node is a Document.
DOCUMENT_TYPE_NODE	The Node is a Document Type Definition.
DOCUMENT_FRAGMENT_NODE	The Node is a Document fragment.
NOTATION_NODE	The Node is a Notation.

Exceptions of DBMS_XMLDOM

The exceptions listed in Table 25-3 are defined for DBMS_XMLDOM:

Table 25-3 Exceptions for DBMS_XMLDDOM

Exception	Description
INDEX_SIZE_ERR	If index or size is negative, or greater than the allowed value.
DOMSTRING_SIZE_ERR	If the specified range of text does not fit into a DOMString.
HIERARCHY_REQUEST_ERR	If any node is inserted somewhere it doesn't belong.
WRONG_DOCUMENT_ERR	If a node is used in a different document than the one that created it (that doesn't support it).
INVALID_CHARACTER_ERR	If an invalid or illegal character is specified, such as in a name. See production 2 in the XML specification for the definition of a legal character, and production 5 for the definition of a legal name character.
NO_DATA_ALLOWED_ERROR	If data is specified for a node which does not support data.
NO_MODIFICATION_ALLOWED_ERR	If an attempt is made to modify an object where modifications are not allowed.
NO_FOUND_ERR	If an attempt is made to reference a node in a context where it does not exist.
NOT_SUPPORTED_ERR	If the implementation does not support the requested type of object or operation.
INUSE_ATTRIBUTE_ERR	If an attempt is made to add an attribute that is already in use elsewhere.

Methods of DBMS_XMLDOM

DBMS_XMLDOM subprograms are divided into groups according to w3c Interfaces.

Table 25-4 Summary of Methods of DBMS_XMLDOM

Group/Method	Description
DOM Node Methods
isNull()	Tests if the node is `NULL.`
makeAttr()	Casts the node to an Attribute.
makeCDataSection()	Casts the node to a CDataSection.
makeCharacterData()	Casts the node to CharacterData.
makeComment()	Casts the node to a Comment.
makeDocumentFragment()	Casts the node to a DocumentFragment.
makeDocumentType()	Casts the node to a Document Type.
makeElement()	Casts the node to an Element.
makeEntity()	Casts the node to an Entity.
makeEntityReference()	Casts the node to an EntityReference.
makeNotation()	Casts the node to a Notation.
makeProcessingInstruction()	Casts the node to a DOMProcessingInstruction.
makeText()	Casts the node to a DOMText.
makeDocument()	Casts the node to a DOMDocument.
writeToFile()	Writes the contents of the node to a file.
writeToBuffer()	Writes the contents of the node to a buffer.
writeToClob()	Writes the contents of the node to a clob.
getNodeName()	Retrieves the Name of the Node.
getNodeValue()	Retrieves the Value of the Node.
setNodeValue()	Sets the Value of the Node.
getNodeType()	Retrieves the Type of the node.
getParentNode()	Retrieves the parent of the node.
getChildNodes()	Retrieves the children of the node.
getFirstChild()	Retrieves the first child of the node.
getLastChild()	Retrieves the last child of the node.
getPreviousSibling()	Retrieves the previous sibling of the node.
getNextSibling()	Retrieves the next sibling of the node.
getAttributes()	Retrieves the attributes of the node.
getOwnerDocument()	Retrieves the owner document of the node.
insertBefore()	Inserts a child before the reference child.
replaceChild()	Replaces the old child with a new child.
removeChild()	Removes a specified child from a node.
appendChild()	Appends a new child to the node.
hasChildNodes()	Tests if the node has child nodes.
cloneNode()	Clones the node.
DOM Named Node Map methods
isNull()	Tests if the NamedNodeMap is `NULL.`
getNamedItem()	Retrieves the item specified by the name.
setNamedItem()	Sets the item in the map specified by the name.
removeNamedItem()	Removes the item specified by name.
item()	Retrieves the item given the index in the map.
getLength()	Retrieves the number of items in the map.
DOM Node List Methods
isNull()	Tests if the Nodelist is `NULL.`
item()	Retrieves the item given the index in the nodelist.
getLength()	Retrieves the number of items in the list.
DOM Attr Methods
isNull()	Tests if the Attribute Node is `NULL.`
makeNode()	Casts the Attribute to a node.
getQualifiedName()	Retrieves the Qualified Name of the attribute.
getNamespace()	Retrieves the NS URI of the attribute.
getLocalName()	Retrieves the local name of the attribute.
getExpandedName()	Retrieves the expanded name of the attribute.
getName()	Retrieves the name of the attribute.
getSpecified()	Tests if attribute was specified in the owning element.
getValue()	Retrieves the value of the attribute.
setValue()	Sets the value of the attribute.
DOM C Data Section Methods
isNull()	Tests if the CDataSection is `NULL.`
makeNode()	Casts the CDatasection to a node.
DOM Character Data Methods
isNull()	Tests if the CharacterData is `NULL.`
makeNode()	Casts the CharacterData to a node.
getData()	Retrieves the data of the node.
setData()	Sets the data to the node.
getLength()	Retrieves the length of the data.
substringData()	Retrieves the substring of the data.
appendData()	Appends the given data to the node data.
insertData()	Inserts the data in the node at the given offSets.
deleteData()	Deletes the data from the given offSets.
replaceData()	Replaces the data from the given offSets.
DOM Comment Methods
isNull()	Tests if the comment is `NULL.`
makeNode()	Casts the Comment to a node.
DOM Implementation Methods
isNull()	Tests if the DOMImplementation node is `NULL.`
hasFeature()	Tests if the DOMImplementation implements a given feature.
DOM Document Fragment Methods
isNull()	Tests if the DocumentFragment is `NULL.`
makeNode()	Casts the Document Fragment to a node.
DOM Document Type Methods
isNull()	Tests if the Document Type is `NULL.`
makeNode()	Casts the document type to a node.
findEntity()	Finds the specified entity in the document type.
findNotation()	Finds the specified notation in the document type.
getPublicId()	Retrieves the public ID of the document type.
getSystemId()	Retrieves the system ID of the document type.
writeExternalDTDToFile()	Writes the document type definition to a file.
writeExternalDTDToBuffer()	Writes the document type definition to a buffer.
writeExternalDTDToClob()	Writes the document type definition to a clob.
getName()	Retrieves the name of the Document type.
getEntities()	Retrieves the nodemap of entities in the Document type.
getNotations()	Retrieves the nodemap of the notations in the Document type.
DOM Element Methods
isNull()	Tests if the Element is `NULL.`
makeNode()	Casts the Element to a node.
getQualifiedName()	Retrieves the qualified name of the element.
getNamespace()	Retrieves the NS URI of the element.
getLocalName()	Retrieves the local name of the element.
getExpandedName()	Retrieves the expanded name of the element.
getChildrenByTagName()	Retrieves the children of the element by tag name.
getElementsByTagName()	Retrieves the elements in the subtree by tagname.
resolveNamespacePrefix()	Resolve the prefix to a namespace uri.
getTagName()	Retrieves the Tag name of the element.
getAttribute()	Retrieves the attribute node specified by the name.
setAttribute()	Sets the attribute specified by the name.
removeAttribute()	Removes the attribute specified by the name.
getAttributeNode()	Retrieves the attribute node specified by the name.
setAttributeNode()	Sets the attribute node in the element.
removeAttributeNode()	Removes the attribute node in the element.
normalize()	Normalizes the text children of the element.
DOM Entity Methods
isNull()	Tests if the Entity is `NULL.`
makeNode()	Casts the Entity to a node.
getPublicId()	Retrieves the public Id of the entity.
getSystemId()	Retrieves the system Id of the entity.
getNotationName()	Retrieves the notation name of the entity.
DOM Entity Reference Methods
isNull()	Tests if the Entity Reference is `NULL.`
makeNode()	Casts the Entity Reference to `NULL`.
DOM Notation Methods
isNull()	Tests if the Notation is `NULL.`
makeNode()	Casts the notation to a node.
getPublicId()	Retrieves the public Id of the notation.
getSystemId()	Retrieves the system Id of the notation.
DOM Processing Instruction Methods
isNull()	Tests if the Processing Instruction is `NULL.`
makeNode()	Casts the Processing Instruction to a node.
getData()	Retrieves the data of the processing instruction.
getTarget()	Retrieves the target of the processing instruction.
setData()	Sets the data of the processing instruction.
DOM Text Methods
isNull()	Tests if the text is `NULL.`
makeNode()	Casts the text to a node.
splitText()	Splits the contents of the text node into 2 text nodes.
DOM Document Methods
isNull()	Tests if the document is `NULL`.
makeNode()	Casts the document to a node.
newDOMDocument()	Creates a new Document.
freeDocument()	Frees the document.
getVersion()	Retrieves the version of the document.
setVersion()	Sets the version of the document.
getCharset()	Retrieves the Character set of the document.
setCharset()	Sets the Character set of the document.
getStandalone()	Retrieves if the document is specified as standalone.
setStandalone()	Sets the document standalone.
writeToFile()	Writes the document to a file.
writeToBuffer()	Writes the document to a buffer.
writeToClob()	Writes the document to a clob.
writeExternalDTDToFile()	Writes the DTD of the document to a file.
writeExternalDTDToBuffer()	Writes the DTD of the document to a buffer.
writeExternalDTDToClob()	Writes the DTD of the document to a clob.
getDoctype()	Retrieves the DTD of the document.
getImplementation()	Retrieves the DOM implementation.
getDocumentElement()	Retrieves the root element of the document.
createElement()	Creates a new Element.
createDocumentFragment()	Creates a new Document Fragment.
createTextNode()	Creates a Text node.
createComment()	Creates a Comment node.
createCDATASection()	Creates a CDatasection node.
createProcessingInstruction()	Creates a Processing Instruction.
createAttribute()	Creates an Attribute.
createEntityReference()	Creates an Entity reference.
getElementsByTagName()	Retrieves the elements in the by tag name.

DOM Node Methods

isNull()

Description

Checks if the given DOMNode is NULL. Returns TRUE if it is NULL, FALSE otherwise.

Syntax

FUNCTION isNull( n DOMNode) RETURN BOOLEAN;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to check.

makeAttr()

Description

Casts a given DOMNode to a DOMAttr, and returns the DOMAttr.

Syntax

FUNCTION makeAttr( n DOMNode) RETURN DOMAttr;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

makeCDataSection()

Description

Casts a given DOMNode to a DOMCDataSection, and returns the DOMCDataSection.

Syntax

FUNCTION makeCDataSection( n DOMNode) RETURN DOMCDataSection;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

makeCharacterData()

Description

Casts a given DOMNode to a DOMCharacterData, and returns the DOMCharacterData.

Syntax

FUNCTION makeCharacterData( n DOMNode) RETURN DOMCharacterData;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

makeComment()

Description

Casts a given DOMNode to a DOMComment, and returns the DOMComment.

Syntax

FUNCTION makeComment(n DOMNode) RETURN DOMComment;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

makeDocumentFragment()

Description

Casts a given DOMNode to a DOMDocumentFragment, and returns the DOMDocumentFragment.

Syntax

FUNCTION makeDocumentFragment( n DOMNode) RETURN DOMDocumentFragment;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

makeDocumentType()

Description

Casts a given DOMNode to a DOMDocumentType and returns the DOMDocumentType.

Syntax

FUNCTION makeDocumentType(n DOMNode) RETURN DOMDocumentType;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

makeElement()

Description

Casts a given DOMNode to a DOMElement, and returns the DOMElement.

Syntax

FUNCTION makeElement(n DOMNode) RETURN DOMElement;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

makeEntity()

Description

Casts a given DOMNode to a DOMEntity, and returns the DOMEntity.

Syntax

FUNCTION makeEntity(n DOMNode) RETURN DOMEntity;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

makeEntityReference()

Description

Casts a given DOMNode to a DOMEntityReference, and returns the DOMEntityReference.

Syntax

FUNCTION makeEntityReference(n DOMNode) RETURN DOMEntityReference;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

makeNotation()

Description

Casts a given DOMNode to a DOMNotation, and returns the DOMNotation.

Syntax

FUNCTION makeNotation(n DOMNode) RETURN DOMNotation;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

makeProcessingInstruction()

Description

Casts a given DOMNode to a DOMProcessingInstruction, and returns the DOMProcessingInstruction.

Syntax

FUNCTION makeProcessingInstruction( n DOMNode)
                                    RETURN DOMProcessingInstruction;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

makeText()

Description

Casts a given DOMNode to a DOMText, and returns the DOMText.

Syntax

FUNCTION makeText(n DOMNode) RETURN DOMText;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

makeDocument()

Description

Casts a given DOMNode to a DOMDocument, and returns the DOMDocument.

Syntax

FUNCTION makeDocument(n DOMNode) RETURN DOMDocument;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to cast

writeToFile()

Description

Writes XML node to specified file. The options are given in the following table.

Syntax	Description
PROCEDURE writeToFile( n DOMNode, fileName VARCHAR2);	Writes XML node to specified file using the database character set.
PROCEDURE writeToFile( n DOMNode, fileName VARCHAR2, charset VARCHAR2);	Writes XML node to specified file using the given character set, which is passed in as a separate parameter.

Syntax

Description

PROCEDURE writeToFile(

n DOMNode,

fileName VARCHAR2);

Writes XML node to specified file using the database character set.

PROCEDURE writeToFile(

n DOMNode,

fileName VARCHAR2,

charset VARCHAR2);

Writes XML node to specified file using the given character set, which is passed in as a separate parameter.

Parameter	IN / OUT	Description
n	(IN)	DOMNode.
fileName	(IN)	File to write to.
charset	(IN)	Given character set.

writeToBuffer()

Description

Writes XML node to specified buffer. The options are given in the following table.

Syntax	Description
PROCEDURE writeToBuffer( n DOMNode, buffer IN OUT VARCHAR2);	Writes XML node to specified buffer using the database character set.
PROCEDURE writeToBuffer( n DOMNode, buffer IN OUT VARCHAR2, charset VARCHAR2);	Writes XML node to specified buffer using the given character set, which is passed in as a separate parameter.

Syntax

Description

PROCEDURE writeToBuffer(

n DOMNode,

buffer IN OUT VARCHAR2);

Writes XML node to specified buffer using the database character set.

PROCEDURE writeToBuffer(

n DOMNode,

buffer IN OUT VARCHAR2,

charset VARCHAR2);

Writes XML node to specified buffer using the given character set, which is passed in as a separate parameter.

Parameter	IN / OUT	Description
n	(IN)	DOMNode.
buffer	(IN/OUT)	Buffer to write to.
charset	(IN)	Given character set.

writeToClob()

Description

Writes XML node to specified clob. The options are given in the following table.

Syntax	Description
PROCEDURE writeToClob( n DOMNode, cl IN OUT CLOB);	Writes XML node to specified clob using the database character set.
PROCEDURE writeToClob( n DOMNode, cl IN OUT CLOB, charset VARCHAR2);	Writes XML node to specified clob using the given character set, which is passed in as a separate parameter.

Syntax

Description

PROCEDURE writeToClob(

n DOMNode,

cl IN OUT CLOB);

Writes XML node to specified clob using the database character set.

PROCEDURE writeToClob(

n DOMNode,

cl IN OUT CLOB,

charset VARCHAR2);

Writes XML node to specified clob using the given character set, which is passed in as a separate parameter.

Parameter	IN / OUT	Description
n	(IN)	DOMNode.
cl	(IN/OUT)	CLOB to write to.
charset	(IN)	Given character set.

getNodeName()

Description

Get the name of the node depending on its type

Syntax

FUNCTION getNodeName(n DOMNode) RETURN VARCHAR2;

Parameter	IN / OUT	Description
n	IN	DOMNode

getNodeValue()

Description

Get the value of this node, depending on its type.

Syntax

FUNCTION getNodeValue(n DOMNode) RETURN VARCHAR2;

Parameter	IN / OUT	Description
n	IN	DOMNode.

setNodeValue()

Description

Sets the value of this node, depending on its type. When it is defined to be null, setting it has no effect.

Syntax

PROCEDURE setNodeValue( n DOMNode,
                        nodeValue IN VARCHAR2);

Parameter	IN / OUT	Description
n	IN	DOMNode.
nodeValue	IN	The value to which node is set.

getNodeType()

Description

Retrieves a code representing the type of the underlying object.

Syntax

FUNCTION getNodeType(n DOMNode) RETURN NUMBER;

Parameter	IN / OUT	Description
n

25 PL/SQL DOM API for XMLType

DBMS_XMLDOM Package

Description of DBMS_XMLDOM

Types of DBMS_XMLDOM

Table 25-1 DBMS_XMLDOM Types

Defined Constants of DBMS_XMLDOM

Table 25-2 Defined Constants for DBMS_XMLDDOM

Exceptions of DBMS_XMLDOM

Table 25-3 Exceptions for DBMS_XMLDDOM

Methods of DBMS_XMLDOM

Table 25-4 Summary of Methods of DBMS_XMLDOM

DOM Node Methods

isNull()

Description

Syntax

makeAttr()

Description

Syntax

makeCDataSection()

Description

Syntax

makeCharacterData()

Description

Syntax

makeComment()

Description

Syntax

makeDocumentFragment()

Description

Syntax

makeDocumentType()

Description

Syntax

makeElement()

Description

Syntax

makeEntity()

Description

Syntax

makeEntityReference()

Description

Syntax

makeNotation()

Description

Syntax

makeProcessingInstruction()

Description

Syntax

makeText()

Description

Syntax

makeDocument()

Description

Syntax

writeToFile()

Description

writeToBuffer()

Description

writeToClob()

Description

getNodeName()

Description

Syntax

getNodeValue()

Description

Syntax

setNodeValue()

Description

Syntax

getNodeType()

Description

Syntax

25
PL/SQL DOM API for XMLType