Jump to: navigation, search

Difference between revisions of "WTP Tomcat FAQ"

m (cat)
Line 1: Line 1:
 
==General==
 
==General==
 
===What should I know about this FAQ?===
 
===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.
+
This FAQ includes frequently asked questions and other useful information about the support for Apache Tomcat servers in WTP 1.5.x and WTP 2.0.x. 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 v6.0. Tomcat 6.0 support requires WTP 2.0.x or later. 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.
+
You are encouraged to review the questions and answers in the [[#Getting Started | Getting Started]] section for some important background information.
  
 
==Getting Started==
 
==Getting Started==
 
===When I create a new Tomcat server, what should I know about its default configuration?===
 
===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.
+
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. In WTP 2.0.x, the New Server Runtime wizard makes the same assumption about any Tomcat server it automatically creates in addition to the new Tomcat runtime. WTP is able to avoid affecting the behavior of the installed Tomcat 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 expect 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.
+
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 issue is addressed by the remaining Getting Started questions.
  
 
===How does WTP support separate Tomcat server instances?===
 
===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.
+
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?===
 
===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 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.
+
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?===
 
===What are the advantages and disadvantages of using the server instance from my Tomcat installation?===
Line 28: Line 28:
 
==Information==
 
==Information==
 
===How do I modify the Tomcat server's configuration?===
 
===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 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 pages, ''Overview'' and ''Modules'', which display different portions of the Tomcat configuration. You switch between these pages 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 configuration for a Tomcat server includes a number of WTP specific options and settings, which appear on the ''Overview'' page. In WTP 1.5.x, these are found in the ''Server'' and ''Automatic Publishing'' sections.  In WTP 2.0.x, these are found in the ''Server Locations'', ''Server Options'', and ''Automatic Publishing'' sections. More importantly, the configuration 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 page. 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.
+
The ''Modules'' page displays the contexts that the Tomcat server is configured to serve. These contexts include Dynamic Web Projects that have been added to the server as well as contexts manually added using this page or modifying '''server.xml''' directly.
  
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.
+
Note: As a convenience, the launch configuration Properties dialog for the Tomcat server may be opened from the ''Overview'' page 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?===
 
===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.
+
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 [[#How do I modify the Tomcat server's configuration?|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'' page. 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?===
 
=== 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.
+
In WTP 1.5.x, the ''Run modules directly from the workspace (do not modify the Tomcat installation)'' check box of the [[#How do I modify the Tomcat server's configuration?|server editor]] controls this option. It is found in the ''General'' section of the ''Overview'' page. 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.
 +
 
 +
In WTP 2.0.x, the ''Server Locations'' section has been added to the server editor to provide improved control over this configuration issue. Choosing the ''Use workspace metadata (does not modify Tomcat installation)'' will use a separate instance and is equivalent to enabling WTP 1.5's ''Run modules directly...'' check box. In addition, the ''Server Path'' field displays the location of this separate instance relative to your workspace. A separate instance is also created if you choose ''Use custom location (does not modify Tomcat installation)'' and specify your desired location in the ''Server Path'' field. Choosing ''Use Tomcat installation (takes control of Tomcat installation)'' uses the instance from your Tomcat installation and is equivalent to disabling WTP 1.5's ''Run modules directly...'' check box.
 +
 
 +
Note that changes to the settings in the ''Server Locations'' section can only occur when there are no projects present on the server. All the settings in the section are disabled if this is not the case. Remove all of the projects and publish the server to enable the settings in this section.
  
 
===If my Tomcat server is using a separate instance, how do I find the location of this separate instance?===
 
===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
+
In WTP 2.0.x, the best way to find the instance location, known as CATALINA_BASE in the Tomcat batch scripts, is to [[#How do I modify the Tomcat server's configuration?|open the server editor]]. The instance location is displayed in the ''Server path'' field. Relative paths are relative to your workspace.
 +
 
 +
In WTP 1.5.x, you can find the instance location by [[#How can I view or modify the launch configuration properties for a Tomcat server?|opening the launch configuration Properties dialog]] and selecting the ''Arguments'' tab. Examine the contents of the ''VM Arguments'' field. The value for the '''catalina.base''' system property specifies the absolute path to the instance location.
  
 
===How do I find the location of the conf, logs, temp, webapps, and work directories for my Tomcat server?===
 
===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.
+
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 [[#If my Tomcat server is using a separate instance, how do I find the location of this separate instance?|question]].
  
 
===When I create my first Tomcat server, why is a Servers project created in my workspace?===
 
===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.
+
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. In WTP 2.0.x, '''catalina.properties''' is included as well. 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 [[#If my Tomcat server is using a separate instance, how do I find the location of this separate instance?|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.
+
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?===
 
===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.
+
From the ''Servers'' view, [[#How do I modify the Tomcat server's configuration?|open the server editor]] for the desired Tomcat server. In the ''General'' section of the ''Overview'' page, 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?===
 
===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.
+
''Publish'' updates the [[#How does WTP support separate Tomcat server instances?|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 [[#If my Tomcat server is using a separate instance, how do I find the location of this separate instance?|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 [[#How do I specify the Tomcat context configuration for my Web Application?|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.
+
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.
+
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 '''logging.properties''', they will be available to the running server in its '''conf''' directory. A couple of files you may wish to import are '''catalina.properties''' (if you are using WTP 1.5.x) and '''context.xml''' (if you are using Tomcat 5.5.x or 6.0.x). WTP 2.0.x already includes '''catalina.properties''', and '''context.xml''' will be included by WTP 3.0.
  
 
===Why are <Context> elements added to server.xml when Dynamic Web Projects are added to the Tomcat server?===
 
===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.
+
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.
 +
 
 +
For Tomcat 5.0.x and later, WTP 2.0.x offers the opportunity to write the contexts to separate XML files in the proper folder (typically '''conf/Catalina/localhost''') according to the requirements of that particular version. This behavior is enabled by checking the ''Publish module contexts to separate XML files'' option in the ''Server Options'' section of the [[#How do I modify the Tomcat server's configuration?|Tomcat server editor]]. Note that only contexts for added projects will be written to separate XML files. Manually added contexts in '''server.xml''' will remain there.
  
 
===How do I specify the Tomcat context configuration for my Web Application?===
 
===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.
+
The configuration within <Context> elements may be added to the [[#When I create my first Tomcat server, why is a Servers project created in my workspace?|'''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.
+
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 context for that project when '''server.xml''', or [[#Why are <Context> elements added to server.xml when Dynamic Web Projects are added to the Tomcat server?|separate context XML file]] in WTP 2.0.x, is file copied as part of [[#What does Publish do for Tomcat servers in the Servers view?|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 the "path" and "docBase" attributes.
  
 
===How do I make the Servlet and JSP API Javadoc in my Tomcat installation accessible within Eclipse?===
 
===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.
+
The '''tomcat-docs''' Web application that comes in the standard Tomcat installation for Tomcat 4.0.x through Tomcat 5.5.x 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.
 
# 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 Package Explorer view, expand the Dynamic Web Project and its library folder for the Tomcat runtime.
# Right-click the API JAR (see table that follows) and select Properties.
+
# Right-click the API JAR (see table that follows) and select ''Properties''.
# In the Properties dialog, select Javadoc Location in the tree on the left.
+
# 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.
+
# 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.
 
The JAR name and folder varies depending on the version of Tomcat. The following table gives the various choices.
Line 100: Line 108:
 
   <td>servlet-api.jar</td>
 
   <td>servlet-api.jar</td>
 
   <td>servletapi</td>
 
   <td>servletapi</td>
 +
</tr>
 +
<tr>
 +
  <td>5.x</td>
 +
  <td>JSP</td>
 +
  <td>jsp-api.jar</td>
 +
  <td>jspapi</td>
 
</tr>
 
</tr>
 
</table>
 
</table>
 +
 +
Tomcat 6.0.x currently doesn't make the Servlet and JSP Javadoc available in its binary downloads. However, the source download for Tomcat 6.0.x currently includes source for these APIs. To make use of the source, select ''Java Source Attachment'' instead of ''Javadoc Location'' in the steps above.  Then provide the path to the '''java''' folder of the expanded source which contains the source for these APIs, and others.
  
 
===How do I enable the JULI logging in a Tomcat 5.5 Server instance?===
 
===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.
 
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.
+
# [[#How do I modify the Tomcat server's configuration?|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.
+
# 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 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:
+
# In the ''VM Arguments'' field, add the following two system properties substituting the '''catalina.base''' path where noted:
  
 
       -Djava.util.logging.config.file="<put catalina.base path here>/conf/logging.properties"
 
       -Djava.util.logging.config.file="<put catalina.base path here>/conf/logging.properties"
Line 115: Line 131:
 
      
 
      
  
The imported logging.properties file can be used to control the JULI logging configuration for the Tomcat server.
+
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?===
 
===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?===
Line 122: Line 138:
 
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.
 
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.
+
For changes to projects already added to a Tomcat server, if the changes are only to JSP files or other static content files, 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.
+
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 in WTP 1.5.x. This is also true in WTP 2.0.x if the ''Publish module contexts to separate XML files'' option is unchecked. If checked, the context configuration is written to a separate file which can trigger a context reload and pick up the 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.
 
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.
Line 133: Line 149:
 
The first part is to add the appropriate Tomcat "work" folder to the launch configuration source paths. Follow these steps to make this addition:  
 
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.
+
# 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.
+
# 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.
+
# 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.
+
# 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.
+
# 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>.
+
# 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.
+
# 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.
+
To get a JSP's Java file open in an editor you will need 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.
+
# 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.
+
# 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.
+
# 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.
 
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.
Line 153: Line 169:
 
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.
 
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.
+
This problem has been known to occur in WTP 1.5.x and earlier 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. WTP 2.0.x was updated to also accept the presence of '''[servletapi].jar''' to satisfy the requirement.
  
 
===When I try to create a server, it says that it "Could not load the Tomcat server configuration." What is the problem?===
 
===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.
+
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 [[#When I create my first Tomcat server, why is a Servers project created in my workspace?|''Servers'' project in your workspace]]. These are the "working copies" that will be copied to the '''conf''' directory of the [[#How does WTP support separate Tomcat server instances?|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. WTP 2.0.x was updated to provide an improved error message that better identifies the problem that occurred.
  
 
===What does it mean if WTP says my server "failed to start"?===
 
===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".
+
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.
 
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.
+
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 in WTP 1.5.x and earlier. If so, then [[#How can I view or modify the launch configuration properties for a Tomcat server?|open the launch configuration]] for the Tomcat server and examine the ''Program Arguments'' field on the '''Arguments''' tab. 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.
+
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, [[#How can I view or modify the launch configuration properties for a Tomcat server?|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.
+
One other use case that can cause this behavior is if you have ''Launch in debug mode when workspace contains breakpoints'' enabled in WTP 1.5 and earlier. 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. This use case is fixed in WTP 1.5.1 and later.
  
 
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.
 
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?===
 
===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.
+
The default location of '''shared/lib''' is relative to the Tomcat server's [[#If my Tomcat server is using a separate instance, how do I find the location of this separate instance?|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 in WTP 1.5.x or ''Use Tomcat installation (takes control of Tomcat installation)'' is selected in WTP 2.0.x. For details on this option, see this [[#What configuration option determines whether the Tomcat server uses a separate instance or the instance from the Tomcat installation?|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 using a [[#How does WTP support separate Tomcat server instances?|separate instance]] of Tomcat, you can create a '''shared/lib''' folder at the [[#If my Tomcat server is using a separate instance, how do I find the location of this separate instance|instance location]] and add the JARs there. Alternatively, you can edit the '''catalina.properties''' file found in the subfolder of the Servers project which is [[#How do I determine which folder in the Servers project is associated with a particular Tomcat server?|associated with the Tomcat server]]. For WTP 1.5.x, you will need to manually import that file from your Tomcat installation into that folder first. In WTP 2.0.x, that file is included in those imported when the server is created. Modify the '''shared.loader''' property, which is responsible for configuring the "shared" class loader, 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?===
 
===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.
+
When creating Tomcat servers in WTP, the default is for the Tomcat server to use a [[#How does WTP support separate Tomcat server instances?|separate instance]] from the Tomcat installation for reasons explained in this [[#What are the advantages and disadvantages of using a separate Tomcat server instance?|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 [[#What configuration option determines whether the Tomcat server uses a separate instance or the instance from the Tomcat installation?|question]].
  
 
===Why can't I access the standard Web applications in my Tomcat server?===
 
===Why can't I access the standard Web applications in my Tomcat server?===
See the previous question.
+
See the previous [[#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?|question]].
 +
 
 +
===Why does my context reload after I publish a change that only involves a changed JSP?===
 +
There are a number of changes you can make to a context that are expected to trigger a context reload on a running Tomcat server. Changing a JSP isn't one of these. Thus, an automatic or manual publish operation in WTP won't trigger a reload if only changes to JSPs are involved. If the publish operation carries additional changes, then a reload may be triggered depending on what those changes are.
 +
 
 +
Currently in WTP 1.5.x and 2.0.x, there is one use case where every publish operation will carry an additional change that is guaranteed to trigger a context reload. This use case occurs when the server instance is the Tomcat installation and the published project has a dependency on a separate utility project. The jar that is created from the utility project and placed in the '''WEB-INF/lib''' of the published context is always rebuilt in a publish operation. Thus, in this situation, it's not possible to publish just a changed JSP and the context will always reload.
 +
 
 +
===Why does my Tomcat 6.0 server fail to start after I enable the Invoker servlet?===
 +
The legacy method of using "/servlet/<servlet.class>" to run servlets in a Web application is provided by the Invoker servlet.  While convenient, it also presents a security risk. This is why the Invoker servlet is commented out by default in the ''conf/web.xml'' file.  Tomcat 6.0.x takes this security risk a step further by allowing the Invoker servlet to run only in "privileged" Web applications.
 +
 
 +
If you are learning servlets, it would be a very good idea to avoid this method of executing servlets.  However, if you still want to make this work, you will first need to copy or import the '''context.xml''' file from the '''conf''' directory of your Tomcat 6.0 installation into the subfolder of the Servers project which is [[#How do I determine which folder in the Servers project is associated with a particular Tomcat server?|associated with the Tomcat server]]. Then edit the '''context.xml''' to add a "privileged" attribute to the <Context> element with its value set to "true". Since this modification is to the "default" '''context.xml''' file, this modification will make all contexts privileged. Since making a context privileged has more side effects than just allowing the Invoker servlet to run, this isn't a configuration you should use under normal circumstances. You do have the option of restricting the side effects to a single project by adding the Invoker's servlet declaration and mapping to the '''web.xml''' file in the project and adding the "privileged" attribute to the appropriate context in the '''server.xml''' file.
 +
 
 +
If the need for the Invoker servlet is to support some legacy code that is still using the "/servlet/<servlet.class>" method, it is much safer to add servlet declarations and mappings to the web.xml for the specific servlets you need to execute.  This means adding servlet declarations and mappings similar to the following:
 +
 
 +
    <servlet>
 +
        <servlet-name>MyLegacyServlet</servlet-name>
 +
        <servlet-class>my.legacy.ServletClass</servlet-class>
 +
    </servlet>
 +
    <servlet-mapping>
 +
        <servlet-name>MyLegacyServlet</servlet-name>
 +
        <url-pattern>/servlet/my.legacy.ServletClass>/url-pattern>
 +
    </servlet-mapping>
  
 
[[Category:Eclipse Web Tools Platform Project]]
 
[[Category:Eclipse Web Tools Platform Project]]
 
[[Category:FAQ]]
 
[[Category:FAQ]]

Revision as of 22:46, 26 February 2008

Contents

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 and WTP 2.0.x. 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 v6.0. Tomcat 6.0 support requires WTP 2.0.x or later. 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. In WTP 2.0.x, the New Server Runtime wizard makes the same assumption about any Tomcat server it automatically creates in addition to the new Tomcat runtime. WTP is able to avoid affecting the behavior of the installed Tomcat 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 expect 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 issue 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 pages, Overview and Modules, which display different portions of the Tomcat configuration. You switch between these pages 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, which appear on the Overview page. In WTP 1.5.x, these are found in the Server and Automatic Publishing sections. In WTP 2.0.x, these are found in the Server Locations, Server Options, and Automatic Publishing sections. More importantly, the configuration 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 page. 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 page displays the contexts that the Tomcat server is configured to serve. These contexts include Dynamic Web Projects that have been added to the server as well as contexts manually added using this page or modifying server.xml directly.

Note: As a convenience, the launch configuration Properties dialog for the Tomcat server may be opened from the Overview page 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 page. 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?

In WTP 1.5.x, the Run modules directly from the workspace (do not modify the Tomcat installation) check box of the server editor controls this option. It is found in the General section of the Overview page. 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.

In WTP 2.0.x, the Server Locations section has been added to the server editor to provide improved control over this configuration issue. Choosing the Use workspace metadata (does not modify Tomcat installation) will use a separate instance and is equivalent to enabling WTP 1.5's Run modules directly... check box. In addition, the Server Path field displays the location of this separate instance relative to your workspace. A separate instance is also created if you choose Use custom location (does not modify Tomcat installation) and specify your desired location in the Server Path field. Choosing Use Tomcat installation (takes control of Tomcat installation) uses the instance from your Tomcat installation and is equivalent to disabling WTP 1.5's Run modules directly... check box.

Note that changes to the settings in the Server Locations section can only occur when there are no projects present on the server. All the settings in the section are disabled if this is not the case. Remove all of the projects and publish the server to enable the settings in this section.

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

In WTP 2.0.x, the best way to find the instance location, known as CATALINA_BASE in the Tomcat batch scripts, is to open the server editor. The instance location is displayed in the Server path field. Relative paths are relative to your workspace.

In WTP 1.5.x, you can find the instance location by opening the launch configuration Properties dialog and selecting the Arguments tab. Examine the contents of the VM Arguments field. The value for the catalina.base system property specifies the absolute path to 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. In WTP 2.0.x, catalina.properties is included as well. 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 page, 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 logging.properties, they will be available to the running server in its conf directory. A couple of files you may wish to import are catalina.properties (if you are using WTP 1.5.x) and context.xml (if you are using Tomcat 5.5.x or 6.0.x). WTP 2.0.x already includes catalina.properties, and context.xml will be included by WTP 3.0.

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.

For Tomcat 5.0.x and later, WTP 2.0.x offers the opportunity to write the contexts to separate XML files in the proper folder (typically conf/Catalina/localhost) according to the requirements of that particular version. This behavior is enabled by checking the Publish module contexts to separate XML files option in the Server Options section of the Tomcat server editor. Note that only contexts for added projects will be written to separate XML files. Manually added contexts in server.xml will remain there.

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 context for that project when server.xml, or separate context XML file in WTP 2.0.x, is 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 the "path" and "docBase" attributes.

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 for Tomcat 4.0.x through Tomcat 5.5.x 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.

  1. 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.
  2. In the Package Explorer view, expand the Dynamic Web Project and its library folder for the Tomcat runtime.
  3. Right-click the API JAR (see table that follows) and select Properties.
  4. In the Properties dialog, select Javadoc Location in the tree on the left.
  5. 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
5.x JSP jsp-api.jar jspapi

Tomcat 6.0.x currently doesn't make the Servlet and JSP Javadoc available in its binary downloads. However, the source download for Tomcat 6.0.x currently includes source for these APIs. To make use of the source, select Java Source Attachment instead of Javadoc Location in the steps above. Then provide the path to the java folder of the expanded source which contains the source for these APIs, and others.

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.

  1. Open the server editor for the Tomcat server and note the folder specified by the Configuration path field.
  2. Import the logging.properties file from the conf directory of your Tomcat 5.5 installation into this folder in your workspace.
  3. In the server editor, click on the Open launch configuration link and in the launch configuration Properties dialog, switch to the Arguments tab.
  4. In the VM Arguments field, add the following two system properties substituting the catalina.base path where noted:
     -Djava.util.logging.config.file="<put catalina.base path here>/conf/logging.properties"
     -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
     				

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 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 in WTP 1.5.x. This is also true in WTP 2.0.x if the Publish module contexts to separate XML files option is unchecked. If checked, the context configuration is written to a separate file which can trigger a context reload and pick up the 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:

  1. Open the server editor by right-clicking on the Tomcat server in the Servers view and selecting Open, or double-clicking the server.
  2. Click the Open launch configuration link and select the Arguments tab in the launch configuration dialog that opens.
  3. In the VM Arguments field, find the setting for catalina.base system property. Select and copy its value, not including the enclosing quotes.
  4. Switch to the Source tab in the launch configuration dialog, click the Add... button, and select File System Directory. Then click OK.
  5. In the dialog that opens, paste the copied catalina.base value into the Directory field. Then click the Browse... button.
  6. 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>.
  7. 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 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.

  1. Execute Debug As -> Debug On Server for this JSP.
  2. 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.
  3. 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

Why won't the New Server Runtime dialog recognize my Linux installed version of Tomcat?

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 in WTP 1.5.x and earlier 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. WTP 2.0.x was updated to also accept the presence of [servletapi].jar to satisfy the 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. WTP 2.0.x was updated to provide an improved error message that better identifies the problem that occurred.

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 in WTP 1.5.x and earlier. If so, then open the launch configuration for the Tomcat server and examine the Program Arguments field on the Arguments tab. 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 in WTP 1.5 and earlier. 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. This use case is fixed in WTP 1.5.1 and later.

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 in WTP 1.5.x or Use Tomcat installation (takes control of Tomcat installation) is selected in WTP 2.0.x. 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 can edit the catalina.properties file found in the subfolder of the Servers project which is associated with the Tomcat server. For WTP 1.5.x, you will need to manually import that file from your Tomcat installation into that folder first. In WTP 2.0.x, that file is included in those imported when the server is created. Modify the shared.loader property, which is responsible for configuring the "shared" class loader, 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.

Why can't I access the standard Web applications in my Tomcat server?

See the previous question.

Why does my context reload after I publish a change that only involves a changed JSP?

There are a number of changes you can make to a context that are expected to trigger a context reload on a running Tomcat server. Changing a JSP isn't one of these. Thus, an automatic or manual publish operation in WTP won't trigger a reload if only changes to JSPs are involved. If the publish operation carries additional changes, then a reload may be triggered depending on what those changes are.

Currently in WTP 1.5.x and 2.0.x, there is one use case where every publish operation will carry an additional change that is guaranteed to trigger a context reload. This use case occurs when the server instance is the Tomcat installation and the published project has a dependency on a separate utility project. The jar that is created from the utility project and placed in the WEB-INF/lib of the published context is always rebuilt in a publish operation. Thus, in this situation, it's not possible to publish just a changed JSP and the context will always reload.

Why does my Tomcat 6.0 server fail to start after I enable the Invoker servlet?

The legacy method of using "/servlet/<servlet.class>" to run servlets in a Web application is provided by the Invoker servlet. While convenient, it also presents a security risk. This is why the Invoker servlet is commented out by default in the conf/web.xml file. Tomcat 6.0.x takes this security risk a step further by allowing the Invoker servlet to run only in "privileged" Web applications.

If you are learning servlets, it would be a very good idea to avoid this method of executing servlets. However, if you still want to make this work, you will first need to copy or import the context.xml file from the conf directory of your Tomcat 6.0 installation into the subfolder of the Servers project which is associated with the Tomcat server. Then edit the context.xml to add a "privileged" attribute to the <Context> element with its value set to "true". Since this modification is to the "default" context.xml file, this modification will make all contexts privileged. Since making a context privileged has more side effects than just allowing the Invoker servlet to run, this isn't a configuration you should use under normal circumstances. You do have the option of restricting the side effects to a single project by adding the Invoker's servlet declaration and mapping to the web.xml file in the project and adding the "privileged" attribute to the appropriate context in the server.xml file.

If the need for the Invoker servlet is to support some legacy code that is still using the "/servlet/<servlet.class>" method, it is much safer to add servlet declarations and mappings to the web.xml for the specific servlets you need to execute. This means adding servlet declarations and mappings similar to the following:

   <servlet>
       <servlet-name>MyLegacyServlet</servlet-name>
       <servlet-class>my.legacy.ServletClass</servlet-class>
   </servlet>
   <servlet-mapping>
       <servlet-name>MyLegacyServlet</servlet-name>
       <url-pattern>/servlet/my.legacy.ServletClass>/url-pattern>
   </servlet-mapping>