1 /*
   2  * Copyright (c) 2003, 2013, 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 import javax.management.openmbean.CompositeData;
  28 import sun.management.MemoryNotifInfoCompositeData;
  29 
  30 /**
  31  * The information about a memory notification.
  32  *
  33  * <p>
  34  * A memory notification is emitted by {@link MemoryMXBean}
  35  * when the Java virtual machine detects that the memory usage
  36  * of a memory pool is exceeding a threshold value.
  37  * The notification emitted will contain the memory notification
  38  * information about the detected condition:
  39  * <ul>
  40  *   <li>The name of the memory pool.</li>
  41  *   <li>The memory usage of the memory pool when the notification
  42  *       was constructed.</li>
  43  *   <li>The number of times that the memory usage has crossed
  44  *       a threshold when the notification was constructed.
  45  *       For usage threshold notifications, this count will be the
  46  *       {@link MemoryPoolMXBean#getUsageThresholdCount usage threshold
  47  *       count}.  For collection threshold notifications,
  48  *       this count will be the
  49  *       {@link MemoryPoolMXBean#getCollectionUsageThresholdCount
  50  *       collection usage threshold count}.
  51  *       </li>
  52  * </ul>
  53  *
  54  * <p>
  55  * A {@link CompositeData CompositeData} representing
  56  * the <tt>MemoryNotificationInfo</tt> object
  57  * is stored in the
  58  * {@link javax.management.Notification#setUserData user data}
  59  * of a {@link javax.management.Notification notification}.
  60  * The {@link #from from} method is provided to convert from
  61  * a <tt>CompositeData</tt> to a <tt>MemoryNotificationInfo</tt>
  62  * object. For example:
  63  *
  64  * <blockquote><pre>
  65  *      Notification notif;
  66  *
  67  *      // receive the notification emitted by MemoryMXBean and set to notif
  68  *      ...
  69  *
  70  *      String notifType = notif.getType();
  71  *      if (notifType.equals(MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED) ||
  72  *          notifType.equals(MemoryNotificationInfo.MEMORY_COLLECTION_THRESHOLD_EXCEEDED)) {
  73  *          // retrieve the memory notification information
  74  *          CompositeData cd = (CompositeData) notif.getUserData();
  75  *          MemoryNotificationInfo info = MemoryNotificationInfo.from(cd);
  76  *          ....
  77  *      }
  78  * </pre></blockquote>
  79  *
  80  * <p>
  81  * The types of notifications emitted by <tt>MemoryMXBean</tt> are:
  82  * <ul>
  83  *   <li>A {@link #MEMORY_THRESHOLD_EXCEEDED
  84  *       usage threshold exceeded notification}.
  85  *       <br>This notification will be emitted when
  86  *       the memory usage of a memory pool is increased and has reached
  87  *       or exceeded its
  88  *       <a href="MemoryPoolMXBean.html#UsageThreshold"> usage threshold</a> value.
  89  *       Subsequent crossing of the usage threshold value does not cause
  90  *       further notification until the memory usage has returned
  91  *       to become less than the usage threshold value.
  92  *       <p></li>
  93  *   <li>A {@link #MEMORY_COLLECTION_THRESHOLD_EXCEEDED
  94  *       collection usage threshold exceeded notification}.
  95  *       <br>This notification will be emitted when
  96  *       the memory usage of a memory pool is greater than or equal to its
  97  *       <a href="MemoryPoolMXBean.html#CollectionThreshold">
  98  *       collection usage threshold</a> after the Java virtual machine
  99  *       has expended effort in recycling unused objects in that
 100  *       memory pool.</li>
 101  * </ul>
 102  *
 103  * @author  Mandy Chung
 104  * @since   1.5
 105  *
 106  */
 107 public class MemoryNotificationInfo {
 108     private final String poolName;
 109     private final MemoryUsage usage;
 110     private final long count;
 111 
 112     /**
 113      * Notification type denoting that
 114      * the memory usage of a memory pool has
 115      * reached or exceeded its
 116      * <a href="MemoryPoolMXBean.html#UsageThreshold"> usage threshold</a> value.
 117      * This notification is emitted by {@link MemoryMXBean}.
 118      * Subsequent crossing of the usage threshold value does not cause
 119      * further notification until the memory usage has returned
 120      * to become less than the usage threshold value.
 121      * The value of this notification type is
 122      * <tt>java.management.memory.threshold.exceeded</tt>.
 123      */
 124     public static final String MEMORY_THRESHOLD_EXCEEDED =
 125         "java.management.memory.threshold.exceeded";
 126 
 127     /**
 128      * Notification type denoting that
 129      * the memory usage of a memory pool is greater than or equal to its
 130      * <a href="MemoryPoolMXBean.html#CollectionThreshold">
 131      * collection usage threshold</a> after the Java virtual machine
 132      * has expended effort in recycling unused objects in that
 133      * memory pool.
 134      * This notification is emitted by {@link MemoryMXBean}.
 135      * The value of this notification type is
 136      * <tt>java.management.memory.collection.threshold.exceeded</tt>.
 137      */
 138     public static final String MEMORY_COLLECTION_THRESHOLD_EXCEEDED =
 139         "java.management.memory.collection.threshold.exceeded";
 140 
 141     /**
 142      * Constructs a <tt>MemoryNotificationInfo</tt> object.
 143      *
 144      * @param poolName The name of the memory pool which triggers this notification.
 145      * @param usage Memory usage of the memory pool.
 146      * @param count The threshold crossing count.
 147      */
 148     public MemoryNotificationInfo(String poolName,
 149                                   MemoryUsage usage,
 150                                   long count) {
 151         if (poolName == null) {
 152             throw new NullPointerException("Null poolName");
 153         }
 154         if (usage == null) {
 155             throw new NullPointerException("Null usage");
 156         }
 157 
 158         this.poolName = poolName;
 159         this.usage = usage;
 160         this.count = count;
 161     }
 162 
 163     MemoryNotificationInfo(CompositeData cd) {
 164         MemoryNotifInfoCompositeData.validateCompositeData(cd);
 165 
 166         this.poolName = MemoryNotifInfoCompositeData.getPoolName(cd);
 167         this.usage = MemoryNotifInfoCompositeData.getUsage(cd);
 168         this.count = MemoryNotifInfoCompositeData.getCount(cd);
 169     }
 170 
 171     /**
 172      * Returns the name of the memory pool that triggers this notification.
 173      * The memory pool usage has crossed a threshold.
 174      *
 175      * @return the name of the memory pool that triggers this notification.
 176      */
 177     public String getPoolName() {
 178         return poolName;
 179     }
 180 
 181     /**
 182      * Returns the memory usage of the memory pool
 183      * when this notification was constructed.
 184      *
 185      * @return the memory usage of the memory pool
 186      * when this notification was constructed.
 187      */
 188     public MemoryUsage getUsage() {
 189         return usage;
 190     }
 191 
 192     /**
 193      * Returns the number of times that the memory usage has crossed
 194      * a threshold when the notification was constructed.
 195      * For usage threshold notifications, this count will be the
 196      * {@link MemoryPoolMXBean#getUsageThresholdCount threshold
 197      * count}.  For collection threshold notifications,
 198      * this count will be the
 199      * {@link MemoryPoolMXBean#getCollectionUsageThresholdCount
 200      * collection usage threshold count}.
 201      *
 202      * @return the number of times that the memory usage has crossed
 203      * a threshold when the notification was constructed.
 204      */
 205     public long getCount() {
 206         return count;
 207     }
 208 
 209     /**
 210      * Returns a <tt>MemoryNotificationInfo</tt> object represented by the
 211      * given <tt>CompositeData</tt>.
 212      * The given <tt>CompositeData</tt> must contain
 213      * the following attributes:
 214      * <blockquote>
 215      * <table border summary="The attributes and the types the given CompositeData contains">
 216      * <tr>
 217      *   <th align=left>Attribute Name</th>
 218      *   <th align=left>Type</th>
 219      * </tr>
 220      * <tr>
 221      *   <td>poolName</td>
 222      *   <td><tt>java.lang.String</tt></td>
 223      * </tr>
 224      * <tr>
 225      *   <td>usage</td>
 226      *   <td><tt>javax.management.openmbean.CompositeData</tt></td>
 227      * </tr>
 228      * <tr>
 229      *   <td>count</td>
 230      *   <td><tt>java.lang.Long</tt></td>
 231      * </tr>
 232      * </table>
 233      * </blockquote>
 234      *
 235      * @param cd <tt>CompositeData</tt> representing a
 236      *           <tt>MemoryNotificationInfo</tt>
 237      *
 238      * @throws IllegalArgumentException if <tt>cd</tt> does not
 239      *   represent a <tt>MemoryNotificationInfo</tt> object.
 240      *
 241      * @return a <tt>MemoryNotificationInfo</tt> object represented
 242      *         by <tt>cd</tt> if <tt>cd</tt> is not <tt>null</tt>;
 243      *         <tt>null</tt> otherwise.
 244      */
 245     public static MemoryNotificationInfo from(CompositeData cd) {
 246         if (cd == null) {
 247             return null;
 248         }
 249 
 250         if (cd instanceof MemoryNotifInfoCompositeData) {
 251             return ((MemoryNotifInfoCompositeData) cd).getMemoryNotifInfo();
 252         } else {
 253             return new MemoryNotificationInfo(cd);
 254         }
 255     }
 256 }