View Javadoc
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      */
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      */
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      */
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      */
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      */
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      */
302     public void gc();
303 
304 }