Skip Headers

Oracle9i XML Developer's Kits Guide - XDK
Release 2 (9.2)

Part Number A96621-01
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback

Go to previous page Go to next page

16
XML Parser for C++

This chapter contains the following sections:

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:

See Also:

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:

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

See Also:

Available validation modes are described in "Oracle XML Parsers 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:

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

Text description of adxml050.gif follows
Text description of the illustration adxml050.gif


XML Parser for C++ Default Behavior

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

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:

These two XML APIs:

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:

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


Go to previous page Go to next page
Oracle
Copyright © 2001, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback