Exit Print View

Troubleshooting Guide for Java SE 7 Desktop Technologies

Print View

Document Information


1.  Introduction

1.1 Overview of Java SE Desktop Technologies

1.1.1 Introduction to Java SE Desktop

1.1.2 AWT

1.1.3 Java 2D

1.1.4 Swing

1.1.5 Internationalization

1.1.6 Sound

1.1.7 Plug-in

1.2 General Troubleshooting Tips

1.3 Identifying the Problem Area

1.3.1 Crashes

1.3.2 Performance Problems

1.3.3 Behavior Problems

1.4 Basic Tools

1.5 Using JDWP for Debugging

2.  AWT

3.  Java 2D

4.  Swing

5.  Internationalization

6.  Java Sound

7.  Applets and Java Web Start Applications

8.  Submitting Bug Reports

A.  Java 2D Properties

B.  Fatal Error Log

Chapter 1


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.

1.1 Overview of Java SE Desktop Technologies

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.

1.1.1 Introduction to Java SE Desktop

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.

Overview of Java SE Desktop
Overview showing user application on top of desktop technologies, which are on top of core tools and libraries

1.1.2 AWT

The Abstract Window Toolkit (AWT) supports Graphical User Interface (GUI) programming. This API gives you, the developer, the following capabilities:

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.

1.1.3 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).

1.1.4 Swing

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.

1.1.5 Internationalization

Internationalization is the process of designing software so that it can be adapted to various languages and regions without engineering changes.

1.1.6 Sound

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.

1.1.7 Plug-in

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.

1.2 General Troubleshooting Tips

The following list provides some advice that can help you in troubleshooting a problem.

  1. Identify the symptom.

    • Identify the type of issue.

    • Find the problem area.

    • Note relevant configuration information.

  2. Eliminate non-issues.

    • 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.

  3. 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. Several unsupported properties are described on the System Properties for Java 2D Technology page.

  4. Find the fix.

    • Find a possible workaround.

    • Fix the setup.

    • File a bug.

    • Fix the user's application.

The Troubleshooting Guide for Java SE 7 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.

1.3 Identifying the Problem Area

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.

1.3.1 Crashes

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_pidpid.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 7 with HotSpot VM.

1.3.2 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.

The following are a few examples of performance-related problems.

1.3.3 Behavior Problems

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.

1.4 Basic Tools

This section simply lists a few tools that can help in troubleshooting. The Troubleshooting Guide for Java SE 7 with HotSpot VM contains detailed information on most of these tools, as well as many other useful tools.

You can also debug JDK builds from dev.java.net for various issues.

1.5 Using JDWP for Debugging

JDWP (Java Debugging Wire Protocol) is very useful in debugging applications as well as applets.

Perform the following steps to debug applications:

  1. Open a command line window. Set the PATH environment variable to jdk/bin.

  2. Run the Java program (called Test in this example) to be debugged as follows:

    • 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
  3. The Test class starts in a debugging mode and waits for a debugger to attach to it.

  4. 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
  5. After jdb initializes and attaches to Test, set your breakpoints and run.

    stop in Test.main run
  6. 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:

  1. Open Visual Studio.

  2. Choose Build -> Start Debug -> Attach to Process. Select the Java process that is running with JDWP.

  3. Choose Project -> Settings -> Additional DLLs. 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. 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:

  1. Launch the Java Control Panel.

  2. Set the Applet Runtime settings.

  3. In the field Java Runtime Parameters, enter the following:

    • On Windows:

      Djavaplugin.trace=true -Xdebug -Xrunjdwp:
    • On Solaris OS and Linux:

      Djavaplugin.trace=true -Xdebug -Xrunjdwp:
  4. 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).

  5. 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
  6. After jdb initializes, set the breakpoints, and then run.

    sStop in MyApplet.func1 run
  7. 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.