| <?xml version='1.0' encoding='UTF-8'?> |
| <!-- |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| --> |
| <!DOCTYPE s1 SYSTEM 'dtd/document.dtd'> |
| <s1 title='Installation'> |
| <s2 title='Unpacking the Files'> |
| <p> |
| &ParserName; 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 <ref>jar</ref> command |
| to unpack the distribution. |
| </p> |
| <source>jar xf &ParserName;-bin.&parserversion;.zip |
| jar xf &ParserName;-src.&parserversion;.zip |
| jar xf &ParserName;-tools.&parserversion;.zip</source> |
| <p> |
| All of these commands create a sub-directory called |
| "&parserdir;" in the current directory, except for the command to unpack |
| the "tools" distribution, since you may install this anywhere you like. |
| </p> |
| </s2> |
| <s2 title='Files in the Binary Package'> |
| <table> |
| <tr> |
| <td>LICENSE</td> |
| <td>License for &ParserName;</td> |
| </tr> |
| <tr> |
| <td>NOTICE</td> |
| <td>NOTICE file for &ParserName;</td> |
| </tr> |
| <tr> |
| <td>LICENSE.resolver.txt</td> |
| <td>License for the XML Commons Resolver</td> |
| </tr> |
| <tr> |
| <td>NOTICE.resolver.txt</td> |
| <td>NOTICE file for the XML Commons Resolver</td> |
| </tr> |
| <tr> |
| <td>LICENSE.serializer.txt</td> |
| <td>License for the Apache Xalan serializer</td> |
| </tr> |
| <tr> |
| <td>NOTICE.serializer.txt</td> |
| <td>NOTICE file for the Apache Xalan serializer</td> |
| </tr> |
| <tr> |
| <td>LICENSE-SAX.html</td> |
| <td>SAX License</td> |
| </tr> |
| <tr> |
| <td>LICENSE.DOM-documentation.html</td> |
| <td>W3C Document License</td> |
| </tr> |
| <tr> |
| <td>LICENSE.DOM-software.html</td> |
| <td>W3C Software License</td> |
| </tr> |
| <tr> |
| <td>Readme.html</td> |
| <td>Web page redirect to docs/html/index.html</td> |
| </tr> |
| <tr> |
| <td>resolver.jar</td> |
| <td>Jar file containing the XML Commons Resolver. Currently |
| Resolver 1.2 is distributed with &ParserName;.</td> |
| </tr> |
| <tr> |
| <td>serializer.jar</td> |
| <td>Jar file containing the Apache Xalan serializer. Currently |
| the serializer included in Xalan 2.7.1 is distributed with &ParserName;.</td> |
| </tr> |
| <tr> |
| <td>xercesImpl.jar</td> |
| <td>Jar file containing all the parser class files that implement |
| one of the standard APIs supported by the parser</td> |
| </tr> |
| <tr> |
| <td>xml-apis.jar</td> |
| <td>Jar file containing all the standard APIs implemented by |
| the parser. Currently &ParserName; supports DOM level 3, SAX |
| 2.0.2, and the <code>javax.xml.datatype</code>, |
| <code>javax.xml.parsers</code> and <code>javax.xml.validation</code> |
| parts of JAXP 1.4.</td> |
| </tr> |
| <tr> |
| <td>xercesSamples.jar</td> |
| <td>Jar file containing all sample class files</td> |
| </tr> |
| <tr> |
| <td>data/</td> |
| <td>Directory containing sample XML data files</td> |
| </tr> |
| <tr> |
| <td>docs/</td> |
| <td>Directory containing documentation</td> |
| </tr> |
| <tr> |
| <td>docs/javadocs/</td> |
| <td>Directory containing Javadoc API for parser framework</td> |
| </tr> |
| <tr> |
| <td>samples/</td> |
| <td>Directory containing the source code for the samples</td> |
| </tr> |
| </table> |
| <note> |
| To use &ParserName; 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. |
| </note> |
| <note> |
| 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). |
| </note> |
| </s2> |
| <s2 title='Files in the Source Package'> |
| <table> |
| <tr> |
| <td>LICENSE</td> |
| <td>License for &ParserName;</td> |
| </tr> |
| <tr> |
| <td>NOTICE</td> |
| <td>NOTICE file for &ParserName;</td> |
| </tr> |
| <tr> |
| <td>LICENSE.resolver.txt</td> |
| <td>License for the XML Commons Resolver</td> |
| </tr> |
| <tr> |
| <td>NOTICE.resolver.txt</td> |
| <td>NOTICE file for the XML Commons Resolver</td> |
| </tr> |
| <tr> |
| <td>LICENSE.serializer.txt</td> |
| <td>License for the Apache Xalan serializer</td> |
| </tr> |
| <tr> |
| <td>NOTICE.serializer.txt</td> |
| <td>NOTICE file for the Apache Xalan serializer</td> |
| </tr> |
| <tr> |
| <td>LICENSE-SAX.html</td> |
| <td>SAX License</td> |
| </tr> |
| <tr> |
| <td>LICENSE.DOM-documentation.html</td> |
| <td>W3C Document License</td> |
| </tr> |
| <tr> |
| <td>LICENSE.DOM-software.html</td> |
| <td>W3C Software License</td> |
| </tr> |
| <tr> |
| <td>build.bat</td> |
| <td>Batch file for invoking Ant build for Windows users</td> |
| </tr> |
| <tr> |
| <td>build.sh</td> |
| <td>Shell script for invoking Ant build for UNIX users</td> |
| </tr> |
| <tr> |
| <td>build.xml</td> |
| <td>Ant build file -- read README file before building</td> |
| </tr> |
| <tr> |
| <td>README</td> |
| <td>Build instructions</td> |
| </tr> |
| <tr> |
| <td>Readme.html</td> |
| <td>Web page redirect required for building documentation</td> |
| </tr> |
| <tr> |
| <td>data/</td> |
| <td>Directory containing sample XML data files</td> |
| </tr> |
| <tr> |
| <td>docs/</td> |
| <td>Directory containing documentation, in XML form</td> |
| </tr> |
| <tr> |
| <td>samples/</td> |
| <td>Directory containing source code for samples</td> |
| </tr> |
| <tr> |
| <td>src/</td> |
| <td> |
| Directory containing source code for parser and supplemental APIs |
| </td> |
| </tr> |
| </table> |
| <note> |
| In order to compile the source code using Ant or to build the |
| release distributions yourself, you must have the contents of |
| <code>&ParserName;-tools.&parserversion;.zip</code> |
| 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 |
| <code>&ParserName;-tools.&parserversion;.zip</code> |
| in your Xerces root directory; the build.sh and build.bat scripts |
| are written for this case. |
| </note> |
| </s2> |
| <s2 title='Files in the Build Tools Package'> |
| <table> |
| <tr> |
| <td>ant*.jar</td> |
| <td>Jar files containing Apache Ant 1.7.1 for building Xerces-J</td> |
| </tr> |
| <tr> |
| <td>ant*.LICENSE.txt</td> |
| <td>License for Apache Ant 1.7.1</td> |
| </tr> |
| <tr> |
| <td>ant*.NOTICE.txt</td> |
| <td>NOTICE file for Apache Ant 1.7.1</td> |
| </tr> |
| <tr> |
| <td>junit.jar</td> |
| <td>Jar file containing JUnit 3.8.1</td> |
| </tr> |
| <tr> |
| <td>junit.LICENSE.html</td> |
| <td>License for JUnit 3.8.1</td> |
| </tr> |
| <tr> |
| <td>resolver.jar</td> |
| <td>Jar file containing the XML Commons Resolver. Currently |
| Resolver 1.2 is distributed with &ParserName;.</td> |
| </tr> |
| <tr> |
| <td>resolver.LICENSE.txt</td> |
| <td>License for the XML Commons Resolver</td> |
| </tr> |
| <tr> |
| <td>resolver.NOTICE.txt</td> |
| <td>NOTICE file for the XML Commons Resolver</td> |
| </tr> |
| <tr> |
| <td>serializer.jar</td> |
| <td>Jar file containing the Apache Xalan serializer. Currently |
| the serializer included in Xalan 2.7.1 is distributed with &ParserName;.</td> |
| </tr> |
| <tr> |
| <td>serializer.LICENSE.txt</td> |
| <td>License for the Apache Xalan serializer</td> |
| </tr> |
| <tr> |
| <td>serializer.NOTICE.txt</td> |
| <td>NOTICE file for the Apache Xalan serializer</td> |
| </tr> |
| <tr> |
| <td>stylebook-1.0-b2.jar</td> |
| <td>Jar file containing the Apache Stylebook for building the |
| Xerces-J documentation</td> |
| </tr> |
| <tr> |
| <td>stylebook-1.0-b2.LICENSE.txt</td> |
| <td>License for the Apache Stylebook</td> |
| </tr> |
| <tr> |
| <td>xalan.jar</td> |
| <td>Jar file containing Apache Xalan 2.7.1 (required by |
| the Apache Stylebook for building the Xerces-J documentation)</td> |
| </tr> |
| <tr> |
| <td>xalan.LICENSE.txt</td> |
| <td>License for Apache Xalan 2.7.1</td> |
| </tr> |
| <tr> |
| <td>xalan.NOTICE.txt</td> |
| <td>NOTICE file for Apache Xalan 2.7.1</td> |
| </tr> |
| <tr> |
| <td>xercesImpl.jar</td> |
| <td>Jar file containing Apache Xerces-J 2.9.1 (required by |
| Apache Ant for building Xerces-J and the Apache Stylebook |
| for building its documentation)</td> |
| </tr> |
| <tr> |
| <td>xercesImpl.LICENSE.txt</td> |
| <td>License for Apache Xerces-J 2.9.1</td> |
| </tr> |
| <tr> |
| <td>xercesImpl.NOTICE.txt</td> |
| <td>NOTICE file for Apache Xerces-J 2.9.1</td> |
| </tr> |
| <tr> |
| <td>xml-apis.jar</td> |
| <td>Jar file containing Apache XML Commons External 1.4.01 |
| (required by Apache Ant for building Xerces-J)</td> |
| </tr> |
| <tr> |
| <td>xml-apis.LICENSE.txt</td> |
| <td>License for Apache XML Commons External 1.4.01</td> |
| </tr> |
| <tr> |
| <td>xml-apis.NOTICE.txt</td> |
| <td>NOTICE file for Apache XML Commons External 1.4.01</td> |
| </tr> |
| <tr> |
| <td>xml-commons-external-src.zip</td> |
| <td>Bundle containing the source of Apache XML Commons |
| External 1.4.01 (required for building the Javadoc)</td> |
| </tr> |
| <tr> |
| <td>xml-commons-external-src.LICENSE.txt</td> |
| <td>License for Apache XML Commons External 1.4.01</td> |
| </tr> |
| <tr> |
| <td>xml-commons-external-src.NOTICE.txt</td> |
| <td>NOTICE file for Apache XML Commons External 1.4.01</td> |
| </tr> |
| <tr> |
| <td>bin/</td> |
| <td>Contains scripts for Ant, a specialized Ant target for |
| building Xerces-J and a taglet for generating custom Javadoc |
| from <code>@xerces.internal</code> and <code>@xerces.experimental</code> |
| tags in the source code.</td> |
| </tr> |
| </table> |
| <note> |
| The xercesImpl.jar in the tools package is provided for building |
| Xerces-J through Ant. This jar will always be older than the |
| current release of Xerces-J and is not intended for application use. |
| </note> |
| </s2> |
| <s2 title='Changes in Xerces jar files'> |
| <p>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 <code>xercesSamples.jar</code> |
| file, which we still produce, Xerces formerly came with a file called |
| <code>xerces.jar</code>. This file contained all of the |
| parser's functionality. Two files are now included: |
| <code>xercesImpl.jar</code>, our implementation of various APIs, |
| and <code>xml-apis.jar</code>, the APIs themselves. This |
| was done so that, if your XSLT processor ships with APIs at the |
| same level as those supported by &ParserName;, you can avoid putting |
| <code>xml-apis.jar</code> on your classpath.</p> |
| |
| <p>Should you wish to use the <code>xerces.jar</code> 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 <code>build.xml</code> file to |
| apply. |
| </p> |
| |
| <p> |
| If you are on a Windows system and you wish to get only the |
| xerces.jar file, you would execute <code>build.bat |
| deprecatedjars</code>. |
| </p> |
| <p> |
| If you want to regenerate new versions of the Xerces |
| binary, source and tools distributions with the old-style jar files, |
| you would execute <code>build.bat deprecatedall</code>. |
| |
| The situation is |
| analogous for Unix users, except that <code>build.sh</code> would be |
| used instead of <code>build.bat</code>. |
| </p> |
| <p> |
| For further information and |
| more options, please look inside build.xml itself; all possibilities |
| are documented there. |
| </p> |
| </s2> |
| <s2 title="Verifying signatures"> |
| <p>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 <jump |
| href="http://www.pgp.com">PGP</jump> or <jump |
| href="http://www.gnupg.org">GNUPG</jump>). 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. |
| </p> |
| <p>In order to verify the legitimacy of Xerces distributions |
| you download, these steps should be followed:</p> |
| <ol> |
| <li> |
| Get a copy of PGP or GNUPG from the above URL's. |
| </li> |
| <li> |
| 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. |
| </li> |
| <li> |
| 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 <code>KEYS</code> located in the |
| root directory of the <code>http://svn.apache.org/repos/asf/xerces/java/trunk/</code> |
| repository. |
| </li> |
| <li> |
| Add these keys to your "public" keyring. In GNUPG, |
| you'd do this with a command like <code>gpg --import |
| KEYS</code>. |
| </li> |
| <li> |
| Issue the command for verifying signatures |
| appropriate for the cryptographic software you've |
| chosen. For GNUPG, this would be |
| <code>gpg --verify Xerces-J-foo.x.y.z.ext.asc |
| Xerces-J-foo.x.y.z.ext</code>. |
| </li> |
| </ol> |
| <p>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. |
| </p> |
| </s2> |
| </s1> |