$Id$ Release Notes for ================= TOMCAT Version 3.1beta1 ======================= 0. TABLE OF CONTENTS: 1. Introduction 2. Installing and Running Tomcat 3. Application Development Using Tomcat 4. New Features In This Release 5. Known Bugs and Issues ============================================================================= 1. INTRODUCTION Tomcat is a servlet container and JavaServer Pages(tm) implementation. It may be used stand alone, or in conjunction with several popular web servers: - Apache, version 1.3 or later - Microsoft Internet Information Server, version 4.0 or later - Microsoft Personal Web Server, version 4.0 or later - Netscape Enterprise Server, version 3.0 or later You should read the License Agreement (in the LICENSE file of the top level directory), which applies to all software included in this release. ============================================================================= 2. INSTALLING AND RUNNING TOMCAT Tomcat requires a Java Runtime Environment conformant to JRE 1.1 or later, including any Java2 platform system. If you wish to develop applications, you will need a Java compiler, such as the one included in a Java Development Kit 1.1 or later environment, including JDKs conformant with Java2. For detailed information about installing and running Tomcat, point your browser at file "doc/uguide/tomcat_ug.html" under the directory into which you unpacked the Tomcat distribution. ============================================================================= 3. APPLICATION DEVELOPMENT USING TOMCAT Preliminary information on using Tomcat for developing Servlet/JSP based applications is provided in the included Application Developer's Guide. Point your browser at file "doc/appdev/index.html" under the directory into which you unpacked the Tomcat distribution. ============================================================================= 4. NEW FEATURES IN THIS RELEASE Many new features have been added to Tomcat since the 3.0 release. Among the most important are: - Connectors for using Tomcat to run servlets with Microsoft's IIS and Netscape's NES web server, as well as Apache and stand-alone. - Automatic generation of configuration files for Apache integration. - Automatic deployment of applications delivered as Web ARchive (WAR) files. To deploy an application, copy the WAR file to the $TOMCAT_HOME/webapps directory and restart Tomcat, after which the WAR file will be automatically expanded. To remove an application, remove the expanded directory (and the WAR file) for that application. - Automatic servlet reloading when servlet classes are changed in WEB-INF/classes or WEB-INF/lib/*.jar. This support can be configured on a per-web-application basis. - Enhanced support for logging on a per-Tomcat-component basis. - Minimal administration tool, allowing new web applications to be deployed into a running Tomcat environment, as well as removing existing applications. - Command line tool (jspc) to compile the JSP pages that comprise your application ahead of time. - Substantially improved installation and development documentation. ============================================================================= 5. KNOWN BUGS AND ISSUES 5.1 Using An Absolute Path as Document Root Under Windows In the TOMCAT_HOME/conf/server.xml file, you can declare a relative or absolute directory pathname for the docRoot attribute. If you wish to use an absolute pathname on a Windows system, you MUST include the drive letter in order to conform to Java's definition of an absolute path on this platform: GOOD: c:\mydirectory\mydocroot GOOD: c:/mydirectory/mydocroot BAD: \mydirectory\mydocroot BAD: /mydirectory/mydocroot Under Unix, absolute pathnames must begin with a slash ('/') character. 5.2 Container Managed Security Tomcat 3.1 has an experimental implementation of container managed security, as described in the Servlet API Specification, version 2.2, section 11. Please note the following information about this implementation: - BASIC authentication appears to work correctly, but has not been extensively tested. Please report any bugs you encounter here at . The example application has a protected area defined at the following URL: http://localhost:8080/examples/jsp/security/protected which can be accessed by any user defined in the configuration file $TOMCAT_HOME/conf/tomcat-users.xml that has been granted the appropriate roles. WARNING: Basic authentication is not suitable for general security use across the Internet, or across other insecure networks, because usernames and passwords are sent encoded, but not encrypted, with every single request. - Form based login is partially supported, but only lightly tested. To assist in debugging this feature, you can enable the partial support by using a nonstandard EXPERIMENTAL_FORM element in your application deployment descriptor (web.xml) file. It should not be enabled for any reason other than debugging Tomcat. - DIGEST authentication and HTTPS client authentication (i.e. SSL) are not supported in this release. 5.3 Using RequestDispatcher.include() on a Welcome File [Bug Report #160] Using the following technique triggers an IllegalStateException: OutputStream is already being used for this request: - You have a subdirectory under your document root (for example "subdir/"). - This subdirectory contains a welcome file that you have configured to be displayed when that subdirectory is requested on a URL (for example "index.html"). - You request a RequestDispatcher for path "/subdir" or path "/subdir/" and then call include() on it. The same problem can occur when you do a to a page "/subdir" or "/subdir/" as well. A workaround is to ask for a RequestDispatcher on the complete context- relative path of the file you wish to have displayed, such as "/subdir/index.html".