| Version Macro |
| Xerces-C++ has defined a numeric preprocessor macro, _XERCES_VERSION, for users to introduce into their code to perform conditional compilation where the version of Xerces is detected in order to enable or disable version specific capabilities. For example,
    #if _XERCES_VERSION >= 20304
      // code specific to Xerces-C++ version 2.3.4
    #else
      // old code here...
    #endif
The minor and revision (patch level) numbers have two digits of resolution which means that '3' becomes '03' and '4' becomes '04' in this example. There are also other string macro, or constants to represent the Xerces-C++ version. Please refer to the header xercesc/util/XercesVersion.hpp for further details.
| Schema Support |
| Xerces-C++ contains an implementation of the W3C XML Schema Language. See the Schema page for details.
| Progressive Parsing |
| In addition to using the parse() method to parse an XML File. You can use the other two parsing methods, parseFirst() and parseNext() to do 'progressive parsing', so that you don't have to depend upon throwing an exception to terminate the parsing operation. Calling parseFirst() will cause the DTD (both internal and external subsets), and any pre-content, i.e. everything up to but not including the root element, to be parsed. Subsequent calls to parseNext() will cause one more pieces of markup to be parsed, and spit out from the core scanning code to the parser (and hence either on to you if using SAX or into the DOM tree if using DOM). You can quit the parse any time by just not calling parseNext() anymore and breaking out of the loop. When you call parseNext() and the end of the root element is the next piece of markup, the parser will continue on to the end of the file and return false, to let you know that the parse is done. So a typical progressive parse loop will look like this:
    // Create a progressive scan token
    XMLPScanToken token;

    if (!parser.parseFirst(xmlFile, token))
    {
      cerr << "scanFirst() failed\n" << endl;
      return 1;
    }

    //
    // We started ok, so lets call scanNext()
    // until we find what we want or hit the end.
    //
    bool gotMore = true;
    while (gotMore && !handler.getDone())
      gotMore = parser.parseNext(token);
In this case, our event handler object (named 'handler' surprisingly enough) is watching form some criteria and will return a status from its getDone() method. Since the handler sees the SAX events coming out of the SAXParser, it can tell when it finds what it wants. So we loop until we get no more data or our handler indicates that it saw what it wanted to see. When doing non-progressive parses, the parser can easily know when the parse is complete and insure that any used resources are cleaned up. Even in the case of a fatal parsing error, it can clean up all per-parse resources. However, when progressive parsing is done, the client code doing the parse loop might choose to stop the parse before the end of the primary file is reached. In such cases, the parser will not know that the parse has ended, so any resources will not be reclaimed until the parser is destroyed or another parse is started. This might not seem like such a bad thing; however, in this case, the files and sockets which were opened in order to parse the referenced XML entities will remain open. This could cause serious problems. Therefore, you should destroy the parser instance in such cases, or restart another parse immediately. In a future release, a reset method will be provided to do this more cleanly. Also note that you must create a scan token and pass it back in on each call. This insures that things don't get done out of sequence. When you call parseFirst() or parse(), any previous scan tokens are invalidated and will cause an error if used again. This prevents incorrect mixed use of the two different parsing schemes or incorrect calls to parseNext().
| Preparsing Grammar and Grammar Caching |
| Xerces-C++ 2.2.0 provides a new function to pre-parse the grammar so that users can check for any syntax or error before using the grammar. Users can also optionally cache these pre-parsed grammars for later use during actual parsing. Here is an example:
    XercesDOMParser parser;

    // enbale schema processing
    parser.setDoSchema(true);
    parser.setDONamespaces(true);

    // Let's preparse the schema grammar (.xsd) and cache it.
    Grammar* grammar = parser.loadGrammar(xmlFile, Grammar::SchemaGrammarType, true);
Besides caching pre-parsed schema grammars, users can also cache any grammars encountered during an xml document parse. Here is an example:
    SAXParser parser;

    // Enable grammar caching by setting cacheGrammarFromParse to true.
    // The parser will cache any encountered grammars if it does not
    // exist in the pool.
    // If the grammar is DTD, no internal subset is allowed.
    parser.cacheGrammarFromParse(true);

    // Let's parse our xml file (DTD grammar)
    parser.parse(xmlFile);

    // We can get the grammar where the root element was declared
    // by calling the parser's method getRootGrammar;
    // Note: The parser owns the grammar, and the user should not delete it.
    Grammar* grammar = parser.getRootGrammar();
We can use any previously cached grammars when parsing new xml documents. Here are some examples on how to use those cached grammars:
    /**
      * Caching and reusing XML Schema (.xsd) grammar
      * Parse an XML document and cache its grammar set. Then,  use the cached
      * grammar set in subsequent parses.
      */

    XercesDOMParser parser;

    // Enable schema processing
    parser.setDoSchema(true);
    parser.setDoNamespaces(true);

    // Enable grammar caching
    parser.cacheGrammarFromParsing(true);

    // Let's parse the XML document. The parser will cache any grammars encounterd.
    parser.parse(xmlFile);

    // No need to enable re-use by setting useCachedGrammarInParse to true. It is
    // automatically enabled with grammar caching.
    for (int i=0; i< 3; i++)
        parser.parse(xmlFile);

    // This will flush the grammar pool
    parser.resetCachedGrammarPool();
    /**
      * Caching and reusing DTD grammar
      * Preparse a grammar and cache it in the pool. Then, we use the cached grammar
      * when parsing XML documents.
      */

    SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();

    // Load grammar and cache it
    parser->loadGrammar(dtdFile, Grammar::DTDGrammarType, true);

    // enable grammar reuse
    parser->setFeature(XMLUni::fgXercesUseCachedGrammarInParse, true);

    // Parse xml files
    parser->parse(xmlFile1);
    parser->parse(xmlFile2);
There are some limitations about caching and using cached grammars: When caching/reusing DTD grammars, no internal subset is allowed. When preparsing grammars with caching option enabled, if a grammar, in the result set, already exists in the pool (same NS for schema or same system id for DTD), the entire set will not be cached. When parsing an XML document with the grammar caching option enabled, the reuse option is also automatically enabled. We will only parse a grammar if it does not exist in the pool.
| Loadable Message Text |
| The Xerces-C++ supports loadable message text. Although the current drop just supports English, it is capable to support other languages. Anyone interested in contributing any translations should contact us. This would be an extremely useful service. In order to support the local message loading services, all the error messages are captured in an XML file in the src/xercesc/NLS/ directory. There is a simple program, in the Tools/NLSXlat/ directory, which can spit out that text in various formats. It currently supports a simple 'in memory' format (i.e. an array of strings), the Win32 resource format, and the message catalog format. The 'in memory' format is intended for very simple installations or for use when porting to a new platform (since you can use it until you can get your own local message loading support done.) In the src/xercesc/util/ directory, there is an XMLMsgLoader class. This is an abstraction from which any number of message loading services can be derived. Your platform driver file can create whichever type of message loader it wants to use on that platform. Xerces-C++ currently has versions for the in memory format, the Win32 resource format, the message catalog format, and ICU message loader. Some of the platforms can support multiple message loaders, in which case a #define token is used to control which one is used. You can set this in your build projects to control the message loader type used.
| Pluggable Transcoders |
| Xerces-C++ also supports pluggable transcoding services. The XMLTransService class is an abstract API that can be derived from, to support any desired transcoding service. XMLTranscoder is the abstract API for a particular instance of a transcoder for a particular encoding. The platform driver file decides what specific type of transcoder to use, which allows each platform to use its native transcoding services, or the ICU service if desired. Implementations are provided for Win32 native services, ICU services, and the iconv services available on many Unix platforms. The Win32 version only provides native code page services, so it can only handle XML code in the intrinsic encodings ASCII, UTF-8, UTF-16 (Big/Small Endian), UCS4 (Big/Small Endian), EBCDIC code pages IBM037 and IBM1140 encodings, ISO-8859-1 (aka Latin1) and Windows-1252. The ICU version provides all of the encodings that ICU supports. The iconv version will support the encodings supported by the local system. You can use transcoders we provide or create your own if you feel ours are insufficient in some way, or if your platform requires an implementation that Xerces-C++ does not provide.
| Porting Guidelines |
| All platform dependent code in Xerces has been isolated to a couple of files, which should ease the porting effort. Here are the basic steps that should be followed to port Xerces. The directory `src/xercesc/util/Platforms` contains the platform sensitive files while `src/xercesc/util/Compilers` contains all development environment sensitive files. Each operating system has a file of its own and each development environment has another one of its own too. As an example, the Win32 platform as a `Win32Defs.hpp` file and the Visual C++ environment has a `VCPPDefs.hpp` file. These files set up certain define tokens, typedefs, constants, etc... that will drive the rest of the code to do the right thing for that platform and development environment. AIX/CSet have their own `AIXDefs.hpp` and `CSetDefs.hpp` files, and so on. You should create new versions of these files for your platform and environment and follow the comments in them to set up your own. Probably the comments in the Win32 and Visual C++ will be the best to follow, since that is where the main development is done. Next, edit the file `XercesDefs.hpp`, which is where all of the fundamental stuff comes into the system. You will see conditional sections in there where the above per-platform and per-environment headers are brought in. Add the new ones for your platform under the appropriate conditionals. Now edit `AutoSense.hpp`. Here we set canonical Xerces internal `#define` tokens which indicate the platform and compiler. These definitions are based on known platform and compiler defines. `AutoSense.hpp` is included in `XercesDefs.hpp` and the canonical platform and compiler settings thus defined will make the particular platform and compiler headers to be the included at compilation. It might be a little tricky to decipher this file so be careful. If you are using say another compiler on Win32, probably it will use similar tokens so that the platform will get picked up already using what is already there. Once this is done, you will then need to implement a version of the platform utilities for your platform. Each operating system has a file which implements some methods of the XMLPlatformUtils class, specific to that operating system. These are not terribly complex, so it should not be a lot of work. The Win32 version is called `Win32PlatformUtils.cpp`, the AIX version is `AIXPlatformUtils.cpp` and so on. Create one for your platform, with the correct name, and empty out all of the implementation so that just the empty shells of the methods are there (with dummy returns where needed to make the compiler happy.) Once you've done that, you can start to get it to build without any real implementation. Once you have the system building, then start implementing your own platform utilities methods. Follow the comments in the Win32 version as to what they do, the comments will be improved in subsequent versions, but they should be fairly obvious now. Once you have these implementations done, you should be able to start debugging the system using the demo programs. Other concerns are: Does ICU compile on your platform? If not, then you'll need to create a transcoder implementation that uses your local transcoding services. The Iconv transcoder should work for you, though perhaps with some modifications. What message loader will you use? To get started, you can use the "in memory" one, which is very simple and easy. Then, once you get going, you may want to adapt the message catalog message loader, or write one of your own that uses local services. What should I define XMLCh to be? Please refer to What should I define XMLCh to be? for further details. That is the work required in a nutshell!
| Using C++ Namespace |
| Xerces-C++ 2.2.0 now supports C++ Namespace. The macro `XERCES_HAS_CPP_NAMESPACE` is defined in each Compiler Definition file if C++ Namespace is supported. For example in header `xercesc/util/Compilers/GCCDefs.hpp`, the C++ Namespace is enabled:
    // -------------------------------------------------------------------------
    // Indicate that we support C++ namespace
    // Do not define it if the compile cannot handle C++ namespace
    // -------------------------------------------------------------------------
    #define XERCES_HAS_CPP_NAMESPACE
If C++ Namespace support is ENABLED (all the binary distributions of Xerces-C++ 2.2.0 are built with C++ Namespace enabled), users' applications must namespace qualified all the Xerces-C++ classes/data/variables with `"xercesc::"` or add the `"using namespace xercesc"` clause. Users also need to ensure all forward declarations are properly qualified or scope. For example
    #include <stdio.h>
    #include <stdlib.h>
    #include <xercesc/sax/HandlerBase.hpp>

    // indicate using Xerces-C++ namespace in general
    using namespace xercesc;

    // need to properly scope any forward declarations
    namespace xercesc {
    class AttributeList;
    }

    // or namespace qualifier the forward declarations
    class xercesc::ErrorHandler;

    class MySAXHandlers : public HandlerBase
    {
    public:
        // -----------------------------------------------------------------------
        //  Handlers for the SAX DocumentHandler interface
        // -----------------------------------------------------------------------
        void startElement(const XMLCh* const name, AttributeList& attributes);
        void characters(const XMLCh* const chars, const unsigned int length);
    :
    :
    };
Header `"xercesc/util/XercesDefs.hpp"` has defined the following macros
    #if defined(XERCES_HAS_CPP_NAMESPACE)
        #define XERCES_CPP_NAMESPACE_BEGIN    namespace xercesc_2_2 {
        #define XERCES_CPP_NAMESPACE_END    }
        #define XERCES_CPP_NAMESPACE_USE    using namespace xercesc_2_2;
        #define XERCES_CPP_NAMESPACE_QUALIFIER    xercesc_2_2::

        namespace xercesc_2_2 { }
        namespace xercesc = xercesc_2_2;
    #else
        #define XERCES_CPP_NAMESPACE_BEGIN
        #define XERCES_CPP_NAMESPACE_END
        #define XERCES_CPP_NAMESPACE_USE
        #define XERCES_CPP_NAMESPACE_QUALIFIER
    #endif
Users can also make use of these pre-defined macro in their applications. For example:
    #include <stdio.h>
    #include <stdlib.h>
    #include <xercesc/sax/HandlerBase.hpp>

    // indicate using Xerces-C++ namespace in general
    XERCES_CPP_NAMESPACE_USE

    // need to properly scope any forward declarations
    XERCES_CPP_NAMESPACE_BEGIN
    class AttributeList;
    XERCES_CPP_NAMESPACE_END

    // or namespace qualifier the forward declarations
    class XERCES_CPP_NAMESPACE_QUALIFIER ErrorHandler;

    class MySAXHandlers : public HandlerBase
    {
    public:
        // -----------------------------------------------------------------------
        //  Handlers for the SAX DocumentHandler interface
        // -----------------------------------------------------------------------
        void startElement(const XMLCh* const name, AttributeList& attributes);
        void characters(const XMLCh* const chars, const unsigned int length);
    :
    :
    };
NOTE: `"namespace xercesc"` and `"namespace xercesc_2_2"` are equivalent in this release. For those users who want to selectively pick which version of API to use, they can do something like this:
    #if _XERCES_VERSION == 20300
      // code specific to Xerces-C++ version 2.3.0
      new xercesc_2_3::SAXParser();
    #elif _XERCES_VERSION == 20200
      // code specific to Xerces-C++ version 2.2.0
      new xercesc_2_2::SAXParser();
    #else
      // old code here...
      new SAXParser();
    #endif
But for those who just want to call the latest API, then they should use `xercesc::` or the macro `XERCES_CPP_NAMESPACE_QUALIFIER` for source compatibility:
    xercesc
    new xercesc::SAXParser();

    //or use the macro
    new XERCES_CPP_NAMESPACE_QUALIFIER SAXParser();
`xercesc` is a generic namespace name which will be assigned to `xercesc_YY_ZZ` in each specific release, where "YY" is the Major Release Number and "ZZ" is the Minor Version Number.
| Specify locale for message loader |
| The Xerces-C++ has implemented mechanism to support NLS, though the current drop has only English version message file, it is capable to support other languages once the translated version of the target language is available. Application can specify the locale for the message loader in their very first invocation to XMLPlatformUtils::Initialize() by supplying a parameter for the target locale intended. The defaul locale is "en_US".
    ...
        // Initialize the parser system
        try
        {
             XMLPlatformUtils::Initialize("fr_FR");
        }

        catch ()
        {
        }
    ..
| Use Specific Scanner |
| For performance and modularity, the Xerces-C++ has implemented a mechanism to allow users to specify the scanner to use when scanning an XML document. Such mechanism will enable the creation of special purpose scanners that can be easily plugged in. Xerces-C++ supports the following scanners:
| WFXMLScanner |
| The WFXMLScanner is a non-validating scanner which performs well-formedness check only. It does not do any DTD/XMLSchema processing. If the XML document contains a DOCTYPE, it will be silently ignored (i.e. no warning message is issued). Similiarly, any schema specific attributes (e.g. schemaLocation), will be treated as normal element attributes. Setting grammar specific features/properties will have no effect on its behavior (e.g. setLoadExternalDTD(true) is ignored).
    // Create a DOM parser
    XercesDOMParser parser;

    // Specify scanner name
    parser.useScanner(XMLUni::fgWFXMLScanner);

    // Specify other parser features, e.g.
    parser.setDoNamespaces(true);
| DGXMLScanner |
| The DGXMLScanner handles XML documents with DOCTYPE information. It does not do any XMLSchema processing, which means that any schema specific attributes (e.g. schemaLocation), will be treated as normal element attributes. Setting schema grammar specific features/properties will have no effect on its behavior (e.g. setDoSchema(true) is ignored).
    // Create a SAX parser
    SAXParser parser;

    // Specify scanner name
    parser.useScanner(XMLUni::fgDGXMLScanner);

    // Specify other parser features, e.g.
    parser.setLoadExternalDTD(true);
| SGXMLScanner |
| The SGXMLScanner handles XML documents with XML schema grammar information. If the XML document contains a DOCTYPE, it will be ignored. Namespace and schema processing features are on by default, and setting them to off has not effect.
    // Create a SAX2 parser
    SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();

    // Specify scanner name
    parser->setProperty(XMLUni::fgXercesScannerName, XMLUni::fgSGXMLScanner);

    // Specify other parser features, e.g.
    parser->setFeature(XMLUni::fgXercesSchemaFullChecking, false);
| IGXMLScanner |
| The IGXMLScanner is an integrated scanner and handles XML documents with DTD and/or XML schema grammar. This is the default scanner used by the various parsers if no scanner is specified.
    // Create a DOMBuilder parser
    DOMBuilder *parser = ((DOMImplementationLS*)impl)->createDOMBuilder(DOMImplementationLS::MODE_SYNCHRONOUS, 0);

    // Specify scanner name - This is optional as IGXMLScanner is the default
    parser->setProperty(XMLUni::fgXercesScannerName, XMLUni::fgIGXMLScanner);

    // Specify other parser features, e.g.
    parser->setFeature(XMLUni::fgDOMNamespaces, doNamespaces);
    parser->setFeature(XMLUni::fgXercesSchema, doSchema);

Copyright © 2001 The Apache Software Foundation. All Rights Reserved.