java.lang.management
Interface MemoryPoolMXBean


public interface MemoryPoolMXBean

Provides access to information about one of the memory resources or pools used by the virtual machine. Instances of this bean are obtained by calling ManagementFactory.getMemoryPoolMXBeans(). One bean is returned for each memory pool provided.

The memory pool bean allows the usage of the pool to be monitored. The bean can provide statistics on the current and peak usage of the pool, and on the threshold levels the pool uses.

getUsage() returns an approximation of the current usage of the pool. Calls to this method are expected to be generally quick to perform; if the call is expensive, the documentation of the bean should specify so. For memory pool beans that represent the memory used by garbage collectors, the usage level includes both referenced and unreferenced objects.

getPeakUsage() and resetPeakUsage() enable the retrieval of the peak usage level and setting it to the current usage level, respectively. Initially, the peak usage level is relative to the start of the virtual machine.

Memory pools may also include optional support for usage thresholds. The usage threshold is a particular level of memory usage. When this value is crossed (the current memory usage becomes equal to or greater than this threshold level), the usage threshold count is increased. This feature is designed for monitoring the trend in memory usage. Support for a collection usage threshold is also provided, for particular garbage collectors. This is used to monitor the amount of memory left uncollected after a garbage collection cycle. There is no need to make special garbage collection runs to support this; the level following collection just needs to be monitored.

Since:
1.5

Method Summary
 MemoryUsage getCollectionUsage()
          Returns memory usage statistics after a best-effort attempt has been made to remove unused objects from the pool.
 long getCollectionUsageThreshold()
          Returns the collection usage threshold level in bytes.
 long getCollectionUsageThresholdCount()
          Returns the number of times the usage level has matched or exceeded the collection usage threshold.
 String[] getMemoryManagerNames()
          Returns the names of the memory managers associated with this pool.
 String getName()
          Returns the name of the memory pool.
 MemoryUsage getPeakUsage()
          Returns memory usage statistics for the peak memory usage of the pool.
 MemoryType getType()
          Returns the type of memory used by this pool.
 MemoryUsage getUsage()
          Returns memory usage statistics for the current memory usage of the pool.
 long getUsageThreshold()
          Returns the usage threshold level in bytes.
 long getUsageThresholdCount()
          Returns the number of times the usage level has matched or exceeded the usage threshold.
 boolean isCollectionUsageThresholdExceeded()
          Returns true if the collection usage level is equal to or greater than the collection usage threshold.
 boolean isCollectionUsageThresholdSupported()
          Returns true if this memory pool supports a collection usage level threshold.
 boolean isUsageThresholdExceeded()
          Returns true if the usage level is equal to or greater than the usage threshold.
 boolean isUsageThresholdSupported()
          Returns true if this memory pool supports a usage level threshold.
 boolean isValid()
          Returns true if this memory pool is still valid.
 void resetPeakUsage()
          Resets the peak memory usage level to the current memory usage level.
 void setCollectionUsageThreshold(long threshold)
          Sets the collection threshold usage level to the given value.
 void setUsageThreshold(long threshold)
          Sets the threshold usage level to the given value.
 

Method Detail

getCollectionUsage

MemoryUsage getCollectionUsage()
Returns memory usage statistics after a best-effort attempt has been made to remove unused objects from the pool. This method is designed for use by the pools of garbage collectors, in order to monitor the amount of memory used after collections. It will return null if such functionality is unsupported by the memory pool represented by this bean.

Returns:
the memory usage of the memory pool after the most recent garbage collection cycle, or null if this operation is not supported.

getCollectionUsageThreshold

long getCollectionUsageThreshold()
Returns the collection usage threshold level in bytes. This value is initially zero.

Returns:
the collection usage threshold in bytes.
Throws:
UnsupportedOperationException - if the collection usage threshold is not supported.
See Also:
getCollectionUsageThresholdCount(), isCollectionUsageThresholdExceeded(), isCollectionUsageThresholdSupported(), setCollectionUsageThreshold(long)

getCollectionUsageThresholdCount

long getCollectionUsageThresholdCount()
Returns the number of times the usage level has matched or exceeded the collection usage threshold.

Returns:
the number of times the usage level has matched or exceeded the collection usage threshold.
Throws:
UnsupportedOperationException - if the collection usage threshold is not supported.
See Also:
getCollectionUsageThreshold(), isCollectionUsageThresholdExceeded(), isCollectionUsageThresholdSupported(), setCollectionUsageThreshold(long)

getMemoryManagerNames

String[] getMemoryManagerNames()
Returns the names of the memory managers associated with this pool. Each pool has at least one memory manager.

Returns:
an array containing the name of each memory manager responsible for this pool.

getName

String getName()
Returns the name of the memory pool.

Returns:
the memory pool name.

getPeakUsage

MemoryUsage getPeakUsage()
Returns memory usage statistics for the peak memory usage of the pool. The peak is the maximum memory usage occurring since the virtual machine was started or since the peak was reset by resetPeakUsage(). The return value may be null if this pool is no longer valid.

Returns:
the memory usage of the memory pool at its peak, or null if this pool is no longer valid.

getType

MemoryType getType()
Returns the type of memory used by this pool. This can be either heap or non-heap memory.

Returns:
the type of this pool.

getUsage

MemoryUsage getUsage()
Returns memory usage statistics for the current memory usage of the pool. The return value may be null if this pool is no longer valid. Obtaining these values is expected to be a relatively quick operation; if this will instead be an expensive operation to perform, the documentation of the implementating bean should specify that this is the case. The values are intended to be an estimate for monitoring purposes.

Returns:
the memory usage of the memory pool at present, or null if this pool is no longer valid.

getUsageThreshold

long getUsageThreshold()
Returns the usage threshold level in bytes. This value is initially defined by the virtual machine.

Returns:
the usage threshold in bytes.
Throws:
UnsupportedOperationException - if the usage threshold is not supported.
See Also:
getUsageThresholdCount(), isUsageThresholdExceeded(), isUsageThresholdSupported(), setUsageThreshold(long)

getUsageThresholdCount

long getUsageThresholdCount()
Returns the number of times the usage level has matched or exceeded the usage threshold.

Returns:
the number of times the usage level has matched or exceeded the usage threshold.
Throws:
UnsupportedOperationException - if the usage threshold is not supported.
See Also:
getUsageThreshold(), isUsageThresholdExceeded(), isUsageThresholdSupported(), setUsageThreshold(long)

isCollectionUsageThresholdExceeded

boolean isCollectionUsageThresholdExceeded()
Returns true if the collection usage level is equal to or greater than the collection usage threshold.

Returns:
true if the collection usage threshold has been matched or exceeded.
Throws:
UnsupportedOperationException - if the collection usage threshold is not supported.
See Also:
getCollectionUsageThreshold(), getCollectionUsageThresholdCount(), isCollectionUsageThresholdSupported(), setCollectionUsageThreshold(long)

isCollectionUsageThresholdSupported

boolean isCollectionUsageThresholdSupported()
Returns true if this memory pool supports a collection usage level threshold.

Returns:
true if a collection usage level threshold is supported.
See Also:
getCollectionUsageThreshold(), getCollectionUsageThresholdCount(), isCollectionUsageThresholdExceeded(), setCollectionUsageThreshold(long)

isUsageThresholdExceeded

boolean isUsageThresholdExceeded()
Returns true if the usage level is equal to or greater than the usage threshold.

Returns:
true if the usage threshold has been matched or exceeded.
Throws:
UnsupportedOperationException - if the usage threshold is not supported.
See Also:
getUsageThreshold(), getUsageThresholdCount(), isUsageThresholdSupported(), setUsageThreshold(long)

isUsageThresholdSupported

boolean isUsageThresholdSupported()
Returns true if this memory pool supports a usage level threshold.

Returns:
true if a usage level threshold is supported.
See Also:
getUsageThreshold(), getUsageThresholdCount(), isUsageThresholdExceeded(), setUsageThreshold(long)

isValid

boolean isValid()
Returns true if this memory pool is still valid. A memory pool becomes invalid when it is removed by the virtual machine and no longer used.

Returns:
true if this memory pool is valid.

resetPeakUsage

void resetPeakUsage()
Resets the peak memory usage level to the current memory usage level.

Throws:
SecurityException - if a security manager exists and denies ManagementPermission("control").

setCollectionUsageThreshold

void setCollectionUsageThreshold(long threshold)
Sets the collection threshold usage level to the given value. A value of zero disables the collection threshold.

Parameters:
threshold - the new threshold level.
Throws:
IllegalArgumentException - if the threshold hold level is negative.
UnsupportedOperationException - if the collection usage threshold is not supported.
SecurityException - if a security manager exists and denies ManagementPermission("control").
See Also:
getCollectionUsageThreshold(), getCollectionUsageThresholdCount(), isCollectionUsageThresholdExceeded(), isCollectionUsageThresholdSupported()

setUsageThreshold

void setUsageThreshold(long threshold)
Sets the threshold usage level to the given value. A value of zero disables the threshold.

Parameters:
threshold - the new threshold level.
Throws:
IllegalArgumentException - if the threshold hold level is negative.
UnsupportedOperationException - if the usage threshold is not supported.
SecurityException - if a security manager exists and denies ManagementPermission("control").
See Also:
getUsageThreshold(), getUsageThresholdCount(), isUsageThresholdExceeded(), isUsageThresholdSupported()