KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > lang > management > MemoryNotificationInfo


1 /*
2  * @(#)MemoryNotificationInfo.java 1.8 06/03/08
3  *
4  * Copyright 2006 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 JavaDoc;
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.html#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.html#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.8, 03/08/06
87  * @since 1.5
88  *
89  */
90 public class MemoryNotificationInfo {
91     private final String JavaDoc poolName;
92     private final MemoryUsage JavaDoc 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.html#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 JavaDoc 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.html#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 JavaDoc 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 JavaDoc poolName,
132                                   MemoryUsage JavaDoc usage,
133                                   long count) {
134         if (poolName == null) {
135             throw new NullPointerException JavaDoc("Null poolName");
136         }
137         if (usage == null) {
138             throw new NullPointerException JavaDoc("Null usage");
139         }
140
141         this.poolName = poolName;
142         this.usage = usage;
143         this.count = count;
144     }
145
146     MemoryNotificationInfo(CompositeData JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc from(CompositeData JavaDoc 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 JavaDoc(cd);
237         }
238     }
239 }
240
Popular Tags