Mailing-List: contact tomcat-dev-help@jakarta.apache.org; run by ezmlm
Message-ID: <396E0B43.A7B1445E@eng.sun.com>
Date: Thu, 13 Jul 2000 11:32:35 -0700
From: "Craig R. McClanahan" <Craig.McClanahan@eng.sun.com>
MIME-Version: 1.0
To: tomcat-dev@jakarta.apache.org
Subject: What Do We Do With The User's Classpath?
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

I have been having an interesting discussion with Sam Ruby
<rubys@us.ibm.com> about how changes are made to Java classpaths in
startup scripts.  It's time to bring this discussion up in a more public
forum, because the issue is very important, and there is no one right
answer that fits everyone's needs.

Basically, when you run the "$TOMCAT_HOME/bin/tomcat.bat" or
"$TOMCAT_HOME/bin/tomcat.sh" script to start or stop Tomcat, some
manipulations occur on the class path that is given to the JVM, to make
sure that all the classes needed to run Tomcat itself are available.  In
addition, all the JAR files in your "$TOMCAT_HOME/lib" directory will
also be added (this used to be true only on Unix; we're working the code
to do this on Windows platforms out as well).  That's all well and good,
because it can save most people from having to mess with the startup
scripts.

But the key issue is this:  do we put the JAR files from this library
*before* the user's existing classpath, or *after* it?  Or do we ignore
the user's classpath entirely?  Here is where it gets sticky -- there is
no "one size fits all" answer.

Besides the Tomcat startup/shutdown scripts, there is another set of
scripts that also manipulates class paths -- the "build.bat" and
"build.sh" scripts that are used to build Tomcat itself when you are
using the source distribution.  It may (or may not) be appropriate to
have different rules for these scripts (on the assumption that Tomcat
developers will be more knowledgeable about classpath issues) than end
users and sysadmins who only want to run Tomcat, not compile it.

To clarify the discussion, lets focus on the three basic approaches that
can be taken, and understand some of the implications of each approach:

1)  The libraries in $TOMCAT_HOME/lib should
    be added to the *front* of the user's existing
    class path.

    *   The rules for adding a new JAR file to Tomcat's
        classpath are simple -- put it in the "lib"
        directory.

    *   If you have your own JAXP-compliant parser
        on your classpath, for example, it will not be
        used -- Tomcat will default to the JAXP reference
        implementation that is bundled -- unless you
        remove the "jaxp.jar" and "parser.jar" files from
        $TOMCAT_HOME/lib.

    *   If you have incompatible versions of some of
        the libraries that Tomcat needs on your class
        path, Tomcat will still work -- because it will
        find the Tomcat libraries first.

2)  The libraries in $TOMCAT_HOME/lib should
    be added to the *back* of the user's existing
    class path.

    *   The classes already on your class path
        override corresponding classes in the Tomcat
        libraries, so you get what you expect if your
        class path is set up right.  (For example, your
        own XML parser is used, in the scenario
        described above).

    *   The classes already on your class path
        override corresponding classes in the Tomcat
        libraries, so you might break Tomcat if they
        conflict.  (For example, your XML parser might
        not be JAXP compliant, so Tomcat cannot
        read its initializaton files).

    *   Adding a library to $TOMCAT_HOME/lib
        is not guaranteed to make those exact
        classes available, if some other JAR file
        on your class path already has a class of
        the same name.

3)  The user's existing class path should be
    ignored, and *only* the libraries in
    $TOMCAT_HOME/lib should be used.

    *   This is philosophically similar to the Java2
        "extensions" mechanism, where JAR files
        placed in a particular directory are automatically
        added to the class path.  This can be good news
        or bad news (it's easy to forget that old versions
        are there).

    *   If you want to use a particular JAR file inside
        Tomcat and in other Java applications, you need
        to duplicate it (in $TOMCAT_HOME/lib), which
        risks being out of sync with other copies of that
        same library.

Obviously, any given person that installs Tomcat can modify the startup
scripts to get the behavior they want.  What we should strive for is to
make the default scripts work as well as possible for the majority of
users.  What do you think?

Craig McClanahan

PS:  Tomcat 3.1 (and current builds of 3.2) use approach #1 for the
Tomcat start/stop scripts, and either approach #1 or approach #2 in the
build scripts depending on platform.  Obviously that latter one needs to
be made consistent.