Migration Archive

Migrating to earlier Releases

- Migrating from &XercesCName; 1.7.0 to 2.0.0
- Migrating from &XercesCName; 1.6.0 to 1.7.0
- Migrating from &XercesCName; 1.5.2 to 1.6.0
- Migrating from &XercesCName; 1.4.0 to 1.5.2
- Migrating from XML4C 2.x to 1.4.0

Migrating from &XercesCName; 1.7.0 to &XercesCName; 2.0.0

This document is a discussion of the technical differences between &XercesCName; 1.7.0 code base and the &XercesCName; 2.0.0.

Topics discussed are:

- New features in &XercesCName; 2.0.0
- Unix Library Name change
- DOM Reorganization
- Reuse Grammar becomes Grammar Caching
- Public API Changes

- New Public API
- Modified Public API
- Deprecated/Removed Public API

New features in &XercesCName; 2.0.0

- 64 bit binaries distribution
- Follow Unix Shared Library Naming Convention
- Apache Recommended DOM C++ Binding
- Experimental DOM Level 3 subset support, including DOMWriter and DOMBuilder
- Grammar preparsing and Grammar caching
- Optionally ignore loading of external DTD
- Project files for Microsoft Visual C++ .Net
- Codewarrior 8 support
- Option to enable/disable strict IANA encoding name checking
- plus many more bug fixes and performance enhancement

Unix Library Name Change

The &XercesCName; UNIX Library now follows the Unix Shared Library Naming Convention (libname.so.soname). It is now called:

- AIX

- &XercesCUnixLib;&XercesCUnixSoName;.so
- symbolic link: &XercesCUnixLib;.so ----> &XercesCUnixLib;&XercesCUnixVersion;.so
- symbolic link: &XercesCUnixLib;&XercesCUnixVersion;.so ----> &XercesCUnixLib;&XercesCUnixSoName;.so

- Solaris / Linux

- &XercesCUnixLib;.so.&XercesCUnixSoName;
- symbolic link: &XercesCUnixLib;.so ----> &XercesCUnixLib;.so.&XercesCUnixVersion;
- symbolic link: &XercesCUnixLib;.so.&XercesCUnixVersion; ----> &XercesCUnixLib;.so.&XercesCUnixSoName;

- HP-UX

- &XercesCUnixLib;.sl.&XercesCUnixSoName;
- symbolic link: &XercesCUnixLib;.sl ----> &XercesCUnixLib;.sl.&XercesCUnixVersion;
- symbolic link: &XercesCUnixLib;.sl.&XercesCUnixVersion; ----> &XercesCUnixLib;.sl.&XercesCUnixSoName;

DOM Reorganization

1. The old Java-like DOM is now deprecated, and all the associated files, including the headers and DOMParser files are moved to `src/xercesc/dom/deprecated`. Users of the old Java-like DOM are required to change all their #include lines to pick up the headers. For example

    //old code
    #include <xercesc/dom/DOM.hpp>
    #include <xercesc/dom/DOM_Document.hpp>
    #include <xercesc/parsers/DOMParser.hpp>

    void test(char* xmlFile) {
        DOMParser parser;
        parser.parse(xmlFile);
        DOM_Document doc = parser.getDocument();
        :
        return;
    }

should now change to

    //new code
    #include <xercesc/dom/deprecated/DOM.hpp>          //<==== change this include line
    #include <xercesc/dom/deprecated/DOM_Document.hpp> //<==== change this include line
    #include <xercesc/dom/deprecated/DOMParser.hpp>    //<==== change this include line

    // the rest is the same
    void test(char* xmlFile) {
        DOMParser parser;
        parser.parse(xmlFile);
        DOM_Document doc = parser.getDocument();
        :
        return;
    }

2. The Experimental IDOM is now renamed, and becomes the Apache Recommended DOM C++ Binding. The following changes are made:

- class names are renamed from IDOM_XXXX to DOMXXXX, e.g. IDOM_Document to DOMDocument
- and thus header files are renamed from IDOM_XXXX.hpp to DOMXXXX.hpp and are moved to `src/xercesc/dom`
- the IDOMParser is renamed to XercesDOMParser. And thus the header file is renamed as well
- the rest is the same, see Apache Recommended DOM C++ binding and DOM Programming Guide for more programming information

Users of IDOM are required to change all their #include lines and do a global rename of IDOMParser to XercesDOMParesr, and IDOM_XXXX to DOMXXXX. For example

    //old code
    #include <xercesc/idom/IDOM.hpp>
    #include <xercesc/idom/IDOM_Document.hpp>
    #include <xercesc/parsers/IDOMParser.hpp>

    void test(char* xmlFile) {
        IDOMParser parser;
        parser.parse(xmlFile);
        IDOM_Document* doc = parser.getDocument();
        :
        return;
    }

should now change to

    //new code
    #include <xercesc/dom/DOM.hpp>                  //<==== change this include line
    #include <xercesc/dom/DOMDocument.hpp>          //<==== change this include line
    #include <xercesc/parsers/XercesDOMParser.hpp>  //<==== change this include line

    void test(char* xmlFile) {
        XercesDOMParser parser;                           //<==== rename the IDOMParser
        parser.parse(xmlFile);
        DOMDocument* doc = parser.getDocument();          //<==== rename the IDOM_XXXX
        :
        return;
    }

Reuse Grammar becomes Grammar Caching

The &XercesCName; 2.0.0 extends the "Reuse Grammar" support by replacing it with a new feature called "Grammar Caching" which provides more flexibility in reusing grammars. Users who used to do the following:

          XercesDOMParser parser;

          // this is the first parse, just usual code as you do normal parse
          // "firstXmlFile" has a grammar (schema or DTD) specified.
          parser.parse(firstXmlFile);

          // this is the second parse, by setting second parameter to true,
          // the parser will reuse the grammar in the last parse
          // (i.e. the one in  "firstXmlFile")
          // to validate the second "anotherXmlFile".  Any grammar that is
          // specified in anotherXmlFile is IGNORED.
          //
          // Note: The anotherXmlFile cannot have any DTD internal subset.
          parser.parse(anotherXmlFile, true);

should now use the features cacheGrammarFromParse and useCachedGrammarFromParse:

          XercesDOMParser parser;

          // By setting cacheGrammarFromParse to true,
          // the parser will cache any grammars encountered in the
          // follow-on xml files, if not cached already
          parser.cacheGrammarFromParse(true);

          parser.parse(firstXmlFile);

          // By setting useCachedGrammarFromParse to true,
          // the parser will use all the previous cached grammars
          // to validate the follow-on xml files if the cached
          // grammar matches the one specified in anotherXmlFile.
          //
          // Note: The follow-on xml files cannot have any DTD internal subset.
          parser.useCachedGrammarFromParse(true);

          parser.parse(anotherXmlFile);

          // This will flush the cached grammar pool
          parser.resetCachedGrammarPool();

Note there are a number of differences between "Reuse Grammar" and "Grammar Caching"

1. "Reuse Grammar" ignores any grammar that is specified in anotherXmlFile and simply reuse whatever stored in previous parse; while "Grammar Caching" will use the cached grammar only if it matches the one specified in the anotherXmlFile. If not match, then the new grammar is parsed.
2. "Reuse Grammar" can only reuse the grammar from previous parse; while "Grammar Caching" can selectively cache many grammars from different parses and collect them all in a pool indexed by targetNamespace (for Schema) or system id (for DTD).
3. Plus "Grammar Caching" has much more functionalities other than above (like "Pre-parsing Grammar"). Please refer to Preparsing Grammar and Grammar Caching for more programming details.

Public API Changes

The following lists the public API changes between the &XercesCName; 1.7.0; and the &XercesCName; 2.0.0 releases of the parser.

New Public API

- To support DOM Level 3, the following are added (see the API documentation page for details).

- DOMNode functions set/getUserData, isSameNode isEqualNode.
- DOMDocument functions renameNode, get/setActualEncoding, get/setEncoding, get/setVersion, get/setStandalone, get/setDocumentURI.
- DOMEntity functions get/setActualEncoding, get/setEncoding, get/setVersion.
- classes AbstractDOMParser, DOMError, DOMErrorHandler, and DOMLocator.
- classes DOMUserDataHandler, DOMImplementationRegistry and DOMImplementationSource.
- classes DOMBuilder, DOMEntityResolver, DOMImplementationLS, DOMInputSource, Wrapper4DOMInputSource and Wrapper4InputSource.
- classes DOMWriter, DOMWriterFilter, LocalFileFormatTarget, StdOutFormatTarget, and MemBufFormatTarget

- To support DOMWriter, the following PlatformUtils functions are added

- openFileToWrite, writeBufferToFile

- To have Apache Recommended DOM C++ Binding, the following are added (see Apache Recommended DOM C++ binding).

- function release() to fix Memory Management problem
- classes DOMDocumentRange and DOMDocumentTraversal
- XMLSize_t is used to represent unsigned integral type in DOM
- IDOM_XXXX classes are renamed to DOMXXXX, and IDOMParser is renamed to XercesDOMParser as described in DOM Reorganization
- XercesDOMParser::adoptDocument is added so that document can optionally live outside the parser.

- To support optionally load external DTD, the following are added:

- XercesDOMParser::set/getLoadExternalDTD
- DOMParser::set/getLoadExternalDTD
- SAXParser::set/getLoadExternalDTD
- and SAX2XMLReader will recognize the feature http://apache.org/xml/features/nonvalidating/load-external-dtd

- To support Preparsing Grammar and Grammar Caching, the following are added:

- XercesDOMParser/DOMParser/SAXParser functions loadGrammar, resetCachedGrammarPool, cacheGrammarFromParse, isCachingGrammarFromParse, useCachedGrammarInParse, isUsingCachedGrammarInParse.
- SAX2XMLReader functions loadGrammar, resetCachedGrammarPool, and will recognize the features http://apache.org/xml/features/validation/cache-grammarFromParse and http://apache.org/xml/features/validation/use-cachedGrammarInParse.

- To support access to Grammar info, the following are added:

- XercesDOMParser/DOMParser/SAXParser/SAX2XMLReader functions getRootGrammar, getGrammar, getURIText.

- To support strict IANA encoding name checking, the following are added:

- class EncodingValidator.
- PlatformUtils functions strictIANAEncoding, isStrictIANAEncoding.
- XMLTransService functions strictIANAEncoding, isStrictIANAEncoding.

Modified Public API

- SAXParser::getScanner() is moved from public to protected.
- Grammar::getGrammarType has been added a const modifier.
- Xerces features are renamed from XMLUni::fgSAX2XercesXXXX to XMLUni::fgXercesXXXX so that they can be shared with DOM parser.
- With the new Grammar Caching introduced, the the last parameter "reuseGrammar" in the following API is dropped. Users should now use the "Grammar Caching" feature as described in Reuse Grammar becomes Grammar Caching.

- (in Parser, SAXParser, DOMParser, and XercesDOMParser)
- parse(const InputSource& source, const bool reuseGrammar = false);
- parse(const XMLCh* const systemId, const bool reuseGrammar = false);
- parse(const char* const systemId, const bool reuseGrammar = false);
- (in SAXParser, DOMParser, and XercesDOMParser)
- parseFirst(const InputSource& source, XMLPScanToken& toFill, const bool reuseGrammar = false);
- parseFirst(const XMLCh* const systemId, XMLPScanToken& toFill, const bool reuseGrammar = false);
- parseFirst(const char* const systemId, XMLPScanToken& toFill, const bool reuseGrammar = false);

Deprecated/Removed Public API

- The old Java-like DOM is now deprecated as described in DOM Reorganization
- SAX2XMLReader::setValidationConstraint. For consistency, SAX2XMLReader users should set the feature http://apache.org/xml/features/validation-error-as-fatal" instead.
- SAX2XMLReader::setExitOnFirstFatalError. For consistency, SAX2XMLReader users should set the feature "http://apache.org/xml/features/continue-after-fatal-error" instead.
- With the new Grammar Caching introduced, the following features will not be recognized by the SAX2XMLReader:

- http://apache.org/xml/features/validation/reuse-grammar
- http://apache.org/xml/features/validation/reuse-validator

Migrating from &XercesCName; 1.6.0 to 1.7.0

The following section is a discussion of the technical differences between &XercesCName; 1.6.0 code base and the &XercesCName; 1.7.0 code base.

New features in &XercesCName; 1.7.0

- Support SAX2-ext's DeclHandler.
- Directory sane_include reorganization: add sub-directory 'xercesc' to src / include folder. See "Directory change in &XercesCName; 1.7.0" below for detail.
- More IDOM test cases - port IDOMMemTest, and merge ThreadTest and IThreadTest.
- Support IconvFBSD in multi-threading environment.
- Use IDOM in schema processing for faster performance.
- Add Project files for BCB6.
- Port to Caldera (SCO) OpenServer.
- Support building with new MacOSURLAccessCF NetAccessor that doesn't require Carbon but can allow Xerces to live solely within CoreServices layer.

Directory change in &XercesCName; 1.7.0

- A new directory, src/xercesc is created to be the new parent directory of all src's direct subdirectories.
- And in the binary package, all the headers are distributed in include/xercesc directory.
- Migration considerations:

- Windows application,
  either change the include directories setting to "..\..\..\..\..\src\xercesc" (Projects->settings->C/C++->Preprocessor),
  or
  change the relevant #include instances in the source/header files, accordingly, eg
  #include <util/XMLString.hpp> be changed to
  #include <xercesc/util/XMLString.hpp>
- Unix application,
  either change the include search path in the Makefile to " -I <installroot>/include/xercesc",
  or
  change the relevant #include instances in the source/header files as shown above.

Public API Changes in &XercesCName; 1.7.0

The following lists the public API changes between the &XercesCName; 1.7.0 and the &XercesCName; 1.7.0 releases of the parser.

New Public API

- Added SAX2-ext's DeclHandler class. See the API documentation page for details.
- To support SAX2-ext's DeclHandler, the following new methods are added in classes DefaultHandler and SAX2XMLReader:

- void DefaultHandler::elementDecl(const XMLCh* const name, const XMLCh* const model)
- void DefaultHandler::attributeDecl(const XMLCh* const eName, const XMLCh* const aName, const XMLCh* const type, const XMLCh* const mode, const XMLCh* const value)
- void DefaultHandler::internalEntityDecl(const XMLCh* const name, const XMLCh* const value)
- void DefaultHandler::externalEntityDecl(const XMLCh* const name, const XMLCh* const publicId, const XMLCh* const systemId)
- DeclHandler* SAX2XMLReader::getDeclarationHandler() const
- void SAX2XMLReader::setDeclarationHandler(DeclHandler* const handler)

- To conform to DOM Level 2 specification, the following methods are added:

- DOM_Node DOM_NodeIterator::getRoot()
- DOM_Node DOM_TreeWalker::getRoot()
- bool DOM_Node::hasAttributes() const
- bool DOM_Element::hasAttribute(const DOMString &name) const
- bool DOM_Element::hasAttributeNS(const DOMString &namespaceURI, const DOMString &localName) const
- IDOM_Node* IDOM_NodeIterator::getRoot()
- IDOM_Node* IDOM_TreeWalker::getRoot()
- bool IDOM_Node::hasAttributes() const
- bool IDOM_Element::hasAttribute(const XMLCh* name) const
- bool IDOM_Element::hasAttributeNS(const XMLCh* namespaceURI, const XMLCh* localName) const

- To fix [Bug 5570], a copy constructor is added to DOM_Range

Modified Public API

- To conform to the SAX2 specification, the namespace-prefixes feature in SAX2 is set to off as default.
- To fix [Bug 6330], the Base64::encode and Base64::decode have been modified as follows

- static XMLByte* Base64::encode(const XMLByte* const inputData, const unsigned int inputLength, unsigned int* outputLength);
- static XMLByte* Base64::decode(const XMLByte* const inputData, unsigned int* outputLength);
- static XMLCh* decode(const XMLCh* const inputData, unsigned int* outputLength);

- To conform to DOM Level 2 specification, the DOM_Node::supports and IDOM_Node::supports are modified to

- bool DOM_Node::isSupported(const DOMString &feature, const DOMString &version) const
- bool IDOM_Node::isSupported(const XMLCh* feature, const XMLCh* version) const

Deprecated Public API

- No Deprecated Public API in this release.

Migrating from &XercesCName; 1.5.2 to 1.6.0

The following section is a discussion of the technical differences between &XercesCName; 1.5.2 code base and the &XercesCName; 1.6.0 code base.

New features in &XercesCName; 1.6.0

- Full Schema support is available in this release. See the Schema page for details.
- New sample SEnumVal to show how to enumerate the markup decls in a Schema Grammar is added.

Public API Changes in &XercesCName; 1.6.0

The following lists the public API changes between the &XercesCName; 1.5.2 and the &XercesCName; 1.6.0 releases of the parser.

New Public API

- It should not be a fatal error if a schema InputSource is not found. Add the following new methods:

- const bool InputSource::getIssueFatalErrorIfNotFound() const
- void InputSource::setIssueFatalErrorIfNotFound(const bool flag

- Allow code to take advantage of the fact that the length of the prefix and local name are known when constructing the QName. Add the following new methods:

- void QName::setNPrefix(const XMLCh*, const unsigned int)
- void QName::setNLocalPart(const XMLCh*, const unsigned int)

- To support schemaLocation and noNamespaceSchemaLocation to be specified outside the instance document, the following new methods are added:

- XMLCh* DOMParser::getExternalSchemaLocation() const
- XMLCh* DOMParser::getExternalNoNamespaceSchemaLocation() const
- void DOMParser::setExternalSchemaLocation(const XMLCh* const schemaLocation)
- void DOMParser::setExternalNoNamespaceSchemaLocation(const char* const noNamespaceSchemaLocation)
- XMLCh* IDOMParser::getExternalSchemaLocation() const
- XMLCh* IDOMParser::getExternalNoNamespaceSchemaLocation() const
- void IDOMParser::setExternalSchemaLocation(const XMLCh* const schemaLocation)
- void IDOMParser::setExternalNoNamespaceSchemaLocation(const char* const noNamespaceSchemaLocation)
- XMLCh* SAXParser::getExternalSchemaLocation() const
- XMLCh* SAXParser::getExternalNoNamespaceSchemaLocation() const
- void SAXParser::setExternalSchemaLocation(const XMLCh* const schemaLocation)
- void SAXParser::setExternalNoNamespaceSchemaLocation(const char* const noNamespaceSchemaLocation)
- and the following properties are recognized by SAX2XMLReader:

- http://apache.org/xml/properties/schema/external-schemaLocation
- http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation

- To support identity constraints, the following new method is added:

- QName* XMLAttr::getAttName() const

Modified Public API

- To support attribute constraint checking, the constant values in XMLAttDef::DefAttTypes have been re-ordered.

Deprecated Public API

- Root Element check is moved from XMLValidator to XMLScanner. Thus XMLValidator::checkRootElement() is deprecated.

Migrating from &XercesCName; 1.4.0 to 1.5.2

The following section is a discussion of the technical differences between &XercesCName; 1.4.0 code base and the &XercesCName; 1.5.2 code base.

New features in &XercesCName; 1.5.2

Schema subset support and an experimental IDOM are available in this release.

Schema Subset Support

- New function "setDoSchema" is added to DOM/SAX parser.
- New feature "http://apache.org/xml/features/validation/schema" is recognized by SAX2XMLReader.
- New classes such as SchemaValidator, TraverseSchema ... are added.
- The Scanner is enhanced to process schema.
- New sample data files personal-schema.xml and personal.xsd.
- New command line option "-s" for samples.

See the Schema page for details.

Experimental IDOM

The experimental IDOM API is a new design of the C++ DOM API. If you would like to migrate from DOM to the experimental IDOM, please refer to IDOM programming guide. Please note that this experimental IDOM API is only a prototype and is subject to change.

Changes required to migrate to &XercesCName; 1.5.2

There are some architectural changes between the &XercesCName; 1.4.0 and the &XercesCName; 1.5.2 releases of the parser, and as a result, some code has undergone restructuring as shown below.

Validator directory Reorganization

- common content model files such as DFAContentModel ... are moved to a new directory called src/validators/common
- DTD related files are moved to a new directory called src/validators/DTD
- new directory src/validators/Datatype is created to store all datatype validators
- new directory src/validators/schema is created to store Schema related files

DTDValidator

DTDValidator was design to scan, validate and store the DTD in &XercesCName; 1.4.0 or earlier. In &XercesCName; 1.5.2, this process is broken down into three components:

- new class DTDScanner - to scan the DTD
- new class DTDGrammar - to store the DTD Grammar
- DTDValidator - to validate the DTD only

Migrating from XML4C 2.x to &XercesCName; 1.4.0

The following section is a discussion of the technical differences between XML4C 2.x code base and the new &XercesCName; 1.4.0 code base.

Summary of changes required to migrate from XML4C 2.x to &XercesCName; 1.4.0

There are some major architectural changes between the 2.3.x and &XercesCName; 1.4.0 releases of the parser, and as a result the code has undergone significant restructuring. The list below mentions the public api's which existed in 2.3.x and no longer exist in &XercesCName; 1.4.0. It also mentions the &XercesCName; 1.4.0 api which will give you the same functionality. Note: This list is not exhaustive. The API docs (and ultimately the header files) supplement this information.

- `parsers/[Non]Validating[DOM/SAX]parser.hpp`
  These files/classes have all been consolidated in the new version to just two files/classes: `[DOM/SAX]Parser.hpp`. Validation is now a property which may be set before invoking the `parse`. Now, the `setDoValidation()` method controls the validation processing.
- The `framework/XMLDocumentTypeHandler.hpp` been replaced with `validators/DTD/DocTypeHandler.hpp`.
- The following methods now have different set of parameters because the underlying base class methods have changed in the 3.x release. These methods belong to one of `XMLDocumentHandler`, `XMLErrorReporter` or `DocTypeHandler` interfaces.

- `[Non]Validating[DOM/SAX]Parser::docComment`
- `[Non]Validating[DOM/SAX]Parser::doctypePI`
- `[Non]ValidatingSAXParser::elementDecl`
- `[Non]ValidatingSAXParser::endAttList`
- `[Non]ValidatingSAXParser::entityDecl`
- `[Non]ValidatingSAXParser::notationDecl`
- `[Non]ValidatingSAXParser::startAttList`
- `[Non]ValidatingSAXParser::TextDecl`
- `[Non]ValidatingSAXParser::docComment`
- `[Non]ValidatingSAXParser::docPI`
- `[Non]Validating[DOM/SAX]Parser::endElement`
- `[Non]Validating[DOM/SAX]Parser::startElement`
- `[Non]Validating[DOM/SAX]Parser::XMLDecl`
- `[Non]Validating[DOM/SAX]Parser::error`

- The following methods/data members changed visibility from `protected` in 2.3.x to `private` (with public setters and getters, as appropriate).

- `[Non]ValidatingDOMParser::fDocument`
- `[Non]ValidatingDOMParser::fCurrentParent`
- `[Non]ValidatingDOMParser::fCurrentNode`
- `[Non]ValidatingDOMParser::fNodeStack`

- The following files have moved, possibly requiring changes in the `#include` statements.

- `MemBufInputSource.hpp`
- `StdInInputSource.hpp`
- `URLInputSource.hpp`

- All the DTD validator code was moved from `internal` to separate `validators/DTD` directory.
- The error code definitions which were earlier in `internal/ErrorCodes.hpp` are now split up into the following files:

- `framework/XMLErrorCodes.hpp` - Core XML errors
- `framework/XMLValidityCodes.hpp` - DTD validity errors
- `util/XMLExceptMsgs.hpp` - C++ specific exception codes.

The Samples

The sample programs no longer use any of the unsupported util/xxx classes. They only existed to allow us to write portable samples. But, since we feel that the wide character APIs are supported on a lot of platforms these days, it was decided to go ahead and just write the samples in terms of these. If your system does not support these APIs, you will not be able to build and run the samples. On some platforms, these APIs might perhaps be optional packages or require runtime updates or some such action.

More samples have been added as well. These highlight some of the new functionality introduced in the new code base. And the existing ones have been cleaned up as well.

The new samples are:

1. PParse - Demonstrates 'progressive parse' (see below)
2. StdInParse - Demonstrates use of the standard in input source
3. EnumVal - Shows how to enumerate the markup decls in a DTD Validator

Parser Classes

In the XML4C 2.x code base, there were the following parser classes (in the src/parsers/ source directory): NonValidatingSAXParser, ValidatingSAXParser, NonValidatingDOMParser, ValidatingDOMParser. The non-validating ones were the base classes and the validating ones just derived from them and turned on the validation. This was deemed a little bit overblown, considering the tiny amount of code required to turn on validation and the fact that it makes people use a pointer to the parser in most cases (if they needed to support either validating or non-validating versions.)

The new code base just has SAXParer and DOMParser classes. These are capable of handling both validating and non-validating modes, according to the state of a flag that you can set on them. For instance, here is a code snippet that shows this in action.

    void ParseThis(const  XMLCh* const fileToParse,
                   const bool validate)
    {
      //
      // Create a SAXParser. It can now just be
      // created by value on the stack if we want
      // to parse something within this scope.
      //
      SAXParser myParser;

      // Tell it whether to validate or not
      myParser.setDoValidation(validate);

      // Parse and catch exceptions...
      try
      {
        myParser.parse(fileToParse);
      }
        ...
    };

We feel that this is a simpler architecture, and that it makes things easier for you. In the above example, for instance, the parser will be cleaned up for you automatically upon exit since you don't have to allocate it anymore.

Moved Classes to src/framework

Some of the classes previously in the src/internal/ directory have been moved to their more correct location in the src/framework/ directory. These are classes used by the outside world and should have been framework classes to begin with. Also, to avoid name classes in the absence of C++ namespace support, some of these clashes have been renamed to make them more XML specific and less likely to clash. More classes might end up being moved to framework as well.

So you might have to change a few include statements to find these classes in their new locations. And you might have to rename some of the names of the classes, if you used any of the ones whose names were changed.

Util directory Reorganization

The src/util directory was becoming somewhat of a dumping ground of platform and compiler stuff. So we reworked that directory to better spread things out. The new scheme is:

util - The platform independent utility stuff

- MsgLoaders - Holds the msg loader implementations

1. ICU
2. InMemory
3. MsgCatalog
4. Win32

- Compilers - All the compiler specific files
- Transcoders - Holds the transcoder implementations

1. Iconv
2. ICU
3. Win32

- Platforms

1. AIX
2. HP-UX
3. Linux
4. Solaris
5. ....
6. Win32

This organization makes things much easier to understand. And it makes it easier to find which files you need and which are optional. Note that only per-platform files have any hard coded references to specific message loaders or transcoders. So if you don't include the ICU implementations of these services, you don't need to link in ICU or use any ICU headers. The rest of the system works only in terms of the abstraction APIs.