1 /*
  2  * Copyright (c) 2005, 2017, 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.io.IOException;
 29 import java.lang.management.PlatformManagedObject;
 30 
 31 /**
 32  * Diagnostic management interface for the HotSpot Virtual Machine.
 33  *
 34  * <p>The diagnostic MBean is registered to the platform MBeanServer
 35  * as are other platform MBeans.
 36  *
 37  * <p>The {@code ObjectName} for uniquely identifying the diagnostic
 38  * MXBean within an MBeanServer is:
 39  * <blockquote>
 40  *    {@code com.sun.management:type=HotSpotDiagnostic}
 41  * </blockquote>
 42 .*
 43  * It can be obtained by calling the
 44  * {@link PlatformManagedObject#getObjectName} method.
 45  *
 46  * All methods throw a {@code NullPointerException} if any input argument is
 47  * {@code null} unless it's stated otherwise.
 48  *
 49  * @see java.lang.management.ManagementFactory#getPlatformMXBeans(Class)
 50  */
 51 public interface HotSpotDiagnosticMXBean extends PlatformManagedObject {
 52     /**
 53      * Dumps the heap to the {@code outputFile} file in the same
 54      * format as the hprof heap dump.
 55      * <p>
 56      * If this method is called remotely from another process,
 57      * the heap dump output is written to a file named {@code outputFile}
 58      * on the machine where the target VM is running.  If outputFile is
 59      * a relative path, it is relative to the working directory where
 60      * the target VM was started.
 61      *
 62      * @param  outputFile the system-dependent filename
 63      * @param  live if {@code true} dump only <i>live</i> objects
 64      *         i.e. objects that are reachable from others
 65      * @throws IOException if the {@code outputFile} already exists,
 66      *                     cannot be created, opened, or written to.
 67      * @throws UnsupportedOperationException if this operation is not supported.
 68      * @throws IllegalArgumentException if {@code outputFile} does not end with ".hprof" suffix.
 69      * @throws NullPointerException if {@code outputFile} is {@code null}.
 70      * @throws SecurityException
 71      *         If a security manager exists and its {@link
 72      *         java.lang.SecurityManager#checkWrite(java.lang.String)}
 73      *         method denies write access to the named file
 74      *         or the caller does not have ManagmentPermission("control").
 75      */
 76     public void dumpHeap(String outputFile, boolean live) throws IOException;
 77 
 78     /**
 79      * Returns a list of {@code VMOption} objects for all diagnostic options.
 80      * A diagnostic option is a {@link VMOption#isWriteable writeable}
 81      * VM option that can be set dynamically mainly for troubleshooting
 82      * and diagnosis.
 83      *
 84      * @return a list of {@code VMOption} objects for all diagnostic options.
 85      */
 86     public java.util.List<VMOption> getDiagnosticOptions();
 87 
 88     /**
 89      * Returns a {@code VMOption} object for a VM option of the given
 90      * name.
 91      *
 92      * @return a {@code VMOption} object for a VM option of the given name.
 93      * @throws NullPointerException if name is {@code null}.
 94      * @throws IllegalArgumentException if a VM option of the given name
 95      *                                     does not exist.
 96      */
 97     public VMOption getVMOption(String name);
 98 
 99     /**
100      * Sets a VM option of the given name to the specified value.
101      * The new value will be reflected in a new {@code VMOption}
102      * object returned by the {@link #getVMOption} method or
103      * the {@link #getDiagnosticOptions} method.  This method does
104      * not change the value of this {@code VMOption} object.
105      *
106      * @param name Name of a VM option
107      * @param value New value of the VM option to be set
108      *
109      * @throws IllegalArgumentException if the VM option of the given name
110      *                                     does not exist.
111      * @throws IllegalArgumentException if the new value is invalid.
112      * @throws IllegalArgumentException if the VM option is not writable.
113      * @throws NullPointerException if name or value is {@code null}.
114      *
115      * @throws  java.lang.SecurityException
116      *     if a security manager exists and the caller does not have
117      *     ManagementPermission("control").
118      */
119     public void setVMOption(String name, String value);
120 }