This chapter explains how the different Java SE client technologies interact with each other. In addition, the chapter helps you to pinpoint the technology where you might start troubleshooting your problem.
Java SE Desktop consists of several technologies, as described at the Java SE Desktop Overview site. This guide currently describes troubleshooting procedures for the following desktop technologies:
This section explains how the different desktop technologies interact with each other. It also describes which of the technologies are more likely to work with native code, or depend on the environment, for example, the hardware or software configuration.
The better you understand the relationships among these technologies, the more quickly you can pinpoint the area your problem falls into.
The Java SE Desktop Java technologies are used to create rich client applications and applets. The desktop tools and libraries interface with the core tools and libraries of the platform.
The Abstract Window Toolkit (AWT) supports Graphical User Interface (GUI) programming. This API gives you, the developer, the following capabilities:
Construction of components such as menus, buttons, text fields, dialog boxes, and checkboxes
Handling of user input through those components
Rendering of simple shapes such as ovals and polygons
Control over the user-interface layout and fonts used by your applications
Handling of native drag-and-drop, events, and cursors
These classes are at the bottom of the software stack (closest to the underlying operating and desktop system).
AWT also provides a set of heavyweight components.
Purely AWT applications are usually not related to Swing. If an AWT application does custom rendering, it uses Java 2D.
The Java 2D API is a set of classes for advanced 2D graphics and imaging. This API enhances the graphics, text, and imaging capabilities of the AWT.
Java 2D is also at the bottom of the software stack (closest to the underlying operating and desktop system).
The Swing classes are built on top of the AWT and Java 2D architecture. Swing implements a set of components for building GUIs and adding rich graphics functionality and interaction to Java applications, with a pluggable look and feel.
Since Swing is a lightweight toolkit, it has very little interaction with the native platform. Swing uses Java 2D for rendering, and AWT provides creation and manipulation of top-level components, such as Windows, Frames, and Dialogs.
Internationalization is the process of designing software so that it can be adapted to various languages and regions without engineering changes.
Java Sound provides a low-level API to control the input and output of sound operations, including capturing, processing, and playing back audio and MIDI (Musical Instrument Digital Interface) data.
Java Plug-in extends the functionality of a web browser by allowing applets or Java Beans to be run under the Java SE runtime environment (JRE) rather than the Java runtime environment that is delivered with the web browser.
The following list provides some advice that can help you in troubleshooting a problem.
Identify the symptom.
Identify the type of issue.
Find the problem area.
Note relevant configuration information.
Make sure the correct patches, drivers, and operating systems are installed.
Try earlier releases (back-tracing).
Minimize the test. Restrict the test to as few issues at a time as possible.
Minimize the hardware and software configuration. Determine if the problem is reproducible on single and multiple systems. Determine if the problem changes with the browser version.
Determine if the problem depends on whether multiple VMs are installed.
Find the cause.
Check for typical causes in the area.
Use flags to change defaults.
In exceptional cases, use system properties to temporarily change the behavior of the painting system. Several unsupported properties are described on the System Properties for Java 2D Technology page.
Find the fix.
Find a possible workaround.
Fix the setup.
File a bug.
Fix the user's application.
The Troubleshooting Guide for Java SE 6 with HotSpot VM provides information that can help in troubleshooting problems between Java SE applications and the Java HotSpot virtual machine. A lot of this information can also be applied to problems with applications that use the Java SE desktop technologies.
See Chapter 8, Submitting Bug Reports for guidance on how to submit a bug report and suggestions on what data to collect for the report.
Take a moment to categorize the problem you are experiencing. This will help you identify the specific area of the problem, find the cause, and ultimately determine a solution or a workaround. Some of these issues might seem obvious, but it is always helpful to consider every possibility and to eliminate what is not an issue.
When a crash occurs, an error log is created with information and the state obtained at the time of the fatal error. The default name of the error log file is hs_err_pid pid .log. For a standalone Java application this file is created in the current directory, while for Java applets it is created in the browser binaries directory or user client folder.
See Appendix B, Fatal Error Log for a detailed description of the fatal error log.
A line near the top of the header section indicates the library where the error occurred. The example below shows that the crash was related to the AWT library.
... # Java VM: Java HotSpot(TM) Client VM (1.6.0-beta2-b76 mixed mode, sharing) # Problematic frame: # C [awt.dll+0x123456] ...
If the crash occurred in JNI native code, it was likely to have been caused by the desktop libraries. A crash in a native library typically means a problem in Java 2D or AWT, because Swing does not have much native code. The small amount of native code in Swing is mostly concerned with native look and feel, and if your application is using native look and feel, the crash may be related to this area.
The error log usually shows the exact library where the crash occurred, and this can give you a good idea of the cause. Crashes in libraries which are not part of the JDK usually indicate problems with the environment, for example, bad video drivers or desktop managers.
In the case of a VM crash, see the Troubleshooting Guide for Java SE 6 with HotSpot VM.
Performance problems are harder to diagnose because you generally do not have as much information.
First, you must determine which technology has the problem. For example, rendering performance problems are probably in Java 2D, and responsiveness issues can be Swing-related.
The following are a few examples of performance-related problems.
Startup. How long does the application take to start up and become useful to the user?
Footprint. How much memory does the application take? This can be measured by tools such as TaskManager on Windows or top and prstat on Solaris OS and Linux.
Runtime performance. How fast does the application complete the task it is designed to perform? For example, if the application computes something, how long does it take to finish the computations? In the case of a game, is the frame rate acceptable, does the animation look smooth?
Note that this is not the same as responsiveness, which is the next topic.
Responsiveness. How fast does the application respond to user interaction? If the user clicks a menu, how long does it take for the menu to appear? Can a long-running task be interrupted? Does the application repaint fast enough so that the application does not appear to be slow?
In addition to crashes, various behavior-related problems can occur. This section presents some of these problems and attempts to guide you to the Java SE desktop technology to troubleshoot.
Hangs: The application does not respond to user input. See the chapter on hanging or looping processes in the Troubleshooting Guide for Java SE 6 with HotSpot VM.
Exceptions in Java code. Exceptions are visibly thrown in the console or the application log files. An examination of this output will guide you to the problem area.
Rendering and repainting issues. For example, the application has an incorrect appearance after a repaint that was caused by another application being dragged over. Other examples are incorrect font, wrong colors, scrolling, damaging the application's frame by dragging another window over it, and updating a damaged area. These issues indicate a problem in Java 2D, or perhaps in Swing.
If your application exhibits repainting issues, the problem is likely to be with Java 2D or Swing.
A quick test is the following: If the problem is reproducible on a different platform (for example, the problem was originally seen on Windows, and it is also present on Solaris OS or Linux), it is very likely to be a Swing PaintManager problem.
See Chapter 3, Troubleshooting Java 2D for ways of changing Java 2D rendering pipelines with some flags. This can also help in determining if the problem is related to Java 2D or to Swing.
Multiscreen-related repainting issues belong to Java 2D (for example, repainting problems when moving a window from one screen to another, or other unusual behavior caused by interaction with a non-default screen device).
Desktop-interaction-related issues indicate a problem in AWT.
Some examples of desktop-interaction-related issues are resizing the window, minimizing or maximizing them, focus handling problems, modality, system Tray or Splashscreens, window placement on the screen, handling (enumerating) of multiple screens.
Drag-and-drop problems. Drag-and-drop belongs to AWT.
Printing problems. Depending on the API that is used, this could be either in Java 2D or AWT.
Font rendering issues in AWT applications might be a problem in font properties or in internationalization.
However, if your application is purely AWT, the text rendering problems might be caused by Java 2D. On Solaris OS or Linux the text rendering is performed by Java 2D. Alternatively, the problem might be in AWT or in internationalization.
Painting problems. This is most likely a Swing issue.
The text rendering in Swing is performed by Java 2D. Therefore, if your application uses Swing and you have text rendering problems (such as missing glyphs, incorrect rendering of glyphs, incorrect spacing between lines or characters, bad quality of the font rendering), the problem is likely to be in Java 2D.
Full-screen issues. This is a Java 2D API.
Encoding and locales issues (for example, no locale-specific characters displayed) indicate internalization problems.
This section simply lists a few tools that can help in troubleshooting. The Troubleshooting Guide for Java SE 6 with HotSpot VM contains detailed information on most of these tools, as well as many other useful tools.
Performance: benchmarks, profilers, DTrace, Java probes
Footprint: jhat, jmap, profilers
Crashes: native debuggers
Hangs: JConsole, jstack, ctrl-break
Check for bad fonts: Font2DTest (delivered with the JDK in demo/jfc/Font2DTest)
You can also debug JDK builds from dev.java.net for various issues.
JDWP (Java Debugging Wire Protocol) is very useful in debugging applications as well as applets.
Perform the following steps to debug applications:
Open a command line window. Set the PATH environment variable to jdk /bin.
Run the Java program (called Test in this example) to be debugged as follows:
java -Xdebug -Xrunjdwp:transport=dt_shmem,address=debug,server=y,suspend=y Test
On Solaris OS and Linux:
java -Xdebug -Xrunjdwp:transport=dt_socket,address=8888,server=y,suspend=y Test
The Test class starts in a debugging mode and waits for a debugger to attach to it.
To do Java level debugging, open another command line window and run jdb to attach to the above running debug server at address debug (Windows) or 8888 (Solaris OS or Linux).
jdb -attach 'debug' or jdb -attach 8888
After jdb initializes and attaches to Test, set your breakpoints and run.
stop in Test.main run
The jdb utility will hit the breakpoint.
To perform native level debugging along with Java debugging, use native debuggers to attach to the Java process running with JDWP.
In Windows, perform the following steps:
Open Visual Studio.
Choose Build -> Start Debug -> Attach to Process. Select the Java process that is running with JDWP.
Choose Project -> Settings -> Additional DLLs. Add the native dll that you want to debug, for example Test.dll.
Open the source file (one or more) of Test.dll and set your breakpoints.
Type cont in the jdb window. The process will hit the breakpoint in Visual Studio.
On Solaris OS, you can use the dbx utility to do native level debugging, and on Linux you can use the gdb utility.
Perform the following steps to debug applets using JDWP:
Launch the Java Control Panel.
Set the Applet Runtime settings.
In the field Java Runtime Parameters, enter the following:
Djavaplugin.trace=true -Xdebug -Xrunjdwp: transport=dt_shmem,address=debug,server=y,suspend=y
On Solaris OS and Linux:
Djavaplugin.trace=true -Xdebug -Xrunjdwp: transport=dt_shmem,address=debug,server=y,suspend=y
When you launch a browser and load an applet, the Java plugin starts in debugging mode and waits for a debugger to attach to it at the address debug (Windows) or 8888 (Solaris OS or Linux).
Run jdb from a command window and attach to address debug (or 8888).
jdb -attach debug Initializing jdb ... VM Started: No frames on the current call stack main
After jdb initializes, set the breakpoints, and then run.
sStop in MyApplet.func1 run
The applet will run in the browser until it hits the set breakpoint. Then you can debug the applet, see the control flow, watch its variables, and so forth.