This chapter explains how the different Java SE Desktop technologies interact with each other. In addition, the chapter helps you pinpoint the technology from which you might start troubleshooting your problem and provides general troubleshooting tips.
This chapter contains the following sections:
Java SE Desktop consists of several technologies used to create rich client applications and applets. The desktop tools and libraries provide an interface between the Java application and the core tools and libraries of the platform.
For information on all desktop technologies available in Java SE, visit the Java SE Desktop Overview website at
http://www.oracle.com/technetwork/java/javase/tech/index-jsp-142216.html
This guide describes troubleshooting procedures for the following Java SE Desktop technologies:
Abstract Window Toolkit (AWT) provides a set of application programming interfaces (APIs) for constructing graphical user interface (GUI) components such as menus, buttons, text fields, dialog boxes, checkboxes, and for handling user input through those components. In addition, AWT allows for rendering of simple shapes such as ovals and polygons and enables developers to control the interface layout and fonts used by their applications. It also includes data transfer classes (including drag and drop) that allow cut and paste through the native platform clipboard.
The classes of this API 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.
For more information about AWT, see the AWT documentation at
http://docs.oracle.com/javase/8/docs/technotes/guides/awt/index.html
Java 2D is a set of classes for advanced 2D graphics and imaging. It encompasses line art, text, and images in a single comprehensive model. The API provides extensive support for image compositing and alpha channel images, a set of classes to provide accurate color space definition and conversion, and a rich set of display-oriented imaging operators. These classes are provided as additions to the java.awt and java.awt.image packages.
Like AWT, Java 2D is also at the bottom of the software stack (closest to the underlying operating and desktop system).
For more information about Java 2D, see the Java 2D documentation at
http://docs.oracle.com/javase/8/docs/technotes/guides/2d/index.html
Swing provides a comprehensive set of GUI components and services which enables the development of commercial-quality desktop and Internet/Intranet applications.
Swing is built on top of many of the other Java SE Desktop technologies, including AWT, Java2D and Internationalization. In most cases the Swing high-level components are recommended instead of those in AWT. However, there are many APIs in AWT that are important to understand when programming in Swing.
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.
For more information about Swing, see the Swing documentation at
http://docs.oracle.com/javase/8/docs/technotes/guides/swing/index.html
Internationalization is the process of designing software so that it can be adapted (localized) to various languages and regions easily, cost-effectively, and in particular without engineering changes to the software. Localization is performed by simply adding locale-specific components, such as translated text, data describing locale-specific behavior, fonts, and input methods.
In Java SE, internationalization support is fully integrated into the classes and packages that provide language-dependent or culture-dependent functionality.
For more information about internationalization APIs and features of Java SE, see the Internationalization documentation at
http://docs.oracle.com/javase/8/docs/technotes/guides/intl/index.html
Java Sound provides low-level support for audio operations such as audio playback and capture (recording), mixing, musical instrument digital interface (MIDI) sequencing, and MIDI synthesis in an extensible, flexible framework. This API is supported by an efficient sound engine which guarantees high-quality audio mixing and MIDI synthesis capabilities for the platform.
For more information about Java Sound, see the Java Sound documentation at
http://docs.oracle.com/javase/8/docs/technotes/guides/sound/index.html
Java Plug-in extends the functionality of popular web browsers by connecting them to the Java platform. This connection enables Java applets on websites to be run within the web browser on the desktop.
For more information about Java Plug-in, see Java Plug-in and Applet Architecture at
http://docs.oracle.com/javase/8/docs/technotes/guides/jweb/applet/applet_execution.html
The better you understand the relationships between these technologies, the more quickly you can pinpoint the area your problem falls into.
When you experience problems running your application, follow the steps below for troubleshooting the issue.
Identify the type of issue. See "Identifying 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.
Check for typical causes in the area.
Use flags to change defaults.
Use tracing.
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 at
http://docs.oracle.com/javase/8/docs/technotes/guides/2d/flags.html
Find a possible workaround.
File a bug.
For guidance on how to submit a bug report and suggestions on what data to collect for the report, see "Submitting Bug Reports".
Fix the setup.
Fix the application.
The Java SE HotSpot VM Troubleshooting Guide provides information that can help in troubleshooting problems between the Java application and the Java HotSpot virtual machine. A lot of that information can also be applied to problems with applications that use the Java SE Desktop technologies.
First of all, 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.
The subsections below provide information about common issue types:
Some of these 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.log where pid is the process identifier (PID) of the process that crashed. 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.
For a detailed description of the fatal error log, see "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 the Java Native Interface (JNI), 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 Java Development Kit (JDK) usually indicate problems with the environment, for example, bad video drivers or desktop managers.
In the case of a VM crash, see the Java SE HotSpot VM Troubleshooting Guide.
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.
Performance-related problems can be divided into the following categories:
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 Task Manager on Windows or top and prstat on Solaris OS and Linux.
Runtime
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 and 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 it does not appear to be slow?
In addition to crashes, various behavior-related problems can occur. Some of these problems are listed below. Their descriptions can guide you to the Java SE Desktop technology to troubleshoot.
Hangs occur when the application stops responding to user input. For more information about dealing with such issues, see the chapter on troubleshooting hanging or looping processes in the Java SE HotSpot VM Troubleshooting Guide.
Exceptions in Java code are visibly thrown to the console or the application log files. An examination of this output will guide you to the problem area.
Rendering and repainting issues indicate a problem in Java 2D, or perhaps in Swing. 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.
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.
For ways of changing Java 2D rendering pipelines with some flags, see Chapter 3, "Java 2D". 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).
Issues related to desktop interaction indicate a problem in AWT. Some examples of such issues occur when moving, resizing, minimizing and maximizing windows, handling focus, enumerating multiple screens, using modality, interacting with the notification area (system tray), and viewing splash screens.
Drag-and-drop problems are related to AWT.
Printing problems could be related either to Java 2D or AWT depending on the API that is used.
Text-rendering issues in AWT applications might be a problem in font properties or in internationalization.
However, if your application is purely AWT, text rendering problems might also be caused by Java 2D. On Solaris OS or Linux text rendering is performed by Java 2D.
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 font rendering), the problem is likely to be in Java 2D.
Painting problems are most likely a Swing issue.
Full-screen issues are related to the 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 certain types of issues. For more information on these and other tools, see the Java SE HotSpot VM Troubleshooting Guide.
Performance: benchmarks, profilers, DTrace, Java probes.
Footprint: jhat, jmap, profilers.
Crashes: native debuggers.
Hangs: JConsole, jstack, Control+Break.
Font-rendering: Font2DTest (delivered with the JDK in demo/jfc/Font2DTest)
You can also debug JDK builds from dev.java.net for various issues.
The Java Debugging Wire Protocol (JDWP) is very useful for debugging applications as well as applets.
To debug an application using JDWP:
Open the command line and set the PATH environment variable to jdk/bin where jdk is the installation directory of the JDK.
Use the following command to run the application (called Test in this example) which you want to debug:
On Windows:
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 will start in the debugging mode and wait for a debugger to attach to it at address debug (on Windows) or 8888 (on Solaris OS and Linux).
Open another command line and use the following command to run jdb and attach it to the running debug server:
On Windows:
jdb -attach 'debug'
On Solaris OS and Linux:
jdb -attach 8888
After jdb initializes and attaches to Test, you can perform Java-level debugging.
Set your breakpoints and run the application. For example, to set the breakpoint at the beginning of the main method in Test, run the following command:
stop in Test.main run
When the jdb utility hits the breakpoint, you will be able to inspect the environment in which the application is running and see if it is functioning as expected.
(Optional) To perform native-level debugging along with Java-level debugging, use native debuggers to attach to the Java process running with JDWP.
On Solaris OS, you can use the dbx utility and on Linux you can use the gdb utility.
In Windows, you can use Visual Studio for native-level debugging as follows:
Open Visual Studio.
On the Debug menu, select Attach to Process. Select the Java process that is running with JDWP.
On the Project menu, select Settings, and open the Debug tab. In the Category drop-down list, select Additional DLLs and 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.
To debug an applet using JDWP:
Launch the Java Control Panel, open the Java tab and click View. On the Java Runtime Environment Settings window, specify the following in the Runtime Parameters field for the necessary platform:
On Windows:
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=8888,server=y,suspend=y
When you launch a web browser and load an applet, the Java Plug-in will start in the debugging mode and wait for a debugger to attach to it at the address debug (on Windows) or 8888 (on Solaris OS and Linux).
Open the command line and use the following command to run jdb and attach it to the running debug server.
On Windows:
jdb -attach 'debug'
On Solaris OS and Linux:
jdb -attach 8888
After jdb initializes and attaches to Test, you can perform Java-level debugging.
Set your breakpoints and run the applet. For example, to set the breakpoint at the beginning of the func1 method in MyApplet, run the following command:
stop in MyApplet.func1 run
When the jdb utility hits the breakpoint, you will be able to inspect the environment in which the application is running and see if it is functioning as expected.
