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
26package java.lang.management;
27
28import javax.management.openmbean.CompositeData;
29import 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 */
112public 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}
311