http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Home

Readme
Installation
Build

Downloads

API Docs
Samples
Programming
Migration
FAQs

Releases
Caveats
Feedback

Questions
 

Answers
 
Why does my application crash on AIX when I run it under a multi-threaded environment?
 

AIX maintains two kinds of libraries on the system, thread-safe and non-thread safe. Multi-threaded libraries on AIX follow a different naming convention, Usually the multi-threaded library names are followed with "_r". For example, libc.a is single threaded whereas libc_r.a is multi-threaded.

To make your multi-threaded application run on AIX, you MUST ensure that you do not have a 'system library path' in your LIBPATH environment variable when you run the application. The appropriate libraries (threaded or non-threaded) are automatically picked up at runtime. An application usually crashes when you build your application for multi-threaded operation but don't point to the thread-safe version of the system libraries. For example, LIBPATH can be simply set as:

LIBPATH=$HOME/<Xerces>/lib

Where <Xerces> points to the directory where Xerces application resides.

If for any reason, unrelated to Xerces, you need to keep a 'system library path' in your LIBPATH environment variable, you must make sure that you have placed the thread-safe path before you specify the normal system path. For example, you must place /lib/threads before /lib in your LIBPATH variable. That is to say your LIBPATH may look like this:

export LIBPATH=$HOME/<Xerces>/lib:/usr/lib/threads:/usr/lib

Where /usr/lib is where your system libraries are.


What compilers are being used on the supported platforms?
 

Xerces has been built on the following platforms with these compilers

Operating System  Compiler 
Windows NT SP5/98  MSVC 6.0 
Redhat Linux 6.0  gcc 
AIX 4.1.4 and higher  xlC 3.1 
Solaris 2.6  CC version 4.2 
HP-UX B10.2  aCC and CC 
HP-UX B11  aCC and CC 

I cannot run my sample applications. What is wrong?
 

In order to run an application built using Xerces you must set up your path and library search path properly. In the standalone version from Apache, you must have the Xerces-C runtime library available from your path settings. On Windows this library is called xerces-c_1.dll which must be available from your PATH settings. On UNIX platforms the library is called libxerces-c1_1.so (or .a or .sl) which must be available from your LD_LIBRARY_PATH (or SHLIB_PATH or LIBPATH) environment variable.

Thus, if you installed your binaries under $HOME/fastxmlparser, you need to point your library path to that directory.

export LIBPATH=$LIBPATH:$HOME/fastxmlparser/lib # (AIX)
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/fastxmlparser/lib # (Solaris, Linux)
export SHLIB_PATH=$SHLIB_PATH:$HOME/fastxmlparser/lib # (HP-UX)

If you are using the enhanced version of this parser from IBM, you will need to put in two additional DLLs. In the Windows build these are icuuc.dll and icudata.dll which must be available from your PATH settings. On UNIX, these libraries are called libicu-uc.so and libicudata.so (or .sl for HP-UX or .a for AIX) which must be available from your library search path.


I just built my own application using the Xerces parser. Why does it crash?
 

In order to work with the Xerces parser, you have to first initialize the XML subsystem. The most common mistake is to forget this initialization. Before you make any calls to Xerces APIs, you must call

XMLPlatformUtils::Initialize():
try {
   XMLPlatformUtils::Initialize();
}
catch (const XMLException& toCatch) {
   // Do your failure processing here
}

This initializes the Xerces system and sets its internal variables. Note that you must the include util/PlatformUtils.hpp file for this to work.


Is Xerces thread-safe?
 

This is not a question that has a simple yes/no answer. Here are the rules for using Xerces in a multi-threaded environment:

Within an address space, an instance of the parser may be used without restriction from a single thread, or an instance of the parser can be accessed from multiple threads, provided the application guarantees that only one thread has entered a method of the parser at any one time.

When two or more parser instances exist in a process, the instances can be used concurrently, and without external synchronization. That is, in an application containing two parsers and two threads, one pareser can be running within the first thread concurrently with the second parser running within the second thread.

The same rules apply to Xerces DOM documents - multiple document instances may be concurrently accessed from different threads, but any given document instance can only be accessed by one thread at a time.

DOMStrings allow multiple concurrent readers. All DOMString const methods are thread safe, and can be concurrently entered by multiple threads. Non-const DOMString methods, such as appendData(), are not thread safe and the application must guarantee that no other methods (including const methods) are executed concurrently with them.


Why does my multi-threaded application crash on Solaris?
 

The problem appears because the throw call on Solaris 2.6 is not multi-thread safe. Sun Microsystems provides a patch to solve this problem. To get the latest patch for solving this problem, go to SunSolve.sun.com and get the appropriate patch for your operating system. For Intel machines running Solaris, you need to get Patch ID 104678. For SPARC machines you need to get Patch ID #105591.


How do I find out what version of Xerces I am using?
 

The version string for Xerces happens to be in one of the source files. Look inside the file src/util/XML4CDefs.hpp and find out what the static variable gXML4CFullVersionStr is defined to be. (It is usually of type 3.0.0 or something similar). This is the version of XML you are using.

If you don't have the source code, you have to find the version information from the shared library name. On Windows NT/95/98 right click on the DLL name xerces-c_1.dll in the bin directory and look up properties. The version information may be found on the Version tab.

On AIX, just look for the library name libxerces-c1_1.a (or libxerces-c1_1.so on Solaris/Linux and libxerces-c1_1.sl on HP-UX). The version number is coded in the name of the library.


How do I uninstall Xerces?
 

Xerces only installs itself in a single directory and does not set any registry entries. Thus, to un-install, you only need to remove the directory where you installed it, and all Xerces related files will be removed.


How are entity reference nodes handled in DOM?
 

If you are using the native DOM classes, the function setExpandEntityReferences controls how entities appear in the DOM tree. When setExpandEntityReferences is set to false (the default), an occurance of an entity reference in the XML document will be represented by a subtree with an EntityReference node at the root whose children represent the entity expansion. Entity expansion will be a DOM tree representing the structure of the entity expansion, not a text node containing the entity expansion as text.

If setExpandEntityReferences is true, an entity reference in the XML document is represented by only the nodes that represent the entity expansion. The DOM tree will not contain any entityReference nodes.


What kinds of URLs are currently supported in Xerces?
 

The XMLURL class provides for limited URL support. It understands the file://, http://, and ftp:// URL types, and is capable or parsing them into their constituent components, and normalizing them. It also supports the commonly required action of conglomerating a base and relative URL into a single URL. In other words, it performs the limited set of functions required by an XML parser.

Another thing that URLs commonly do are to create an input stream that provides access to the entity referenced. The parser, as shipped, only supports this functionality on URLs in the form file:/// and file://localhost/, i.e. only when the URL refers to a local file.

You may enable support for HTTP and FTP URLs by implementing and installing a NetAccessor object. When a NetAccessor object is installed, the URL class will use it to create input streams for the remote entities refered to by such URLs.


How can I add support for URL's with HTTP/FTP protocols?
 

To address the need to make remote connections to resources specified using other protocols like HTTP, FTP etc..., Xerces-C now provides the NetAccessor interface. The header file is src/util/XMLNetAccessor.hpp. This interface allows you to plug in your own implementation of URL networking code into the Xerces-C parser.

One such implementation (tested minimally under WinNT only) is already provided in Xerces-C source code drop, using W3C's Libwww library. Libwww is available for free and has been ported to various platforms. Click here to read how you can rebuild Xerces-C binaries with this implementation.

Some more notes about the NetAccessor implementation using Libwww:

  • This implementation only supports HTTP and does not return adequate error messages when connections cannot be made to the remote resources. It however illustrates how you can add support for HTTP and FTP URL's.
  • The Xerces-C team will NOT be able to address any questions related to how things work in Libwww. You can get some help with Libwww by subscribing to the <www-lib@w3.org> public mailing list.
  • However, we will welcome any feedback on the design of the NetAccessor interface. Please send all such feedback to xerces-dev@xml.apache.org.
  • You do not have to recompile Xerces-C to plugin your NetAccessor implementation. You can simply point the static pointer variable XMLPlatformUtils::fgNetAccessor to an instance of your NetAccessor implementation. Please refer to the files src/util/PlatformUtils.cpp and src/util/Platforms/Win32/Win32PlatformUtils.cpp to see how we have done this simple illustrative implementation.

Can I use Xerces to parse HTML?
 

Yes, if it follows the XML spec rules. Most HTML, however, does not follow the XML rules, and will therefore generate XML well-formedness errors.


I keep getting an error: "invalid UTF-8 character". What's wrong?
 

There are many Unicode characters that are not allowed in your XML document, according to the XML spec. Typical disallowed characters are control characters, even if you escape them using the Character Reference form: See the XML spec, sections 2.2 and 4.1 for details. If the parser is generating this error, it is very likely that there's a character in there that you can't see. You can generally use a UNIX command like "od -hc" to find it.

Another reason for this error is that your file is in some non UTF/ASCII encoding but you gave no encoding="" string in your file to tell the parser what its real encoding is.


What encodings are supported by Xerces-C / XML4C?
 

Xerces-C has intrinsic support for ASCII, UTF-8, UTF-16 (Big/Small Endian), UCS4 (Big/Small Endian), EBCDIC code pages IBM037 and IBM1140 encodings, ISO-8859-1 (aka Latin1) and Windows-1252. This means that it can parse input XML files in these above mentioned encodings.

XML4C - the version of Xerces-C available from IBM - extends this set to include the encodings listed in the table below.

Common Name  Use this name in XML 
8 bit Unicode  UTF-8 
ISO Latin 1  ISO-8859-1 
ISO Latin 2  ISO-8859-2 
ISO Latin 3  ISO-8859-3 
ISO Latin 4  ISO-8859-4 
ISO Latin Cyrillic  ISO-8859-5 
ISO Latin Arabic  ISO-8859-6 
ISO Latin Greek  ISO-8859-7 
ISO Latin Hebrew  ISO-8859-8 
ISO Latin 5  ISO-8859-9 
EBCDIC US  ebcdic-cp-us 
EBCDIC with Euro symbol  ibm1140 
Chinese, PRC  gb2312 
Chinese, Big5  Big5 
Cyrillic  koi8-r 
Japanese, Shift JIS  Shift_JIS 
Korean, Extended UNIX code  euc-kr 

Some implementations or ports of Xerces-C provide support for additional encodings. The exact set will depend on the supplier of the parser and on the character set transcoding services in use.


What character encoding should I use when creating XML documents?
 

The best choice in most cases is either utf-8 or utf-16. Advantages of these encodings include

  • The best portability. These encodings are more widely supported by XML processors than any others, meaning that your documents will have the best possible chance of being read correctly, no matter where they end up.
  • Full international character support. Both utf-8 and utf-16 cover the full Unicode character set, which includes all of the characters from all major national, international and industry character sets.
  • Efficient. utf-8 has the smaller storage requirements for documents that are primarily composed of of characters from the Latin alphabet. utf-16 is more efficient for encoding Asian languages. But both encodings cover all languages without loss.

The only drawback of utf-8 or utf-16 is that they are not the native text file format for most systems, meaning that common text file editors and viewers can not be directly used.

A second choice of encoding would be any of the others listed in the table above. This works best when the xml encoding is the same as the default system encoding on the machine where the XML document is being prepared, because the document will then display correctly as a plain text file. For UNIX systems in countries speaking Western European languages, the encoding will usually be iso-8859-1.

The versions of Xerces, both C and Java, distributed by IBM as XML4C and XML4J, include all of the encodings listed in the above table, on all platforms.

A word of caution for Windows users: The default character set on Windows systems is windows-1252, not iso-8859-1. While Xerces-c does recognize this Windows encoding, it is a poor choice for portable XML data because it is not widely recoginized by other XML processing tools. If you are using a Windows based editing tool to generate XML, check which character set it generates, and make sure that the resulting XML specifies the correct name in the encoding="..." declaration.


Is EBCDIC supported?
 

Yes, Xerces-C supports EBCDIC. When creating EBCDIC encoded XML data, the preferred encoding is ibm1140. Also supported is ibm037 (and its alternate name, ebcdic-cp-us); this encoding is almost the same as ibm1140, but it lacks the Euro symbol

These two encodings, ibm1140 and ibm037, are available on both Xerces-C and IBM XML4C, on all platforms.

On IBM System 390, XML4C also supports two alternative forms, ibm037-s390 and ibm1140-s390. These are similar to the base ibm037 and ibm1140 encodings, but with alternate mappings of the EBCDIC new-line character, which allows them to appear as normal text files on System 390s. These encodings are not supported on other platforms, and should not be used for portable data.

XML4C on System 390 and AS/400 also provides additional EBCDIC encodings, including those for the character sets of different countries. The exact set supported will be platform dependent, and these encodings are not recommended for portable XML data.




Copyright © 2000 The Apache Software Foundation. All Rights Reserved.