remm 02/01/29 07:07:00
Modified: webapps/tomcat-docs Tag: tomcat_40_branch
class-loader-howto.xml
Log:
- Remove lots of deprecated information.
- Update the list of JARs provided with Tomcat.
- Fix file (incorrect CRLF).
Revision Changes Path
No revision
No revision
1.1.2.2 +220 -267 jakarta-tomcat-4.0/webapps/tomcat-docs/class-loader-howto.xml
Index: class-loader-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/class-loader-howto.xml,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- class-loader-howto.xml 10 Jan 2002 22:17:13 -0000 1.1.2.1
+++ class-loader-howto.xml 29 Jan 2002 15:07:00 -0000 1.1.2.2
@@ -1,267 +1,220 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document>
-
- &project;
-
- <properties>
- <author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
- <title>Class Loader INFO</title>
- </properties>
-
-<body>
-
-
-<section name="Quick Start">
-
-<p>The following rules cover about 95% of the decisions that application
-developers and deployers must make about where to place class and resource
-files to make them available to web applications:</p>
-<ul>
-<li>For classes and resources specific to a particular web application,
- place unpacked classes and resources under <code>/WEB-INF/classe</code>
- of your web application archive, or place JAR files containing those
- classes and resources under <code>/WEB-INF/lib</code> of your web
- application archive.</li>
-<li>For classes and resources that must be shared across all web applications,
- place unpacked classes and resources under
- <code>$CATALINA_HOME/classes</code>, or place JAR files containing those
- classes and resources under <code>$CATALINA_HOME/lib</code>.</li>
-</ul>
-
-<p><strong>WARNING</strong> - Unlike Tomcat 3.x, Tomcat 4 does
-<strong>NOT</strong> make an XML parser visible to web applications by default.
-If you need to do this, see <a href="#Tomcat 4 and XML Parsers">Tomcat 4 and
-XML Parsers</a>, below.</p>
-
-</section>
-
-
-<section name="Overview">
-
-<p>Like many server applications, Tomcat 4 installs a variety of class loaders
-(that is, classes that implement <code>java.lang.ClassLoader</code>) to allow
-different portions of the container, and the web applications running on the
-container, to have access to different repositories of available classes and
-resources. This mechanism is used to provide the functionality defined in the
-Servlet Specification, version 2.3 -- in particular, Sections 9.4 and 9.6.</p>
-
-<p>In a Java 2 (that is, JDK 1.2 or later) environment, class loaders are
-arranged in a parent-child tree. Normally, when a class loader is asked to
-load a particular class or resource, it delegates the request to a parent
-class loader first, and then looks in its own repositories only if the parent
-class loader(s) cannot find the requested class or resource. The model for
-web application class loaders differs slightly from this, as discussed below,
-but the main principles are the same.</p>
-
-<p>When Tomcat 4 is started, it creates a set of class loaders that are
-organized into the following parent-child relationships, where the parent
-class loader is above the child class loader:</p>
-
-<source>
- Bootstrap
- |
- System
- |
- Common
- / \
- Catalina Shared
- / \
- Webapp1 Webapp2 ...
- / /
- Jasper1 Jasper2 ...
-</source>
-
-<p>The characteristics of each of these class loaders, including the source
-of classes and resources that they make visible, are discussed in detail in
-the following section.</p>
-
-</section>
-
-<section name="Class Loader Definitions">
-
-<p>As indicated in the diagram above, Tomcat 4 creates the following class
-loaders as it is initialized:</p>
-<ul>
-<li><strong>Bootstrap</strong> - This class loader contains the basic runtime
- classes provided by the Java Virtual Machine, plus any classes from JAR
- files present in the System Extensions directory
- (<code>$JAVA_HOME/jre/lib/ext</code>). <em>NOTE</em> - Some JVMs may
- implement this as more than one class loader, or it may not be visible
- (as a class loader) at all.</li>
-<li><strong>System</strong> - This class loader is normally initialized from
- the contents of the <code>CLASSPATH</code> environment variable. All such
- classes are visible to both Tomcat internal classes, and to web
- applications. However, the standard Tomcat 4 startup scripts
- (<code>$CATALINA_HOME/bin/catalina.sh</code> or
- <code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents
- of the <code>CLASSPATH</code> environment variable itself, and instead
- build the System class loader from the following repositories:
- <ul>
- <li><em>$CATALINA_HOME/bin/bootstrap.jar</em> - Contains the main() method
- that is used to initialize the Tomcat 4 server, and the class loader
- implementation classes it depends on.</li>
- <li><em>$JAVA_HOME/lib/tools.jar</em> - Contains the "javac" compiler used
- to convert JSP pages into servlet classes.</li>
- </ul></li>
-<li><strong>Common</strong> - This class loader contains additional classes
- that are made visible to both Tomcat internal classes and to all web
- applications. Normally, application classes should <strong>NOT</strong>
- be placed here. All unpacked classes and resources in
- <code>$CATALINA_HOME/common/classes</code>, as well as classes and
- resources in JAR files under
- <code>$CATALINA_HOME/common/lib</code>, are made visible through this
- class loader. By default, that includes the following:
- <ul>
- <li><em>jndi.jar</em> - The Java Naming and Directory Interface API
- classes (loaded <strong>ONLY</strong> on a JDK 1.2 system, because they
- are included automatically on JDK 1.3 and later).</li>
- <li><em>naming.jar</em> - The JNDI implementation used by Tomcat 4 to
- represent the default JNDI naming context provided to web
- applications.</li>
- <li><em>resources.jar</em> - Resource factory classes for the JNDI naming
- context that is used internally to represent the static resources of
- a web application.</li>
- <li><em>servlet.jar</em> - The Servlet and JSP API classes.</li>
- </ul></li>
-<li><strong>Catalina</strong> - This class loader is initialized to include
- all classes and resources required to implement Tomcat 4 itself. These
- classes and resources are <strong>TOTALLY</strong> invisible to web
- applications. All unpacked classes and resources in
- <code>$CATALINA_HOME/server/classes</code>, as well as classes and
- resources in JAR files under
- <code>$CATALINA_HOME/server/lib</code>, are made visible through
- this class loader. By default, that includes the following:
- <ul>
- <li><em>catalina.jar</em> - Implementation of the Catalina servlet
- container portion of Tomcat 4.</li>
- <li><em>crimson.jar</em> - Parser portion of the JAXP/1.1 reference
- implementation, used to parse web application deployment descriptor
- (<code>web.xml</code>) files, as well as the server configuration file
- (<code>$CATALINA_HOME/conf/server.xml</code>).</li>
- <li><em>jakarta-regexp-X.Y.jar</em> - The binary distribution of the
- <a href="http://jakarta.apache.org/regexp/";>Jakarta Regexp</a>
- regular expression processing library, used in the implementation of
- request filters.</li>
- <li><em>jaxp.jar</em> - JAXP API portion of the JAXP/1.1 reference
- implementation, used to parse web application deployment descriptor
- (<code>web.xml</code>) files, as well as the server configuration file
- (<code>$CATALINA_HOME/conf/server.xml</code>).</li>
- <li><em>warp.jar</em> - Classes for the Java portion of the
- <code>mod_webapp</code> web server connector, which allows Tomcat to
- run behind web servers such as Apache and iPlanet iAS and iWS.</li>
- </ul></li>
-<li><strong>Shared</strong> - This class loader is the place to put classes
- and resources that you wish to share across <strong>ALL</strong>
- web applications (unless Tomcat internal classes also need access, which
- is an unusual case). All unpacked classes and resources in
- <code>$CATALINA_HOME/classes</code>, as well as classes and resources
- in JAR files under <code>$CATALINA_HOME/lib</code>, are made visible
- through this class loader. By default, that includes the following:
- <ul>
- <li><em>jasper-runtime.jar</em> - The runtime support classes required
- to execute JSP pages that have already been translated into Java
- servlets and then compiled.</li>
- <li><em>namingfactory.jar</em> - JNDI object factories for resources
- supported by the default JNDI naming context provided to web
- applications.</li>
- </ul></li>
-<li><strong>WebappX</strong> - A class loader is created for each web
- application that is deployed in a single Tomcat 4 instance. All unpacked
- classes and resources in the <code>/WEB-INF/classes</code> directory of
- your web application archive, plus classes and resources in JAR files
- under the <code>/WEB-INF/lib</code> directory of your web application
- archive, are made visible to the containing web application, but to
- no others.</li>
-<li><strong>JasperX</strong> - If your web application uses JSP pages, Tomcat
- also creates an additional class loader for the web application,
- containing the JSP compiler and classes it depends on. It is initialized
- to include all JAR files found in <code>$CATALINA_HOME/jasper</code>.
- Because this is a child class loader of the web application class loader,
- the Jasper compiler (and the pages that it compiles) can see all of the
- application bean classes visible in the <code>Webapp</code> class loader.
- </li>
-</ul>
-
-<p>As mentioned above, the web application class loader diverges from the
-default Java 2 delegation model (in accordance with the recommendations in the
-Servlet Specification, version 2.3, section 9.6). When a request to load a
-class from the web application's <em>WebappX</em> class loader is processed,
-this class loader will look in the local repositories <strong>first</strong>,
-instead of delegating before looking. All other class loaders in Tomcat 4
-follow the usual delegation pattern.</p>
-
-<p>Therefore, from the perspective of a web application, class or resource
-loading looks in the following repositories, in this order:</p>
-<ul>
-<li><em>/WEB-INF/classes</em> of your web application</li>
-<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
-<li>Bootstrap classes of your JVM</li>
-<li>System class loader classses (described above)</li>
-<li><em>$CATALINA_HOME/common/classes</em></li>
-<li><em>$CATALINA_HOME/common/lib/*.jar</em></li>
-<li><em>$CATALINA_HOME/classes</em></li>
-<li><em>$CATALINA_HOME/lib/*.jar</em></li>
-</ul>
-
-</section>
-
-
-<section name="Tomcat 4 and XML Parsers">
-
-<p>Tomcat 4 itself utilizes XML parsing for three processing activities:</p>
-<ul>
-<li>Parsing the <code>server.xml</code> configuration file</li>
-<li>Parsing <code>web.xml</code> deployment descriptors</li>
-<li>Parsing JSP pages in XML syntax</li>
-</ul>
-
-<p>By default, the Java API for XML Processing (Version 1.1) reference
-implementation is utilized for all of these purposes. However, this parser
-is <strong>not</strong> visible to web applications -- instead, the XML
-parser stored in <code>$CATALINA_HOME/server/lib</code> is used for parsing
-<code>web.xml</code> and <code>server.xml</code> files, while the parser
-stored in <code>$CATALINA_HOME/jasper</code> is used for parsing JSP pages
-in XML syntax.</p>
-
-<p>To make an XML parser available to your web applications, you have several
-options:</p>
-<ul>
-<li>To utilize an XML parser in a single web application, simply include the
- parser's JAR files in the <code>/WEB-INF/web.xml</code> directory of that
- web application. This will work, no matter what parser might be used by
- Tomcat 4 internally, or by other web applications running in the same
- instance of Tomcat 4.</li>
-<li>If you wish to make the JAXP/1.1 reference implementation parser available
- to all web applications, simply move the "jaxp.jar" and "crimson.jar" files
- from the <code>$CATALINA_HOME/jasper</code> directory into the
- <code>$CATALINA_HOME/lib</code> directory. Jasper will continue to use
- this parser for processing JSP pages in XML syntax.</li>
-<li>If you wish to make another XML parser that is JAXP/1.1 compatible
- (such as Xerces 1.3.1 or later), install that parser's JAR files into the
- <code>$CATALINA_HOME/lib</code> directory, and remove "jaxp.jar" and
- "crimson.jar" from the <code>$CATALINA_HOME/jasper</code> directory.
- Jasper will then utilize the new XML parser as well.</li>
-</ul>
-
-<p><strong>WARNING</strong> - Do not attempt to use a JAXP/1.0 (rather than
-JAXP/1.1) compliant parser with Tomcat 4. Tomcat relies on the extra features
-that were added in JAXP/1.1 to perform its parsing activities.</p>
-
-<p><strong>WARNING</strong> - The final release of the JAXP/1.1 reference
-implementation includes JAR files with the <code>sealed</code> attribute.
-This causes class loading problems (most commonly visible through "package
-sealing violation" exceptions) on JDK 1.3 and later platforms. To avoid
-these problems, <em>modified</em> versions of "jaxp.jar" and "crimson.jar"
-are shipped with Tomcat 4. You must <strong>NOT</strong> replace these files
-with standard JAXP/1.1 JAR files, until a subsequent JAXP release occurs that
-has the "sealed" attribute removed.</p>
-
-</section>
-
-
-</body>
-
-</document>
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document>
+
+ &project;
+
+ <properties>
+ <author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
+ <title>Class Loader INFO</title>
+ </properties>
+
+<body>
+
+
+<section name="Quick Start">
+
+<p>The following rules cover about 95% of the decisions that application
+developers and deployers must make about where to place class and resource
+files to make them available to web applications:</p>
+<ul>
+<li>For classes and resources specific to a particular web application,
+ place unpacked classes and resources under <code>/WEB-INF/classe</code>
+ of your web application archive, or place JAR files containing those
+ classes and resources under <code>/WEB-INF/lib</code> of your web
+ application archive.</li>
+<li>For classes and resources that must be shared across all web applications,
+ place unpacked classes and resources under
+ <code>$CATALINA_HOME/classes</code>, or place JAR files containing those
+ classes and resources under <code>$CATALINA_HOME/lib</code>.</li>
+</ul>
+
+</section>
+
+
+<section name="Overview">
+
+<p>Like many server applications, Tomcat 4 installs a variety of class loaders
+(that is, classes that implement <code>java.lang.ClassLoader</code>) to allow
+different portions of the container, and the web applications running on the
+container, to have access to different repositories of available classes and
+resources. This mechanism is used to provide the functionality defined in the
+Servlet Specification, version 2.3 -- in particular, Sections 9.4 and 9.6.</p>
+
+<p>In a Java 2 (that is, JDK 1.2 or later) environment, class loaders are
+arranged in a parent-child tree. Normally, when a class loader is asked to
+load a particular class or resource, it delegates the request to a parent
+class loader first, and then looks in its own repositories only if the parent
+class loader(s) cannot find the requested class or resource. The model for
+web application class loaders differs slightly from this, as discussed below,
+but the main principles are the same.</p>
+
+<p>When Tomcat 4 is started, it creates a set of class loaders that are
+organized into the following parent-child relationships, where the parent
+class loader is above the child class loader:</p>
+
+<source>
+ Bootstrap
+ |
+ System
+ |
+ Common
+ / \
+ Catalina Shared
+ / \
+ Webapp1 Webapp2 ...
+ / /
+ Jasper1 Jasper2 ...
+</source>
+
+<p>The characteristics of each of these class loaders, including the source
+of classes and resources that they make visible, are discussed in detail in
+the following section.</p>
+
+</section>
+
+<section name="Class Loader Definitions">
+
+<p>As indicated in the diagram above, Tomcat 4 creates the following class
+loaders as it is initialized:</p>
+<ul>
+<li><strong>Bootstrap</strong> - This class loader contains the basic runtime
+ classes provided by the Java Virtual Machine, plus any classes from JAR
+ files present in the System Extensions directory
+ (<code>$JAVA_HOME/jre/lib/ext</code>). <em>NOTE</em> - Some JVMs may
+ implement this as more than one class loader, or it may not be visible
+ (as a class loader) at all.</li>
+<li><strong>System</strong> - This class loader is normally initialized from
+ the contents of the <code>CLASSPATH</code> environment variable. All such
+ classes are visible to both Tomcat internal classes, and to web
+ applications. However, the standard Tomcat 4 startup scripts
+ (<code>$CATALINA_HOME/bin/catalina.sh</code> or
+ <code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents
+ of the <code>CLASSPATH</code> environment variable itself, and instead
+ build the System class loader from the following repositories:
+ <ul>
+ <li><em>$CATALINA_HOME/bin/bootstrap.jar</em> - Contains the main()
+ method that is used to initialize the Tomcat 4 server, and
+ the class loader implementation classes it depends on.</li>
+ <li><em>$JAVA_HOME/lib/tools.jar</em> - Contains the "javac"
+ compiler used to convert JSP pages into servlet classes.</li>
+ </ul></li>
+<li><strong>Common</strong> - This class loader contains additional classes
+ that are made visible to both Tomcat internal classes and to all web
+ applications. Normally, application classes should <strong>NOT</strong>
+ be placed here. All unpacked classes and resources in
+ <code>$CATALINA_HOME/common/classes</code>, as well as classes and
+ resources in JAR files under
+ <code>$CATALINA_HOME/common/lib</code>, are made visible through this
+ class loader. By default, that includes the following:
+ <ul>
+ <li><em>activation.jar</em> - The Java activation framework.</li>
+ <li><em>jdbc2_0-stdext.jar</em> - JDBC 2.0 standard extension
+ (included as a standard part of JDBC 3.0).</li>
+ <li><em>jndi.jar</em> - The Java Naming and Directory Interface API
+ classes (loaded <strong>ONLY</strong> on a JDK 1.2 system, because
+ they are included automatically on JDK 1.3 and later).</li>
+ <li><em>jta-spec.jar</em> - The Java Transaction API interfaces.</li>
+ <li><em>mail.jar</em> - Java Mail.</li>
+ <li><em>naming-common.jar</em> - The JNDI implementation used
+ by Tomcat 4 to represent the default JNDI naming context provided
+ to web applications.</li>
+ <li><em>naming-resources.jar</em> - JNDI Directory Context
+ implementations which are used to abstract access to the static
+ resources of a web application.</li>
+ <li><em>servlet.jar</em> - The Servlet and JSP API classes.</li>
+ <li><em>tyrex-0.9.7.jar</em> - JTA/JTS/OTS compliant transaction
+ manager and DataSource connection pool implementation.</li>
+ <li><em>xerces.jar</em> - The Xerces 1.x XML parser (also includes the
+ JAXP 1.1 interfaces).</li>
+ </ul></li>
+<li><strong>Catalina</strong> - This class loader is initialized to include
+ all classes and resources required to implement Tomcat 4 itself. These
+ classes and resources are <strong>TOTALLY</strong> invisible to web
+ applications. All unpacked classes and resources in
+ <code>$CATALINA_HOME/server/classes</code>, as well as classes and
+ resources in JAR files under
+ <code>$CATALINA_HOME/server/lib</code>, are made visible through
+ this class loader. By default, that includes the following:
+ <ul>
+ <li><em>catalina.jar</em> - Implementation of the Catalina servlet
+ container portion of Tomcat 4.</li>
+ <li><em>jakarta-regexp-X.Y.jar</em> - The binary distribution of the
+ <a href="http://jakarta.apache.org/regexp/";>Jakarta Regexp</a>
+ regular expression processing library, used in the implementation of
+ request filters.</li>
+ <li><em>servlets-xxxx.jar</em> - The standard suite of servlets
+ which provide basic services, like static page serving, WebDAV support,
+ CGI, SSI, and more.</li>
+ <li><em>tomcat-util.jar</em> - Utility components used by modules from
+ the jakarta-tomcat-connectors subproject.</li>
+ <li><em>tomcat-ajp.jar</em> - The Java portion of the AJP 1.x connector
+ (also know as the JK connector), which provides support for
+ connecting native webservers, and load balancing between multiple
+ Tomcat instances.</li>
+ <li><em>warp.jar</em> - Classes for the Java portion of the
+ <code>mod_webapp</code> web server connector, which allows Tomcat to
+ run behind web servers such as Apache and iPlanet iAS and iWS.</li>
+ </ul></li>
+<li><strong>Shared</strong> - This class loader is the place to put classes
+ and resources that you wish to share across <strong>ALL</strong>
+ web applications (unless Tomcat internal classes also need access, which
+ is an unusual case). All unpacked classes and resources in
+ <code>$CATALINA_HOME/classes</code>, as well as classes and resources
+ in JAR files under <code>$CATALINA_HOME/lib</code>, are made visible
+ through this class loader. By default, that includes the following:
+ <ul>
+ <li><em>jasper-compiler.jar</em> - The Jasper JSP page compiler.</li>
+ <li><em>jasper-runtime.jar</em> - The runtime support classes required
+ to execute JSP pages that have already been translated into Java
+ servlets and then compiled.</li>
+ <li><em>naming-factory.jar</em> - JNDI object factories for resources
+ supported by the default JNDI naming context provided to web
+ applications.</li>
+ </ul></li>
+<li><strong>WebappX</strong> - A class loader is created for each web
+ application that is deployed in a single Tomcat 4 instance. All unpacked
+ classes and resources in the <code>/WEB-INF/classes</code> directory of
+ your web application archive, plus classes and resources in JAR files
+ under the <code>/WEB-INF/lib</code> directory of your web application
+ archive, are made visible to the containing web application, but to
+ no others.</li>
+<li><strong>JasperX</strong> - If your web application uses JSP pages, Tomcat
+ also creates an additional class loader for the web application,
+ containing the JSP compiler and classes it depends on. It is initialized
+ to include all JAR files found in <code>$CATALINA_HOME/jasper</code>.
+ Because this is a child class loader of the web application class loader,
+ the Jasper compiler (and the pages that it compiles) can see all of the
+ application bean classes visible in the <code>Webapp</code> class loader.
+ </li>
+</ul>
+
+<p>As mentioned above, the web application class loader diverges from the
+default Java 2 delegation model (in accordance with the recommendations in the
+Servlet Specification, version 2.3, section 9.6). When a request to load a
+class from the web application's <em>WebappX</em> class loader is processed,
+this class loader will look in the local repositories <strong>first</strong>,
+instead of delegating before looking. All other class loaders in Tomcat 4
+follow the usual delegation pattern.</p>
+
+<p>Therefore, from the perspective of a web application, class or resource
+loading looks in the following repositories, in this order:</p>
+<ul>
+<li><em>/WEB-INF/classes</em> of your web application</li>
+<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
+<li>Bootstrap classes of your JVM</li>
+<li>System class loader classses (described above)</li>
+<li><em>$CATALINA_HOME/common/classes</em></li>
+<li><em>$CATALINA_HOME/common/lib/*.jar</em></li>
+<li><em>$CATALINA_HOME/classes</em></li>
+<li><em>$CATALINA_HOME/lib/*.jar</em></li>
+</ul>
+
+</section>
+
+
+</body>
+
+</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
