                    Apache Tomcat Version 4.0.1 Beta 1
                    ==================================
                              Release Notes
                              =============

$Id: RELEASE-NOTES-4.0.1-B1.txt,v 1.1.2.2 2001/10/07 18:02:06 remm 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".

Only bugfix changes will be implemented before a Tomcat 4.0.1 final release is 
made available.


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


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

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

Build process:  The build process is now a lot more modular.

Xerces:  Switch to the XML parser used to Xerces 1.4.3.


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

ErrorReportValve:  Separate the error report generation from the standard
implementation of the pipeline, and put in in a valve which is now mapped at
the Host level.

ErrorDispatcherValve:  Separate the error dispatching from the standard
implementation of the pipeline, and put in in a valve which is now mapped at
the Host level.

ErrorReportValve:  Error reports generated by Catalina are now fancier.

StandardHost:  The StandardHost will automatically set up the error dispatcher
and error report valve.

Response:  Add new status flags allowing to separate the commit of the response
at the application level from its commit status at the connector level. That
allows fixing specification compliance problems when using sendRedirect, 
sendError or RequestDispatcher.forward.

ResourceAttributes:  The resource attributes now allows lazy loading of the 
attributes. It also avoids using complex object structure, like Hashtables.

FileDirContext:  The file directory context now takes advantage of the lazy 
loading.

ProxyDirContext:  Add resource content caching, which allows fixing some cache
consistency issues.

JasperLoader:  The JasperLoader has been removed, since no special handling of
the XML parser is needed.


----------------------
Connector New Features:
----------------------

AJP:  Add support for AJP 1.3.


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



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



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

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

Licensing fixes:  Add a license document for Tyrex, and remove ldap.jar.

Documentation:  Fix for various inconsistencies between the implementation and
what is indicated in the documentation.


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

NamingContext:  Fix a recursive method call.

WebappClassLoader:  Refuse loading base J2SE classes (java.*) or classes from 
the servlet API packages from the web application class repositories.

Default configuration file:  Fix incorrect indication that the session-timeout
is in seconds (it's in minutes).

InvokerServlet:  Fix problems when including the invoker servlet, which made
the first inclusion request fail.

Bootstrap:  Make the process of building class loaders much smarter about 
technologies that have been integrated into later versions of the JDK.

StandardContext:  Now, on an application reload (caused by automatic detection
of modified classes, or by manual request through the Manager servlet), all 
registered listeners, filters, and load-on-startup servlets will be 
reinitialized before the saved sessions are deserialized and reloaded.

CookieTools:  Avoid NullPointerException with malformed cookies with null names
or values.

ClassLoaderFactory:  Create class loaders in delegating mode.

StandardContextValve:  Remove legacy error report code, which makes the code
cleaner.

EmbeddedManager:  If the startup failed, the status reported was incorrect.

ProxyDirContext:  Fix cache consistency problems by tying the cache 
revalidation with the caching of the content, so that the resource attributes
and its content are always consistent.

RequestDispatcher:  Suspend the response when returning from a forward, instead
of finishing it.

HttpResponseStream:  Use setHeader instead of addHeader, which could lead to
header duplication, which could end up breaking the protocol in some cases 
(like a ranged request).

HttpProcessor:  Don't finish the response if an EOFException is raised when
trying to read the request header.

WebappClassLeader:  Implement getResources.

ProxyDirContext:  In addition to the last modified date, also use the content 
length to revalidate a cache entry.

DefaultServlet:  Don't set last-modified and don't check the If headers when 
serving a directory browsing page.

SSLServerSocketFactory:  Fix for possible unfreed resource.


-------------------
Connector Bug Fixes:
-------------------




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

Parser:  Fix NullPointerException when comments were embedded inside a useBean
declaration.

Compiler:  Fix problems with import declarations.

TagBeginGenerator:  Fix generated code for custom tag attributes of type 
Object, which are required to accept a literal String value.

Compiler: Catch NumberFormatException when attempting to get the line number 
from javac error messages, so that the messages will be dispalyed if we guess
wrong.  Also filter the line so that tags in strings are displayed correctly.

JspC:  Support tag library descriptors inside JARs when running command line 
compiles.

ForwardGenerator:  Values of <jsp:param> are URL encoded.


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

Simpletag example:  Fix non-existing tag library problem.

Sendmail example:  Fix typo in the resource parameters defined for the SendMail
factory.


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

2693    Syntax errors in JSP source generate NumberFormatException.
3617    "null" in JasperException.
3640    Fix for JSPC handling of tag libraries in a JAR.
3669    Improve Jasper error reporting (stack traces).
3695    Do not add ldap.jar to class path on JDK 1.3 or later.
3699    A recursive function call in org.apache.naming.NamingContext.
3707    Custom action attribute of type Object does not accept literal string 
        value.
3708    Ldap.jar has a questionable license.
3709    Tyrex license is not being followed.
3718    NEW_SPECS.txt file in src directory could confuse the inexperienced.
3724    WebApps do not autodeploy if appBase changed under Windows.
3733    Session serialization problem.
3736    Incorrect PathInfo on first invocation of servlet chain.
3739    Custom tag support error.
3740    Simple javabeans problem.
3759    Conversion from String to Object doesn't work.
3779    The value of <jsp:param> should be URL encoded.
3780    Documentation notes.
3796    XML Classloader problem has crept back in.
3809    Jar files in the wrong directories.
3817    Classpath loading priority doesn't match docs.
3822    Drive letter causes a NumberFormatException when JSP compile.
3841    Incorrect state reported by EmbeddedManager.java:start().
3845    Body content is supposed to be empty.
3885    Server.xml ResourceParam does not match envCtx.lookup.
3889    Documentation for "Remote Address Filter" and "Remote Host Filter" 
        incorrect.
3892    Can't compile 2092.jsp.
3910    Web.xml mime type incorrect for jnlp.
3936    ClassLoader.getResources does not work.
3949    Document with content-length of 0 results in resend headers.


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


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


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


-------------------------
Context reloading and JCE:
-------------------------

JCE's handling of custom security providers may make context reloading fail 
with a message saying that the class loader is stopped, followed by a stack 
trace.
The problem is that JCE attempts to use the class loader which originally
loaded the security provider, which is the old class loader.

There are two solutions to this problem. Either:
- Move JCE and your custom security provider to the shared class loader
- Use Security.removeProvider to remove the custom security provider on destory


