1/31

Contents

Title and Copyright Information

Preface

• Audience
• Documentation Accessibility
• Related Documents
• Conventions

Part I General Java Troubleshooting

1 Prepare Java for Troubleshooting

• Set Up Java for Troubleshooting
• Enable Options and Flags for JVM Troubleshooting
• Gather Relevant Data
  • Make a Java Application Easier to Debug

2 Diagnostic Tools

• Diagnostic Tools Overview
• Java Mission Control
  • Troubleshoot with Java Mission Control
• What Are Java Flight Recordings
  • Types of Recordings
• How to Produce a Flight Recording
  • Use Java Mission Control to Produce a Flight Recording
  • Use Startup Flags at the Command Line to Produce a Flight Recording
  • Use Triggers for Automatic Recordings
• Inspect a Flight Recording
  • How to Get a Sample JFR to Inspect
  • Range Navigator
  • General Tab
  • Memory Tab
  • Code Tab
  • Threads Tab
  • I/O Tab
  • System Tab
  • Events Tab
• The jcmd Utility
  • Useful Commands for the jcmd Utility
  • Troubleshoot with the jcmd Utility
• Native Memory Tracking
  • Use NMT to Detect a Memory Leak
  • How to Monitor VM Internal Memory
• JConsole
  • Troubleshoot with the JConsole Tool
  • Monitor Local and Remote Applications with JConsole
• The jdb Utility
  • Troubleshoot with the jdb Utility
  • Attach a Process
  • Attach to a Core File on the Same Machine
  • Attach to a Core File or a Hung Process from a Different Machine
• The jinfo Utility
  • Troubleshooting with the jinfo Utility
• The jmap Utility
  • Heap Configuration and Usage
  • Heap Histogram
  • Permanent Generation Statistics
• The jps Utility
• The jstack Utility
  • Troubleshoot with the jstack Utility
  • Stack Trace from a Core Dump
  • Mixed Stack
• The jstat Utility
• The visualgc Tool
• Control+Break Handler
  • Thread Dump
  • Detect Deadlocks
  • Heap Summary
• Native Operating System Tools
  • DTrace Tool
  • Probe Providers in Java HotSpot VM
  • Improvements to the pmap Utility
  • Improvements to the pstack Utility
• Custom Diagnostic Tools
  • Java Platform Debugger Architecture
• NMT Memory Categories
• Postmortem Diagnostic Tools
• Hung Processes Tools
• Monitoring Tools
• Other Tools, Options, Variables, and Properties
• The java.lang.management Package
• The java.lang.instrument Package
• The java.lang.Thread Class
• JVM Tool Interface
• The jrunscript Utility
• The jsadebugd Daemon
• The jstatd Daemon
• Thread States for a Thread Dump
• Troubleshooting Tools Based on the Operating System

3 Troubleshoot Memory Leaks

• Debug a Memory Leak Using Java Flight Recorder
  • Detect a Memory Leak
  • Find the Leaking Class
  • Find the Leak
• Understand the OutOfMemoryError Exception
• Troubleshoot a Crash Instead of OutOfMemoryError
• Diagnose Leaks in Java Language Code
  • Get a Heap Histogram
  • Monitor the Objects Pending Finalization
• Diagnose Leaks in Native Code
  • Track All Memory Allocation and Free Calls
  • Track All Memory Allocations in the JNI Library
  • Track Memory Allocation with Operating System Support
  • Find Leaks with the dbx Debugger
  • Find Leaks with the libumem Tool

4 Troubleshoot Performance Issues Using JFR

• JFR Overhead
• Find Bottlenecks
• Garbage Collection Performance
• Synchronization Performance
• I/O Performance
• Code Execution Performance

Part II Debug JVM Issues

5 Troubleshoot System Crashes

• Determine Where the Crash Occurred
  • Crash the Native Code
  • Crash in the Compiled Code
  • Crash in the HotSpot Compiler Thread
  • Crash in the VM Thread
  • Crash Due to Stack Overflow
• Find 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

6 Troubleshoot Process Hangs and Loops

• Diagnose a Loop Process
• Diagnose a Hung Process
  • Deadlock Detected
  • Deadlock Not Detected
  • No Thread Dump
• Oracle Solaris 8 Thread Library

7 Handle Signals and Exceptions

• Handle Signals on Oracle Solaris, Linux, and macOS
• Handle Exceptions on Windows
• Signal Chaining
• Handle Exceptions Using the Java HotSpot VM
• Console Handlers
• Signals Used in Oracle Solaris, Linux, and macOS

Part III Debug Core Library Issues

8 Time Zone Settings in the JRE

• Native Time Zone Information and the JRE
  • Determine the Time Zone Data Version in Use
  • Troubleshoot Problems with TZupdater
• Determine the Default Time Zone on Windows
  • Check the Default Time Zone JRE Reports
  • Determine the Setting in the Control Panel
  • Check for Automatic Daylight Saving Time Adjustment
  • Set the Default Time Zone in the Control Panel
  • Check -Duser.timezone System Property
  • Special Tools in Windows 7
  • JRE Internal Representation of Time Zone Mappings

Part IV Debug Client Issues

9 Introduction to Client Issues

• Java SE Desktop Technologies
• General Steps to Troubleshoot an Issue
• Identify the Type of Issue
  • Java Client Crashes
  • Performance Problems
  • Behavior Problems
• Basic Tools
• Java Debug Wire Protocol

10 AWT

• Debug Tips for AWT
• Layout Manager Issues
• Key Events
• Modality Issues
• AWT Crashes
• Focus Events
  • How to Trace Focus Events
  • Native Focus System
  • Focus System in Java Plug-in
  • Focus Models Supported by X Window Managers
  • Miscellaneous Problems with Focus
• Data Transfer
  • Debug Drag-and-Drop Applications
  • Frequent Issues with Data Transfer
• Other Issues
  • Splash Screen Issues
  • Tray Icon Issues
  • Pop-up Menu Issues
  • Background or Foreground Color Inheritance
  • AWT Panel Size Restriction
  • Hangs During Debugging of Pop-up Menus and Similar Components on X11
  • Window.toFront()/toBack() Behavior on X11
• Heavyweight or Lightweight Components Mix

11 Java 2D Pipeline Rendering and Properties

• Oracle Solaris and Linux: X11 Pipeline
  • X11 Pipeline Pixmaps Properties
  • X11 Pipeline MIT Shared Memory Extension
  • Oracle Solaris on SPARC: DGA Support
  • Oracle Solaris on SPARC - Change Java 2D Default Visual
• Windows OS - DirectDraw/GDI Pipeline
• Windows OS - Direct3D Pipeline in Full-Screen Mode
• OpenGL Pipeline in Oracle Solaris, Linux, and Windows
  • Enable OpenGL Pipeline
  • Minimum Requirements
  • Diagnose Startup Issues
  • Diagnose Rendering and Performance Issues
• Latest OpenGL Drivers

12 Java 2D

• Generic Performance Issues
  • Hardware-Accelerated Rendering Primitives
  • Primitive Tracing to Detect and Avoid Non-Accelerated Rendering
  • Causes of Poor Rendering Performance
  • Improve Performance of Software-only Rendering
• Text-Related Issues
  • Application Crash During Text Rendering
  • Differences in Text Appearance
  • Metrics
• Java 2D Printing

13 Swing

• General Debug Tips for Swing
• Specific Debug Tips for Swing
  • Incorrect Threading
  • JComponent Children Overlap
  • Display Update
  • Model Change
  • Add or Remove Components
  • Opaque Override
  • Permanent Changes to Graphics
  • Custom Painting and Double Buffering
  • Opaque Content Pane
  • Renderer Call for Each Cell Performance
  • Possible Leaks
  • Mix Heavyweight and Lightweight Components
  • Use Synth
  • Track Activity on Event Dispatch Thread
  • Specify Default Layout Manager
  • Listener Object Dispatched to Incorrect Component
  • Add a Component to Content Pane
  • Drag and Drop Support
  • One Parent for a Component
  • JFileChooser Issues with Windows Shortcuts

14 Internationalization

• Troubleshoot Internationalization and Localization

15 Java Sound

• Troubleshoot Java Sound Issues

16 Applets and Java Web Start Applications

• Configuration Problems
  • Validation
  • Common Configuration Problems
  • Manage Java Runtime
  • Pass Parameters to the JRE
  • Java Deployment Home
  • Deployment Tracing
  • Deployment Cache
  • Network Configuration
• Troubleshoot Applets
  • Plugin Cheat Sheet for Applet Start
  • Browser or Java Process Crash
  • Unresponsive Web page
• Avoid Security Dialog Boxes
  • Signed Applications
  • Mixed-Code Issues
• Development Tips

Part V Submit Bug Reports

17 Submit a Bug Report

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

Appendices

A Fatal Error Log

• Location of Fatal Error Log
• Description of Fatal Error Log
• Header Format
• Thread Section Format
• Process Section Format
• System Section Format

B Java 2D Properties

• Properties on Oracle Solaris and Linux
• Properties on Windows

C Environment Variables and System Properties

• The JAVA_HOME Environment Variable
• The JAVA_TOOL_OPTIONS Environment Variable
• The java.security.debug System Property

D Command-Line Options

• Java HotSpot VM Command-Line Options
• Other Command-Line Options

E Summary of Tools in This Release