1 /*
   2  * Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang.management;
  27 
  28 import javax.management.openmbean.CompositeData;
  29 import sun.management.MemoryUsageCompositeData;
  30 
  31 /**
  32  * A {@code MemoryUsage} object represents a snapshot of memory usage.
  33  * Instances of the {@code MemoryUsage} class are usually constructed
  34  * by methods that are used to obtain memory usage
  35  * information about individual memory pool of the Java virtual machine or
  36  * the heap or non-heap memory of the Java virtual machine as a whole.
  37  *
  38  * <p> A {@code MemoryUsage} object contains four values:
  39  * <table class="striped">
  40  * <caption style="display:none">Describes the MemoryUsage object content</caption>
  41  * <thead>
  42  * <tr><th scope="col">Value</th><th scope="col">Description</th></tr>
  43  * </thead>
  44  * <tbody style="text-align:left">
  45  * <tr>
  46  * <th scope="row" style="vertical-align:top"> {@code init} </th>
  47  * <td style="vertical-align:top"> represents the initial amount of memory (in bytes) that
  48  *      the Java virtual machine requests from the operating system
  49  *      for memory management during startup.  The Java virtual machine
  50  *      may request additional memory from the operating system and
  51  *      may also release memory to the system over time.
  52  *      The value of {@code init} may be undefined.
  53  * </td>
  54  * </tr>
  55  * <tr>
  56  * <th scope="row" style="vertical-align:top"> {@code used} </th>
  57  * <td style="vertical-align:top"> represents the amount of memory currently used (in bytes).
  58  * </td>
  59  * </tr>
  60  * <tr>
  61  * <th scope="row" style="vertical-align:top"> {@code committed} </th>
  62  * <td style="vertical-align:top"> represents the amount of memory (in bytes) that is
  63  *      guaranteed to be available for use by the Java virtual machine.
  64  *      The amount of committed memory may change over time (increase
  65  *      or decrease).  The Java virtual machine may release memory to
  66  *      the system and {@code committed} could be less than {@code init}.
  67  *      {@code committed} will always be greater than
  68  *      or equal to {@code used}.
  69  * </td>
  70  * </tr>
  71  * <tr>
  72  * <th scope="row" style="vertical-align:top"> {@code max} </th>
  73  * <td style="vertical-align:top"> represents the maximum amount of memory (in bytes)
  74  *      that can be used for memory management. Its value may be undefined.
  75  *      The maximum amount of memory may change over time if defined.
  76  *      The amount of used and committed memory will always be less than
  77  *      or equal to {@code max} if {@code max} is defined.
  78  *      A memory allocation may fail if it attempts to increase the
  79  *      used memory such that {@code used > committed} even
  80  *      if {@code used <= max} would still be true (for example,
  81  *      when the system is low on virtual memory).
  82  * </td>
  83  * </tr>
  84  * </tbody>
  85  * </table>
  86  *
  87  * Below is a picture showing an example of a memory pool:
  88  *
  89  * <pre>
  90  *        +----------------------------------------------+
  91  *        +////////////////           |                  +
  92  *        +////////////////           |                  +
  93  *        +----------------------------------------------+
  94  *
  95  *        |--------|
  96  *           init
  97  *        |---------------|
  98  *               used
  99  *        |---------------------------|
 100  *                  committed
 101  *        |----------------------------------------------|
 102  *                            max
 103  * </pre>
 104  *
 105  * <h3>MXBean Mapping</h3>
 106  * {@code MemoryUsage} is mapped to a {@link CompositeData CompositeData}
 107  * with attributes as specified in the {@link #from from} method.
 108  *
 109  * @author   Mandy Chung
 110  * @since   1.5
 111  */
 112 public class MemoryUsage {
 113     private final long init;
 114     private final long used;
 115     private final long committed;
 116     private final long max;
 117 
 118     /**
 119      * Constructs a {@code MemoryUsage} object.
 120      *
 121      * @param init      the initial amount of memory in bytes that
 122      *                  the Java virtual machine allocates;
 123      *                  or {@code -1} if undefined.
 124      * @param used      the amount of used memory in bytes.
 125      * @param committed the amount of committed memory in bytes.
 126      * @param max       the maximum amount of memory in bytes that
 127      *                  can be used; or {@code -1} if undefined.
 128      *
 129      * @throws IllegalArgumentException if
 130      * <ul>
 131      * <li> the value of {@code init} or {@code max} is negative
 132      *      but not {@code -1}; or</li>
 133      * <li> the value of {@code used} or {@code committed} is negative;
 134      *      or</li>
 135      * <li> {@code used} is greater than the value of {@code committed};
 136      *      or</li>
 137      * <li> {@code committed} is greater than the value of {@code max}
 138      *      {@code max} if defined.</li>
 139      * </ul>
 140      */
 141     public MemoryUsage(long init,
 142                        long used,
 143                        long committed,
 144                        long max) {
 145         if (init < -1) {
 146             throw new IllegalArgumentException( "init parameter = " +
 147                 init + " is negative but not -1.");
 148         }
 149         if (max < -1) {
 150             throw new IllegalArgumentException( "max parameter = " +
 151                 max + " is negative but not -1.");
 152         }
 153         if (used < 0) {
 154             throw new IllegalArgumentException( "used parameter = " +
 155                 used + " is negative.");
 156         }
 157         if (committed < 0) {
 158             throw new IllegalArgumentException( "committed parameter = " +
 159                 committed + " is negative.");
 160         }
 161         if (used > committed) {
 162             throw new IllegalArgumentException( "used = " + used +
 163                 " should be <= committed = " + committed);
 164         }
 165         if (max >= 0 && committed > max) {
 166             throw new IllegalArgumentException( "committed = " + committed +
 167                 " should be < max = " + max);
 168         }
 169 
 170         this.init = init;
 171         this.used = used;
 172         this.committed = committed;
 173         this.max = max;
 174     }
 175 
 176     /**
 177      * Constructs a {@code MemoryUsage} object from a
 178      * {@link CompositeData CompositeData}.
 179      */
 180     private MemoryUsage(CompositeData cd) {
 181         // validate the input composite data
 182         MemoryUsageCompositeData.validateCompositeData(cd);
 183 
 184         this.init = MemoryUsageCompositeData.getInit(cd);
 185         this.used = MemoryUsageCompositeData.getUsed(cd);
 186         this.committed = MemoryUsageCompositeData.getCommitted(cd);
 187         this.max = MemoryUsageCompositeData.getMax(cd);
 188     }
 189 
 190     /**
 191      * Returns the amount of memory in bytes that the Java virtual machine
 192      * initially requests from the operating system for memory management.
 193      * This method returns {@code -1} if the initial memory size is undefined.
 194      *
 195      * @return the initial size of memory in bytes;
 196      * {@code -1} if undefined.
 197      */
 198     public long getInit() {
 199         return init;
 200     }
 201 
 202     /**
 203      * Returns the amount of used memory in bytes.
 204      *
 205      * @return the amount of used memory in bytes.
 206      *
 207      */
 208     public long getUsed() {
 209         return used;
 210     };
 211 
 212     /**
 213      * Returns the amount of memory in bytes that is committed for
 214      * the Java virtual machine to use.  This amount of memory is
 215      * guaranteed for the Java virtual machine to use.
 216      *
 217      * @return the amount of committed memory in bytes.
 218      *
 219      */
 220     public long getCommitted() {
 221         return committed;
 222     };
 223 
 224     /**
 225      * Returns the maximum amount of memory in bytes that can be
 226      * used for memory management.  This method returns {@code -1}
 227      * if the maximum memory size is undefined.
 228      *
 229      * <p> This amount of memory is not guaranteed to be available
 230      * for memory management if it is greater than the amount of
 231      * committed memory.  The Java virtual machine may fail to allocate
 232      * memory even if the amount of used memory does not exceed this
 233      * maximum size.
 234      *
 235      * @return the maximum amount of memory in bytes;
 236      * {@code -1} if undefined.
 237      */
 238     public long getMax() {
 239         return max;
 240     };
 241 
 242     /**
 243      * Returns a descriptive representation of this memory usage.
 244      */
 245     public String toString() {
 246         StringBuilder buf = new StringBuilder();
 247         buf.append("init = " + init + "(" + (init >> 10) + "K) ");
 248         buf.append("used = " + used + "(" + (used >> 10) + "K) ");
 249         buf.append("committed = " + committed + "(" +
 250                    (committed >> 10) + "K) " );
 251         buf.append("max = " + max + "(" + (max >> 10) + "K)");
 252         return buf.toString();
 253     }
 254 
 255     /**
 256      * Returns a {@code MemoryUsage} object represented by the
 257      * given {@code CompositeData}. The given {@code CompositeData}
 258      * must contain the following attributes:
 259      *
 260      * <table class="striped" style="margin-left:2em;">
 261      * <caption style="display:none">The attributes and the types the given CompositeData contains</caption>
 262      * <thead>
 263      * <tr>
 264      *   <th scope="col">Attribute Name</th>
 265      *   <th scope="col">Type</th>
 266      * </tr>
 267      * </thead>
 268      * <tbody style="text-align:left">
 269      * <tr>
 270      *   <th scope="row">init</th>
 271      *   <td>{@code java.lang.Long}</td>
 272      * </tr>
 273      * <tr>
 274      *   <th scope="row">used</th>
 275      *   <td>{@code java.lang.Long}</td>
 276      * </tr>
 277      * <tr>
 278      *   <th scope="row">committed</th>
 279      *   <td>{@code java.lang.Long}</td>
 280      * </tr>
 281      * <tr>
 282      *   <th scope="row">max</th>
 283      *   <td>{@code java.lang.Long}</td>
 284      * </tr>
 285      * </tbody>
 286      * </table>
 287      *
 288      * @param cd {@code CompositeData} representing a {@code MemoryUsage}
 289      *
 290      * @throws IllegalArgumentException if {@code cd} does not
 291      *   represent a {@code MemoryUsage} with the attributes described
 292      *   above.
 293      *
 294      * @return a {@code MemoryUsage} object represented by {@code cd}
 295      *         if {@code cd} is not {@code null};
 296      *         {@code null} otherwise.
 297      */
 298     public static MemoryUsage from(CompositeData cd) {
 299         if (cd == null) {
 300             return null;
 301         }
 302 
 303         if (cd instanceof MemoryUsageCompositeData) {
 304             return ((MemoryUsageCompositeData) cd).getMemoryUsage();
 305         } else {
 306             return new MemoryUsage(cd);
 307         }
 308 
 309     }
 310 }