001 /*
002 * Copyright 2003-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.lang.management;
027
028 import javax.management.openmbean.CompositeData;
029 import sun.management.MemoryNotifInfoCompositeData;
030
031 /**
032 * The information about a memory notification.
033 *
034 * <p>
035 * A memory notification is emitted by {@link MemoryMXBean}
036 * when the Java virtual machine detects that the memory usage
037 * of a memory pool is exceeding a threshold value.
038 * The notification emitted will contain the memory notification
039 * information about the detected condition:
040 * <ul>
041 * <li>The name of the memory pool.</li>
042 * <li>The memory usage of the memory pool when the notification
043 * was constructed.</li>
044 * <li>The number of times that the memory usage has crossed
045 * a threshold when the notification was constructed.
046 * For usage threshold notifications, this count will be the
047 * {@link MemoryPoolMXBean#getUsageThresholdCount usage threshold
048 * count}. For collection threshold notifications,
049 * this count will be the
050 * {@link MemoryPoolMXBean#getCollectionUsageThresholdCount
051 * collection usage threshold count}.
052 * </li>
053 * </ul>
054 *
055 * <p>
056 * A {@link CompositeData CompositeData} representing
057 * the <tt>MemoryNotificationInfo</tt> object
058 * is stored in the
059 * {@link javax.management.Notification#setUserData user data}
060 * of a {@link javax.management.Notification notification}.
061 * The {@link #from from} method is provided to convert from
062 * a <tt>CompositeData</tt> to a <tt>MemoryNotificationInfo</tt>
063 * object. For example:
064 *
065 * <blockquote><pre>
066 * Notification notif;
067 *
068 * // receive the notification emitted by MemoryMXBean and set to notif
069 * ...
070 *
071 * String notifType = notif.getType();
072 * if (notifType.equals(MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED) ||
073 * notifType.equals(MemoryNotificationInfo.MEMORY_COLLECTION_THRESHOLD_EXCEEDED)) {
074 * // retrieve the memory notification information
075 * CompositeData cd = (CompositeData) notif.getUserData();
076 * MemoryNotificationInfo info = MemoryNotificationInfo.from(cd);
077 * ....
078 * }
079 * </pre></blockquote>
080 *
081 * <p>
082 * The types of notifications emitted by <tt>MemoryMXBean</tt> are:
083 * <ul>
084 * <li>A {@link #MEMORY_THRESHOLD_EXCEEDED
085 * usage threshold exceeded notification}.
086 * <br>This notification will be emitted when
087 * the memory usage of a memory pool is increased and has reached
088 * or exceeded its
089 * <a href="MemoryPoolMXBean.html#UsageThreshold"> usage threshold</a> value.
090 * Subsequent crossing of the usage threshold value does not cause
091 * further notification until the memory usage has returned
092 * to become less than the usage threshold value.
093 * <p></li>
094 * <li>A {@link #MEMORY_COLLECTION_THRESHOLD_EXCEEDED
095 * collection usage threshold exceeded notification}.
096 * <br>This notification will be emitted when
097 * the memory usage of a memory pool is greater than or equal to its
098 * <a href="MemoryPoolMXBean.html#CollectionThreshold">
099 * collection usage threshold</a> after the Java virtual machine
100 * has expended effort in recycling unused objects in that
101 * memory pool.</li>
102 * </ul>
103 *
104 * @author Mandy Chung
105 * @version 1.14, 05/05/07
106 * @since 1.5
107 *
108 */
109 public class MemoryNotificationInfo {
110 private final String poolName;
111 private final MemoryUsage usage;
112 private final long count;
113
114 /**
115 * Notification type denoting that
116 * the memory usage of a memory pool has
117 * reached or exceeded its
118 * <a href="MemoryPoolMXBean.html#UsageThreshold"> usage threshold</a> value.
119 * This notification is emitted by {@link MemoryMXBean}.
120 * Subsequent crossing of the usage threshold value does not cause
121 * further notification until the memory usage has returned
122 * to become less than the usage threshold value.
123 * The value of this notification type is
124 * <tt>java.management.memory.threshold.exceeded</tt>.
125 */
126 public static final String MEMORY_THRESHOLD_EXCEEDED = "java.management.memory.threshold.exceeded";
127
128 /**
129 * Notification type denoting that
130 * the memory usage of a memory pool is greater than or equal to its
131 * <a href="MemoryPoolMXBean.html#CollectionThreshold">
132 * collection usage threshold</a> after the Java virtual machine
133 * has expended effort in recycling unused objects in that
134 * memory pool.
135 * This notification is emitted by {@link MemoryMXBean}.
136 * The value of this notification type is
137 * <tt>java.management.memory.collection.threshold.exceeded</tt>.
138 */
139 public static final String MEMORY_COLLECTION_THRESHOLD_EXCEEDED = "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, MemoryUsage usage,
149 long count) {
150 if (poolName == null) {
151 throw new NullPointerException("Null poolName");
152 }
153 if (usage == null) {
154 throw new NullPointerException("Null usage");
155 }
156
157 this .poolName = poolName;
158 this .usage = usage;
159 this .count = count;
160 }
161
162 MemoryNotificationInfo(CompositeData cd) {
163 MemoryNotifInfoCompositeData.validateCompositeData(cd);
164
165 this .poolName = MemoryNotifInfoCompositeData.getPoolName(cd);
166 this .usage = MemoryNotifInfoCompositeData.getUsage(cd);
167 this .count = MemoryNotifInfoCompositeData.getCount(cd);
168 }
169
170 /**
171 * Returns the name of the memory pool that triggers this notification.
172 * The memory pool usage has crossed a threshold.
173 *
174 * @return the name of the memory pool that triggers this notification.
175 */
176 public String getPoolName() {
177 return poolName;
178 }
179
180 /**
181 * Returns the memory usage of the memory pool
182 * when this notification was constructed.
183 *
184 * @return the memory usage of the memory pool
185 * when this notification was constructed.
186 */
187 public MemoryUsage getUsage() {
188 return usage;
189 }
190
191 /**
192 * Returns the number of times that the memory usage has crossed
193 * a threshold when the notification was constructed.
194 * For usage threshold notifications, this count will be the
195 * {@link MemoryPoolMXBean#getUsageThresholdCount threshold
196 * count}. For collection threshold notifications,
197 * this count will be the
198 * {@link MemoryPoolMXBean#getCollectionUsageThresholdCount
199 * collection usage threshold count}.
200 *
201 * @return the number of times that the memory usage has crossed
202 * a threshold when the notification was constructed.
203 */
204 public long getCount() {
205 return count;
206 }
207
208 /**
209 * Returns a <tt>MemoryNotificationInfo</tt> object represented by the
210 * given <tt>CompositeData</tt>.
211 * The given <tt>CompositeData</tt> must contain
212 * the following attributes:
213 * <blockquote>
214 * <table border>
215 * <tr>
216 * <th align=left>Attribute Name</th>
217 * <th align=left>Type</th>
218 * </tr>
219 * <tr>
220 * <td>poolName</td>
221 * <td><tt>java.lang.String</tt></td>
222 * </tr>
223 * <tr>
224 * <td>usage</td>
225 * <td><tt>javax.management.openmbean.CompositeData</tt></td>
226 * </tr>
227 * <tr>
228 * <td>count</td>
229 * <td><tt>java.lang.Long</tt></td>
230 * </tr>
231 * </table>
232 * </blockquote>
233 *
234 * @param cd <tt>CompositeData</tt> representing a
235 * <tt>MemoryNotificationInfo</tt>
236 *
237 * @throws IllegalArgumentException if <tt>cd</tt> does not
238 * represent a <tt>MemoryNotificationInfo</tt> object.
239 *
240 * @return a <tt>MemoryNotificationInfo</tt> object represented
241 * by <tt>cd</tt> if <tt>cd</tt> is not <tt>null</tt>;
242 * <tt>null</tt> otherwise.
243 */
244 public static MemoryNotificationInfo from(CompositeData cd) {
245 if (cd == null) {
246 return null;
247 }
248
249 if (cd instanceof MemoryNotifInfoCompositeData) {
250 return ((MemoryNotifInfoCompositeData) cd)
251 .getMemoryNotifInfo();
252 } else {
253 return new MemoryNotificationInfo(cd);
254 }
255 }
256 }
|