1 /*
   2  * Copyright (c) 2016, 2019, 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 jdk.management.jfr;
  27 
  28 import java.util.concurrent.Callable;
  29 
  30 import javax.management.openmbean.CompositeData;
  31 
  32 import jdk.jfr.EventType;
  33 import jdk.jfr.SettingDescriptor;
  34 
  35 /**
  36  * Management class that describes a setting, for example name, description and
  37  * default value.
  38  *
  39  * @see EventType#getSettingDescriptors()
  40  *
  41  * @since 9
  42  */
  43 public final class SettingDescriptorInfo {
  44 
  45     private final String name;
  46     private final String label;
  47     private final String description;
  48     private final String typeName;
  49     private final String contentType;
  50     private final String defaultValue;
  51 
  52     // package private
  53     SettingDescriptorInfo(SettingDescriptor settingDescriptor) {
  54         this.name = settingDescriptor.getName();
  55         this.label = settingDescriptor.getLabel();
  56         this.description = settingDescriptor.getDescription();
  57         this.typeName = settingDescriptor.getTypeName();
  58         this.contentType = settingDescriptor.getContentType();
  59         this.defaultValue = settingDescriptor.getDefaultValue();
  60     }
  61 
  62     private SettingDescriptorInfo(CompositeData cd) {
  63         this.name = (String) cd.get("name");
  64         this.label = (String) cd.get("label");
  65         this.description = (String) cd.get("description");
  66         this.typeName = (String) cd.get("typeName");
  67         this.defaultValue = (String) cd.get("defaultValue");
  68         this.contentType = (String) cd.get("contentType");
  69     }
  70 
  71     /**
  72      * Returns the human-readable name of this setting, for example
  73      * {@code "Threshold"}.
  74      *
  75      * @return the label for this setting, not {@code null}
  76      */
  77     public String getLabel() {
  78         return label;
  79     }
  80 
  81     /**
  82      * Returns the name of the setting associated with this
  83      * {@code SettingDescriptorInfo}, for example {@code "threshold"}.
  84      *
  85      * @return the name of this setting, not {@code null}
  86      */
  87     public String getName() {
  88         return name;
  89     }
  90 
  91     /**
  92      * Returns the description of the setting associated this
  93      * {@code SettingDescriptorInfo}, for example
  94      * {@code "The duration an event must exceed to be be recorded"}.
  95      *
  96      * @return the description of this setting, not null
  97      */
  98     public String getDescription() {
  99         return description;
 100     }
 101 
 102     /**
 103      * Returns the type name of the setting associated this
 104      * {@code SettingDescriptorInfo}, for example
 105      * {@code "com.oracle.jfr.settings.Threshold"}.
 106      * <p>
 107      * The type can be used to identify what type of setting this is.
 108      *
 109      * @return the name of this settings type, not {@code null}
 110      */
 111     public String getTypeName() {
 112         return typeName;
 113     }
 114 
 115     /**
 116      * Returns the content type of the setting associated this
 117      * {@code SettingDescriptorInfo}, for example {@code "jdk.jfr.Timespan"}.
 118      * <p>
 119      * The content type can be used to determine how the setting should be
 120      * rendered in a graphical user interface.
 121      *
 122      * @return the name of this settings type, not {@code null}
 123      */
 124     public String getContentType() {
 125         return contentType;
 126     }
 127 
 128     /**
 129      * Returns the default value of the setting associated this
 130      * {@code SettingDescriptorInfo}, for example {@code "20 ms"}.
 131      *
 132      * @return default value for this setting, not {@code null}
 133      *
 134      * @see SettingDescriptor#getDefaultValue()
 135      */
 136     public String getDefaultValue() {
 137         return defaultValue;
 138     }
 139 
 140     /**
 141      * Returns an {@code SettingDescriptorInfo} represented by the specified
 142      * {@code CompositeData}
 143      * <p>
 144      * The supplied {@code CompositeData} must have the following item names and
 145      * item types to be valid. <blockquote>
 146      * <table class="striped">
 147      * <caption>The name and type the specified CompositeData must contain</caption>
 148      * <thead>
 149      * <tr>
 150      * <th scope="col" style="text-align:left">Name</th>
 151      * <th scope="col" style="text-align:left">Type</th>
 152      * </tr>
 153      * </thead>
 154      * <tbody>
 155      * <tr>
 156      * <th scope="row">name</th>
 157      * <td>{@code String}</td>
 158      * </tr>
 159      * <tr>
 160      * <th scope="row">label</th>
 161      * <td>{@code String}</td>
 162      * </tr>
 163      * <tr>
 164      * <th scope="row">description</th>
 165      * <td>{@code String}</td>
 166      * </tr>
 167      * <tr>
 168      * <th scope="row">typeName</th>
 169      * <td>{@code String}</td>
 170      * </tr>
 171      * <tr>
 172      * <th scope="row">contentType</th>
 173      * <td>{@code String}</td>
 174      * </tr>
 175      * <tr>
 176      * <th scope="row">defaultValue</th>
 177      * <td>{@code String}</td>
 178      * </tr>
 179      * </tbody>
 180      * </table>
 181      * </blockquote>
 182      *
 183      * @param cd {@code CompositeData} representing the {@code SettingDescriptorInfo} to
 184      *        return
 185      *
 186      * @throws IllegalArgumentException if {@code cd} does not represent a valid
 187      *         {@code EventTypeInfo}
 188      *
 189      * @return a {@code SettingDescriptorInfo}, or {@code null} if {@code cd} is
 190      *         {@code null}
 191      */
 192     public static SettingDescriptorInfo from(CompositeData cd) {
 193         if (cd == null) {
 194             return null;
 195         }
 196         return new SettingDescriptorInfo(cd);
 197     }
 198 
 199     /**
 200      * Returns a string description of this {@code SettingDescriptorInfo}.
 201      *
 202      * @return a string describing this setting, not {@code null}
 203      */
 204     @Override
 205     public String toString() {
 206         Stringifier s = new Stringifier();
 207         s.add("name", name);
 208         s.add("label", label);
 209         s.add("description", description);
 210         s.add("typeName", typeName);
 211         s.add("contentType", contentType);
 212         s.add("defaultValue", defaultValue);
 213         return s.toString();
 214     }
 215 }