| Unpacking the Files |

Xerces-J is packaged as a ZIP file for all platforms and operating systems. The parser release is also packaged as Tar GZip files as a convenience for UNIX users. You can extract the ZIP files using the Java jar command to unpack the distribution.

    jar xf Xerces-J-bin.2.9.1.zip
    jar xf Xerces-J-src.2.9.1.zip
    jar xf Xerces-J-tools.2.9.1.zip

All of these commands create a sub-directory called "xerces-2_9_1" in the current directory, except for the command to unpack the "tools" distribution, since you may install this anywhere you like.

| Files in the Binary Package |

LICENSE | License for Xerces-J
NOTICE | NOTICE file for Xerces-J
LICENSE.resolver.txt | License for the XML Commons Resolver
NOTICE.resolver.txt | NOTICE file for the XML Commons Resolver
LICENSE.serializer.txt | License for the Apache Xalan serializer
NOTICE.serializer.txt | NOTICE file for the Apache Xalan serializer
LICENSE-SAX.html | SAX License
LICENSE.DOM-documentation.html | W3C Document License
LICENSE.DOM-software.html | W3C Software License
Readme.html | Web page redirect to docs/html/index.html
resolver.jar | Jar file containing the XML Commons Resolver. Currently Resolver 1.2 is distributed with Xerces-J.
serializer.jar | Jar file containing the Apache Xalan serializer. Currently the serializer included in Xalan 2.7.1 is distributed with Xerces-J.
xercesImpl.jar | Jar file containing all the parser class files that implement one of the standard APIs supported by the parser
xml-apis.jar | Jar file containing all the standard APIs implemented by the parser. Currently Xerces-J supports DOM level 3, SAX 2.0.2, and the `javax.xml.datatype`, `javax.xml.parsers` and `javax.xml.validation` parts of JAXP 1.3.
xercesSamples.jar | Jar file containing all sample class files
data/ | Directory containing sample XML data files
docs/ | Directory containing documentation
docs/javadocs/ | Directory containing Javadoc API for parser framework
samples/ | Directory containing the source code for the samples

| To use Xerces-J you do not need the source files. However, if you want to recompile the sources you need to download the source package and have the contents of the tools package (or equivalent) available.

| xerces.jar is no longer available in the main distribution. You can still download this jar from deprecated distribution. xerces.jar is a Jar file that contains all the parser class files (i.e., it contains the intersection of the contents of xercesImpl.jar and xml-apis.jar).

| Files in the Source Package |

LICENSE | License for Xerces-J
NOTICE | NOTICE file for Xerces-J
LICENSE.resolver.txt | License for the XML Commons Resolver
NOTICE.resolver.txt | NOTICE file for the XML Commons Resolver
LICENSE.serializer.txt | License for the Apache Xalan serializer
NOTICE.serializer.txt | NOTICE file for the Apache Xalan serializer
LICENSE-SAX.html | SAX License
LICENSE.DOM-documentation.html | W3C Document License
LICENSE.DOM-software.html | W3C Software License
build.bat | Batch file for invoking Ant build for Windows users
build.sh | Shell script for invoking Ant build for UNIX users
build.xml | Ant build file -- read README file before building
README | Build instructions
Readme.html | Web page redirect required for building documentation
data/ | Directory containing sample XML data files
docs/ | Directory containing documentation, in XML form
samples/ | Directory containing source code for samples
src/ | Directory containing source code for parser and supplemental APIs

In order to compile the source code using Ant or to build the release distributions yourself, you must have the contents of `Xerces-J-tools.2.9.1.zip` on your classpath; i.e., you will need access to a version of Ant, Xalan, StyleBook and an XML parser such as Xerces. For ease of use, we recommend extracting `Xerces-J-tools.2.9.1.zip` in your Xerces root directory; the build.sh and build.bat scripts are written for this case.

| Changes in Xerces jar files |

In order to accommodate the very common case in which Xerces is used with an XSLT processor such as Xalan, between Xerces 2.0.0 beta 3 and beta 4 a change in the default organization of Xerces' jar files was introduced. As well as the `xercesSamples.jar` file, which we still produce, Xerces formerly came with a file called `xerces.jar`. This file contained all of the parser's functionality. Two files are now included: `xercesImpl.jar`, our implementation of various APIs, and `xml-apis.jar`, the APIs themselves. This was done so that, if your XSLT processor ships with APIs at the same level as those supported by Xerces-J, you can avoid putting `xml-apis.jar` on your classpath.

Should you wish to use the `xerces.jar` instead, we have included several Ant targets for backward compatibility. An "Ant target" is an argument given to Ant, our build tool, that tells it which portions of the `build.xml` file to apply.

If you are on a Windows system and you wish to get only the xerces.jar file, you would execute `build.bat deprecatedjars`.

If you want to regenerate new versions of the Xerces binary, source and tools distributions with the old-style jar files, you would execute `build.bat deprecatedall`. The situation is analogous for Unix users, except that `build.sh` would be used instead of `build.bat`.

For further information and more options, please look inside build.xml itself; all possibilities are documented there.

| Verifying signatures |

In order to provide security-conscious users with the best possible assurance that the Xerces distribution they have downloaded is official, "signatures" are provided for all 6 Xerces packages produced in each release. A signature is produced with cryptographic software (such as PGP or GNUPG). The cryptographic software is used to apply an algorithm that uses the secret "key" of a Xerces committer to generate a unique file from each Xerces distribution. The Xerces committer then makes a "public" key available, which the user can use, in conjunction with the downloaded distribution and the accompanying signature, to verify that the distribution was actually produced by that committer.

In order to verify the legitimacy of Xerces distributions you download, these steps should be followed:

1. Get a copy of PGP or GNUPG from the above URL's.
2. Obtain the signature of the Xerces package you wish to verify. For instance, if you want to verify the legitimacy of Xerces-bin.x.y.z.tar.gz, download the Xerces-bin.x.y.z.tar.gz.asc file from the same location as the original file was obtained.
3. Obtain a copy of the public key of the Xerces committer. While most committers have posted their keys to public "key servers", probably the easiest place to get them from is SVN. The public keys of all Xerces committers who post releases are available from the file called `KEYS` located in the root directory of the `http://svn.apache.org/repos/asf/xerces/java/trunk/` repository.
4. Add these keys to your "public" keyring. In GNUPG, you'd do this with a command like `gpg --import KEYS`.
5. Issue the command for verifying signatures appropriate for the cryptographic software you've chosen. For GNUPG, this would be `gpg --verify Xerces-J-foo.x.y.z.ext.asc Xerces-J-foo.x.y.z.ext`.

Note that, in general, it won't be necessary to acquire new copies of public keys to verify signatures for each Xerces release. This will only be necessary if a new Xerces committer has published the release.

Copyright © 1999-2007 The Apache Software Foundation. All Rights Reserved.