001    /* MemoryUsage.java - Information on the usage of a memory pool.
002       Copyright (C) 2006 Free Software Foundation
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package java.lang.management;
039    
040    import javax.management.openmbean.CompositeData;
041    import javax.management.openmbean.CompositeType;
042    import javax.management.openmbean.SimpleType;
043    /**
044     * <p>
045     * Retains information on the usage of a particular memory
046     * pool, or heap/non-heap memory as a whole.  Memory usage
047     * is represented by four values (all in bytes):
048     * </p>
049     * <ul>
050     * <li><strong>Initial Level</strong>: This is the initial
051     * amount of memory allocated for the pool by the operating
052     * system.  This value may be undefined.</li>
053     * <li><strong>Used Level</strong>: This is the amount of
054     * memory currently in use.</li>
055     * <li><strong>Committed Level</strong>: This is the current
056     * amount of memory allocated for the pool by the operating
057     * system.  This value will always be equal to or greater than
058     * the current amount of memory in use.  It may drop below
059     * the initial amount, if the virtual machine judges this to
060     * be practical.</li>
061     * <li><strong>Maximum Level</strong>: This is the maximum
062     * amount of memory that may be allocated for the pool by
063     * the operating system.  Like the initial amount, it may
064     * be undefined.  If it is defined, it will be greater than
065     * or equal to the used and committed amounts and may change
066     * over time.  It is not guaranteed that the maximum amount
067     * of memory may actually be allocated to the pool.  For
068     * example, a request for an amount of memory greater than
069     * the current committed level, but less than the maximum,
070     * may still fail due to resources at the operating system
071     * level not being sufficient to fulfill the demand.</li>
072     * </ul>
073     *
074     * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
075     * @since 1.5
076     * @see MemoryMXBean
077     * @see MemoryPoolMXBean
078     */
079    public class MemoryUsage
080    {
081    
082      /**
083       * The initial amount of memory allocated.
084       */
085      private long init;
086    
087      /**
088       * The amount of memory used.
089       */
090      private long used;
091    
092      /**
093       * The amount of memory committed for use.
094       */
095      private long committed;
096    
097      /**
098       * The maximum amount of memory available.
099       */
100      private long maximum;
101    
102      /**
103       * Constructs a new {@link MemoryUsage} object with
104       * the specified allocation levels.
105       *
106       * @param init the initial amount of memory allocated,
107       *             or -1 if this value is undefined.  Must
108       *             be >= -1.
109       * @param used the amount of memory used.  Must be >= 0,
110       *             and <= committed.
111       * @param committed the amount of memory committed for use
112       *                  at present.  Must be >= 0 and <=
113       *                  maximum (if defined).
114       * @param maximum the maximum amount of memory that may be
115       *                used, or -1 if this value is undefined.
116       *                Must be >= -1.
117       * @throws IllegalArgumentException if the values break any
118       *                                  of the limits specified
119       *                                  above.
120       */
121      public MemoryUsage(long init, long used, long committed,
122                         long maximum)
123      {
124        if (init < -1)
125          throw new IllegalArgumentException("Initial value of "
126                                             + init + " is too small.");
127        if (used < 0)
128          throw new IllegalArgumentException("Used value of "
129                                             + used + " is too small.");
130        if (committed < 0)
131          throw new IllegalArgumentException("Committed value of "
132                                             + committed + " is too small.");
133        if (committed < used)
134          throw new IllegalArgumentException("Committed value of "
135                                             + committed + " is below "
136                                             + used + ", the amount used.");
137        if (maximum < -1)
138          throw new IllegalArgumentException("Maximum value of "
139                                             + maximum + " is too small.");
140        if (maximum != -1 && maximum < committed)
141          throw new IllegalArgumentException("Maximum value of "
142                                             + maximum + " is below "
143                                             + committed + ", the amount "
144                                             + "committed.");
145        this.init = init;
146        this.used = used;
147        this.committed = committed;
148        this.maximum = maximum;
149      }
150    
151      /**
152       * <p>
153       * Returns a {@link MemoryUsage} instance using the values
154       * given in the supplied
155       * {@link javax.management.openmbean.CompositeData} object.
156       * The composite data instance should contain the following
157       * attributes:
158       * </p>
159       * <ul>
160       * <li>init</li>
161       * <li>used</li>
162       * <li>committed</li>
163       * <li>max</li>
164       * </ul>
165       * <p>
166       * All should have the type, <code>java.lang.Long</code>.
167       * </p>
168       *
169       * @param data the composite data structure to take values from.
170       * @return a new instance containing the values from the
171       *         composite data structure, or <code>null</code>
172       *         if the data structure was also <code>null</code>.
173       * @throws IllegalArgumentException if the composite data structure
174       *                                  does not match the structure
175       *                                  outlined above, or the values
176       *                                  are invalid.
177       */
178      public static MemoryUsage from(CompositeData data)
179      {
180        if (data == null)
181          return null;
182        CompositeType type = data.getCompositeType();
183        ThreadInfo.checkAttribute(type, "Init", SimpleType.LONG);
184        ThreadInfo.checkAttribute(type, "Used", SimpleType.LONG);
185        ThreadInfo.checkAttribute(type, "Committed", SimpleType.LONG);
186        ThreadInfo.checkAttribute(type, "Max", SimpleType.LONG);
187        return new MemoryUsage(((Long) data.get("Init")).longValue(),
188                               ((Long) data.get("Used")).longValue(),
189                               ((Long) data.get("Committed")).longValue(),
190                               ((Long) data.get("Max")).longValue());
191      }
192    
193      /**
194       * Returns the amount of memory committed for use by this
195       * memory pool (in bytes).  This amount is guaranteed to
196       * be available, unlike the maximum.
197       *
198       * @return the committed amount of memory.
199       */
200      public long getCommitted()
201      {
202        return committed;
203      }
204    
205      /**
206       * Returns the initial amount of memory allocated to the
207       * pool (in bytes).  This method may return -1, if the
208       * value is undefined.
209       *
210       * @return the initial amount of memory allocated, or -1
211       *         if this value is undefined.
212       */
213      public long getInit()
214      {
215        return init;
216      }
217    
218      /**
219       * Returns the maximum amount of memory available for this
220       * pool (in bytes).  This amount is not guaranteed to
221       * actually be usable.  This method may return -1, if the
222       * value is undefined.
223       *
224       * @return the maximum amount of memory available, or -1
225       *         if this value is undefined.
226       */
227      public long getMax()
228      {
229        return maximum;
230      }
231    
232      /**
233       * Returns the amount of memory used (in bytes).
234       *
235       * @return the amount of used memory.
236       */
237      public long getUsed()
238      {
239        return used;
240      }
241    
242      /**
243       * Returns a {@link java.lang.String} representation of
244       * this {@link MemoryUsage} object.  This takes the form
245       * <code>java.lang.management.MemoryUsage[init=i, used=u,
246       * committed=c, maximum=m]</code>, where <code>i</code>
247       * is the initial level, <code>u</code> is the used level,
248       * <code>c</code> is the committed level and <code>m</code>
249       * is the maximum level.
250       *
251       * @return the string specified above.
252       */
253      public String toString()
254      {
255        int megabyte = 1024 * 1024;
256        return getClass().getName() +
257          "[init=" + init + " bytes (~" + (init / megabyte) +
258          "MB), used=" + used + " bytes (~" + (used / megabyte) +
259          "MB), committed=" + committed + " bytes (~" + (committed / megabyte) +
260          "MB), maximum=" + maximum + " bytes (~" + (maximum / megabyte) +
261          "MB)]";
262      }
263    
264    }