openj9.lang.management

Interface OpenJ9DiagnosticsMXBean

  • All Superinterfaces:
    java.lang.management.PlatformManagedObject


    public interface OpenJ9DiagnosticsMXBean
    extends java.lang.management.PlatformManagedObject

    This interface provides APIs to dynamically trigger dump agents. APIs are also available to configure dump options. This MXBean reuses the methods in com.ibm.jvm.Dump API

    Usage example for the OpenJ9DiagnosticsMXBean
     
       ...
       try {
          mxbeanName = new ObjectName("openj9.lang.management:type=OpenJ9Diagnostics");
       } catch (MalformedObjectNameException e) {
          // Exception Handling
       }
       try {
          MBeanServer mbeanServer = ManagementFactory.getPlatformMBeanServer();
          if (false == mbeanServer.isRegistered(mxbeanName)) {
             // OpenJ9DiagnosticsMXBean not registered
          }
          OpenJ9DiagnosticsMXBean diagBean = JMX.newMXBeanProxy(mbeanServer, mxbeanName, OpenJ9DiagnosticsMXBean.class);
       } catch (Exception e) {
          // Exception Handling
       }
     
     
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method and Description
      void resetDumpOptions()
      Reset the JVM dump options to the settings specified when the JVM was started removing any additional configuration done since then.
      void setDumpOptions(java.lang.String dumpOptions)
      This function sets options for the dump subsystem.
      java.lang.String triggerClassicHeapDump()
      This function triggers the heap dump agent and requests for a heap dump in CLASSIC format.
      void triggerDump(java.lang.String dumpAgent)
      This function triggers the specified dump agent.
      java.lang.String triggerDumpToFile(java.lang.String dumpAgent, java.lang.String fileNamePattern)
      This function triggers the specified dump agent.
      • Methods inherited from interface java.lang.management.PlatformManagedObject

        getObjectName
    • Method Detail

      • resetDumpOptions

        void resetDumpOptions()
                       throws ConfigurationUnavailableException
        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 ConfigurationUnavailableException if the dump configuration cannot be altered. If this occurs it will usually be because a dump event is currently being handled.
        Throws:
        ConfigurationUnavailableException - if the configuration cannot be changed because a dump is already in progress
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to change the dump settings
      • setDumpOptions

        void setDumpOptions(java.lang.String dumpOptions)
                     throws InvalidOptionException,
                            ConfigurationUnavailableException
        This function sets options for the dump subsystem. The dump option is passed in as a 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 OpenJ9 JVM. This method may throw a ConfigurationUnavailableException if the dump configuration cannot be altered.
        Parameters:
        dumpOptions - the options string to be set
        Throws:
        InvalidOptionException - if the specified dumpOptions cannot be set or is incorrect
        ConfigurationUnavailableException - if the configuration cannot be changed because a dump is already 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 dumpOptions is null
      • triggerDump

        void triggerDump(java.lang.String dumpAgent)
                  throws java.lang.IllegalArgumentException
        This function triggers the specified dump agent. Dump agents supported - java, snap, system and heap. A java dump is in a human-readable format, and summarizes the state of the JVM. The default heap dump format (a phd file) is not human-readable. 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 snap dump format is not human-readable and must be processed using the trace formatting tool supplied with the OpenJ9 JVM.
        Parameters:
        dumpAgent - the dump agent to be triggered
        Throws:
        java.lang.IllegalArgumentException - if the specified dump agent is invalid or unsupported by this method
        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
        java.lang.NullPointerException - if dumpAgent is null
      • triggerDumpToFile

        java.lang.String triggerDumpToFile(java.lang.String dumpAgent,
                                           java.lang.String fileNamePattern)
                                    throws java.lang.IllegalArgumentException,
                                           InvalidOptionException
        This function triggers the specified dump agent. Dump agents supported - java, snap, system and heap. 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 OpenJ9 JVM. A string containing the actual filename written to is returned. This may not be the same as the requested filename for several reasons:
        • null or the empty string was 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 filename 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:
        dumpAgent - the dump agent to be triggered
        fileNamePattern - the filename to write to, which may be null, empty or include replacement tokens
        Returns:
        the file name that the dump was actually written to
        Throws:
        InvalidOptionException - if the fileNamePattern was invalid
        java.lang.IllegalArgumentException - if the specified dump agent is invalid or unsupported by this method
        java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
        java.lang.NullPointerException - if dumpAgent is null
      • triggerClassicHeapDump

        java.lang.String triggerClassicHeapDump()
                                         throws InvalidOptionException
        This function triggers the heap dump agent and requests for a heap dump in CLASSIC format.
        Returns:
        The file name of the dump that was created
        Throws:
        InvalidOptionException - if the dump operation fails
        java.lang.RuntimeException - if the JVM 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

Copyright © 2003, 2018 IBM Corp. and others