Advanced IO and Tomcat

Like many server applications, Tomcat 5 installs a variety of class loaders +

Like many server applications, Tomcat 6 installs a variety of class loaders (that is, classes that implement java.lang.ClassLoader) 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 @@ -53,7 +32,7 @@ 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.

When Tomcat 5 is started, it creates a set of class loaders that are +

When Tomcat 6 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:

@@ -63,10 +42,8 @@ class loader is above the child class loader:

System | Common - / \ - Catalina Shared - / \ - Webapp1 Webapp2 ... + / \ + Webapp1 Webapp2 ...

The characteristics of each of these class loaders, including the source @@ -77,7 +54,7 @@ the following section.

As indicated in the diagram above, Tomcat 5 creates the following class +

As indicated in the diagram above, Tomcat 6 creates the following class loaders as it is initialized:

Bootstrap - This class loader contains the basic runtime @@ -96,97 +73,41 @@ loaders as it is initialized:
build the System class loader from the following repositories:
- $CATALINA_HOME/bin/bootstrap.jar - Contains the main() method - that is used to initialize the Tomcat 5 server, and the class loader + that is used to initialize the Tomcat 6 server, and the class loader implementation classes it depends on.
- $JAVA_HOME/lib/tools.jar - Contains the "javac" compiler used - to convert JSP pages into servlet classes.
- $CATALINA_HOME/bin/commons-logging-api.jar - Jakarta commons logging API.
- $CATALINA_HOME/bin/commons-daemon.jar - Jakarta commons - daemon API.
- jmx.jar - The JMX 1.2 implementation.
Common - This class loader contains additional classes that are made visible to both Tomcat internal classes and to all web applications. Normally, application classes should NOT be placed here. All unpacked classes and resources in - $CATALINA_HOME/common/classes, as well as classes and - resources in JAR files under the - $CATALINA_HOME/commons/endorsed, - $CATALINA_HOME/commons/i18n and - $CATALINA_HOME/common/lib directories, - are made visible through this + $CATALINA_HOME/lib, as well as classes and + resources in JAR files are made visible through this class loader. By default, that includes the following:
- commons-el.jar - Jakarta commons el, implementing the - expression language used by Jasper.
- jasper-compiler.jar - The JSP 2.0 compiler.
- jasper-compiler-jdt.jar - The Eclipse JDT Java compiler.
- jasper-runtime.jar - The JSP 2.0 runtime.
- jsp-api.jar - The JSP 2.0 API.
- naming-common.jar - The JNDI implementation used by Tomcat 5 - to represent in-memory naming contexts.
- naming-factory.jar - The JNDI implementation used by Tomcat 5 - to resolve references to enterprise resources (EJB, connection - pools).
- naming-factory-dbcp.jar - Jakarta commons DBCP, providing a - JDBC connection pool to web applications. The classes have been moved - out of their default org.apache.commons package.
- naming-java.jar - Handler for the java: namespace.
- naming-resources.jar - The specialized JNDI naming context - implementation used to represent the static resources of a web - application. This is not related to the support of the J2EE ENC, and - cannot be removed.
- servlet-api.jar - The Servlet 2.4 API.
- annotations-api.jar - JEE annotations classes.
- catalina.jar - Implementation of the Catalina servlet + container portion of Tomcat 6.
- catalina-ant.jar - Tomcat Catalina Ant tasks.
- catalina-ha.jar - High availability package.
- catalina-tribes.jar - Group communication package.
- el-api.jar - EL 2.1 API.
- jasper.jar - Jasper 2 Compiler and Runtime.
- jasper-el.jar - Jasper 2 EL implementation.
- jasper-jdt.jar - Eclipse JDT 3.2 Java compiler.
- jsp-api.jar - JSP 2.1 API.
- servlet-api.jar - Servlet 2.5 API.
- tomcat-coyote.jar - Tomcat connectors and utility classes.
- tomcat-dbcp.jar - package renamed database connection + pool based on Commons DBCP.
- tomcat-i18n-**.jar - Optional JARs containing resource bundles for other languages. As default bundles are also included in each individual JAR, they can be safely removed if no internationalization of messages is needed.
Catalina - This class loader is initialized to include - all classes and resources required to implement Tomcat 5 itself. These - classes and resources are TOTALLY invisible to web - applications. All unpacked classes and resources in - $CATALINA_HOME/server/classes, as well as classes and - resources in JAR files under - $CATALINA_HOME/server/lib, are made visible through - this class loader. By default, that includes the following: -
- catalina.jar - Implementation of the Catalina servlet - container portion of Tomcat 5.
- catalina-ant.jar - Some Ant tasks which can be used to - manage Tomcat using the manager web application.
- catalina-optional.jar - Some optional components of - Catalina.
- commons-modeler.jar - A model MBeans implementation used - by Tomcat to expose its internal objects through JMX.
- servlets-xxxxx.jar - The classes associated with each - internal servlet that provides part of Tomcat's functionality. - These are separated so that they can be completely removed if the - corresponding service is not required, or they can be subject to - specialized security manager permissions.
- tomcat-coyote.jar - Coyote API.
- tomcat-http.jar - Standalone Java HTTP/1.1 - connector.
- tomcat-ajp.jar - Classes for the Java portion of the - AJP web server connector, which allows Tomcat to - run behind web servers such as Apache and iPlanet iAS and iWS.
- tomcat-util.jar - Utility classes required by some - Tomcat connectors.
Shared - This class loader is the place to put classes - and resources that you wish to share across ALL - web applications (unless Tomcat internal classes also need access, - in which case you should put them in the Common - class loader instead). All unpacked classes and resources in - $CATALINA_BASE/shared/classes, as well as classes and - resources in JAR files under $CATALINA_BASE/shared/lib, are - made visible through this class loader. If multiple Tomcat instances are - run from the same binary using the $CATALINA_BASE environment variable, - then this classloader repositories are relative to $CATALINA_BASE rather - than $CATALINA_HOME.
WebappX - A class loader is created for each web - application that is deployed in a single Tomcat 5 instance. All unpacked + application that is deployed in a single Tomcat 6 instance. All unpacked classes and resources in the /WEB-INF/classes directory of your web application archive, plus classes and resources in JAR files under the /WEB-INF/lib directory of your web application @@ -203,11 +124,10 @@ this class loader will look in the local repositories first, instead of delegating before looking. There are exceptions. Classes which are part of the JRE base classes cannot be overriden. For some classes (such as the XML parser components in J2SE 1.4+), the J2SE 1.4 endorsed feature can be -used -(see the common classloader definition above). +used. Last, any JAR containing servlet API classes will be ignored by the classloader. -All other class loaders in Tomcat 5 follow the usual delegation pattern.
+All other class loaders in Tomcat 6 follow the usual delegation pattern.

Therefore, from the perspective of a web application, class or resource loading looks in the following repositories, in this order:
@@ -216,42 +136,36 @@ loading looks in the following repositories, in this order:
System class loader classses (described above)
/WEB-INF/classes of your web application
/WEB-INF/lib/*.jar of your web application
$CATALINA_HOME/common/classes
$CATALINA_HOME/common/endorsed/*.jar
$CATALINA_HOME/common/i18n/*.jar
$CATALINA_HOME/common/lib/*.jar
$CATALINA_BASE/shared/classes
$CATALINA_BASE/shared/lib/*.jar
$CATALINA_HOME/lib
$CATALINA_HOME/lib/*.jar

Among many other changes, the J2SE 1.4 release packages the JAXP APIs, and +

Among many other changes, the JSE 5 release packages the JAXP APIs, and a version of Xerces, inside the JRE. This has impacts on applications that wish to use their own XML parser.

In previous versions of Tomcat 5, you could simply replace the XML parser +

In previous versions of Tomcat, you could simply replace the XML parser in the $CATALINA_HOME/common/lib directory to change the parser used by all web applications. However, this technique will not be effective -when you are running on J2SE 1.4, because the usual class loader delegation +when you are running on JSE 5, because the usual class loader delegation process will always choose the implementation inside the JDK in preference to this one.

JDK 1.4 supports a mechanism called the "Endorsed Standards Override +

JDK 1.5 supports a mechanism called the "Endorsed Standards Override Mechanism" to allow replacement of APIs created outside of the JCP (i.e. DOM and SAX from W3C). It can also be used to update the XML parser implementation. For more information, see: - -http://java.sun.com/j2se/1.4/docs/guide/standards/index.html.

+ +http://java.sun.com/j2se/1.5/docs/guide/standards/index.html.

Tomcat utilizes this mechanism by including the system property setting --Djava.endorsed.dirs=$CATALINA_HOME/common/endorsed in the -command line that starts the container. Therefore, you can replace the -parser that is installed in this directory, and it will get used even on a -JDK 1.4 system.

+-Djava.endorsed.dirs=$CATALINA_HOME/endorsed in the +command line that starts the container.

diff --git a/webapps/docs/jasper-howto.xml b/webapps/docs/jasper-howto.xml index dedd38021..6826746fb 100644 --- a/webapps/docs/jasper-howto.xml +++ b/webapps/docs/jasper-howto.xml @@ -26,7 +26,7 @@

Tomcat 5.5 uses the Jasper 2 JSP Engine to implement +

Tomcat 6.0 uses the Jasper 2 JSP Engine to implement the JavaServer Pages 2.0 specification.

@@ -148,13 +148,12 @@ actions or directives be trimmed ?, default false. advanced Java compiler which will load all dependencies from the Tomcat class loader, which will help tremendously when compiling on large installations with tens of JARs. On fast servers, this will allow sub-second recompilation cycles for even large JSP -pages. This new compiler will be updated to support the Java 5 syntax as soon as -possible.

+pages.

Apache Ant, which was used in previous Tomcat releases, can be used instead instead of -the new compiler by simply removing the common/lib/jasper-compiler-jdt.jar file, +the new compiler by simply removing the common/lib/jasper-jdt.jar file, and placing the ant.jar file from the latest Ant distribution in the -common/lib folder. If you do this, you also need to use the "javac" +lib folder. If you do this, you also need to use the "javac" argument to catalina.sh.

diff --git a/webapps/docs/logging.xml b/webapps/docs/logging.xml index 4f551adb6..7f6e1d73e 100644 --- a/webapps/docs/logging.xml +++ b/webapps/docs/logging.xml @@ -16,7 +16,7 @@

- Tomcat 5.5 uses + Tomcat 6.0 uses Commons Logging throughout its internal code allowing the developer to choose a logging configuration that suits their needs, e.g @@ -27,7 +27,7 @@ logging implementation.

- An important consequence for Tomcat 5.5 is that the <Logger> element found in + An important consequence for Tomcat 6.0 is that the <Logger> element found in previous versions to create a localhost_log is no longer a valid nested element of <Context>. Instead, the default Tomcat configuration will use java.util.logging. If the developer wishes to collect detailed internal Tomcat logging (i.e what is happening @@ -39,7 +39,7 @@

- Tomcat 5.5 has done away with localhost_log which you may be familiar with + Tomcat 6.0 has done away with localhost_log which you may be familiar with as the runtime exception/stack trace log. These types of error are usually thrown by uncaught exceptions, but are still valuable to the developer. They can now be found in the stdout log. @@ -129,10 +129,6 @@

- In order to configure JDK logging you should have JDK 1.4+. Tomcat 5.5 is intended for - JDK 5.0, but can be run on JDK 1.4 using a compatibility package. -

The default implemenatation of java.util.logging provided in the JDK is too limited to be useful. A limitation of JDK Logging appears to be the inability to have per-web application logging, as the configuration is per-VM. As a result, Tomcat will, in the default configuration, @@ -144,13 +140,13 @@ constructs which allows more freedom for defining handlers and assigning them to loggers.

- JULI is enabled by default in Tomcat 5.5, and supports per classloader configuration, in addition to + JULI is enabled by default in Tomcat 6.0, and supports per classloader configuration, in addition to the regular global java.util.logging configuration. This means that logging can be configured at the following layers:

In the JDK's logging.properties file. Check - your JAVA_HOME environment setting to see which JDK Tomcat is using (or maybe JRE 5.0 as Tomcat - can now run on a JRE from version 5.5). The file will be in $JAVA_HOME/jre/lib. + your JAVA_HOME environment setting to see which JDK Tomcat is using. The file will be in + $JAVA_HOME/jre/lib. Alternately, it can also use a global configuration file located elsewhere by using the system property java.util.logging.config.file, or programmatic configuration using java.util.logging.config.class.

reloadable

To support these capabilities, Tomcat 5 includes a web application +

To support these capabilities, Tomcat 6 includes a web application (installed by default on context path /manager) that supports the following functions:

Host

server.xml

-<Context path="/manager" debug="0" privileged="true"
-         docBase="/usr/local/kinetic/tomcat5/server/webapps/manager">
+<Context path="/manager" privileged="true"
+         docBase="/usr/local/kinetic/tomcat6/server/webapps/manager">
 </Context>

Future versions of Tomcat 5 will include administrative functionality that +

Future versions of Tomcat 6 will include administrative functionality that is presented in (at least) the following forms:

As web services, so that Tomcat administration can be easily integrated @@ -138,9 +138,9 @@ is presented in (at least) the following forms:
The description below uses the variable name $CATALINA_HOME - to refer to the directory into which you have installed Tomcat 5, + to refer to the directory into which you have installed Tomcat 6, and is the base directory against which most relative paths are - resolved. However, if you have configured Tomcat 5 for multiple + resolved. However, if you have configured Tomcat 6 for multiple instances by setting a CATALINA_BASE directory, you should use $CATALINA_BASE instead of $CATALINA_HOME for each of these references.
@@ -164,7 +164,7 @@ depends on which Realm implementation you are using:

MemoryRealm - If you have not customized your $CATALINA_HOME/conf/server.xml to select a different one, - Tomcat 5 defaults to an XML-format file stored at + Tomcat 6 defaults to an XML-format file stored at $CATALINA_HOME/conf/tomcat-users.xml, which can be edited with any text editor. This file contains an XML <user> for each individual user, which might @@ -200,8 +200,8 @@ could be restricted by the remote IP address or host by adding a RemoteAddrValve or RemoteHostValve. Here is an example of restricting access to the localhost by IP address:
-<Context path="/manager" debug="0" privileged="true" - docBase="/usr/local/kinetic/tomcat5/server/webapps/manager"> +<Context path="/manager" privileged="true" + docBase="/usr/local/kinetic/tomcat6/server/webapps/manager"> <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="127.0.0.1"/> </Context> @@ -332,7 +332,7 @@ error message. Possible causes for problems include:

Encountered exception

An exception was encountered trying to start the new web application. - Check the Tomcat 5 logs for the details, but likely explanations include + Check the Tomcat 6 logs for the details, but likely explanations include problems parsing your /WEB-INF/web.xml file, or missing classes encountered when initializing application event listeners and filters.
@@ -515,7 +515,7 @@ error message. Possible causes for problems include:

Encountered exception

An exception was encountered trying to start the new web application. - Check the Tomcat 5 logs for the details, but likely explanations include + Check the Tomcat 6 logs for the details, but likely explanations include problems parsing your /WEB-INF/web.xml file, or missing classes encountered when initializing application event listeners and filters.
@@ -598,7 +598,7 @@ error message. Possible causes for problems include:

Encountered exception

An exception was encountered trying to restart the web application. - Check the Tomcat 5 logs for the details.
+ Check the Tomcat 6 logs for the details.

Invalid context path was specified
@@ -642,7 +642,7 @@ include an error message. Possible causes for problems include:

Encountered exception

An exception was encountered trying to enumerate the system properties. - Check the Tomcat 5 logs for the details.
+ Check the Tomcat 6 logs for the details.

@@ -687,7 +687,7 @@ include an error message. Possible causes for problems include:

Encountered exception

An exception was encountered trying to enumerate the global JNDI - resources. Check the Tomcat 5 logs for the details.
+ resources. Check the Tomcat 6 logs for the details.

No global JNDI resources are available
@@ -796,7 +796,7 @@ error message. Possible causes for problems include:

Encountered exception

An exception was encountered trying to start the web application. - Check the Tomcat 5 logs for the details.
+ Check the Tomcat 6 logs for the details.

Invalid context path was specified
@@ -838,7 +838,7 @@ error message. Possible causes for problems include:

Encountered exception

An exception was encountered trying to stop the web application. - Check the Tomcat 5 logs for the details.
+ Check the Tomcat 6 logs for the details.

Invalid context path was specified
@@ -893,7 +893,7 @@ error message. Possible causes for problems include:

Encountered exception

An exception was encountered trying to undeploy the web application. - Check the Tomcat 5 logs for the details.
+ Check the Tomcat 6 logs for the details.

Invalid context path was specified
@@ -918,7 +918,7 @@ error message. Possible causes for problems include:

In addition to the ability to execute Manager commands via HTTP requests, -as documented above, Tomcat 5 includes a convenient set of Task definitions +as documented above, Tomcat 6 includes a convenient set of Task definitions for the Ant (version 1.4 or later) build tool. In order to use these commands, you must perform the following setup operations:

@@ -927,7 +927,7 @@ commands, you must perform the following setup operations:
You must use version 1.4 or later.
Install the Ant distribution in a convenient directory (called ANT_HOME in the remainder of these instructions).
-
Copy the file server/lib/catalina-ant.jar from your Tomcat 5 +
Copy the file server/lib/catalina-ant.jar from your Tomcat 6 installation into Ant's library directory ($ANT_HOME/lib).

Add the $ANT_HOME/bin directory to your PATH diff --git a/webapps/docs/mbeans-descriptor-howto.xml b/webapps/docs/mbeans-descriptor-howto.xml index 69df84e35..595b8159c 100644 --- a/webapps/docs/mbeans-descriptor-howto.xml +++ b/webapps/docs/mbeans-descriptor-howto.xml @@ -15,7 +15,7 @@
-
Tomcat 5 uses JMX MBeans as the technology for implementing +
Tomcat 6 uses JMX MBeans as the technology for implementing manageability of Tomcat.

The descriptions of JMX MBeans for Catalina are in the mbeans-descriptor.xml diff --git a/webapps/docs/realm-howto.xml b/webapps/docs/realm-howto.xml index 27d93d5e4..d25cc3201 100644 --- a/webapps/docs/realm-howto.xml +++ b/webapps/docs/realm-howto.xml @@ -110,7 +110,7 @@ sources of authentication information:

It is also possible to write your own Realm implementation, -and integrate it with Tomcat 5. To do so, you need to: +and integrate it with Tomcat 6. To do so, you need to:

Implement org.apache.catalina.Realm,

Place your compiled realm in $CATALINA_HOME/server/lib,
-- 2.11.0