Accessing XML Parser for C++

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 via a DOM interface or operate serially via a SAX interface.

Error Message Files

Error message files are provided in the mesg/ subdirectory. The messages files also exist in the $ORACLE_HOME/oracore/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.

Figure 26-2 Parser for C++: XSL-T Functionality (DOM Interface) Usage

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 via one of the following interfaces:

DOM interface

Serially via 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.

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.

Sample Programs

Table 26-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, i.e. 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 (e.g. "CLEOPATRA"), whereas minor characters have capitalized names (e.g. "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.

XML Parser for C++ Example 7: C++ -- DOMSample.std

DOMSample.std shows the expected output from DOMSample.cpp.

XML C++ DOM sample
Initializing XML package...
Parsing 'cleo.xml'...
Dumping Soothsayer speeches...
-----------------------------------------------------------
ACT I, SCENE II. The same. Another room.
Your will?
ACT I, SCENE II. The same. Another room.
In nature's infinite book of secrecy
A little I can read.
ACT I, SCENE II. The same. Another room.
I make not, but foresee.
ACT I, SCENE II. The same. Another room.
You shall be yet far fairer than you are.
ACT I, SCENE II. The same. Another room.
You shall be more beloving than beloved.
ACT I, SCENE II. The same. Another room.
You shall outlive the lady whom you serve.
ACT I, SCENE II. The same. Another room.
You have seen and proved a fairer former fortune
Than that which is to approach.
ACT I, SCENE II. The same. Another room.
If every of your wishes had a womb.
And fertile every wish, a million.
ACT I, SCENE II. The same. Another room.
Your fortunes are alike.
ACT I, SCENE II. The same. Another room.
I have said.
ACT II, SCENE III. The same. OCTAVIUS CAESAR's house.
Would I had never come from thence, nor you Thither!
ACT II, SCENE III. The same. OCTAVIUS CAESAR's house.
I see it in
My motion, have it not in my tongue: but yet
Hie you to Egypt again.
ACT II, SCENE III. The same. OCTAVIUS CAESAR's house.
Caesar's.
Therefore, O Antony, stay not by his side:
Thy demon, that's thy spirit which keeps thee, is
Noble, courageous high, unmatchable,
Where Caesar's is not; but, near him, thy angel
Becomes a fear, as being o'erpower'd: therefore
Make space enough between you.
ACT II, SCENE III. The same. OCTAVIUS CAESAR's house.
To none but thee; no more, but when to thee.
If thou dost play with him at any game,
Thou art sure to lose; and, of that natural luck,
He beats thee 'gainst the odds: thy lustre thickens,
When he shines by: I say again, thy spirit
Is all afraid to govern thee near him;
But, he away, 'tis noble.