SpyJ allows a programmer:
SpyJ 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 SpyJ simultaneously with a conventional debugger gives the developer maximum power for debugging and troubleshooting of Java GUI problems.
SpyJ was developed to run on Java VM version 1.1 and higher. Advanced features (such as method call and field access tracing require 1.2 or higher).
To display the tree of GUI components and display Java events SpyJ needs to intercept flow of events in the Java event queue. Under JDK 1.2 and 1.3 SpyJ uses a documented API to install a global event listener. SpyJ should be able to run on third party Java implementations, which fully support Sun JDK 1.2 specification.
To intercept events on JDK 1.1 SpyJ 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.spyj.SpyJQueueMonitor11.
SpyJ also supports event spying on Microsoft VM v 5.0 by using an undocumented API, which may be not supported in the future.
SpyJ 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, Java Plugin 1.3 and Microsoft Internet Explorer 5.0.
Method calls tracing requires JDK 1.2 or higher VM, which supports JVMDI (debug interface) or JVMPI (profiler interface). Field access tracing requires JVMDI interface on JDK 1.2 or higher. SpyJ includes SpyJDll.dll Windows DLL to support these features. The "classic" version of Java VM in interpreted mode should be used. SpyJ may not work correctly on some versions of "hotspot" Java VM (the VM may work very slowly in debug mode and may crash) . See Running SpyJ for more details. To get the SpyJ native library for Linux please contact support@forwardlab.com.
SpyJ was tested on the following platforms:
SpyJ is distributed in a single zip file spyj20.zip (where 20 is the version number and may change). This file contains Java classes, native library (SpyJDll.dll), a manual, a readme and a license texts. The DLL is only used for method call and field access tracing. The rest of SpyJ features does not require any platform specific features.
In order to install and use SpyJ it is necessary to have a Java virtual machine installed. For best results a full JDK should be installed, but most features works with JRE as well.
The easiest way to install SpyJ on Windows is to open spyj20.zip in a zip application, such as WinZip, then execute Setup.bat or _Setup.bat.
After start the Setup asks the User to select the installation directory. Then it copies the spyj20.zip to that directory and extracts some files, such as the manual. The Setup does not attempt to modify the "CLASSPATH" system environment variable, because this is platform-specific operation. See Running SpyJ for more information about using the SpyJ.
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 SpyJ 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 SpyJ, including hierarchical view of UI components, their properties, events, trace method calls and field accesses.
If you don't have a zip application, you can run the Setup class from command
line:
java -classpath spyj20.zip com.spyj.Setup
The User may need to install SpyJ 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 SpyJ in most circumstances as long as spyj20.zip is on the classpath and class com.spyj.SpyJ is instantiated immediately after the debuggee starts. To work on JDK 1.1 it is necessary to add the line "AWT.EventQueueClass=com.spyj.SpyJQueueMonitor11" to awt.properties.
Manual installation steps:
1. Copy spyj20.zip to a desired directory.
2. Extract the manual (this document), all .gif files, SpyJDll.dll and the license agreement:
jar xvf spyj20.zip Manual.htm License.txt readme.txt
jar xvf spyj20.zip ManualFiles/EventsScreenScr.gif ManualFiles/SpyJAndDemoDragScr.gif
jar xvf spyj20.zip ManualFiles/SpyJInitAndDemoScr.gif ManualFiles/MethodFieldTracesScr.gif
jar xvf spyj20.zip SpyJPropConfig.txt
jar xvf spyj20.zip Run.bat RunJdk11.bat RunJdk13.bat Setup.bat RunAppletViewer.bat
jar xvf spyj20.zip SecurityPolicy.txt TestApplet.html TestAppletPlugin.html
jar xvf spyj20.zip SpyJDll.dll
Read the license agreement in License.txt.
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.spyj.SpyJQueueMonitor11
If awt.properties file cannot be found, it may be because you using a non-standard JDK. SpyJ 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 spyj20.zip if necessary. Replace java.exe by jre.exe or jview.exe and "-classpath" by "-cp" depending on your environment.
java.exe -classpath spyj20.zip com.spyj.SpyJ com.spyj.Demo DemoParam1 DemoParam2
to enable tracing method calls, event accesses and modifications run JVM 1.2 or higher, add the directory with SpyJDll.dll to the system path and run:
java.exe -classic -Xdebug -Xnoagent -Djava.compiler=NONE -XrunSpyJDll -classpath spyj20.zip com.spyj.SpyJ com.spyj.Demo DemoParam1 DemoParam2
This command line invokes the Java interpreter with spyj20.zip on the classpath and com.spyj.SpyJ as the main executable class. The Demo class and it's parameters are specified as arguments for the SpyJ class. The SpyJ 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 SpyJ 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 SpyJ.
6. If you want to run SpyJ 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 spyj20.zip to the classpath string and com.spyj.SpyJ 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 spyj20.zip to the classpath box, move your own main class from the "start class" box to the front of the "parameters" box and type com.spyj.SpyJ in the "start box".
While running SpyJ from IDE it may be convenient to quickly enable or disable the SpyJ without making too many modifications in the project configuration dialog. For that purpose SpyJX class was created. When you don't want SpyJ to start, simply put 'X' at the end of com.spyj.SpyJ in the appropriate box in the project configuration dialog. SpyJX will launch your application exactly as SpyJ does, but it will not launch the spy itself.
Except for JDK 1.1, SpyJ does not modify anything in the environment. Therefore, to uninstall it, simply delete the zip file, manual and other extracted files.
Under JDK 1.1 it is necessary to remove the AWT.EventQueueClass=com.spyj.SpyJQueueMonitor11 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 spyj20.zip com.spyj.Uninstall
After the installation is successfully completed, you should be able to run the Demo class and your own applications. If you used the simplified installation, it should have produced file Run.bat with commands appropriate for the selected VM. For example the commands for JDK 1.3.1 with classic VM are:
PATH=%PATH%;c:\SpyJ
c:\jdk1.3\bin\java -classic -Xdebug -Xnoagent -Djava.compiler=NONE -XrunSpyJDll -classpath c:\SpyJ\spyj20.zip com.spyj.SpyJ
com.spyj.Demo DemoParam1 DemoParam2
If you use JDK 1.1, method call and field access tracing are not supported and command will be:
c:\jdk1.1.8\bin\java.exe -classpath c:\jdk1.1.8\lib\classes.zip;spyj20.zip com.spyj.SpyJ com.spyj.Demo DemoParam1 DemoParam2
If you performed installation manually, you will need to modify Run.bat. Specify full paths for java.exe and spyj20.zip if necessary. Replace java.exe by jre.exe or jview.exe and "-classpath" by "-cp" depending on your environment. Replace com.spyj.Demo and parameters by the name of your class and arguments. See Manual installation for more details.
When the SpyJ 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 SpyJ and Demo, find the missing OK button and make it visible at run time, without recompiling the program (to confirm the cause of the bug).
To start exploring the Demo GUI, click on the "Init Spy" button. The SpyJ 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: SpyJ 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 SpyJ, 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 second 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 SpyJ 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 SpyJ window) displays the most useful information about the currently selected component (either selected in the tree or by using Finder Tool). The program uses SpyJPropConfig.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)
The final demonstration is to watch method calls and field accesses and modifications. It is available only when using JDK 1.2 or higher classic VM. Click on "Method/field" button on the "SpyJ demo" window. It will display a list with the demo instructions. On SpyJ toolbar click on "Trace" button. "SpyJ Trace Points" window will appear, click on "Add" button to display "Add SpyJ Trace Point" dialog. Enter class "com.spyj.DemoTrace" or use "Browse" button to select the class. Then enter "DemoMethod()" method or select it using the "Browse" button. Then click "OK". Then click "Add" again and enter the same class and "DemoField" field, click "OK". Click "OK" to dismiss the "Trace Points" dialog and activate the trace points. Then click on "DemoMethod()" and "DemoField" buttons on the "SpyJ Demo" window. The trace of the method call and field access and assignment should appear in the event view window.
SpyJ 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.3 and Java Plugin 1.3.1 with Microsoft Internet Explorer 5.0.
The following sequence of steps should run SpyJ 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.spyj.SpyJA as the applet class and spyj20.zip
as the archive name. The parameter "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.spyj.SpyJA.class" archive=spyj20.zip
width=100 height=50>
<param name=Target value="com.spyj.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 spyj20.zip) includes:
grant {
permission java.security.AllPermission;
};
3. Run the appletviewer (or use RunAppletViewer.bat):
c:\jdk1.3.1\bin\appletviewer -classic -J-Xdebug -J-Xnoagent -J-XrunSpyJDll -J-Djava.compiler=NONE -J-Djava.security.policy=SecurityPolicy.txt TestApplet.html
If tracing of method calls and field accesses is not needed, execute the following line:
c:\jdk1.3.1\bin\appletviewer -J-Djava.security.policy=SecurityPolicy.txt TestApplet.html
4. The appletviewer should start and display the demo applet. Then SpyJ 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 spyj20.zip to the system's classpath.
1. In the HTML file, which invokes the applet, insert OBJECT tag as explained in Java Plugin documentation. Specify com.spyj.SpyJA as the applet class (parameter "code" of the plugin), spyj20.zip as the archive name (parameter "archive"). The "Target" parameter should contain the name of your applet class. Other parameters will be passed to your applet. For example, file TestAppletPlugin.html contains the following lines:
<OBJECT classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
width=600 height=400 align="baseline" code="com.spyj.SpyJA.class" archive=spyj20.zip>
<PARAM NAME="code" VALUE="com.spyj.SpyJA.class">
<PARAM NAME="archive" VALUE="spyj20.zip">
<PARAM NAME="type" VALUE="application/x-java-applet;version=1.3">
<param name=Target value="com.spyj.DemoApplet">
<param name=text value="SpyJ applet">
No Java 2 SDK, Standard Edition v 1.3 support for applet
</OBJECT>
2. Since SpyJ needs to access Java event queue, files and properties, it
is necessary to give SpyJ all permissions. To enable this open java.policy file
under lib/security directory of the JRE and add lines:
grant codeBase "file:c:/spyj/spyj20.zip" {
permission java.security.AllPermission;
};
3. Add the directory with SpyJDll.dll to the system path.
4. Open Java Plugin control panel and enter Java Runtime Parameters:
-Xdebug -Xnoagent -Djava.compiler=NONE -XrunSpyJDll
5. Open the HTML file (TestAppletPlugin.html) in a browser. If the applet does not start, verify that SpyJDll is on the path or try to temporarily remove -XrunSpyJDll option. If the applet failed to start because of access control exception, make sure that the permissions are granted as explained above.
Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc., in the U.S. and other countries.
The SpyJ is a product of ForwardLab,Inc.
Copyright © 2000,2001, ForwardLab,Inc.
All rights reserved.