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 to 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 of 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 performed by the garbage collector
 156      *
 157      * @return the action performed by the garbage collector
 158      */
 159     public String getGcAction() {
 160         return gcAction;
 161     }
 162 
 163     /**
 164      * Returns the cause of the garbage collection
 165      *
 166      * @return the cause of 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 }
--- EOF ---