Instructions for setting up Visual Café to debug

JSPs, JavaBeans, and Servlets

 

1)       Install tomcat:  For this example, I am going to install tomcat to d:\tomcat, and use the default setup with a \webapps\ subdirectory off of there.  My JSPs and associated classes will reside in the \webapps\example directory, specifically, the classes reside in \webapps\example\WEB-INF\classes.  After installing Tomcat, make sure it works, (by starting it, connecting to http://localhost:8080, and then stopping it).

 

2)        Configure Visual Café’s environment:  The easiest way to make sure VCafe includes the appropriate files in it’s CLASSPATH when running/debugging Java programs is to add them to the SC.INI file in the VisualCafe\Bin directory.  Make a backup of this file before editing it, VCafe is fairly picky on exact correctness of the file, and you may wish to restore it if you have problems.  There should already be a line containing CLASSPATH=.;\;%@P%\..\Java\Lib\symclass.zip;etc.  Add to the beginning of this line: the path to the Sun Java tools (part of the JDK), all of the .jar files that are located in the tomcat\lib directory, and “d:\tomcat\src”,  so it looks like this: CLASSPATH=.;d:\tomcat\src;d:\jdk1.2.2\lib\tools.jar;d:\tomcat\lib\ant.jar\; d:\tomcat\lib\jasper.jar\;d:\tomcat\lib\servlet.jar\;d:\tomcat\lib\webserver.jar\; d:\tomcat\lib\xml.jar\; %@P%\..\Java\Lib\symclass.zip;etc (No spaces between each)

 

Note: Make sure all of the pathnames are correct.  If you attempt to start VCafe with an incorrect path in its classpath, it will kindly not load, giving no error message at all, and leaving itself in memory.  Kill the VCafe.EXE process, fix the line in the SC.INI file, and try reloading.  If you cannot get it to load this way, restore the original file, and you can go into VCafe and manually enter all of the files in the Tools | Environment Options… | Internal VM dialog.  Again, make sure to kill all running VCafe.EXE processes before trying to load.

 

3)       Recompile Tomcat in VCafe:  This step is probably not necessary if you do not need to debug the tomcat source. Enter VCafe, and create a new, empty project.  Save As… to the D:\tomcat\src directory.  Choose Insert | Files into Project… from the menu, check the Include Subfolders checkbox, and click on Add All.  Click Ok to exit the dialog.  After a short wait while it parses all of the new files.  Now you can press F7 to Build All of the files in your project.  It should compile fine, with 2 deprecation warning messages.  If you wish to test the tomcat build at this point, you can go into the Project | Options on the menu, set the Project Type to Application, and set the Main Class to org.apache.tomcat.startup.Tomcat.  Finally, set the program arguments to “-home d:\tomcat”.  Then you should be able to launch the project, see the Tomcat messages display in the Messages window, and then be able to connect to localhost in a web browser.

 

If you are having problems getting Tomcat to compile, some of the things I’ve done to try and fix errors are (I think these are now fixed in the above procedure):

        Move D:\Tomcat\src\ after the d:\tomcat\lib\*.jar in the classpath.  To do this, either manually edit the SC.INI file, or the easier way would be to go into VCafe under the Tools | Environment Options | Internal VM and click on D:\Tomcat and then repetitively click on Up until it is above the other .jar files, but still after the “.” entry.

        Try compiling with the output directory set to D:\Tomcat\ first, and then change it to d:\tomcat\src (or possibly add D:\tomcat\src\ to the classpath).

 

To stop Tomcat after it is running, you can use the normal method of just killing it within the debugger, or you can run D:\tomcat\bin\shutdown.bat like you normally would.  The latter might cause a cleaner exit, but I have had no problems so far with just killing it in the debugger.

 

4)       Set up your own project to debug:  Now that tomcat is compiled by VCafe, we can create a project of our own (or use an existing one), and set it up to run through tomcat.  You have to keep the .vep (VCafe Project) files in the D:\tomcat\src directory, so that it uses the newly compiled version of tomcat.  You can keep your .java files wherever you want, but you need to set the Output files directory to the D:\tomcat\webapps\example\WEB-INF\classes directory.  This property is set in the Project | Options… | Directories tab.  Next, you need to direct to project so that it will launch Tomcat. Go into the Project | Options on the menu, set the Project Type to Application, and set the Main Class to org.apache.tomcat.startup.Tomcat. .  Finally, set the program arguments to “-home d:\tomcat”.  Then you should be able to launch the project, see the Tomcat messages display in the Messages window, and then be able to connect to localhost in a web browser.

 

5)       Conclusion. You can now debug applications by setting a break point (even while the server is already running), and then using a web browser to connect to Tomcat and go to a page that uses the class in which the breakpoint is.  It should stop and return you to VCafe, but it often just stops, and you have to manually task switch to VCafe.  To debug a .JSP file, Tomcat must first parse and compile it, and you can load the .java file from the D:\tomcat\work directory and set breakpoints within it, and they should function normally.  The java file generated should be similar to the .jsp source file, at least enough so that you can read through it.  It is important to note that every time the .jsp file is changed, Tomcat generates a new, uniquely named, .java file, so you will need to reload the different file if you change the original .jsp.