--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.management/share/classes/java/lang/management/MemoryMXBean.java Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,304 @@
+/*
+ * 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();
+
+}