1 /*
   2  * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package com.sun.management;
  27 
  28 import java.util.List;
  29 import java.lang.management.PlatformManagedObject;
  30 
  31 /**
  32  * Diagnostic management interface for the HotSpot Virtual Machine.
  33  * The diagnostic MBean is registered to the platform MBeanServer
  34  * as are other platform MBeans.
  35  *
  36  * Diagnostic commands are actions that can be invoked dynamically and
  37  * executed in a target Java virtual machine, mainly for troubleshooting
  38  * and diagnosis.
  39  *
  40  * <p>The <tt>ObjectName</tt> for uniquely identifying the diagnostic
  41  * MXBean within an MBeanServer is:
  42  * <blockquote>
  43  *    <tt>com.sun.management:type=HotSpotDiagnostic</tt>
  44  * </blockquote>
  45 .*
  46  * It can be obtained by calling the
  47  * {@link PlatformManagedObject#getObjectName} method.
  48  *
  49  * All methods throw a {@code NullPointerException} if any input argument is
  50  * {@code null} unless it's stated otherwise.
  51  *
  52  * @see ManagementFactory#getPlatformMXBeans(Class)
  53  */
  54 public interface HotSpotDiagnosticMXBean extends PlatformManagedObject {
  55     /**
  56      * Dumps the heap to the <tt>outputFile</tt> file in the same
  57      * format as the hprof heap dump.
  58      * <p>
  59      * If this method is called remotely from another process,
  60      * the heap dump output is written to a file named <tt>outputFile</tt>
  61      * on the machine where the target VM is running.  If outputFile is
  62      * a relative path, it is relative to the working directory where
  63      * the target VM was started.
  64      *
  65      * @param  outputFile the system-dependent filename
  66      * @param  live if <tt>true</tt> dump only <i>live</i> objects
  67      *         i.e. objects that are reachable from others
  68      * @throws IOException if the <tt>outputFile</tt>
  69      *                     cannot be created, opened, or written to.
  70      * @throws UnsupportedOperationException if this operation is not supported.
  71      * @throws NullPointerException if <tt>outputFile</tt> is <tt>null</tt>.
  72      */
  73     public void dumpHeap(String outputFile, boolean live) throws java.io.IOException;
  74 
  75     /**
  76      * Returns a list of <tt>VMOption</tt> objects for all diagnostic options.
  77      * A diagnostic option is a {@link VMOption#isWriteable writeable}
  78      * VM option that can be set dynamically mainly for troubleshooting
  79      * and diagnosis.
  80      *
  81      * @return a list of <tt>VMOption</tt> objects for all diagnostic options.
  82      */
  83     public java.util.List<VMOption> getDiagnosticOptions();
  84 
  85     /**
  86      * Returns a <tt>VMOption</tt> object for a VM option of the given
  87      * name.
  88      *
  89      * @return a <tt>VMOption</tt> object for a VM option of the given name.
  90      * @throws NullPointerException if name is <tt>null</tt>.
  91      * @throws IllegalArgumentException if a VM option of the given name
  92      *                                     does not exist.
  93      */
  94     public VMOption getVMOption(String name);
  95 
  96     /**
  97      * Sets a VM option of the given name to the specified value.
  98      * The new value will be reflected in a new <tt>VMOption</tt>
  99      * object returned by the {@link #getVMOption} method or
 100      * the {@link #getDiagnosticOptions} method.  This method does
 101      * not change the value of this <tt>VMOption</tt> object.
 102      *
 103      * @param name Name of a VM option
 104      * @param value New value of the VM option to be set
 105      *
 106      * @throws IllegalArgumentException if the VM option of the given name
 107      *                                     does not exist.
 108      * @throws IllegalArgumentException if the new value is invalid.
 109      * @throws IllegalArgumentException if the VM option is not writeable.
 110      * @throws NullPointerException if name or value is <tt>null</tt>.
 111      *
 112      * @throws  java.security.SecurityException
 113      *     if a security manager exists and the caller does not have
 114      *     ManagementPermission("control").
 115      */
 116     public void setVMOption(String name, String value);
 117 
 118     /**
 119      * Returns the {@linkplain DiagnosticCommandInfo#getName() names}
 120      * of all diagnostic commands.
 121      * A diagnostic command is an action that can be invoked dynamically
 122      * mainly for troubleshooting and diagnosis.
 123      *
 124      * @return the names of all diagnostic commands.
 125      *
 126      * @since 7u4
 127      */
 128     public List<String> getDiagnosticCommands();
 129 
 130     /**
 131      * Returns a {@code DiagnosticCommandInfo} object describing the
 132      * diagnostic command of the specified name {@code command}
 133      *
 134      * @param command a diagnostic command name
 135      * @return a {@code DiagnosticCommandInfo} object
 136      * @throws  java.lang.IllegalArgumentException if the {@code command}
 137      *          doesn't match any diagnostic command registered in the
 138      *          targeted Java virtual machine.
 139      *
 140      * @since 7u4
 141      */
 142     public DiagnosticCommandInfo getDiagnosticCommandInfo(String command);
 143 
 144     /**
 145      * Returns a list of {@code DiagnosticCommandInfo} object describing
 146      * all diagnostic commands available on the targeted Java virtual machine
 147      *
 148      * @return a list of {@code DiagnosticCommandInfo} objects
 149      *
 150      * @since 7u4
 151      */
 152     public List<DiagnosticCommandInfo> getDiagnosticCommandInfo();
 153 
 154     /**
 155      * Returns a list of {@code DiagnosticCommandInfo} object describing
 156      * all diagnostic commands specified in the {@code commands} list.
 157      *
 158      * @param commands {@code List} of {@code String} containing diagnostic
 159      *        command names
 160      * @return a {@code List} of {@code DiagnosticCommandInfo} objects
 161      *
 162      * @throws  java.lang.IllegalArgumentException if at least one
 163      *          command specified in the {@code commands } list
 164      *          doesn't match any diagnostic command registered in the
 165      *          targeted Java virtual machine.
 166      *
 167      *
 168      * @since 7u4
 169      */
 170     public List<DiagnosticCommandInfo> getDiagnosticCommandInfo(List<String> commands);
 171 
 172     /**
 173      * Execute the command line {@code commandLine}. The command line must
 174      * start with a diagnostic command name, optionally followed by parameters.
 175      * Each command has its own syntax but the generic syntax for a diagnostic
 176      * command line is:
 177      * <blockquote>
 178      *    &lt;command name&gt; [&lt;option&gt;=&lt;value&gt;] [&lt;argument_value&gt;]
 179      * </blockquote>
 180      *
 181      * @param commandLine command line to execute
 182      * @return a {@code String} object containing the diagnostic command
 183      *          output.
 184      *
 185      * @throws  java.lang.IllegalArgumentException if the command line doesn't
 186      *          match any diagnostic command registered in the virtual machine
 187      *          of if the parameters don't match the diagnostic command
 188      *          syntax.
 189      *
 190      * @since 7u4
 191      */
 192     public String execute(String commandLine);
 193 
 194     /**
 195      * Invoke the diagnostic command named {@code cmd} with the parameters
 196      * specified in {@code args}. Each command has its own syntax but
 197      * the generic syntax for parameters is:
 198      * <blockquote>
 199      *    [&lt;option&gt;=&lt;value&gt;] [&lt;argument_value&gt;]
 200      * </blockquote>
 201      *
 202      * @param cmd a diagnostic command name
 203      * @param args the command parameters
 204      * @return a {@code String} object containing the diagnostic command
 205      *          output.
 206      *
 207      * @throws  java.lang.IllegalArgumentException if the command line doesn't
 208      *          match any diagnostic command registered in the virtual machine
 209      *          of if the parameters don't match the diagnostic command
 210      *          syntax.
 211      *
 212      * @since 7u4
 213      */
 214     public String execute(String cmd, String... args);
 215 }