16
XML Parser for C++

This chapter contains the following sections:

• Class Attr

• Class CDATASection

• Class Comment

• Class Document

• Class DocumentType

• Class DOMImplementation

• Class Element

• Class Entity

• Class EntityReference

• Class NamedNodeMap

• Class Node

• Class NodeList

• Class Notation

• Class ProcessingInstruction

• Class Text

• Class XMLParser

• C++ SAX API

  See Also: Oracle Application Developer's Guide - XML

---

Class Attr

Accessing the name and value of a single document node attribute.

Table 16-1 Summary of Methods of Attr

Method	Description
getName()	Returns name of an attribute.
getValue()	Returns definition of an attribute.
getSpecified()	Returns attribute's "specified" flag value.
setValue()	Sets an attribute's value.

---

getName()

Returns name of an attribute.

Syntax

String getName()

---

getValue()

Returns the definition of an attribute.

Syntax

String getValue()

---

getSpecified()

Returns value of attribute's "specified" flag. The DOM specifies"If this attribute was explicitly given a value in the original document, this is true; otherwise, it is false. Note that the implementation is in charge of this attribute, not the user. If the user changes the value of the attribute (even if it ends up having the same value as the default value) then the specified flag is automatically flipped to true. To re-specify the attribute as the default value from the DTD, the user must delete the attribute. The implementation will then make a new attribute available with specified set to false and the default value (if one exists)."

Syntax

boolean getSpecified()

---

setValue()

Sets an attribute's "value".

Syntax

void setValue(String value)

Parameter	Description
value	Attribute's new value

---

Class CDATASection

This class implements the CDATA node type, a subclass of Text.

---

Class Comment

This class implements the COMMENT node type, a subclass of CharacterData.

---

Class Document

This class contains methods for creating and retrieving nodes.

Table 16-2  Summary of Methods of Document

Method	Description
createAttribute()	Create an ATTRIBUTE node.
createCDATASection()	Create a CDATA node.
createComment()	Create a COMMENT node.
createDocumentFragment()	Create a DOCUMENT_FRAGMENT node.
createElement()	Create an ELEMENT node.
createEntityReference()	Create an ENTITY_REFERENCE node.
createProcessingInstruction()	Create a PROCESSING_INSTRUCTION node.
createTextNode()	Create a TEXT node.
getElementsByTagName()	Select nodes based on tag name.
getImplementation()	Return DTD for document.

---

createAttribute()

Create a new attribute node. Use setValue to set its value. Returns a pointer to node.

Syntax

Attr* createAttribute(String name)

Parameter	Description
name	name of attribute

---

createCDATASection()

Create a new CDATA node with the given contents. Returns a pointer to node.

Syntax

Attr* createCDATASection(String name)

Parameter	Description
data	contents of node

---

createComment()

Create a new comment node with the given contents. Returns a pointer to node.

Syntax

Comment* createComment(String data)

Parameter	Description
data	contents of node

---

createDocumentFragment()

Create a new document fragment node. Returns a pointer to created node.

Syntax

DocumentFragment* createDocumentFragment()

---

createElement()

Create a new element node with the given (tag) name. Returns a pointer to node.

Syntax

Element* createElement(String tagName)

Parameter	Description
tagName	element's tag name

---

createEntityReference()

Create a new entity reference node. Returns a pointer to created node.

Syntax

EntityReference* createEntityReference(String name)

Parameter	Description
name	name of entity to reference

---

createProcessingInstruction()

Create a new processing instruction node. Returns a pointer to created node.

Syntax

ProcessingInstruction* createProcessingInstruction(String target, String data)

Parameter	Description
target	target part of PI
data	data for node

---

createTextNode()

Create a new TEXT node. Returns a pointer to created node.

Syntax

Text* createTextNode(String data)

Parameter	Description
data	data for node

---

getElementsByTagName()

Returns a NodeList of all the Elements with a given tag name in the order in which they would be encountered in a preorder traversal of the Document tree. The special value "*" matches all tags. Returns list of matches, NULL if none.

Syntax

NodeList* getElementsByTagName(String tagname)

Parameter	Description
tagname	tag name to select

---

getImplementation()

Returns the DOMImplementation structure, currently useless. Perhaps it will be used in later DOM versions. Returns pointer to structure.

Syntax

DOMImplementation* getImplementation()

---

Class DocumentType

This class contains methods for accessing information about the Document Type Definition (DTD) of a document.

Table 16-3  Summary of Methods of DocumentType

Method	Description
getName()	Returns name of DTD.
getEntities()	Returns map of DTD's entities.
getNotations()	Returns map of DTD's notations.

---

getName()

Return name of DTD.

Syntax

String getName()

---

getEntities()

Returns map of DTD's (general) entities.

Syntax

NamedNodeMap* getEntities()

---

getNotations()

Returns map of DTD's notations.

Syntax

NamedNodeMap* getNotations()

---

Class DOMImplementation

This class contains methods relating to the specific DOM implementation supported by the parser.

---

hasFeature()

Test if the DOM implementation implements a specific feature. Returns TRUE if the feature is supported.

Syntax

boolean hasFeature(DOMString feature, DOMString version)

Parameter	Description
feature	The package name of the feature to test. In Level 1, the legal values are "HTML" and "XML" (case-insensitive)
version	This is the version number of the package name to test. In Level 1, this is the string "1.0". If the version is not specified, supporting any version of the feature will cause the method to return true.

---

Class Element

This class contains methods pertaining to element nodes.

Table 16-4  Summary of Methods of Element

Method	Description
getTagName()	Return the node's tag name
getAttribute()	Select an attribute given its name
setAttribute()	Create a new attribute given its name and value
removeAttribute()	Remove an attribute given its name
getAttributeNode()	Remove an attribute given its name
setAttributeNode()	Add a new attribute node
removeAttributeNode()	Remove an attribute node
getElementsByTagName()	Return a list of element nodes with the given tag name
normalize()	Normalize an element (merge adjacent text nodes)

---

getTagName()

Return the tag name of the element. The DOM says: "...even though there is a generic nodeName attribute on the Node interface, there is still a tagName attribute on the Element interface; these two attributes must contain the same value, but the Working Group considers it worthwhile to support both, given the different constituencies the DOM API must satisfy.

Syntax

String getTagName()

---

getAttribute()

Return "value" (definition) of named attribute

Syntax

String getAttribute(String name)

Parameter	Description
name	name of attribute

---

setAttribute()

Create a new attribute.

Syntax

Attr* setAttribute(String name, String value)

Parameter	Description
name	name of new attribute
value	value of new attribute

---

removeAttribute()

Removes the named attribute

Syntax

void removeAttribute(String name)

Parameter	Description
name	name of attribute to remove

---

getAttributeNode()

Return pointer to named attribute.

Syntax

Attr* getAttributeNode(DOMString name)

Parameter	Description
naem	name of attribute

---

setAttributeNode()

Set (add) new attribute. Returns TRUE on success.

Syntax

boolean setAttributeNode(Attr* newAttr, Attr** oldAttr)

Parameter	Description
newAttr	pointer to new attribute
oldAttr	returned pointer to replaced attribute

---

removeAttributeNode()

Remove the named attribute

Syntax

Attr* removeAttributeNode(Attr* oldAttr)

Parameter	Description
oldAttr	attribute to remove

---

getElementsByTagName()

Create a list of matching elements.

Syntax

NodeList* getElementsByTagName(DOMString name)

Parameter	Description
name	tagname to match, "*" for all

---

normalize()

Normalize an element, i.e. merge all adjacent TEXT nodes.

Syntax

void normalize(void)

---

Class Entity

This class implements the ENTITY node type, a subclass of Node.

Table 16-5  Summary of Methods of Entity

Method	Description
getNotationName()	Return entity's NDATA (notation name)
getPublicId()	Return entity's public ID
getSystemId()	Return entity's system ID

---

getNotationName()

Return an entity node's notation name NDATA.

Syntax

String* getNotationName()

---

getPublicId()

Return an entity node's public ID.

Syntax

String getPublicId()

---

getSystemId()

Return an entity node's system ID.

Syntax

String getSystemId()

---

Class EntityReference

This class implements the ENTITY_REFERENCE node type, a subclass of Node.

---

Class NamedNodeMap

This class contains methods for accessing the number of nodes in a node map and fetching individual nodes.

Table 16-6  Summary of Methods of NamedNodeMap

Method	Description
item()	Return nth node in map.
getLength()	Return number of nodes in map
getNamedItem()	Select a node by name
setNamedItem()	Set a node into the map
removeNamedItem()	Remove the named node from map

---

item()

Return n^th node in node map.

Syntax

Node* item(size_t index)

Parameter	Description
index	zero-based node number

---

getLength()

Return number of nodes in map.

Syntax

size_t getLength()

---

getNamedItem()

Selects the node with the given name from the map.

Syntax

Node* getNamedItem(String name)

Parameter	Description
name	name of node to select

---

setNamedItem()

Adds a node to the map replacing any node that already exists with the same name.

Syntax

boolean setNamedItem(Node *node, Node **old)

Parameter	Description
node	Name of node to add
old	Pointer to replaced node, NULL if node is new

---

removeNamedItem()

Removes the node with the given name from the node map.

Syntax

Node* removeNamedItem(String name)

Parameter	Description
name	name of node to remove

---

Class Node

This class contains methods for details about a document node.

Table 16-7  Summary of Methods of Node

Method	Description
appendChild()	Append a new child to the end of the current node's list of children
cloneNode()	Clone an existing node and optionally all its children
getAttributes()	Return structure contains all defined node attributes
getChildNode()	Return specific indexed child of given node
getChildNodes()	Return structure contains all child nodes of given node
getFirstChild()	Return first child of given node
getLastChild()	Return last child of given node
getLocal()	Returns the local name of the node
getNamespace()	Return a node's namespace
getNextSibling()	Return a node's next sibling
getName()	Return name of node
getType()	Return numeric type-code of node
getValue()	Return "value" (data) of node
getOwnerDocument()	Return document node which contains a node
getParentNode()	Return parent node of given node
getPrefix()	Returns the namespace prefix for the node
getPreviousSibling()	Returns the previous sibling of the current node
getQualifiedName()	Return namespace qualified node of given node
hasAttributes()	Determine if node has any defined attributes
hasChildNodes()	Determine if node has children
insertBefore()	Insert new child node into a node's list of children
numChildNodes()	Return count of number of child nodes.
removeChild()	Removes a child from the current node.
replaceChild()	Replace a child node with another
setValue()	Sets a node's value (data)

---

appendChild()

Append a new child to the current node's list of children.

Syntax

Node* appendChild(Node *newChild)

Parameter	Description
newChild	new child node

---

cloneNode()

Returns a duplicate of this node, i.e., 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

Node* cloneNode(boolean deep)

Parameter	Description
deep	recursion flag

---

getAttributes()

Return structure of all attributes for node

Syntax

NamedNodeMap* getAttributes()

---

getChildNode()

Return one of the node's children.

Syntax

Node* getChildNode(uword index)

Parameter	Description
index	child number, starting at 0

---

getChildNodes()

Return node's children.

Syntax

NodeList* getChildNodes()

---

getFirstChild()

Return the node's first child.

Syntax

Node* getFirstChild()

---

getLastChild()

Return the node's last child.

Syntax

Node* getLastChild()

---

getLocal()

Return the node's local name.

Syntax

String getLocal()

---

getNamespace()

Return the node's namespace.

Syntax

String getNamespace()

---

getNextSibling()

Returns the next sibling of the node.

Syntax

Node* getNextSibling()

---

getName()

Return name of node, or NULL if the node has no name.

Syntax

String getName()

---

getType()

Return numeric type-code for node. These include ELEMENT_NODE, ATTRIBUTE_NODE, TEXT_NODE, CDATA_SECTION_NODE, ENTITY_REFERENCE_NODE, ENTITY_NODE, PROCESSING_INSTRUCTION_NODE, COMMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, DOCUMENT_FRAGMENT_NODE, NOTATION_NODE.

Syntax

short getType()

---

getValue()

Return "value" (data) of node, or NULL if the node has no value.

Syntax

String getValue()

---

getOwnerDocument()

Return document node which contains the current node.

Syntax

Document* getOwnerDocument()

---

getParentNode()

Return node's parent.

Syntax

Node* getParentNode()

---

getPrefix()

Return the namespace prefix of node.

Syntax

String getPrefix()

---

getPreviousSibling()

Returns the previous sibling of the node.

Syntax

Node* getPreviousSibling()

---

getQualifiedName()

Return the fully qualified (namespace) name of node.

Syntax

String getQualifiedName()

---

hasAttributes()

Determine if node has any defined attributes.

Syntax

boolean hasAttributes()

---

hasChildNodes()

Determine if node has any children.

Syntax

boolean hasChildNodes()

---

insertBefore()

Insert a new child node before the reference node into the list of children nodes.

Syntax

Node* insertBefore(Node *newChild, Node *refChild)

Parameter	Description
newChild	new node to insert
refChild	reference node; new node comes before

---

numChildNodes()

Return count of node's children.

Syntax

uword numChildNodes()

---

removeChild()

Removes a child node from the current node's list of children.

Syntax

Node* removeChild(Node *oldChild)

Parameter	Description
oldChild	old node being removed

---

replaceChild()

Replaces one node in the list of children with another.

Syntax

Node* replaceChild(Node *newChild, Node *oldChild)

Parameter	Description
newChild	new replacement node
oldChild	old node being replaced

---

setValue()

Sets a node's "value" (data)

Syntax

void setValue(String data)

Parameter	Description
data	New data for node

---

Class NodeList

This class contains methods for extracting nodes from a NodeList

Table 16-8  Summary of Methods of NodeList

Method	Description
item()	Return nth node in list.
getLength()	Return number of nodes in list

---

item()

Return nth node in node list.

Syntax

Node* item(size_t index)

Parameter	Description
index	zero-based node number

---

getLength()

Return number of nodes in list.

Syntax

size_t getLength()

---

Class Notation

This class implements the NOTATION node type, a subclass of Node.

Table 16-9  Summary of Methods of Notation

Method	Description
getData()	Return notation's data
getTarget()	Return notation's target
setData()	Set notation's data

---

getData()

Return a notation's data.

Syntax

String getData()

---

getTarget()

Return a notation's target.

Syntax

String getTarget()

---

setData()

Set a notation's data

Syntax

void setData(String data)

Parameter	Description
data	new data

---

Class ProcessingInstruction

Implements the PROCESSING_INSTRUCTION node type, a subclass of Node.

Table 16-10  Summary of Methods of ProcessingInstruction

Method	Description
getData()	Return the PI's data.
getTarget()	Return the PI's target.
setData()	Set the PI's data.

---

getData()

Return data for a processing instruction.

Syntax

String getData()

---

getTarget()

Return a processing instruction's target value.

Syntax

String getTarget()

---

setData()

Set the data for a processing instruction.

Syntax

void setData(String data)

Parameter	Description
data	PI's new data

---

Class Text

Accesses and modifies the data associated with text nodes (subclasses CharacterData).

---

splitText()

Split a text node in two. The original node retains its data up to the split point, and the remaining data is turned into a new text node which follows. Returns the pointer to new text node.

Syntax

Text* splitText(unsigned long offset)

Parameter	Description
offset	split point

---

Class XMLParser

This class contains top-level methods for invoking the parser and returning high-level information about a document.

Table 16-11  Summary of Methods of XMLParser

Method	Description
xmlinit()	Initialize XML parser
xmlterm()	Terminate XML parser
xmlparse()	Parse a document from a file
xmlparseBuffer()	Parse a document from a buffer
getContent()	Returns the content model for an element
getModifier()	Returns the modifier for a content-model node
getDocument()	Returns the root node of a parsed document
getDocumentElement()	Returns the root element of a parsed document
getDocType()	Returns the document type string
isStandalone()	Returns the value of the standalone flag
isSingleChar()	Determine document encoding.
getEncoding()	Return name of document's character encoding.

---

xmlinit()

Initialize XML parser. Returns error code, 0 on success.

Syntax

uword xmlinit(oratext *encoding,
              void (*msghdlr)(void *msgctx, oratext *msg, ub4 errcode),
              void *msgctx, lpxsaxcb *saxcb, void *saxcbctx, oratext *lang)

Parameter	Description
encoding	Input file's encoding, default UTF8
msghdlr	Error message callback
msgctx	User-defined context pointer passed to msghdlr
saxcb	SAX callback structure (iff using SAX)
saxcbctx	User-defined SAX context structure passed to SAX callback functions
lang	Language for error message (not used)

---

xmlterm()

Terminate XML parser, tear down, free memory, and so on.

Syntax

void xmlterm()

---

xmlparse()

Parses a document. Returns error code, 0 on success.

Syntax

uword xmlparse(oratext *doc, oratext *encoding, ub4 flags)

Parameter	Description
doc	document path
encoding	document's encoding
flags	Mask of flag bits: XML_FLAG_VALIDATE -- Validate document against DTD XML_FLAG_DISCARD_WHITESPACE -- Discard ignorable whitespace

---

xmlparseBuffer()

Parses a document. Returns error code, 0 on success.

Syntax

uword xmlparseBuffer(oratext *buffer, size_t len, oratext *encoding, ub4 flags)

Parameter	Description
buffer	buffer containing document to parse
len	length of document
encoding	document's encoding
flags	Mask of flag bits XML_FLAG_VALIDATE -- Validate document against DTD XML_FLAG_DISCARD_WHITESPACE -- Discard ignorable whitespace

---

getContent()

Returns the content model for a node. Content model nodes are Nodes and can be traversed and examined with the same functions as the parsed document.

Syntax

Node* getContent(Node *node)

Parameter	Description
node	content model node whose modifer to return

---

getModifier()

Returns the modifier for a content model node. The modifier is one of XMLCPMOD_NONE (no modifier), XMLCPMOD_OPT ('?', optional), XMLCPMOD_0MORE ('*', zero or more), or XMLCPMOD_1MORE ('+', one or more).

Syntax

xmlcpmod getContent(Node *node)

Parameter	Description
node	content model node whose modifer to return

---

getDocument()

After a document has been successfully parsed, Returns a pointer to the root node of the document. Compare with getDocumentElement which Returns the root element node. Pointer to root node of document.

Syntax

Node* getDocument()

---

getDocumentElement()

Returns a pointer to the root element (node) of a parsed document.

Syntax

Element* getDocumentElement()

Returns

Element* -- Pointer to root element (node) of document

---

getDocType()

Returns a pointer to a "DocType" structure which describes the DTD.

Syntax

DocumentType* getDocType()

---

isStandalone()

Returns TRUE if the document is specified as standalone on the <?xml?> line, FALSE otherwise. Value of standalone flag.

Syntax

boolean isStandalone()

---

isSingleChar()

Returns a flag which specifies whether the current document is encoded as single-byte characters, ASCII, or multi-byte characters, UTF-8. Compare to getEncoding, which Returns the actual name of the document's encoding.

Syntax

boolean isSingleChar()

---

getEncoding()

Returns the name of the current document's character encoding scheme, such as ASCII, UTF8, and so on. Compare to isSingleChar which just returns a boolean flag saying whether the current encoding is single or multi-byte.

Syntax

String getEncoding()

---

C++ SAX API

The SAX API is based on callbacks. Instead of the entire document being parsed and turned into a data structure which may be referenced (by the DOM interface), the SAX interface is serial. As the document is processed, appropriate SAX user callback functions are invoked. Each callback function returns an error code, zero meaning success, any non-zero value meaning failure. If a non-zero code is returned, document processing is stopped. To use SAX, an xmlsaxcb structure is initialized with function pointers and passed to the xmlinit() call. A pointer to a user-defined context structure may also be included; that context pointer will be passed to each SAX function.

SAX callback structure

typedef struct
{
   sword (*)(void *ctx);
   sword (*)(void *ctx);
   sword (*)(void *ctx, const oratext *name, struct xmlarray *attrs);
   sword (*)(void *ctx, const oratext *name);
   sword (*)(void *ctx, const oratext *ch, size_t len);
   sword (*)(void *ctx, const oratext *ch, size_t len);
   sword (*)(void *ctx, const oratext *target, const oratext *data);
   sword (*)(void *ctx, const oratext *name,
                         const oratext *publicId, const oratext *systemId);
   sword (*)(void *ctx, const oratext *name, const oratext *publicId,
                               const oratext *systemId, const oratext 
*notationName);
   sword (*)(void *ctx, const oratext *qname,
                           const oratext *local, const oratext *namespace);
} xmlsaxcb;

Table 16-12  Summary of Methods C++ SAX

Method	Description
startDocument()	Starts document processing.
endDocument()	Ends document processing.
startElement()	Starts processing of each new element.
endElement()	Ends processing of each new element.
characters()	Processes pieces of literal text.
IgnorableWhitespace()	Processes piece of non-significant whitespace.
processingInstruction()	Processes Processing Instructions.
notationDecl()	Processes Notations.
unparsedEntityDecl()	Parses Entities.
nsStartElement()	Starts document processing for documents using explicit namespace.

---

startDocument()

Called once when document processing is first starting. Returns error code, 0 for success, non-0 for error.

Syntax

sword startDocument(void *ctx)

Parameter	Description
ctx	User-defined context as passed to initialize()

---

endDocument()

Called once when document processing is finished. Returns error code, 0 for success, non-0 for error.

Syntax

sword endDocument(void *ctx)

Parameter	Description
ctx	User-defined context as passed to initialize()

---

startElement()

Called once for each new document element. Returns error code, 0 for success, non-0 for error.

Syntax

sword startElement(void *ctx, const oratext *name, struct xmlarray *attrs)

Parameter	Description
ctx	User-defined context as passed to initialize()
name	name of node
attrs	array of node's attributes

---

endElement()

Called once when each document element closes. Returns error code, 0 for success, non-0 for error.

Syntax

sword endElement(void *ctx, const oratext *name)

Parameter	Description
ctx	User-defined context as passed to initialize()
name	name of node

---

characters()

Called for each piece of literal text. Error code, 0 for success, non-0 for error.

Syntax

sword characters(void *ctx, const oratext *ch, size_t len)

Parameter	Description
ctx	User-defined context as passed to initialize()
ch	pointer to text
len	number of character in text

---

IgnorableWhitespace()

Called for each piece of ignorable (non-significant) whitespace. Returns error code, 0 for success, non-0 for error.

Syntax

sword ignorableWhitespace(void *ctx, const oratext *ch, size_t len)

Parameter	Description
ctx	User-defined context as passed to initialize()
ch	pointer to whitespace text
len	number of characters of whitespace

---

processingInstruction()

Called once for each PI (Processing Instruction). Returns error code, 0 for success, non-0 for error.

Syntax

sword processingInstruction(void *ctx, const oratext *target,
                            const oratext *data)

Parameter	Description
ctx	User-defined context as passed to initialize()
target	PI target
data	PI data

---

notationDecl()

Called once for each NOTATION. Returns error code, 0 for success, non-0 for error.

Syntax

sword notationDecl(void *ctx, const oratext *name,
                   const oratext *publicId, const oratext *systemId)

Parameter	Description
ctx	User-defined context as passed to initialize()
name	name of notation
publicId	Public ID
systemId	System ID

---

unparsedEntityDecl()

Called once for each unparsed entity declaration. Returns error code, 0 for success, non-0 for error.

Syntax

sword unparsedEntityDecl( void *ctx, const oratext *name, 
                          const oratext *publicId,
                          const oratext *systemId,
                          const oratext *notationName)

Parameter	Description
ctx	User-defined context as passed to initialize()
name	name of entity
publicId	Public ID
systemId	System ID
notationName	notation name

---

nsStartElement()

Namespace variant of startElement: called once for each new document element, when the element uses an explicit namespace. Returns error code, 0 for success, non-0 for error.

Syntax

sword startElement(void *ctx, const oratext *qname,
                   const oratext *local, const oratext *namespace)

Parameter	Description
ctx	User-defined context as passed to initialize()
qname	qualified namespace
local	umm
namespace	yes, well