How to Work with Tomcat in the NetBeans IDE

May

In this tutorial, you will convert Tomcat into a NetBeans project and learn how to run, debug, and profile the Tomcat project in the NetBeans IDE.

Introduction

This tutorial shows how to easily develop large (about a half of million lines of code) industrial-scale projects in the NetBeans IDE. The tutorial uses the Tomcat server as a project example.

The NetBeans Integrated Development Environment (IDE) is a free, open-source Integrated Development Environment for software developers. The NetBeans IDE provides developers with all the tools they need to create professional cross-platform desktop, enterprise, web, and mobile applications.
In this tutorial, you will learn how to convert the popular Tomcat project into a NetBeans project, which helps the user to develop, debug, and profile the Tomcat server within the NetBeans IDE.

For more information about the Netbeans IDE's features and supported technologies, see features.

For more information on how to work with the NetBeans IDE, see the Support and Docs page.

Software needed

Before you begin, you need to install the following software on your computer: NetBeans IDE 6.0.
Since NetBeans 6.0 is under development now, use NetBeans IDE 6.0 Preview (M9) available from NetBeans IDE 6.0 Preview (M9) Download, for the latest working version.
You can also use the NetBeans 5.5.1 release. For more information about using the 5.5.1 version, see Addendum: Using NetBeans 5.5.1. Don't forget to install the NetBeans Profiler 5.5.1 because it is not part of the NetBeans 5.5.1 IDE.

Notations used in this documentation

  • <NETBEANS_HOME> - the NetBeans IDE installation directory
  • <USER_HOME> - the user's home directory. Example: "C:\Documents and Settings\user_home"
  • <tomcat_root> - directory into which Tomcat sources are downloaded

Exercises

Converting Tomcat into a Netbeans Project

Downloading Tomcat Source:

1. Go to and download the .zip file from the Source Code Distributions section.

2. Unzip the .zip file (in our case, the file name is apache-tomcat-6.0.13-src.zip) into the <tomcat_root> directory.

After the Tomcat zip file is extracted under <tomcat_root>, you will see a subdirectory, in this case called apache-tomcat-6.0.13-src. For example, on Windows, extracting the Tomcat zip file in the root of C:\tmp\ creates the following path: C:\tmp\apache-tomcat-6.0.13-src.
On Solaris/Linux, unzipping the Tomcat zip file in the /home/username directory creates the following directories: /home/username/apache-tomcat-6.0.13-src.

Creating Tomcat Netbeans Project:

1. Download the attached nbproject.zip(info) file and unpack it into the <tomcat_root> directory.
Note: if you installed NetBeans 5.5.1, use the nbproject551.zip(info) file instead.

2. In the <tomcat_root> directory, create a new file named build.properties. This file specifies the directory for external libraries (i.e. <tomcat_root>/jars) and, if needed, contains proxy configuration data. This step is required because Tomcat uses libraries that need to be downloaded from external sources.

Your build.properties file should look similar to this:

# ----- Default Base Path for Dependent Packages -----
# Replace this path with the directory path to where the binaries of dependencies
# should be downloaded
base.path=C:/tmp/apache-tomcat-6.0.13-src/jars
# ----- Proxy setup -----
# Uncomment if using a proxy server
proxy.host=my.proxy
proxy.port=8080
useproxy=on

3. Start the NetBeans IDE.

Note: To build Tomcat, the IDE uses JDK 1.5. If you install NetBeans with JDK 1.6, change the IDE configuration to use JDK 1.5. To change the IDE configuration, open the netbeans.conf file in the <NETBEANS_HOME>/etc/ directory, and change the JDK location to point to JDK 1.5:

# Default location of JDK, can be overridden by using --jdkhome <dir>:
netbeans_jdkhome="C:\Program Files\Java\jdk1.5.0_11"

Then, start the IDE.

4. In the IDE, choose Open Project from the main menu, and open the Tomcat project from the <tomcat_root> directory.

Note: Netbeans is showing red X's for Java classes, because you have not yet downloaded the required external libraries. You will do this in the next exercise.

Building the Tomcat Project

1. In the Projects window, right-click the Tomcat 6.0 project node and choose Properties from the pop-up menu. Select the Java Sources ClassPath category on the left and add the <NETBEANS_HOME>/java1/ant/ant.jar file to the classpath.

This step is required because the NetBeans editor does not pull classpath information from the Ant build script. Although the module will build, it will look not good in the editor.

2. Right-click the Tomcat 6.0 project's node and choose Download from the pop-up menu. The IDE downloads necessary libraries, unpacks them, and builds dependencies for Tomcat.

Wait until the download completes and you will see the 'BUILD SUCCESSFUL' message in the Output window as shown in the following figure.

Note: If you get any errors when downloading a file from a particular location, edit the .loc entry for that file in the original <tomcat_root>/tomcat/build.properties.default file. In the following example, the eclipse compiler was not found at the original sunsite location. So, we noted this location as errant and added a new location.

# ----- Eclipse JDT, version 3.2 or later -----
jdt.home=${base.path}/eclipse/plugins
jdt.lib=${jdt.home}
jdt.jar=${jdt.lib}/org.eclipse.jdt.core_3.2.3.v_686_R32x.jar

3. Right-click the Tomcat 6.0 project node, and choose Build from the pop-up menu.

Now you built the Tomcat server source code.

Running Tomcat

To run the Tomcat server, do the following:

1. Create a Tomcat user with the loginname admin and password adminadmin. To do this, modify the tomcat-users.xml file in the <tomcat_root>/output/build/conf directory to look as follows:

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="admin" password="adminadmin" roles="admin,manager"/>
</tomcat-users>

2. In the Projects window, right-click the Tomcat node, and choose Start Tomcat from the pop-up menu.

Wait until you see a message like 'INFO: Server startup in 7019 ms' in the Output window.

In your web browser, type localhost:8080. You will see that Tomcat is running.

Explore what applications are deployed on your Tomcat server by default.

3. To stop running Tomcat, right-click the Tomcat project's node and choose Stop Tomcat from the pop-up menu.

Debugging Tomcat

1. Open the Bootstrap.java class from the org.apache.catalina.startup package, and set a breakpoint at line 387.

2. Right-click the Tomcat project's node and choose Debug Project from the pop-up menu.

The IDE opens the Debugger windows, and runs Tomcat in the debugger until the breakpoint is reached. You can perform Step Into, Step Over, and other debugging activities.
To finish debugging, press the Finish button in the toolbar.

Profiling Tomcat Server using Netbeans Profiler

1. In the Projects window, right-click the Tomcat project's node, and choose Profile Project from the pop-up menu.

2. In the Profile Tomcat 6.0 window, accept the default "CPU > Analyze Performance" option and click the Run button.

The Profiler tab opens in the IDE.

3. On the Profiler tab, click VM Telemetry to view memory (heap) changes and other data. Perform some activities on your running Tomcat, for example, run different web applications from the Tomcat Web Application Manager page, and you will see how the size of memory heap is changing.

4. To finish profiling, press the Stop button under Controls on the Profiler tab. Alternatively, right-click the Tomcat project's node in the Projects window and choose Stop Tomcat from the pop-up menu.


Addendum: Using NetBeans 5.5.1

If you use NetBeans 5.5.1, don't forget to install NetBeans Profiler 5.5.1 separately from the core IDE.

There is the only one difference in the steps for creating Tomcat NetBeans projects in 5.5.1 and 6.0 versions of the IDE. Note that there are different files for 5.5.1 and 6.0 versions in the Exercises|NetbeansedTomcat#Exercises] section. For the 5.5.1 version of the IDE, use nbproject551.zip(info) because 5.5.1 uses the older version of XML schema for project.xml files, and nbproject551.zip contains all the required files.


Summary

In this tutorial, you learned how to start Tomcat development in the NetBeans IDE. You have completed the following exercises:
  • Turn Tomcat into a Netbeans Project.
  • Build and run the Tomcat Project.
  • Debug Tomcat.
  • Profile the Tomcat Server using Netbeans Profiler.

See Also

References:

Attachments

breakpoint.jpg Info on breakpoint.jpg 42691 bytes
build-action.jpg Info on build-action.jpg 26970 bytes
build-excluded-pkg.jpg Info on build-excluded-pkg.jpg 51689 bytes
build_excluded_pkg_sm.PNG Info on build_excluded_pkg_sm.PNG 27243 bytes
debug-action.jpg Info on debug-action.jpg 28263 bytes
download-action.jpg Info on download-action.jpg 26896 bytes
download-complete.jpg Info on download-complete.jpg 39899 bytes
nbproject-props.jpg Info on nbproject-props.jpg 56852 bytes
open-nbproject.jpg Info on open-nbproject.jpg 37795 bytes
pr-property.jpg Info on pr-property.jpg 52507 bytes
pr_property.PNG Info on pr_property.PNG 25341 bytes
profile-action.jpg Info on profile-action.jpg 27807 bytes
profiler-window.jpg Info on profiler-window.jpg 45825 bytes
profiler_window.PNG Info on profiler_window.PNG 31059 bytes
profiling-tomcat1.jpg Info on profiling-tomcat1.jpg 111059 bytes
profiling_tomcat1_sm.PNG Info on profiling_tomcat1_sm.PNG 177333 bytes
start-tomcat-output.jpg Info on start-tomcat-output.jpg 27729 bytes
start-tomcat.jpg Info on start-tomcat.jpg 28479 bytes
stop-debug.jpg Info on stop-debug.jpg 3899 bytes
stop-tomcat.jpg Info on stop-tomcat.jpg 28301 bytes
stop_tomcat.PNG Info on stop_tomcat.PNG 25486 bytes
structure.jpg Info on structure.jpg 34342 bytes
structure1.JPG Info on structure1.JPG 34342 bytes
tomcat-deploy-wa.jpg Info on tomcat-deploy-wa.jpg 108282 bytes
tomcat-nbproject.jpg Info on tomcat-nbproject.jpg 17013 bytes
tomcat-running.jpg Info on tomcat-running.jpg 111351 bytes
tomcat_deploy_wa_sm.PNG Info on tomcat_deploy_wa_sm.PNG 140190 bytes
tomcat_running_sm.PNG Info on tomcat_running_sm.PNG 222050 bytes

NetBeans