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