MemoryUsage


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 &gt committed</tt> even
58   *      if <tt>used &lt= 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 }
287
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags