Documentation Contents

Contents

Title and Copyright Information

Preface

• Audience
• Documentation Accessibility
• Related Documents
• Conventions

Part I General Java Troubleshooting

1 Diagnostic Tools and Detailed Descriptions

• Diagnostic Tools - Overview
  • Postmortem Diagnostics Tools
  • Hung Processes Tools
  • Monitoring Tools
  • Other Tools, Options, Variables, and Properties
• Java Mission Control
  • How to Produce a Flight Recording
• The jcmd Utility
• Useful Commands for jcmd Utility
• Troubleshooting Options for jcmd Utility
• HPROF
  • Heap Allocation Profile heap=sites
  • Heap Dump Profile heap=dump
  • CPU Usage Sampling Profile cpu=samples
  • CPU Usage Times Profile cpu=times
• JConsole
• Java VisualVM
• The jdb Utility
  • Attaching to a Process
  • Attaching to a Core File on the Same Machine
  • Attaching to a Core File or a Hung Process from a Different Machine
• The jhat Utility
  • Standard Queries
  • Custom Queries
  • Heap Analysis Hints
• The jinfo Utility
• The jmap Utility
  • Heap Configuration and Usage
  • Heap Histogram
  • Permanent Generation Statistics
• The jps Utility
• The jrunscript Utility
• The jsadebugd Daemon
• The jstack Utility
  • Forcing a Stack Dump
  • Printing Stack Trace from a Core Dump
  • Printing a Mixed Stack
• The jstat Utility
• The jstatd Daemon
• The visualgc Tool
• Control+Break Handler
  • Thread Dump
  • Detected Deadlocks
  • Heap Summary
• Native Operating System Tools
  • Using the DTrace Tool
  • Improvements in the pmap Tool
  • Improvements in the pstack Tool
• Custom Diagnostic Tools
  • The java.lang.management Package
  • The java.lang.instrument Package
  • The java.lang.Thread Class
  • Java Virtual Machine Tool Interface
  • Java Platform Debugger Architecture

2 Troubleshooting Memory Leaks

• Understanding the OutofMemoryError Exception
• Crash Instead of OutOfMemoryError
• Diagnosing Leaks in Java Language Code
  • Creating a Heap Dump
  • Obtaining a Heap Histogram
  • Monitoring the Number of Objects Pending Finalization
• Diagnosing Leaks in Native Code
  • Tracking All Memory Allocation and Free Calls
  • Tracking Memory Allocation in a JNI Library
  • Tracking Memory Allocation with Operating System Support
  • Using the dbx Debugger to Find Leaks
  • Using the libumem Tool to Find Leaks

Part II Debugging JVM Issues

3 Troubleshooting System Crashes

• Determining Where the Crash Occurred
  • Crash in Native Code
  • Crash in Compiled Code
  • Crash in the HotSpot Compiler Thread
  • Crash in VMThread
  • Crash Due to Stack Overflow
• Finding a Workaround
  • Working Around Crashes in the HotSpot Compiler Thread or Compiled Code
  • Working Around Crashes During Garbage Collection
  • Working Around Crashes Caused by Class Data Sharing
• Microsoft Visual C++ Version Considerations

4 Troubleshooting Hanging or Looping Processes

• Diagnosing a Looping Process
• Diagnosing a Hung Process
  • Deadlock Detected
  • Deadlock Not Detected
  • No Thread Dump
• Oracle Solaris 8 Thread Library

5 Integrating Signal and Exception Handling

• Signal Handling on Oracle Solaris and Linux Operating Systems
  • Signal Chaining
• Exception Handling on Windows
  • Exception Handling By the Java HotSpot VM
  • Console Handlers

Part III Debugging Core Library Issues

6 Time Zone Settings in the JRE

• Native Time Zone Information and the JRE
  • Determine the Time Zone Data Version in Use
  • Troubleshooting Problems with Tzupdater
• Determining the Default Time Zone on Windows
  • Check Which Time Zone the JRE Reports as Default
  • Determine the Setting in the Control Panel
  • Check Whether Automatic Daylight Saving Time Adjustment is Enabled
  • Set the Default Time Zone in the Control Panel
  • Check Whether You Can Use -Duser.timezone
  • Special Tools in Windows 7
  • JRE Internal Representation of Time Zone Mappings

Part IV Debugging Client Issues

7 Introduction to Client Issues

• Java SE Desktop Overview
• Troubleshooting an Issue
• Identifying the Type of Issue
  • Crashes
  • Performance Problems
  • Behavior Problems
• Basic Tools
• Using JDWP

8 AWT

• Debugging Tips for AWT
• Layout Managers
• Key Events
• Modality
• Memory Leaks
• Crashes
  • How to Distinguish an AWT Crash
  • How to Troubleshoot an AWT Crash
• Focus Events
  • How to Trace Focus Events
  • Native Focus System
  • Focus System in the Java Plug-in
  • Focus Models Supported by X Window Managers
  • Miscellaneous Problems With Focus
• Data Transfer
  • Debugging Drag and Drop Applications
  • Frequent Issues With Data Transfer
• Other Issues
  • Splash Screen Issues
  • Tray Icon Issues
  • Popup Menu Issues
  • Background/Foreground Color Inheritance
  • AWT Panel Size Restriction
  • Hangs when debugging popup menus and similar components on X11
  • Window.toFront()/toBack() Behavior on X11
• Heavyweight/Lightweight Components Mixing
  • The Requirement of Validating the Component Hierarchy
  • Validate Roots
  • Swing Painting Optimizations
  • Non-opaque LW Components
  • Disabling the Default HW/LW Mixing Feature Implementation

9 Java 2D

• Changing Rendering Pipelines and Their Properties
  • Oracle Solaris and Linux: Using Default X11 Pipeline
  • Oracle Solaris operating system on SPARC: Changing Default Visual Used by Java 2D
  • Windows OS: Using Default DirectDraw/GDI Pipeline
  • Windows OS: Using Direct3D Pipeline (Full-Screen Mode)
  • Using OpenGL Pipeline (Oracle Solaris, Linux, and Windows)
• Generic Performance Issues
  • Hardware Accelerated Rendering Primitives
  • Using Java 2D Primitive Tracing to Detect and Avoid Non-accelerated Rendering
  • Causes of Poor Rendering Performance
  • Improving Performance of Software-only Rendering
• Text-Related Issues
  • Application Crash During Text Rendering
  • Differences in Text Appearance
  • Metrics
• Java 2D Printing

10 Swing

• General Debugging Tips for Swing
• Specific Debugging Tips for Swing
  • Incorrect Threading
  • Overlapping Children of a JComponent
  • Updating the Display
  • Changing the Model
  • Adding or Removing Components
  • Overriding Opaque
  • Permanent Changes to a Graphics
  • Custom Painting and Double Buffering
  • Opaque Content Pane
  • Performance: Call to Renderer for Each Cell
  • Possible Leaks
  • Mixing Heavyweight and Lightweight Components
  • Tips for Using Synth
  • Tracking Activity on Event Dispatch Thread
  • Differing Default Layout Managers
  • Listener Objects Dispatched to Deepest Component
  • Adding a Component to Content Pane
  • Drag and Drop Support in Swing
  • One Parent at a Time for a Component
  • Problem With JFileChooser and Shortcuts on Windows

11 Internationalization

• Introduction
• Troubleshooting

12 Java Sound

• System Sound Configuration
• Audio File Formats
• Audio Formats
• Overrun and Underrun Conditions

13 Applets and Java Web Start Applications

• Configuration Problems
  • Validation
  • Common Configuration Problems
  • Managing Java Runtimes
  • Passing Parameters to the JRE
  • Java Deployment Home
  • Deployment Tracing Information
  • Deployment Cache
  • Network Configuration
• Applet Troubleshooting
  • Applet Does Not Start - Plugin Cheat Sheet
  • Unresponsive Web Page
• Avoiding Security Dialogs
  • Signed Applications
  • Mixed Code Issues
• Development Tips
  • Debugging Applets and Web Start Applications
  • Profiling Applets and Java Web Start Applications
  • Debugging Memory Leaks

Part V Submitting Bug Reports

14 Submitting Bug Reports

• Checking for Existing Fixes in Update Releases
• Preparing to Submit a Bug Report
• Collecting Data for a Bug Report
  • Hardware Details
  • Operating System
  • Java SE Version
  • Command-Line Options
  • Environment Variables
  • Fatal Error Log
  • Core or Crash Dump
  • Detailed Description of the Problem
  • Logs and Traces
  • Results from Troubleshooting Steps
• Collecting Core Dumps
  • Collecting Core Dumps on Oracle Solaris operating system
  • Collecting Core Dumps on Linux
  • Reasons for Not Getting a Core File
  • Collecting Crash Dumps on Windows

Part VI Appendix

A Fatal Error Log

• Location of Fatal Error Log
• Description of Fatal Error Log
• Header Format
• Thread Section Format
  • Thread Information
  • Signal Information
  • Register Context
  • Machine Instructions
  • Thread Stack
  • Further Details
• Process Section Format
  • Thread List
  • VM State
  • Mutexes and Monitors
  • Heap Summary
  • Memory Map
  • VM Arguments and Environment Variables
  • Signal Handlers
• System Section Format

B Java 2D Properties

• Properties on Oracle Solaris and Linux
• Properties on Windows

C Environment Variables and System Properties

D Command-Line Options

• Java HotSpot VM Command-Line Options
  • The -XX:HeapDumpOnOutOfMemoryError Option
  • The -XX:OnError Option
  • The -XX:ShowMessageBoxOnError Option
  • Other -XX Options
• Other Command-Line Options
  • The -Xcheck:jni Option
  • The -verbose:class Option
  • The -verbose:gc Option
  • The -verbose:jni Option

E Summary of Tools in This Release

---

Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.

Contact Us