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
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.
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.
Other company, product, and
service names may be trademarks or service marks of others.