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 }