001 /*
002 * Copyright 2003-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.lang.management;
027
028 import javax.management.openmbean.CompositeData;
029 import sun.management.MemoryUsageCompositeData;
030
031 /**
032 * A <tt>MemoryUsage</tt> object represents a snapshot of memory usage.
033 * Instances of the <tt>MemoryUsage</tt> class are usually constructed
034 * by methods that are used to obtain memory usage
035 * information about individual memory pool of the Java virtual machine or
036 * the heap or non-heap memory of the Java virtual machine as a whole.
037 *
038 * <p> A <tt>MemoryUsage</tt> object contains four values:
039 * <ul>
040 * <table>
041 * <tr>
042 * <td valign=top> <tt>init</tt> </td>
043 * <td valign=top> represents the initial amount of memory (in bytes) that
044 * the Java virtual machine requests from the operating system
045 * for memory management during startup. The Java virtual machine
046 * may request additional memory from the operating system and
047 * may also release memory to the system over time.
048 * The value of <tt>init</tt> may be undefined.
049 * </td>
050 * </tr>
051 * <tr>
052 * <td valign=top> <tt>used</tt> </td>
053 * <td valign=top> represents the amount of memory currently used (in bytes).
054 * </td>
055 * </tr>
056 * <tr>
057 * <td valign=top> <tt>committed</tt> </td>
058 * <td valign=top> represents the amount of memory (in bytes) that is
059 * guaranteed to be available for use by the Java virtual machine.
060 * The amount of committed memory may change over time (increase
061 * or decrease). The Java virtual machine may release memory to
062 * the system and <tt>committed</tt> could be less than <tt>init</tt>.
063 * <tt>committed</tt> will always be greater than
064 * or equal to <tt>used</tt>.
065 * </td>
066 * </tr>
067 * <tr>
068 * <td valign=top> <tt>max</tt> </td>
069 * <td valign=top> represents the maximum amount of memory (in bytes)
070 * that can be used for memory management. Its value may be undefined.
071 * The maximum amount of memory may change over time if defined.
072 * The amount of used and committed memory will always be less than
073 * or equal to <tt>max</tt> if <tt>max</tt> is defined.
074 * A memory allocation may fail if it attempts to increase the
075 * used memory such that <tt>used > committed</tt> even
076 * if <tt>used <= max</tt> would still be true (for example,
077 * when the system is low on virtual memory).
078 * </td>
079 * </tr>
080 * </table>
081 * </ul>
082 *
083 * Below is a picture showing an example of a memory pool:
084 * <p>
085 * <pre>
086 * +----------------------------------------------+
087 * +//////////////// | +
088 * +//////////////// | +
089 * +----------------------------------------------+
090 *
091 * |--------|
092 * init
093 * |---------------|
094 * used
095 * |---------------------------|
096 * committed
097 * |----------------------------------------------|
098 * max
099 * </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 * @version 1.23, 05/05/07
107 * @since 1.5
108 */
109 public class MemoryUsage {
110 private final long init;
111 private final long used;
112 private final long committed;
113 private final long max;
114
115 /**
116 * Constructs a <tt>MemoryUsage</tt> object.
117 *
118 * @param init the initial amount of memory in bytes that
119 * the Java virtual machine allocates;
120 * or <tt>-1</tt> if undefined.
121 * @param used the amount of used memory in bytes.
122 * @param committed the amount of committed memory in bytes.
123 * @param max the maximum amount of memory in bytes that
124 * can be used; or <tt>-1</tt> if undefined.
125 *
126 * @throws IllegalArgumentException if
127 * <ul>
128 * <li> the value of <tt>init</tt> or <tt>max</tt> is negative
129 * but not <tt>-1</tt>; or</li>
130 * <li> the value of <tt>used</tt> or <tt>committed</tt> is negative;
131 * or</li>
132 * <li> <tt>used</tt> is greater than the value of <tt>committed</tt>;
133 * or</li>
134 * <li> <tt>committed</tt> is greater than the value of <tt>max</tt>
135 * <tt>max</tt> if defined.</li>
136 * </ul>
137 */
138 public MemoryUsage(long init, long used, long committed, long max) {
139 if (init < -1) {
140 throw new IllegalArgumentException("init parameter = "
141 + init + " is negative but not -1.");
142 }
143 if (max < -1) {
144 throw new IllegalArgumentException("max parameter = " + max
145 + " is negative but not -1.");
146 }
147 if (used < 0) {
148 throw new IllegalArgumentException("used parameter = "
149 + used + " is negative.");
150 }
151 if (committed < 0) {
152 throw new IllegalArgumentException("committed parameter = "
153 + committed + " is negative.");
154 }
155 if (used > committed) {
156 throw new IllegalArgumentException("used = " + used
157 + " should be <= committed = " + committed);
158 }
159 if (max >= 0 && committed > max) {
160 throw new IllegalArgumentException("committed = "
161 + committed + " should be < max = " + max);
162 }
163
164 this .init = init;
165 this .used = used;
166 this .committed = committed;
167 this .max = max;
168 }
169
170 /**
171 * Constructs a <tt>MemoryUsage</tt> object from a
172 * {@link CompositeData CompositeData}.
173 */
174 private MemoryUsage(CompositeData cd) {
175 // validate the input composite data
176 MemoryUsageCompositeData.validateCompositeData(cd);
177
178 this .init = MemoryUsageCompositeData.getInit(cd);
179 this .used = MemoryUsageCompositeData.getUsed(cd);
180 this .committed = MemoryUsageCompositeData.getCommitted(cd);
181 this .max = MemoryUsageCompositeData.getMax(cd);
182 }
183
184 /**
185 * Returns the amount of memory in bytes that the Java virtual machine
186 * initially requests from the operating system for memory management.
187 * This method returns <tt>-1</tt> if the initial memory size is undefined.
188 *
189 * @return the initial size of memory in bytes;
190 * <tt>-1</tt> if undefined.
191 */
192 public long getInit() {
193 return init;
194 }
195
196 /**
197 * Returns the amount of used memory in bytes.
198 *
199 * @return the amount of used memory in bytes.
200 *
201 */
202 public long getUsed() {
203 return used;
204 };
205
206 /**
207 * Returns the amount of memory in bytes that is committed for
208 * the Java virtual machine to use. This amount of memory is
209 * guaranteed for the Java virtual machine to use.
210 *
211 * @return the amount of committed memory in bytes.
212 *
213 */
214 public long getCommitted() {
215 return committed;
216 };
217
218 /**
219 * Returns the maximum amount of memory in bytes that can be
220 * used for memory management. This method returns <tt>-1</tt>
221 * if the maximum memory size is undefined.
222 *
223 * <p> This amount of memory is not guaranteed to be available
224 * for memory management if it is greater than the amount of
225 * committed memory. The Java virtual machine may fail to allocate
226 * memory even if the amount of used memory does not exceed this
227 * maximum size.
228 *
229 * @return the maximum amount of memory in bytes;
230 * <tt>-1</tt> if undefined.
231 */
232 public long getMax() {
233 return max;
234 };
235
236 /**
237 * Returns a descriptive representation of this memory usage.
238 */
239 public String toString() {
240 StringBuffer buf = new StringBuffer();
241 buf.append("init = " + init + "(" + (init >> 10) + "K) ");
242 buf.append("used = " + used + "(" + (used >> 10) + "K) ");
243 buf.append("committed = " + committed + "(" + (committed >> 10)
244 + "K) ");
245 buf.append("max = " + max + "(" + (max >> 10) + "K)");
246 return buf.toString();
247 }
248
249 /**
250 * Returns a <tt>MemoryUsage</tt> object represented by the
251 * given <tt>CompositeData</tt>. The given <tt>CompositeData</tt>
252 * must contain the following attributes:
253 * <p>
254 * <blockquote>
255 * <table border>
256 * <tr>
257 * <th align=left>Attribute Name</th>
258 * <th align=left>Type</th>
259 * </tr>
260 * <tr>
261 * <td>init</td>
262 * <td><tt>java.lang.Long</tt></td>
263 * </tr>
264 * <tr>
265 * <td>used</td>
266 * <td><tt>java.lang.Long</tt></td>
267 * </tr>
268 * <tr>
269 * <td>committed</td>
270 * <td><tt>java.lang.Long</tt></td>
271 * </tr>
272 * <tr>
273 * <td>max</td>
274 * <td><tt>java.lang.Long</tt></td>
275 * </tr>
276 * </table>
277 * </blockquote>
278 *
279 * @param cd <tt>CompositeData</tt> representing a <tt>MemoryUsage</tt>
280 *
281 * @throws IllegalArgumentException if <tt>cd</tt> does not
282 * represent a <tt>MemoryUsage</tt> with the attributes described
283 * above.
284 *
285 * @return a <tt>MemoryUsage</tt> object represented by <tt>cd</tt>
286 * if <tt>cd</tt> is not <tt>null</tt>;
287 * <tt>null</tt> otherwise.
288 */
289 public static MemoryUsage from(CompositeData cd) {
290 if (cd == null) {
291 return null;
292 }
293
294 if (cd instanceof MemoryUsageCompositeData) {
295 return ((MemoryUsageCompositeData) cd).getMemoryUsage();
296 } else {
297 return new MemoryUsage(cd);
298 }
299
300 }
301 }
|