1 /*
2 * Copyright (c) 2003, 2020, 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 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();
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 * @deprecated Finalization has been deprecated for removal. See
211 * {@link java.lang.Object#finalize} for details.
212 *
213 * @return the approximate number objects for which finalization
214 * is pending. If this MemoryMXBean contains information about a JVM in
215 * which finalization has been disabled or removed, this method always
216 * returns zero.
217 */
218 @Deprecated(since="18")
219 public int getObjectPendingFinalizationCount();
220
221 /**
222 * Returns the current memory usage of the heap that
223 * is used for object allocation. The heap consists
224 * of one or more memory pools. The {@code used}
225 * and {@code committed} size of the returned memory
226 * usage is the sum of those values of all heap memory pools
227 * whereas the {@code init} and {@code max} size of the
228 * returned memory usage represents the setting of the heap
229 * memory which may not be the sum of those of all heap
230 * memory pools.
231 * <p>
232 * The amount of used memory in the returned memory usage
233 * is the amount of memory occupied by both live objects
234 * and garbage objects that have not been collected, if any.
235 *
236 * <p>
237 * <b>MBeanServer access</b>:<br>
238 * The mapped type of {@code MemoryUsage} is
239 * {@code CompositeData} with attributes as specified in
240 * {@link MemoryUsage#from MemoryUsage}.
241 *
242 * @return a {@link MemoryUsage} object representing
243 * the heap memory usage.
244 */
245 public MemoryUsage getHeapMemoryUsage();
246
247 /**
248 * Returns the current memory usage of non-heap memory that
249 * is used by the Java virtual machine.
250 * The non-heap memory consists of one or more memory pools.
251 * The {@code used} and {@code committed} size of the
252 * returned memory usage is the sum of those values of
253 * all non-heap memory pools whereas the {@code init}
254 * and {@code max} size of the returned memory usage
255 * represents the setting of the non-heap
256 * memory which may not be the sum of those of all non-heap
257 * memory pools.
258 *
259 * <p>
260 * <b>MBeanServer access</b>:<br>
261 * The mapped type of {@code MemoryUsage} is
262 * {@code CompositeData} with attributes as specified in
263 * {@link MemoryUsage#from MemoryUsage}.
264 *
265 * @return a {@link MemoryUsage} object representing
266 * the non-heap memory usage.
267 */
268 public MemoryUsage getNonHeapMemoryUsage();
269
270 /**
271 * Tests if verbose output for the memory system is enabled.
272 *
273 * @return {@code true} if verbose output for the memory
274 * system is enabled; {@code false} otherwise.
275 */
276 public boolean isVerbose();
277
278 /**
279 * Enables or disables verbose output for the memory
280 * system. The verbose output information and the output stream
281 * to which the verbose information is emitted are implementation
282 * dependent. Typically, a Java virtual machine implementation
283 * prints a message whenever it frees memory at garbage collection.
284 *
285 * <p>
286 * Each invocation of this method enables or disables verbose
287 * output globally.
288 *
289 * @param value {@code true} to enable verbose output;
290 * {@code false} to disable.
291 *
292 * @throws java.lang.SecurityException if a security manager
293 * exists and the caller does not have
294 * ManagementPermission("control").
295 */
296 public void setVerbose(boolean value);
297
298 /**
299 * Runs the garbage collector.
300 * The call <code>gc()</code> is effectively equivalent to the
301 * call:
302 * <blockquote><pre>
303 * System.gc()
304 * </pre></blockquote>
305 *
306 * @see java.lang.System#gc()
307 */
308 public void gc();
309
310 }