1 /*
2 * Copyright (c) 2005, 2008, 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.lang.management.PlatformManagedObject;
29
30 /**
31 * Diagnostic management interface for the HotSpot Virtual Machine.
32 * The diagnostic MBean is registered to the platform MBeanServer
33 * as are other platform MBeans.
34 *
35 * <p>The <tt>ObjectName</tt> for uniquely identifying the diagnostic
36 * MXBean within an MBeanServer is:
37 * <blockquote>
38 * <tt>com.sun.management:type=HotSpotDiagnostic</tt>
39 * </blockquote>
40 .*
41 * It can be obtained by calling the
42 * {@link PlatformManagedObject#getObjectName} method.
43 *
44 * @see ManagementFactory#getPlatformMXBeans(Class)
45 */
46 public interface HotSpotDiagnosticMXBean extends PlatformManagedObject {
47 /**
48 * Dumps the heap to the <tt>outputFile</tt> file in the same
49 * format as the hprof heap dump.
50 * <p>
51 * If this method is called remotely from another process,
52 * the heap dump output is written to a file named <tt>outputFile</tt>
53 * on the machine where the target VM is running. If outputFile is
54 * a relative path, it is relative to the working directory where
55 * the target VM was started.
56 *
57 * @param outputFile the system-dependent filename
58 * @param live if <tt>true</tt> dump only <i>live</i> objects
59 * i.e. objects that are reachable from others
60 * @throws IOException if the <tt>outputFile</tt>
61 * cannot be created, opened, or written to.
62 * @throws UnsupportedOperationException if this operation is not supported.
63 * @throws NullPointerException if <tt>outputFile</tt> is <tt>null</tt>.
84 * does not exist.
85 */
86 public VMOption getVMOption(String name);
87
88 /**
89 * Sets a VM option of the given name to the specified value.
90 * The new value will be reflected in a new <tt>VMOption</tt>
91 * object returned by the {@link #getVMOption} method or
92 * the {@link #getDiagnosticOptions} method. This method does
93 * not change the value of this <tt>VMOption</tt> object.
94 *
95 * @param name Name of a VM option
96 * @param value New value of the VM option to be set
97 *
98 * @throws IllegalArgumentException if the VM option of the given name
99 * does not exist.
100 * @throws IllegalArgumentException if the new value is invalid.
101 * @throws IllegalArgumentException if the VM option is not writeable.
102 * @throws NullPointerException if name or value is <tt>null</tt>.
103 *
104 * @throws java.security.SecurityException
105 * if a security manager exists and the caller does not have
106 * ManagementPermission("control").
107 */
108 public void setVMOption(String name, String value);
109 }
|
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 *
34 * <p>{@linkplain #getDiagnosticCommands Diagnostic commands}
35 * are actions that can be invoked dynamically and
36 * executed in a target Java virtual machine, mainly for troubleshooting
37 * and diagnosis.
38 *
39 * <p>The diagnostic MBean is registered to the platform MBeanServer
40 * as are other platform MBeans.
41 *
42 * <p>The <tt>ObjectName</tt> for uniquely identifying the diagnostic
43 * MXBean within an MBeanServer is:
44 * <blockquote>
45 * <tt>com.sun.management:type=HotSpotDiagnostic</tt>
46 * </blockquote>
47 .*
48 * It can be obtained by calling the
49 * {@link PlatformManagedObject#getObjectName} method.
50 *
51 * All methods throw a {@code NullPointerException} if any input argument is
52 * {@code null} unless it's stated otherwise.
53 *
54 * @see ManagementFactory#getPlatformMXBeans(Class)
55 */
56 public interface HotSpotDiagnosticMXBean extends PlatformManagedObject {
57 /**
58 * Dumps the heap to the <tt>outputFile</tt> file in the same
59 * format as the hprof heap dump.
60 * <p>
61 * If this method is called remotely from another process,
62 * the heap dump output is written to a file named <tt>outputFile</tt>
63 * on the machine where the target VM is running. If outputFile is
64 * a relative path, it is relative to the working directory where
65 * the target VM was started.
66 *
67 * @param outputFile the system-dependent filename
68 * @param live if <tt>true</tt> dump only <i>live</i> objects
69 * i.e. objects that are reachable from others
70 * @throws IOException if the <tt>outputFile</tt>
71 * cannot be created, opened, or written to.
72 * @throws UnsupportedOperationException if this operation is not supported.
73 * @throws NullPointerException if <tt>outputFile</tt> is <tt>null</tt>.
94 * does not exist.
95 */
96 public VMOption getVMOption(String name);
97
98 /**
99 * Sets a VM option of the given name to the specified value.
100 * The new value will be reflected in a new <tt>VMOption</tt>
101 * object returned by the {@link #getVMOption} method or
102 * the {@link #getDiagnosticOptions} method. This method does
103 * not change the value of this <tt>VMOption</tt> object.
104 *
105 * @param name Name of a VM option
106 * @param value New value of the VM option to be set
107 *
108 * @throws IllegalArgumentException if the VM option of the given name
109 * does not exist.
110 * @throws IllegalArgumentException if the new value is invalid.
111 * @throws IllegalArgumentException if the VM option is not writeable.
112 * @throws NullPointerException if name or value is <tt>null</tt>.
113 *
114 * @throws java.lang.SecurityException
115 * if a security manager exists and the caller does not have
116 * ManagementPermission("control").
117 */
118 public void setVMOption(String name, String value);
119
120 /**
121 * Returns the {@linkplain DiagnosticCommandInfo#getName() names}
122 * of all diagnostic commands.
123 * A diagnostic command is an action that can be invoked dynamically
124 * mainly for troubleshooting and diagnosis. The list of diagnostic
125 * commands may change at runtime. A diagnostic command may be
126 * {@linkplain DiagnosticCommandInfo#isEnabled disabled} but will
127 * not be removed from a previously returned list.
128 *
129 * @return the names of all diagnostic commands.
130 *
131 * @since 7u4
132 */
133 public List<String> getDiagnosticCommands();
134
135 /**
136 * Returns a {@code DiagnosticCommandInfo} object describing the
137 * diagnostic command of the specified name {@code command}
138 *
139 * @param command a diagnostic command name
140 * @return a {@code DiagnosticCommandInfo} object
141 * @throws java.lang.IllegalArgumentException if the {@code command}
142 * doesn't match any diagnostic command registered in the
143 * targeted Java virtual machine.
144 *
145 * @since 7u4
146 */
147 public DiagnosticCommandInfo getDiagnosticCommandInfo(String command);
148
149 /**
150 * Returns a list of {@code DiagnosticCommandInfo} object describing
151 * all diagnostic commands available on the targeted Java virtual machine
152 *
153 * @return a list of {@code DiagnosticCommandInfo} objects
154 *
155 * @since 7u4
156 */
157 public List<DiagnosticCommandInfo> getDiagnosticCommandInfo();
158
159 /**
160 * Returns a list of {@code DiagnosticCommandInfo} object describing
161 * all diagnostic commands specified in the {@code commands} list.
162 *
163 * @param commands {@code List} of {@code String} containing diagnostic
164 * command names
165 * @return a {@code List} of {@code DiagnosticCommandInfo} objects
166 *
167 * @throws java.lang.IllegalArgumentException if at least one
168 * command specified in the {@code commands } list
169 * doesn't match any diagnostic command registered in the
170 * targeted Java virtual machine.
171 *
172 * @since 7u4
173 */
174 public List<DiagnosticCommandInfo> getDiagnosticCommandInfo(List<String> commands);
175
176 /**
177 * Executes the command line {@code commandLine}. The command line must
178 * start with a diagnostic command name, optionally followed by parameters.
179 * Each command has its own syntax but the generic syntax for a diagnostic
180 * command line is:
181 * <blockquote>
182 * <command name> [<option>=<value>] [<argument_value>]
183 * </blockquote>
184 *
185 * @param commandLine command line to execute
186 * @return a {@code String} object containing the diagnostic command
187 * output.
188 *
189 * @throws java.lang.IllegalArgumentException if the command line doesn't
190 * match any diagnostic command registered in the virtual machine
191 * of if the parameters don't match the diagnostic command syntax.
192 * @throws java.lang.SecurityException
193 * if a security manager exists and the caller does not have
194 * ManagementPermission("control").
195 *
196 * @since 7u4
197 */
198 public String execute(String commandLine);
199
200 /**
201 * Invokes the diagnostic command named {@code cmd} with the parameters
202 * specified in {@code args}. Each command has its own syntax but
203 * the generic syntax for parameters is:
204 * <blockquote>
205 * [<option>=<value>] [<argument_value>]
206 * </blockquote>
207 *
208 * @param cmd a diagnostic command name
209 * @param args the command parameters
210 * @return a {@code String} object containing the diagnostic command
211 * output.
212 *
213 * @throws java.lang.IllegalArgumentException if the command line doesn't
214 * match any diagnostic command registered in the virtual machine
215 * of if the parameters don't match the diagnostic command syntax.
216 * @throws java.lang.SecurityException
217 * if a security manager exists and the caller does not have
218 * ManagementPermission("control").
219 *
220 * @since 7u4
221 */
222 public String execute(String cmd, String... args);
223 }
|