Installing a SAX2 Parser (SAX2)

1.7. Installing a SAX2 Parser

Unless you use JDK 1.4 (which bundles SAX2 and the Crimson parser) or some other environment that's already set up with SAX2 support (such as any up-to-date web application server), you will need to update your Java programming environment so that you can use SAX. Consult the documentation that comes with your parser and Java Virtual Machine for specific details. Assuming the SAX interfaces and your SAX parser are distributed in a single JAR file called xml.jar (you'll need to know and use the correct full pathname, including the directory), you'll probably use one of these approaches shown in the following list.

Add to extensions directory

If you use JDK 1.2 or later for your runtime environment,[6] you can install the JAR file into the jre/lib/ext subdirectory of your Java distribution. This is the preferred solution during development, since it's the simplest and least error-prone.

[6]Most current graphical development tools, called IDEs, bundle this software for Java.

On Windows, you may need to add this to two different locations: one for the development environment as well as one for the runtime environment.

Update class path on command line

This solution works with JDK 1.2 and later. Whenever you invoke a program that needs the SAX support (such as java, javac, or javadoc) pass the -cp xml.jar parameter to add SAX to the class path.

Add to CLASSPATH in environment

This is the original way to add software to your Java environment, and it works on a JDK 1.1-based system and on many Java implementations that aren't derived from Sun's JDK. You may prefer this technique if you have to make several different Java execution environments cooperate -- perhaps one for each IDE and test environment used for application development. You could also have your application use its bundled JVM when it's deployed, rather than whatever the end user happened to have around.

The details vary from operating system to operating system, and from installation to installation, because you may need to ensure that your CLASSPATH includes libraries internal to the JVM. Put the CLASSPATH assignment into your login script (autoexec.bat or your environment variables, .profile, .login, or other file). On Windows, you'll likely need to reboot after you modify autoexec.bat, to ensure that all new JVM instances see the new configuration.

You may end up with a variety of SAX2 parsers in your environment. Sometimes which parser you use will be important, but you should avoid creating such problems. See Section 3.2, "Bootstrapping an XMLReader" in Chapter 3, "Producing SAX2 Events" for information about making sure you're using a particular parser; there are several mechanisms, including setting system properties and adding META-INF/services/ resources to your class path. If you work within some application environment (perhaps a web server), you may want to look for specialized configuration mechanisms. Also, if you have SAX1 support in your environment, you can easily upgrade it; see Section 5.2, "SAX1 Support " in Chapter 5, "Other SAX Classes".

Note that because SAX lets applications hand character streams to parsers with java.io.Reader, you can't use JDK 1.0 with SAX. You need JDK 1.1, which is a more complete and stable release in any case. Since the Java environments that aren't based on Sun's code generally treat JDK 1.1 as the conformance target,[7] that should cause no real trouble. SAX itself doesn't require more recent APIs, but some of the tools you use with SAX might have such requirements. For portability, the example code in this book avoids use of APIs added in JDK 1.2 and later. The main impact of this restriction is that in a few cases you'll be able to get minor performance improvements by using the collections APIs.

[7]Many Macintosh developers can't use JDK 1.2 yet. The Microsoft JVM also does not support JDK 1.2 APIs.