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 }