16
XML Parser for C++

This chapter contains the following sections:

• Accessing XML Parser for C++
• XML Parser for C++ Features
• XML Parser for C++ Usage
• XML Parser for C++ Default Behavior
• DOM and SAX APIs
• Invoking XML Parser for C++
• Using the Sample Files Included with Your Software
• Running the XML Parser for C++ Sample Programs

Accessing XML Parser for C++

The XML Parser for C++ is provided with Oracle9i and Oracle9i Application Serverand is also available for download from the OTN site: http://otn.oracle.com/tech/xml.

It is located at $ORACLE_HOME/xdk/cpp/parser.

XML Parser for C++ Features

readme.html in the root directory of the software archive contains release specific information including bug fixes and API additions.

XML Parser for C++ will check if an XML document is well-formed, and optionally validate it against a DTD. The parser will construct an object tree which can be accessed through a DOM interface or operate serially through a SAX interface.

You can post questions, comments, or bug reports to the XML Discussion Forum at http://otn.oracle.com/tech/xml/ .

Specifications

See the following:

Memory Allocation

The memory callback functions memcb may be used if you wish to use your own memory allocation. If they are used, all of the functions should be specified.

The memory allocated for parameters passed to the SAX callbacks or for nodes and data stored with the DOM parse tree will not be freed until one of the following is done:

• xmlclean() is called.
• xmlterm() is called.

Thread Safety

If threads are forked off somewhere in the midst of the init-parse-term sequence of calls, you will get unpredictable behavior and results.

Data Types Index

Table 16-1 lists the datatypes used in XML Parser for C++.

Table 16-1 Datatypes Used in XML Parser for C++  

DataType	Description
oratext	String pointer
xmlctx	Master XML context
xmlmemcb	Memory callback structure (optional)
xmlsaxcb	SAX callback structure (SAX only)
ub4	32-bit (or larger) unsigned integer
uword	Native unsigned integer

Error Message Files

Error message files are provided in the mesg/ subdirectory. The messages files also exist in the $ORACLE_HOME/xdk/mesg directory. You may set the environment variable ORA_XML_MESG to point to the absolute path of the mesg/ subdirectory although this not required.

Validation Modes

XML Parser for C++ Usage

Figure 16-1 illustrates the XML Parser for C++ functionality.

1. xmlinit() function initializes the parsing process.
2. The XML input can be either an XML file or string buffer. This inputs the following methods:
   • XMLParser.xmlparse() if the input is an XML file
   • XMLParser.xmlparseBuffer() if the input is a string buffer
3. DOM or SAX API

   DOM: If you are using the DOM interface, include the following steps:

   • The XMLParser.xmlparse() or .xmlparserBuffer() method calls .getDocument Element(). If no other DOM methods are being applied, you can invoke .xmlterm().
   • This optionally calls other DOM methods if required. These are typically Node class methods or print methods. It outputs the DOM document.
   • If complete, the process invokes .xmlterm()
   • You can first invoke .xmlclean() to clean up any data structure created during the parse process. You would then call .xmlterm()

   SAX: If you are using the SAX interface, include the following steps:

   • Process the results of the parser from .xmlparse() or .xmlparseBuffer() through callback methods.
   • Register the callback methods
4. Use .xmlclean() to clean up the memory and structures used during a parse, and go to Step 5. or return to Step 2.
5. Terminate the parsing process with .xmlterm()

Parser Calling Sequence

The sequence of calls to the parser can be any of the following:

• XMLParser.xmlinit() - XMLParser.xmlparse() or

  XMLParser.xmlparsebuf() - XMLParser.xmlterm()

• XMLParser.xmlinit() - XMLParser.xmlparse() or

  XMLParser.xmlparsebuf() - XMLParser.xmlclean() - XMLParser.xmlparse() or

  XMLParser.xmlparsebuf() - XMLParser.xmlclean() -... - XMLParser.xmlterm()

• XMLParser.xmlinit() - XMLParser.xmlparse() or

  XMLParser.xmlparsebuf() - XMLParser.xmlparse() or

  XMLParser.xmlparsebuf() -... - XMLParser.xmlterm()

Figure 16-1 XML Parser for C++ (DOM and SAX Interfaces) Usage

Text description of the illustration adxml050.gif

XML Parser for C++ Default Behavior

The following is the XML Parser for C++ default behavior:

• Character set encoding is UTF-8. If all your documents are ASCII, you are encouraged to set the encoding to US-ASCII for better performance.
• Messages are printed to stderr unless msghdlr is given.
• A parse tree which can be accessed by DOM APIs is built unless saxcb is set to use the SAX callback APIs. Note that any of the SAX callback functions can be set to NULL if not needed.
• The default behavior for the parser is to check that the input is well-formed but not to check whether it is valid. The flag XML_FLAG_VALIDATE can be set to validate the input. The default behavior for whitespace processing is to be fully conformant to the XML 1.0 spec, that is, all whitespace is reported back to the application but it is indicated which whitespace is ignorable. However, some applications may prefer to set the XML_FLAG_DISCARD_WHITESPACE which will discard all whitespace between an end-element tag and the following start-element tag.

  Note: It is recommended that you set the default encoding explicitly if using only single byte character sets (such as US-ASCII or any of the ISO-8859 character sets) for performance up to 25% faster than with multibyte character sets, such as UTF-8.

DOM and SAX APIs

Oracle XML parser for C++ checks if an XML document is well-formed, and optionally validates it against a DTD. The parser constructs an object tree which can be accessed through one of the following interfaces:

• DOM interface
• Serially through a SAX interface

These two XML APIs:

• DOM: Tree-based APIs. A tree-based API compiles an XML document into an internal tree structure, then allows an application to navigate that tree using the Document Object Model (DOM), a standard tree-based API for XML and HTML documents.
• SAX: Event-based APIs. An event-based API, on the other hand, reports parsing events (such as the start and end of elements) directly to the application through callbacks, and does not usually build an internal tree. The application implements handlers to deal with the different events, much like handling events in a graphical user interface.

Tree-based APIs are useful for a wide range of applications, but they often put a great strain on system resources, especially if the document is large (under very controlled circumstances, it is possible to construct the tree in a lazy fashion to avoid some of this problem). Furthermore, some applications need to build their own, different data trees, and it is very inefficient to build a tree of parse nodes, only to map it onto a new tree.

In both of these cases, an event-based API provides a simpler, lower-level access to an XML document: you can parse documents much larger than your available system memory, and you can construct your own data structures using your callback event handlers.

Using the SAX API

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 can also be included. That context pointer will be passed to each SAX function.

SAX Callback Structure

The SAX callback structure:

typedef struct
{
 sword (*startDocument)(void *ctx);
 sword (*endDocument)(void *ctx);
 sword (*startElement)(void *ctx, const oratext *name, 
             const struct xmlarray *attrs);
 sword (*endElement)(void *ctx, const oratext *name);
 sword (*characters)(void *ctx, const oratext *ch, size_t len);
 sword (*ignorableWhitespace)(void *ctx, const oratext *ch, size_t len);
 sword (*processingInstruction)(void *ctx, const oratext *target,
             const oratext *data);
 sword (*notationDecl)(void *ctx, const oratext *name,
             const oratext *publicId, const oratext *systemId);
 sword (*unparsedEntityDecl)(void *ctx, const oratext *name, 
             const oratext *publicId,
             const oratext *systemId, const oratext *notationName);
 sword (*nsStartElement)(void *ctx, const oratext *qname,
             const oratext *local, const oratext *nsp,
             const struct xmlnodes *attrs);
} xmlsaxcb;

Invoking XML Parser for C++

XML Parser for C++ can be invoked in two ways:

• By invoking the executable on the command line
• By writing C++ code and using the supplied APIs

Command Line Usage

The XML Parser for C++ can be called as an executable by invoking bin/xml

Table 16-2 lists the command line options.

Table 16-2 XML Parser for C++: Command Line Options

Option	Description
-c	Conformance check only, no validation
-e encoding	Specify input file encoding
-h	Help - show this usage help
-n	Number - DOM traverse and report number of elements
-p	Print document and DTD structures after parse
-x	Exercise SAX interface and print document
-v	Version - display parser version then exit
-w	Whitespace - preserve all whitespace

Writing C++ Code to Use Supplied APIs

XML Parser for C++ can also be invoked by writing code to use the supplied APIs. The code must be compiled using the headers in the include/ subdirectory and linked against the libraries in the lib/ subdirectory. Please see the Makefile in the sample/ subdirectory for full details of how to build your program.

Using the Sample Files Included with Your Software

$ORACLE_HOME/xdk/cpp/parser/sample/ directory contains several XML applications to illustrate how to use the XML Parser for C++ with the DOM and SAX interfaces.

Table 16-3 lists the sample files in sample/ directory.

Table 16-3 XML Parser for C++ sample/ Files  

sample/ File Name	Description
DOMNamespace.cpp	Source for DOMNamespace program
DOMNamespace.std	Expected output from DOMNamespace
DOMSample.cpp	Source for DOMSample program
DOMSample.std	Expected output from DOMSample
FullDOM.c	Sample usage of DOM interface
FullDOM.std	Expected output from FullDOM
Make.bat	Batch file to build sample executables
Makefile	Makefile for sample programs
NSExample.xml	Sample XML file using namespaces
SAXNamespace.cpp	Source for SAXNamespace program
SAXNamespace.std	Expected output from SAXNamespace
SAXSample.cpp	Source for SAXSample program
SAXSample.std	Expected output from SAXSample
XSLSample.cpp	Source for XSLSample program
XSLSample.std	Expected output from XSLSample
class.xml	XML file that may be used with XSLSample
iden.xsl	Stylesheet that may be used with XSLSample
cleo.xml	XML version of Shakespeare's play

Running the XML Parser for C++ Sample Programs

Building the Sample Programs

Change directories to the sample directory ($ORACLE_HOME/xdk/demo/cpp/parser on Solaris^TM Operating Environment) and read the README file. This will explain how to build the sample programs according to your platform.

Sample Programs

Table 16-4 lists the programs built by the sample files in sample/.

Table 16-4 XML Parser for C++, Sample Programs Built in sample/  

Built Program	Description
SAXSample	A sample application using SAX APIs. Prints out all speakers in each scene, that is, all the unique SPEAKER elements within each SCENE element.
DOMSample [speaker]	A sample application using DOM APIs. Prints all speeches made by the given speaker. If no speaker is specified, "Soothsayer" is used. Note that major characters have uppercase names (for example, "CLEOPATRA"), whereas minor characters have capitalized names (for example, "Attendant"). See the output of SAXSample.
SAXNamespace	A sample application using Namespace extensions to SAX API; prints out all elements and attributes of NSExample.xml along with full namespace information.
DOMNamespace	Same as SAXNamespace except using DOM interface.
FullDOM	Sample usage of full DOM interface. Exercises all the calls, but does nothing too exciting.
XSLSample <xmlfile> <xsl ss>	Sample usage of XSL processor. It takes two filenames as input, the XML file and the XSL stylesheet. Note: If you redirect stdout of this program to a file, you may encounter some missing output, depending on your environment.