View Javadoc
1   /*
2    * Copyright (c) 2011, 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 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  @jdk.Exported
89  public class GarbageCollectionNotificationInfo implements  CompositeDataView {
90  
91      private final String gcName;
92      private final String gcAction;
93      private final String gcCause;
94      private final GcInfo gcInfo;
95      private final CompositeData cdata;
96  
97      /**
98       * Notification type denoting that
99       * the Java virtual machine has completed a garbage collection cycle.
100      * This notification is emitted by a {@link GarbageCollectorMXBean}.
101      * The value of this notification type is
102      * {@code com.sun.management.gc.notification}.
103      */
104     public static final String GARBAGE_COLLECTION_NOTIFICATION =
105         "com.sun.management.gc.notification";
106 
107     /**
108      * Constructs a {@code GarbageCollectionNotificationInfo} object.
109      *
110      * @param gcName The name of the garbage collector used to perform the collection
111      * @param gcAction The name of the action performed by the garbage collector
112      * @param gcCause The cause the garbage collection action
113      * @param gcInfo  a GcInfo object providing statistics about the GC cycle
114      */
115     public GarbageCollectionNotificationInfo(String gcName,
116                                              String gcAction,
117                                              String gcCause,
118                                              GcInfo gcInfo)  {
119         if (gcName == null) {
120             throw new NullPointerException("Null gcName");
121         }
122         if (gcAction == null) {
123             throw new NullPointerException("Null gcAction");
124         }
125         if (gcCause == null) {
126             throw new NullPointerException("Null gcCause");
127         }
128         this.gcName = gcName;
129         this.gcAction = gcAction;
130         this.gcCause = gcCause;
131         this.gcInfo = gcInfo;
132         this.cdata = new GarbageCollectionNotifInfoCompositeData(this);
133     }
134 
135     GarbageCollectionNotificationInfo(CompositeData cd) {
136         GarbageCollectionNotifInfoCompositeData.validateCompositeData(cd);
137 
138         this.gcName = GarbageCollectionNotifInfoCompositeData.getGcName(cd);
139         this.gcAction = GarbageCollectionNotifInfoCompositeData.getGcAction(cd);
140         this.gcCause = GarbageCollectionNotifInfoCompositeData.getGcCause(cd);
141         this.gcInfo = GarbageCollectionNotifInfoCompositeData.getGcInfo(cd);
142         this.cdata = cd;
143     }
144 
145     /**
146      * Returns the name of the garbage collector used to perform the collection
147      *
148      * @return the name of the garbage collector used to perform the collection
149      */
150     public String getGcName() {
151         return gcName;
152     }
153 
154     /**
155      * Returns the action of the performed by the garbage collector
156      *
157      * @return the the action of the performed by the garbage collector
158      */
159     public String getGcAction() {
160         return gcAction;
161     }
162 
163     /**
164      * Returns the cause  the garbage collection
165      *
166      * @return the the cause  the garbage collection
167      */
168     public String getGcCause() {
169         return gcCause;
170     }
171 
172     /**
173      * Returns the GC information related to the last garbage collection
174      *
175      * @return the GC information related to the
176      * last garbage collection
177      */
178     public GcInfo getGcInfo() {
179         return gcInfo;
180     }
181 
182     /**
183      * Returns a {@code GarbageCollectionNotificationInfo} object represented by the
184      * given {@code CompositeData}.
185      * The given {@code CompositeData} must contain
186      * the following attributes:
187      * <blockquote>
188      * <table border>
189      * <tr>
190      *   <th align=left>Attribute Name</th>
191      *   <th align=left>Type</th>
192      * </tr>
193      * <tr>
194      *   <td>gcName</td>
195      *   <td>{@code java.lang.String}</td>
196      * </tr>
197      * <tr>
198      *   <td>gcAction</td>
199      *   <td>{@code java.lang.String}</td>
200      * </tr>
201      * <tr>
202      *   <td>gcCause</td>
203      *   <td>{@code java.lang.String}</td>
204      * </tr>
205      * <tr>
206      *   <td>gcInfo</td>
207      *   <td>{@code javax.management.openmbean.CompositeData}</td>
208      * </tr>
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 }