1. /*

  2.  * @(#)MemoryUsage.java	1.16 04/05/25

  3.  *

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.lang.management;

  9. 

  10. import javax.management.openmbean.CompositeData;

  11. import sun.management.MemoryUsageCompositeData;

  12. 

  13. /**

  14.  * A <tt>MemoryUsage</tt> object represents a snapshot of memory usage.

  15.  * Instances of the <tt>MemoryUsage</tt> class are usually constructed

  16.  * by methods that are used to obtain memory usage

  17.  * information about individual memory pool of the Java virtual machine or

  18.  * the heap or non-heap memory of the Java virtual machine as a whole.

  19.  *

  20.  * <p> A <tt>MemoryUsage</tt> object contains four values:

  21.  * <ul>

  22.  * <table>

  23.  * <tr>

  24.  * <td valign=top> <tt>init</tt> </td>

  25.  * <td valign=top> represents the initial amount of memory (in bytes) that

  26.  *      the Java virtual machine requests from the operating system

  27.  *      for memory management during startup.  The Java virtual machine

  28.  *      may request additional memory from the operating system and

  29.  *      may also release memory to the system over time.

  30.  *      The value of <tt>init</tt> may be undefined.

  31.  * </td>

  32.  * </tr>

  33.  * <tr>

  34.  * <td valign=top> <tt>used</tt> </td>

  35.  * <td valign=top> represents the amount of memory currently used (in bytes).

  36.  * </td>

  37.  * </tr>

  38.  * <tr>

  39.  * <td valign=top> <tt>committed</tt> </td>

  40.  * <td valign=top> represents the amount of memory (in bytes) that is

  41.  *      guaranteed to be available for use by the Java virtual machine.

  42.  *      The amount of committed memory may change over time (increase

  43.  *      or decrease).  The Java virtual machine may release memory to

  44.  *      the system and <tt>committed</tt> could be less than <tt>init</tt>.

  45.  *      <tt>committed</tt> will always be greater than

  46.  *      or equal to <tt>used</tt>.

  47.  * </td>

  48.  * </tr>

  49.  * <tr>

  50.  * <td valign=top> <tt>max</tt> </td>

  51.  * <td valign=top> represents the maximum amount of memory (in bytes)

  52.  *      that can be used for memory management. Its value may be undefined.

  53.  *      The maximum amount of memory may change over time if defined.

  54.  *      The amount of used and committed memory will always be less than 

  55.  *      or equal to <tt>max</tt> if <tt>max</tt> is defined.

  56.  *      A memory allocation may fail if it attempts to increase the

  57.  *      used memory such that <tt>used > committed</tt> even

  58.  *      if <tt>used <= max</tt> would still be true (for example,

  59.  *      when the system is low on virtual memory).

  60.  * </td>

  61.  * </tr>

  62.  * </table>

  63.  * </ul>

  64.  *

  65.  * Below is a picture showing an example of a memory pool:

  66.  * <p>

  67.  * <pre>

  68.  *        +----------------------------------------------+

  69.  *        +////////////////           |                  +

  70.  *        +////////////////           |                  +

  71.  *        +----------------------------------------------+

  72.  *

  73.  *        |--------|

  74.  *           init

  75.  *        |---------------|

  76.  *               used

  77.  *        |---------------------------|

  78.  *                  committed 

  79.  *        |----------------------------------------------|

  80.  *                            max 

  81.  * </pre>

  82.  *

  83.  * <h4>MXBean Mapping</h4>

  84.  * <tt>MemoryUsage</tt> is mapped to a {@link CompositeData CompositeData}

  85.  * with attributes as specified in the {@link #from from} method. 

  86.  *

  87.  * @author   Mandy Chung

  88.  * @version 1.16, 05/25/04

  89.  * @since   1.5

  90.  */

  91. public class MemoryUsage {

  92.     private final long init;

  93.     private final long used;

  94.     private final long committed;

  95.     private final long max;

  96. 

  97.     /**

  98.      * Constructs a <tt>MemoryUsage</tt> object.

  99.      *

  100.      * @param init      the initial amount of memory in bytes that

  101.      *                  the Java virtual machine allocates;

  102.      *                  or <tt>-1</tt> if undefined.

  103.      * @param used      the amount of used memory in bytes.

  104.      * @param committed the amount of committed memory in bytes.

  105.      * @param max       the maximum amount of memory in bytes that

  106.      *                  can be used; or <tt>-1</tt> if undefined.

  107.      *

  108.      * @throws IllegalArgumentException if

  109.      * <ul>

  110.      * <li> the value of <tt>init</tt> or <tt>max</tt> is negative

  111.      *      but not <tt>-1</tt> or</li>

  112.      * <li> the value of <tt>used</tt> or <tt>committed</tt> is negative;

  113.      *      or</li>

  114.      * <li> <tt>used</tt> is greater than the value of <tt>committed</tt>

  115.      *      or</li>

  116.      * <li> <tt>committed</tt> is greater than the value of <tt>max</tt> 

  117.      *      <tt>max</tt> if defined.</li>

  118.      * </ul>

  119.      */

  120.     public MemoryUsage(long init,

  121.                        long used,

  122.                        long committed,

  123.                        long max) {

  124.         if (init < -1) {

  125.             throw new IllegalArgumentException( "init parameter = " + 

  126.                 init + " is negative but not -1.");

  127.         }

  128.         if (max < -1) {

  129.             throw new IllegalArgumentException( "max parameter = " + 

  130.                 max + " is negative but not -1.");

  131.         }

  132.         if (used < 0) {

  133.             throw new IllegalArgumentException( "used parameter = " + 

  134.                 used + " is negative.");

  135.         }

  136.         if (committed < 0) {

  137.             throw new IllegalArgumentException( "committed parameter = " + 

  138.                 committed + " is negative.");

  139.         }

  140.         if (used > committed) {

  141.             throw new IllegalArgumentException( "used = " + used +

  142.                 " should be <= committed = " + committed);

  143.         }

  144.         if (max >= 0 && committed > max) {

  145.             throw new IllegalArgumentException( "committed = " + committed +

  146.                 " should be < max = " + max);

  147.         }

  148. 

  149.         this.init = init;

  150.         this.used = used;

  151.         this.committed = committed;

  152.         this.max = max;

  153.     }

  154. 

  155.     /**

  156.      * Constructs a <tt>MemoryUsage</tt> object from a 

  157.      * {@link CompositeData CompositeData}.  

  158.      */

  159.     private MemoryUsage(CompositeData cd) {

  160.         // validate the input composite data  

  161.         MemoryUsageCompositeData.validateCompositeData(cd);

  162. 

  163.         this.init = MemoryUsageCompositeData.getInit(cd);

  164.         this.used = MemoryUsageCompositeData.getUsed(cd);

  165.         this.committed = MemoryUsageCompositeData.getCommitted(cd);

  166.         this.max = MemoryUsageCompositeData.getMax(cd);

  167.     }

  168. 

  169.     /**

  170.      * Returns the amount of memory in bytes that the Java virtual machine

  171.      * initially requests from the operating system for memory management.

  172.      * This method returns <tt>-1</tt> if the initial memory size is undefined.

  173.      *

  174.      * @return the initial size of memory in bytes;

  175.      * <tt>-1</tt> if undefined.

  176.      */

  177.     public long getInit() {

  178.         return init;

  179.     }

  180.     

  181.     /** 

  182.      * Returns the amount of used memory in bytes.

  183.      *

  184.      * @return the amount of used memory in bytes.

  185.      *

  186.      */

  187.     public long getUsed() {

  188.         return used;

  189.     };

  190.     

  191.     /** 

  192.      * Returns the amount of memory in bytes that is committed for

  193.      * the Java virtual machine to use.  This amount of memory is

  194.      * guaranteed for the Java virtual machine to use. 

  195.      *

  196.      * @return the amount of committed memory in bytes.

  197.      *

  198.      */

  199.     public long getCommitted() {

  200.         return committed;

  201.     };

  202.        

  203.     /** 

  204.      * Returns the maximum amount of memory in bytes that can be 

  205.      * used for memory management.  This method returns <tt>-1</tt> 

  206.      * if the maximum memory size is undefined.

  207.      *

  208.      * <p> This amount of memory is not guaranteed to be available 

  209.      * for memory management if it is greater than the amount of 

  210.      * committed memory.  The Java virtual machine may fail to allocate 

  211.      * memory even if the amount of used memory does not exceed this 

  212.      * maximum size.

  213.      * 

  214.      * @return the maximum amount of memory in bytes; 

  215.      * <tt>-1</tt> if undefined.

  216.      */

  217.     public long getMax() {

  218.         return max;

  219.     };

  220.            

  221.     /**

  222.      * Returns a descriptive representation of this memory usage.

  223.      */

  224.     public String toString() {

  225.         StringBuffer buf = new StringBuffer();

  226.         buf.append("init = " + init + "(" + (init >> 10) + "K) ");

  227.         buf.append("used = " + used + "(" + (used >> 10) + "K) ");

  228.         buf.append("committed = " + committed + "(" + 

  229.                    (committed >> 10) + "K) " );

  230.         buf.append("max = " + max + "(" + (max >> 10) + "K)");

  231.         return buf.toString();

  232.     }

  233. 

  234.     /**

  235.      * Returns a <tt>MemoryUsage</tt> object represented by the

  236.      * given <tt>CompositeData</tt>. The given <tt>CompositeData</tt>

  237.      * must contain the following attributes:

  238.      * <p>

  239.      * <blockquote>

  240.      * <table border>

  241.      * <tr>

  242.      *   <th align=left>Attribute Name</th>

  243.      *   <th align=left>Type</th>

  244.      * </tr>

  245.      * <tr>

  246.      *   <td>init</td>

  247.      *   <td><tt>java.lang.Long</tt></td>

  248.      * </tr>

  249.      * <tr>

  250.      *   <td>used</td>

  251.      *   <td><tt>java.lang.Long</tt></td>

  252.      * </tr>

  253.      * <tr>

  254.      *   <td>committed</td>

  255.      *   <td><tt>java.lang.Long</tt></td>

  256.      * </tr>

  257.      * <tr>

  258.      *   <td>max</td>

  259.      *   <td><tt>java.lang.Long</tt></td>

  260.      * </tr>

  261.      * </table>

  262.      * </blockquote>

  263.      *

  264.      * @param cd <tt>CompositeData</tt> representing a <tt>MemoryUsage</tt>

  265.      *

  266.      * @throws IllegalArgumentException if <tt>cd</tt> does not

  267.      *   represent a <tt>MemoryUsage</tt> with the attributes described

  268.      *   above.

  269.      *

  270.      * @return a <tt>MemoryUsage</tt> object represented by <tt>cd</tt>

  271.      *         if <tt>cd</tt> is not <tt>null</tt>

  272.      *         <tt>null</tt> otherwise.

  273.      */

  274.     public static MemoryUsage from(CompositeData cd) {

  275.         if (cd == null) {

  276.             return null;

  277.         }

  278. 

  279.         if (cd instanceof MemoryUsageCompositeData) {

  280.             return ((MemoryUsageCompositeData) cd).getMemoryUsage();

  281.         } else {

  282.             return new MemoryUsage(cd);

  283.         }

  284. 

  285.     }

  286. }