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.

How can I view or modify the launch configuration properties for a Tomcat server?

The Java start-up environment for a Tomcat server is displayed in the launch configuration Properties dialog for the server. The most straightforward way to open this dialog is to first open the server editor for the Tomcat server. Once the server editor is open, click the Open launch configuration link found in the General section of the Overview view. This approach has the advantage of creating the launch configuration if it is a new server that has not yet been started for the first time. You can also open the launch configuration Properties dialog by executing Run -> Run... (or Debug...) and select the desired run configuration from those under the Apache Tomcat category.

What configuration option determines whether the Tomcat server uses a separate instance or the instance from the Tomcat installation?

The Run modules directly from the workspace (do not modify the Tomcat installation) checkbox of the server editor controls this option. It is found in the General section of the Overview view. If checked, a separate instance is used. If not checked, the instance from the Tomcat installation is used. The default is checked. It is best to change this option immediately after creating the server, or at least while no projects have been added to the server.

If my Tomcat server is using a separate instance, how do I find the location of this separate instance?

The best way to find the instance location, known as CATALINA_BASE in the Tomcat batch scripts, is to first open the launch configuration Properties dialog. Then select the Arguments tab in this dialog and examine the contents of the VM Arguments field. The value for the catalina.base system property specifies the instance location

How do I find the location of the conf, logs, temp, webapps, and work directories for my Tomcat server?

The conf, logs, temp, webapps, and work directories are all relative to the Tomcat server's instance location, known as CATALINA_BASE to the batch files. To find this location, see the previous question.

When I create my first Tomcat server, why is a Servers project created in my workspace?

The Servers project is created, along with a subfolder associated with the Tomcat server, to hold copies of the server.xml, catalina.policy, tomcat-users.xml, and web.xml files for that Tomcat server. This makes is easier to make modifications to those files. It also allows these files to be "working copies", separate from the copies that are found in the conf directory of the instance location. This avoids the possibility of interfering with a running Tomcat server if modifications are made to the files in the Servers project while the server is running.

This Servers project must remain open for Tomcat servers to function properly. Be aware that use of the Close Unrelated Projects command may unintentionally close the Servers project. Reopen the Servers project if this occurs.

How do I determine which folder in the Servers project is associated with a particular Tomcat server?

From the Servers view, open the server editor for the desired Tomcat server. In the General section of the Overview view, the Configuration path field displays the path to the associated folder in the workspace that contains the Tomcat configuration files. The default name for this folder is the name of the server with "-config" appended.

What does Publish do for Tomcat servers in the Servers view?

Publish updates the server instance with any server configuration changes, changes related to projects added or removed from the server, and content changes in projects already added to the server. This includes copying the server configuration files found under the associated subfolder of the Servers project to the server's instance location. In the case of server.xml, "adjustments" may be made to the file by WTP during the copy. For an example of an "adjustment", see this question.

Note the configuration files under the subfolders in the Servers project are not used directly by running servers. The running server uses copies of these files. This implies that any manual changes made to the copy will be overwritten the next time the server is published.

Also note that all files found in the subfolder of the Servers project will be copied. If you have imported additional files there, such as catalina.properties or logging.properties, they will be available to the running server in its conf directory.

Why are <Context> elements added to server.xml when Dynamic Web Projects are added to the Tomcat server?

Though the approach of declaring contexts by adding <Context> elements to server.xml has been deprecated in current Tomcat versions, it is still the only approach that works across all Tomcat versions. In addition, the handling for these <Context> elements is consistent across all Tomcat versions. The support for individual context XML files is not supported for Tomcat 3.2 and varies between the remaining Tomcat versions.

How do I specify the Tomcat context configuration for my Web Application?

The configuration within <Context> elements may be added to the server.xml file associated with the Tomcat server, after the project has been added to the server. Note that if the project is removed from the server, this configuration will be lost. You can save a copy of the configuration in some file in your project if you want to persist this information.

Another approach is use the support found in Tomcat 4.1 and later for specifying context configuration within a META-INF/context.xml file found in the Web application. If a project containing a META-INF/context.xml file is added to one of these Tomcat servers in WTP, the context configuration found in this file will be included in the server.xml when this file copied as part of publishing the server. When adding the configuration from the META-INF/context.xml file, all child elements of the <Context> are copied as well as its attributes, excluding path and docBase.

How do I make the Servlet and JSP API Javadoc in my Tomcat installation accessible within Eclipse?

The tomcat-docs Web application that comes in the standard Tomcat installation includes Javadoc for the servlet and JSP API classes. It is possible to attach this Javadoc to the appropriate JAR(s) in a Tomcat runtime and receive the benefits supported by Eclipse. Other Javadoc and source you acquire for the Tomcat runtime JARs can also be attached in a similar fashion. Caching of this information means that you only have to specify this once per Tomcat runtime in each workspace you use. You do not have to do it for each project.

If you do not have one already, create a Dynamic Web Project which uses the Tomcat runtime to which you want to attach the Servlet and JSP API Javadoc.

In the Package Explorer view, expand the Dynamic Web Project and its library folder for the Tomcat runtime.

In the Properties dialog, select Javadoc Location in the tree on the left.

With the Javadoc URL option selected, click Browse. Navigate to the appropriate folder (see table that follows) and click OK twice to exit the Properties dialog.

The JAR name and folder varies depending on the version of Tomcat. The following table gives the various choices.

Tomcat Version

API

JAR

tomcat-docs Subfolder

4.x

Servlet & JSP

servlet.jar

servletapi

5.x

Servlet

servlet-api.jar

servletapi

How do I enable the JULI logging in a Tomcat 5.5 Server instance?

Tomcat 5.5 comes with an enhanced implementation of java.util.logging, called JULI, which is configured by default in a standard Tomcat 5.5 installation. This JULI logging configuration is not picked up automatically when creating a new Tomcat 5.5 server in WTP. Some manual steps are necessary to add this configuration to your WTP Tomcat 5.5 server.

Open the server editor for the Tomcat server and note the folder specified by the Configuration path field.

Import the logging.properties file from the conf directory of your Tomcat 5.5 installation into this folder in your workspace.

In the server editor, click on the Open launch configuration link and in the launch configuration Properties dialog, switch to the Arguments tab.

In the VM Arguments field, add the following two system properties substituting the catalina.base path where noted:

The imported logging.properties file can be used to control the JULI logging configuration for the Tomcat server.

Can I add or remove a project from a server, or publish changes for a project already on a server, while that server is running?

If you are adding a project to a Tomcat server, it would be best to stop the server, add the project, then start the server again. The "autoDeploy" feature of Tomcat could automatically serve the Web application when it is published without stopping Tomcat. However, there is a good chance that the Web application will be served before it is completely published, resulting in a context that is incomplete in some fashion. For example, if Tomcat started serving the Web application before the web.xml had been copied, the Web application would be run with just Tomcat's built in web.xml defaults. Thus, it is best to add projects while Tomcat is stopped.

Likewise, when removing a project from a Tomcat server, it would be best to stop the server, remove the project, then start the server again. When using an OS that tends to lock files, such as Windows, stopping the server before removing a project will be necessary to avoid errors stating that certain files, typically JARs, could not be deleted. If this occurs, you will need to manually delete these files to complete the removal. Regardless of the file locking issue, it shouldn't be assumed that Tomcat won't have problems with Web applications being removed in this fashion while it is running.

For changes to projects already added to a Tomcat server, if the changes are only to JSP files or other static content files, there there should be no issues if the server is already running. For other changes, success is not typically guaranteed with the odds varying depending on exactly what changed and the current state of the running Web application.

If you make changes to the context configuration for the Web application, then the Tomcat server will need to be restarted. The context configuration appears in the server.xml for the running server and a restart is the only way to pick up those changes.

For Windows systems, there is an internal feature which may help or hurt with respect to making changes to Utility JAR dependencies of a Dynamic Web Project that is on a running Tomcat server. As mentioned above, JARs in use by a running Tomcat are locked by the Windows operating system and can not be deleted for replacement by a newer version. If the JAR can not be deleted when the publish operation tries to update the JAR, then the publish operation will rewrite the JAR instead. For this rewrite to achieve a useful effect, the Web application will need to be reloaded. If the context for the Web application has reloading enabled, this should occur automatically. If reloading is not enabled, then this rewrite will likely do more harm than good and you should restart Tomcat.

How can I debug with the Java source that Tomcat creates for a JSP?

This is feasible with Tomcat 5.0.x and later. However, you should be aware that if you are serving multiple Web applications, the debugger will not be able to tell in which Web application a break point is occurring. The hope is that the class will be unique across all Web applications and finding the right source file just requires searching all Web applications. In the case of JSP, the servlet class generated for a JSP will be the same in each Web application for JSPs with the same name and location. Thus, if you set a breakpoint in an index.jsp file in one Web application, you effectively set a breakpoint in all index.jsp files at the same location in all other Web applications.

The first part is to add the appropriate Tomcat "work" folder to the launch configuration source paths. Follow these steps to make this addition:

Open the server editor by right-clicking on the Tomcat server in the Servers view and selecting Open, or double-clicking the server.

Click the Open launch configuration link and select the Arguments tab in the launch configuration dialog that opens.

In the VM Arguments field, find the setting for catalina.base system property. Select and copy its value, not including the enclosing quotes.

Switch to the Source tab in the launch configuration dialog, click the Add... button, and select File System Directory. Then click OK.

In the dialog that opens, paste the copied catalina.base value into the Directory field. Then click the Browse... button.

Navigate to the work directory for the web application you are debugging and click OK. It will typically be something like work/Catalina/localhost/<webapp context-root>.

Click OK two more times to exit the launch configuration dialog.

To get a JSP's Java file open in an editor you will need to to set a breakpoint in the JSP. In WTP, breakpoints can be set in a JSP only where there is Java code. If the JSP does not already contain something suitable, you can add a "<% %>" scriptlet to provide a location where you can set a breakpoint. Once the breakpoint is set, the following steps show how to open the Java file for the JSP.

Execute Debug As -> Debug On Server for this JSP.

When the breakpoint is hit, find the thread serving the HTTP request in the Debug view. The top line of the stack under this thread corresponds to the breakpoint in the JSP.

Right-click on the top line of the stack identified in the prior step and select Show Source -> Java. This will open the Java file for the JSP.

You can step through the Java code in this file as well as set additional breakpoints. Breakpoint markers do not appear in the left hand margin of this editor, but they do appear in the Breakpoints view. Note that this editor does not show updates to the JSP. You will have to close the editor and hit a breakpoint again to see newer versions of the Java file.

Trouble Shooting

To support searching for Tomcat runtimes, the contents of each directory being tested is checked for a set of content that uniquely identifies the version of Tomcat. These sets are based on the standard zip or tar.gz installs from Apache. The packaged install for various versions of Linux might not quite match the expected set of files.

This problem has been known to occur with Tomcat packages that install a version of Tomcat 5.0.x. When identifying Tomcat 5.0.x, a servlet-api.jar is expected to be present in the common/lib directory. The installation instead has a link named [servletapi].jar to provide the equivalent jar. To meet the verification requirement, you can create an empty jar file named servlet-api.jar in this directory to work around this requirement.

When I try to create a server, it says that it "Could not load the Tomcat server configuration." What is the problem?

When a Tomcat server is created, server.xml, catalina.policy, tomcat-users.xml, and web.xml are copied from the Tomcat installation to a folder under the Servers project in your workspace. These are the "working copies" that will be copied to the conf directory of the server instance when the server is run. If one of these files is missing or can't be read, then this error will occur. This error is most likely to occur when using a packaged Tomcat installation on Linux, since the user running Eclipse may not have permission to read one or more of these files.

What does it mean if WTP says my server "failed to start"?

WTP will start the Tomcat server and then try open a connection to the server's HTTP port. If the JVM that is running Tomcat terminates early, or the connection can't be established within a certain timeout, an error dialog appears displaying "Server <server's name> failed to start".

In addition to server configuration problems which prevent the server from staring, there are several known use cases which can result in this behavior. If none of these use cases apply, then you should examine the server logs or console output for clues as to why the server did not start.

The first use case that can cause this behavior is if the Enable Tomcat debug mode is, or has been, checked in the Tomcat server configuration. If so, then open the launch configuration for the Tomcat server and examine the Program Arguments field on the Arguments. Ensure that "-debug" is not present, or precedes the "start" argument. If it follows the "start" argument, it will cause the server not to start. If the Enable Tomcat debug mode is unchecked, delete the "-debug" string from the field and click Apply to save the change. Once checked, unchecking this option does not successfully remove the argument from the launch configuration, so it must be deleted manually. Note that in Tomcat 5 and later, there is virtually no benefit to enabling this option.

Another use case that can cause this behavior is using a packaged Tomcat installation on Linux. In a packaged Tomcat installation, the classpath specification normally found in the MANIFEST.MF of Tomcat's bootstrap.jar file may have been removed so that installed versions of one or more JARs might be picked up by the start-up batch scripts. You will need to modify the launch configuration to add the missing JARs before the server can be started. First, open the launch configuration for the Tomcat server. Then select the Classpath tab and add the JARs you find being added in the start-up batch scripts to the User Entries. Also, when using a packaged Tomcat install on Linux, you must ensure that the user running Eclipse has permission to read the JARs in the installation.

One other use case that can cause this behavior is if you have Launch in debug mode when workspace contains breakpoints enabled. This setting is found on the Launching preference page under the Run/Debug category of the Preferences dialog. If this setting is enabled and Tomcat is started with a Run command rather than a Debug command, the error can appear because the server did not start in the expected "run" mode because the mode was overridden by the preference setting.

If the error occurs, but the server starts anyway, then the problem may be that a Web project added to the server slows the start-up time sufficiently to exceed the timeout. In this case, you can adjust the Server timeout delay found on the Server preferences page of the Preferences dialog to lengthen the timeout.

Why are classes in my Tomcat installation's shared/lib not seen by my Web application?

The default location of shared/lib is relative to the Tomcat server's instance location. This means that the shared/lib location is not the one in your Tomcat installation unless the Run modules directly from the workspace (do not modify the Tomcat installation) option is unchecked. For details on this option, see this question.

If using a separate instance of Tomcat, you can create a shared/lib folder at the instance location and add the JARs there. Alternatively, you could import the catalina.properties file from your Tomcat installation into the folder in the Servers project associated with the Tomcat server. Once imported, you can modify the shared.loader property, which is responsible for configuring the "shared" classloader, to meet your requirements.

If I start my Tomcat server and try to display Tomcat's default page, why do I see a directory listing or 404 error page?

When creating Tomcat servers in WTP, the default is for the Tomcat server to use a separate instance from the Tomcat installation for reasons explained in this question. There is no attempt to serve the standard Web applications found in the installation. Instead, a simple "ROOT" Web application, containing just a minimal web.xml file, is provided as the default context. The URL "http://localhost:8080/" tries to display the welcome file at the base of this ROOT context. Since this ROOT context contains no welcome file, the default behavior for Tomcat is to display a directory listing. This is why you will see a directory listing for this URL with Tomcat 4.0, 4.1, and 5.0 servers. Directly listings have been disabled in Tomcat 5.5, so the result is a 404 error page instead. To modify the Tomcat server in WTP to use the same server instance as the installation, see this question.