experimentalstuff.com: HotSwap Client Tool

Sun Microsystems Laboratories Experimental Stuff

HotSwap Client Tool

HOW TO USE THE TOOL

The HotSwap Client tool works with Sun's JDK™ 1.4 or later versions. The tool can attach to the running JVM, make some simple inquiries to it, and perform class redefinition (hotswapping) on-the-fly. In order to use this tool, you need to start the target JVM™ with special options (see below). If this is unacceptable for you, consider writing your own code to directly access the low-level HotSwap functionality, which is a part of the JVM Debugging Interface (JVMDI).

Target JVM Invocation

The tool uses the same standard wire protocol (JDWP) that debuggers use to communicate with JVMs (see the details on JPDA Web page). Therefore, to be able to use it, you should start the target JVM with several options that would enable it to listen to a specific port, connect to the tool, and exchange information with it over a socket connection. The command line should look as follows:

java -Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=4000,suspend=n MyMainClass

In brief, these options tell the JVM to activate the internal data structures supporting debugger protocol communication, and start listening to the port 4000 in parallel with your application execution. Naturally, you can choose any port number. The detailed explanation of these and other JPDA-related options can be found in the Connection and Invocation Details section of the JPDA specification.

Note that the above options do not affect the JVM performance if the "client" dynamic compiler is used by the JVM (that is, the compiler used by default, or if you specify the -client option when starting the JVM). In other words, the -Xdebug option does not force the HotSpot VM to turn off the client compiler (as it used to be until JDK 1.4 Beta 3), and the memory overhead due to the internal debugging data structures activated is negligible. Unfortunately, if you use the server compiler (-server option), these options still force the JVM to switch to interpretation-only mode, which may affect performance significantly. Java Software is currently working on enabling server compiler in the debugging mode. Thus, if you use the very latest version of HotSpot, you may check to see if performance really degrades - this problem could have been already fixed by the time you read this!

Tool Description

To run the tool, you need to have the standard tools.jar JDK library on the CLASSPATH. Thus the command line may look as follows:

java -classpath $JDK14HOME/lib/tools.jar:hsclient1.0.jar sunlabs.hsclient.Main

Upon the first invocation of the tool for a given project, you will have to set some options in it that usually remain the same for your project afterwards. They are saved into the configuration file automatically upon tool shutdown. These options are:

Connection settings. This is found in the JVM menu and is necessary for establishing network connection with the target VM. You have to set the same port number that you specified when starting the target JVM (4000 in the above example).
Old/new class path, old/new source path. These options are not mandatory, and you need to set them only if you want to use the Find updated classes and Compare sources features of the tool. They are set through the corresponding items of the File menu. The tool uses these class path values to look up and compare the old and the new versions of the binaries and source code for your application. You therefore have to keep them in separate directories and make sure that "old" classes are those that your application really uses, whereas you make changes only to the "new" classes. The best way to achieve such a state is to copy your current sources and binaries to a separate directory, named, say, deployed every time just before you start your application (you may even include the commands to do that in the script that starts your app). We fully recognize that this is not an ideal solution; however, since the JVM itself does not preserve the .class files or the sources for the classes that it runs, the above method is the only way for you to be able to compare old and new class versions. Once again, you are not enforced to do any of the above -- all you lose is a bit of convenience.

Once all of the above options are set, the most typical sequence of actions that you may perform after starting the tool is as follows:

Connect to the target JVM using the JVM/Connect menu item. If the connection is successfully established, the capabilities of the target VM with respect to class evolution will be reported. In JDK1.4, only the very basic capability level is provided, that enables the JVM to hotswap a class if the only changes in its new version are to method bodies. No other changes, e.g. adding methods or fields, are supported. Note: we are planning to add more capabilities in future releases of JDK. In our private experimental code, adding methods and fields is already supported. These changes may be incorporated into future versions of JDK.
Get the list of classes currently loaded by the VM using the JVM/View Loaded Classes menu item. This shows just "user" classes, i.e. Java core classes (java.* and sun.*) are not shown.
Find which classes have changed using the JVM/Find Changed Classes menu item. This iterates over all the classes that you obtained during step 2, and for each of them finds the old and the new .class file on the file system. Old and new class paths should be set to enable this operation. Classes whose versions appear to be different will be listed in the "Classes to Replace" window. Alternatively, to nominate a class for replacement, you may just double-click on a class name in the "Loaded classes" window, or load a class through File/Load new class menu item.
Compare the source code for the versions by pressing "View old/new source" in the "Classes to Replace" window. This will work if the source paths are set, and present the side-by-side representation of the old and the new sources for the same class, with differences highlighted.
Submit classes to the JVM by pressing the "Submit" button. You will be notified of success or any problems (they are most likely to be due to changes to the class not supported by the target VM, e.g. method deletion).

The work on this tool is not finished. In future we plan to add support for class structure comparing, so that the user of the tool can immediately see if any methods or fields were added/deleted etc. We also welcome your suggestions, code contributions and bug reports. Please send e-mails to Misha Dmitriev.

This page is: http://www.experimentalstuff.com/Technologies/HotSwapTool/hotswaptool.html
Last Modified: Fri, 03 May 2002 19:43:32 GMT
copyright (c) 2000-2009, Sun Microsystems