1/*
2 * Copyright (c) 2011, 2017, 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
26package com.sun.management;
27
28import javax.management.openmbean.CompositeData;
29import javax.management.openmbean.CompositeDataView;
30import javax.management.openmbean.CompositeType;
31import 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 * <ul>
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 * </ul>
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 *       </li>
82 * </ul>
83 **/
84
85public class GarbageCollectionNotificationInfo implements  CompositeDataView {
86
87    private final String gcName;
88    private final String gcAction;
89    private final String gcCause;
90    private final GcInfo gcInfo;
91    private final CompositeData cdata;
92
93    /**
94     * Notification type denoting that
95     * the Java virtual machine has completed a garbage collection cycle.
96     * This notification is emitted by a {@link GarbageCollectorMXBean}.
97     * The value of this notification type is
98     * {@code com.sun.management.gc.notification}.
99     */
100    public static final String GARBAGE_COLLECTION_NOTIFICATION =
101        "com.sun.management.gc.notification";
102
103    /**
104     * Constructs a {@code GarbageCollectionNotificationInfo} object.
105     *
106     * @param gcName The name of the garbage collector used to perform the collection
107     * @param gcAction The name of the action performed by the garbage collector
108     * @param gcCause The cause of the garbage collection action
109     * @param gcInfo  a GcInfo object providing statistics about the GC cycle
110     */
111    public GarbageCollectionNotificationInfo(String gcName,
112                                             String gcAction,
113                                             String gcCause,
114                                             GcInfo gcInfo)  {
115        if (gcName == null) {
116            throw new NullPointerException("Null gcName");
117        }
118        if (gcAction == null) {
119            throw new NullPointerException("Null gcAction");
120        }
121        if (gcCause == null) {
122            throw new NullPointerException("Null gcCause");
123        }
124        this.gcName = gcName;
125        this.gcAction = gcAction;
126        this.gcCause = gcCause;
127        this.gcInfo = gcInfo;
128        this.cdata = new GarbageCollectionNotifInfoCompositeData(this);
129    }
130
131    GarbageCollectionNotificationInfo(CompositeData cd) {
132        GarbageCollectionNotifInfoCompositeData.validateCompositeData(cd);
133
134        this.gcName = GarbageCollectionNotifInfoCompositeData.getGcName(cd);
135        this.gcAction = GarbageCollectionNotifInfoCompositeData.getGcAction(cd);
136        this.gcCause = GarbageCollectionNotifInfoCompositeData.getGcCause(cd);
137        this.gcInfo = GarbageCollectionNotifInfoCompositeData.getGcInfo(cd);
138        this.cdata = cd;
139    }
140
141    /**
142     * Returns the name of the garbage collector used to perform the collection
143     *
144     * @return the name of the garbage collector used to perform the collection
145     */
146    public String getGcName() {
147        return gcName;
148    }
149
150    /**
151     * Returns the action performed by the garbage collector
152     *
153     * @return the action performed by the garbage collector
154     */
155    public String getGcAction() {
156        return gcAction;
157    }
158
159    /**
160     * Returns the cause of the garbage collection
161     *
162     * @return the cause of the garbage collection
163     */
164    public String getGcCause() {
165        return gcCause;
166    }
167
168    /**
169     * Returns the GC information related to the last garbage collection
170     *
171     * @return the GC information related to the
172     * last garbage collection
173     */
174    public GcInfo getGcInfo() {
175        return gcInfo;
176    }
177
178    /**
179     * Returns a {@code GarbageCollectionNotificationInfo} object represented by the
180     * given {@code CompositeData}.
181     * The given {@code CompositeData} must contain
182     * the following attributes:
183     * <blockquote>
184     * <table class="striped"><caption style="display:none">description</caption>
185     * <thead>
186     * <tr>
187     *   <th scope="col" style="text-align:left">Attribute Name</th>
188     *   <th scope="col" style="text-align:left">Type</th>
189     * </tr>
190     * </thead>
191     * <tbody>
192     * <tr>
193     *   <th scope="row">gcName</th>
194     *   <td>{@code java.lang.String}</td>
195     * </tr>
196     * <tr>
197     *   <th scope="row">gcAction</th>
198     *   <td>{@code java.lang.String}</td>
199     * </tr>
200     * <tr>
201     *   <th scope="row">gcCause</th>
202     *   <td>{@code java.lang.String}</td>
203     * </tr>
204     * <tr>
205     *   <th scope="row">gcInfo</th>
206     *   <td>{@code javax.management.openmbean.CompositeData}</td>
207     * </tr>
208     * </tbody>
209     * </table>
210     * </blockquote>
211     *
212     * @param cd {@code CompositeData} representing a
213     *           {@code GarbageCollectionNotificationInfo}
214     *
215     * @throws IllegalArgumentException if {@code cd} does not
216     *   represent a {@code GarbaageCollectionNotificationInfo} object.
217     *
218     * @return a {@code GarbageCollectionNotificationInfo} object represented
219     *         by {@code cd} if {@code cd} is not {@code null};
220     *         {@code null} otherwise.
221     */
222    public static GarbageCollectionNotificationInfo from(CompositeData cd) {
223        if (cd == null) {
224            return null;
225        }
226
227        if (cd instanceof GarbageCollectionNotifInfoCompositeData) {
228            return ((GarbageCollectionNotifInfoCompositeData) cd).getGarbageCollectionNotifInfo();
229        } else {
230            return new GarbageCollectionNotificationInfo(cd);
231        }
232    }
233
234    public CompositeData toCompositeData(CompositeType ct) {
235        return cdata;
236    }
237
238}
239