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 that is developed under the Apache license. For more information, see the Apache Software Foundation Web site.
There have been numerous releases of Tomcat 4.1.x. The Java components from SAS have been tested using Tomcat 4.1.18. Thus, the SAS AppDev Studio "Create required servers" cheat sheet and other documentation specifically requires Tomcat 4.1.18 as the version to use for testing SAS Web Application Projects.
The Java components from SAS 9.1.3 Service Pack 4 have not been thoroughly tested on any version of Tomcat newer than 4.1.18. The behavior of these Java components is expected to be the same in newer versions of Tomcat 4.1.x; however, you should verify this for your situation. SAS advises thorough testing (even when you use Tomcat 4.1.18) to validate the Web application behavior for your particular configuration.
In this document, 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. If you decide to try Tomcat 5.0.x or Tomcat 5.5.x, be sure to check the known issues for Tomcat 4.1.29 section for some important information. Other than this, details specific to Tomcat 5.0.x and 5.5.x are not included.
This document covers the following topics:
This information refers to a Tomcat installation separate from the
one installed and used with the SAS AppDev Studio 3.2 Eclipse Plug-ins.
If you want to deploy to a Tomcat 4.1.18 running on the same system as
SAS AppDev Studio, you do have the option to use the Tomcat 4.1.18
installed for SAS AppDev Studio. Just be aware that when a Tomcat server
is created within Eclipse, that server will use imported copies of the
catalina.policy, server.xml,
tomcat-users.xml, and web.xml files with
whatever contents they have at the time. If these files contain changes
related to your deployments, you might need to undo those changes in the
files created under the corresponding folder in the Servers project in
your Eclipse workspace. The following information assumes that you are
installing a separate Tomcat on either the same or another system.
The Apache Software Foundation Web 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 the Windows environment, 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,
make 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,
make sure the jvm.dll file you want is used, and include 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 make sure that the
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, see 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 (under the 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 the appBase attribute
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 to true, then new source directories and WAR that are files that
are 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 the WAR file that is being served. Other context attributes contain default values
as determined by your Tomcat configuration. For more information, see the Tomcat
documentation.
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
attribute that matches the default value.
If the deployXML attribute of the <Host> element
is set to true (which is the default) along with the autoDeploy
attribute, then the XML files that 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.
For more information, see the Tomcat documentation.
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 <Context> element that you want in this
file, without the path and the docBase attributes.
Then deploy the WAR file that contains this XML file using the
manager application. Note that with this deployment approach,
you can only serve the Web application directly from the WAR file.
All of the SAS Web application example templates will create a
META-INF/context.xml file in the Web content source folder for
your SAS Web Application Project. The purpose of this file is to deal with the
Tomcat 4.1.x HTTP session serialization issue.
The Tomcat support within Web Tools will use this file when
testing the Web application on a Tomcat server. This support ignores the
path and docBase attributes, substituting appropriate
values to ensure they will be correct for testing. This implies that
this file can be used as the basis for a context XML file with the path
and docBase attributes as you set them in preparation for deployment.
This is one of the best deployment strategies to use with Tomcat, because
you can keep your testing context configuration the same, or at
least similar, to your intended deployment configuration.
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.
As mentioned in the prior section, the META-INF/context.xml file
that is created by the SAS Web application templates can be useful in this form of
deployment too. It provides the XML, with appropriate changes to the
path and docBase attributes, that should be inserted in the
server.xml file.
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 so
that they are served from the WAR file, you can avoid the following issue (which
is still true at least through Tomcat 4.1.29):
If the
unpackWARsattribute is set totrueand you use the manager "deploy" command to deploy a WAR file that does not contain aMETA-INF/context.xmlfile, it will be auto-expanded and served from the source directory. In this case, uninstalling or redeploying using the 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 does not persist 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 the
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 the maximum JVM heap sizes.
If you are running in the Windows environment 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 the start-up system properties. For instructions on re-installing the service, see the Installing Tomcat 4.1.x section.
SAS Web Application Projects will likely contain a
launchParameters.txt file. This file contains options
needed for testing within the Eclipse environment, but many of which
will also be needed during deployment. The first option will be a system
property that relates to the name of the project. It is used as part of
the codeBase parameter of the Web application's grant blocks in the
java.webapp.policy file for the project. It might or might not be needed
depending what the codeBase parameter needs to be in the deployed version
of the policy file.
Next in the launchParameters.txt file, there might be some
memory size options. These should be adjusted as needed for you
deployment environment. Typically a system property named
java.security.auth.login.config will come next. If not already
specified in your Tomcat startup, you will need to include this system
property and set its value to point it to a suitably located copy of the
login.config file from the project's root directory. If this system
property is already defined, you will need to merge the contents of the
project's login.config with the one that Tomcat is already using.
The remaining properties in the launchParamters.txt file
are likely properties that relate to various servers used by the Web application.
These properties simplify the deployment of Java security permissions that are
needed to connect to the servers used by the Web application. The
benefit of this approach is described in the following section.
For SAS Web Application Projects that use SAS Foundation Services,
the launchParameters.txt file includes documentation about
other JVM options that might be appropriate. For more information, see
the "Best Practices for Configuring Your Middle Tier" chapter in the
SAS
9.1.3 Intelligence Platform: Administration Guide.
You can augment or replace the default JVM run-time permissions using
the java.security.policy system property to specify the
path to a policy file. This system property is unique in
that it uses equal signs to indicate whether the specified policy file
should appended to or replace the default permissions. Use
a single equal sign (=) to indicate that the permissions
should be appended to the default permissions.
double equal signs (==) to indicate that the permissions
should replace the default permissions.
Note that the java.security.policy system property is
not included in the launchParameters.txt file with the
other system properties because this property is handled by Web Tools
Tomcat server configuration.
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 run-time permissions that are 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 a suitable alternative.
Since system properties can be used within the permissions, the 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.
Typically, SAS Web Application Projects created by the SAS AppDev
Studio Eclipse Plug-ins will contain a java.webapp.policy
file in the root of the project. This is a version of the
catalina.policy file 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.
To deploy these permissions, copy the bottom portion of the
java.webapp.policy, starting with the comment line that contains:
// ========== <project name> Web Application Permissions ==========
where <project name> is the name of the project, and append it to
the end of the catalina.policy file being used by Tomcat.
Provided the appBase attribute on the <Host> element in the
server.xml file is still set to the default value of
"webapps", and you deploy the Web application as a source
directory under Tomcat's webapps
directory, then no changes are required to the codeBase parameters of the
grant blocks that are copied. If deployed differently, then the
codeBase value of these grant blocks should be updated
accordingly.
There are some additional permissions included in the
java.webapp.policy file that are not present in Tomcat
4.1.18's catalina.policy file. These are all preceded with
comments that begin with "NEW:". The purpose of these
additions is explained in the comments. Copy any permissions that are
appropriate to the corresponding global grant
block in Tomcat's catalina.policy file. These added
permissions are also documented in the next section in case the Web
application project does not contain a java.webapp.policy
file.
To enable a security manager, include a java.security.manager
system property on the Java start-up command. If you do 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.
For instructions on re-installing the service, see the
Installing Tomcat 4.1.x section.
If you enable a security manager and your Web application uses JAXP for parsing or XML transformation, you might want 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 can be granted to specific Web applications or
granted more globally. In 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 the rt.jar file. Otherwise, a permission exception
will prevent the transformer from being instantiated.
These permissions are among those mentioned in the prior section as
being present in the java.webapp.policy file that might be
found in SAS Web Application projects. Another of these added
permissions is the following permission, which avoids an unnecessary
exception when compiling JSP pages:
permission java.lang.RuntimePermission "defineClassInPackage.org.apache.jasper.runtime";
The last permission added is:
permission java.lang.RuntimePermission "defineClassInPackage.org.apache.coyote.*";
This permission addresses a Tomcat bug that is described in the known issues for Tomcat 4.1.18 through 4.1.27.
This section addresses the known issues in the Tomcat versions that affect SAS AppDev Studio software. It does not try to cover known bugs in all the various Tomcat versions. For information about Tomcat bugs, refer to the bug database that is available on the Apache Software Foundation Web site.
By default, Tomcat 4.1.x tries to serialize all HTTP session data to a file for each Web application when a Tomcat or an individual Web application is stopped. When Tomcat or the Web application is restarted, if this session file exists, Tomcat will try to deserialize the contents of this file in an attempt to restore the HTTP session data for that Web application. This feature attempts to prevent users from realizing that the Tomcat server or Web application has been restarted.
For certain kinds of Java objects, like connections to SAS servers, this attempt at a transparent restart does not succeed. The issue for connections to SAS servers is that there is "state" that is exists on the Tomcat server and on the SAS server. When the Tomcat server "state" is restored, there is not currently support to restore the SAS server portion of the connection, so the connection no longer functions correctly.
Exceptions will occur when the HTTP session data that includes these
problem objects is restored. Because HTTP session data of some
undetermined state will be the result, it is best to disable this
feature for SAS Web applications. You can accomplish this by adding
following configuration XML to the <Context> element for the
Web application in the server.xml file or other
context file, depending on your deployment strategy.
<Manager className="org.apache.catalina.session.PersistentManager"
debug="0" saveOnRestart="false"
maxActiveSessions="-1" minIdleSwap="-1" maxIdleSwap="-1" maxIdleBackup="-1">
<Store className="org.apache.catalina.session.FileStore" />
</Manager>
The important item is the saveOnRestart attribute. The
remainder of the configuration simply duplicates the defaults you would
get without this context configuration.
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's Bugzilla database as Bug #17523. Since JSP execution has sufficient permission, once a JSP instantiates a session and loads the required class, servlets can create and access sessions normally. Tomcat 4.1.28, and later, you can avoid this problem by loading the required class at server startup.
The work around for this problem in Tomcat 4.1.18 through 4.1.27, is for you to
include the following permission in your Tomcat's catalina.policy file.
It is best to add the permission within a global grant block, so that
it applies to all Web applications.
permission java.lang.RuntimePermission "defineClassInPackage.org.apache.coyote.*";
This is one of the permissions included in the java.webapp.policy
file as described at the end of the Specifying the
JVM Run-Time Permissions section.
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 that 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.