                    Apache Tomcat Version 4.0.1
                    ===========================
                            Release Notes
                            =============

$Id: RELEASE-NOTES-4.0.1.txt,v 1.1.2.13 2001/10/13 19:18:36 remm Exp $


============
INTRODUCTION:
============


This document describes the changes that have been made in the current
release candidate release of Apache Tomcat, relative to the previous release.
The release notes for all prior releases of Tomcat 4.0 are also included, for
your reference.

Bug reports should be entered at the bug reporting system for
Jakarta projects at:

        http://nagoya.apache.org/bugzilla/

Please report bugs and feature requests under product name "Tomcat 4".



============
NEW FEATURES:
============


--------------------
General New Features:
--------------------

     ***** Please note the revised documentation below related to *****
     ***** using XML parsers with Tomcat 4.0 based applications.  *****


---------------------
Catalina New Features:
---------------------


-------------------
Jasper New Features:
-------------------


--------------------
Webapps New Features:
--------------------


==========================
BUG FIXES AND IMPROVEMENTS:
==========================


------------------
Generic Bug Fixes:
------------------

Build.xml: Fixes for the DOS style CRLF problems.

Scripts: Fix problems with the catalina.bat and jasper.bat scripts when
they are run on Windows 9x.

CGI Servlet: The CGI servlet will not be available to web applications, unless
$CATALINA_HOME/server/lib/servlets-cgi.renametojar is renamed (as the name 
implies) to $CATALINA_HOME/server/lib/servlets-cgi.jar.

SSI Servlet: The SSI servlet and helper classes will not be available to web 
applications, unless $CATALINA_HOME/server/lib/servlets-cgi.renametojar 
is renamed (as the name implies) to $CATALINA_HOME/server/lib/servlets-cgi.jar.


------------------
Catalina Bug Fixes:
------------------

StandardContext: Don't start the context when the doc base doesn't exist.

Documentation: Fixes in jndi-resources-howto.xml.

FormAuthenticator: If the user incorrectly references the form login page 
directly, return an error 403 (bad request) instead of a meaningless 404 
(not found) for a path that ends with "/null".

WebappCLassLoader: Modify getResourceAsStream so that there is no need to use
URL.openStream() which would require a privileged action when using a security
manager.

InstanceEvent: Enhance InstanceEvent reporting to include any exception that 
was thrown during the process being reported by this event. This applies to 
any of the "AFTER" events.

Catalina.bat: Fix the path used for jsse.jar.

Context: Add a new privileged flag.

StandardWrapper: Only allow container servlets in privileged contexts, with the
exception of the InvokerServlet.


----------------
Jasper Bug Fixes:
----------------

BeanGenerator: If a bean is an abstract class or interface, throw an 
InstantiationException.


-----------------
Webapps Bug Fixes:
-----------------


----------------------
Bugzilla Bugs Resolved:
----------------------

4021    UseBean with only class and scope attributes specified, will result 
        in a fatal translation error if the class is abstract, an interface, 
        or a class without a public no-arg constructor.
4023    Exceptions that terminate engine should be saved in a log.
4043    gotCatalinaHome and gotCatalinaBase labels in catalina.bat
        indistinguishable for Windows 98.
4067    jndi-resources-howto.xml fixes.
4078    "%JSSE_HOME%\jsse.jar" should be "%JSSE_HOME%\lib\jsse.jar" 
        in catalina.bat.
4104    Null saved request at FormAuthenticator.authenticate().
4134    WarpConnector.java: appbase -> appBase.
4135    WarpConnector.java: setAddress(int port) possibly unused.
4136    WarpConnector.java:Minor typos.


============================
KNOWN ISSUES IN THIS RELEASE:
============================

* Tomcat 4.0 and Apache
* Tomcat 4.0 and AJP 1.3
* Tomcat 4.0 and JNI Based Applications
* Tomcat 4.0 Standard APIs Available
* Tomcat 4.0 and XML Parsers
* Web application reloading and static fields in shared libraries
* JAVAC leaking memory
* Linux and Sun JDK 1.2.x - 1.3.x
* Jasper and Jikes
* Tomcat 4.0 and Apache Cocoon 2.0
* Enabling SSI and CGI Support


---------------------
Tomcat 4.0 and Apache:
---------------------

The binary distribution for Tomcat 4.0 includes the most recent stable version
of the WARP connector, which is the Tomcat component that talks to mod_webapp
inside Apache 1.3.  The current state of this support is summarized as follows:

* The mod_webapp connector is configured based on the contents of the
  web.xml file for your web application.  The only required per-webapp
  configuration information in your Apache 1.3 httpd.conf file is
  something like this:

    WebAppDeploy examples   warpConnection   /examples/

  which causes mod_webapp to automatically recognize all of your servlet
  mappings, security constraints, and other configuration elements.

* Currently, mod_webapp forwards *all* requests under the specified
  context path to Tomcat for processing.  When Tomcat 4.0 final is released,
  it will automatically configure itself to serve static resources
  from Apache *unless* the resource is subject to filtering, or subject
  to a security constraint, as defined in web.xml.  No extra configuration
  in httpd.conf will be required.

* With this release, FORM-based authentication will work correctly, but
  there is a bug that prevents BASIC authentication from operating.  This
  will be addressed before final release.

* If you restart Tomcat, you must also restart Apache to avoid receiving
  "Error 400 - Bad Request" errors.  This will be handled transparently
  in the final release.

* The combination of Apache+Tomcat currently passes all spec validation
  tests in the "jakarta-watchdog-4.0" suite.


----------------------
Tomcat 4.0 and AJP 1.3:
----------------------

Tomcat 4.0.1 now includes beta support for the AJP 1.3 protocol, which the 
mod_jk collection of native webserver modules implements.

The AJP connector is not enabled by default. To enable it, uncomment 
the following section in $CATALINA_HOME/conf/server.xml:

    <!--
    <Connector className="org.apache.ajp.tomcat4.Ajp13Connector"
               port="8009" minProcessors="5" maxProcessors="75"
               acceptCount="10" debug="0"/>
    -->

The AJP connector for Tomcat 4.0 does not support load balancing at this time.


-------------------------------------
Tomcat 4.0 and JNI Based Applications:
-------------------------------------

Applications that require native libraries must ensure that the libraries have
been loaded prior to use.  Typically, this is done with a call like:

  static {
    System.loadLibrary("path-to-library-file");
  }

in some class.  However, the application must also ensure that the library is
not loaded more than once.  If the above code were placed in a class inside
the web application (i.e. under /WEB-INF/classes or /WEB-INF/lib), and the
application were reloaded, the loadLibrary() call would be attempted a second
time.

To avoid this problem, place classes that load native libraries outside of the
web application, and ensure that the loadLibrary() call is executed only once
during the lifetime of a particular JVM.


----------------------------------
Tomcat 4.0 Standard APIs Available:
----------------------------------

A standard installation of Tomcat 4 makes all of the following APIs available
for use by web applications (by placing them in "common/lib" or "lib"):
* activation.jar (Java Activation Framework)
* jdbc2_0-stdext.jar (JDBC 2.0 Optional Package, javax.sql.*)
* jndi.jar (JNDI 1.2 base API classes)
* jta-spec1_0_1 (Java Transacation APIs)
* mail.jar (JavaMail 1.2)
* servlet.jar (Servlet 2.3 and JSP 1.2 APIs)
* tyrex-0.9.7.0.jar (Tyrex XA-compatible data source from tyrex.exolab.org)
* xerces.jar (Xerces 1.4.3)

You can make additional APIs available to all of your web applications by
putting unpacked classes into a "classes" directory (not created by default),
or by placing them in JAR files in the "lib" directory.


--------------------------
Tomcat 4.0 and XML Parsers:
--------------------------

As described above, Tomcat 4.0 makes an XML parser (and many other standard
APIs) available to web applications.  This parser is also used internally
to parse web.xml files and the server.xml configuration file.  If you wish,
you may replace the "xerces.jar" file in "common/lib" with another XML parser,
as long as it is compatible with the JAXP/1.1 APIs.

If you wish to *not* make any XML parser visible to all web applications,
this can be accomplished by copying the "xerces.jar" file from "common/lib"
to both "server/lib" and "jasper", and removing it from "common/lib".


---------------------------------------------------------------
Web application reloading and static fields in shared libraries:
---------------------------------------------------------------

Some shared libraries (many are part of the JDK) keep references to objects
instantiated by the web application. To avoid class loading related problems
(ClassCastExceptions, messages indicating that the classloader 
is stopped, ...), the shared libraries state should be reinitialized.

Something which could help is to avoid putting classes which would be 
referenced by a shared static field in the web application classloader, 
and put them in the shared classloader instead (the JARs should be put in the 
"lib" folder, and classes should be put in the "classes" folder).


--------------------
JAVAC leaking memory:
--------------------

The Java compiler leaks memory each time a class is compiled. Web applications
containing hundreds of JSP files may as a result trigger out of memory errors 
once a significant number of pages have been accessed. The memory can only be 
freed by stopping Tomcat and then restarting it.

The JSP command line compiler (JSPC) can also be used to precompile the JSPs.


-------------------------------
Linux and Sun JDK 1.2.x - 1.3.x:
-------------------------------

Virtual machine crashes can be experienced when using certain combinations of
kernel / glibc under Linux with Sun Hotspot 1.2 to 1.3. The crashes were 
reported to occur mostly on startup. Sun JDK 1.4 does not exhibit the problems,
and neither does IBM JDK for Linux.

The problems can be fixed by reducing the default stack size. At bash shell, 
do "ulimit -s 2048"; use "limit stacksize 2048" for tcsh.

GLIBC 2.2 / Linux 2.4 users should also define an environment variable:
export LD_ASSUME_KERNEL=2.2.5


----------------
Jasper and Jikes:
----------------

Jikes can be used with the Jasper JSP page compiler, but the runtime classes 
JAR of the JDK or JRE (depending on what is installed on the computer) must
be added to the system classpath.

This can be achieved by editing the main catalina script, and adding the rt.jar
file:

On Windows:
  line 71 of %CATALINA_HOME%\bin\catalina.bat, change
set CP=%CATALINA_HOME%\bin\bootstrap.jar;%JAVA_HOME%\lib\tools.jar
  to
set CP=%JAVA_HOME%\jre\lib\rt.jar;%CATALINA_HOME%\bin\bootstrap.jar;%JAVA_HOME%\lib\tools.jar

On Unix or Unix-like OSes:
  line 89 of $CATALINA_HOME/bin/catalina.sh, change
CP="$CATALINA_HOME/bin/bootstrap.jar"
  to
CP="$JAVA_HOME/jre/lib/rt.jar:$CATALINA_HOME/bin/bootstrap.jar"


--------------------------------
Tomcat 4.0 and Apache Cocoon 2.0:
--------------------------------

For optimal performance with Apache Cocoon 2.0, it is recommended to use the
HTTP/1.0 connector.


----------------------------
Enabling SSI and CGI Support:
----------------------------

Having CGI and SSI available to web applications created security problems when
using a security manager (as a malicious web application could use them to 
sidestep the security manager access control). In Tomcat 4.0.1, they have been
disabled by default, as our goal is to provide a fully secure default 
configuration. However, CGI and SSI remain available in Tomcat 4.0.1.

On Windows:
* rename the file %CATALINA_HOME%\server\lib\servlets-cgi.renametojar to
  %CATALINA_HOME%\server\lib\servlets-cgi.jar.
* rename the file %CATALINA_HOME%\server\lib\servlets-ssi.renametojar to
  %CATALINA_HOME%\server\lib\servlets-ssi.jar.
* in %CATALINA_HOME%\conf\web.xml, uncomment the servlet declarations starting
  line 165 and 213, as well as the associated servlet mappings 
  line 265 and 274. Alternately, these servlet declarations and mappings can
  be added to your web application deployment descriptor.

On Unix:
* rename the file $CATALINA_HOME/server/lib/servlets-cgi.renametojar to
  $CATALINA_HOME/server/lib/servlets-cgi.jar.
* rename the file $CATALINA_HOME/server/lib/servlets-ssi.renametojar to
  $CATALINA_HOME/server/lib/servlets-ssi.jar.
* in $CATALINA_HOME/conf/web.xml, uncomment the servlet declarations starting
  line 165 and 213, as well as the associated servlet mappings 
  line 265 and 274. Alternately, these servlet declarations and mappings can
  be added to your web application deployment descriptor.



