W3cubDocs

/OpenJDK 21

Interface HotSpotDiagnosticMXBean

All Superinterfaces:
PlatformManagedObject
public interface HotSpotDiagnosticMXBean extends PlatformManagedObject
Diagnostic management interface for the HotSpot Virtual Machine.

The diagnostic MBean is registered to the platform MBeanServer as are other platform MBeans.

The ObjectName for uniquely identifying the diagnostic MXBean within an MBeanServer is:

com.sun.management:type=HotSpotDiagnostic
It can be obtained by calling the PlatformManagedObject.getObjectName() method. All methods throw a NullPointerException if any input argument is null unless it's stated otherwise.
See Also:

Nested Class Summary

Modifier and Type Interface Description
static enum  HotSpotDiagnosticMXBean.ThreadDumpFormat
Thread dump format.

Method Summary

Modifier and Type Method Description
void dumpHeap(String outputFile, boolean live)
Dumps the heap to the outputFile file in the same format as the hprof heap dump.
default void dumpThreads(String outputFile, HotSpotDiagnosticMXBean.ThreadDumpFormat format)
Generate a thread dump to the given file in the given format.
List<VMOption> getDiagnosticOptions()
Returns a list of VMOption objects for all diagnostic options.
VMOption getVMOption(String name)
Returns a VMOption object for a VM option of the given name.
void setVMOption(String name, String value)
Sets a VM option of the given name to the specified value.

Methods declared in interface java.lang.management.PlatformManagedObject

getObjectName

Method Details

dumpHeap

void dumpHeap(String outputFile, boolean live) throws IOException
Dumps the heap to the outputFile file in the same format as the hprof heap dump.

If this method is called remotely from another process, the heap dump output is written to a file named outputFile on the machine where the target VM is running. If outputFile is a relative path, it is relative to the working directory where the target VM was started.

Parameters:
outputFile - the system-dependent filename
live - if true dump only live objects i.e. objects that are reachable from others
Throws:
IOException - if the outputFile already exists, cannot be created, opened, or written to.
UnsupportedOperationException - if this operation is not supported.
IllegalArgumentException - if outputFile does not end with ".hprof" suffix.
NullPointerException - if outputFile is null.
SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies write access to the named file or the caller does not have ManagmentPermission("control").

getDiagnosticOptions

List<VMOption> getDiagnosticOptions()
Returns a list of VMOption objects for all diagnostic options. A diagnostic option is a writeable VM option that can be set dynamically mainly for troubleshooting and diagnosis.
Returns:
a list of VMOption objects for all diagnostic options.

getVMOption

VMOption getVMOption(String name)
Returns a VMOption object for a VM option of the given name.
Returns:
a VMOption object for a VM option of the given name.
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if a VM option of the given name does not exist.

setVMOption

void setVMOption(String name, String value)
Sets a VM option of the given name to the specified value. The new value will be reflected in a new VMOption object returned by the getVMOption(java.lang.String) method or the getDiagnosticOptions() method. This method does not change the value of this VMOption object.
Parameters:
name - Name of a VM option
value - New value of the VM option to be set
Throws:
IllegalArgumentException - if the VM option of the given name does not exist.
IllegalArgumentException - if the new value is invalid.
IllegalArgumentException - if the VM option is not writable.
NullPointerException - if name or value is null.
SecurityException - if a security manager exists and the caller does not have ManagementPermission("control").

dumpThreads

default void dumpThreads(String outputFile, HotSpotDiagnosticMXBean.ThreadDumpFormat format) throws IOException
Generate a thread dump to the given file in the given format. The outputFile parameter must be an absolute path to a file that does not exist.

The thread dump will include output for all platform threads. It may include output for some or all virtual threads.

API Note:
The output file is required to be an absolute path as the MXBean may be accessed remotely from a tool or program with a different current working directory.
Implementation Requirements:
The default implementation throws UnsupportedOperationException.
Parameters:
outputFile - the path to the file to create
format - the format to use
Throws:
IllegalArgumentException - if the file path is not absolute
IOException - if the file already exists or an I/O exception is thrown writing to the file
NullPointerException - if either parameter is null
SecurityException - if a security manager is set and its SecurityManager.checkWrite(java.lang.String) method denies write access to the file or ManagementPermission("control") is denied
UnsupportedOperationException - if this operation is not supported
Since:
21

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.management/com/sun/management/HotSpotDiagnosticMXBean.html