SAS® AppDev Studio 3.3 Developer's Site

Tomcat Deployment Information for SAS AppDev Studio

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:

Installing Tomcat 4.1.x

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"
    -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.

Administering Tomcat 4.1.x

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).

Deployment Strategies

Deployment Within the appBase Directory

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.

Deployment Using Context XML Files

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.

Deployment by Declaring Contexts Within the server.xml 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.

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.

Serving the WAR File or a Source Directory

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 unpackWARs attribute is set to true and you use the manager "deploy" command to deploy a WAR file that does not contain a META-INF/context.xml file, 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 manager remove command works; however, it does not rewrite the server.xml file with the context removed. The removal does not persist in the server.xml file unless some other command or action causes it to be rewritten.

Updating Tomcat 4.1.x Settings

Specifying the JVM Options and the Start-Up System Properties

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 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 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.

Specifying the JVM Run-Time Permissions

You can augment or replace the default JVM run-time permissions using the 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

Note that the 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 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 system property is not already present (it is not in the default installation), then you will need to re-install the service. Include the 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 "readCredential", "ReadCredential";
    permission "*", "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.

Enabling a Security Manager

To enable a security manager, include a 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 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.home}${/}lib${/}", "read";
  permission "${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 "";

The last permission added is:

  permission java.lang.RuntimePermission "*";

This permission addresses a Tomcat bug that is described in the known issues for Tomcat 4.1.18 through 4.1.27.

Known Issues for Tomcat 4.1.x

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.

Tomcat 4.1.x Session Serialization

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" />

The important item is the saveOnRestart attribute. The remainder of the configuration simply duplicates the defaults you would get without this context configuration.

Tomcat 4.1.18 Through 4.1.27

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 "*";

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.

Tomcat 4.1.29

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.