Apache Tomcat 3.1 Final Release Servlet and JSP Development with VisualAge for Java (update)

Sheldon Bradley Wosnick
April 2000

Please Note:

Tomcat 3.0 final release has been "reposted" (luckily I had a personal backup that I burned to CD which I submited to the Tomcat management folks :-) and so it is once against available if you want to walk through the original tutorial. For advice on using 3.1 final release, for now, you are urged to first see the original piece on the IBM VisualAge Developer's Domain (VADD) based on 3.0 and then this latest update which uses the 3.1 Final Release.

Introduction

My previously published IBM VisualAge Developer Domain (VADD) article called Apache Tomcat Servlet and JavaServer Pages Development with VisualAge for Java has been positively received by the Java servlet and JSP developer community (and the Java "newbie" communities as well) way beyond my wildest imagination! I knew it was important and something the people wanted, but I had no idea that it was this big. I have personally received and responded to hundreds and hundreds of emails praising the usefulness of VisualAge for Java to debug servlets and JSP, the approach and my methodology. It has definitely hit the right nerve in the development community and gives me a sense of satisfaction and accomplishment that I am making a difference somewhere -- I suppose the innermost goal of most developers these days.

This paper can be found at the following URL on the VisualAge Developer Domain:

http://www7.software.ibm.com/vad.nsf/data/document2389?OpenDocument

To quote Govind Seshadri, a registered Java guru at jGuru.com, on a comment he made about this article:

"IBM's Visual Age for Java IDE provides numerous features to aid in the debugging and incremental development of JSPs ... A really cool feature is that you can enable VisualAge for Java to work with the freely available JSP 1.1 reference implementation  of Tomcat, available from the Apache Group. In fact, you can also use the freely available VisualAge for Java Entry Edition (which is limited to 750 classes -- more than sufficient for getting started) to debug JSPs that run under Tomcat. Read the excellent article published in Visual Age Developer Domain titled "Apache Tomcat Servlet and JavaServer Pages Development with VisualAge for Java" by Sheldon Wosnick for the inside scoop."

One consequence of developing a technique or methodology which in any way involves the Open Source movement, as the Apache Tomcat project, Jakarta, certainly is, is that it becomes obsolete all too quickly with what seems to be a never-ending barrage of  new "releases".

No one questions that this is correct or a good thing since the goal is to produce better and better versions, fix known bugs that keep coming up in the previous release, as well as cram in a lot of new functionality. However, keeping up with a codebase that is changing that quickly is truly daunting, even when we are talking in terms of "Web time". By the time I work though, for myself, for my own development, how to build a driver (that's IBM-speak for a build) it gets changed again. To publish these findings, even in the Web medium takes cycles and is forever stale the day it gets released. As an example, this update uses Tomcat 3.1 Final Release. It changed a fair amount from 3.1 Beta 1 and a LOT from 3.0 Final Release (all for the better I might add). Hey, we can't fault them since they have the right idea in mind.

I am hoping that this "no-frills" Web site can at least fill in the gaps until I get some free cycles (not sure what that is...) to publish this on IBM's VisualAge Developer Domain. This is already an "update to an update" updating 3.1 RC 1 to 3.1 Final Release.
 

Assumptions

Until such time that I can bring together all the pieces in one place, I expect as a minimum that you have read and understood the paper at the URL above and that the only problems you are having is that the 3.1 version of Tomcat you are using (that was available to you to download from the Jakarta project site) is incompatible with the methodology described there. You are familiar, now, with the unique capabilities of VisualAge for Java for server-side Java development and want to learn more about maximizing on its potential for servlet and JSP development.

That is, typically you are one of two types of users. One, who tried the approach based on Tomcat 3.0 Release say by downloading the required software, following my instructions and were off and running/developing/debugging servlets and JSPs. However, when you tried to use Tomcat 3.1x, the approach broke down.

Another user is one who stumbled onto my Tomcat paper but finds that 3.0 Release (which was not available for a while but is back online). When trying my instructions for 3.0 they find nothing looks or works as described and hence cannot do anything productive. But that user is in luck since the Tomcat 3.0 Final Release is once more available on the Tomcat site. They may still want to move to 3.1 for all the right reasons.

This update is meant to fill in just those gaps and will assume much of what is referred to in that paper. In fact, I will be constantly referring back to it so it probably  a good idea to have it in front of you as you read what follows.

The following briefly describes an updated series of steps to take to get Tomcat 3.1 Final Release working inside VisualAge for Java. It is meant as an update to the paper I published at IBM and is meant to "tide over" any really interested users who cannot wait until I formally update that paper (which I plan to do). The steps using Release 3.1 were verified and tested on the following machine and configuration thought be one typical developer setup:
 


This no-fluff site was put up rather quickly and any material in it are not in any way associated with IBM and IBM will not be liable for any damages that result from following any of these steps. Try not to get me into any trouble. This is not an advertisment for IBM. The source code that is provided is provided as is with no warranties of any sort. While the author does work for IBM on the VisualAge for Java development team, and this is an update of a sort to an IBM sanctioned and published paper, the contents of this update and any mistakes or inaccuracies are completely the fault of the author, Sheldon Bradley Wosnick, not IBM. I have no problem with distributing the source as long as the copyright notices are clearly in place and the information and the responsibility of the author are disassociated from IBM.

In addition to Entry Edition, I have tested this methodology (by using it for my own "real" servlet/JSP development work) with VisualAge for Java 3.02 Java 2 Early Adopter's Edition Professional on Windows. I have received several emails from users that the 3.1 RC 1 setup worked great on Linux Entry as well. There are no known dependencies on Java 2 -- JDK 1.1x works fine as well.

In favour of getting this to the Web as fast as I can I may have overlooked some details which I hope will be (politely) pointed out to me. One in particular has been pointed out to me several times and is updated here (problem with resolving the classpath in the .jar files still requires you to unjar to a common directory and put that instead on the StartTomcat and StopTomcat classpaths).  Also, I have taken the liberty of capturing quite large screen caps which may present a problem for laptop/notebook users. I feel that the bigger image is worth the scrolling that might be required.

I sincerely hope this information you find this information useful because (though I am biased of course)  I really do believe in the products, VisualAge for Java, and Tomcat too, which I would hope that I have helped in some manner to make successful. I think the combination is unique in many ways and I has a lot of interesting features tremendously useful for serious server-side Java development.

(That means -- please don't go posting to the IBM newsgroups or bothering our support folks that this stuff "doesn't work as advertised". You are on your own for now, this is a convenience I am providing on my own time away from my "real" job.).
 

Setting up the VisualAge for Java environment with the Tomcat 3.1 Final Release binaries release

Follow these (updated) steps to set up the environment:

1. Download and install VisualAge for Java, Entry Edition, Version 3.0 if you have not already done so. I am presuming a clean workspace exists. If not, make sure to remove any vestiges of previous Tomcat projects.

2. Start VisualAge for Java and create a new project called "Apache Tomcat Test Environment". This is different from my original paper but will be used in all subsequent papers I publish.

3. Download from the Tomcat site the "binary version" of Tomcat 3.1 Final Release at:

http://jakarta.apache.org/builds/tomcat/release/v3.1/bin/

That is, download at a minimum, the source jarkarta-tomcat zip/tar/gz file and unzip to the file system, say to d:\work\jarkarta-tomcat. Even the binary version is packaged with the source code, but no build scripts.

4. Copy the following subdirectories and their contents and files under the root of where you unzipped Tomcat (in the example above under d:\work\jakarta-tomacat\ to:

<IBMVJava>\ide\project_resources\Apache Tomcat Test Environment.
\conf
\doc
\lib
\src
\webapps
License

You need not copy over the \bin subdirectory because the batch files and script files are not used by VisualAge for Java. Actually you don't really even need the \lib directory either since, as you will see in subsequent steps, you will be unjarring the .jar files anyway.

This directory was created when you created  the "Apache Tomcat Test Environment" project in VisualAge for Java. This directory is now the VisualAge for Java-Tomcat server root and should now contain the entire Tomcat run time, identical to the tree under the d:\work\jakarta-tomcat directory where you first unzipped it to.
 

Importing Tomcat 3.1 Final Release binaries to VisualAge for Java

1. Right-click on the "Apache Tomcat Test Environment" project and select Import.

2. Make sure the Directory radio button is selected, and then click the Next button.

3. Import the Servlet API source from <IBMVJava>\ide\project_resources\Apache Tomcat Test Environment\src\javax (but not \org, the Tomcat source which can stay in the file system for debugging) directory and make sure only the .java Checkbox is checked. You could of course import them from the original location you unzipped them to in step 3. It does not matter from where you import them.

4. Click Finish to begin importing the Servlet API source. You should see exactly two (and no more) deprecation warnings in the All Problems page from the javax.servlet.http package but you can safely ignore them. Consult the Servlet API specs for more details.

5. Since the binary release does not include the examples in a directory format, to import the Tomcat example Java code, browse to the examples.war file in the webapps\examples directory to the "Apache Tomcat Test Environment Project" using the import as JAR file SmartGuide and select All files (*.*). Make sure just the .java check box is checked like in step 3. The import will succede because a .war file is really just a .jar file with a different extension.

6. Next you to import my two small launcher classes (or create versions for yourself) so that you can start Tomcat from inside the VisualAge for Java IDE, but reference classes outside on the file system. Since my primary goal still remains to get the no-cost VisualAge for Java Entry user, who has a workspace class limit of 750, up and running with Tomcat, the Reflection APIs are used to minimize the number of classes that must be imported. You could, of course import them if you want and then such a technique would be superfluous. But this method is very effective for keeping the workspace class count down low. Select the links below and chose use your browser's "Save Link/Target As..." to save to a working directory the StartTomcat.java and StopTomcat.java files below.

StartTomcat.java
StopTomcat.java

As noted, by doing so, you will be invoking the Startup and Shutdown classes using the Java Reflection API, to avoid importing major parts of the Tomcat run time into the VisualAge for Java Workspace (which would be counted towards the 750 Workspace class limit in the Entry Edition.)

Import these StartTomcat and StopTomcat.java classes to the "Apache Tomcat Test Environment" project as .java source.

At this point the Apache Tomcat Test Environment project should look like this:


 

Configuring the Tomcat 3.1 Final Release classes

Here are the steps:

1. Create a new subdirectory called \_classes off of the project_resources\Apache Tomcat Test Environment and unjar all five .jar files completely to this \classes sudirectory. These .jar files can be found under the \lib director if you copied over this directory, else in the original working directory that you unzipped the Tomcat binaries. Unjar the following run time classes not worring about overwriting the Manifest.mf which is not used:

ant.jar
jasper.jar
servlet.jar
webserver.jar
xml.jar

(Aside: I personally have found different results with resolving the classpath in the .jar files in the Entry Edition 3.0 and the 3.02 Java 2 Early Adopter's Edition. It seems that Entry may have (I have not confirmed) a bug that necessitates expressing the extra classpath to a directory rather than to the .jar. Since it works for some users but others say it doesn't, best thing -- just to play it safe -- is to create the directory and unzip/unjar the five .jar files there which seems to work for all users. Also, use _classes rather than classes because the latter has special significance to Tomcat -- see Tomcat docs.)

2. Right-click on the StartTomcat class (and then later repeat for the StopTomcat class) and select Properties from the pop-up menu. In the Properties dialog, click on the Class Path tab. Next click the Edit button for the Extra directories path.

Enter (or copy and paste) the following directories to the extra class path for both the StartTomcat and StopTomcat classes extra classpath. Relative paths are acceptable and may be used in Extra class paths:

.\;
.\_classes;
.\conf\;
.\webapps\;
.\webapps\examples\jsp\;
.\webapps\examples\WEB-INF\classes\;
.\webapps\admin\;
.\webapps\admin\WEB-INF\classes\;
.\_classes\javax\servlet\;
 

Note that the tomcat.home and the server root need not point to the same directory, I have done this for convenience.

3. For Tomcat 3.1 you need to specify the tomcat.home by either setting the system TOMCAT_HOME environment variable or setting the tomcat.home into the system properties. In VisualAge for Java you must do the second (setting the system environment externally has no effect) and to do so, to set it to the server root, the current directory, for convenience add:

tomcat.home=.

Again, you should do this for both the StartTomcat and StopTomcat classes.

4. The following step is optional but one I have found personally very useful, especially alongside the powerful VisualAge for Java integrated debugger. It turns out that Tomcat provides a fair degree of flexibility in terms of logging to file or to stdout/stderr as well as flags for verbosity and debug level. In order to set the the debug and verbosity levels higher for many low-level functions and to send that output to the VisualAge for Java console rather than to a log file, you may want to edit the \conf\server.xml file as follows:

<Server>
    <!-- Debug low-level events in XmlMapper startup -->
    <xmlmapper:debug level="1" />

    <!-- This is quite flexible; we can either have a log file per
         module in Tomcat (example: ContextManager) or we can have
         one for Servlets and one for Jasper, or we can just have
  one tomcat.log for both Servlet and Jasper.

  If you omit "path" there, then stderr should be used.

  verbosityLevel values can be:
     FATAL
     ERROR
     WARNING
     INFORMATION
     DEBUG
     -->

    <Logger name="tc_log"
            customOutput="yes" />

    <Logger name="servlet_log"
            customOutput="yes" />

    <Logger name="JASPER_LOG"
            verbosityLevel = "DEBUG" />

    <!-- Add "home" attribute if you want tomcat to be based on a different directory
         "home" is used to create work and to read webapps, but not for libs or CLASSPATH.
         Note that TOMCAT_HOME is where tomcat is installed, while ContextManager home is the
         base directory for contexts, webapps/ and work/
      -->
    <ContextManager debug="1" workDir="work" >
        <!-- ContextInterceptor className="org.apache.tomcat.context.LogEvents" / -->
        <ContextInterceptor className="org.apache.tomcat.context.AutoSetup" />
        <ContextInterceptor className="org.apache.tomcat.context.DefaultCMSetter" />
        <ContextInterceptor className="org.apache.tomcat.context.WorkDirInterceptor" />
        <ContextInterceptor className="org.apache.tomcat.context.WebXmlReader" />
        <ContextInterceptor className="org.apache.tomcat.context.LoadOnStartupInterceptor" />
        <!-- Request processing -->
        <RequestInterceptor className="org.apache.tomcat.request.SimpleMapper" debug="0" />
        <RequestInterceptor className="org.apache.tomcat.request.SessionInterceptor" />
        <RequestInterceptor className="org.apache.tomcat.request.SecurityCheck" />
        <RequestInterceptor className="org.apache.tomcat.request.FixHeaders" />

        <Connector className="org.apache.tomcat.service.SimpleTcpConnector">
            <Parameter name="handler" value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
            <Parameter name="port" value="8080"/>
        </Connector>

        <Connector className="org.apache.tomcat.service.SimpleTcpConnector">
            <Parameter name="handler" value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
            <Parameter name="port" value="8007"/>
        </Connector>

        <!-- example - how to override AutoSetup actions -->
        <Context path="/examples" docBase="webapps/examples" debug="1" reloadable="true" >
        </Context>
        <!-- example - how to override AutoSetup actions -->
        <Context path="" docBase="webapps/ROOT" debug="1" reloadable="true" >
        </Context>

        <Context path="/test" docBase="webapps/test" debug="1" reloadable="true" >
        </Context>

    </ContextManager>
</Server>

You may find that you don't desire or need to see that much output to the console (almost every action is dumped to stderr). If so, set according to your taste by setting the debug level from 1 to 0 or verbosity from DEBUG back to INFORMATION.
 

Debugging and Testing Servlets with Tomcat 3.1 Final Release

All instructions from this point on are the same as they were for 3.0 and you can revisit my first article. The console (stderr/out) output has changed significantly from 3.0 Release. See the Resources section below. When you go to the Tomcat Home page you should see the version as "Version 3.1" (I just have not had the time to update the screen shot below from "Version 3.1 RC 1" :-). That will be an indication to you that you have completely the previous steps correctly.


 

Debugging the Tomcat 3.1 Final Release runtime itself (optional)

One new thing I thought I might share with you that I did not describe in my original article (but alluded to if you were paying attention) is that you can also debug the Tomcat code itself which may be important when unexpected things are happening. Say for example you need to see and step through the code as the server starts up or shuts down in stand-alone mode. To do that in VisualAge for Java, without the requirement to actually import all that source to the workspace, is fairly straightforward. Here's what you need to do and it is followed by an example of debugging the startup sequence:
 

1. Add the <IBMVJava>\ide\project_resources\Apache Tomcat Test Environment\src directory to the debugging source path. This directory and source should have been copied over when you did the initial setup as I described above. To do so, open Window->Options->Coding->Debugging and set the "Source path for dynamically loaded classes" to the fullpath to the root directory where the source lives.

2.  Next, to see this scenario in operation, open the Debugger to the Breakpoints page and set a breakpoint in an external .class (whic is described in my first article in the context of the generated/compiled JSP code) but this time in a JAR file, specifically, in the \lib\webserver.jar file you copied over and the classpath points to and choose the org.apache.tomcat.startup.Tomcat class. Alternatively, point it to wherever this file lives if not copied over or even to the .class file you did create in \_classes (in that case, choose the File in Directory radio button instead).


 

3. Select the Break on method enter radio button and then click the Details button to break on the stopTomcat method (just for example).

4. Now, to demonstrate this, start Tomcat by running the StartTomcat class, browse over to http://localhost:8080 and try executing some samples (either JSPs or servlets will do). Then, run the StopTomcat class to shutdown Tomcat. You should hit the breakpoint you set and br able to fully step through and into the Tomcat runtime itself and use the object inspectors which may be beneficial under certain conditions. Since Tomcat is Open Source, the source code is readily available. The only thing you can't do debugging in this way is to make changes to the source and hotlink them into the running program as you could if the source had been imported to the workspace. The savings is that you don't need to import any source to the workspace, important if you are trying to keep within the 750 class limit on the Entry Edition.


 

Conclusion

I have attempted in this (second) update to fill in the missing pieces for users trying to run Tomcat 3.1 Final Release inside VisualAge for Java as well as how to debug the Tomcat runtime itself. That on top of the unique features of VisualAge for Java in terms of Servlet and JSP development and testing attest to richness of this server-side Java development environment.
 

Resources

Download the Tomcat 3.1 Release from:
http://jakarta.apache.org/builds/tomcat/release/v3.1/

Save the following two launcher classes to your local system as StartTomcat.java and StopTomcat.java
StartTomcat.java
StopTomcat.java
 

References

Sheldon Bradley Wosnick, Apache Tomcat Servlet and JavaServer Pages Development with VisualAge for Java

IBM VisualAge Developer Domain, January 2000



Disclaimer.  Please read this.

The information herein is provided completely "AS-IS" without any warranty or condition of any kind. The Tomcat software is experimental and may have defects or deficiencies which cannot or will not be corrected by IBM. IBM (and Sheldon Bradley Wosnick)  is under no obligation to provide maintenance, support, updates or error corrections for the Tomcat software or for any IBM product to make it operate with the Tomcat software. IBM accepts no liability for any damages you may suffer as a result of the information provided herein or your use of the Tomcat software, including any damages claimed by you based on any third party claims. IBM is under no obligation to provide now or in the future in any IBM product any features, capabilities or compatibility with respect to any version of the Tomcat software or specifications. You are solely responsible for the adequate protection and backup of your data and equipment.



About Sheldon Bradley Wosnick

Sheldon Bradley Wosnick is a software developer on the VisualAge for Java WebSphere Tools team at the IBM Toronto Lab in Toronto, Canada. He architected and implemented the VisualAge for Java and Tomcat technical preview described in this article and previous articles. Sometimes fondly known as the "run-time guy," he was responsible for integrating the WebSphere servlet and JSP run times in the WebSphere Test Environment for VisualAge for Java and writing extensively on this topic in print and on the Web. His special interest is distributed server-side Java, especially as it applies to servlets and JavaServer Pages.

You can reach Sheldon at swosnick@ca.ibm.com.

Please note: I receive a lot of email about Tomcat and cannot easily reply to each and every email. Comments though, are genuinely appreciated and often help to point out mistakes/inaccuracies in logic and methodology.



Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and/or other countries.

Other company, product, and service names may be trademarks or service marks of others.