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 * <command name> [<option>=<value>] [<argument_value>] 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 * [<option>=<value>] [<argument_value>] 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 }