JavaSpy version 1.0

User's Guide

Contents

  1. Introduction
  2. Installing JavaSpy
  3. Running JavaSpy

1. Introduction

Welcome to the JavaSpy User's Guide. This guide explains how to install and use the JavaSpy debugging tool. 

About JavaSpy

JavaSpy is a Java utility designed to assist in development and debugging of Java graphical user interface (GUI) applications and applets. It provides a graphical view of user interface components (such as frames, panels, buttons, etc.) and events at run time. 

JavaSpy allows a programmer:

JavaSpy runs in the same virtual machine (VM) as the program under debugging (debuggee). It may be launched from a command line as well as from an integrated debugger. Using JavaSpy simultaneously with a conventional debugger gives the developer  maximum power for debugging and troubleshooting of Java GUI problems.  

JavaSpy uses features of Sun JDK 1.1 and higher to intercept flow of events in the Java event queue.  See Supported platforms for more details.

Supported platforms

JavaSpy was developed to support JDK 1.1 and 1.2 and higher. 

Under JDK 1.2 and 1.3 JavaSpy uses a documented API to install a global event listener. JavaSpy should be able to run on third party Java implementations, which fully support Sun JDK 1.2 specification.

To support JDK 1.1 JavaSpy uses a specific feature of Sun implementation of the JDK, which allows to replace the system event queue of the VM. To replace the system event queue the following line is added to awt.properties file located in JDK\LIB directory: AWT.EventQueueClass=com.javaspy.JavaSpyQueueMonitor11. This feature is also used in Sun's Java Accessibility Utilities and explained in Java Accessibility Utilities

JavaSpy also supports Microsoft VM v 5.0 by using an undocumented API, which may be not supported in the future.

JavaSpy requires an access to the system event queue and local file system. In order to debug an applet it is necessary to configure an applet viewer to provide full security permissions. This feature was tested with applet viewer from JDK 1.2 and Microsoft Internet Explorer 5.0.

JavaSpy was tested on the following platforms:

2. Installation

JavaSpy is distributed in a single Jar file javaspy.jar. It may be called javasp10.zip because of requirements on some Web sites (where 10 is the version number and may change). In such a case it is better to rename javasp10.zip to javaspy.jar, but it is possible to run setup directly from javasp10.zip. This file contains Java classes, a manual, a readme and a license texts. This package does not contain any platform specific code. In order to install and use JavaSpy it is necessary to have a Java virtual machine installed.

Using automated installation

The javaspy.jar includes "com.javaspy.Setup" class for automated installation.  To execute it you need to launch Java interpreter with the javaspy.jar on a class path and com.javaspy.Setup as a parameter. For example,

java -classpath javaspy.jar  com.javaspy.Setup

If you using a zip application, such as WinZip under Windows, you may open javasp10.zip (or javaspy.jar) in that application and then execute setup.bat, which will execute the same command line as shown above. 

After start the Setup asks the User to select the installation directory. Then it copies the javaspy.jar to that directory and extracts some files, such as the manual. The Setup does not attempt to modify the "CLASSPATH" environment variable, because this is platform-specific operation. See Running JavaSpy for more information about using the JavaSpy.

Before terminating the Setup give the User a choice to run a Demo. If the User confirms, the Setup launches a new instance of Java VM with the JavaSpy and Demo classes. The Demo is a  simple application, which displays a Frame and several AWT controls. If the installation was successful, the User should be able to start exploring features of  JavaSpy, including hierarchical view of UI components, their properties and events.

Manual installation

The User may need to install JavaSpy manually because of specifics of the Java platform and development environment in use. Some Java platforms store "CLASSPATH" variables in a file, others - in a system registry. Some Users may prefer to specify the classpath on the command line of Java interpreter. Many integrated development environments (IDE) allow the programmer to specify and store the classpath in a project file. It should be possible to run JavaSpy in most circumstances as long as javaspy.jar is on the classpath and class com.javaspy.JavaSpy is instantiated immediately after the debuggee starts. To work on JDK 1.1 it is necessary to add the line "AWT.EventQueueClass=com.javaspy.JavaSpyQueueMonitor11" to awt.properties.

Manual installation steps:

1. Copy javaspy.jar to a desired directory.

2. Extract the manual (this document), all .gif files and the license agreement:

jar xvf javaspy.jar Manual.htm license.txt readme.txt

jar xvf javaspy.jar EventsScreenScr.gif JavaSpyAndDemoDragScr.gif JavaSpyInitAndDemoScr.gif

jar xvf javaspy.jar JavaSpyPropConfig.txt

jar xvf javaspy.jar Run.bat Setup.bat RunAppletViewer.bat SecurityPolicy.txt TestApplet.html

Read the license agreement.

3. If you using JDK 1.2 or higher or Microsoft VM, go to (4). If you using JDK 1.1, find the file awt.properties in the LIB subdirectory of the JDK (where classes.zip is located). Search the file for the keyword "AWT.EventQueueClass". If it is found, may be some other application already replaces the global event queue. Try to comment out this key by placing "#" character in front of it. In any case add the following line to the file: AWT.EventQueueClass=com.javaspy.JavaSpyQueueMonitor11

If awt.properties file cannot be found, it may be because you using a non-standard JDK. JavaSpy does not support non-standard JDKs except for Microsoft VM. There is no file modifications necessary for the Microsoft VM.

4. Run the Demo by using the following command line. Specify full paths for java.exe and javaspy.jar if necessary. Replace java.exe by jre.exe or jview.exe and "-classpath" by "-cp" depending on your environment.

java.exe -classpath javaspy.jar com.javaspy.JavaSpy com.javaspy.Demo DemoParam1 DemoParam2

This command line invokes the Java interpreter with javaspy.jar on the classpath and com.javaspy.JavaSpy as the main executable class. The Demo class and it's parameters are specified as arguments for the JavaSpy class. The JavaSpy class instantiates the Demo class and the UI starts. If everything working correctly, two frame appears. One of them is the Demo GUI and another is the JavaSpy window.

5. Try to run your own programs by using the same command line as the Demo, but specifying your own class name and parameters as the arguments for the JavaSpy.

6. If you want to run JavaSpy and your program from an IDE debugger, you will need to modify the IDE project configuration. Some IDE, for example Visual J++, provide a single text box for the command line including classpath, class name and parameters. In such a case, insert the path to javaspy.jar to the classpath string and com.javaspy.JavaSpy in front of your own main class. Other IDE, such as Symantec Visual Cafe, provides separate text boxes for the classpath, start class and parameters. In that case, add the path to javaspy.jar to the classpath box, move your own main class from the "start class" box to the front of the  "parameters" box and type com.javaspy.JavaSpy in the "start box". 

While running JavaSpy from IDE it may be convenient to quickly enable or disable the JavaSpy without making too many modifications in the project configuration dialog. For that purpose JavaSpyX class was created. When you don't want JavaSpy to start, simply put 'X' at the end of com.javaspy.JavaSpy in the appropriate box in the project configuration dialog. JavaSpyX will launch your application exactly as JavaSpy does, but it will not launch the spy itself.

Uninstall

Except for JDK 1.1, JavaSpy does not modify anything in the environment. Therefore, to uninstall it, simply delete the jar file, manual and other text files.

Under JDK 1.1 it is necessary to remove the AWT.EventQueueClass=com.javaspy.JavaSpyQueueMonitor11 line from awt.properties and restore the original value of AWT.EventQueueClass= (if any).

To assist in this procedure you may run the class Uninstall:

java.exe -classpath javaspy.jar javaspy.Uninstall 

3. Running JavaSpy

After the installation is successfully completed, you should be able to run the Demo class and your own applications. In the simple case run the following line:

java.exe -classpath javaspy.jar com.javaspy.JavaSpy com.javaspy.Demo DemoParam1 DemoParam2

Specify full paths for java.exe and javaspy.jar if necessary. Replace java.exe by jre.exe or jview.exe and "-classpath" by "-cp" depending on your environment. Replace com.javaspy.Demo and parameters by the name of your class and arguments. See Manual installation for more details.

When the JavaSpy successfully starts, it presents a small window. The window is displayed in the reduced size to reduce display clutter. In a separate window the Demo program displays the simple GUI:

This Demo has an intentional defect. It created "OK" button, but it failed to appear on the screen. This can be caused by a variety of reasons: 0 size, position is outside of visible area or simply setVisible(false) was called. The Demo displays a list of steps that can be taken in order to explore JavaSpy and Demo, find the missing OK button and make it visible at run time, without recompiling the program (to confirm the reason of the bug).

To start exploring the Demo GUI, click on the "Init Spy" button. The JavaSpy window should expand and a hierarchical view of GUI components should appear on the left. This hierarchy has two roots correspondent to two frame windows: JavaSpy and Demo. You may select UI components in the tree view or press the "Find by mouse" button and move the mouse to any place in one of these two frames (don't keep the  mouse button down). If a mouse is positioned over a Java component, which was recorded by the JavaSpy, then properties of this component will appear in the properties pane (on the right from the component tree). To finish the "Find by mouse" process, click any key.  To highlight the component in the tree, click on the "Locate in Tree" button. The following picture shows the view after the User moved the mouse to the list box in the Demo window and then clicked "Locate in Tree" button. The blue arc is the trajectory of the mouse movement. The red arrow points to the missing OK button. To make it visible, please follow steps explained in the Demo window.

The final exercise is to watch an event flow in this demo. Click on the "Events" button to display the Events pane. Enable tracing of some events by checking some checkboxes. After that perform various actions in the Demo UI or in the JavaSpy itself. The Demo is not designed to generate all kind of events. Since it is a simple AWT application, you will be able to see only AWT events. The following picture shows several ItemEvent and ActionEvent generated after clicking and double-clicking on the list box in the Demo. One of events was selected in the list and it's properties are displayed in the Properties pane.

The Properties panel (which is located in the upper-right part of the JavaSpy window) displays the most useful information about the currently selected component (either selected in the tree or by using Finder Tool). The program uses JavaSpyPropConfig.txt file to determine which methods and fields to evaluate for a particular class. This file has a simple format, which is explained inside the file. Users may modify this file to display information, which is most useful for them.

Here are few examples:

java.awt.Button->getLabel()  - displays a label for a button (or derived) class

java.util.EventObject->getSource() - displays a source of an event

java.awt.Component->setVisible(false) - this is not a serious setting. It will simply hide all components under a mouse (if the Finder Tool is used)

Debugging applets

JavaSpy requires an access to the system event queue and local file system. In order to debug an applet it is necessary to configure an applet viewer to provide full security permissions. This feature was tested with applet viewer from JDK 1.2 and Microsoft Internet Explorer 5.0.

The following sequence of steps should run JavaSpy with a sample DemoApplet in the appletviwer.

1. Create an HTML file to invoke the applet or use sample TestApplet.html. This HTML file should specify com.javaspy.JavaSpyA as the applet class and javaspy.jar as the archive name. The "Target" should contain the name of the debuggee applet class. Other parameters will be passed to your applet. For example, file TestApplet.html
contains the following lines:

<applet code="com.javaspy.JavaSpyA.class" archive=javaspy.jar width=100 height=50>
<param name=Target value="com.javaspy.DemoApplet">
<param name=Param1 value="Value1">
<param name=Param2 value="Value2">
</applet>

2. Create a policy file with all permissions. For example, file SecurityPolicy.txt (shipped with javaspy.jar) includes:

grant {
permission java.security.AllPermission;
};

3. Run the appletviewer (or use RunAppletViewer.bat):

appletviewer -J-Djava.security.policy=SecurityPolicy.txt TestApplet.html 

4. The appletviewer should start and display the demo applet. Then JavaSpy should start in a separate frame. It should work exactly like in the case of application debugging. 

To run in the Internet Explorer it is necessary to add javaspy.jar to the system's classpath.

 

 


The JavaSpy is a product of Dmitri Leman. 

Copyright © 2000, Dmitri Leman. 
All rights reserved.