MemoryMXBean


1   /*
2    * @(#)MemoryMXBean.java    1.16 06/03/08
3    *
4    * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.lang.management;
9   
10  import javax.management.openmbean.CompositeData  ;
11  
12  /**
13   * The management interface for the memory system of
14   * the Java virtual machine.
15   *
16   * <p> A Java virtual machine has a single instance of the implementation
17   * class of this interface.  This instance implementing this interface is
18   * an <a HREF="ManagementFactory.html#MXBean">MXBean</a>
19   * that can be obtained by calling
20   * the {@link ManagementFactory#getMemoryMXBean} method or
21   * from the {@link ManagementFactory#getPlatformMBeanServer
22   * platform <tt>MBeanServer</tt>} method.
23   *
24   * <p>The <tt>ObjectName</tt> for uniquely identifying the MXBean for
25   * the memory system within an MBeanServer is:
26   * <blockquote>
27   *    {@link ManagementFactory#MEMORY_MXBEAN_NAME 
28   *           <tt>java.lang:type=Memory</tt>}
29   * </blockquote>
30   *
31   * <h4> Memory </h4>
32   * The memory system of the Java virtual machine manages 
33   * the following kinds of memory:
34   *
35   * <h4> 1. Heap </h4>
36   * The Java virtual machine has a <i>heap</i> that is the runtime
37   * data area from which memory for all class instances and arrays 
38   * are allocated.  It is created at the Java virtual machine start-up.
39   * Heap memory for objects is reclaimed by an automatic memory management
40   * system which is known as a <i>garbage collector</i>.
41   *
42   * <p>The heap may be of a fixed size or may be expanded and shrunk.
43   * The memory for the heap does not need to be contiguous.
44   *
45   * <h4> 2. Non-Heap Memory</h4>
46   * The Java virtual machine manages memory other than the heap
47   * (referred as <i>non-heap memory</i>).
48   * 
49   * <p> The Java virtual machine has a <i>method area</i> that is shared
50   * among all threads.
51   * The method area belongs to non-heap memory.  It stores per-class structures
52   * such as a runtime constant pool, field and method data, and the code for
53   * methods and constructors.  It is created at the Java virtual machine
54   * start-up.
55   * 
56   * <p> The method area is logically part of the heap but a Java virtual
57   * machine implementation may choose not to either garbage collect
58   * or compact it.  Similar to the heap, the method area may be of a
59   * fixed size or may be expanded and shrunk.  The memory for the
60   * method area does not need to be contiguous.
61   *
62   * <p>In addition to the method area, a Java virtual machine
63   * implementation may require memory for internal processing or 
64   * optimization which also belongs to non-heap memory.
65   * For example, the JIT compiler requires memory for storing the native
66   * machine code translated from the Java virtual machine code for
67   * high performance.
68   *
69   * <h4>Memory Pools and Memory Managers</h4>
70   * {@link MemoryPoolMXBean Memory pools} and 
71   * {@link MemoryManagerMXBean memory managers} are the abstract entities
72   * that monitor and manage the memory system
73   * of the Java virtual machine.
74   *
75   * <p>A memory pool represents a memory area that the Java virtual machine 
76   * manages.  The Java virtual machine has at least one memory pool
77   * and it may create or remove memory pools during execution.  
78   * A memory pool can belong to either the heap or the non-heap memory. 
79   * 
80   * <p>A memory manager is responsible for managing one or more memory pools.
81   * The garbage collector is one type of memory manager responsible 
82   * for reclaiming memory occupied by unreachable objects.  A Java virtual
83   * machine may have one or more memory managers.   It may
84   * add or remove memory managers during execution.
85   * A memory pool can be managed by more than one memory manager.
86   *
87   * <h4>Memory Usage Monitoring</h4>
88   *
89   * Memory usage is a very important monitoring attribute for the memory system.
90   * The memory usage, for example, could indicate:
91   * <ul>
92   *   <li>the memory usage of an application,</li>
93   *   <li>the workload being imposed on the automatic memory management system,</li>
94   *   <li>potential memory leakage.</li>
95   * </ul>
96   *
97   * <p>
98   * The memory usage can be monitored in three ways:
99   * <ul>
100  *   <li>Polling</li>
101  *   <li>Usage Threshold Notification</li>
102  *   <li>Collection Usage Threshold Notification</li>
103  * </ul>
104  *
105  * Details are specified in the {@link MemoryPoolMXBean} interface.
106  *
107  * <p>The memory usage monitoring mechanism is intended for load-balancing
108  * or workload distribution use.  For example, an application would stop
109  * receiving any new workload when its memory usage exceeds a
110  * certain threshold. It is not intended for an application to detect
111  * and recover from a low memory condition.
112  *
113  * <h4>Notifications</h4>
114  *
115  * <p>This <tt>MemoryMXBean</tt> is a 
116  * {@link javax.management.NotificationEmitter NotificationEmitter}
117  * that emits two types of memory {@link javax.management.Notification 
118  * notifications} if any one of the memory pools
119  * supports a <a HREF="MemoryPoolMXBean.html#UsageThreshold">usage threshold</a>
120  * or a <a HREF="MemoryPoolMXBean.html#CollectionThreshold">collection usage
121  * threshold</a> which can be determined by calling the
122  * {@link MemoryPoolMXBean#isUsageThresholdSupported} and
123  * {@link MemoryPoolMXBean#isCollectionUsageThresholdSupported} methods. 
124  * <ul>
125  *   <li>{@link MemoryNotificationInfo#MEMORY_THRESHOLD_EXCEEDED
126  *       usage threshold exceeded notification} - for notifying that
127  *       the memory usage of a memory pool is increased and has reached
128  *       or exceeded its
129  *       <a HREF="MemoryPoolMXBean.html#UsageThreshold"> usage threshold</a> value.
130  *       </li>
131  *   <li>{@link MemoryNotificationInfo#MEMORY_COLLECTION_THRESHOLD_EXCEEDED
132  *       collection usage threshold exceeded notification} - for notifying that
133  *       the memory usage of a memory pool is greater than or equal to its
134  *       <a HREF="MemoryPoolMXBean.html#CollectionThreshold">
135  *       collection usage threshold</a> after the Java virtual machine
136  *       has expended effort in recycling unused objects in that
137  *       memory pool.</li>
138  * </ul>
139  *
140  * <p>
141  * The notification emitted is a {@link javax.management.Notification}
142  * instance whose {@link javax.management.Notification#setUserData 
143  * user data} is set to a {@link CompositeData CompositeData} 
144  * that represents a {@link MemoryNotificationInfo} object
145  * containing information about the memory pool when the notification
146  * was constructed. The <tt>CompositeData</tt> contains the attributes
147  * as described in {@link MemoryNotificationInfo#from 
148  * MemoryNotificationInfo}.
149  *
150  * <hr>
151  * <h4>NotificationEmitter</h4>
152  * The <tt>MemoryMXBean</tt> object returned by
153  * {@link ManagementFactory#getMemoryMXBean} implements
154  * the {@link javax.management.NotificationEmitter NotificationEmitter}
155  * interface that allows a listener to be registered within the
156  * <tt>MemoryMXBean</tt> as a notification listener.  
157  * 
158  * Below is an example code that registers a <tt>MyListener</tt> to handle 
159  * notification emitted by the <tt>MemoryMXBean</tt>. 
160  *
161  * <blockquote><pre>
162  * class MyListener implements javax.management.NotificationListener {
163  *     public void handleNotification(Notification notif, Object handback) {
164  *         // handle notification
165  *         ....
166  *     }
167  * }
168  *
169  * MemoryMXBean mbean = ManagementFactory.getMemoryMXBean();
170  * NotificationEmitter emitter = (NotificationEmitter) mbean;
171  * MyListener listener = new MyListener();
172  * emitter.addNotificationListener(listener, null, null);
173  * </pre></blockquote>
174  *
175  * @see <a HREF="../../../javax/management/package-summary.html">
176  *      JMX Specification.</a>
177  * @see <a HREF="package-summary.html#examples">
178  *      Ways to Access MXBeans</a>
179  *
180  * @author  Mandy Chung
181  * @version 1.16, 03/08/06 
182  * @since   1.5
183  */
184 public interface MemoryMXBean {
185     /** 
186      * Returns the approximate number of objects for which 
187      * finalization is pending.
188      *
189      * @return the approximate number objects for which finalization
190      * is pending.
191      */
192     public int getObjectPendingFinalizationCount();
193     
194     /** 
195      * Returns the current memory usage of the heap that
196      * is used for object allocation.  The heap consists 
197      * of one or more memory pools.  The <tt>used</tt>
198      * and <tt>committed</tt> size of the returned memory
199      * usage is the sum of those values of all heap memory pools
200      * whereas the <tt>init</tt> and <tt>max</tt> size of the
201      * returned memory usage represents the setting of the heap
202      * memory which may not be the sum of those of all heap
203      * memory pools.
204      * <p>
205      * The amount of used memory in the returned memory usage
206      * is the amount of memory occupied by both live objects
207      * and garbage objects that have not been collected, if any.
208      *
209      * <p>
210      * <b>MBeanServer access</b>:<br>
211      * The mapped type of <tt>MemoryUsage</tt> is
212      * <tt>CompositeData</tt> with attributes as specified in 
213      * {@link MemoryUsage#from MemoryUsage}.
214      *
215      * @return a {@link MemoryUsage} object representing 
216      * the heap memory usage.
217      */
218     public MemoryUsage   getHeapMemoryUsage();
219 
220     /** 
221      * Returns the current memory usage of non-heap memory that
222      * is used by the Java virtual machine.
223      * The non-heap memory consists of one or more memory pools.  
224      * The <tt>used</tt> and <tt>committed</tt> size of the 
225      * returned memory usage is the sum of those values of 
226      * all non-heap memory pools whereas the <tt>init</tt> 
227      * and <tt>max</tt> size of the returned memory usage 
228      * represents the setting of the non-heap
229      * memory which may not be the sum of those of all non-heap
230      * memory pools.
231      *
232      * <p>
233      * <b>MBeanServer access</b>:<br>
234      * The mapped type of <tt>MemoryUsage</tt> is
235      * <tt>CompositeData</tt> with attributes as specified in 
236      * {@link MemoryUsage#from MemoryUsage}.
237      *
238      * @return a {@link MemoryUsage} object representing 
239      * the non-heap memory usage.
240      */
241     public MemoryUsage   getNonHeapMemoryUsage();
242     
243     /**
244      * Tests if verbose output for the memory system is enabled.
245      *
246      * @return <tt>true</tt> if verbose output for the memory 
247      * system is enabled; <tt>false</tt> otherwise.
248      */
249     public boolean isVerbose();
250 
251     /**
252      * Enables or disables verbose output for the memory
253      * system.  The verbose output information and the output stream
254      * to which the verbose information is emitted are implementation
255      * dependent.  Typically, a Java virtual machine implementation
256      * prints a message whenever it frees memory at garbage collection. 
257      *
258      * <p>
259      * Each invocation of this method enables or disables verbose
260      * output globally.
261      *
262      * @param value <tt>true</tt> to enable verbose output;
263      *              <tt>false</tt> to disable.
264      *
265      * @exception  java.lang.SecurityException if a security manager
266      *             exists and the caller does not have
267      *             ManagementPermission("control").
268      */
269     public void setVerbose(boolean value);
270 
271     /**
272      * Runs the garbage collector.  
273      * The call <code>gc()</code> is effectively equivalent to the
274      * call:
275      * <blockquote><pre>
276      * System.gc()
277      * </pre></blockquote>
278      *
279      * @see     java.lang.System#gc()
280      */
281     public void gc();
282 
283 }
284
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags