This release uses Swing 1.1 (JFC 1.1). Swing is only used by the sample programs and is not required by the parser itself.

To build Xerces-J on Windows, you need a copy of Cygnus's Cygwin. See http://sourceware.cygnus.com/cygwin. Once Cygwin is installed, you need to set two environment variables. Edit the batch file BuildAll.bat to set these variables. Execute BuildAll.bat, and then set your classpath to point to the src and samples directories in the Xerces-J distribution. You can then go to the top of the Xerces-J tree and type 'make'.

To build Xerces-J Java on UNIX, you need to set an environment variable. Edit the shell script BuildAll to set this variables. Execute BuildAll, and then set your classpath to point to the src and samples directories in the Xerces-J distribution. You can then go to the top of the Xerces-J tree and type 'make'.

To regenerate the api documentation, you need to set up your environment to build Xerces-J. Instead of typing 'make', you type 'make apidocs'.

• Why does VisualAge for Java 2.0 report problems when I import the Xerces-J parser?
  The current version of the Xerces-J parser uses Swing 1.1, while VisualAge for Java 2.0 comes with Swing 1.0.2. The free update for the Professional version of VisualAge for Java 2.0 installs Swing 1.0.3. The most important difference between Swing 1.0.2 - 1.0.3 and 1.1 is the Java package was changed from com.sun.java.swing.* to javax.swing.*.
  To fix the errors, you must download the Java Foundation Classes 1.1 with Swing 1.1 from Sun's Java home page and import the "swingall.jar" file into VisualAge for Java 2.0. The Swing 1.1 package can be found at the following URL:
  http://java.sun.com/products/jfc/index.html
  Refer to the VisualAge for Java 2.0 documentation for information about how to import a JAR file into the repository and add that code to your workspace.
• Are there any other tips for importing the Xerces-J parser into VisualAge for Java 2.0?
  The most useful tip applies to any updated code that you import into the VisualAge for Java 2.0 product. Before updating code, do the following:
  1. version the old code
  2. delete it from your workspace
  3. import the new code
  Deleting code from your workspace does not actually delete the code permanently -- the versioned code is moved to the repository where it can be retrieved later. Be aware, though, that removing code from your workspace will cause problems with all of the other classes that use that code. VisualAge for Java 2.0 will flag them as errors but this situation is temporary. When you import the new code, the errors found when deleting the old code will be fixed.
  If you are unsure as to how to perform any of these steps, refer to the VisualAge for Java 2.0 documentation.

Running JavaPureCheck on the Xerces-J parser code indicated 339 pure Java classes, 9 warnings, and 0 errors. The nine warnings are enumerated below with explanations. To see the entire report, click here.

There are many common cases where JavaPureCheck issues warnings even though the code is pure Java. These are the most common reasons:

1. Warning: method reference: java.lang.Class.forName(java.lang.String)
   This warning is issued in the following two cases:
1. Program code calls the Class.forName(String) method to dynamically load a class file. In this situation, the specified class may contain impure Java code. In the cases where this method is called directly in the parser code, an explanation is provided detailing why this warning can be ignored.
2. Program code makes direct reference to an object's class. For example: Class stringClass = String.class;. In this situation the Java compiler converts String.class to the method call Class.forName("java.lang.String"). As long as the object whose class is being referenced is pure Java, the code making the reference remains pure.
2. Warning: possible hard-coded path: ...
   When a String literal contains a common path separator character (e.g. '/' or '\'), JavaPureCheck assumes that it is a hard-coded path and that the class may not contain portable code. While a human tester can verify that the string is not a path, JavaPureCheck must be conservative and issue a warning.

Explanations:

• Class: org.xml.sax.helpers.ParserFactory
• Warning: method reference: java.lang.Class.forName(java.lang.String)
• Explanation: The ParserFactory class is part of the standard SAX 1.0 distribution. The warning given that this class "may load impure class" is correct -- the ParserFactory class may load impure Java class files. However, the purpose of this utility class is to load parser classes by name and therefore cannot dynamically check the pureness of parser classes loaded in this fashion. Since the Xerces-J parser does not use this method directly, it is not a problem that concerns the Xerces-J parser.
• Class: org.apache.xml.serialize.SerializerFactory
• Warning: method reference: java.lang.Class.forName(java.lang.String)
• Explanation: The SerializerFactory supports querying a system property to dynamically instantiate a serializer by class name. However, all of the serializer classes provided in this distribution are pure. The only way to load an impure serializer is if the user provided an impure serializer implementation.
• Class: org.apache.xml.serialize.OutputFormat
• Warning: possible hard-coded path: text/xml
• Warning: possible hard-coded path: text/plain
• Warning: possible hard-coded path: application/pdf
• Warning: possible hard-coded path: text/html
• Warning: possible hard-coded path: -//W3C//DTD XHTML 1.0 Strict//EN
• Explanation: These strings are not filenames.
• Class: org.apache.xml.serialize.HTMLdtd
• Warning: method reference: java.lang.Class.forName(java.lang.String)
• Explanation: Referencing class object that is pure Java.
• Class: org.apache.html.dom.HTMLDocumentImpl
• Warning: method reference: java.lang.Class.forName(java.lang.String)
• Explanation: Referencing class object that is pure Java.
• Class: org.apache.xerces.readers.StringReader
• Warning: method reference: java.lang.Class.forName(java.lang.String)
• Explanation: Referencing class object that is pure Java.
• Class: org.apache.xerces.parsers.DOMParser
• Warning: method reference: java.lang.Class.forName(java.lang.String)
• Explanation: The DOMParser class allows the user to set the DOM implemenation to use, by name. However, the default DOM implementation is pure Java.
• Explanation: Referencing class object that is pure Java.
• Class: org.apache.xerces.utils.CharDataChunk
• Warning: method reference: java.lang.Class.forName(java.lang.String)
• Explanation: Referencing class object that is pure Java.
• Class: org.apache.xerces.utils.UTF8DataChunk
• Warning: method reference: java.lang.Class.forName(java.lang.String)
• Explanation: Referencing class object that is pure Java.

The results file of the JavaPureCheck can be viewed by clicking here.

The samples were not checked with JavaPureCheck and are not guaranteed to be pure Java. We reserve the right to write samples in the future that are platform specific and therefore may not pass as pure Java. The parser, however, will remain pure Java.

Prerequisites (available from http://developer.apple.com/java/):

• MRJ 2.1 (this is the most recent version of the JVM)
• MRJ SDK 2.1 (this is the most recent version of the Java developer tools)

Instructions (other variations would work also):

1. Download the .tar.gz file containing Xerces-J.
2. Use Stuffit Expander(tm), Suntar, or some other Macintosh tool that
   supports the .tar.gz format to expand the downloaded file.
3. JBindery, part of MRJ SDK 2.1, is used to create a double-clickable Java application with the necessary configuration information built in. It is analogous to writing a .bat or .sh script.
4. To run the dom.DOMWriter example:
1. Double click on JBindery to start it up.
2. Click on the Classpath panel.
3. Click on the "Add .zip File" button and add both the "Xerces-J.jar" and "Xerces-JSamples.jar" files.
4. Click on the Command panel.
5. Enter "dom.DOMWriter" as the Class name. Enter "data/personal.xml" in the Optional parameters box.
6. Click on Save Settings button, pick a name such as "Run dom.DOMWriter" for the file, and be sure that "Save as Application" is selected (this is the default) and save the file.
7. Quit JBindery.
8. You can now double click on the file you created in step f to run the XJParse example.

The Visual Cafe debugger is set to trap ArrayIndexOutOfBoundsException exceptions by default. Xerces-J uses ArrayIndexOutOfBoundsException internally to signal exceptional, but not erroneous conditions. In order to run Xerces-J2 inside Visual Cafe's debugger, you need to turn off the trapping of these exceptions.

To do this:

1. Select the "Options" item in the "Project" menu.
2. Select the "Debugger" tab in the dialog which appears.
3. Select "Exceptions" from the popup menu.
4. Remove the check from the checkbox for java.lang.ArrayIndexOutOfBoundsException.