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