| Frames | No Frames |
1: /* MemoryPoolMXBean.java - Interface for a memory pool bean 2: Copyright (C) 2006 Free Software Foundation 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: package java.lang.management; 39: 40: /** 41: * <p> 42: * Provides access to information about one of the memory 43: * resources or pools used by the virtual machine. Instances 44: * of this bean are obtained by calling 45: * {@link ManagementFactory#getMemoryPoolMXBeans()}. One 46: * bean is returned for each memory pool provided. 47: * </p> 48: * <p> 49: * The memory pool bean allows the usage of the pool to be 50: * monitored. The bean can provide statistics on the current 51: * and peak usage of the pool, and on the threshold levels the 52: * pool uses. 53: * </p> 54: * <p> 55: * {@link getUsage()} returns an approximation of the current 56: * usage of the pool. Calls to this method are expected to be 57: * generally quick to perform; if the call is expensive, the 58: * documentation of the bean should specify so. For memory 59: * pool beans that represent the memory used by garbage 60: * collectors, the usage level includes both referenced and 61: * unreferenced objects. 62: * </p> 63: * <p> 64: * {@link getPeakUsage()} and {@link resetPeakUsage()} enable 65: * the retrieval of the peak usage level and setting it to the 66: * current usage level, respectively. Initially, the peak usage 67: * level is relative to the start of the virtual machine. 68: * </p> 69: * <p> 70: * Memory pools may also include optional support for usage thresholds. 71: * The usage threshold is a particular level of memory usage. When this 72: * value is crossed (the current memory usage becomes equal to or greater 73: * than this threshold level), the usage threshold count is increased. 74: * This feature is designed for monitoring the trend in memory usage. 75: * Support for a collection usage threshold is also provided, for 76: * particular garbage collectors. This is used to monitor the amount 77: * of memory left uncollected after a garbage collection cycle. There 78: * is no need to make special garbage collection runs to support this; 79: * the level following collection just needs to be monitored. 80: * </p> 81: * 82: * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 83: * @since 1.5 84: */ 85: public interface MemoryPoolMXBean 86: { 87: 88: /** 89: * Returns memory usage statistics after a best-effort attempt 90: * has been made to remove unused objects from the pool. This 91: * method is designed for use by the pools of garbage collectors, 92: * in order to monitor the amount of memory used after collections. 93: * It will return <code>null</code> if such functionality is 94: * unsupported by the memory pool represented by this bean. 95: * 96: * @return the memory usage of the memory pool after the most 97: * recent garbage collection cycle, or <code>null</code> 98: * if this operation is not supported. 99: */ 100: MemoryUsage getCollectionUsage(); 101: 102: /** 103: * Returns the collection usage threshold level in bytes. This 104: * value is initially zero. 105: * 106: * @return the collection usage threshold in bytes. 107: * @throws UnsupportedOperationException if the collection usage 108: * threshold is not supported. 109: * @see #getCollectionUsageThresholdCount() 110: * @see #isCollectionUsageThresholdExceeded() 111: * @see #isCollectionUsageThresholdSupported() 112: * @see #setCollectionUsageThreshold(long) 113: */ 114: long getCollectionUsageThreshold(); 115: 116: /** 117: * Returns the number of times the usage level has matched or 118: * exceeded the collection usage threshold. 119: * 120: * @return the number of times the usage level has matched 121: * or exceeded the collection usage threshold. 122: * @throws UnsupportedOperationException if the collection usage 123: * threshold is not supported. 124: * @see #getCollectionUsageThreshold() 125: * @see #isCollectionUsageThresholdExceeded() 126: * @see #isCollectionUsageThresholdSupported() 127: * @see #setCollectionUsageThreshold(long) 128: */ 129: long getCollectionUsageThresholdCount(); 130: 131: /** 132: * Returns the names of the memory managers associated with this 133: * pool. Each pool has at least one memory manager. 134: * 135: * @return an array containing the name of each memory manager 136: * responsible for this pool. 137: */ 138: String[] getMemoryManagerNames(); 139: 140: /** 141: * Returns the name of the memory pool. 142: * 143: * @return the memory pool name. 144: */ 145: String getName(); 146: 147: /** 148: * Returns memory usage statistics for the peak memory usage 149: * of the pool. The peak is the maximum memory usage occurring 150: * since the virtual machine was started or since the peak 151: * was reset by {@link #resetPeakUsage()}. The return value 152: * may be <code>null</code> if this pool is no longer valid. 153: * 154: * @return the memory usage of the memory pool at its peak, 155: * or <code>null</code> if this pool is no longer valid. 156: */ 157: MemoryUsage getPeakUsage(); 158: 159: /** 160: * Returns the type of memory used by this pool. This can be 161: * either heap or non-heap memory. 162: * 163: * @return the type of this pool. 164: */ 165: MemoryType getType(); 166: 167: /** 168: * Returns memory usage statistics for the current memory usage 169: * of the pool. The return value may be <code>null</code> if 170: * this pool is no longer valid. Obtaining these values is 171: * expected to be a relatively quick operation; if this will 172: * instead be an expensive operation to perform, the documentation 173: * of the implementating bean should specify that this is the 174: * case. The values are intended to be an estimate for monitoring 175: * purposes. 176: * 177: * @return the memory usage of the memory pool at present, 178: * or <code>null</code> if this pool is no longer valid. 179: */ 180: MemoryUsage getUsage(); 181: 182: /** 183: * Returns the usage threshold level in bytes. This 184: * value is initially defined by the virtual machine. 185: * 186: * @return the usage threshold in bytes. 187: * @throws UnsupportedOperationException if the usage threshold 188: * is not supported. 189: * @see #getUsageThresholdCount() 190: * @see #isUsageThresholdExceeded() 191: * @see #isUsageThresholdSupported() 192: * @see #setUsageThreshold(long) 193: */ 194: long getUsageThreshold(); 195: 196: /** 197: * Returns the number of times the usage level has matched or 198: * exceeded the usage threshold. 199: * 200: * @return the number of times the usage level has matched 201: * or exceeded the usage threshold. 202: * @throws UnsupportedOperationException if the usage threshold 203: * is not supported. 204: * @see #getUsageThreshold() 205: * @see #isUsageThresholdExceeded() 206: * @see #isUsageThresholdSupported() 207: * @see #setUsageThreshold(long) 208: */ 209: long getUsageThresholdCount(); 210: 211: /** 212: * Returns true if the collection usage level is equal to 213: * or greater than the collection usage threshold. 214: * 215: * @return true if the collection usage threshold has been 216: * matched or exceeded. 217: * @throws UnsupportedOperationException if the collection usage 218: * threshold is not supported. 219: * @see #getCollectionUsageThreshold() 220: * @see #getCollectionUsageThresholdCount() 221: * @see #isCollectionUsageThresholdSupported() 222: * @see #setCollectionUsageThreshold(long) 223: */ 224: boolean isCollectionUsageThresholdExceeded(); 225: 226: /** 227: * Returns true if this memory pool supports a collection usage 228: * level threshold. 229: * 230: * @return true if a collection usage level threshold is supported. 231: * @see #getCollectionUsageThreshold() 232: * @see #getCollectionUsageThresholdCount() 233: * @see #isCollectionUsageThresholdExceeded() 234: * @see #setCollectionUsageThreshold(long) 235: */ 236: boolean isCollectionUsageThresholdSupported(); 237: 238: /** 239: * Returns true if the usage level is equal to 240: * or greater than the usage threshold. 241: * 242: * @return true if the usage threshold has been 243: * matched or exceeded. 244: * @throws UnsupportedOperationException if the usage threshold 245: * is not supported. 246: * @see #getUsageThreshold() 247: * @see #getUsageThresholdCount() 248: * @see #isUsageThresholdSupported() 249: * @see #setUsageThreshold(long) 250: */ 251: boolean isUsageThresholdExceeded(); 252: 253: /** 254: * Returns true if this memory pool supports a usage level threshold. 255: * 256: * @return true if a usage level threshold is supported. 257: * @see #getUsageThreshold() 258: * @see #getUsageThresholdCount() 259: * @see #isUsageThresholdExceeded() 260: * @see #setUsageThreshold(long) 261: */ 262: boolean isUsageThresholdSupported(); 263: 264: /** 265: * Returns true if this memory pool is still valid. A memory pool 266: * becomes invalid when it is removed by the virtual machine and 267: * no longer used. 268: * 269: * @return true if this memory pool is valid. 270: */ 271: boolean isValid(); 272: 273: /** 274: * Resets the peak memory usage level to the current memory usage 275: * level. 276: * 277: * @throws SecurityException if a security manager exists and 278: * denies ManagementPermission("control"). 279: */ 280: void resetPeakUsage(); 281: 282: /** 283: * Sets the collection threshold usage level to the given value. 284: * A value of zero disables the collection threshold. 285: * 286: * @param threshold the new threshold level. 287: * @throws IllegalArgumentException if the threshold hold level 288: * is negative. 289: * @throws UnsupportedOperationException if the collection usage 290: * threshold is not supported. 291: * @throws SecurityException if a security manager exists and 292: * denies ManagementPermission("control"). 293: * @see #getCollectionUsageThreshold() 294: * @see #getCollectionUsageThresholdCount() 295: * @see #isCollectionUsageThresholdExceeded() 296: * @see #isCollectionUsageThresholdSupported() 297: */ 298: void setCollectionUsageThreshold(long threshold); 299: 300: /** 301: * Sets the threshold usage level to the given value. A value of 302: * zero disables the threshold. 303: * 304: * @param threshold the new threshold level. 305: * @throws IllegalArgumentException if the threshold hold level 306: * is negative. 307: * @throws UnsupportedOperationException if the usage threshold 308: * is not supported. 309: * @throws SecurityException if a security manager exists and 310: * denies ManagementPermission("control"). 311: * @see #getUsageThreshold() 312: * @see #getUsageThresholdCount() 313: * @see #isUsageThresholdExceeded() 314: * @see #isUsageThresholdSupported() 315: */ 316: void setUsageThreshold(long threshold); 317: 318: }