com.ibm.jvm

Class Dump

  • java.lang.Object
    • com.ibm.jvm.Dump


  • public class Dump
    extends java.lang.Object
    APIs used to cause RAS dumps. -Xdump must be enabled on the command line.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method and Description
      static void HeapDump()
      Cause a HeapDump to occur.
      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()
      Cause a JavaDump to occur.
      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 SystemDump to occur.
      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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • JavaDump

        public static void JavaDump()
        Cause a JavaDump to occur. A JavaDump is in a human-readable format, and summarizes the state of the JVM.
        Throws:
        java.lang.RuntimeException - if the vm does not contain RAS dump support
      • HeapDump

        public static void HeapDump()
        Cause a HeapDump to occur. The default HeapDump format (phd files) is not human-readable and must be processed using available tools.
        Throws:
        java.lang.RuntimeException - if the vm does not contain RAS dump support
      • SystemDump

        public static void SystemDump()
        Trigger a SystemDump to occur. A SystemDump is a platform-specific file that contains information about the active processes, threads, and system memory. System dumps are usually large.
        Throws:
        java.lang.RuntimeException - if the vm does not contain RAS dump support
      • SnapDump

        public static void SnapDump()
        Trigger a snap dump. The snap dump format is not human-readable and must be processed using the trace formatting tool supplied with the IBM JVM. A security manager check will be made only if the system property com.ibm.jvm.enableLegacyDumpSecurity is set to "true" in which case a check will be made for com.ibm.jvm.DumpPermission
        Throws:
        java.lang.RuntimeException - if the vm does not contain RAS dump support
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to take this dump
      • javaDumpToFile

        public static java.lang.String javaDumpToFile(java.lang.String fileNamePattern)
                                               throws InvalidDumpOptionException
        Trigger a java dump. A java dump is in a human-readable format, and summarizes the state of the JVM. The JVM will attempt to write the file to the specified file name. This may include replacement tokens as documented in the section on dump agents in the documentation for the IBM JVM. A string containing the actual file name written to is returned. This may not be the same as the requested filename for several reasons:
        • null or the empty string were specified, this will cause the JVM to write the dump to the default location based on the current dump settings and return that path.
        • Replacement (%) tokens were specified in the file name. These will have been expanded.
        • The full path is returned, if only a file name with no directory was specified the full path with the directory the dump was written to will be returned.
        • The JVM couldn't write to the specified location. In this case it will attempt to write the dump to another location, unless -Xdump:nofailover was specified on the command line.
        If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
        Parameters:
        fileNamePattern - the file name to write to, which may be null, empty or include replacement tokens
        Returns:
        the file name that the dump was actually written to
        Throws:
        InvalidDumpOptionException - if the filename was invalid
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
      • javaDumpToFile

        public static java.lang.String javaDumpToFile()
        Trigger a java dump. A java dump is in a human-readable format, and summarizes the state of the JVM. The JVM will attempt to write the file to the default location. A string containing the actual file name written to is returned. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
        Returns:
        the file name that the dump was actually written to
        Throws:
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
      • heapDumpToFile

        public static java.lang.String heapDumpToFile(java.lang.String fileNamePattern)
                                               throws InvalidDumpOptionException
        Trigger a heap dump. The default heap dump format (a phd file) is not human-readable. The JVM will attempt to write the file to the specified file name. This may include replacement tokens as documented in the section on dump agents in the documentation for the IBM JVM. A string containing the actual file name written to is returned. This may not be the same as the requested filename for several reasons:
        • null or the empty string were specified, this will cause the JVM to write the dump to the default location based on the current dump settings and return that path.
        • Replacement (%) tokens were specified in the file name. These will have been expanded.
        • The full path is returned, if only a file name with no directory was specified the full path with the directory the dump was written to will be returned.
        • The JVM couldn't write to the specified location. In this case it will attempt to write the dump to another location, unless -Xdump:nofailover was specified on the command line.
        If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
        Parameters:
        fileNamePattern - the file name to write to, which may be null, empty or include replacement tokens
        Returns:
        the file name that the dump was actually written to
        Throws:
        InvalidDumpOptionException - if the filename was invalid
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
      • heapDumpToFile

        public static java.lang.String heapDumpToFile()
        Trigger a heap dump. The default heap dump format (a phd file) is not human-readable. The JVM will attempt to write the file to the default location. A string containing the actual file name written to is returned. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
        Returns:
        the file name that the dump was actually written to
        Throws:
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
      • systemDumpToFile

        public static java.lang.String systemDumpToFile(java.lang.String fileNamePattern)
                                                 throws InvalidDumpOptionException
        Trigger a system dump. A system dump is a platform-specific file that contains information about the active processes, threads, and system memory. System dumps are usually large. The JVM will attempt to write the file to the specified file name. This may include replacement tokens as documented in the section on dump agents in the documentation for the IBM JVM. A string containing the actual file name written to is returned. This may not be the same as the requested filename for several reasons:
        • null or the empty string were specified, this will cause the JVM to write the dump to the default location based on the current dump settings and return that path.
        • Replacement (%) tokens were specified in the file name. These will have been expanded.
        • The full path is returned, if only a file name with no directory was specified the full path with the directory the dump was written to will be returned.
        • The JVM couldn't write to the specified location. In this case it will attempt to write the dump to another location, unless -Xdump:nofailover was specified on the command line.
        If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
        Parameters:
        fileNamePattern - the file name to write to, which may be null, empty or include replacement tokens
        Returns:
        the file name that the dump was actually written to
        Throws:
        InvalidDumpOptionException - if the filename was invalid
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
      • systemDumpToFile

        public static java.lang.String systemDumpToFile()
        Trigger a system dump. A system dump is a platform-specific file that contains information about the active processes, threads, and system memory. System dumps are usually large. The JVM will attempt to write the file to the default location. A string containing the actual file name written to is returned. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
        Returns:
        the file name that the dump was actually written to
        Throws:
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
      • snapDumpToFile

        public static java.lang.String snapDumpToFile(java.lang.String fileNamePattern)
                                               throws InvalidDumpOptionException
        Trigger a snap dump. The snap dump format is not human-readable and must be processed using the trace formatting tool supplied with the IBM JVM. The JVM will attempt to write the file to the specified file name. This may include replacement tokens as documented in the section on dump agents in the documentation for the IBM JVM. A string containing the actual file name written to is returned. This may not be the same as the requested filename for several reasons:
        • null or the empty string were specified, this will cause the JVM to write the dump to the default location based on the current dump settings and return that path.
        • Replacement (%) tokens were specified in the file name. These will have been expanded.
        • The full path is returned, if only a file name with no directory was specified the full path with the directory the dump was written to will be returned.
        • The JVM couldn't write to the specified location. In this case it will attempt to write the dump to another location, unless -Xdump:nofailover was specified on the command line.
        If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
        Parameters:
        fileNamePattern - the file name to write to, which may be null, empty or include replacement tokens
        Returns:
        the file name that the dump was actually written to
        Throws:
        InvalidDumpOptionException - if the filename was invalid
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
      • snapDumpToFile

        public static java.lang.String snapDumpToFile()
        Trigger a snap dump. The snap dump format is not human-readable and must be processed using the trace formatting tool supplied with the IBM JVM. The JVM will attempt to write the file to the default location. A string containing the actual file name written to is returned. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
        Returns:
        the file name that the dump was actually written to
        Throws:
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
      • triggerDump

        public static java.lang.String triggerDump(java.lang.String dumpOptions)
                                            throws InvalidDumpOptionException
        Trigger a dump with the specified options. This method will trigger a dump of the specified type, with the specified options, immediately. The dump type and options are specified using the same string parameters as the -Xdump flag as described in the section on dump agents in the documentation for the IBM JVM. Settings that do not apply to dumps that occur immediately ("range=", "priority=", "filter=", "events=", "none" and "defaults") will be ignored. The "opts=" setting is supported if an option is used that causes two dumps to occur only the filename for the first will be returned. If a filename is specified for the dump it may contain replacement strings as specified in the documentation. In addition if a dump cannot be created with the specified filename the JVM may attempt to write it to another location. For these reasons you should always use the file name that is returned from this function when looking for the dump rather than the name you supplied. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown. If a "tool" dump is requested an additional check for com.ibm.jvm.ToolDumpPermission will also be made.
        Parameters:
        dumpOptions - a dump settings string
        Returns:
        The file name of the dump that was created. The String "-" means the dump was written to stderr.
        Throws:
        java.lang.RuntimeException - if the vm does not contain RAS dump support
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
        InvalidDumpOptionException - If the dump options are invalid or the dump operation fails
        java.lang.NullPointerException - if dumpSettings is null
      • setDumpOptions

        public static void setDumpOptions(java.lang.String dumpOptions)
                                   throws InvalidDumpOptionException,
                                          DumpConfigurationUnavailableException
        Sets options for the dump subsystem. The dump option is passed in as an String. Use the same syntax as the -Xdump command-line option, with the initial -Xdump: omitted. See Using the -Xdump option as described in the section on dump agents in the documentation for the IBM JVM. This method may throw a DumpConfigurationUnavailableException if the dump configuration cannot be altered. If this occurs it will usually be because a dump event is currently being handled. As this can take some time depending on the dumps being generated an exception is thrown rather than this call blocking the calling thread potentially for minutes. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown. If a "tool" dump is specified an additional check for com.ibm.jvm.ToolDumpPermission will also be made.
        Parameters:
        dumpOptions - the options string to set
        Throws:
        InvalidDumpOptionException - if the specified option cannot be set or is incorrect
        DumpConfigurationUnavailableException - If the dump configuration cannot be changed because a dump is currently in progress
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to change the dump settings
        java.lang.NullPointerException - if options is null
      • queryDumpOptions

        public static java.lang.String[] queryDumpOptions()
        Returns the current dump configuration as an array of Strings. The syntax of the option Strings is the same as the -Xdump command-line option, with the initial -Xdump: omitted. See Using the -Xdump option in the section on dump agents in the documentation for the IBM JVM. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
        Returns:
        the options strings
        Throws:
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to read the dump settings
      • resetDumpOptions

        public static void resetDumpOptions()
                                     throws DumpConfigurationUnavailableException
        Reset the JVM dump options to the settings specified when the JVM was started removing any additional configuration done since then. This method may throw a DumpConfigurationUnavailableException if the dump configuration cannot be altered. If this occurs it will usually be because a dump event is currently being handled. As this can take some time depending on the dumps being generated an exception is thrown rather than this call blocking the calling thread potentially for minutes. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
        Throws:
        DumpConfigurationUnavailableException - if the dump configuration cannot be changed because a dump is currently in progress
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to change the dump settings

© Copyright 2003, 2015 IBM Corporation.