Introduction to Client Issues

Java SE Desktop Technologies

Java SE Desktop consists of several technologies used to create rich client applications.

The desktop tools and libraries provide an interface between the Java application and the core tools and libraries of the platform, as shown in Figure 10-1.

Figure 10-1 Overview of the Java SE Desktop

Description of "Figure 10-1 Overview of the Java SE Desktop"

This topic describes troubleshooting techniques 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, check boxes, 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.
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).
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.
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.

To know more about internationalization APIs and features of Java SE, see Internationalization Overview.
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.

The better you understand the relationships between these technologies, the more quickly you can pinpoint the area your problem falls into.

General Steps to Troubleshoot an Issue

General steps to troubleshoot problems in your application.

When you experience problems running your application, follow the steps below for troubleshooting the issue.

Identify the symptom:
- Identify the Type of Issue.
- Find the problem area.
- Note the vant configuration information.
Eliminate non-issues:
- Ensure that 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 a single system and on 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.
- Use tracing.
- In exceptional cases, use system properties to temporarily change the behavior of the painting system.
Find the fix:
- Find a possible workaround.
- File a bug.
  
  For guidance about how to submit a bug report and suggestions about what data to collect for the report, see Submit a Bug Report.
- Fix the setup.
- Fix the application.

Identify the Type of Issue

Guidance about identifying the problem you are experiencing, and finding the cause and solution.

First of all, take a moment to categorize the problem you are experiencing. This will help you to identify the specific area of the problem, find the cause, and ultimately determine a solution or a workaround.

The following 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.

Java Client Crashes

An error log is created that contains information and the state obtained at the time of the fatal error, when the Java client crashes.

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.

To know more about 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 following example 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 then concerned with the native look and feel, and if your application is using native look and feel, then 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.

Performance Problems

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 the Linux operating system.
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: 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 it does not appear to be slow?

Behavior Problems

This section provides guidance about dealing with various problems in the application.

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. See Troubleshoot Process Hangs and Loops.
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 in Swing. For example, the application’s appearance is incorrect after a repaint that was caused by another application being dragged over it. 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 Linux), it is very likely to be a Swing PaintManager problem.

For the ways to change the Java 2D rendering pipelines with some flags, see Java 2D. This can also help determine 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 the 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 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), then 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.

Basic Tools

This section provides a list of basic tools that can help you troubleshoot certain types of issues.

This section lists a few tools that can help you troubleshoot certain types of issues.

Performance: Benchmarks, profilers, DTrace, Java probe.
FootPrint: jmap, profilers
Crashes: Native debuggers
Hangs: JConsole, jstack, Control+Break

Java Debug Wire Protocol

The Java Debug Wire Protocol (JDWP) is very useful for debugging applications.

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) that you want to debug:
- On Windows:
```
java -Xdebug -Xrunjdwp:transport=dt_shmem,address=debug,server=y,suspend=y Test
```
- On the Linux operating system:
```
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 the Linux operating system).
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 the Linux operating system:
```
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 Linux, you can use the gdb utility.
- On Windows, you can use Visual Studio for native-level debugging as follows:
  1. Open Visual Studio.
  2. On the Debug menu, select Attach to Process. Select the Java process that is running with JDWP.
  3. 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).
  4. Open the source file (one or more) of Test.dll and set your breakpoints.
  5. Enter cont in the jdb window. The process will hit the breakpoint in Visual Studio.