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

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.

Initializing and Parsing Sequence Changes

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

Example 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);

Example 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);

Example 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);

Example 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);

Datatype Mapping between oraxml and xml Packages

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

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.Usexmlctx.

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.UseXmlXPathGetObjectNSetNum()and XmlXPathGetObjectNSetNode().

xpnsetele

Obsolete.UseXmlXPathGetObjectNSetNum()and XmlXPathGetObjectNSetNode().

xpobj
xpobj
xpobjtyp
xmlxslobjtype
xslctx
xslctx
xsloutputmethod
xmlxsloutputmethod

Method Mapping between oraxml and xml Packages

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

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()