1. /*

  2.  * @(#)MemoryNotificationInfo.java	1.6 04/04/18

  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. import javax.management.openmbean.CompositeData;

  10. import sun.management.MemoryNotifInfoCompositeData;

  11. 

  12. /**

  13.  * The information about a memory notification.

  14.  *

  15.  * <p>

  16.  * A memory notification is emitted by {@link MemoryMXBean} 

  17.  * when the Java virtual machine detects that the memory usage 

  18.  * of a memory pool is exceeding a threshold value. 

  19.  * The notification emitted will contain the memory notification

  20.  * information about the detected condition:

  21.  * <ul>

  22.  *   <li>The name of the memory pool.</li>

  23.  *   <li>The memory usage of the memory pool when the notification 

  24.  *       was constructed.</li>

  25.  *   <li>The number of times that the memory usage has crossed 

  26.  *       a threshold when the notification was constructed.

  27.  *       For usage threshold notifications, this count will be the 

  28.  *       {@link MemoryPoolMXBean#getUsageThresholdCount usage threshold

  29.  *       count}.  For collection threshold notifications, 

  30.  *       this count will be the

  31.  *       {@link MemoryPoolMXBean#getCollectionUsageThresholdCount

  32.  *       collection usage threshold count}.

  33.  *       </li>

  34.  * </ul>

  35.  *

  36.  * <p>

  37.  * A {@link CompositeData CompositeData} representing 

  38.  * the <tt>MemoryNotificationInfo</tt> object 

  39.  * is stored in the

  40.  * {@link javax.management.Notification#setUserData user data} 

  41.  * of a {@link javax.management.Notification notification}.

  42.  * The {@link #from from} method is provided to convert from 

  43.  * a <tt>CompositeData</tt> to a <tt>MemoryNotificationInfo</tt> 

  44.  * object. For example:

  45.  *

  46.  * <blockquote><pre>

  47.  *      Notification notif;

  48.  *

  49.  *      // receive the notification emitted by MemoryMXBean and set to notif

  50.  *      ...

  51.  *            

  52.  *      String notifType = notif.getType();

  53.  *      if (notifType.equals(MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED) ||

  54.  *          notifType.equals(MemoryNotificationInfo.MEMORY_COLLECTION_THRESHOLD_EXCEEDED)) {

  55.  *          // retrieve the memory notification information

  56.  *          CompositeData cd = (CompositeData) notif.getUserData();

  57.  *          MemoryNotificationInfo info = MemoryNotificationInfo.from(cd);

  58.  *          ....

  59.  *      }  

  60.  * </pre></blockquote>

  61.  *

  62.  * <p>

  63.  * The types of notifications emitted by <tt>MemoryMXBean</tt> are:

  64.  * <ul> 

  65.  *   <li>A {@link #MEMORY_THRESHOLD_EXCEEDED 

  66.  *       usage threshold exceeded notification}.

  67.  *       <br>This notification will be emitted when

  68.  *       the memory usage of a memory pool is increased and has reached 

  69.  *       or exceeded its 

  70.  *       <a href="MemoryPoolMXBean#UsageThreshold"> usage threshold</a> value.

  71.  *       Subsequent crossing of the usage threshold value does not cause

  72.  *       further notification until the memory usage has returned

  73.  *       to become less than the usage threshold value.

  74.  *       <p></li>

  75.  *   <li>A {@link #MEMORY_COLLECTION_THRESHOLD_EXCEEDED

  76.  *       collection usage threshold exceeded notification}.

  77.  *       <br>This notification will be emitted when

  78.  *       the memory usage of a memory pool is greater than or equal to its

  79.  *       <a href="MemoryPoolMXBean#CollectionThreshold">

  80.  *       collection usage threshold</a> after the Java virtual machine

  81.  *       has expended effort in recycling unused objects in that

  82.  *       memory pool.</li> 

  83.  * </ul>

  84.  *

  85.  * @author  Mandy Chung

  86.  * @version 1.6, 04/18/04

  87.  * @since   1.5

  88.  *

  89.  */

  90. public class MemoryNotificationInfo {

  91.     private final String poolName;

  92.     private final MemoryUsage usage;

  93.     private final long count;

  94. 

  95.     /**

  96.      * Notification type denoting that 

  97.      * the memory usage of a memory pool has

  98.      * reached or exceeded its

  99.      * <a href="MemoryPoolMXBean#UsageThreshold"> usage threshold</a> value.

  100.      * This notification is emitted by {@link MemoryMXBean}.

  101.      * Subsequent crossing of the usage threshold value does not cause

  102.      * further notification until the memory usage has returned

  103.      * to become less than the usage threshold value.

  104.      * The value of this notification type is 

  105.      * <tt>java.management.memory.threshold.exceeded</tt>.

  106.      */

  107.     public static final String MEMORY_THRESHOLD_EXCEEDED = 

  108.         "java.management.memory.threshold.exceeded";

  109. 

  110.     /**

  111.      * Notification type denoting that 

  112.      * the memory usage of a memory pool is greater than or equal to its

  113.      * <a href="MemoryPoolMXBean#CollectionThreshold">

  114.      * collection usage threshold</a> after the Java virtual machine

  115.      * has expended effort in recycling unused objects in that

  116.      * memory pool. 

  117.      * This notification is emitted by {@link MemoryMXBean}.

  118.      * The value of this notification type is 

  119.      * <tt>java.management.memory.collection.threshold.exceeded</tt>.

  120.      */

  121.     public static final String MEMORY_COLLECTION_THRESHOLD_EXCEEDED =

  122.         "java.management.memory.collection.threshold.exceeded";

  123. 

  124.     /**

  125.      * Constructs a <tt>MemoryNotificationInfo</tt> object.

  126.      *

  127.      * @param poolName The name of the memory pool which triggers this notification.

  128.      * @param usage Memory usage of the memory pool.

  129.      * @param count The threshold crossing count.

  130.      */

  131.     public MemoryNotificationInfo(String poolName,

  132.                                   MemoryUsage usage,

  133.                                   long count) {

  134.         if (poolName == null) {

  135.             throw new NullPointerException("Null poolName");

  136.         }

  137.         if (usage == null) {

  138.             throw new NullPointerException("Null usage");

  139.         }

  140. 

  141.         this.poolName = poolName;

  142.         this.usage = usage;

  143.         this.count = count;

  144.     }

  145. 

  146.     MemoryNotificationInfo(CompositeData cd) {

  147.         MemoryNotifInfoCompositeData.validateCompositeData(cd);

  148. 

  149.         this.poolName = MemoryNotifInfoCompositeData.getPoolName(cd);

  150.         this.usage = MemoryNotifInfoCompositeData.getUsage(cd);

  151.         this.count = MemoryNotifInfoCompositeData.getCount(cd);

  152.     }

  153. 

  154.     /**

  155.      * Returns the name of the memory pool that triggers this notification.

  156.      * The memory pool usage has crossed a threshold.

  157.      *

  158.      * @return the name of the memory pool that triggers this notification.

  159.      */

  160.     public String getPoolName() {

  161.         return poolName;

  162.     }

  163. 

  164.     /**

  165.      * Returns the memory usage of the memory pool

  166.      * when this notification was constructed.

  167.      *

  168.      * @return the memory usage of the memory pool  

  169.      * when this notification was constructed.

  170.      */

  171.     public MemoryUsage getUsage() {

  172.         return usage;

  173.     }

  174.  

  175.     /**

  176.      * Returns the number of times that the memory usage has crossed 

  177.      * a threshold when the notification was constructed.

  178.      * For usage threshold notifications, this count will be the 

  179.      * {@link MemoryPoolMXBean#getUsageThresholdCount threshold

  180.      * count}.  For collection threshold notifications, 

  181.      * this count will be the

  182.      * {@link MemoryPoolMXBean#getCollectionUsageThresholdCount

  183.      * collection usage threshold count}.

  184.      *

  185.      * @return the number of times that the memory usage has crossed 

  186.      * a threshold when the notification was constructed.

  187.      */

  188.     public long getCount() {

  189.         return count;

  190.     }

  191. 

  192.     /**

  193.      * Returns a <tt>MemoryNotificationInfo</tt> object represented by the

  194.      * given <tt>CompositeData</tt>.

  195.      * The given <tt>CompositeData</tt> must contain

  196.      * the following attributes:

  197.      * <blockquote>

  198.      * <table border>

  199.      * <tr>

  200.      *   <th align=left>Attribute Name</th>

  201.      *   <th align=left>Type</th>

  202.      * </tr>

  203.      * <tr>

  204.      *   <td>poolName</td>

  205.      *   <td><tt>java.lang.String</tt></td>

  206.      * </tr>

  207.      * <tr>

  208.      *   <td>usage</td>

  209.      *   <td><tt>javax.management.openmbean.CompositeData</tt></td>

  210.      * </tr>

  211.      * <tr>

  212.      *   <td>count</td>

  213.      *   <td><tt>java.lang.Long</tt></td>

  214.      * </tr>

  215.      * </table>

  216.      * </blockquote>

  217.      *

  218.      * @param cd <tt>CompositeData</tt> representing a

  219.      *           <tt>MemoryNotificationInfo</tt>

  220.      *

  221.      * @throws IllegalArgumentException if <tt>cd</tt> does not

  222.      *   represent a <tt>MemoryNotificationInfo</tt> object.

  223.      *

  224.      * @return a <tt>MemoryNotificationInfo</tt> object represented 

  225.      *         by <tt>cd</tt> if <tt>cd</tt> is not <tt>null</tt>

  226.      *         <tt>null</tt> otherwise.

  227.      */

  228.     public static MemoryNotificationInfo from(CompositeData cd) {

  229.         if (cd == null) {

  230.             return null;

  231.         }

  232. 

  233.         if (cd instanceof MemoryNotifInfoCompositeData) {

  234.             return ((MemoryNotifInfoCompositeData) cd).getMemoryNotifInfo();

  235.         } else {

  236.             return new MemoryNotificationInfo(cd);

  237.         }

  238.     }

  239. }