Remote debugging is the act of debugging a remote application. The term remote generally means the application being debugged is on a separate machine, connected via a network. While this is true, it is also true that the debuggee can reside on the same machine as the debugger. As far as the debugger is concerned, it is still remote debugging whether the application is physically near or far.
Remote debugging can be advantageous over launched debugging for a number of reasons. The debuggee may require a particular environment that is hard to replicate on the debugging machine. In cases involving large applications with long startup times, remote debugging will avoid the typical slowness caused by an attached debugger. Whatever reason you choose, this page provides instruction on remote debugging.
To debug a program that is already running, you must have started that program using the following command line:
% java -Xdebug -Xnoagent -Djava.compiler=NONE \ -Xrunjdwp:transport=dt_socket,server=y,suspend=n <class>
This will start the JPDA debugger back-end and run the given
class. The socket transport will be used and the back-end will act
as the server. This allows JSwat to connect to the debugger
back-end by using the attach
command (or the
like-named menu item in the "VM" menu). The debugger
back-end will print a four-digit number in the command shell where
you invoked java
. This is the socket port number that
JSwat must connect to.
Once you have started JSwat and the debuggee program is running,
you can type "attach <port>
" to attach
to the debugger back-end through the given port number. JSwat
should display "VM attached" when successful.
Typically socket-based debugging means that each time the
debugger is detached, the debuggee will listen on a new port. To
avoid this, add "address=1234
" to the list
of arguments to the -Xrunjdwp
option. The value is a
port number between 1 and 65535. Usually port numbers below 1024
are for privileged use only. Be sure to choose a port number that
is not being used by any other socket-based application.
JSwat supports the shared memory connector, when the system
allows it. This is generally only true for Windows systems. To use
the shared memory connector, start the debuggee using the command
line shown above, but replace the dt_socket
with
dt_shmem
. A shared memory name will be displayed in
the debuggee's console. Use that as the argument to the
attach
command.
To end the remote debugging session, invoke the
close
command. This will close the connection with the
debuggee VM and leave it running. If you invoke the
kill
command instead, this will terminate the debuggee
VM. Alternately, the "VM" menu has two items that perform
the same operations: "Detach from debuggee" and
"Terminate VM".
In addition to connecting to an already running remote VM, JSwat
can listen for connections from new VMs. This is done using the
listen
command. It takes an optional port number to
listen to, or uses a default as generated by the JPDA. While JSwat
is listening for a remote VM to connect, you may launch the remote
debuggee using something like the following:
% java -Xdebug -Xnoagent -Djava.compiler=NONE \ -Xrunjdwp:transport=dt_socket,address=<port> <class>
For the <port>
value, substitute the value
returned from the listen
command. Enter the name of
the class you want to debug in place of the
<class>
argument. Once the remote VM starts up,
JSwat will activate a new debugging session and will be ready for
your input.
Remote debugging through the shared memory transport seems to be less stable than the socket transport. JSwat will hang upon disconnect from the debuggee when using the shared memory transport. The socket transport does not have this problem. This is true not only for JSwat, but for other JPDA-based debuggers as well.
When JSwat and/or the debuggee appear to freeze and become
unresponsive, the solution is simple: kill the debuggee process. On
Unix, this means kill -9
, while on Windows it will be
necessary to "End Process" the java.exe
running the debuggee. Once the debuggee process is terminated,
JSwat will return and indicate that the debuggee has
disconnected.
If you are connected to Jakarta Tomcat, simply invoking the catalina stop command should resolve the frozen connection. Tomcat will terminate normally and JSwat will return from its frozen state.
Check out the thorough documentation available for the JPDA library. These docs come with the JDK documentation for JDK 1.3 and above. Be sure to read up on the JPDA connectors to learn all the options when remotely debugging.