$Id$ Release Notes for: ================== TOMCAT Version 3.2 ================== 0. TABLE OF CONTENTS: 1. Introduction 2. Installing and Running Tomcat 3. Application Development Using Tomcat 4. Tomcat: Past, Present, and Future 5. New Features In This Release 6. 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. TOMCAT: PAST, PRESENT, AND FUTURE - Version 3.0 (released 12/1999) was the initial release of Tomcat. In addition to implementing the Java Servlet and Server Pages specification, this release featured a minimal Apache connector. - Tomcat 3.1 (released 4/2000) improved the Apache connection and added connector support for Netscape and IIS web servers. It also added WAR file support, automatic servlet reloading, and a command line tool (jspc) to compile ahead of time the JSP pages that comprise your application. Finally, version 3.1 also focused on reorganizing the code (modularization, cleanup, refactoring, removal of dead code, and separation of J2EE-specific code). - Tomcat 3.2 is the first performance tune-up, and also adds a few new features (see next section). - Tomcat 4.0 is separate development from Tomcat 3.x. It is based on the Catalina architecture, which is very different from the architecture of Tomcat 3.x. In addition, Tomcat 4.0 is to be the reference implementation for the Servlet 2.3 and JSP 1.2 specifications. ============================================================================= 5. NEW FEATURES IN THIS RELEASE Tomcat 3.2 is mainly a performance tune-up release, although a few new features have been added. - Support for mod_jk, which is a replacement to the elderly mod_jserv, has had several bugs fixed and has received much more testing. It is now recommended that all users use mod_jk instead of mod_jserv. - Support JAXP-based XML parser independence. - New and often requested "how-to" documents covering the following topics: - Configuring workers.properties - IIS and Netscape configuration - Running tomcat inside an IIS or Netscape process - Running Tomcat as a Windows NT service - Configuring a JDBC realm - Configuring mod_jk - First round of policy-based security support intended for running untrusted code inside of Tomcat. Interested users should test this support and post feedback to the Tomcat users mailing list. - SSL support for standalone Tomcat. (Preliminary support first appeared in 3.1, but the support in 3.2 has received more testing and documentation support. - Thread reuse is now enabled by default. The thread pool support code was part of 3.1, but not enabled since it was new. - Support for plug-able session managers. Unfortunately, no how-to documents that support this functionality exist (yet). For the adventurous, be aware that the interface that allows administrators to plug session managers is the normal Interceptor interface. - An almost total rewrite of the HTTP request handling now results in improved performance when running Tomcat stand-alone. - Significantly reduced garbage collection. - The code has undergone a refactoring effort resulting in (we hope) improved readability. - And of course, hundreds of miscellaneous improvements and fixes. ============================================================================= 6. KNOWN BUGS AND ISSUES 6.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. 6.2 Container Managed Security Tomcat 3.2 has an 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 and FORM based authentication should work correctly. 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. Form-based authentication is used by default, but a commented out setting for Basic authentication is provided if you wish to give it a try. 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. - DIGEST authentication and HTTPS client authentication (i.e. SSL) are not supported in this release. 6.3 Using RequestDispatcher.include() on a Welcome File [Bug Report #160] Using the following technique results in a response with incorrect content: - 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". 6.4 Automatic Servlet Reloading Tomcat 3.2 includes a feature whereby you can ask it to automatically reload servlet classes (loaded from either the WEB-INF/classes directory or a JAR file in the WEB-INF/lib directory) that have been changed. This feature is experimental, and may not be completely functional. In particular, changes to classes other than the servlet you are requesting do not trigger class reloads -- you will need to restart Tomcat to reflect changes in those classes. Reloading is enabled by including a reloadable="true" attribute on the element in the "conf/server.xml" file. Note that automatic reload support is not recommended for production applications because of its experimental nature, and the extra overhead required to perform the necessary checks on every request. 6.5 Returned strings from getServletPath, getPathInfo, and getPathTranslated The Servlet 2.2 Errata - April 27, 2000 specifies that HttpServletRequest methods getServletPath, getPathInfo, and getPathTranslated should return decoded strings. This clarification has not been implemented in Tomcat 3.2. In Tomcat 3.2, these methods return encoded strings. 6.6 Avoiding "Out of environment space" errors on Windows 95/98 This error can easily occur since the default amount of environment space is typically insufficient to run Tomcat. Here are a couple of ways to avoid it. A. If you use the MS-DOS Prompt to start Tomcat, execute Programs -> MS-DOS Prompt. Right-click the MS-DOS icon on the left of the title bar and select Properties at the bottom of the menu. In the MS-DOS Prompt Properties dialog select the Memory tab. In the "Initial environment:" field, set a sufficiently high number. If you are not sure, 3072 should be plenty. Click OK and close the MS-DOS Prompt window. Execute Programs -> MS-DOS Prompt again, navigate to the directory where you installed Tomcat. Set the JAVA_HOME environment variable if not set already. You should be able to execute "bin\startup" and "bin\shutdown" to start and stop Tomcat without getting an "Out of environment space" error. B. If you want to start Tomcat by double clicking a batch file such as startup.bat, you should right-click on the desired batch file in Windows Explorer and select Properties to open the MS-DOS Prompt Properties dialog. Select the Memory tab and set the "Initial environment:" as described above. You may want to also select the Program tab and check "Close on exit". Then click OK. A shortcut with these settings will be created in same directory with the same base name as the batch file. You should be able to double-click the shortcut or the batch file to execute without getting an "Out of environment space" error. If you wish to execute startup.bat and shutdown.bat in this fashion, you will need to do the above for both files. In addition, you need to provide for setting JAVA_HOME. This may be done by adding a "SET JAVA_HOME=path to your jdk" line to your autoexec.bat or to the startup.bat and shutdown.bat files themselves. 6.7 URL's are now case sensitive on all operating systems As of Tomcat 3.2, URL's are case sensitive for all operating systems, including operating systems which have case insensitive file systems, such as Windows. This represents a change from Tomcat 3.1, where URL's were case insensitive on case insensitive OS's. This was done for a number of reasons, security and portability among them. A "non-portable" web application, i.e. one with case mismatches, which worked on a case insensitive OS under Tomcat 3.1 will show its non-portability when run under Tomcat 3.2. This can also cause URL's that look correct to actually be incorrect. In Windows Explorer, a directory whose name fits within the MS-DOS 8.3 format may be displayed using a "formated" name. For example, a directory named "MYDIR" may display as "Mydir". A URL like "http://localhost/mysite/Mydir/ index.jsp" would return "File Not Found" because the correct URL would be "http://localhost/mysite/MYDIR/index.jsp". If you find URL's being mysteriously "not found", check for case mismatch. Use the Windows Explorer Properties dialog or an MS-DOS window to check the actual case of the file and directory names. This can cause an additional problem when Tomcat is used with a case insensitive web server, such as IIS, where the web server serves the static content. The web server could serve a static page with mismatched case in the URL. If that static page contains relative links to resources served by Tomcat, then invoking those links would carry the mismatched case to Tomcat where it cause the resource not to be found. 6.8 Container Managed Security Constraints Due to the way that Tomcat 3.2 is implemented, container managed security constraints are imposed both on the original request URI *and* on subrequests initiated to handle RequestDispatcher.forward() or RequestDispatcher.include() calls. Whether or not this should actually be done was not defined in the Servlet 2.2 Specification, but has been clarified in 2.3 -- security constraints should only be applied on the original request URI. For future compatibility, you should be aware of this issue as you design your security constraint architecture, to avoid portability problems if you ever migrate to a different Servlet 2.2 container (which might implement this differently), or to a Servlet 2.3 container at a later date.