View Javadoc
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 }