1 /*
2 * Copyright (c) 2003, 2004, 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 <tt>MemoryUsage</tt> object represents a snapshot of memory usage.
33 * Instances of the <tt>MemoryUsage</tt> 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 <tt>MemoryUsage</tt> object contains four values:
39 * <ul>
40 * <table>
41 * <tr>
42 * <td valign=top> <tt>init</tt> </td>
43 * <td valign=top> represents the initial amount of memory (in bytes) that
44 * the Java virtual machine requests from the operating system
45 * for memory management during startup. The Java virtual machine
46 * may request additional memory from the operating system and
47 * may also release memory to the system over time.
48 * The value of <tt>init</tt> may be undefined.
49 * </td>
50 * </tr>
51 * <tr>
52 * <td valign=top> <tt>used</tt> </td>
53 * <td valign=top> represents the amount of memory currently used (in bytes).
54 * </td>
55 * </tr>
56 * <tr>
57 * <td valign=top> <tt>committed</tt> </td>
58 * <td valign=top> represents the amount of memory (in bytes) that is
59 * guaranteed to be available for use by the Java virtual machine.
60 * The amount of committed memory may change over time (increase
61 * or decrease). The Java virtual machine may release memory to
62 * the system and <tt>committed</tt> could be less than <tt>init</tt>.
63 * <tt>committed</tt> will always be greater than
64 * or equal to <tt>used</tt>.
65 * </td>
66 * </tr>
67 * <tr>
68 * <td valign=top> <tt>max</tt> </td>
69 * <td valign=top> represents the maximum amount of memory (in bytes)
70 * that can be used for memory management. Its value may be undefined.
71 * The maximum amount of memory may change over time if defined.
72 * The amount of used and committed memory will always be less than
73 * or equal to <tt>max</tt> if <tt>max</tt> is defined.
74 * A memory allocation may fail if it attempts to increase the
75 * used memory such that <tt>used > committed</tt> even
76 * if <tt>used <= max</tt> would still be true (for example,
77 * when the system is low on virtual memory).
78 * </td>
79 * </tr>
80 * </table>
81 * </ul>
82 *
83 * Below is a picture showing an example of a memory pool:
84 * <p>
85 * <pre>
86 * +----------------------------------------------+
87 * +//////////////// | +
88 * +//////////////// | +
89 * +----------------------------------------------+
90 *
91 * |--------|
92 * init
93 * |---------------|
94 * used
95 * |---------------------------|
96 * committed
97 * |----------------------------------------------|
98 * max
99 * </pre>
100 *
101 * <h4>MXBean Mapping</h4>
102 * <tt>MemoryUsage</tt> is mapped to a {@link CompositeData CompositeData}
103 * with attributes as specified in the {@link #from from} method.
104 *
105 * @author Mandy Chung
106 * @since 1.5
107 */
108 public class MemoryUsage {
109 private final long init;
110 private final long used;
111 private final long committed;
112 private final long max;
113
114 /**
115 * Constructs a <tt>MemoryUsage</tt> object.
116 *
117 * @param init the initial amount of memory in bytes that
118 * the Java virtual machine allocates;
119 * or <tt>-1</tt> if undefined.
120 * @param used the amount of used memory in bytes.
121 * @param committed the amount of committed memory in bytes.
122 * @param max the maximum amount of memory in bytes that
123 * can be used; or <tt>-1</tt> if undefined.
124 *
125 * @throws IllegalArgumentException if
126 * <ul>
127 * <li> the value of <tt>init</tt> or <tt>max</tt> is negative
128 * but not <tt>-1</tt>; or</li>
129 * <li> the value of <tt>used</tt> or <tt>committed</tt> is negative;
130 * or</li>
131 * <li> <tt>used</tt> is greater than the value of <tt>committed</tt>;
132 * or</li>
133 * <li> <tt>committed</tt> is greater than the value of <tt>max</tt>
134 * <tt>max</tt> if defined.</li>
135 * </ul>
136 */
137 public MemoryUsage(long init,
138 long used,
139 long committed,
140 long max) {
141 if (init < -1) {
142 throw new IllegalArgumentException( "init parameter = " +
143 init + " is negative but not -1.");
144 }
145 if (max < -1) {
146 throw new IllegalArgumentException( "max parameter = " +
147 max + " is negative but not -1.");
148 }
149 if (used < 0) {
150 throw new IllegalArgumentException( "used parameter = " +
151 used + " is negative.");
152 }
153 if (committed < 0) {
154 throw new IllegalArgumentException( "committed parameter = " +
155 committed + " is negative.");
156 }
157 if (used > committed) {
158 throw new IllegalArgumentException( "used = " + used +
159 " should be <= committed = " + committed);
160 }
161 if (max >= 0 && committed > max) {
162 throw new IllegalArgumentException( "committed = " + committed +
163 " should be < max = " + max);
164 }
165
166 this.init = init;
167 this.used = used;
168 this.committed = committed;
169 this.max = max;
170 }
171
172 /**
173 * Constructs a <tt>MemoryUsage</tt> object from a
174 * {@link CompositeData CompositeData}.
175 */
176 private MemoryUsage(CompositeData cd) {
177 // validate the input composite data
178 MemoryUsageCompositeData.validateCompositeData(cd);
179
180 this.init = MemoryUsageCompositeData.getInit(cd);
181 this.used = MemoryUsageCompositeData.getUsed(cd);
182 this.committed = MemoryUsageCompositeData.getCommitted(cd);
183 this.max = MemoryUsageCompositeData.getMax(cd);
184 }
185
186 /**
187 * Returns the amount of memory in bytes that the Java virtual machine
188 * initially requests from the operating system for memory management.
189 * This method returns <tt>-1</tt> if the initial memory size is undefined.
190 *
191 * @return the initial size of memory in bytes;
192 * <tt>-1</tt> if undefined.
193 */
194 public long getInit() {
195 return init;
196 }
197
198 /**
199 * Returns the amount of used memory in bytes.
200 *
201 * @return the amount of used memory in bytes.
202 *
203 */
204 public long getUsed() {
205 return used;
206 };
207
208 /**
209 * Returns the amount of memory in bytes that is committed for
210 * the Java virtual machine to use. This amount of memory is
211 * guaranteed for the Java virtual machine to use.
212 *
213 * @return the amount of committed memory in bytes.
214 *
215 */
216 public long getCommitted() {
217 return committed;
218 };
219
220 /**
221 * Returns the maximum amount of memory in bytes that can be
222 * used for memory management. This method returns <tt>-1</tt>
223 * if the maximum memory size is undefined.
224 *
225 * <p> This amount of memory is not guaranteed to be available
226 * for memory management if it is greater than the amount of
227 * committed memory. The Java virtual machine may fail to allocate
228 * memory even if the amount of used memory does not exceed this
229 * maximum size.
230 *
231 * @return the maximum amount of memory in bytes;
232 * <tt>-1</tt> if undefined.
233 */
234 public long getMax() {
235 return max;
236 };
237
238 /**
239 * Returns a descriptive representation of this memory usage.
240 */
241 public String toString() {
242 StringBuffer buf = new StringBuffer();
243 buf.append("init = " + init + "(" + (init >> 10) + "K) ");
244 buf.append("used = " + used + "(" + (used >> 10) + "K) ");
245 buf.append("committed = " + committed + "(" +
246 (committed >> 10) + "K) " );
247 buf.append("max = " + max + "(" + (max >> 10) + "K)");
248 return buf.toString();
249 }
250
251 /**
252 * Returns a <tt>MemoryUsage</tt> object represented by the
253 * given <tt>CompositeData</tt>. The given <tt>CompositeData</tt>
254 * must contain the following attributes:
255 * <p>
256 * <blockquote>
257 * <table border>
258 * <tr>
259 * <th align=left>Attribute Name</th>
260 * <th align=left>Type</th>
261 * </tr>
262 * <tr>
263 * <td>init</td>
264 * <td><tt>java.lang.Long</tt></td>
265 * </tr>
266 * <tr>
267 * <td>used</td>
268 * <td><tt>java.lang.Long</tt></td>
269 * </tr>
270 * <tr>
271 * <td>committed</td>
272 * <td><tt>java.lang.Long</tt></td>
273 * </tr>
274 * <tr>
275 * <td>max</td>
276 * <td><tt>java.lang.Long</tt></td>
277 * </tr>
278 * </table>
279 * </blockquote>
280 *
281 * @param cd <tt>CompositeData</tt> representing a <tt>MemoryUsage</tt>
282 *
283 * @throws IllegalArgumentException if <tt>cd</tt> does not
284 * represent a <tt>MemoryUsage</tt> with the attributes described
285 * above.
286 *
287 * @return a <tt>MemoryUsage</tt> object represented by <tt>cd</tt>
288 * if <tt>cd</tt> is not <tt>null</tt>;
289 * <tt>null</tt> otherwise.
290 */
291 public static MemoryUsage from(CompositeData cd) {
292 if (cd == null) {
293 return null;
294 }
295
296 if (cd instanceof MemoryUsageCompositeData) {
297 return ((MemoryUsageCompositeData) cd).getMemoryUsage();
298 } else {
299 return new MemoryUsage(cd);
300 }
301
302 }
303 }