Apache Tomcat 4.1.x is an implementation of the Java Servlet 2.3 and JavaServer Pages 1.2 Specifications. It is open-source software developed under the Apache license. See http://tomcat.apache.org/ for details.
There have been numerous releases of Tomcat 4.1.x. The Java components from SAS have been tested using Tomcat 4.1.18. Thus, webAF uses Tomcat 4.1.18 as its integrated Web server for testing Web applications and applets.
The Java components from SAS have not been thoroughly tested on any version of Tomcat newer than 4.1.18. Behavior of the Java components from SAS is expected to be the same in newer versions of Tomcat 4.1.x. However, until this is verified, you should thoroughly test your Web application for proper behavior if you are using a newer version of Tomcat. SAS advises thorough testing, even when you are using Tomcat 4.1.18, to validate Web application behavior in your particular configuration.
In the discussion that follows, the term "Tomcat 4.1.x" is used to refer to Tomcat 4.1.18 or newer. Using a version of Tomcat 4 prior to Tomcat 4.1.18 is not recommended. This paper covers the following topics:
The Apache Software Foundation site provides two forms of binary installations for Tomcat 4.1.x. For a broad range of systems, archives are provided in the form of .tar.gz and .zip files. For Windows systems, an executable file (*.exe) is available for you to install Tomcat 4.1.x. The directory in which Tomcat is installed or expanded should not contain any spaces in its path. Web applications that use RMI will have problems if the install path contains spaces. If you use the Windows executable file, you will have to modify the default installation path.
If you want to install Tomcat as a service using the Windows executable file,
be sure that you set the JAVA_HOME environment variable prior to running the
installation. This enables you to specify the JDK that you want Tomcat 4.1.x
to use. You cannot specify the JDK during the installation. If you do not set
the JAVA_HOME environment variable, the "Apache Tomcat 4.1" service
will run using your most recent JRE. This occurs because the install needs a
path to a jvm.dll file, which is easily obtained from the registry
for a JRE, but is difficult to derive for a JDK.
To simplify support for running Tomcat as a service, the installation
always copies the tools.jar file from the JDK to the
<catalina_home>\common\lib directory. This will not cause
a problem if nothing changes. However, if you try to customize, upgrade, or
reinstall either Tomcat or Java, then there are scenarios where the
tools.jar file can get out of sync with the JDK or the JRE that
is being used, which leads to unexpected behavior. Keep this in mind when you
make changes to your installation.
A simple solution to these service issues is to reinstall the service,
making sure the jvm.dll file you want is used, and including the
tools.jar file in the classpath so it can be removed from the
commons\lib directory. To do this, stop the
Apache Tomcat 4.1 service, if it is currently running. Then uninstall
the service by executing the following command:
<Tomcat 4.1.x install directory>\bin\tomcat.exe - uninstall "Apache Tomcat 4.1"
Place the following commands in a batch file, and be sure that tomcat.exe command is on a single line.
set JAVA_HOME=<JDK install directory>
set CATALINA_HOME=<Tomcat 4.1.x install directory>
set CATALINA_OPTS=<Tomcat options>
rem The following command should be on a single line
"%CATALINA_HOME%\bin\tomcat.exe" -install "Apache Tomcat 4.1"
"%JAVA_HOME%\jre\bin\server\jvm.dll"
-Djava.class.path="%CATALINA_HOME%\bin\bootstrap.jar;%JAVA_HOME%\lib\tools.jar"
-Dcatalina.home="%CATALINA_HOME%"
-Djava.endorsed.dirs="%CATALINA_HOME%\common\endorsed"
%CATALINA_OPTS%
-start org.apache.catalina.startup.BootstrapService -params start
-stop org.apache.catalina.startup.BootstrapService -params stop
-out "%CATALINA_HOME%\logs\stdout.log" -err "%CATALINA_HOME%\logs\stderr.log"
Modify the path to the jvm.dll file as needed. Then, execute the batch file. This duplicates the default service installation, but with the jvm.dll and tools.jar files specified in the classpath. You can then remove the tools.jar file from the commons\lib directory. This batch file also provides a CATALINA_OPTS environment variable to supply additional JVM options and System properties, if needed.
Before determining how you want to deploy Web applications to Tomcat 4.1.x, you should
first consider how you want to administer your Tomcat's configuration. Tomcat's
configuration is controlled primarily by the server.xml file, which is
found in Tomcat's conf directory. One way to administer Tomcat's
configuration is to manually edit this file with a text editor. An alternative
way is to use the admin Web application that included in the Tomcat
binary installation.
The point of this choice is that these two methods do not mix well.
Once you save a change to the configuration with the admin Web application,
then the server.xml file is rewritten (after a back-up copy is made)
without any comments and little formatting. As a result, it becomes difficult to
edit manually after that. Also, Web application contexts that are present
are included in the rewritten server.xml file. These context
declarations will take precedence over any context XML files that might have
previously defined that Web application's configuration. Automatic deployment
features will still work for new Web applications; however, they stop being automatic
with the next rewrite of the server.xml file.
Tomcat 4.1.x also includes a manager Web application. It supports
deploying and managing Web applications and related resources. Its
deploy command also rewrites the server.xml file, which encourages you to
use the admin Web application for administering Tomcat configuration.
If you want to retain manual control over your Web application deployments, you
should not use the admin and manager Web
applications to make permanent configuration changes.
For information about configuring Tomcat 4.1.x, refer to the documentation found in your Tomcat 4.1.x installation. With Tomcat running, go to the Tomcat home page and click the Tomcat Documentation link. Then on the left hand side of the displayed page, click the Reference link found under Configuration heading.
Tomcat 4.1.x supports the auto-deployment of Web applications with respect to
the appBase attribute of the <Host> element, which is found
in the server.xml file. Auto-deployment primarily refers to the
automatic creation of contexts within the Web server to serve Web applications
that are not explicitly declared using a <Context> element.
The default Tomcat 4.1.x installation comes with an appBase set to the
webapps directory within the Tomcat installation. Web application
source directories or WAR (Web Archive) files placed in this directory will have contexts
automatically created for them, if they are not already declared.
If the <Host> element's liveDeploy attribute is
set true, then new source directories and WAR that are files added while
Tomcat is running will automatically be deployed. If the attribute is set to false,
then you will need to restart Tomcat to auto-deploy new Web applications.
The unpackWars attribute of the <Host> element
determines how WAR files are auto-deployed. If the element is set to true, then the WAR
file is expanded and the context is created to serve the created source directory.
If the element is set to false, then the context is created to serve the WAR file
directly.
The contexts created for auto-deployed Web applications receive context default settings. The path attribute defaults to the name of the source directory or the name of the WAR file without the .war file extension. The docBase attribute defaults to the path of the directory or WAR file that is being served. Other context attributes contain default values as determined by your Tomcat configuration. Refer to the Tomcat documentation for more details.
If some context attributes need values other than the default, then the
context must be declared using a <Context> element to
specify the necessary values. The existence of such a context declaration disables the
auto-deployment of the Web application, provided that it specifies the same
default value for the path attribute. If the declaration specifies a
different path attribute, then two instances of the Web application
will be served. One context will have the declared path and one
auto-deployed context will have the default path. Thus, placing a Web
application under the directory specified by the appBase attribute
imposes the restriction that it has to be served with a path that matches the
default value.
If the deployXML attribute of the <Host> element
is set true (the default) along with the autoDeploy
attribute, then XML files which contain a single <Context>
declaration might be placed in the directory specified by the appBase
attribute. Contexts for such XML files will be created according to the
<Context> declaration and your Tomcat configuration.
Refer to the Tomcat documentation for more details.
This form of deployment has a couple of advantages over the auto-deployment of Web application source directories and WAR files described above. First, the docBase attribute may point outside of the Tomcat installation, if desired. Second, you can specify a path attribute that does not need to match the source directory or WAR file name. This assumes you have not put the source directory or WAR file under the directory specified by the appBase attribute.
If you use the manager Web application to deploy WAR files, it is
still possible for you to use this form of deployment. Create a file named
context.xml in a META-INF subdirectory of your Web
application. Declare the desired <Context> element in this
file, without the path and docBase attributes. Then deploy the
WAR containing this XML file using the managerapplication. Note that with this
deployment approach, you can only serve the Web application directly from
the WAR file.
Regardless of configuration, Context elements can be declared
in the server.xml file. This form of deployment has the same
advantages as using the context XML files. These declarations take precedence over
the other methods for contexts with the same path. This is the method
that the manager and admin Web applications use to persist
deployed Web applications.
If you manually modify the server.xml file, then you will have to
restart Tomcat to serve the new Web applications. To deploy new Web
applications while Tomcat remains running, use the manager or
admin Web applications.
Tomcat 4.1.x supports serving either a source directory or WAR file. If you are using Tomcat 4.1.24 and later and are using the manager Web application for deployment, there is an additional consideration when making this choice. In Tomcat 4.1.24 and later, the manager Web application honors the unpackWARs attribute. If you always deploy WAR files such that they are served from the WAR, you can avoid the following issue, which is still true at least through Tomcat 4.1.29.
If the unpackWARs attribute is set to
trueand you use the manager "deploy" command to deploy a WAR file which doesn't contain aMETA-INF/context.xmlfile, it will be auto-expanded and served from the source directory. In this case, undeploying or redeploying using manager fails with a message about being unable to remove the document base for the Web application. The managerremovecommand works; however, it does not rewrite theserver.xmlfile with the context removed. The removal is not persisted in theserver.xmlfile unless some other command or action causes it to be rewritten.
If you start Tomcat from the batch scripts, you might want to specify JVM options
and the System properties using the CATALINA_OPTS environment variable. The
catalina.bat and catalina.sh batch scripts both
incorporate the contents of this environment variable into the Java command
line at a suitable location. You will typically want to specify at least
the minimum and maximum JVM heap sizes.
If you are running on Windows system and you installed Tomcat 4.1.x to run as a service, then you will need to manually re-install the service to add or modify the JVM options and start-up System properties. Instructions on how to re-install the service are found in the section on Installing Tomcat 4.1.x.
You can augment or replace the default JVM runtime permissions using the
java.security.policy System property to specify the path to
a policy file. This System property is unique in that it can use "="
or "==" to indicate whether the policy file specified should append
to, or replace the default permissions. If you use the "=", the
permissions in the specified policy file are appended to the default
permissions. If you use the "==", then the permissions in the specified
policy file replace the default permissions.
When you start Tomcat 4.1.x using the batch scripts, adding a
"-security" command line argument will cause a
java.security.policy System property to be automatically included
in Tomcat's Java startup command. It uses the "==" and names the
catalina.policy file in the conf directory as the
policy file. You can append any runtime permissions required by the Web
application to this file.
If you use the Windows service to run Tomcat 4.1.x and the
java.security.policy System property is not already present
(it is not in the default installation), then you will need to re-install the service.
Include the java.security.policy property with it pointing to the
catalina.policy file, or suitable alternative.
Since System properties can be used within the permissions, effective
use of System properties within the policy file can eliminate, or help minimize,
the changes that are needed when the permissions are added to the target application server
or the servlet container. Adjusting System properties is safer and easier
than directly editing the permissions that have been added to the
catalina.policy file.
If you use SAS Foundation Services to access an Open Metadata Repository, as well as certain other operations, then you will need a couple of run-time permissions, even if a security manager is not enabled. These permissions are the following:
permission com.sas.services.user.CredentialPermission "readCredential", "ReadCredential";
permission com.sas.services.user.UserContextPermission "*", "read";
These run-time permissions must be granted to the Web application's code
base. In a SAS AppDev Studio installation, these permissions can be found in the
java.app.policy file in the webAF\resources
directory.
A java.webapp.policy file is also included in the webAF\resources
directory. This is a version of the catalina.policy from
Tomcat 4.1.18 that has been modified so that it can be appended to the JVM
default permissions. It includes a standard set of permissions that support use
of SAS Foundation Services. It makes use of a number of System properties to
specify what servers can be accessed, as well as a System property to specify
the Web application's code base.
Web application projects that webAF creates will contain their own copy of
the java.webapp.policy file in the home directory of the project.
If the Web application requires any extra permissions, they should have been
added to this file. Use this copy as the source of permissions that you want
to append to the catalina.policy file, or another appropriate file,
being used by Tomcat.
To enable a security manager, include a java.security.manager
System property on the Java start-up command. If it does not specify a security
manager class, then the default security manager class is used.
When you start Tomcat 4.1.x using the batch scripts, adding a
"-security" command line argument will cause the
java.security.manager System property to be automatically included
in Tomcat's Java startup command. If you use the Windows service, then you will need
to re-install the service, and add this System property, if necessary.
Instructions on how to re-install the service are found in the section on
Installing Tomcat 4.1.x.
If you enable a security manager and your Web application uses JAXP for parsing or XML transformation, you might wish to add the following set of permissions:
permission java.util.PropertyPermission "javax.xml.parsers.DocumentBuilderFactory", "read";
permission java.util.PropertyPermission "javax.xml.parsers.SAXParserFactory", "read";
permission java.util.PropertyPermission "javax.xml.transform.TransformerFactory", "read";
permission java.io.FilePermission "${java.home}${/}lib${/}jaxp.properties", "read";
permission java.io.FilePermission "${java.home}${/}lib${/}rt.jar", "read";
These permissions may be granted to specific Web applications or granted
more globally. It most cases, they help avoid unnecessary exceptions that
would otherwise occur during initialization of the XML parser or transformer.
However, in some cases, they avoid exceptions that would cause the operation
to fail. For example, if a JSP page tries to instantiate the default Xalan XML
transformer, read permission will be required for rt.jar.
Otherwise, a permission exception will prevent the transformer from being
instantiated.
WebAF includes the permissions shown above in a global grant
block found in the java.webapp.policy located in the
webAF\resources directory. This global grant includes two
additional permissions that are also not found in the default
catalina.policy file. One is the following permission, which
avoids an unnecessary exception when compiling JSP pages:
permission java.lang.RuntimePermission "defineClassInPackage.org.apache.jasper.runtime";
The other added permission is described here.
This section addresses known issues in specific Tomcat versions that specifically affect SAS AppDev Studio software. It does not try to cover known bugs in the various Tomcat versions. For information about Tomcat bugs, refer to the bug database that is available on the Apache Software Foundation site.
After starting Tomcat, version 4.1.18 through 4.1.27, with a security manager, servlets will be unable to create or check for sessions due to a permissions failure when trying to load a required class. This is documented in the Apache Software Foundation Bugzilla Database as Bug #17523. Since JSP page execution has sufficient permission, once a JSP page instantiates a session and loads the required class, servlets can create and access sessions normally. Tomcat 4.1.28, and later, avoid this problem by loading the required class at startup.
To work around this problem in Tomcat 4.1.18 through 4.1.27, include the
following permission in your Tomcat's catalina.policy file. It is
best to add it within a global grant block, so it applies to all
Web applications.
permission java.lang.RuntimePermission "defineClassInPackage.org.apache.coyote.*";
This permission can be found in the java.webapp.policy
file located in the webAF\resources directory of your AppDev
Studio installation.
There is an important difference between Tomcat 4.1.29 and prior Tomcat 4.1.x releases. This difference can cause problems for localized Web applications which use the Java Components provided by SAS AppDev Studio.
Tomcat 4.1.29 shares some code with Tomcat 5, where earlier versions of Tomcat 4.1.x use an older independent branch of this code. By using the current code, Tomcat 4.1.29 picked up some, but not all of some changes to implement the W3C standard that the entire request URL be encoded with UTF-8. As a result in Tomcat 4.1.29, the path portion of request URLs are decoded using UTF-8 and the query string, if present, is decoded with the JVM default character encoding. Also unlike prior versions, ServletRequest.setCharacterEncoding() in Tomcat 4.1.29 no longer affects the query string. This change is consistent with the Servlet 2.3 specifications, which only promises that setCharacterEncoding() affect the request body.
The Java Components from SAS are affected by this, because in a limited number of cases, the response might include HREFs that contain query strings with UTF-8 encoded non-ASCII characters if a non-English language is in use. In this case, the value of the query parameter will be decoded incorrectly if that link is accessed. As a result, we recommend that you not use Tomcat 4.1.29 for serving Web applications developed using the Java Components from SAS, unless its use is restricted to English environments.