Apache Tomcat Version 4.0 Release Candidate 1 ============================================= Release Notes ============= $Id$ ============ 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 elements, this list *replaces* (rather than appends to) the default list from $CATALINA_HOME/conf/web.xml. The "User Web Applications" feature (see the 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 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 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.