001 /*
002 * Copyright 2003-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.lang.management;
027
028 import javax.management.openmbean.CompositeData;
029
030 /**
031 * The management interface for the memory system of
032 * the Java virtual machine.
033 *
034 * <p> A Java virtual machine has a single instance of the implementation
035 * class of this interface. This instance implementing this interface is
036 * an <a href="ManagementFactory.html#MXBean">MXBean</a>
037 * that can be obtained by calling
038 * the {@link ManagementFactory#getMemoryMXBean} method or
039 * from the {@link ManagementFactory#getPlatformMBeanServer
040 * platform <tt>MBeanServer</tt>} method.
041 *
042 * <p>The <tt>ObjectName</tt> for uniquely identifying the MXBean for
043 * the memory system within an MBeanServer is:
044 * <blockquote>
045 * {@link ManagementFactory#MEMORY_MXBEAN_NAME
046 * <tt>java.lang:type=Memory</tt>}
047 * </blockquote>
048 *
049 * <h4> Memory </h4>
050 * The memory system of the Java virtual machine manages
051 * the following kinds of memory:
052 *
053 * <h4> 1. Heap </h4>
054 * The Java virtual machine has a <i>heap</i> that is the runtime
055 * data area from which memory for all class instances and arrays
056 * are allocated. It is created at the Java virtual machine start-up.
057 * Heap memory for objects is reclaimed by an automatic memory management
058 * system which is known as a <i>garbage collector</i>.
059 *
060 * <p>The heap may be of a fixed size or may be expanded and shrunk.
061 * The memory for the heap does not need to be contiguous.
062 *
063 * <h4> 2. Non-Heap Memory</h4>
064 * The Java virtual machine manages memory other than the heap
065 * (referred as <i>non-heap memory</i>).
066 *
067 * <p> The Java virtual machine has a <i>method area</i> that is shared
068 * among all threads.
069 * The method area belongs to non-heap memory. It stores per-class structures
070 * such as a runtime constant pool, field and method data, and the code for
071 * methods and constructors. It is created at the Java virtual machine
072 * start-up.
073 *
074 * <p> The method area is logically part of the heap but a Java virtual
075 * machine implementation may choose not to either garbage collect
076 * or compact it. Similar to the heap, the method area may be of a
077 * fixed size or may be expanded and shrunk. The memory for the
078 * method area does not need to be contiguous.
079 *
080 * <p>In addition to the method area, a Java virtual machine
081 * implementation may require memory for internal processing or
082 * optimization which also belongs to non-heap memory.
083 * For example, the JIT compiler requires memory for storing the native
084 * machine code translated from the Java virtual machine code for
085 * high performance.
086 *
087 * <h4>Memory Pools and Memory Managers</h4>
088 * {@link MemoryPoolMXBean Memory pools} and
089 * {@link MemoryManagerMXBean memory managers} are the abstract entities
090 * that monitor and manage the memory system
091 * of the Java virtual machine.
092 *
093 * <p>A memory pool represents a memory area that the Java virtual machine
094 * manages. The Java virtual machine has at least one memory pool
095 * and it may create or remove memory pools during execution.
096 * A memory pool can belong to either the heap or the non-heap memory.
097 *
098 * <p>A memory manager is responsible for managing one or more memory pools.
099 * The garbage collector is one type of memory manager responsible
100 * for reclaiming memory occupied by unreachable objects. A Java virtual
101 * machine may have one or more memory managers. It may
102 * add or remove memory managers during execution.
103 * A memory pool can be managed by more than one memory manager.
104 *
105 * <h4>Memory Usage Monitoring</h4>
106 *
107 * Memory usage is a very important monitoring attribute for the memory system.
108 * The memory usage, for example, could indicate:
109 * <ul>
110 * <li>the memory usage of an application,</li>
111 * <li>the workload being imposed on the automatic memory management system,</li>
112 * <li>potential memory leakage.</li>
113 * </ul>
114 *
115 * <p>
116 * The memory usage can be monitored in three ways:
117 * <ul>
118 * <li>Polling</li>
119 * <li>Usage Threshold Notification</li>
120 * <li>Collection Usage Threshold Notification</li>
121 * </ul>
122 *
123 * Details are specified in the {@link MemoryPoolMXBean} interface.
124 *
125 * <p>The memory usage monitoring mechanism is intended for load-balancing
126 * or workload distribution use. For example, an application would stop
127 * receiving any new workload when its memory usage exceeds a
128 * certain threshold. It is not intended for an application to detect
129 * and recover from a low memory condition.
130 *
131 * <h4>Notifications</h4>
132 *
133 * <p>This <tt>MemoryMXBean</tt> is a
134 * {@link javax.management.NotificationEmitter NotificationEmitter}
135 * that emits two types of memory {@link javax.management.Notification
136 * notifications} if any one of the memory pools
137 * supports a <a href="MemoryPoolMXBean.html#UsageThreshold">usage threshold</a>
138 * or a <a href="MemoryPoolMXBean.html#CollectionThreshold">collection usage
139 * threshold</a> which can be determined by calling the
140 * {@link MemoryPoolMXBean#isUsageThresholdSupported} and
141 * {@link MemoryPoolMXBean#isCollectionUsageThresholdSupported} methods.
142 * <ul>
143 * <li>{@link MemoryNotificationInfo#MEMORY_THRESHOLD_EXCEEDED
144 * usage threshold exceeded notification} - for notifying that
145 * the memory usage of a memory pool is increased and has reached
146 * or exceeded its
147 * <a href="MemoryPoolMXBean.html#UsageThreshold"> usage threshold</a> value.
148 * </li>
149 * <li>{@link MemoryNotificationInfo#MEMORY_COLLECTION_THRESHOLD_EXCEEDED
150 * collection usage threshold exceeded notification} - for notifying that
151 * the memory usage of a memory pool is greater than or equal to its
152 * <a href="MemoryPoolMXBean.html#CollectionThreshold">
153 * collection usage threshold</a> after the Java virtual machine
154 * has expended effort in recycling unused objects in that
155 * memory pool.</li>
156 * </ul>
157 *
158 * <p>
159 * The notification emitted is a {@link javax.management.Notification}
160 * instance whose {@link javax.management.Notification#setUserData
161 * user data} is set to a {@link CompositeData CompositeData}
162 * that represents a {@link MemoryNotificationInfo} object
163 * containing information about the memory pool when the notification
164 * was constructed. The <tt>CompositeData</tt> contains the attributes
165 * as described in {@link MemoryNotificationInfo#from
166 * MemoryNotificationInfo}.
167 *
168 * <hr>
169 * <h4>NotificationEmitter</h4>
170 * The <tt>MemoryMXBean</tt> object returned by
171 * {@link ManagementFactory#getMemoryMXBean} implements
172 * the {@link javax.management.NotificationEmitter NotificationEmitter}
173 * interface that allows a listener to be registered within the
174 * <tt>MemoryMXBean</tt> as a notification listener.
175 *
176 * Below is an example code that registers a <tt>MyListener</tt> to handle
177 * notification emitted by the <tt>MemoryMXBean</tt>.
178 *
179 * <blockquote><pre>
180 * class MyListener implements javax.management.NotificationListener {
181 * public void handleNotification(Notification notif, Object handback) {
182 * // handle notification
183 * ....
184 * }
185 * }
186 *
187 * MemoryMXBean mbean = ManagementFactory.getMemoryMXBean();
188 * NotificationEmitter emitter = (NotificationEmitter) mbean;
189 * MyListener listener = new MyListener();
190 * emitter.addNotificationListener(listener, null, null);
191 * </pre></blockquote>
192 *
193 * @see <a href="../../../javax/management/package-summary.html">
194 * JMX Specification.</a>
195 * @see <a href="package-summary.html#examples">
196 * Ways to Access MXBeans</a>
197 *
198 * @author Mandy Chung
199 * @version 1.22, 05/05/07
200 * @since 1.5
201 */
202 public interface MemoryMXBean {
203 /**
204 * Returns the approximate number of objects for which
205 * finalization is pending.
206 *
207 * @return the approximate number objects for which finalization
208 * is pending.
209 */
210 public int getObjectPendingFinalizationCount();
211
212 /**
213 * Returns the current memory usage of the heap that
214 * is used for object allocation. The heap consists
215 * of one or more memory pools. The <tt>used</tt>
216 * and <tt>committed</tt> size of the returned memory
217 * usage is the sum of those values of all heap memory pools
218 * whereas the <tt>init</tt> and <tt>max</tt> size of the
219 * returned memory usage represents the setting of the heap
220 * memory which may not be the sum of those of all heap
221 * memory pools.
222 * <p>
223 * The amount of used memory in the returned memory usage
224 * is the amount of memory occupied by both live objects
225 * and garbage objects that have not been collected, if any.
226 *
227 * <p>
228 * <b>MBeanServer access</b>:<br>
229 * The mapped type of <tt>MemoryUsage</tt> is
230 * <tt>CompositeData</tt> with attributes as specified in
231 * {@link MemoryUsage#from MemoryUsage}.
232 *
233 * @return a {@link MemoryUsage} object representing
234 * the heap memory usage.
235 */
236 public MemoryUsage getHeapMemoryUsage();
237
238 /**
239 * Returns the current memory usage of non-heap memory that
240 * is used by the Java virtual machine.
241 * The non-heap memory consists of one or more memory pools.
242 * The <tt>used</tt> and <tt>committed</tt> size of the
243 * returned memory usage is the sum of those values of
244 * all non-heap memory pools whereas the <tt>init</tt>
245 * and <tt>max</tt> size of the returned memory usage
246 * represents the setting of the non-heap
247 * memory which may not be the sum of those of all non-heap
248 * memory pools.
249 *
250 * <p>
251 * <b>MBeanServer access</b>:<br>
252 * The mapped type of <tt>MemoryUsage</tt> is
253 * <tt>CompositeData</tt> with attributes as specified in
254 * {@link MemoryUsage#from MemoryUsage}.
255 *
256 * @return a {@link MemoryUsage} object representing
257 * the non-heap memory usage.
258 */
259 public MemoryUsage getNonHeapMemoryUsage();
260
261 /**
262 * Tests if verbose output for the memory system is enabled.
263 *
264 * @return <tt>true</tt> if verbose output for the memory
265 * system is enabled; <tt>false</tt> otherwise.
266 */
267 public boolean isVerbose();
268
269 /**
270 * Enables or disables verbose output for the memory
271 * system. The verbose output information and the output stream
272 * to which the verbose information is emitted are implementation
273 * dependent. Typically, a Java virtual machine implementation
274 * prints a message whenever it frees memory at garbage collection.
275 *
276 * <p>
277 * Each invocation of this method enables or disables verbose
278 * output globally.
279 *
280 * @param value <tt>true</tt> to enable verbose output;
281 * <tt>false</tt> to disable.
282 *
283 * @exception java.lang.SecurityException if a security manager
284 * exists and the caller does not have
285 * ManagementPermission("control").
286 */
287 public void setVerbose(boolean value);
288
289 /**
290 * Runs the garbage collector.
291 * The call <code>gc()</code> is effectively equivalent to the
292 * call:
293 * <blockquote><pre>
294 * System.gc()
295 * </pre></blockquote>
296 *
297 * @see java.lang.System#gc()
298 */
299 public void gc();
300
301 }
|