JSwat cannot find the JPDA

I am excited about jswat.  Our official IDE is JBuilder 6 Professional
edition -- which does not support remote debugging!  This makes it much
more difficult to do J2EE development, duh!  So much for PHBs.

Anyway, I have downloaded and untarred jswat-2.9.tar.gz.  I see
jswat.jar, so the first thing I try is, of course:

     java -jar jswat.jar

The result is:

     JSwat cannot find the JPDA.
     Read the README.html file.

Fair enough, so I take a look at README.html.  The first thing I see is:

     "JSwat requires the Java 2 (TM) platform, version 1.4 or
     higher."

So, since I have a large number of jdks installed, I try:

     /usr/local/j2sdk1.4.1/jre/bin/java -jar jswat.jar

No change.  I get the same error message as before.  Since this is a
developers' tool, I figure the jre may not be the right thing to use, so
I try:

     /usr/local/j2sdk1.4.1/bin/java -jar jswat.jar

Again, no change.  OK, I'll keep reading README.html.  It says something
about:

     java [1] com.bluemarsh.jswat.Main [2]

but certainly the -jar approach is the more modern way to start java
apps, so I keep reading.  Ah ha!  It says:

     java [1] -jar jswat.jar [2]

Well, that's pretty much what I've been trying without success.  So
I look at what [1] and [2] mean:

     "The arguments inside [ ] are optional"

OK, well, they can't be that important, but I take a look at the table
anyway.  No, I should not need -hotspot to get this working, nor should
I need -Djava.source.path since I just want to get the bloody gui up.
Then it mentions:

     load -client MyClass arg1 arg2 attach ahost:1234

Again, those look like things I would need to debug a particular
application, but I don't think they would help me resolve the "JSwat
cannot find the JPDA" error.  So I read about the 'Platform
Particulars'.  MAC OS?  No I'm running Linux, and the info certainly
seems MAC OS specific.  Windows?  It says:

     "If JSwat tells you that the JPDA cannot be found and you are
     certain you followed the instructions above correctly, then
     chances are the JRE is getting in the way. "

What "instructions above?"  You mean about java -jar jswat.jar?  Been
there, done that.  Just to be safe, I rename
/usr/local/j2sdk1.4.1/jre/bin/java to jre_java.  Since I have directly
executed the non-jre version of java, I cannot believe this will make
any difference.  It doesn't.

Ah, the 'Troubleshooting' section.  Nothing about finding JPDA.  It
mentions the classpath.  I /never/ set my CLASSPATH, but just to make
sure, I double check that my CLASSPATH variable is unset and that no
naughty classes are sneaking in.  They're not.

So, what, exactly, is it in the README.html file that is supposed to
help me solve this problem?  I don't see much there that wouldn't be
obvious to an experienced developer.

And I am an experienced developer.  I just happened to have never done
JPDA development before.  The ease of use of most IDE's have left be
blissfully ignorant about the inner workings of JPDA.  So what am
I missing?

Thinks I:  there must be a jpda.jar file (or some such thing) in the jdk
directory that needs to be in the classpath:

     $ cd /usr/local/j2sdk1.4.1
     $ find -type f | grep -i jpda

     ./demo/jpda/examples.jar

What's this?  A demo file?  A quick look inside reveals that there are
most java files in ./demo/jpda/examples.jar.  But there are some html
files in there as well, so they might be worth a look.  The index.html
file states:

     "Your classpath must include the JDI Library code, which is in
     tools.jar in the lib directory."

Progress!  I just need to include tools.jar in the classpath.  No
problem.  This is old news to a J2EE developer who would needs a
compiler to compile JSPs.  Yes!  I /know/ this will work:

     $ /usr/local/j2sdk1.4.1/bin/java -cp
     /usr/local/j2sdk1.4.1/lib/tools.jar -jar jswat.jar

     JSwat cannot find the JPDA.
     Read the README.html file.

Gee.  I think I'm starting to get frustrated now.  The index.html file
(from examples.jar) clearly states:

     "New versions of the J2SE SDK have JPDA included." ... "J2SE
     SDK v1.3 and later"

So, presumably, this should be in tools.jar.  Maybe I should double
check:

     jar tf tools.jar | grep -i jpda

This returns nothing.  That's very odd.  So I manually browse the file
and see that there are classes named:

     com/sun/jdi/event/WatchpointEvent.class
     com/sun/jdi/event/LocatableEvent.class
     com/sun/jdi/event/BreakpointEvent.class

Hmm, jdi -- Java ... Debugger ... Interface.  That must be it!  But what
are these classes doing in com.sun instead of java.jpda or javax.jpda?
And why does it still not work????  Frustration still building.

Next step, download the damn JPDA archive, presumably from
http://java.sun.com/products/jpda. I make my way to
http://java.sun.com/products/jpda/download.html, and it tells me that
JPDA is included in Linux SDKs 1.3 and later.  Screw it, I'll download
the windows version just to check it out.  But it also happens to say:

     "works only with the Classic VM, but not with Java HotSpot VM"

So maybe I need to specify  -classic:

     $ /usr/local/j2sdk1.4.1/bin/java -classic -cp
     /usr/local/j2sdk1.4.1/lib/tools.jar -jar jswat.jar

     Warning: classic VM not supported; client VM will be used
     Warning: classic VM not supported; client VM will be used
     JSwat cannot find the JPDA.
     Read the README.html file.

No luck.  OK, download the stinking Windows JPDA.  Now I have:

     jpda1_0-win.zip

Let's take a look.  Ah ha!  There is a jpda.jar file here!  The missing
treasure!  But, this has classes that look like:

     com/sun/jdi/event/AccessWatchpointEvent.class
     com/sun/jdi/event/BreakpointEvent.class

Looks a lot like what was in tools.jar.  I quickly check to see if there
are any classes that are in jpda.jar that are not in tools.jar:

     $ jar tf jpda.jar |
     while read class;
     do
     jar tf /usr/local/j2sdk1.4.1/lib/tools.jar $class | grep -q
     $class || echo $class not found;
     done

Well, there are a handful of inner classes that exist in jpda.jar but do
not exist in tools.jar and none of the example code was in tools.jar (as
would be expected).  This is not surprising given that JDK 1.4.1 must be
a newer version.  In fact, it is a bit surprising that there are /only/
these files which not in tools.jar:

     com/sun/tools/jdi/ConnectorImpl$Argument.class not found
     com/sun/tools/jdi/ConnectorImpl$BooleanArgument.class not
     found
     com/sun/tools/jdi/ConnectorImpl$IntegerArgument.class not
     found
     com/sun/tools/jdi/ConnectorImpl$StringArgument.class not found

     com/sun/tools/jdi/ConnectorImpl$SelectedArgument.class not
     found
     com/sun/tools/jdi/MethodImpl$SoftLineInfo.class not found

So, it looks like I have the classes that I need in tools.jar.  Then
what the #$%@! is the problem?

Well, out of sheer frustration, I'll try using jpda.jar anyway:

     $ /usr/local/j2sdk1.4.1/bin/java -cp
     /downloads/jpda1_0-win/lib/jpda.jar -jar jswat.jar
     JSwat cannot find the JPDA.
     Read the README.html file.

Maybe there's a FAQ.  Yes, I see that there is a jswat FAQ.  Great!
Let's see:

     "To use JSwat you will need a JDK and the JPDA installed on
     your system. See the README.html file distributed with JSwat
     for the details."

Well, a circular reference here.  That's perfectly useless.  I believe
I have already perused README.html to no avail.

     "You cannot debug using the JPDA with the JIT compiler turned
     on. You can turn off the JIT compiler by passing the
     "-Djava.compiler=NONE" switch to java when starting JSwat
     and/or your application."

Ah!  That's right.  -classic doesn't apply to newer JDKs.  I need to use
-Djava.compiler=NONE.  Lets see:

     $ /usr/local/j2sdk1.4.1/bin/java -Djava.compiler=NONE -cp
     /usr/local/j2sdk1.4.1/lib/tools.jar -jar jswat.jar
     JSwat cannot find the JPDA.
     Read the README.html file.

No luck.  But hey, here's my question!

     4. When I try to start JSwat like so "java -jar jswat.jar", it
     fails. It prints a message "Missing JPDA package."

And the reply:

     Please read the README.html file included with JSwat for the
     instructions on how to start the program.

Once again, totaly useless.  The rest of the FAQ is 'Using Questions'.
Since I haven't gotten it to start, I don't really have any questions on
how to use it.

Well, maybe there's a mailing list.  Yes, I see that bluemarsh.com also
has a mailing list, and it even provides search capabilities.  Great!

OK, let's search on:

     JSwat cannot find the JPDA

Given the very poor state of the initial documentation, I'm sure this is
going to be a popular question (gee, maybe it should even be answered in
the FAQ!).  I press Search and get 21 matches.  Now we're talking.
Let's browse through these.

The first is from November 2000 and appears to be out of date.  So is
the second. And the third...  Finally, here is an interesting tidbit:

     Make sure that if you are running jswat using "java -jar" that

     you put the tools.jar file in the jre\lib\ext directory. The
     -jar option
     has a nasty habit of ignoring the classpath setting.

OK, I can believe that.  So I copy tools.jar to
/usr/local/j2sdk1.4.1/jre/lib/ext:

     $ ls /usr/local/j2sdk1.4.1/jre/lib/ext/t*
     /usr/local/j2sdk1.4.1/jre/lib/ext/tools.jar

     $ /usr/local/j2sdk1.4.1/bin/java -jar jswat.jar

Halleluia! Halleluia! Halleluia! It works!

MAYBE THIS SHOULD HAVE BEEN MENTIONED IN README.html!!!

As an alternative to mucking up your JDK directory (which I really
despise), lets try this.  First, remove tools.jar from the jre/lib/ext
directory to get the JDK directory back into its original state.  Then:

     $ /usr/local/j2sdk1.4.1/bin/java
     -Djava.ext.dirs=/usr/local/j2sdk1.4.1/lib -jar jswat.jar

Gosh, this works too! Halleluia! Halleluia! Halleluia! And I didn't even
have to much up my JDK directory.

Conclusion:  YOUR DOCUMENTATION REALLY SUCKS!

I wonder how many people have given up on jswat because of this single
issue.

FIX YOUR DOCUMENTATION!

Or better yet, output a more meaningful error message.  How about:

     JSwat cannot find the JPDA.  Please try adding
     -Djava.ext.dirs=<jdkhome>/lib to your command line.

Now maybe I'll be able to see if your software is any better than your
documentation.

cc

P.S.  OK, I'm frustrated.  I hope others may find this message helpful.