1 /*
2 * Copyright (c) 2011, 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 com.sun.management;
27
28 import javax.management.Notification;
29 import javax.management.openmbean.CompositeData;
30 import javax.management.openmbean.CompositeDataView;
31 import javax.management.openmbean.CompositeType;
32 import java.util.Collection;
33 import java.util.Collections;
34 import sun.management.GarbageCollectionNotifInfoCompositeData;
35
36 /**
37 * The information about a garbage collection
38 *
39 * <p>
40 * A garbage collection notification is emitted by {@link GarbageCollectorMXBean}
41 * when the Java virtual machine completes a garbage collection action
42 * The notification emitted will contain the garbage collection notification
43 * information about the status of the memory:
44 * <u1>
45 * <li>The name of the garbage collector used perform the collection.</li>
46 * <li>The action performed by the garbage collector.</li>
47 * <li>The cause of the garbage collection action.</li>
48 * <li>A {@link GcInfo} object containing some statistics about the GC cycle
49 (start time, end time) and the memory usage before and after
50 the GC cycle.</li>
51 * </u1>
52 *
53 * <p>
54 * A {@link CompositeData CompositeData} representing
55 * the {@code GarbageCollectionNotificationInfo} object
56 * is stored in the
57 * {@linkplain javax.management.Notification#setUserData userdata}
58 * of a {@linkplain javax.management.Notification notification}.
59 * The {@link #from from} method is provided to convert from
60 * a {@code CompositeData} to a {@code GarbageCollectionNotificationInfo}
61 * object. For example:
62 *
63 * <blockquote><pre>
64 * Notification notif;
65 *
66 * // receive the notification emitted by a GarbageCollectorMXBean and set to notif
67 * ...
68 *
69 * String notifType = notif.getType();
70 * if (notifType.equals(GarbageCollectionNotificationInfo.GARBAGE_COLLECTION_NOTIFICATION)) {
71 * // retrieve the garbage collection notification information
72 * CompositeData cd = (CompositeData) notif.getUserData();
73 * GarbageCollectionNotificationInfo info = GarbageCollectionNotificationInfo.from(cd);
74 * ....
75 * }
76 * </pre></blockquote>
77 *
78 * <p>
79 * The type of the notification emitted by a {@code GarbageCollectorMXBean} is:
80 * <ul>
81 * <li>A {@linkplain #GARBAGE_COLLECTION_NOTIFICATION garbage collection notification}.
82 * <br>Used by every notification emitted by the garbage collector, the details about
83 * the notification are provided in the {@linkplain #getGcAction action} String
84 * <p></li>
85 * </ul>
86 **/
87
88 public class GarbageCollectionNotificationInfo implements CompositeDataView {
89
90 private final String gcName;
91 private final String gcAction;
92 private final String gcCause;
93 private final GcInfo gcInfo;
94 private final CompositeData cdata;
95
96 /**
97 * Notification type denoting that
98 * the Java virtual machine has completed a garbage collection cycle.
99 * This notification is emitted by a {@link GarbageCollectorMXBean}.
100 * The value of this notification type is
101 * {@code com.sun.management.gc.notification}.
102 */
103 public static final String GARBAGE_COLLECTION_NOTIFICATION =
104 "com.sun.management.gc.notification";
105
106 /**
107 * Constructs a {@code GarbageCollectionNotificationInfo} object.
108 *
109 * @param gcName The name of the garbage collector used to perform the collection
110 * @param gcAction The name of the action performed by the garbage collector
111 * @param gcCause The cause the garbage collection action
112 * @param gcInfo a GcInfo object providing statistics about the GC cycle
113 */
114 public GarbageCollectionNotificationInfo(String gcName,
115 String gcAction,
116 String gcCause,
117 GcInfo gcInfo) {
118 if (gcName == null) {
119 throw new NullPointerException("Null gcName");
120 }
121 if (gcAction == null) {
122 throw new NullPointerException("Null gcAction");
123 }
124 if (gcCause == null) {
125 throw new NullPointerException("Null gcCause");
126 }
127 this.gcName = gcName;
128 this.gcAction = gcAction;
129 this.gcCause = gcCause;
130 this.gcInfo = gcInfo;
131 this.cdata = new GarbageCollectionNotifInfoCompositeData(this);
132 }
133
134 GarbageCollectionNotificationInfo(CompositeData cd) {
135 GarbageCollectionNotifInfoCompositeData.validateCompositeData(cd);
136
137 this.gcName = GarbageCollectionNotifInfoCompositeData.getGcName(cd);
138 this.gcAction = GarbageCollectionNotifInfoCompositeData.getGcAction(cd);
139 this.gcCause = GarbageCollectionNotifInfoCompositeData.getGcCause(cd);
140 this.gcInfo = GarbageCollectionNotifInfoCompositeData.getGcInfo(cd);
141 this.cdata = cd;
142 }
143
144 /**
145 * Returns the name of the garbage collector used to perform the collection
146 *
147 * @return the name of the garbage collector used to perform the collection
148 */
149 public String getGcName() {
150 return gcName;
151 }
152
153 /**
154 * Returns the action of the performed by the garbage collector
155 *
156 * @return the the action of the performed by the garbage collector
157 */
158 public String getGcAction() {
159 return gcAction;
160 }
161
162 /**
163 * Returns the cause the garbage collection
164 *
165 * @return the the cause the garbage collection
166 */
167 public String getGcCause() {
168 return gcCause;
169 }
170
171 /**
172 * Returns the GC information related to the last garbage collection
173 *
174 * @return the GC information related to the
175 * last garbage collection
176 */
177 public GcInfo getGcInfo() {
178 return gcInfo;
179 }
180
181 /**
182 * Returns a {@code GarbageCollectionNotificationInfo} object represented by the
183 * given {@code CompositeData}.
184 * The given {@code CompositeData} must contain
185 * the following attributes:
186 * <blockquote>
187 * <table border>
188 * <tr>
189 * <th align=left>Attribute Name</th>
190 * <th align=left>Type</th>
191 * </tr>
192 * <tr>
193 * <td>gcName</td>
194 * <td>{@code java.lang.String}</td>
195 * </tr>
196 * <tr>
197 * <td>gcAction</td>
198 * <td>{@code java.lang.String}</td>
199 * </tr>
200 * <tr>
201 * <td>gcCause</td>
202 * <td>{@code java.lang.String}</td>
203 * </tr>
204 * <tr>
205 * <td>gcInfo</td>
206 * <td>{@code javax.management.openmbean.CompositeData}</td>
207 * </tr>
208 * </table>
209 * </blockquote>
210 *
211 * @param cd {@code CompositeData} representing a
212 * {@code GarbageCollectionNotificationInfo}
213 *
214 * @throws IllegalArgumentException if {@code cd} does not
215 * represent a {@code GarbaageCollectionNotificationInfo} object.
216 *
217 * @return a {@code GarbageCollectionNotificationInfo} object represented
218 * by {@code cd} if {@code cd} is not {@code null};
219 * {@code null} otherwise.
220 */
221 public static GarbageCollectionNotificationInfo from(CompositeData cd) {
222 if (cd == null) {
223 return null;
224 }
225
226 if (cd instanceof GarbageCollectionNotifInfoCompositeData) {
227 return ((GarbageCollectionNotifInfoCompositeData) cd).getGarbageCollectionNotifInfo();
228 } else {
229 return new GarbageCollectionNotificationInfo(cd);
230 }
231 }
232
233 public CompositeData toCompositeData(CompositeType ct) {
234 return cdata;
235 }
236
237 }