diff --git a/doc/migration.xml b/doc/migration.xml
index d4a7f7757e3cf27927d6e53b14712ae6a662266c..fa54121797a481b23b4663791f87bf301185874a 100644
--- a/doc/migration.xml
+++ b/doc/migration.xml
@@ -16,39 +16,206 @@
<p>Topics discussed are:</p>
<ul>
<li><link anchor="NewFeatures">New features in &XercesCName; &XercesCVersion;</link></li>
- <li><link anchor="LibraryChange">Library Name change in &XercesCName; &XercesCVersion;</link></li>
- <li><link anchor="DirChange">Directory change in &XercesCName; &XercesCVersion;</link></li>
- <li><link anchor="API">Public API Changes in &XercesCName; &XercesCVersion;</link></li>
+ <li><link anchor="LibraryChange">Unix Library Name change</link></li>
+ <li><link anchor="DirChange">DOM Reorganization</link></li>
+ <li><link anchor="Reuse">Reuse Grammar becomes Grammar Caching</link></li>
+ <li><link anchor="API">Public API Changes</link></li>
<ul>
<li><link anchor="NewAPI">New Public API</link></li>
<li><link anchor="ModifiedAPI">Modified Public API</link></li>
- <li><link anchor="DeprecatedAPI">Deprecated Public API</link></li>
+ <li><link anchor="DeprecatedAPI">Deprecated/Removed Public API</link></li>
</ul>
</ul>
<anchor name="NewFeatures"/>
<s3 title="New features in &XercesCName; &XercesCVersion;">
<ul>
- <li></li>
+ <li>64 bit binaries distribution</li>
+ <li>Follow Unix Shared Library Naming Convention</li>
+ <li>Apache Recommended DOM C++ Binding</li>
+ <li>Experimental DOM Level 3 subset support, including DOMWriter and DOMBuilder</li>
+ <li>Grammar preparsing and Grammar caching</li>
+ <li>Optionally ignore loading of external DTD</li>
+ <li>Project files for Microsoft Visual C++ .Net</li>
+ <li>Codewarrior 8 support</li>
+ <li>plus many more bug fixes and performance enhancement</li>
</ul>
</s3>
<anchor name="LibraryChange"/>
- <s3 title="Library Name Change in &XercesCName; &XercesCVersion;">
- <ul>
- <li></li>
- </ul>
+ <s3 title="Unix Library Name Change">
+ <p>The Xerces-C++ UNIX Library now follows the Unix Shared Library Naming Convention (libname.so.soname).
+ It is now called:</p>
+ <ul>
+ <li>AIX</li>
+ <ul>
+ <li>&XercesCUnixLib;&XercesCUnixSoName;.so</li>
+ <li>symbolic link: &XercesCUnixLib;.so ----> &XercesCUnixLib;&XercesCUnixSoName;.so</li>
+ <li>symbolic link: &XercesCUnixLib;&XercesCUnixVersion;.so ----> &XercesCUnixLib;&XercesCUnixSoName;.so</li>
+ </ul>
+ <li>Solaris / Linux</li>
+ <ul>
+ <li>&XercesCUnixLib;.so.&XercesCUnixSoName;</li>
+ <li>symbolic link: &XercesCUnixLib;.so ----> &XercesCUnixLib;.so.&XercesCUnixSoName;</li>
+ <li>symbolic link: &XercesCUnixLib;.so.&XercesCUnixVersion; ----> &XercesCUnixLib;.so.&XercesCUnixSoName;</li>
+ </ul>
+ <li>HP-UX</li>
+ <ul>
+ <li>&XercesCUnixLib;.sl.&XercesCUnixSoName;</li>
+ <li>symbolic link: &XercesCUnixLib;.sl ----> &XercesCUnixLib;.sl.&XercesCUnixSoName;</li>
+ <li>symbolic link: &XercesCUnixLib;.sl.&XercesCUnixVersion; ----> &XercesCUnixLib;.sl.&XercesCUnixSoName;</li>
+ </ul>
+ </ul>
</s3>
<anchor name="DirChange"/>
- <s3 title="Directory change in &XercesCName; &XercesCVersion;">
- <ul>
- <li></li>
- </ul>
+ <s3 title="DOM Reorganization">
+ <p>1. The old Java-like DOM is now deprecated, and all the associated files, including the headers
+ and DOMParser files are moved to <code>src/xercesc/dom/deprecated</code>. Users of the old
+ Java-like DOM are required to change all their #include lines to pick up the headers.
+ For example</p>
+<source>
+//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;
+}
+</source>
+ <p> should now change to </p>
+<source>
+//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;
+}
+</source>
+ <p>2. The Experimental IDOM is now renamed, and becomes the Apache Recommended DOM C++ Binding.
+ The following changes are made: </p>
+ <ul>
+ <li>class names are renamed from IDOM_XXXX to DOMXXXX, e.g. IDOM_Document to DOMDocument</li>
+ <li>and thus header files are renamed from IDOM_XXXX.hpp to DOMXXXX.hpp and are moved
+ to <code>src/xercesc/dom</code></li>
+ <li>the IDOMParser is renamed to XercesDOMParser. And thus the header
+ file is renamed as well</li>
+ <li>the rest is the same, see
+ <jump href="ApacheDOMC++Binding.html">Apache Recommended DOM C++ binding</jump>
+ and <jump href="program-dom.html">DOM Programming Guide</jump> for more programming
+ information</li>
+ </ul>
+ <p>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</p>
+<source>
+//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;
+}
+</source>
+ <p> should now change to </p>
+<source>
+//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;
+}
+</source>
+ </s3>
+
+ <anchor name="Reuse"/>
+ <s3 title="Reuse Grammar becomes Grammar Caching">
+ <p>The &XercesCName; &XercesCVersion; 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:</p>
+<source>
+
+ 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);
+
+</source>
+ <p>should now use the features cacheGrammarFromParse and useCachedGrammarFromParse:</p>
+<source>
+ 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();
+</source>
+
+ <p>Note there are a number of differences between "Reuse Grammar" and "Grammar Caching" </p>
+ <ol>
+ <li>"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.</li>
+ <li>"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).</li>
+ <li>Plus "Grammar Caching" has much more functionalities other than above
+ (like "Pre-parsing Grammar"). Please refer to
+ <jump href="program-others.html#GrammarCache">Preparsing Grammar and Grammar Caching
+ </jump> for more programming details.</li>
+ </ol>
</s3>
<anchor name="API"/>
- <s3 title="Public API Changes in &XercesCName; &XercesCVersion;">
+ <s3 title="Public API Changes">
<p>The following lists the public API changes between the &XercesCName;
1.7.0; and the &XercesCName; &XercesCVersion; releases
@@ -57,21 +224,87 @@
<anchor name="NewAPI"/>
<s4 title="New Public API">
<ul>
- <li></li>
+ <li>To support DOM Level 3, the following are added (see
+ <jump href="api.html">the API documentation page</jump> for details).</li>
+ <ul>
+ <li>DOMNode functions set/getUserData, isSameNode isEqualNode.</li>
+ <li>DOMDocument functions renameNode, get/setActualEncoding, get/setEncoding, get/setVersion, get/setStandalone, get/setDocumentURI.</li>
+ <li>DOMEntity functions get/setActualEncoding, get/setEncoding, get/setVersion.</li>
+ <li>classes AbstractDOMParser, DOMError, DOMErrorHandler, and DOMLocator.</li>
+ <li>classes DOMUserDataHandler, DOMImplementationRegistry and DOMImplementationSource.</li>
+ <li>classes DOMBuilder, DOMEntityResolver, DOMImplementationLS, DOMInputSource,
+ Wrapper4DOMInputSource and Wrapper4InputSource.</li>
+ <li>classes DOMWriter, DOMWriterFilter, LocalFileFormatTarget, StdOutFormatTarget,
+ and MemBufFormatTarget</li>
+ </ul>
+ <li>To support DOMWriter, the following PlatformUtils functions are added</li>
+ <ul>
+ <li></li>
+ </ul>
+ <li>To have Apache Recommended DOM C++ Binding, the following are added (see
+ <jump href="ApacheDOMC++Binding.html">Apache Recommended DOM C++ binding).</jump></li>
+ <ul>
+ <li>function release() to fix Memory Management problem</li>
+ <li>classes DOMDocumentRange and DOMDocumentTraversal</li>
+ <li>XMLSize_t is used to represent unsigned integral type in DOM</li>
+ <li>IDOM_XXXX classes are renamed to DOMXXXX, and IDOMParser is renamed to XercesDOMParser
+ as described in <link anchor="DirChange">DOM Reorganization</link></li>
+ <li>XercesDOMParser::adoptDocument is added so that document can optionally live
+ outside the parser.</li>
+ </ul>
+ <li>To support optionally load external DTD, the following are added:</li>
+ <ul>
+ <li>XercesDOMParser::set/getLoadExternalDTD</li>
+ <li>DOMParser::set/getLoadExternalDTD</li>
+ <li>SAXParser::set/getLoadExternalDTD</li>
+ <li>and SAX2XMLReader will recognize the feature
+ http://apache.org/xml/features/nonvalidating/load-external-dtd</li>
+ </ul>
+ <li>To support Preparsing Grammar and Grammar Caching, the following are added:</li>
+ <ul>
+ <li></li>
+ </ul>
</ul>
</s4>
<anchor name="ModifiedAPI"/>
<s4 title="Modified Public API">
<ul>
- <li></li>
+ <li>SAXParser::getScanner() is moved from public to protected.</li>
+ <li>Grammar::getGrammarType has been added a const modifier.</li>
+ <li>Xerces features are renamed from XMLUni::fgSAX2XercesXXXX to XMLUni::fgXercesXXXX
+ so that they can be shared with DOM parser.</li>
+ <li>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
+ <link anchor="Reuse">Reuse Grammar becomes Grammar Caching</link>.</li>
+ <ul>
+ <li>(in SAXParser, DOMParser, and XercesDOMParser) </li>
+ <li>parse(const InputSource& source, const bool reuseGrammar = false);</li>
+ <li>parse(const XMLCh* const systemId, const bool reuseGrammar = false);</li>
+ <li>parse(const char* const systemId, const bool reuseGrammar = false);</li>
+ <li>parseFirst(const InputSource& source, XMLPScanToken& toFill, const bool reuseGrammar = false);</li>
+ <li>parseFirst(const XMLCh* const systemId, XMLPScanToken& toFill, const bool reuseGrammar = false);</li>
+ <li>parseFirst(const char* const systemId, XMLPScanToken& toFill, const bool reuseGrammar = false);</li>
+ </ul>
</ul>
</s4>
<anchor name="DeprecatedAPI"/>
- <s4 title="Deprecated Public API">
+ <s4 title="Deprecated/Removed Public API">
<ul>
- <li></li>
+ <li>The old Java-like DOM is now deprecated as described in
+ <link anchor="DirChange">DOM Reorganization</link></li>
+ <li>SAX2XMLReader::setValidationConstraint. For consistency, SAX2XMLReader users should
+ set the feature http://apache.org/xml/features/validation-error-as-fatal" instead.</li>
+ <li>SAX2XMLReader::setExitOnFirstFatalError. For consistency, SAX2XMLReader users should
+ set the feature "http://apache.org/xml/features/continue-after-fatal-error" instead.</li>
+ <li>With the new Grammar Caching introduced, the following features will not be
+ recognized by the SAX2XMLReader:</li>
+ <ul>
+ <li>http://apache.org/xml/features/validation/reuse-grammar</li>
+ <li>http://apache.org/xml/features/validation/reuse-validator</li>
+ </ul>
</ul>
</s4>