public class Dump
extends java.lang.Object
-Xdump must be enabled on the command line or the functions that attempt to cause dumps to be created or set options will fail with a java.lang.RuntimeException.
The methods on this class can be used to trigger dumps, configure dump options and query those options.
The JavaDump()
, SystemDump()
, HeapDump()
and SnapDump()
methods trigger dumps of the given type with no options and no return value.
Although they are not configurable they do provide an easy API to use via reflection
if your code is likely to run on both OpenJ9 and non-OpenJ9 JVMs and you only need the most
basic ability to create a dump.
The javaDumpToFile()
, systemDumpToFile()
, heapDumpToFile()
and
snapDumpToFile()
methods allow a destination file to be optionally specified and
will return the full path of the file that is created.
The recommended usage of the javaDumpToFile()
, systemDumpToFile()
,
heapDumpToFile()
and snapDumpToFile()
methods is to call the no argument versions of these calls rather than specifying a file
name as this will trigger a dump to the default location. Your dump file will go to the
default location specified by any -Xdump options given to the JVM at startup time following
the user or administrators preferences.
The location the dump file was written to will be returned as a String so the generated
file can be located.
The triggerDump(String)
method offers similar functionality as the DumpToFile() methods
but with the ability to specify any dump options that are meaningful for a dump that occurs
immediately. The options are passed as a String that follows the same format as the option
strings passed to -Xdump on the command line.
For example:
The setDumpOptions(String)
method allows dump options that will cause or change how
a dump occurs for an event in the future to be specified. The options are specified in the
format expected by the -Xdump command line. Not all options can be configured at runtime and
this method will throw an InvalidDumpOption exception if it is passed an option that cannot be set.
For example:
The queryDumpOptions()
method returns a String array containing a snapshot of the currently
configured dump options. Each String is in the format expected by the -Xdump command line
option and setDumpOptions. The Strings can be passed back to setDumpOptions to recreate
the current dump agent configuration at a later time.
The resetDumpOptions()
method resets the dump options to the settings specified when the
JVM was started removing any additional configuration done since then.
If you wish to change the dump configuration at runtime and then reset it to an earlier
state that included additional runtime configuration done through this API or JVMTI you should
consider saving the result of queryDumpOptions and then later use setDumpOptions(String)
to restore that configuration after a call to setDumpOptions("none") to clear all dump agent
configuration.
Modifier and Type | Method and Description |
---|---|
static void |
HeapDump()
Trigger a heap dump.
|
static java.lang.String |
heapDumpToFile()
Trigger a heap dump.
|
static java.lang.String |
heapDumpToFile(java.lang.String fileNamePattern)
Trigger a heap dump.
|
static void |
JavaDump()
Trigger a java dump.
|
static java.lang.String |
javaDumpToFile()
Trigger a java dump.
|
static java.lang.String |
javaDumpToFile(java.lang.String fileNamePattern)
Trigger a java dump.
|
static java.lang.String[] |
queryDumpOptions()
Returns the current dump configuration as an array of Strings.
|
static void |
resetDumpOptions()
Reset the JVM dump options to the settings specified when the JVM
was started removing any additional configuration done since then.
|
static void |
setDumpOptions(java.lang.String dumpOptions)
Sets options for the dump subsystem.
|
static void |
SnapDump()
Trigger a snap dump.
|
static java.lang.String |
snapDumpToFile()
Trigger a snap dump.
|
static java.lang.String |
snapDumpToFile(java.lang.String fileNamePattern)
Trigger a snap dump.
|
static void |
SystemDump()
Trigger a system dump.
|
static java.lang.String |
systemDumpToFile()
Trigger a system dump.
|
static java.lang.String |
systemDumpToFile(java.lang.String fileNamePattern)
Trigger a system dump.
|
static java.lang.String |
triggerDump(java.lang.String dumpOptions)
Trigger a dump with the specified options.
|
public static void JavaDump()
java.lang.RuntimeException
- if the vm does not contain RAS dump supportjava.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumppublic static void HeapDump()
java.lang.RuntimeException
- if the vm does not contain RAS dump supportjava.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumppublic static void SystemDump()
java.lang.RuntimeException
- if the vm does not contain RAS dump supportjava.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumppublic static void SnapDump()
java.lang.RuntimeException
- if the vm does not contain RAS dump supportjava.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumppublic static java.lang.String javaDumpToFile(java.lang.String fileNamePattern) throws InvalidDumpOptionException
fileNamePattern
- the file name to write to, which may be null, empty or include replacement tokensInvalidDumpOptionException
- if the filename was invalidjava.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumppublic static java.lang.String javaDumpToFile()
java.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumppublic static java.lang.String heapDumpToFile(java.lang.String fileNamePattern) throws InvalidDumpOptionException
fileNamePattern
- the file name to write to, which may be null, empty or include replacement tokensInvalidDumpOptionException
- if the filename was invalidjava.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumppublic static java.lang.String heapDumpToFile()
java.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumppublic static java.lang.String systemDumpToFile(java.lang.String fileNamePattern) throws InvalidDumpOptionException
fileNamePattern
- the file name to write to, which may be null, empty or include replacement tokensInvalidDumpOptionException
- if the filename was invalidjava.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumppublic static java.lang.String systemDumpToFile()
java.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumppublic static java.lang.String snapDumpToFile(java.lang.String fileNamePattern) throws InvalidDumpOptionException
fileNamePattern
- the file name to write to, which may be null, empty or include replacement tokensInvalidDumpOptionException
- if the filename was invalidjava.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumppublic static java.lang.String snapDumpToFile()
java.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumppublic static java.lang.String triggerDump(java.lang.String dumpOptions) throws InvalidDumpOptionException
dumpOptions
- a dump settings stringjava.lang.RuntimeException
- if the vm does not contain RAS dump supportjava.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumpInvalidDumpOptionException
- If the dump options are invalid or the dump operation failsjava.lang.NullPointerException
- if dumpSettings is nullpublic static void setDumpOptions(java.lang.String dumpOptions) throws InvalidDumpOptionException, DumpConfigurationUnavailableException
dumpOptions
- the options string to setInvalidDumpOptionException
- if the specified option cannot be set or is incorrectDumpConfigurationUnavailableException
- If the dump configuration cannot be changed because a dump is currently in progressjava.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to change the dump settingsjava.lang.NullPointerException
- if options is nullpublic static java.lang.String[] queryDumpOptions()
java.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to read the dump settingspublic static void resetDumpOptions() throws DumpConfigurationUnavailableException
DumpConfigurationUnavailableException
- if the dump configuration cannot be changed because a dump is currently in progressjava.lang.SecurityException
- if there is a security manager and it doesn't allow the checks required to change the dump settingsEclipse OpenJ9 website.
To raise a bug report or suggest an improvement create an Eclipse OpenJ9 issue.
Copyright © 1998, 2023 IBM Corp. and others.