Newer
Older
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s2 title="Migrating to earlier Releases">
<ul>
<li><link anchor="Migrateto170">Migrating from &XercesCName; 1.6.0 to 1.7.0</link></li>
<li><link anchor="Migrateto160">Migrating from &XercesCName; 1.5.2 to 1.6.0</link></li>
<li><link anchor="Migrateto152">Migrating from &XercesCName; 1.4.0 to 1.5.2</link></li>
<li><link anchor="Migrateto140">Migrating from XML4C 2.x to 1.4.0</link></li>
</ul>
</s2>
<anchor name="Migrateto170"/>
<s2 title="Migrating from &XercesCName; 1.6.0 to 1.7.0">
<p>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.</p>
<s3 title="New features in &XercesCName; 1.7.0">
<li>Support SAX2-ext's DeclHandler.</li>
<li>Directory sane_include reorganization: add sub-directory 'xercesc' to src / include folder.
See <link anchor="DirChange2">"Directory change in &XercesCName; 1.7.0"</link>
below for detail.</li>
<li>More IDOM test cases - port IDOMMemTest, and merge ThreadTest and IThreadTest.</li>
<li>Support IconvFBSD in multi-threading environment.</li>
<li>Use IDOM in schema processing for faster performance.</li>
<li>Add Project files for BCB6.</li>
<li>Port to Caldera (SCO) OpenServer.</li>
<li>Support building with new MacOSURLAccessCF NetAccessor that doesn't require
Carbon but can allow Xerces to live solely within CoreServices layer.</li>
</ul>
</s3>
<anchor name="DirChange2"/>
<s3 title="Directory change in &XercesCName; 1.7.0">
<li>A new directory, <em>src/xercesc</em> is created to be the new parent directory of
all src's direct subdirectories.</li>
<li>And in the binary package, all the headers are distributed in <em>include/xercesc</em> directory.</li>
<li>Migration considerations:</li>
<ul>
<li>Windows application, <br/>
either change the <em>include directories </em> setting to
"..\..\..\..\..\src\<em>xercesc</em>" (Projects->settings->C/C++->Preprocessor), <br/>
or <br/>
change the relevant #include instances in the source/header files, accordingly, eg <br/>
#include <util/XMLString.hpp> be changed to <br/>
#include <<em>xercesc</em>/util/XMLString.hpp> </li>
<li>Unix application, <br/>
either change the <em>include search path </em> in the Makefile to
" -I <installroot>/include/<em>xercesc</em>", <br/>
or <br/>
change the relevant #include instances in the source/header files as shown above. </li>
</ul>
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
</s3>
<s3 title="Public API Changes in &XercesCName; 1.7.0">
<p>The following lists the public API changes between the &XercesCName;
1.7.0 and the &XercesCName; 1.7.0 releases
of the parser. </p>
<s4 title="New Public API">
<ul>
<li>Added SAX2-ext's DeclHandler class.
See <jump href="api.html">the API documentation page</jump> for details.</li>
<li>To support SAX2-ext's DeclHandler, the following new methods are added
in classes DefaultHandler and SAX2XMLReader:</li>
<ul>
<li>void DefaultHandler::elementDecl(const XMLCh* const name, const XMLCh* const model)</li>
<li>void DefaultHandler::attributeDecl(const XMLCh* const eName, const XMLCh* const aName,
const XMLCh* const type, const XMLCh* const mode, const XMLCh* const value)</li>
<li>void DefaultHandler::internalEntityDecl(const XMLCh* const name, const XMLCh* const value)</li>
<li>void DefaultHandler::externalEntityDecl(const XMLCh* const name, const XMLCh* const publicId,
const XMLCh* const systemId)</li>
<li>DeclHandler* SAX2XMLReader::getDeclarationHandler() const</li>
<li>void SAX2XMLReader::setDeclarationHandler(DeclHandler* const handler)</li>
</ul>
<li>To conform to DOM Level 2 specification, the following methods are added:</li>
<ul>
<li>DOM_Node DOM_NodeIterator::getRoot()</li>
<li>DOM_Node DOM_TreeWalker::getRoot()</li>
<li>bool DOM_Node::hasAttributes() const</li>
<li>bool DOM_Element::hasAttribute(const DOMString &name) const</li>
<li>bool DOM_Element::hasAttributeNS(const DOMString &namespaceURI,
const DOMString &localName) const</li>
<li>IDOM_Node* IDOM_NodeIterator::getRoot()</li>
<li>IDOM_Node* IDOM_TreeWalker::getRoot()</li>
<li>bool IDOM_Node::hasAttributes() const</li>
<li>bool IDOM_Element::hasAttribute(const XMLCh* name) const</li>
<li>bool IDOM_Element::hasAttributeNS(const XMLCh* namespaceURI,
const XMLCh* localName) const</li>
</ul>
<li>To fix [Bug 5570], a copy constructor is added to DOM_Range</li>
</ul>
</s4>
<s4 title="Modified Public API">
<ul>
<li>To conform to the SAX2 specification, the namespace-prefixes feature
in SAX2 is set to off as default.</li>
<li>To fix [Bug 6330], the Base64::encode and Base64::decode have been modified
as follows</li>
<ul>
<li>static XMLByte* Base64::encode(const XMLByte* const inputData,
const unsigned int inputLength,
unsigned int* outputLength);</li>
<li>static XMLByte* Base64::decode(const XMLByte* const inputData,
unsigned int* outputLength);</li>
<li>static XMLCh* decode(const XMLCh* const inputData,
unsigned int* outputLength);</li>
</ul>
<li>To conform to DOM Level 2 specification, the DOM_Node::supports and IDOM_Node::supports
are modified to</li>
<ul>
<li>bool DOM_Node::isSupported(const DOMString &feature, const DOMString &version) const</li>
<li>bool IDOM_Node::isSupported(const XMLCh* feature, const XMLCh* version) const</li>
</ul>
</ul>
</s4>
<s4 title="Deprecated Public API">
<ul>
<li>No Deprecated Public API in this release.</li>
</ul>
</s4>
</s3>
<anchor name="Migrateto160"/>
<s2 title="Migrating from &XercesCName; 1.5.2 to 1.6.0">
<p>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.</p>
<s3 title="New features in &XercesCName; 1.6.0">
<ul>
<li>Full Schema support is available in this release.
See <jump href="schema.html">the Schema page</jump> for details.</li>
<li>New sample SEnumVal to show how to enumerate the markup decls in a Schema Grammar is added.</li>
</ul>
<s3 title="Public API Changes in &XercesCName; 1.6.0">
<p>The following lists the public API changes between the &XercesCName;
1.5.2 and the &XercesCName; 1.6.0 releases
<s4 title="New Public API">
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
<ul>
<li>It should not be a fatal error if a schema InputSource is not found.
Add the following new methods:</li>
<ul>
<li>const bool InputSource::getIssueFatalErrorIfNotFound() const</li>
<li>void InputSource::setIssueFatalErrorIfNotFound(const bool flag</li>
</ul>
<li>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:</li>
<ul>
<li>void QName::setNPrefix(const XMLCh*, const unsigned int)</li>
<li>void QName::setNLocalPart(const XMLCh*, const unsigned int)</li>
</ul>
<li>To support schemaLocation and noNamespaceSchemaLocation to be specified outside the
instance document, the following new methods are added:</li>
<ul>
<li>XMLCh* DOMParser::getExternalSchemaLocation() const</li>
<li>XMLCh* DOMParser::getExternalNoNamespaceSchemaLocation() const</li>
<li>void DOMParser::setExternalSchemaLocation(const XMLCh* const schemaLocation)</li>
<li>void DOMParser::setExternalNoNamespaceSchemaLocation(const char* const noNamespaceSchemaLocation)</li>
<li>XMLCh* IDOMParser::getExternalSchemaLocation() const</li>
<li>XMLCh* IDOMParser::getExternalNoNamespaceSchemaLocation() const</li>
<li>void IDOMParser::setExternalSchemaLocation(const XMLCh* const schemaLocation)</li>
<li>void IDOMParser::setExternalNoNamespaceSchemaLocation(const char* const noNamespaceSchemaLocation)</li>
<li>XMLCh* SAXParser::getExternalSchemaLocation() const</li>
<li>XMLCh* SAXParser::getExternalNoNamespaceSchemaLocation() const</li>
<li>void SAXParser::setExternalSchemaLocation(const XMLCh* const schemaLocation)</li>
<li>void SAXParser::setExternalNoNamespaceSchemaLocation(const char* const noNamespaceSchemaLocation)</li>
<li>and the following properties are recognized by SAX2XMLReader:</li>
<ul>
<li>http://apache.org/xml/properties/schema/external-schemaLocation</li>
<li>http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation</li>
</ul>
</ul>
<li>To support identity constraints, the following new method is added:</li>
<ul>
<li>QName* XMLAttr::getAttName() const</li>
</ul>
</ul>
<s4 title="Modified Public API">
<ul>
<li>To support attribute constraint checking, the constant values in XMLAttDef::DefAttTypes have been re-ordered.</li>
</ul>
<s4 title="Deprecated Public API">
<ul>
<li>Root Element check is moved from XMLValidator to XMLScanner. Thus XMLValidator::checkRootElement() is deprecated.</li>
</ul>
<anchor name="Migrateto152"/>
<s2 title="Migrating from &XercesCName; 1.4.0 to 1.5.2">
<p>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.</p>
<s3 title="New features in &XercesCName; 1.5.2">
<p>Schema subset support and an experimental IDOM are available
in this release.
</p>
<s4 title="Schema Subset Support">
<ul>
<li>New function "setDoSchema" is added to DOM/SAX parser.</li>
<li>New feature "http://apache.org/xml/features/validation/schema" is recognized by SAX2XMLReader.</li>
<li>New classes such as SchemaValidator, TraverseSchema ... are added.</li>
<li>The Scanner is enhanced to process schema.</li>
<li>New sample data files personal-schema.xml and personal.xsd.</li>
<li>New command line option "-s" for samples.</li>
</ul>
<p>
See <jump href="schema.html">the Schema page</jump> for details.
</p>
<s4 title="Experimental IDOM">
<p>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
<jump href="program-idom.html">
IDOM programming guide.</jump> Please note that this experimental IDOM API is only
a prototype and is subject to change.
</p>
<s3 title="Changes required to migrate to &XercesCName; 1.5.2">
<p>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. </p>
<s4 title="Validator directory Reorganization">
<ul>
<li>common content model files such as DFAContentModel ...
are moved to a new directory called src/validators/common</li>
<li>DTD related files are moved to a new directory called src/validators/DTD</li>
<li>new directory src/validators/Datatype is created to store all datatype validators</li>
<li>new directory src/validators/schema is created to store Schema related files</li>
</ul>
</s4>
<s4 title="DTDValidator">
<p> 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:
</p>
<ul>
<li>new class DTDScanner - to scan the DTD</li>
<li>new class DTDGrammar - to store the DTD Grammar</li>
<li>DTDValidator - to validate the DTD only</li>
</ul>
</s4>
<anchor name="Migrateto140"/>
<s2 title="Migrating from XML4C 2.x to &XercesCName; 1.4.0">
<p>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.</p>
<s3 title="Summary of changes required to migrate from XML4C 2.x to &XercesCName; 1.4.0">
<p>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
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
same functionality. Note: This list is not exhaustive. The
API docs (and ultimately the header files) supplement this
information.</p>
<ul>
<li><code>parsers/[Non]Validating[DOM/SAX]parser.hpp</code><br/>
These files/classes have all been consolidated in the new
version to just two files/classes:
<code>[DOM/SAX]Parser.hpp</code>. Validation is now a
property which may be set before invoking the
<code>parse</code>. Now, the
<code>setDoValidation()</code> method controls the
validation processing.</li>
<li>The <code>framework/XMLDocumentTypeHandler.hpp</code>
been replaced with
<code>validators/DTD/DocTypeHandler.hpp</code>.</li>
<li>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
<code>XMLDocumentHandler</code>,
<code>XMLErrorReporter</code> or
<code>DocTypeHandler</code> interfaces.</li>
<ul>
<li><code>[Non]Validating[DOM/SAX]Parser::docComment</code></li>
<li><code>[Non]Validating[DOM/SAX]Parser::doctypePI</code></li>
<li><code>[Non]ValidatingSAXParser::elementDecl</code></li>
<li><code>[Non]ValidatingSAXParser::endAttList</code></li>
<li><code>[Non]ValidatingSAXParser::entityDecl</code></li>
<li><code>[Non]ValidatingSAXParser::notationDecl</code></li>
<li><code>[Non]ValidatingSAXParser::startAttList</code></li>
<li><code>[Non]ValidatingSAXParser::TextDecl</code></li>
<li><code>[Non]ValidatingSAXParser::docComment</code></li>
<li><code>[Non]ValidatingSAXParser::docPI</code></li>
<li><code>[Non]Validating[DOM/SAX]Parser::endElement</code></li>
<li><code>[Non]Validating[DOM/SAX]Parser::startElement</code></li>
<li><code>[Non]Validating[DOM/SAX]Parser::XMLDecl</code></li>
<li><code>[Non]Validating[DOM/SAX]Parser::error</code></li>
</ul>
<li>The following methods/data members changed visibility
from <code>protected</code> in 2.3.x to
<code>private</code> (with public setters and getters, as
appropriate).</li>
<ul>
<li><code>[Non]ValidatingDOMParser::fDocument</code></li>
<li><code>[Non]ValidatingDOMParser::fCurrentParent</code></li>
<li><code>[Non]ValidatingDOMParser::fCurrentNode</code></li>
<li><code>[Non]ValidatingDOMParser::fNodeStack</code></li>
</ul>
<li>The following files have moved, possibly requiring
changes in the <code>#include</code> statements.</li>
<ul>
<li><code>MemBufInputSource.hpp</code></li>
<li><code>StdInInputSource.hpp</code></li>
<li><code>URLInputSource.hpp</code></li>
</ul>
<li>All the DTD validator code was moved from
<code>internal</code> to separate
<code>validators/DTD</code> directory.</li>
<li>The error code definitions which were earlier in
<code>internal/ErrorCodes.hpp</code> are now split up into
the following files:</li>
<ul>
<li><code>framework/XMLErrorCodes.hpp </code> - Core XML errors</li>
<li><code>framework/XMLValidityCodes.hpp</code> - DTD validity errors</li>
<li><code>util/XMLExceptMsgs.hpp </code> - C++ specific exception codes.</li>
</ul>
</ul>
<p>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.</p>
<p>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.</p>
<p>The new samples are:</p>
<ol>
<li>PParse - Demonstrates 'progressive parse' (see below)</li>
<li>StdInParse - Demonstrates use of the standard in input source</li>
<li>EnumVal - Shows how to enumerate the markup decls in a DTD Validator</li>
</ol>
<s3 title="Parser Classes">
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
<p>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.)</p>
<p>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.</p>
<source>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);
}
...
};</source>
<p>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.</p>
<s3 title="Moved Classes to src/framework">
<p>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.</p>
<p>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.</p>
<s3 title="Util directory Reorganization">
<p>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:
</p>
<s4 title="util - The platform independent utility stuff">
<ul>
<li>MsgLoaders - Holds the msg loader implementations</li>
<ol>
<li>ICU</li>
<li>InMemory</li>
<li>MsgCatalog</li>
<li>Win32</li>
</ol>
<li>Compilers - All the compiler specific files</li>
<li>Transcoders - Holds the transcoder implementations</li>
<ol>
<li>Iconv</li>
<li>ICU</li>
<li>Win32</li>
</ol>
<li>Platforms</li>
<ol>
<li>AIX</li>
<li>HP-UX</li>
<li>Linux</li>
<li>Solaris</li>
<li>....</li>
<li>Win32</li>
</ol>
</ul>
<p>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.</p>