java.lang.management

Interface MemoryPoolMXBean

Known Implementing Classes:: MemoryPoolMXBeanImpl

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.

getCollectionUsage

public 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

public 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

public 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

public 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

public String getName()

Returns the name of the memory pool.
Returns:
the memory pool name.

getPeakUsage

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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()

MemoryPoolMXBean.java - Interface for a memory pool bean Copyright (C) 2006 Free Software Foundation This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

Overview Package Class Use Source Tree Index Deprecated About
Prev Class \| Next Class		Frames \| No Frames
Summary: Nested \| Field \| Method \| Constr	Detail: Nested \| Field \| Method \| Constr