Source for java.lang.management.MemoryPoolMXBean

   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: }