Xerces-C++ contains an implementation of the W3C XML Schema
Language. See the XML Schema Support page for details.
In addition to using the
parse() method to parse an XML File.
You can use the other two parsing methods,
to do the so called progressive parsing. This way you don't
have to depend on throwing an exception to terminate the
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 propagated from the core scanning code to the parser (and
hence either on to you if using SAX/SAX2 or into the DOM tree if
You can quit the parse any time by just not
parseNext() anymore and breaking out of the loop. When
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
// Create a progressive scan token
if (!parser.parseFirst(xmlFile, token))
cerr << "scanFirst() failed\n" << endl;
// 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')
is watching for some criteria and will
return a status from its
getDone() method. Since
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
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
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
|Pre-parsing Grammar and Grammar Caching|
Xerces-C++ provides a function to pre-parse the grammar so that users
can check for any syntax error before using the grammar. Users can also optionally
cache these pre-parsed grammars for later use during actual parsing.
Here is an example:
// Enable schema processing.
// 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:
// 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.
// Let's parse our xml file (DTD grammar)
// 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.
// Enable schema processing
// Enable grammar caching
// Let's parse the XML document. The parser will cache any grammars encountered.
// 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++)
// This will flush the grammar pool
* 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
// Parse xml files
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 namespace for schema or same system
id for DTD), the entire set will not be cached. This behavior is the default but can
be overridden for XML Schema caching. See the SAX/SAX2/DOM parser features for details.
- 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.
The Xerces-C++ supports loadable message text. Although
the current distribution only supports English, it is capable of
languages. Anyone interested in contributing any translations
should contact us. This would be an extremely useful
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/NLS/Xlat/ directory,
which can translate 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.
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, IBM1047 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
All platform dependent code in Xerces-C++ has been
isolated to a couple of files, which should ease the porting
contains all such files. In particular:
contains implementations of file managers for various
contains implementations of mutex managers for various
provide base definitions for various platforms.
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
Finally, you need to decide about how to define XMLCh. Generally,
XMLCh should be defined to be a type suitable for holding a
utf-16 encoded (16 bit) value, usually an
All XML data is handled within Xerces-C++ as strings of
XMLCh characters. Regardless of the size of the
type chosen, the data stored in variables of type XMLCh
will always be utf-16 encoded values.
Unlike XMLCh, the encoding
of wchar_t is platform dependent. Sometimes it is utf-16
(AIX, Windows), sometimes ucs-4 (Solaris,
Linux), sometimes it is not based on Unicode at all
(HP/UX, AS/400, system 390).
Some earlier releases of Xerces-C++ defined XMLCh to be the
same type as wchar_t on most platforms, with the goal of making
it possible to pass XMLCh strings to library or system functions
that were expecting wchar_t parameters. This approach has
been abandoned because of
Portability problems with any code that assumes that
the types of XMLCh and wchar_t are compatible
- Excessive memory usage, especially in the DOM, on
platforms with 32 bit wchar_t.
- utf-16 encoded XMLCh is not always compatible with
ucs-4 encoded wchar_t on Solaris and Linux. The
problem occurs with Unicode characters with values
greater than 64k; in ucs-4 the value is stored as
a single 32 bit quantity. With utf-16, the value
will be stored as a "surrogate pair" of two 16 bit
values. Even with XMLCh equated to wchar_t, xerces will
still create the utf-16 encoded surrogate pairs, which
are illegal in ucs-4 encoded wchar_t strings.
Certain applications wish to maintain precise control over
memory allocation. This enables them to recover more easily
from crashes of individual components, as well as to allocate
memory more efficiently than a general-purpose OS-level
procedure with no knowledge of the characteristics of the
program making the requests for memory. In Xerces-C++ this
is supported via the Pluggable Memory Handler.
Users who wish to implement their own MemoryManager,
an interface found in
need to implement only two methods:
// This method allocates requested memory.
// the parameter is the requested memory size
// A pointer to the allocated memory is returned.
virtual void* allocate(XMLSize_t size) = 0;
// This method deallocates memory
// The parameter is a pointer to the allocated memory to be deleted
virtual void deallocate(void* p) = 0;
To maximize the amount of flexibility that applications
have in terms of controlling memory allocation, a
MemoryManager instance may be set as part of the call to
XMLPlatformUtils::Initialize() to allow for static
initialization to be done with the given MemoryHandler; a
(possibly different) MemoryManager may be passed in to the
constructors of all Xerces parser objects as well, and all
dynamic allocations within the parsers will make use of this
object. Assuming that MyMemoryHandler is a class that
implements the MemoryManager interface, here is a bit of
pseudocode which illustrates these ideas:
MyMemoryHandler *mm_for_statics = new MyMemoryHandler();
MyMemoryHandler *mm_for_particular_parser = new MyMemoryManager();
// initialize the parser information; try/catch
// removed for brevity
// create a parser object
XercesDOMParser *parser = new
If a user provides a MemoryManager object to the parser, then
the user owns that object. It is also important to note that
Xerces-C++ default implementation simply uses the global
new and delete operators.
For performance and modularity Xerces-C++ provides a mechanism
for specifying the scanner to be used 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: