|
| | |
Xerces-C++ contains an implementation of the W3C XML Schema
Language. See the Schema page for details.
|
| | |
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 for 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.6.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.cacheGrammarFromParse(true);
// Let's parse the XML document. The parser will cache any grammars encountered.
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.
|
| | |
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/NLS/Xlat/ 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.
|
| | |
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
provide.
|
| | |
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!
|
| | |
Xerces-C++ 2.6.0 supports C++ Namespace as of Version 2.2.0.
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.6.0 are built
with C++ Namespace enabled), users' applications must
namespace qualify all the Xerces-C++ classes, data and
variables with XERCES_CPP_NAMESPACE_QUALIFIER
or add the XERCES_CPP_NAMESPACE_USE
statement. Users also need to ensure all forward
declarations are properly qualified or scoped.
Note: If If C++ Namespace support is ENABLED,
XERCES_CPP_NAMESPACE_QUALIFIER expands to the
Xerces-C++ namespace name followed by two colons, and
XERCES_CPP_NAMESPACE_USE expands to the full
using namespace statement, including the
semicolon. Do NOT add colons or semicolons following these
macros in your source.
If C++ Namespace support is not enabled, both macros expand
to an empty string. The same holds for macros
XERCES_CPP_NAMESPACE_BEGIN and
XERCES_CPP_NAMESPACE_END, introduced in the
example below. You will also see all of these macros used
throughout the Xerces-C++ source code.
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);
:
:
};
| | | | |
All macros used above are defined in header file xercesc/util/XercesDefs.hpp:
| | | |
#if defined(XERCES_HAS_CPP_NAMESPACE)
#define XERCES_CPP_NAMESPACE_BEGIN namespace xercesc_2_6 {
#define XERCES_CPP_NAMESPACE_END }
#define XERCES_CPP_NAMESPACE_USE using namespace xercesc_2_6;
#define XERCES_CPP_NAMESPACE_QUALIFIER xercesc_2_6::
namespace xercesc_2_6 { }
namespace xercesc = xercesc_2_6;
#else
#define XERCES_CPP_NAMESPACE_BEGIN
#define XERCES_CPP_NAMESPACE_END
#define XERCES_CPP_NAMESPACE_USE
#define XERCES_CPP_NAMESPACE_QUALIFIER
#endif
| | | | |
Users should 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 qualify 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);
:
:
};
| | | | |
For those users who want to selectively pick which version of API to use, they can do
something like the code below (Note that this is not the best of examples, as the
API is the same in all versions):
| | | |
#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
the macro XERCES_CPP_NAMESPACE_QUALIFIER
for source compatibility:
| | | |
new XERCES_CPP_NAMESPACE_QUALIFIER SAXParser();
| | | | |
Header file xercesc/util/XercesDefs.hpp also
declares namespace xercesc as 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. However, when you use
xercesc:: instead of
XERCES_CPP_NAMESPACE_QUALIFIER when your
compiler does not support namespaces, your code will not
work.
|
| | |
The Xerces-C++ reports, through the method panic(), any panic encountered,
to the panic handler installed, which in turn takes whatever action appropriate,
to handle the panic.
The Xerces-C++ allows application plugging a customized panic handler
(class implementing the interface PanicHandler), in its very first invocation to
XMLPlatformUtils::Initialize() by supplying a parameter for the panic handler
intended.
In the absence of such a plugged panic handler, Xerces-C++ default
panic handler is installed and used, which aborts program whenever a panic
is seen.
| | | |
...
// Initialize the parser system
try
{
PanicHandler* ph = new MyPanicHandler();
XMLPlatformUtils::Initialize("en_US"
, "/usr/application_root/msg_home"
, ph);
}
catch ()
{
}
..
| | | | |
|
| | |
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. As of Xerces-C 2.3.0 this
is supported via the Pluggable Memory Handler.
Users that have no particular memory management
requirements (beyond that components don't leak memory or
attempt to read from or write to areas of memory they haven't
been assigned), should notice no behavioural changes in the
parser, so long as their code conforms to Xerces-C best
practices (e.g., avoids implicit destruction of objects
related to the parser after XMLPlatformUtils::Terminate() has
been called; see the FAQ
entry describing a reason why applications may suddenly start
segfaulting with Xerces-C 2.3.0 for details.). Such users can ignore this subsection and
continue using the parser as they always had.
Users who wish to implement their own MemoryManager,
an interface found in xercesc/framework/MemoryManager.hpp, need
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(size_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
XMLPlatformUtils::Initialize(XMLUni::fgXercescDefaultLocale, 0,0,
mm_for_statics);
// create a parser object
XercesDOMParser *parser = new
XercesDomParser(mm_for_particular_parser);
// ...
delete parser;
XMLPlatformUtils::Terminate();
| | | | |
Notice that, to maintain backward compatibility, the
MemoryManager parameter is positioned last in the list of
parameters to XMLPlatformUtils::Initialize(); this means that
all other parameters must be specified with their defaults as
found in Xerces code if all other aspects of standard
behaviour are to be preserved.
If a user provides a MemoryManager object to the parser, then
the user owns that object. It is also important to note that
Xerces default implementation simply uses the global new and
delete.
Finally, there are two platform/compiler-related
limitations of our memory handling facilities that
certain users will need to be aware of:
- The compiler shipped with HPUX 11 does not understand
"placement" delete operators. These versions of delete
have the same signature as our "placement" new operators
but will only be invoked when an exception is thrown
during the construction of an object. Since the HP
compiler does not permit delete to be overridden twice
within a class, we cannot provide a placement delete;
hence, in the few cases in which an exception may be
thrown during object construction by Xerces, destructors of objects
created during that construction will not be called.
- There is a bug in versions of GCC older than 2.96
which makes it impossible to have the pluggable memory
manager create elements in the
RefHash3KeysIdPool template hashtable.
Therefore, on this compiler, we must use global new for
this purpose. These elements will be properly destroyed
under this compiler; the limitation is that, since the
pluggable memory manager cannot be used, these particular
elements will not be destroyed if the user destroys their
memory manager directly. Note that this hashtable is not
used that often in Xerces.
|
| | |
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:
|
|
|
