A Mapping of APIs used before Oracle Database 10g Release 1

This chapter maps the XML C APIs available in Oracle9i release to the Unified XML C APIs available in this release of Oracle Database.

The chapter contains these topics:

C Package Changes
Initializing and Parsing Sequence Changes
Datatype Mapping between oraxml and xml Packages
Method Mapping between oraxml and xml Packages

C Package Changes

Pre-existing C APIs were available through the oraxml package. It had the following characteristics:

Specification is limited to a one-to-one mapping between the xml context (xmlctx) and an xml document. Only one document can be accessed by DOM at any one time, however the data of multiple documents can be concurrent.
The APIs are not always consistent, and don't always follow the declarations of the xmlctx.

In contrast, the new unified C APIs solve these problems:

Multiple independent documents share the xmlctx.
All APIs conform to the declarations of the xmlctx.
Each document can be accessed simultaneously by DOM until explicitly destroyed by an XmlDestroy() call.

CAXML6418

Initializing and Parsing Sequence Changes

The initialization and parsing of documents has changed in the Unified C API.

CAXML6419Example A-1 Initializing and Parsing Sequence for the Pre-Unified C API, One Document at a Time

The following pseudo-code demonstrates how to initialize and parse documents, one at a time, using the old C APIs. Contrast this with Example A-2.

#include <oraxml.h>
uword err;
xmlctx *ctx = xmlinit(&err, options);
for (;;)
{
   err = xmlparse(ctx, URI, options);
   ...
   /* DOM operations */
   ...
   /* recycle memory from document */
   xmlclean(ctx);
}
xmlterm(ctx);

CAXML6420Example A-2 Initializing and Parsing Sequence for the Unified C API, One Document at a Time

The following pseudo-code demonstrates how to initialize and parse documents, one at a time, using the new C APIs. Contrast this with Example A-1.

#include <xml.h>
xmlerr err;
xmldocnode *doc;
xmlctx *xctx = XmlCreate(&err, options, NULL);
for (;;)
{
   doc = XmlLoadDom(xctx, &err, "URI", URI, NULL);
   ...
   /* DOM operations */
   ...
   XmlFreeDocument(xctx, doc);
}
XmlDestroy(xctx);

CAXML6421Example A-3 Initializing and Parsing Sequence for the Pre-Unified C API, Multiple Documents and Simultaneous DOM Access

The following pseudo-code demonstrates how to initialize and parse multiple documents with simultaneous DOM access using the old C APIs. Contrast this with Example A-4.

xmlctx *ctx1 = xmlinitenc(&err, options);
xmlctx *ctx2 = xmlinitenc(&err, options);
err = xmlparse(ctx1, URI_1, options);
err = xmlparse(ctx2, URI_2, options);
...
/* DOM operations for both documents */
...
xmlterm(ctx1);
xmlterm(ctx2);

CAXML6422Example A-4 Initializing and Parsing Sequence for the Unified C API, Multiple Documents and Simultaneous DOM Access

The following pseudo-code example demonstrates how to initialize and parse multiple documents with simultaneous DOM access using the new C APIs. Contrast this with Example A-3.

xmldocnode *doc1;
xmldocnode *doc2;
xmlctx *xctx = XmlCreate(&err, options, NULL);
doc1 = XmlLoadDom(xctx, &err, "URI", URI_1, NULL);
doc2 = XmlLoadDom(xctx, &err, "URI", URI_2, NULL);
...
/* DOM operations for both documents*/
...
XmlFreeDocument(xctx, doc1);
XmlFreeDocument(xctx, doc2);
...
XmlDestroy(xctx);

CAXML6423

Datatype Mapping between oraxml and xml Packages

Table A-1 outlines the changes made to datatypes for the new C API.

CAXML6424 Table A-1 Datatypes Supported by oraxml Package versus xml Package

oraxml Supported Datatype	xml Supported Datatype
uword	xmlerr
xmlacctype	xmlurlacc
xmlattrnode	xmlattrnode
xmlcdatanode	xmlcdatanode
xmlcommentnode	xmlcommentnode
xmlctx	xmlctx
xmldocnode	xmldocnode
xmldomimp	Obsolete.Use`xmlctx`.
xmldtdnode	xmldtdnode
xmlelemnode	xmlelemnode
xmlentnode	xmlentnode
xmlentrefnode	xmlentrefnode
xmlflags	ub4
xmlfragnode	xmlfragnode
xmlihdl	xmlurlhdl
xmlmemcb	Use individual function pointers.
xmlnode	xmlnode
xmlnodes	xmlnodelist, xmlnamedmap
xmlnotenode	xmlnotenode
xmlntype	xmlnodetype
xmlpflags	ub4
xmlpinode	xmlpinode
xmlsaxcb	xmlsaxcb
xmlstream	xmlistream, xmliostream
xmltextnode	xmltextnode
xpctx	xpctx
xpexpr	xpexpr
xpnset	Obsolete.Use`XmlXPathGetObjectNSetNum()`and `XmlXPathGetObjectNSetNode()`.
xpnsetele	Obsolete.Use`XmlXPathGetObjectNSetNum()`and `XmlXPathGetObjectNSetNode()`.
xpobj	xpobj
xpobjtyp	xmlxslobjtype
xslctx	xslctx
xsloutputmethod	xmlxsloutputmethod

CAXML6425

Method Mapping between oraxml and xml Packages

Table A-2 outlines the changes made to the methods of the new C API.

CAXML6426 Table A-2 Methods of the oraxml Package versus the xml Package

Package oraxml Method	Package xml Method(s)
appendChild()	XmlDomAppendChild()
appendData()	XmlDomAppendData()
cloneNode()	XmlDomCloneNode()
createAttribute()	XmlDomCreateAttr()
createAttributeNS()	XmlDomCreateAttrNS()
createCDATASection()	XmlDomCreateCDATA()
createComment()	XmlDomCreateComment()
createDocument()	XmlCreateDocument()
createDocumentFragment()	XmlDomCreateFragment()
createDocumentNS()	XmlCreateDocument()
createDocumentType()	XmlCreateDTD()
createElement()	XmlDomCreateElem()
createElementNS()	XmlDomCreateElemNS()
createEntityReference()	XmlDomCreateEntityRef()
createProcessingInstruction()	XmlDomCreatePI()
createTextNode()	XmlDomCreateText()
deleteData()	XmlDomDeleteData()
freeElements()	XmlDomFreeNodeList()
getAttribute()	XmlDomGetAttr()
getAttributeIndex()	XmlDomGetAttrs(), XmlDomGetNodeMapItem()
getAttributeNode()	XmlDomGetAttrNode()
getAttributes()	XmlDomGetAttrs()
getAttrLocal()	XmlDomGetAttrLocal(), XmlDomGetAttrLocalLen()
getAttrName()	XmlDomGetAttrName()
getAttrNamespace()	XmlDomGetAttrURI(), XmlDomGetAttrURILen()
getAttrPrefix()	XmlDomGetAttrPrefix()
getAttrQualifiedName()	XmlDomGetAttrName()
getAttrSpecified()	XmlDomGetAttrSpecified()
getAttrValue()	XmlDomGetAttrValue()
getCharData()	XmlDomGetCharData()
getChildNode()	XmlDomGetChildNode()
getChildNodes()	XmlDomGetChildNodes()
getContentModel()	XmlDomGetContentModel()
getDocType()	XmlDomGetDTD()
getDocTypeEntities()	XmlDomGetDTDEntities()
getDocTypeName()	XmlDomGetDTDName()
getDocTypeNotations()	XmlDomGetDTDNotations()
getDocument()	Obsolete; document returned by `XmlLoadDomxxx()`calls
getDocumentElement()	XmlDomGetDoctElem()
getElementByID()	XmlDomGetElemByID()
getElementsByTagName()	XmlDomGetElemsByTag()
getElementsByTagNameNS()	XmlDomGetElemsByTag()
getEncoding()	XmlDomGetEncoding()
getEntityNotation()	XmlDomGetEntityNotation()
getEntityPubID()	XmlDomGetEntityPubID()
getEntitySysID()	XmlDomGetEntitySysID()
getFirstChild()	XmlDomGetFirstChild()
getImplementation()	Obsolete; use `xmlctx` instead of `DOMImplementation`
getLastChild()	XmlDomGetLastChild()
getNamedItem()	XmlDomGetNamedItem()
getNextSibling()	XmlDomGetNextSibling()
getNodeLocal()	XmlDomGetNodeLocal(), XmlDomGetNodeLocalLen()
getNodeMapLength()	XmlDomGetNodeMapLength()
getNodeName()	XmlDomGetNodeName(), XmlDomGetNodeNameLen()
getNodeNameSpace()	XmlDomGetNodeURI(), XmlDomGetNodeURILen()
getNodePrefix()	XmlDomGetNodePrefix()
getNodeQualifiedName()	XmlDomGetNodedName(), XmlDomGetNodedNameLen()
getNodeType()	XmlDomGetNodeType()
getNodeValue()	XmlDomGetNodeValue(), XmlDomGetNodeValueLen()
getNotationPubID()	XmlDomGetNotationPubID()
getNotationSysID()	XmlDomGetNotationSysID()
getOwnerDocument()	XmlDomGetOwnerDocument()
getParentNode()	XmlDomGetParentNode()
getPIData()	XmlDomGetPIData()
getPITarget()	XmlDomGetPITarget()
getPreviousSibling()	XmlDomGetPrevSibling()
getTagName()	XmlDomGetTagName()
hasAttributes()	XmlDomHasAttrs()
hasChildNodes()	XmlDomHasChildNodes()
hasFeature()	XmlHasFeature()
importNode()	XmlDomImportNode()
insertBefore()	XmlDomInsertBefore()
insertData()	XmlDomInsertData()
isSingleChar()	XmlIsSimple()
isStandalone()	XmlDomGetDecl()
isUnicode()	XmlDomIsUnicode()
nodeValid()	XmlDomValidate()
normalize()	XmlDomNormalize()
numAttributes()	XmlDomNumAttrs()
numChildNodes()	XmlDomNumChildNodes()
prefixToURI()	XmlDomPrefixToURI()
printBuffer()	XmlSaveDomBuffer()
printBufferEnc()	XmlSaveDomBuffer()
printCallback()	XmlSaveDomStream()
printCallbackEnc()	XmlSaveDomStream()
printSize()	XmlSaveDomSize()
printSizeEnc()	XmlSaveDomSize()
printStream()	XmlSaveDomStdio()
printStreamEnc()	XmlSaveDomStdio()
removeAttribute()	XmlDomRemoveAttr()
removeAttributeNode()	XmlDomRemoveAttrNode()
removeChild()	XmlDomRemoveChild()
removeNamedItem()	XmlDomRemoveNamedItem()
replaceChild()	XmlDomReplaceChild()
replaceData()	XmlDomReplaceData()
saveString2()	XmlDomSaveString2()
saveString()	XmlDomSaveString()
setAttribute()	XmlDomSetAttr()
setAttributeNode()	XmlDomSetAttrNode()
setAttrValue()	XmlDomSetAttrValue()
setCharData()	XmlDomSetCharData()
setNamedItem()	XmlDomSetNamedItem()
setNodeValue()	XmlDomSetNodeValue(), XmlDomSetNodeValueLen()
setPIData()	XmlDomSetPIData()
splitText()	XmlDomSplitText()
substringData()	XmlDomSubstringData()
xmlaccess()	XmlAccess()
xmlinit()	XmlCreate()
xmlinitenc()	XmlCreate()
xmlparse()	XmlLoadDomURI()
xmlparsebuf()	XmlLoadDomBuffer()
xmlparsedtd()	Obsolete; use `XML_LOAD_FLAG_DTD_ONLY` flag in `XmlLoadXXX()` calls.
xmlparsefile()	XmlLoadDomFile()
xmlparsestream()	XmlLoadDomStream()
xmlterm()	XmlDestroy()
xpevalxpathexpr()	XmlXPathEval()
xpfreexpathctx()	XmlXPathDeleteCtx()
xpgetbooleanval()	XmlXPathGetObjectBoolean()
xpgetfirstnsetelem()	XmlXPathGetObjectNSetNum()
xpgetnextnsetelem()	XmlXPathGetObjectNSetNum()
xpgetnsetelemnode()	XmlXPathGetObjectNSetNum()
xpgetnsetval()	XmlXPathGetObjectNSetNum()
xpgetnumval()	XmlXPathGetObjectNumber()
xpgetrtfragval()	XmlXPathGetObjectFragment()
xpgetstrval()	XmlXPathGetObjectString()
xpgetxpobjtyp()	XmlXPathGetObjectType()
xpmakexpathctx()	XmlXPathCreateCtx()
xpparsexpathexpr()	XmlXPathParse()
xslgetbaseuri()	XmlXslGetBaseURI()
xslgetoutputdomctx()	XmlXslGetOutputDom()
xslgetoutputsax()	Unnecessary
xslgetoutputstream()	Unnecessary
xslgetresultdocfrag()	XmlXslGetOutputFragment()
xslgettextparam()	XmlXslGetTextParam()
xslgetxslctx()	Unnecessary
xslinit()	XmlXslCreateCtx()
xslprocess()	XmlXslProcess()
xslprocessex()	XmlXslProcess()
xslprocessxml()	XmlXslProcess()
xslprocessxmldocfrag()	XmlXslProcess()
xslresetallparams()	XmlXslResetAllParams()
xslsetoutputdomctx()	XmlXslSetOutputDom()
xslsetoutputencoding()	XmlXslSetOutputEncoding()
xslsetoutputmethod()	XmlXslSetOutputMethod()
xslsetoutputsax()	XmlXslSetOutputSax()
xslsetoutputsaxctx()	XmlXslSetOutputSax()
xslsetoutputstream()	XmlXslSetOutputStream()
xslsettextparam()	XmlXslSetTextParam()
xslterm()	XmlXslDeleteCtx()