/*
* Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.lang.management;
import javax.management.openmbean.CompositeData;
import sun.management.MemoryUsageCompositeData;
/**
* A MemoryUsage object represents a snapshot of memory usage.
* Instances of the MemoryUsage class are usually constructed
* by methods that are used to obtain memory usage
* information about individual memory pool of the Java virtual machine or
* the heap or non-heap memory of the Java virtual machine as a whole.
*
* A MemoryUsage object contains four values:
*
*
* | init |
* represents the initial amount of memory (in bytes) that
* the Java virtual machine requests from the operating system
* for memory management during startup. The Java virtual machine
* may request additional memory from the operating system and
* may also release memory to the system over time.
* The value of init may be undefined.
* |
*
*
* | used |
* represents the amount of memory currently used (in bytes).
* |
*
*
* | committed |
* represents the amount of memory (in bytes) that is
* guaranteed to be available for use by the Java virtual machine.
* The amount of committed memory may change over time (increase
* or decrease). The Java virtual machine may release memory to
* the system and committed could be less than init.
* committed will always be greater than
* or equal to used.
* |
*
*
* | max |
* represents the maximum amount of memory (in bytes)
* that can be used for memory management. Its value may be undefined.
* The maximum amount of memory may change over time if defined.
* The amount of used and committed memory will always be less than
* or equal to max if max is defined.
* A memory allocation may fail if it attempts to increase the
* used memory such that used > committed even
* if used <= max would still be true (for example,
* when the system is low on virtual memory).
* |
*
*
*
* Below is a picture showing an example of a memory pool:
*
*
* +----------------------------------------------+
* +//////////////// | +
* +//////////////// | +
* +----------------------------------------------+
*
* |--------|
* init
* |---------------|
* used
* |---------------------------|
* committed
* |----------------------------------------------|
* max
*
*
* MXBean Mapping
* MemoryUsage is mapped to a {@link CompositeData CompositeData}
* with attributes as specified in the {@link #from from} method.
*
* @author Mandy Chung
* @since 1.5
*/
public class MemoryUsage {
private final long init;
private final long used;
private final long committed;
private final long max;
/**
* Constructs a MemoryUsage object.
*
* @param init the initial amount of memory in bytes that
* the Java virtual machine allocates;
* or -1 if undefined.
* @param used the amount of used memory in bytes.
* @param committed the amount of committed memory in bytes.
* @param max the maximum amount of memory in bytes that
* can be used; or -1 if undefined.
*
* @throws IllegalArgumentException if
*
* - the value of init or max is negative
* but not -1; or
* - the value of used or committed is negative;
* or
* - used is greater than the value of committed;
* or
* - committed is greater than the value of max
* max if defined.
*
*/
public MemoryUsage(long init,
long used,
long committed,
long max) {
if (init < -1) {
throw new IllegalArgumentException( "init parameter = " +
init + " is negative but not -1.");
}
if (max < -1) {
throw new IllegalArgumentException( "max parameter = " +
max + " is negative but not -1.");
}
if (used < 0) {
throw new IllegalArgumentException( "used parameter = " +
used + " is negative.");
}
if (committed < 0) {
throw new IllegalArgumentException( "committed parameter = " +
committed + " is negative.");
}
if (used > committed) {
throw new IllegalArgumentException( "used = " + used +
" should be <= committed = " + committed);
}
if (max >= 0 && committed > max) {
throw new IllegalArgumentException( "committed = " + committed +
" should be < max = " + max);
}
this.init = init;
this.used = used;
this.committed = committed;
this.max = max;
}
/**
* Constructs a MemoryUsage object from a
* {@link CompositeData CompositeData}.
*/
private MemoryUsage(CompositeData cd) {
// validate the input composite data
MemoryUsageCompositeData.validateCompositeData(cd);
this.init = MemoryUsageCompositeData.getInit(cd);
this.used = MemoryUsageCompositeData.getUsed(cd);
this.committed = MemoryUsageCompositeData.getCommitted(cd);
this.max = MemoryUsageCompositeData.getMax(cd);
}
/**
* Returns the amount of memory in bytes that the Java virtual machine
* initially requests from the operating system for memory management.
* This method returns -1 if the initial memory size is undefined.
*
* @return the initial size of memory in bytes;
* -1 if undefined.
*/
public long getInit() {
return init;
}
/**
* Returns the amount of used memory in bytes.
*
* @return the amount of used memory in bytes.
*
*/
public long getUsed() {
return used;
};
/**
* Returns the amount of memory in bytes that is committed for
* the Java virtual machine to use. This amount of memory is
* guaranteed for the Java virtual machine to use.
*
* @return the amount of committed memory in bytes.
*
*/
public long getCommitted() {
return committed;
};
/**
* Returns the maximum amount of memory in bytes that can be
* used for memory management. This method returns -1
* if the maximum memory size is undefined.
*
* This amount of memory is not guaranteed to be available
* for memory management if it is greater than the amount of
* committed memory. The Java virtual machine may fail to allocate
* memory even if the amount of used memory does not exceed this
* maximum size.
*
* @return the maximum amount of memory in bytes;
* -1 if undefined.
*/
public long getMax() {
return max;
};
/**
* Returns a descriptive representation of this memory usage.
*/
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append("init = ").append(init).append('(').append(init >> 10)
.append("K) ");
sb.append("used = ").append(used).append('(').append(used >> 10)
.append("K) ");
sb.append("committed = ").append(committed).append('(')
.append(committed >> 10).append("K) ");
sb.append("max = ").append(max).append('(').append(max >> 10)
.append("K)");
return sb.toString();
}
/**
* Returns a MemoryUsage object represented by the
* given CompositeData. The given CompositeData
* must contain the following attributes:
*
*
*
*
* | Attribute Name |
* Type |
*
*
* | init |
* java.lang.Long |
*
*
* | used |
* java.lang.Long |
*
*
* | committed |
* java.lang.Long |
*
*
* | max |
* java.lang.Long |
*
*
*
*
* @param cd CompositeData representing a MemoryUsage
*
* @throws IllegalArgumentException if cd does not
* represent a MemoryUsage with the attributes described
* above.
*
* @return a MemoryUsage object represented by cd
* if cd is not null;
* null otherwise.
*/
public static MemoryUsage from(CompositeData cd) {
if (cd == null) {
return null;
}
if (cd instanceof MemoryUsageCompositeData) {
return ((MemoryUsageCompositeData) cd).getMemoryUsage();
} else {
return new MemoryUsage(cd);
}
}
}