SAX1 Programming Guide

Using the SAX API

The SAX API for XML parsers was originally developed for Java. Please be aware that there is no standard SAX API for C++, and that use of the &XercesCName; SAX API does not guarantee client code compatibility with other C++ XML parsers.

The SAX API presents a callback based API to the parser. An application that uses SAX provides an instance of a handler class to the parser. When the parser detects XML constructs, it calls the methods of the handler class, passing them information about the construct that was detected. The most commonly used handler classes are DocumentHandler which is called when XML constructs are recognized, and ErrorHandler which is called when an error occurs. The header files for the various SAX handler classes are in '<&XercesCInstallDir;>/include/xercesc/sax'

As a convenience, &XercesCName; provides the class HandlerBase, which is a single class which is publicly derived from all the Handler classes. HandlerBase's default implementation of the handler callback methods is to do nothing. A convenient way to get started with &XercesCName; is to derive your own handler class from HandlerBase and override just those methods in HandlerBase which you are interested in customizing. This simple example shows how to create a handler which will print element names, and print fatal error messages. The source code for the sample applications show additional examples of how to write handler classes.

This is the header file MySAXHandler.hpp:

    #include <xercesc/sax/HandlerBase.hpp>

    class MySAXHandler : public HandlerBase {
    public:
        void startElement(const XMLCh* const, AttributeList&);
        void fatalError(const SAXParseException&);
    };

This is the implementation file MySAXHandler.cpp:

    #include "MySAXHandler.hpp"
    #include <iostream.h>

    MySAXHandler::MySAXHandler()
    {
    }

    MySAXHandler::startElement(const XMLCh* const name,
                               AttributeList& attributes)
    {
        char* message = XMLString::transcode(name);
        cout << "I saw element: "<< message << endl;
        delete [] message;
    }

    MySAXHandler::fatalError(const SAXParseException& exception)
    {
        char* message = XMLString::transcode(exception.getMessage());
        cout << "Fatal Error: " << message
             << " at line: " << exception.getLineNumber()
             << endl;
    }

The XMLCh and AttributeList types are supplied by &XercesCName; and are documented in the include files. Examples of their usage appear in the source code to the sample applications.

SAXParser

Constructing a SAXParser

In order to use &XercesCName; to parse XML files, you will need to create an instance of the SAXParser class. The example below shows the code you need in order to create an instance of SAXParser. The DocumentHandler and ErrorHandler instances required by the SAX API are provided using the HandlerBase class supplied with &XercesCName;.

        #include <xercesc/parsers/SAXParser.hpp>
        #include <xercesc/sax/HandlerBase.hpp>
        #include <xercesc/util/XMLString.hpp>

        int main (int argc, char* args[]) {

            try {
                XMLPlatformUtils::Initialize();
            }
            catch (const XMLException& toCatch) {
                char* message = XMLString::transcode(toCatch.getMessage());
                cout << "Error during initialization! :\n"
                     << message << "\n";
                delete [] message;
                return 1;
            }

            char* xmlFile = "x1.xml";
            SAXParser* parser = new SAXParser();
            parser->setDoValidation(true);    // optional.
            parser->setDoNamespaces(true);    // optional

            DocumentHandler* docHandler = new HandlerBase();
            ErrorHandler* errHandler = (ErrorHandler*) docHandler;
            parser->setDocumentHandler(docHandler);
            parser->setErrorHandler(errHandler);

            try {
                parser->parse(xmlFile);
            }
            catch (const XMLException& toCatch) {
                char* message = XMLString::transcode(toCatch.getMessage());
                cout << "Exception message is: \n"
                     << message << "\n";
                delete [] message;
                return -1;
            }
            catch (const SAXParseException& toCatch) {
                char* message = XMLString::transcode(toCatch.getMessage());
                cout << "Exception message is: \n"
                     << message << "\n";
                delete [] message;
                return -1;
            }
            catch (...) {
                cout << "Unexpected Exception \n" ;
                return -1;
            }

            delete parser;
            delete docHandler;
            return 0;
        }

SAXParser Supported Features

The behavior of the SAXParser is dependant on the values of the following features. All of the features below are set using the "setter" methods (e.g. `setDoNamespaces`), and are queried using the corresponding "getter" methods (e.g. `getDoNamespaces`). The following only gives you a quick summary of supported features. Please refer to API Documentataion for complete detail.

None of these features can be modified in the middle of a parse, or an exception will be thrown.

void setDoNamespaces(const bool)
true: | Perform Namespace processing.
false: | Do not perform Namespace processing.
default: | false
note: | If the validation scheme is set to Val_Always or Val_Auto, then the document must contain a grammar that supports the use of namespaces.
see: | setValidationScheme

void setDoValidation(const bool) (deprecated) please use setValidationScheme.
true: | Report all validation errors.
false: | Do not report validation errors.
default: | see the default of setValidationScheme.
see: | setValidationScheme

void setValidationScheme(const ValSchemes)
Val_Auto: | The parser will report validation errors only if a grammar is specified.
Val_Always: | The parser will always report validation errors.
Val_Never: | Do not report validation errors.
default: | Val_Auto
note: | If set to Val_Always, the document must specify a grammar. If this feature is set to Val_Never and document specifies a grammar, that grammar might be parsed but no validation of the document contents will be performed.
see: | setLoadExternalDTD

void setDoSchema(const bool)
true: | Enable the parser's schema support.
false: | Disable the parser's schema support.
default: | false
note | If set to true, namespace processing must also be turned on.
see: | setDoNamespaces

void setValidationSchemaFullChecking(const bool)
true: | Enable full schema constraint checking, including checking which may be time-consuming or memory intensive. Currently, particle unique attribution constraint checking and particle derivation restriction checking are controlled by this option.
false: | Disable full schema constraint checking.
default: | false
note: | This feature checks the Schema grammar itself for additional errors that are time-consuming or memory intensive. It does not affect the level of checking performed on document instances that use Schema grammars.
see: | setDoSchema

void setLoadExternalDTD(const bool)
true: | Load the External DTD .
false: | Ignore the external DTD completely.
default: | true
note | This feature is ignored and DTD is always loaded if the validation scheme is set to Val_Always or Val_Auto.
see: | setValidationScheme

void setExitOnFirstFatalError(const bool)
true: | Stops parse on first fatal error.
false: | Attempt to continue parsing after a fatal error.
default: | true
note: | The behavior of the parser when this feature is set to false is undetermined! Therefore use this feature with extreme caution because the parser may get stuck in an infinite loop or worse.

void setValidationConstraintFatal(const bool)
true: | The parser will treat validation error as fatal and will exit depends on the state of setExitOnFirstFatalError.
false: | The parser will report the error and continue processing.
default: | false
note: | Setting this true does not mean the validation error will be printed with the word "Fatal Error". It is still printed as "Error", but the parser will exit if setExitOnFirstFatalError is set to true.
see: | setExitOnFirstFatalError

void useCachedGrammarInParse(const bool)
true: | Use cached grammar if it exists in the pool.
false: | Parse the schema grammar.
default: | false
note: | The getter function for this method is called isUsingCachedGrammarInParse
note: | If the grammar caching option is enabled, this option is set to true automatically. Any setting to this option by the users is a no-op.
see: | cacheGrammarFromParse

void cacheGrammarFromParse(const bool)
true: | Cache the grammar in the pool for re-use in subsequent parses.
false: | Do not cache the grammar in the pool
default: | false
note: | The getter function for this method is called isCachingGrammarFromParse
note: | If set to true, the useCachedGrammarInParse is also set to true automatically.
see: | useCachedGrammarInParse

void setExternalSchemaLocation(const XMLCh* const)

Description

The XML Schema Recommendation explicitly states that the inclusion of schemaLocation/ noNamespaceSchemaLocation attributes in the instance document is only a hint; it does not mandate that these attributes must be used to locate schemas. Similar situation happens to <import> element in schema documents. This property allows the user to specify a list of schemas to use. If the targetNamespace of a schema specified using this method matches the targetNamespace of a schema occurring in the instance document in schemaLocation attribute, or if the targetNamespace matches the namespace attribute of <import> element, the schema specified by the user using this property will be used (i.e., the schemaLocation attribute in the instance document or on the <import> element will be effectively ignored).

Value | The syntax is the same as for schemaLocation attributes in instance documents: e.g, "http://www.example.com file_name.xsd". The user can specify more than one XML Schema in the list.
Value Type | XMLCh*

void setExternalNoNamespaceSchemaLocation(const XMLCh* const)

Description

The XML Schema Recommendation explicitly states that the inclusion of schemaLocation/ noNamespaceSchemaLocation attributes in the instance document is only a hint; it does not mandate that these attributes must be used to locate schemas. This property allows the user to specify the no target namespace XML Schema Location externally. If specified, the instance document's noNamespaceSchemaLocation attribute will be effectively ignored.

Value | The syntax is the same as for the noNamespaceSchemaLocation attribute that may occur in an instance document: e.g."file_name.xsd".
Value Type | XMLCh*