2362N/A * Copyright (c) 2003, 2008, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * The management interface for the memory system of 0N/A * the Java virtual machine. 0N/A * <p> A Java virtual machine has a single instance of the implementation 0N/A * class of this interface. This instance implementing this interface is 0N/A * that can be obtained by calling 0N/A * the {@link ManagementFactory#getMemoryMXBean} method or 0N/A * from the {@link ManagementFactory#getPlatformMBeanServer 0N/A * platform <tt>MBeanServer</tt>} method. 0N/A * <p>The <tt>ObjectName</tt> for uniquely identifying the MXBean for 0N/A * the memory system within an MBeanServer is: 0N/A * {@link ManagementFactory#MEMORY_MXBEAN_NAME 0N/A * <tt>java.lang:type=Memory</tt>} 178N/A * It can be obtained by calling the 178N/A * {@link PlatformManagedObject#getObjectName} method. 0N/A * The memory system of the Java virtual machine manages 0N/A * the following kinds of memory: 0N/A * <h4> 1. Heap </h4> 0N/A * The Java virtual machine has a <i>heap</i> that is the runtime 0N/A * data area from which memory for all class instances and arrays 0N/A * are allocated. It is created at the Java virtual machine start-up. 0N/A * Heap memory for objects is reclaimed by an automatic memory management 0N/A * system which is known as a <i>garbage collector</i>. 0N/A * <p>The heap may be of a fixed size or may be expanded and shrunk. 0N/A * The memory for the heap does not need to be contiguous. 0N/A * <h4> 2. Non-Heap Memory</h4> 0N/A * The Java virtual machine manages memory other than the heap 0N/A * (referred as <i>non-heap memory</i>). 0N/A * <p> The Java virtual machine has a <i>method area</i> that is shared 0N/A * among all threads. 0N/A * The method area belongs to non-heap memory. It stores per-class structures 0N/A * such as a runtime constant pool, field and method data, and the code for 0N/A * methods and constructors. It is created at the Java virtual machine 0N/A * <p> The method area is logically part of the heap but a Java virtual 0N/A * machine implementation may choose not to either garbage collect 0N/A * or compact it. Similar to the heap, the method area may be of a 0N/A * fixed size or may be expanded and shrunk. The memory for the 0N/A * method area does not need to be contiguous. 0N/A * <p>In addition to the method area, a Java virtual machine 0N/A * implementation may require memory for internal processing or 0N/A * optimization which also belongs to non-heap memory. 0N/A * For example, the JIT compiler requires memory for storing the native 0N/A * machine code translated from the Java virtual machine code for 0N/A * <h4>Memory Pools and Memory Managers</h4> 0N/A * {@link MemoryPoolMXBean Memory pools} and 0N/A * {@link MemoryManagerMXBean memory managers} are the abstract entities 0N/A * that monitor and manage the memory system 0N/A * of the Java virtual machine. 0N/A * <p>A memory pool represents a memory area that the Java virtual machine 0N/A * manages. The Java virtual machine has at least one memory pool 0N/A * and it may create or remove memory pools during execution. 0N/A * A memory pool can belong to either the heap or the non-heap memory. 0N/A * <p>A memory manager is responsible for managing one or more memory pools. 0N/A * The garbage collector is one type of memory manager responsible 0N/A * for reclaiming memory occupied by unreachable objects. A Java virtual 0N/A * machine may have one or more memory managers. It may 0N/A * add or remove memory managers during execution. 0N/A * A memory pool can be managed by more than one memory manager. 0N/A * <h4>Memory Usage Monitoring</h4> 0N/A * Memory usage is a very important monitoring attribute for the memory system. 0N/A * The memory usage, for example, could indicate: 0N/A * <li>the memory usage of an application,</li> 0N/A * <li>the workload being imposed on the automatic memory management system,</li> 0N/A * <li>potential memory leakage.</li> 0N/A * The memory usage can be monitored in three ways: 0N/A * <li>Usage Threshold Notification</li> 0N/A * <li>Collection Usage Threshold Notification</li> 0N/A * Details are specified in the {@link MemoryPoolMXBean} interface. 0N/A * <p>The memory usage monitoring mechanism is intended for load-balancing 0N/A * or workload distribution use. For example, an application would stop 0N/A * receiving any new workload when its memory usage exceeds a 0N/A * certain threshold. It is not intended for an application to detect 0N/A * and recover from a low memory condition. 0N/A * <h4>Notifications</h4> 0N/A * <p>This <tt>MemoryMXBean</tt> is a 0N/A * {@link javax.management.NotificationEmitter NotificationEmitter} 0N/A * that emits two types of memory {@link javax.management.Notification 0N/A * notifications} if any one of the memory pools 0N/A * threshold</a> which can be determined by calling the 0N/A * {@link MemoryPoolMXBean#isUsageThresholdSupported} and 0N/A * {@link MemoryPoolMXBean#isCollectionUsageThresholdSupported} methods. 0N/A * <li>{@link MemoryNotificationInfo#MEMORY_THRESHOLD_EXCEEDED 0N/A * usage threshold exceeded notification} - for notifying that 0N/A * the memory usage of a memory pool is increased and has reached 0N/A * <li>{@link MemoryNotificationInfo#MEMORY_COLLECTION_THRESHOLD_EXCEEDED 0N/A * collection usage threshold exceeded notification} - for notifying that 0N/A * the memory usage of a memory pool is greater than or equal to its 0N/A * collection usage threshold</a> after the Java virtual machine 0N/A * has expended effort in recycling unused objects in that 0N/A * The notification emitted is a {@link javax.management.Notification} 0N/A * instance whose {@link javax.management.Notification#setUserData 0N/A * user data} is set to a {@link CompositeData CompositeData} 0N/A * that represents a {@link MemoryNotificationInfo} object 0N/A * containing information about the memory pool when the notification 0N/A * was constructed. The <tt>CompositeData</tt> contains the attributes 0N/A * as described in {@link MemoryNotificationInfo#from 0N/A * MemoryNotificationInfo}. 0N/A * <h4>NotificationEmitter</h4> 0N/A * The <tt>MemoryMXBean</tt> object returned by 0N/A * {@link ManagementFactory#getMemoryMXBean} implements 0N/A * the {@link javax.management.NotificationEmitter NotificationEmitter} 0N/A * interface that allows a listener to be registered within the 0N/A * <tt>MemoryMXBean</tt> as a notification listener. 0N/A * Below is an example code that registers a <tt>MyListener</tt> to handle 0N/A * notification emitted by the <tt>MemoryMXBean</tt>. 0N/A * class MyListener implements javax.management.NotificationListener { 0N/A * public void handleNotification(Notification notif, Object handback) { 0N/A * // handle notification 0N/A * MemoryMXBean mbean = ManagementFactory.getMemoryMXBean(); 0N/A * NotificationEmitter emitter = (NotificationEmitter) mbean; 0N/A * MyListener listener = new MyListener(); 0N/A * emitter.addNotificationListener(listener, null, null); 0N/A * </pre></blockquote> 178N/A * @see ManagementFactory#getPlatformMXBeans(Class) 0N/A * JMX Specification.</a> 0N/A * Ways to Access MXBeans</a> 0N/A * @author Mandy Chung 0N/A * Returns the approximate number of objects for which 0N/A * finalization is pending. 0N/A * @return the approximate number objects for which finalization 0N/A * Returns the current memory usage of the heap that 0N/A * is used for object allocation. The heap consists 0N/A * of one or more memory pools. The <tt>used</tt> 0N/A * and <tt>committed</tt> size of the returned memory 0N/A * usage is the sum of those values of all heap memory pools 0N/A * whereas the <tt>init</tt> and <tt>max</tt> size of the 0N/A * returned memory usage represents the setting of the heap 0N/A * memory which may not be the sum of those of all heap 0N/A * The amount of used memory in the returned memory usage 0N/A * is the amount of memory occupied by both live objects 0N/A * and garbage objects that have not been collected, if any. 0N/A * <b>MBeanServer access</b>:<br> 0N/A * The mapped type of <tt>MemoryUsage</tt> is 0N/A * <tt>CompositeData</tt> with attributes as specified in 0N/A * {@link MemoryUsage#from MemoryUsage}. 0N/A * @return a {@link MemoryUsage} object representing 0N/A * the heap memory usage. 0N/A * Returns the current memory usage of non-heap memory that 0N/A * is used by the Java virtual machine. 0N/A * The non-heap memory consists of one or more memory pools. 0N/A * The <tt>used</tt> and <tt>committed</tt> size of the 0N/A * returned memory usage is the sum of those values of 0N/A * all non-heap memory pools whereas the <tt>init</tt> 0N/A * and <tt>max</tt> size of the returned memory usage 0N/A * represents the setting of the non-heap 0N/A * memory which may not be the sum of those of all non-heap 0N/A * <b>MBeanServer access</b>:<br> 0N/A * The mapped type of <tt>MemoryUsage</tt> is 0N/A * <tt>CompositeData</tt> with attributes as specified in 0N/A * {@link MemoryUsage#from MemoryUsage}. 0N/A * @return a {@link MemoryUsage} object representing 0N/A * the non-heap memory usage. 0N/A * Tests if verbose output for the memory system is enabled. 0N/A * @return <tt>true</tt> if verbose output for the memory 0N/A * system is enabled; <tt>false</tt> otherwise. 0N/A * Enables or disables verbose output for the memory 0N/A * system. The verbose output information and the output stream 0N/A * to which the verbose information is emitted are implementation 0N/A * dependent. Typically, a Java virtual machine implementation 0N/A * prints a message whenever it frees memory at garbage collection. 0N/A * Each invocation of this method enables or disables verbose 0N/A * @param value <tt>true</tt> to enable verbose output; 0N/A * <tt>false</tt> to disable. 0N/A * @exception java.lang.SecurityException if a security manager 0N/A * exists and the caller does not have 0N/A * ManagementPermission("control"). 0N/A * Runs the garbage collector. 0N/A * The call <code>gc()</code> is effectively equivalent to the 0N/A * </pre></blockquote> 0N/A * @see java.lang.System#gc()