< prev index next >

src/java.management/share/classes/java/lang/management/MemoryMXBean.java

Print this page


   1 /*
   2  * Copyright (c) 2003, 2019, 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


  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 MBeanServer} method.
  41  *
  42  * <p>The {@code ObjectName} for uniquely identifying the MXBean for
  43  * the memory system within an MBeanServer is:
  44  * <blockquote>
  45  *    {@link ManagementFactory#MEMORY_MXBEAN_NAME
  46  *           java.lang:type=Memory}
  47  * </blockquote>
  48  *
  49  * It can be obtained by calling the
  50  * {@link PlatformManagedObject#getObjectName} method.
  51  *
  52  * <h2> Memory </h2>
  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  * <h2>Memory Pools and Memory Managers</h2>
  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  * <h2>Memory Usage Monitoring</h2>
 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  * <h2>Notifications</h2>
 135  *
 136  * <p>This {@code MemoryMXBean} 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 {@code CompositeData} contains the attributes
 168  * as described in {@link MemoryNotificationInfo#from
 169  * MemoryNotificationInfo}.
 170  *
 171  * <hr>
 172  * <h2>NotificationEmitter</h2>
 173  * The {@code MemoryMXBean} 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  * {@code MemoryMXBean} as a notification listener.
 178  *
 179  * Below is an example code that registers a {@code MyListener} to handle
 180  * notification emitted by the {@code MemoryMXBean}.
 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();


   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


  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 MBeanServer} method.
  41  *
  42  * <p>The {@code ObjectName} for uniquely identifying the MXBean for
  43  * the memory system within an MBeanServer is:
  44  * <blockquote>
  45  *    {@link ManagementFactory#MEMORY_MXBEAN_NAME
  46  *           java.lang:type=Memory}
  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 {@code MemoryMXBean} 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 {@code CompositeData} contains the attributes
 168  * as described in {@link MemoryNotificationInfo#from
 169  * MemoryNotificationInfo}.
 170  *
 171  * <hr>
 172  * <h3>NotificationEmitter</h3>
 173  * The {@code MemoryMXBean} 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  * {@code MemoryMXBean} as a notification listener.
 178  *
 179  * Below is an example code that registers a {@code MyListener} to handle
 180  * notification emitted by the {@code MemoryMXBean}.
 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();


< prev index next >