Debugging Droplets on the Windows Platform
 


The Droplets SDK features full support for debugging of your Droplets applications using any third-party remote debugger.

Remote debugging environments have become the industry standard for debugging server-side software, and are widely available. A remote debugger connects you to a remote machine, allowing you to debug a process that is running on that machine.

For those who have not yet worked with remote debuggers, this does not mean that you need two separate machines in order to debug a Droplets application; in fact, you will typically want to debug on the same machine you've used to develop. You simply need to use a debugger that has the capability to connect to a process that is already running. All you need to to accomplish this is specify "localhost" on your remote debugger as the machine that is running the process to debug.

If you have no previous experience working with remote debuggers, java.sun.com's jdb is a mature, full-featured Java debugger that comes with the JDK 1.3 on the Solaris and Windows platforms. The instructions below are for this jdb debugger, but will give you a good idea of how to debug your Droplets regardless of which remote debugger you use. For more information on how to use jdb, see java.sun.com's jdb tutorial.

Important Note: The debugging method described below is not limited to jdb or any other particular debugger. This technique works with any standard Java remote debugging tool, like JDB, Forte, and many others.


1. Environment variables

Before beginning, you should make sure that your environment variables have set properly for use with jdb. Assuming that C:\jdk1.3 is the location of your JDK, ensure the following:

  • C:\jdk1.3\bin\jdwp.dll must be in your PATH
  • C:\jdk1.3\lib\tools.jar must be in your CLASSPATH

If both of these tasks have been accomplished, typing the following on the command-line should give you the version number of your jdb debugger:

jdb -version


2. Compile your Droplet

You should next ensure that your Droplets application to be debugged has been compiled using the -g option of javac, as in:

javac -g MyClass

This will allow you to print local variables while debugging.


3. Configure your Droplets Server

You will next need to configure your Droplets UI Server to load the JVM for debugging. This is done by changing a registry setting. Under HKEY_LOCAL_MACHINE/SOFTWARE/Droplet/Droplet Server/Java, there is a key called jvm-options that you will need to edit (or add, if it is not present) as follows:

-Xdebug -Xrunjdwp:transport=dt_shmem,server=y,suspend=y,address=5150 -Xnoagent -Djava.compiler=NONE

  • -Xdebug enables debugging support in the JVM.

  • -Xrunjdwp loads in-process debugging libraries and specifies the kind of connection to be made. In this case, we are using shared memory to connect between the debugger and the Droplets JVM.

  • suspend=y indicates that the process should suspend before loading the JVM. If you don't care about debugging the loading of Java Droplets (ie. the App Factories), you can specify suspend=n.

  • 5150 is the port address that jdb should use when connecting with the Droplets VM. You can substitute any port address as long as you specify the same address when you later start jdb.

  • -Xnoagent indicates that the JVM is to use the JPDA debugging agent.

  • -Djava.compiler=NONE disables the JIT compiler, as required for debugging.


You can also use sockets for connecting to the Droplets VM. To do this, you will need to specify the following JVM options:

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y -Xnoagent -Djava.compiler=NONE


4. Start the Droplets Server

Now, start the Droplets Server console (DropletConsole.exe). If you have suspend=y specified in the Droplets Server jvm-options registry key, it should pause after it prints out "Loaded Droplets:". Otherwise, it will continue to load all known Droplets applications.

If you have configured the Droplets Server to use the shared memory transport, it should also print out:

Listening for transport dt_shmem at address: javadebug
Make a note of the address it prints out. You'll need it for the next step.


5. Start the Remote Debugger (jdb)

Now comes the payoff: starting jdb. Open another command-line prompt. If you specified the sockets transport in the Droplets Server jvm-options, start jdb using the following command-line options:

jdb -connect com.sun.jdi.SocketAttach:hostname=localhost,port=5150

The port (5150 in this case) should correspond to the port address you specified in the jvm-options registry setting.

If you specified that the shared memory transport should be used for communication, you should instead start jdb as follows:

jdb -attach javadebug

Where javadebug is the address printed out by the Droplets Server Console when it started.

 

Now that You've Started jdb...

jdb should be started in the main thread successfully. You can now specify jdb commands to set breakpoints, etc. To set breakpoints, make sure you specify the fully-qualified path of a class and method:

stop in com.droplets.examples.hello.HelloWindow.addAllComponents

Which sets a breakpoint in the first line of the method addAllComponents in the HelloWindow class in package com.droplets.exmaples.hello.HelloWindow.

If suspend is on, you should enter the run command to let the Droplets Server continue loading the Droplets JVM. Type help to see all the commands you can use in jdb.

If you want jdb to list source text as you are debugging, you can specify the "use" command to specify paths where the debugger should look for source files.

 

Return to Droplets SDK Documentation Home