1 /* 2 * Copyright (c) 2003, 2013, 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 java.lang.management; 27 28 import javax.management.openmbean.CompositeData; 29 30 /** 31 * The management interface for the memory system of 32 * the Java virtual machine. 33 * 34 * <p> A Java virtual machine has a single instance of the implementation 35 * class of this interface. This instance implementing this interface is 36 * an <a href="ManagementFactory.html#MXBean">MXBean</a> 37 * that can be obtained by calling 38 * the {@link ManagementFactory#getMemoryMXBean} method or 39 * from the {@link ManagementFactory#getPlatformMBeanServer 40 * platform <tt>MBeanServer</tt>} method. 41 * 42 * <p>The <tt>ObjectName</tt> for uniquely identifying the MXBean for 43 * the memory system within an MBeanServer is: 44 * <blockquote> 45 * {@link ManagementFactory#MEMORY_MXBEAN_NAME 46 * <tt>java.lang:type=Memory</tt>} 47 * </blockquote> 48 * 49 * It can be obtained by calling the 50 * {@link PlatformManagedObject#getObjectName} method. 51 * 52 * <h3> Memory </h3> 53 * The memory system of the Java virtual machine manages 54 * the following kinds of memory: 55 * 56 * <h3> 1. Heap </h3> 57 * The Java virtual machine has a <i>heap</i> that is the runtime 58 * data area from which memory for all class instances and arrays 59 * are allocated. It is created at the Java virtual machine start-up. 60 * Heap memory for objects is reclaimed by an automatic memory management 61 * system which is known as a <i>garbage collector</i>. 62 * 63 * <p>The heap may be of a fixed size or may be expanded and shrunk. 64 * The memory for the heap does not need to be contiguous. 65 * 66 * <h3> 2. Non-Heap Memory</h3> 67 * The Java virtual machine manages memory other than the heap 68 * (referred as <i>non-heap memory</i>). 69 * 70 * <p> The Java virtual machine has a <i>method area</i> that is shared 71 * among all threads. 72 * The method area belongs to non-heap memory. It stores per-class structures 73 * such as a runtime constant pool, field and method data, and the code for 74 * methods and constructors. It is created at the Java virtual machine 75 * start-up. 76 * 77 * <p> The method area is logically part of the heap but a Java virtual 78 * machine implementation may choose not to either garbage collect 79 * or compact it. Similar to the heap, the method area may be of a 80 * fixed size or may be expanded and shrunk. The memory for the 81 * method area does not need to be contiguous. 82 * 83 * <p>In addition to the method area, a Java virtual machine 84 * implementation may require memory for internal processing or 85 * optimization which also belongs to non-heap memory. 86 * For example, the JIT compiler requires memory for storing the native 87 * machine code translated from the Java virtual machine code for 88 * high performance. 89 * 90 * <h3>Memory Pools and Memory Managers</h3> 91 * {@link MemoryPoolMXBean Memory pools} and 92 * {@link MemoryManagerMXBean memory managers} are the abstract entities 93 * that monitor and manage the memory system 94 * of the Java virtual machine. 95 * 96 * <p>A memory pool represents a memory area that the Java virtual machine 97 * manages. The Java virtual machine has at least one memory pool 98 * and it may create or remove memory pools during execution. 99 * A memory pool can belong to either the heap or the non-heap memory. 100 * 101 * <p>A memory manager is responsible for managing one or more memory pools. 102 * The garbage collector is one type of memory manager responsible 103 * for reclaiming memory occupied by unreachable objects. A Java virtual 104 * machine may have one or more memory managers. It may 105 * add or remove memory managers during execution. 106 * A memory pool can be managed by more than one memory manager. 107 * 108 * <h3>Memory Usage Monitoring</h3> 109 * 110 * Memory usage is a very important monitoring attribute for the memory system. 111 * The memory usage, for example, could indicate: 112 * <ul> 113 * <li>the memory usage of an application,</li> 114 * <li>the workload being imposed on the automatic memory management system,</li> 115 * <li>potential memory leakage.</li> 116 * </ul> 117 * 118 * <p> 119 * The memory usage can be monitored in three ways: 120 * <ul> 121 * <li>Polling</li> 122 * <li>Usage Threshold Notification</li> 123 * <li>Collection Usage Threshold Notification</li> 124 * </ul> 125 * 126 * Details are specified in the {@link MemoryPoolMXBean} interface. 127 * 128 * <p>The memory usage monitoring mechanism is intended for load-balancing 129 * or workload distribution use. For example, an application would stop 130 * receiving any new workload when its memory usage exceeds a 131 * certain threshold. It is not intended for an application to detect 132 * and recover from a low memory condition. 133 * 134 * <h3>Notifications</h3> 135 * 136 * <p>This <tt>MemoryMXBean</tt> is a 137 * {@link javax.management.NotificationEmitter NotificationEmitter} 138 * that emits two types of memory {@link javax.management.Notification 139 * notifications} if any one of the memory pools 140 * supports a <a href="MemoryPoolMXBean.html#UsageThreshold">usage threshold</a> 141 * or a <a href="MemoryPoolMXBean.html#CollectionThreshold">collection usage 142 * threshold</a> which can be determined by calling the 143 * {@link MemoryPoolMXBean#isUsageThresholdSupported} and 144 * {@link MemoryPoolMXBean#isCollectionUsageThresholdSupported} methods. 145 * <ul> 146 * <li>{@link MemoryNotificationInfo#MEMORY_THRESHOLD_EXCEEDED 147 * usage threshold exceeded notification} - for notifying that 148 * the memory usage of a memory pool is increased and has reached 149 * or exceeded its 150 * <a href="MemoryPoolMXBean.html#UsageThreshold"> usage threshold</a> value. 151 * </li> 152 * <li>{@link MemoryNotificationInfo#MEMORY_COLLECTION_THRESHOLD_EXCEEDED 153 * collection usage threshold exceeded notification} - for notifying that 154 * the memory usage of a memory pool is greater than or equal to its 155 * <a href="MemoryPoolMXBean.html#CollectionThreshold"> 156 * collection usage threshold</a> after the Java virtual machine 157 * has expended effort in recycling unused objects in that 158 * memory pool.</li> 159 * </ul> 160 * 161 * <p> 162 * The notification emitted is a {@link javax.management.Notification} 163 * instance whose {@link javax.management.Notification#setUserData 164 * user data} is set to a {@link CompositeData CompositeData} 165 * that represents a {@link MemoryNotificationInfo} object 166 * containing information about the memory pool when the notification 167 * was constructed. The <tt>CompositeData</tt> contains the attributes 168 * as described in {@link MemoryNotificationInfo#from 169 * MemoryNotificationInfo}. 170 * 171 * <hr> 172 * <h3>NotificationEmitter</h3> 173 * The <tt>MemoryMXBean</tt> object returned by 174 * {@link ManagementFactory#getMemoryMXBean} implements 175 * the {@link javax.management.NotificationEmitter NotificationEmitter} 176 * interface that allows a listener to be registered within the 177 * <tt>MemoryMXBean</tt> as a notification listener. 178 * 179 * Below is an example code that registers a <tt>MyListener</tt> to handle 180 * notification emitted by the <tt>MemoryMXBean</tt>. 181 * 182 * <blockquote><pre> 183 * class MyListener implements javax.management.NotificationListener { 184 * public void handleNotification(Notification notif, Object handback) { 185 * // handle notification 186 * .... 187 * } 188 * } 189 * 190 * MemoryMXBean mbean = ManagementFactory.getMemoryMXBean(); 191 * NotificationEmitter emitter = (NotificationEmitter) mbean; 192 * MyListener listener = new MyListener(); 193 * emitter.addNotificationListener(listener, null, null); 194 * </pre></blockquote> 195 * 196 * @see ManagementFactory#getPlatformMXBeans(Class) 197 * @see <a href="../../../javax/management/package-summary.html"> 198 * JMX Specification.</a> 199 * @see <a href="package-summary.html#examples"> 200 * Ways to Access MXBeans</a> 201 * 202 * @author Mandy Chung 203 * @since 1.5 204 */ 205 public interface MemoryMXBean extends PlatformManagedObject { 206 /** 207 * Returns the approximate number of objects for which 208 * finalization is pending. 209 * 210 * @return the approximate number objects for which finalization 211 * is pending. 212 */ getObjectPendingFinalizationCount()213 public int getObjectPendingFinalizationCount(); 214 215 /** 216 * Returns the current memory usage of the heap that 217 * is used for object allocation. The heap consists 218 * of one or more memory pools. The <tt>used</tt> 219 * and <tt>committed</tt> size of the returned memory 220 * usage is the sum of those values of all heap memory pools 221 * whereas the <tt>init</tt> and <tt>max</tt> size of the 222 * returned memory usage represents the setting of the heap 223 * memory which may not be the sum of those of all heap 224 * memory pools. 225 * <p> 226 * The amount of used memory in the returned memory usage 227 * is the amount of memory occupied by both live objects 228 * and garbage objects that have not been collected, if any. 229 * 230 * <p> 231 * <b>MBeanServer access</b>:<br> 232 * The mapped type of <tt>MemoryUsage</tt> is 233 * <tt>CompositeData</tt> with attributes as specified in 234 * {@link MemoryUsage#from MemoryUsage}. 235 * 236 * @return a {@link MemoryUsage} object representing 237 * the heap memory usage. 238 */ getHeapMemoryUsage()239 public MemoryUsage getHeapMemoryUsage(); 240 241 /** 242 * Returns the current memory usage of non-heap memory that 243 * is used by the Java virtual machine. 244 * The non-heap memory consists of one or more memory pools. 245 * The <tt>used</tt> and <tt>committed</tt> size of the 246 * returned memory usage is the sum of those values of 247 * all non-heap memory pools whereas the <tt>init</tt> 248 * and <tt>max</tt> size of the returned memory usage 249 * represents the setting of the non-heap 250 * memory which may not be the sum of those of all non-heap 251 * memory pools. 252 * 253 * <p> 254 * <b>MBeanServer access</b>:<br> 255 * The mapped type of <tt>MemoryUsage</tt> is 256 * <tt>CompositeData</tt> with attributes as specified in 257 * {@link MemoryUsage#from MemoryUsage}. 258 * 259 * @return a {@link MemoryUsage} object representing 260 * the non-heap memory usage. 261 */ getNonHeapMemoryUsage()262 public MemoryUsage getNonHeapMemoryUsage(); 263 264 /** 265 * Tests if verbose output for the memory system is enabled. 266 * 267 * @return <tt>true</tt> if verbose output for the memory 268 * system is enabled; <tt>false</tt> otherwise. 269 */ isVerbose()270 public boolean isVerbose(); 271 272 /** 273 * Enables or disables verbose output for the memory 274 * system. The verbose output information and the output stream 275 * to which the verbose information is emitted are implementation 276 * dependent. Typically, a Java virtual machine implementation 277 * prints a message whenever it frees memory at garbage collection. 278 * 279 * <p> 280 * Each invocation of this method enables or disables verbose 281 * output globally. 282 * 283 * @param value <tt>true</tt> to enable verbose output; 284 * <tt>false</tt> to disable. 285 * 286 * @exception java.lang.SecurityException if a security manager 287 * exists and the caller does not have 288 * ManagementPermission("control"). 289 */ setVerbose(boolean value)290 public void setVerbose(boolean value); 291 292 /** 293 * Runs the garbage collector. 294 * The call <code>gc()</code> is effectively equivalent to the 295 * call: 296 * <blockquote><pre> 297 * System.gc() 298 * </pre></blockquote> 299 * 300 * @see java.lang.System#gc() 301 */ gc()302 public void gc(); 303 304 } 305