Preface

This document helps in troubleshooting problems that might occur with applications that are developed using the release of Java Platform, Standard Edition Development Kit 7 (JDK 7 release). In particular, this guide addresses possible problems between the application and the Java HotSpot virtual machine.

See Appendix D, Summary of Tools in This Release for a list of changes to the troubleshooting tools for this release of the JDK compared with the previous release.

This document is currently focused on providing information about the tools and options available for diagnostics and monitoring. It does not yet include information on garbage collection or diagnosing performance issues.

For help in troubleshooting Java applications that use desktop technologies, see the following guide: Troubleshooting Guide for Java SE 7 Desktop Technologies.

Java HotSpot Virtual Machine

The Java HotSpot virtual machine provides a runtime environment for instructions that were generated by a Java compiler. The JDK provides two implementations of the Java virtual machine: client VM and server VM. These two systems are essentially two different just-in-time compilers interfacing with the same runtime system.

Client VM. This implementation is installed on platforms that are typically used for client, or desktop, applications. The client VM is tuned to reduce startup time and memory footprint. It is invoked by using the -client command-line option when launching an application.
Server VM. This implementation is installed on all platforms. The server VM is designed for maximum program execution speed. It is invoked by using the -server command-line option when launching an application.

The default implementation depends on the platform and the class of the machine.

More information on the Java Hotspot VM can be found at the following locations:

Who Should Use This Guide

The target audience for this document comprises developers who are working with JDK 7, as well as support or administration personnel who maintain applications that are deployed with JDK 7.

This document is intended for readers with a high-level understanding of the components of the Java Virtual Machine, as well as some understanding of concepts such as garbage collection, threads, native libraries, and so on. In addition, it is assumed that the reader is reasonably proficient on the operating system where the Java application is installed.

How This Guide Is Organized

The first chapter of this document introduces the various diagnostic and monitoring tools, utilities, options, and system properties that are available for troubleshooting in JDK 7. The chapter also provides a summary of tools and options by category. Note that tool availability depends on the platform: Solaris Operating System (Solaris OS), Linux, or Windows. Read this chapter to get acquainted with the capabilities of the utilities and options that are available.

The second chapter describes the troubleshooting tools in detail. The chapter also provides a list of the operating system tools and utilities that may be used in conjunction with the JDK utilities and options. Finally, the chapter describes in detail how you can develop new tools using the APIs provided in the JDK.

The third through fifth chapters suggest procedures to try when you encounter a problem with memory leaks, crashes, or hangs.

The sixth chapter deals with applications that use signal handlers.

The last chapter provides suggestions on what to try before submitting a bug report, guidance on how to submit a report, and suggestions on what data to collect for the report.

Finally, there is an appendix for each of the following reference areas: environment variables, command line options, details about the format of the fatal error report, and a list of tools in this release.

Feedback and Suggestions

Troubleshooting is a very important topic. If you have feedback on this document or if you have suggestions for topics that could be covered in a future version, please send your comments.

Other Resources

Troubleshooting information for J2SE 1.5 is described in the Java 2 Platform, Standard Edition 5.0, Troubleshooting and Diagnostic Guide.

In addition, the following online troubleshooting resources are available:

The article Monitoring and Managing Java SE 6 Platform Applications describes the most common problems in Java applications and suggests how to use several tools for troubleshooting these problems.
The article Troubleshooting Java SE 6 Deployment explores several ways to troubleshoot running Java applications, with examples.
The Java Tuning White Paper provides performance tuning information, techniques, and pointers for the Java programming language.
The Documentation for the Java HotSpot VM provides information about performance tuning of the Java HotSpot virtual machine, including garbage collection tuning.
The Java Plug-in Guide provides troubleshooting FAQ as well as information on how to enable tracing when trying to diagnose issues with the Java Plug-in.
The Java Web Start FAQ has a troubleshooting section dealing with issues that might arise with Java Web Start.
The bug database can be a useful resource to search for problems and solutions.
The Solaris Operating System Freeware site is the source for freeware that is packaged for the Solaris Operating System.
The Sunfreeware.com site (Freeware for Solaris) explains how to download freeware that is packaged for the Solaris Operating System.
The OpenSolaris site is the principle open source community site for OpenSolaris technology.
The blastwave.org site supports a collective effort to assemble free software that can be automatically installed on a Solaris computer.

Community Support

Community support can often be obtained using the Java Technology Forums. The forums provide a way to share information and locate solutions to problems. The forums are located at http://forums.oracle.com/forums/category.jspa?categoryID=285.

Typographic Conventions

The following table describes the typographic conventions that are used in this book.

Typographic Conventions

Typeface	Meaning	Example
`AaBbCc123`	The names of commands, files, and directories, and onscreen computer output	Edit your `.login` file. Use `ls -a` to list all files. `machine_name% you have mail.`
`AaBbCc123`	What you type, contrasted with onscreen computer output	`machine_name%` `su` `Password:`
`aabbcc123`	Placeholder: replace with a real name or value	The command to remove a file is `rm` `filename`.
AaBbCc123	Book titles, new terms, and terms to be emphasized	Read Chapter 6 in the User's Guide. A cache is a copy that is stored locally. Do not save the file. Note: Some emphasized items appear bold online.

Shell Prompts in Command Examples

The following table shows the default UNIX system prompt and superuser prompt for shells that are included in the Solaris OS. Note that the default system prompt that is displayed in command examples varies, depending on the Solaris release.

Shell Prompts

Shell	Prompt
Bash shell, Korn shell, and Bourne shell	`$`
Bash shell, Korn shell, and Bourne shell for superuser	`#`
C shell	`machine_name%`
C shell for superuser	`machine_name#`

Related Third-Party Web Site References

Third-party URLs are referenced in this document and provide additional, related information.

Note - Oracle is not responsible for the availability of third-party web sites mentioned in this document. Oracle does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Oracle will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through such sites or resources.

Acknowledgments

Many people contributed technical expertise and other input to this guide: Alan Bateman (major contributor), Tim Bell (major contributor and reviewer), Stephen Bohne, Mandy Chung, Stuart Clements, Uday Dhanikonda (responsible engineering manager), Christine Dorffi, Daniel Fuchs, Jim Holmlund (major contributor and reviewer), David Holmes, Karen Kinnear, Peter LaPierre, James C. Lee, Antonia Lewis (writer), Teresa London, Srinivas Madishetty, Keith McGuigan, Kelly O'Hair, Coleen Phillimore, Leif Samuelsson, Bill Situ, A. Sundararajan, Jesse Suen, Adam Wisnewski.

Document History

The following table tracks the changes in version of this guide.

Version Date	Changes
December 2006	Original version.
January 2007	New feedback form.
May 2007	Minor corrections.
August 2007	Corrections to tool support by platform.
September 2007	Addition to `jmap` entry in Appendix D. Minor corrections and improvements.
November 2008	Addition of the Java VisualVM tool. Corrections to changed link locations.
June 2011	Updates for JDK 7.