General

What should I know about this FAQ?

This FAQ includes frequently asked questions and other useful information about the support for Apache Tomcat servers in WTP 1.5.x (WTP 2.0 information will be added later). The answers below assume some familiarity with your Tomcat version and its configuration. The answers are not intended to educate you about Tomcat to any significant degree. Covered is Tomcat v4.0 through v5.5. Tomcat v6.0 is not supported by WTP 1.5.x. Tomcat 3.2 is omitted since it differs significantly from the other Tomcat versions and is not likely to have enough users to make its inclusion worth the effort.

You are encouraged to review the questions and answers in the Getting Started section for some important background information.

Getting Started

When I create a new Tomcat server, what should I know about its default configuration?

When you create a new Tomcat server in Eclipse, the New Server wizard assumes it is not safe to affect the current behavior of the Tomcat installation that this new server will use. This is achieved by using Tomcat's ability to run multiple server instances from a single installation. Thus, the default configuration for each new Tomcat sever you create will be a new server instance of the Tomcat installation associated with the Tomcat runtime selected in the wizard. If you expecte the new Tomcat server in Eclipse to run the same instance that the default batch files in your Tomcat installation run, you will likely be surprised when the Tomcat server in Eclipse doesn't behave as expected.

The Tomcat server configuration can be changed so that it does run the same instance as your Tomcat installation. However, there are advantages and disadvantages to doing this, which should be reviewed before making this configuration change. This is addressed by the remaining Getting Started questions.

How does WTP support separate Tomcat server instances?

Apache Tomcat 4.0 and later operate with paths that are relative to one of two locations. These two locations are known in the Tomcat batch scripts as CATALINA_HOME and CATALINA_BASE. In the Java command that actually runs Tomcat, they appear as catalina.home and catalina.base system properties. The "home" location defines where the binary portion of Tomcat lives. This includes the bin, common, and server directories. The "base" location defines where the configuration and working directories for a Tomcat server instance lives. This includes the conf, logs, shared, webapps, and work directories. Tomcat servers created in WTP will have their "home" location set to the Tomcat installation associated with the Tomcat Runtime selected for the server. The "base" location will default to an internally created directory under the .metadata folder found in your workspace.

What are the advantages and disadvantages of using a separate Tomcat server instance?

The main advantage is that configuration changes you make to your Tomcat server within WTP will have no effect on the behavior of the server configured in your Tomcat installation, assuming that is desired. You can run them simultaneously provided the port numbers used by the servers are modified to avoid conflicts. Also, when using a separate instances, you have the option of creating multiple servers from a single Tomcat installation. If you have web projects or testing that need different server environments, you can create and configure a separate server for each of these environments. This will be less error prone than reconfiguring a single server between the various environments.

The main disadvantage is that the standard web applications that come with Tomcat don't automatically appear. However, they can be added manually, if needed, and save a little start-up time for those web applications that are not needed. Another disadvantage is that your Dynamic Web Projects are not automatically served when you start your Tomcat installation's server instance, assuming that is desired. You have to manually deploy them to the Tomcat installation first. Depending on how your installation's Tomcat server is configured, this could be as simple as exporting the Web project as a War file and writing that file to the server's webapps folder.

What are the advantages and disadvantages of using the server instance from my Tomcat installation?

The main advantage of using the server instance from your Tomcat installation is that you can run the same server outside of Eclipse that you run inside of Eclipse. In addition, the web applications that come standard with Tomcat are present automatically.

The main disadvantage with this configuration is that the Tomcat server in Eclipse, in a sense, owns the Tomcat installation. The files found in the associated subfolder under the Servers project in your workspace become the master versions of these Tomcat configuration files. Each time you start this Tomcat server in Eclipse, those files will overwrite the corresponding files in the Tomcat installation. Any changes made locally to those files in the installation would be lost. This implies there will be problems trying to make permanent changes to the Tomcat server using the Manager or Admin Web applications available for Tomcat.

An additional disadvantage is that any custom options added to the Tomcat server's launch configuration within Eclipse will need to be duplicated in the Tomcat batch scripts if the Tomcat server is to be run outside of Eclipse.

Information

How do I modify the Tomcat server's configuration?

The Tomcat server's configuration can be changed using the server editor. This editor is opened by displaying the context menu for the server in the Servers view and selecting Open. Double-clicking on the server in the Servers view also opens this editor. The editor contains two views, Overview and Modules, which display different portions of the Tomcat configuration. You switch between these views by clicking on their respective tabs at the bottom of the editor.

The configuration for a Tomcat server includes a number of WTP specific options and settings, shown in the Server and Automatic Publishing sections of the Overview view. More importantly, it also includes the set of Tomcat configuration files found in the folder specified by the Configuration Path field shown in the General section of this view. This server editor has the ability to make a limited set of modifications to the server.xml in that folder, such as modifying the server port numbers. Modifications to the other files and other modifications to server.xml will need to be made directly to the file.

The Modules view displays the contexts that the Tomcat server is configured to server. These contexts include Dynamic Web Projects that have been added to the server as well as contexts manually added using this view.

As a convenience, the launch configuration Properties dialog for the Tomcat server may be opened from the Overview view of the server editor by clicking on the Open launch configuration link found in the General section.