Integrating Tomcat 4 with Intellij IDEA by Tom Maxwell
5/14/2002

There are some really great IDE's to use for Java development, but the one we prefer is Intellij's IDEA (www.intellij.com). Out of the box, IDEA has an elegant, uncluttered interface that makes it easy for developers to focus on their code and not the IDE.

IDEA has the features you expect, such as excellent class browsing capability, syntax highlighting, and code completion in both *.java files and JSPs. IDEA also has some advanced features like refactoring-- once you use it, you'll wonder how you ever lived without it.

This article isn't meant to be a review of IDEA, but rather to show how you can use Apache's Tomcat 4 servlet container with IDEA as a integrated platform for editing servlets and JSPs. You'll be able to run Tomcat from within IDEA, as well as debug your servlets from the IDE.

We've made an effort here to make no assumptions about familiarity with any of the concepts talked about here. These instructions should be helpful for any programmer, whether you be a novice or seasoned veteran.

Obtaining the software

To get started, you'll need both IDEA, and Tomcat 4. As of this writing, the current versions of these are IDEA 2.5.2 and Tomcat 4.0.3. These instructions assume that you already have the JDK installed. The Tomcat installation program requires that a JDK already be installed.

A demo of IDEA can be downloaded here (you can also order a license online):

http://www.intellij.com/idea/download.jsp

Tomcat 4.x can be downloaded here:

http://jakarta.apache.org/site/binindex.html

Installing the software

For our example, we've chosen to install the software packages in the following directories on a PC running Windows 2000 with the Sun JDK 1.3.1_03:

JDK - c:\jdk1.3.1_03
IDEA - c:\idea
Tomcat 4.x - c:\tomcat4

The only environment variable that needs to be in place is the JAVA_HOME environment variable, eg.

JAVA_HOME=C:\jdk1.3.1_03

In general, we've found that installing to paths/directories that have no spaces in the names works best, and we recommend that you install each program to its own folder in the root of your hard drive, similar to our examples above.

When installing IDEA, the default installation options should work well.

When installing Tomcat 4.x, you want to install the examples, as we'll be using those to run example code and to show how to use some of the features of IDEA. You should also install the source code-- you'll see a dialog box as shown below, and you'll want to check the box to install the Tomcat 4.0 Source Code:

Creating the Project

Now that you have the software installed, you are ready to configure IDEA. We'll start by creating a project so that we can edit the Tomcat examples, and run them from within IDEA.

Start Intellij IDEA, then go to the File menu, and choose New Project...

You be presented with the following New Project Wizard:

We'll name the project "Tomcat 4 Examples". The location (where the IDEA settings file is stored) is automatically filled in by IDEA. If you have more than one JDK installed, you'll want to select a specific one for use with the project. We'll use the only one installed on our machine (selected by default), the Sun JDK 1.3.1_03.

You'll want to select the compiler output path - this is where the compiled classes will be saved.

Our Tomcat installation is in C:\Tomcat4. Click the [...] button and browse to the Tomcat4 classes folder.

The full path to the classes folder is:
C:\Tomcat4\webapps\examples\WEB-INF\classes

The completed first page of the New Project Wizard should look something like this:

The second page of the New Project Wizard has us selecting the Project Path. Click the [...] button and browse to the Tomcat4 examples folder. The full path should then be:
C:\Tomcat4\webapps\examples

When you are satisfied with the entry, continue>

On the third page of the New Project Wizard, you'll be entering the Sourcepath. There will be a number of directories that IDEA automatically adds, based on your Project Path. To these, we will add the Tomcat src directory. Click the Add path button and browse to the Tomcat4 src folder. The full path should then be:

C:\Tomcat4\src

The fourth page of the New Project Wizard is for setting up the Classpath. A couple items are entered by IDEA by default (the JDK's rt.jar, and the Output Path), but we'll need to add the Tomcat jar files, so that IDEA will have all it needs to run Tomcat from within IDEA, and features like class browsing and code completion will work while editing servlets and JSPs.

** Tip: you can select multiple *.jar files in a folder and add them all at once by selecting the first *.jar file, then while holding down the shift-key, selecting the last *.jar file, then clicking OK. You can also select multiple individual files by holding down the CTRL-key and selecting individual *.jar files, then clicking OK.

Click the Add path button and add the following jar files:

C:\jdk1.3.1_03\lib\tools.jar

C:\Tomcat4\bin\bootstrap.jar

C:\Tomcat4\common\lib\activation.jar
C:\Tomcat4\common\lib\jdbc2_0-stdext.jar
C:\Tomcat4\common\lib\jndi.jar
C:\Tomcat4\common\lib\jta-spec1_0_1.jar
C:\Tomcat4\common\lib\mail.jar
C:\Tomcat4\common\lib\naming-common.jar
C:\Tomcat4\common\lib\naming-resources.jar
C:\Tomcat4\common\lib\servlet.jar
C:\Tomcat4\common\lib\tools.jar
C:\Tomcat4\common\lib\tyrex-0.9.7.0.jar
C:\Tomcat4\common\lib\xerces.jar

C:\Tomcat4\server\lib\catalina.jar
C:\Tomcat4\server\lib\jakarta-regexp-1.2.jar
C:\Tomcat4\server\lib\servlets-cgi.renametojar
C:\Tomcat4\server\lib\servlets-common.jar
C:\Tomcat4\server\lib\servlets-default.jar
C:\Tomcat4\server\lib\servlets-invoker.jar
C:\Tomcat4\server\lib\servlets-manager.jar
C:\Tomcat4\server\lib\servlets-snoop.jar
C:\Tomcat4\server\lib\servlets-ssi.renametojar
C:\Tomcat4\server\lib\servlets-webdav.jar
C:\Tomcat4\server\lib\tomcat-ajp.jar
C:\Tomcat4\server\lib\tomcat-util.jar
C:\Tomcat4\server\lib\warp.jar

The Classpath should look something like this:

When you are satisfied with the entry, click Finish.

Next, we'll configure IDEA to run Tomcat.

Configuring and Running Tomcat 4

Now we'll set up IDEA to be able to launch Tomcat 4, and have the system output to the IDEA console.

Click the Run menu and select Run.

In the dialog that follows, enter the following values:

Name:

Tomcat 4

Main class:

org.apache.catalina.startup.Bootstrap

VM parameters: (these go all on one line with spaces between - see picture below)

-Djava.endorsed.dirs="C:\Tomcat4\bin;C:\Tomcat4\common\lib"
-Dcatalina.base="C:\Tomcat4"
-Dcatalina.home="C:\Tomcat4"
-Djava.io.tmpdir="C:\Tomcat4\temp"

Program parameters:

start

Working Directory:

C:\Tomcat4

The completed dialog should look like the following:

Click Apply, then test out the setup by clicking Run

The Tomcat output will show in the IDEA console (here, shown in a reduced window):

While Tomcat 4 is running, you should be able to access the examples at:

http://localhost:8080/index.html

Verify that the examples will execute, by running example JSPs like the number guess example:

http://localhost:8080/examples/jsp/num/numguess.jsp

..or servlets, like the Hello World! example:

http://localhost:8080/examples/servlet/HelloWorldExample

You can use the console controls to pause the console output, stop the Tomcat server, and close Run console. Detailed instructions about the console window are available in the IDEA online help.

TIP: Tomcat should not be running *outside* of IDEA before you try to run it from *within* IDEA. If Tomcat is already running, you'll see an error message like the following:

Catalina.start: LifecycleException:  null.open:  java.net.BindException: Address in use: JVM_Bind:8080

Now that we have verified that we can run Tomcat from within IDEA, we can try to run in debug mode, set breakpoints in a servlet, and use the IDE to step through the code.

Running Tomcat 4 in Debug Mode

The first thing to do is open up some code in the editor, so we can set breakpoints and do an example System.out so we can show the output in the console. This isn't meant to be an extensive debugging tutorial, but rather just an illustration of the mechanics of debugging servlets in Tomcat4+IDEA.

If Tomcat 4 is still running, stop the server with the Stop button in the console, and then close the console with the close button. These buttons appear as follows:

Stop button

Close button

We'll be editing some code now, so click "Source" on the tool window bar on the left side of the IDEA IDE.

The Tomcat 4 examples include a requisite Hello World! servlet, so we'll open that up and modify it for our example. The complete path to the file is:

C:\Tomcat4\webapps\examples\WEB-INF\classes\HelloWorldExample

Double-click the class name HelloWorldExample to open the file in the editor. You may need to click the Source tab on the left side to reveal the source code, and again to hide the source code once you have opened up the HelloWorldExample code.

You should now have the code open in the editor, as follows:

First off, we'll add a System.out output line, to show how to send output to the console when the servlet executes.

Scroll about halfway down the code to the line right after the BODY html tag is output (approximately line 37 in the code). Hit a couple returns to make some space, and add the lines:

//write some text output to the console
System.out.println("Hello Console!");

You should end up with something like the following:

Compile the servlet:

If all goes well, you should see that your servlet compiled successfully in the status bar at the bottom of the IDEA window:

Click the Run menu and select Run. Then click the Run button to start the Tomcat server:

Now, when you run the HelloWorldExample servlet in your web browser, you should see "Hello Console!" appear in the IDEA console.

http://localhost:8080/examples/servlet/HelloWorldExample

Now we'll try add a little more example code, and try setting a breakpoint in the servlet, then run Tomcat in debug mode and step through the code.

Go ahead and stop the Tomcat server if Tomcat 4 is still running. Again, use the Stop button in the console, and then close the console with the close button. These buttons appear as follows:

Stop button

Close button

Scroll down the code to just below the System.out line that we'd entered before. Add the following lines:

//some code to illustrate debugging 
        String newString = ""; 
        String skyColor = "blue"; 
 
        if (skyColor.equals("blue")) 
            newString = "it's a nice day"; 
 
        System.out.println("The sky is " + 
                skyColor + 
                ", so " + 
                newString); 

Your code should look like this in IDEA:

Now that we have a little code added, we'll set breakpoints. The purpose of breakpoints is to allow you to see what is going on with your program flow and the values of your variables while the program is running. You set a breakpoint by clicking on the left side of the code window with your mouse on the line of code where you'd like the program to stop execution, allowing you to examine the program while it runs.

Set a breakpoint on the line that says:

String newString = "";

The line should appear like follows:

Before we run our code in debug mode, we want to make sure that the compiler is compiling the code with debugging info.  This is something that for performance reasons, you would not do if you were compiling the code for use on a production system. However while code is in development, generating the debugging info is helpful. When you are satisfied with your code, you merely recompile without the debugging info before you deploy the code to the production environment.

From the File... menu, select the Project Properties:

You'll see the Project Properties dialog box. Click Compiler on the left side of the window to view the Compiler info. Make certain that Javac is the active compiler, and that Generate Debugging info is checked, then click OK.

Now we can again compile the code, knowing that debugging info will be available:

If all goes well, you should see that your servlet compiled successfully in the status bar at the bottom of the IDEA window:

Now we can run Tomcat in debug mode, and step through the code.

Click the Run menu and select Debug.

Click the Debug button to start Tomcat in debug mode:

Now, run the servelet once again in your browser:

http://localhost:8080/examples/servlet/HelloWorldExample

When you initially run the servlet, your IDEA window should look like the following:

The code execution has paused on the line where you set your breakpoint. The console window shows the Frame tab by default, which allows you to view the details of any selected stack frame. The IDEA help file has complete details about the frame tab.

For now, we'll try stepping through the code and looking at the console output. Click the Console tab. You should see:

You can see that the line we added before that writes "Hello Console!" to the console has executed, as it is just prior to our breakpoint. You may also notice that the browser continues to try to load the page while the code execution has stopped.

The buttons on the left side of the console can be used to step through the code. For this example, we are only concerned with the Step Over button:

Clicking this button steps to the next line in the file. When you click it, the next line in the code is executed, and then code execution is paused. Click the Step Over button once, and you should see the following:

The line in blue is the current line, and the previous line with the breakpoint has now been executed.

The frame tab now shows a new variable:

Go back to the Console tab, and click the Step Over button until the line in blue is the line that reads:

System.out.println("The sky is " +

Now, hold your cursor over variables in the editor window - you can see that the current value of each variable will be displayed in a tooltip as you hold your cursor over the variable. For example, the String newString equals "it's a nice day" as shown below.

Continue clicking the Step Over button until the remaining code executes, or click the Resume Program button to resume program execution until the next breakpoint (if any).

Resume Program

The Console output should now look like the following:

You may notice that the servlet has completed execution in your browser.

You should be able to now use these instructions to help you set up IDEA and Tomcat 4 for your own servlets and JSP projects. These two tools combined provide an excellent platform for servlets and JSP development. Once configured, the integration is seamless and allows for rapid development of servlets and JSPs from within IDEA.

About the author:
Tom Maxwell is a software developer with Phasesoft Corporation, specializing in Java and J2EE web development.