May

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 file and unpack it into the <tomcat_root> directory.
Note: if you installed NetBeans 5.5.1, use the nbproject551.zip 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 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

• NetbeansedJRuby
• NetbeansedJEdit

References:

• Documentation:
• Got issues:
• FAQ List: NetBeansUserFAQ
• Profiler Docs: profiler-index

Attachments

---