             Apache Tomcat Version 4.0 Release Candidate 1
             =============================================
                            Release Notes
                            =============

$Id: RELEASE-NOTES-4.0-RC1.txt,v 1.1 2001/09/10 05:52:22 craigmcc 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.


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

Made it possible to start Catalina under a JPDA debugging environment via the
command "$CATALINA_HOME/bin/catalina.sh jpda start".

It is now possible to share a single instance of Catalina among multiple
independent executions, by defining a new environment variable named
CATALINA_BASE.  The following directories are now resolved (by default)
against CATALINA_BASE instead of CATALINA_HOME:
* conf
* logs
* webapps
* work


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

FileDirContext:  Sort the directory listing returned when there is no welcome
file (and directory listings are not suppressed) for webapps that are unpacked
into a real directory.

WARDirContext:  Sort the directory listing returned when there is no welcome
file (and directory listings are not suppressed) for webapps that are executed
directly from a WAR file.

Server/StandardServer:  Add a singleton (and corresponding static method) that
will return the top of the component tree, without requiring a reference to
any component in the tree.

Engine/Service:  Add navigational link properties so that the entire Catalina
component hierarchy can now be navigated.  This will be important in
management applications.

BeanFactory:  Add a new JNDI resource factory for resource objects conforming
to the JavaBeans component model.

When an application web.xml file specifies one or more <welcome-file> elements,
this list *replaces* (rather than appends to) the default list from
$CATALINA_HOME/conf/web.xml.

The "User Web Applications" feature (see the <Host> element documentation) now
recognizes user "public_html" directories if they exist, are directories, and
are readable.  Previously, this feature also required the existence of a
/WEB-INF/web.xml file.

The built in servlets that are part of Catalina are now delivered as separate
JAR files in $CATALINA_HOME/server/lib, so that you can give them individual
permissions when running Tomcat 4 under a security manager.

StandardContext:  Synchronize start/stop/reload processing to avoid some
nasty race conditions.

CompressionFilter:  Properly flush the compressed output, even if the servlet
does not close the output stream or writer.


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

Generated filenames for the servlets created from JSP pages no longer include
the complete directory path, since they are stored in directory structures that
mirror the web application.  This substantially reduces problems with path
length limits on Windows systems.


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

All of the Tomcat 4 documentation has been converted to a new standardized
format, under context path "/tomcat-docs".  In addition, *many* new System
Administrator HOW-TO documents are included.

Servlet mappings for the CGI and SSI servlets have been commented out in
"$CATALINA_HOME/conf/web.xml".  You can uncomment them here (to enable these
services for all web applications) or add them to your own web application
(if they are needed only in specific applications).


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

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

Documentation: Updated all references to TOMCAT_HOME in the documentation to
be CATALINA_HOME. (Thanks to Dennis Doubleday for noticing)


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

Bootstrap:  Do not load "jndi.jar" on a JDK 1.3 or later system, in *any* of
the class loaders we are creating (because it is built in to the JDK in 1.3).
Previously, we were only checking this for the common class loader.

Bootstrap:  Fix more cases of platform-sensitive classpath paths on Windows.

StandardClassLoader:  Make StandardClassLoader sensitive to File.separator.

HttpRequestBase:  Fix bugs in ServletRequest.getRequestDispatcher() when
called with paths that had "/../" elements.

StandardWrapper:  Do not allow a servlet unload() operation to begin if there
are any current requests executing within this servlet.

CGIServlet:  Make it not possible to use the "invoker" service to execute
CGIServlet when it is not mapped.

CGIServlet:  Send a 404 when the CGI script does not exist.

InvokerServlet:  Synchronize around the initial creation of a new Wrapper for
the invoked servlet, to avoid race conditions when multiple requests try to
create the same wrapper at the same time.

StandardServer:  Fix a DoS attack against the shutdown port, that could cause
an "out of memory" exception by sending a continuous stream of characters.

StandardWrapperValve:  Fix handling of UnavailableException thrown by the
service() method.  The spec requires that the servlet instance be taken out
of service immediately (including a call to destroy()).  In addition, return
status 503 (SC_SERVICE_UNAVAILABLE) rather than 500 (SC_INTERNAL_SERVER_ERROR).

HttpResponseBase:  Make it possible to call sendRedirect() to a URL with a
protocol not supported by the current server (such as a redirect to an
"https" URL on another server, when this Tomcat instance does not have the
JSSE classes installed.

DefaultServlet:  A 206 status returned the wrong content length.

WebappClassLoader:  Synchronize before calling defineClass().

HttpConnector:  Fix race conditions during HTTP connector shutdown.

FormAuthenticator:  Do not double up query-string based parameters when
restoring the original request after a form-based login.  This was only
happening on GET requests -- POST requests were already processed correctly.

Base64:  Update Base64 implementation to eliminate trailing 00 bytes from
the output of decode().

CookieTools:  URL encode the name and value of generated cookies, since we
URL decode them on input.

WebdavServlet:  Return status 405 (method not allowed) in response to a
PROPPATCH request.

SSLServerSocketFactory:  Make it possible to specify absolute or relative
(to $CATALINA_BASE) paths for the "keystoreFile" property.

JDBCRealm/JNDIRealm/MemoryRealm:  When comparing the hexadecimal versions of
digested passwords, perform a case-insensitive comparison to avoid problems
comparing "a-f" with "A-F".


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

JikesJavaCompiler:  Normalize the classpath Jikes is invoked with so that it
doesn't contain file URLs like "/c:/tomcat/webapps/..." on Windows.  Add "+E"
option to Jikes command line so that error output parsing works.

IncludeGenerator/JspRuntimeLibrary/PageContextImpl:  Fix a spec-compliance
bug in the implementation of PageContext.include(), which was not flushing
the output stream even though this is explicitly required in the Javadocs.

JspServlet:  Change the way that Jasper looks for the "?jsp_precompile"
request parameter.  Previously, it was using request.getParameter(), which
caused all of the request parameters to be parsed before the JSP page
would have the opportunity to call request.setCharacterEncoding().

TagBeginGenerator:  Fix problems when generating code for custom tag attributes
of type char, Character, or short.

XmlOutputter:  Fix problems in the generated XML view of a JSP page that would
cause duplicate <jsp:root> elements or attributes when processing a page that
was already in XML syntax.

JspC:  Update web.xml fragments generated by jspc command line compiler
to use the appropriate DTD header, and generate valid <servlet-mapping>
elements.

TagGeneratorBase:  Create valid custom tag names even when characters not valid
in Java identifiers are included.


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

Updated all examples to the new DTDs and tag library syntax.


============================
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 "$CATALINA_HOME/jasper" directory to the "$CATALINA_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
  "$CATALINA_HOME/lib" directory and remove "jaxp.jar" and "crimson.jar"
  from the "$CATALINA_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.

* Make sure you do *not* place an XML parser in your Java system extensions
  directory ($JAVA_HOME/jre/lib/ext), or modify the startup scripts to include
  such a parser in the CLASSPATH under which Tomcat executes.

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


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


