                  Apache Tomcat Version 4.0 Beta 7
                  =================================
                            Release Notes
                            =============

$Id: RELEASE-NOTES-4.0-B7.txt,v 1.4 2001/08/10 14:14:15 pier Exp $


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


This document describes the changes that have been made in the current
beta release of Apache Tomcat, relative to the previous release.

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".

This version of Tomcat 4 should be considered a "release candidate" for
all capabilities except the mod_webapp connector.  Only bugfix changes will
be implemented before a Tomcat 4.0 final release is made available, which
will occur when the Servlet 2.3 and JSP 1.2 specifications go final.


----> SECURITY VULNERABILITY FIXED:  In addition to the new features and
----> bug fixes listed below, this release of Tomcat fixes a vulnerability
----> on Windows 9x platforms (at least, possibly on other Windows versions
----> as well) that causes request URLs like "http://localhost:8080/.../"
----> to expose files on your disk.  This vulnerability does not exist on
----> Unix platforms.


----> UPCOMING CHANGE NOTICE:  In a future release of Tomcat 4.0, it
----> is likely that the default operational mode will be to run Tomcat
----> under a security manager (rather than the current default of not
----> using one).  This may necessitate editing the policy permissions
----> file ($CATALINA_HOME/conf/catalina.policy) if your web applications
----> require permissions that are not enabled by default (such as connecting
----> to network ports).  You are urged to test your applications with
----> Tomcat 4.0-b5 running under the security manager now, so that this
----> upcoming change will not be disruptive.  To do so, start Tomcat 4.0
----> with the command "$CATALINA_HOME/bin/catalina.sh start -security"
----> (Unix) or "%CATALINA_HOME%\bin\catalina start -security" (Windows).


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


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

Documentation - Revised the installation instructions, as well as instructions
for building from source, to reflect current dependencies.

Spec Compliance - Tomcat 4.0 is now compliant with the changes in the Servlet
2.3 (Proposed Final Draft 3) and JSP 1.2 (Proposed Final Draft 3)
specifications.  Further changes in the specifications are possible, but grow
increasingly unlikely as they approach final release.

Documentation - Started migrating to a new "tomcat-docs" web app that uses a
standard stylesheet to manage the creation of documentation (in HTML format).
This new web app is not yet included in the release, but a snapshot of the
progress to date is available at:

    http://jakarta.apache.org/tomcat/tomcat-4.0-doc-exp/index.html


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

Connectors - Refactored the startup code so that Catalina can run on port 80
(without being root) when started by JavaService or equivalent service
managers.

StandardContext / ProxyDirContext - Support the disabling of caching for
static resource metadata.

SingleSignOff Support - If you are using "single sign on" support with form
based login, invalidating (or timing out) a session in one app will now sign
the user off from all apps, as required by Servlet 2.3 PFD3.

InstanceEvent - The events sent to Catalina-internal instance event listeners
now include the request and response being processed if relevant.

InstanceEvent - New event types for before and after dispatching are now
fired when a servlet is invoked via a request dispatcher.

Sessions and Requests - Internal implementation objects now support a new
"notes" facility that lets Catalina components decorate them with extra
information, without requiring creation of additional object properties, or
exposing the information to applications by using attributes.

AccessLogValve - Support a new "combined" logging format that includes the
referer and user-agent headers, along with everything in the default "common"
log format.


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


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

SetCharacterEncodingFilter - A new Filter has been added to the "/examples"
web application shipped with Tomcat, which allows you to programmatically
determine what character set you wish to use to interpret request parameters
for a given request, and then call request.setCharacterEncoding().  Doing this
as a filter means you do not need to modify all of your servlets and JSP pages
to include this functionality.  Feel free to use this Filter as is, or as the
basis for a more sophisticated implementation.


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


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

WebappClassLoader - [Bugzilla #2725] Non-JAR files placed in
/WEB-INF/lib would cause continuous reloads of a reloadable context.

FileDirContext - Close the input stream after finishing copying.  Otherwise,
was causing problems deleting resources that were the source of a COPY.

StandardContext - [Bugzilla #2710] getNamingContextName() was returning an
incorrect name.

AccessLogValve - [Bugzilla #2763] Include the query string (if any) in the
access log output.

FormAuthenticator - [Bugzilla #2768] When processing a form-based login and
redirecting back to the orginally requested resource, include any query string
that was part of the original request.

StandardContext - [Bugzilla #2755] Clean up thread binding and unbinding so
that the context class loader is set during the start and stop of listeners
and filters.

ApplicationContext - Throw IllegalArgumentException if the first argument to
setAttribute() is null.

RequestBase - Throw IllegalArgumentException if the first argument to
setAttribute() is null.

HttpProcessor - Fix for prohibitively long shutdown times when HTTP/1.1
persistent connections are in use.

FormAuthenticator - [Bugzilla #2806] Fix an endless loop that would occur
if the <form-error-page> was within the protected area of the web application.
There was already a special case for the login page.

ContextConfig - [Bugzilla #2870] If parsing errors are encountered when
processing web.xml, mark the application unavailable instead of letting it
serve requests in a partially initialized state.

SSLAuthenticator - [BugTraq #4485977] Authenticate users through the Realm
when using CLIENT-CERT login, by passing the client certificate chain to a
new Realm.authenticate() method.

WebappClassLoader - The system policy file is now refreshed in the
ClassLoader constructor, and any security exception is swallowed.

FormAuthenticator - [BugTraq #4485977] Make form-based login work correctly
even if caching of authenticated principals in the session is turned off.

ApplicationDispatcher - When a RequestDispatcher is used to access a resource
in a different context, propertly set and reset the thread context class
loader so that the invoked resource sees the correct one.

HttpResponseBase / HttpResponseImpl - Per HTTP/1.1 specification (RFC 2616),
Section 3.1, a server should return the highest HTTP protocol version it
claims to support.

SocketInputStream - When parsing multi-line HTTP headers, correctly treat a
TAB character as whitespace.

HttpProcessor - [Bugzilla #3062] Make request URIs that contain "/..." return
"Bad Request".  On some (all?) Windows platforms, this would cause the OS to
walk up the directory tree and expose files, just like "../../.." type paths
would if they were not normalized.

WarpConnector - Brought the sources of the WARP connector (used to talk with
Apache+mod_webapp) up to date with the most recent bugfixes.  See below for
current information about this connector.


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

JSP Compiler - [BugTraq #4481010] Do not generate implicit import for
"javax.servlet.jsp.tagext.*".  The implicit import list now matches the
requirements of JSP 1.2 PFD3b, page 50.  Modified code generators as needed
to reflect this change.

JSP Compiler - [Bugzilla #2602] Correct code generated for Strings with
Unicode escape sequences like <%= "\u9b5a" %>, while still correctly dealing
with %\>.

JSP Compiler - [Bugzilla #2722] Correct the XML quoted value for the "double
quote" character (was incorrectly rendering as "&quote;" instead of "&quot;").

JSP Compiler - [Bugzilla #2748] Correct the pathname used to store template
text when the "largefile" initialization parameter (of the JSP servlet)
is set.  In addition, modify the generated code for this option to reflect the
fact that java.io.* is no longer implicitly imported.

XmlOutputter - [Bugzilla #2704] Correctly escape occurrences of "]]>" in XML
output inside a CDATA section.

JasperLogger - [BugTraq #4488877] Disable creation of useless background thread
per <jsp-file> declaration, which can eventually cause resource exhaustion.


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

WebdavServlet - Correct decoding of the destination header (was previously
handled by normalize).

WebdavServlet - Various fixes to support lock-null properties correctly.

WebdavServlet - Correct use of DocumentBuilderFactory, which is not threadsafe.


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


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

Previous versions of Tomcat 4.0 exposed the XML parser used by Jasper (the
JAXP/1.1 reference implementation) to web applications.  This is no longer
the case, because Jasper loads its parser with a new class loader instead.
Keep the following points in mind when considering how to use XML parsers
in Tomcat 4.0 and your web applications:

* If you wish to make the JAXP/1.1 RI XML parser available to all web
  applications, simply move the "jaxp.jar" and "crimson.jar" files from
  the "$TOMCAT_HOME/jasper" directory to the "$TOMCAT_HOME/lib" directory.

* If you wish to make another XML parser that is JAXP/1.1-compatible
  available to all web applications, install that parser into the
  "$TOMCAT_HOME/lib" directory and remove "jaxp.jar" and "crimson.jar"
  from the "$TOMCAT_HOME/jasper" directory.  It has been reported that
  Xerces 1.3.1 can be used in this fashion, but 2.x alpha releases
  can not be.

* If you wish to use an XML parser (such as Xerces) in the WEB-INF/lib
  directory of your web application, this should now be possible, because
  of the modified JAXP 1.1 parser mentioned below.

WARNING:  Tomcat 4.0 now ships with a modified version of the JAXP/1.1
(Final) "jaxp.jar" and "crimson.jar" files in the "jasper" subdirectory.
The "sealed" attribute has been removed from the manifest file for these
two JARs, to avoid "package sealing violation" errors that were caused by
them in a JDK 1.3 environment.  You MUST NOT replace these files with a
different (or later) release of JAXP, unless that later release has had
the sealed attribute removed, or you will encounter "package sealing violation"
errors when trying to use a different XML parser in a web application.


---------------------
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.

* There are several test failures in the "tester" unit test suite that will
  be corrected before final release.  (Most of these issues related to the
  bug that prevents BASIC authentication form operating.)
