general remarks
***************
the 'Communiqué JSP Debugger' (cqjd) is a remote java/jsp debugger.
it's a native windows application entirely written in c++. 
it's based on jpda 1.0 (java platform debugger architecture),
which is the official debugging support for the java 2 platform.
jpda-support comes with jre 1.3 and can be added to jre 1.2.2.

for more information on jpda see "http://java.sun.com/products/jpda"

the latest version of cqjd can be downloaded at: http://www.day.com/devnet

feature list
************
- remote java debugging: debug ejb's, servlets, etc. in any 
  jpda-compliant vm anywhere on the network
- source-level jsp-debugging (any server, any time)
- browse server-side webapps 
- view server-side jsp/servlet source code
- dynamic and static jsp inclusion support for breakpoints and stepping
  (e.g. <jsp:include page="foo.jsp">, <%@ include file="foo.jsp"%>)
- view jsp inclusion dependencies
- breakpoints / step, in, out & over
- variable inspection
- java source structure viewer
- break in running threads, browse threadgroups & threads
- one single executable, no setup required (debug client)
- absolutely no server-side deployment necessary
- no need to modify servlet/jsp engine configuration
- no file-sharing protocol between debugger and server running jsp engine required
- automatic servlet/jsp engine configuration detection
- syntax coloring for jsp and java source code
- simple and intuitive ms-visual studio like look and feel

comments & bug reports
**********************
your feedback is highly appreciated. please send comments, questions and 
bug reports to mailto:cqjd@day.com

known bugs and limitations
**************************
- currently supported/tested debugee platforms are: 
  	- sun classic vm 1.3.0 on win32 (preferably nt)
  	- sun classic and hotspot vm 1.3.1 on win32 (preferably nt, with certain caveats, see below)
  	- sun hotspot vm 1.4.0 on win32 (preferably nt, with certain caveats, see below)
  	- sun hotspot vm 1.4.1 on win32 (preferably nt)
  	- sun classic vm 1.3.0 on linux
	- sun classic and hotspot vm 1.3.1 on linux
	- sun hotspot vm 1.3.1 on solaris 7 (with certain caveats, see below)
- jsp debugging is currently supported/tested for:
 	- tomcat 3.1 
	- tomcat 3.2.x 
	- tomcat 3.3.x (no autodetection, requires initial manual jsp request)
	- tomcat (i.e. catalina) 4.0.x
	- tomcat (i.e. catalina) 4.1.x (requires compilation of jsp during 
	                                debug session; instable with jre 1.3.1;
	                                use jre 1.4.1)
	- jboss 2.4.3 with embedded tomcat 3.2.3
	- jboss 2.4.3 with embedded tomcat 4.0
	(solaris: only tomcat versions 3.2.3 and 4.0 are currently
         supported; debugging other tomcat versions on solaris 
         may result in 'unexpected signal 11' errors on the server;
         this problem only occurs if you connect to a vm on solaris running tomcat
         which has not yet processed any jsp requests; sending a jsp request
         before connecting with cqjd will avoid this problem)
- jre 1.4.0: make sure you specified the "-Xint" flag in the jvm debug cmd-line 
  options (see below). omitting the "Xint" (e.g. interpreted mode) in a 1.4.0 
  jvm sometime causes strange behavior of the debugee.
- we've heard of users reporting that cqjd was crashing on systems with 
  internet explorer 5.0 (5.00.2314.1003) installed. the problem was solved 
  by upgrading to browser to 5.0 sp1 or later. btw, microsoft recommends
  to install sp1 or later for ie5.0 (security issues).
- when both cqjd and the target vm (e.g. the debugee) are running on the same 
  machine under windows 98, you might experience a significantly slower debug 
  performance. the problem is currently under investigation. running the 
  target vm on a (separate) windows nt (or linux) machine will solve this 
  problem for the time being. 
- if you get a 'Failed to initialize JSP debugger' message after connecting 
  to a vm running a supported jsp engine, try disconnecting and reconnecting 
  again. or try sending a jsp request manually before connecting. 
  this should help in most cases.
- if you get a 'Transport error, error code = -1' message on the target vm 
  console, you have to restart the vm before you can connect with cqjd. 
  you may get this message if cqjd crashes (which luckily doesn't happen very often).
- if you want to debug java code in a remote vm and the debugee terminates 
  with an uncaught InterruptedException after connecting, start cqjd with
  the command-line option "-passive"
- if you observe unusual behavior of the debugee or uncaught exceptions 
  (such as ClassNotFoundException) after connecting with the debugger, 
  try invoking cqjd with the command-line option "-passive" and/or "-no_jsp"


instructions for debugging tomcat 3.1/3.2.X/3.3/4.0/4.1
*******************************************************
- install jre 1.3.1 or 1.4.1 as necessary
- set the environment variable TOMCAT_OPTS (tomcat 3.x) or 
  CATALINA_OPTS (tomcat 4.0) as follows:
  
  SET TOMCAT_OPTS=-Xdebug -Xint -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=9999 

    or

  SET CATALINA_OPTS=-Xdebug -Xint -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=9999 

  (you might want to change the port# from 9999 to something more 
  appropriate...)
  
  IMPORTANT: if you're your using jre 1.3.0 or earlier, add "-classic" add the beginning

- run the tomcat start script (<tomcat_home>\bin\tomcat[.bat,.sh] 
  or <catalina_home>\bin\catalina[.bat,.sh])
- start cqjd, enter the port# (e.g. 9999) and host (e.g. localhost) and 
  select the directories/jar files which contain the java source files 
  (e.g. c:\jdk1.3.1\src.jar). important note: the directory structure
  relative to the base source directories must match the package structures
- after some seconds the webapps tree will popup, open a jsp file, set a 
  breakpoint, send a request (e.g. 'execute' the jsp) and start debugging...
- tomcat 4.1.x only: a jsp page must be compiled at least once during 
  the debug session; check the 'Force Recompile' option in the 'Execute JSP' dialog
  (right-click on the jsp in the webapps tree and choose 'Execute...') when requesting 
  the jsp for the first time.

instructions for java remote debugging
**************************************
- install jre 1.3.1 or 1.4.1 as necessary
- add the following flags to the java command line:
  
  -Xdebug -Xint -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=9999
  
  (you might want to change the port# from 9999 to something more 
  appropriate...)
  
  IMPORTANT: if you're your using jre 1.3.0 or earlier, add "-classic" add the beginning

- start cqjd, enter the port# (e.g. 9999) and host (e.g. localhost) and 
  select the directories/jar files which contain the java source files 
  (e.g. c:\jdk1.3.0\src.jar). important note: the directory structure
  relative to the base source directories must match the package structures
- set a breakpoint in a java source file or break execution, start debugging...