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.jfr;
  27 
  28 import java.lang.annotation.Annotation;
  29 import java.util.Collections;
  30 import java.util.List;
  31 import java.util.Objects;
  32 
  33 import jdk.jfr.internal.AnnotationConstruct;
  34 import jdk.jfr.internal.Type;
  35 
  36 /**
  37  * Describes an event setting.
  38  *
  39  * @since 8
  40  */
  41 public final class SettingDescriptor {
  42 
  43     private final AnnotationConstruct annotationConstruct;
  44     private final Type type;
  45     private final String name;
  46     private final String defaultValue;
  47 
  48     // package private, invoked by jdk.internal.
  49     SettingDescriptor(Type type, String name, String defaultValue, List<AnnotationElement> annotations) {
  50         Objects.requireNonNull(annotations);
  51         this.name = Objects.requireNonNull(name, "Name of value descriptor can't be null");
  52         this.type = Objects.requireNonNull(type);
  53         this.annotationConstruct = new AnnotationConstruct(annotations);
  54         this.defaultValue = Objects.requireNonNull(defaultValue);
  55     }
  56 
  57     // package private
  58     void setAnnotations(List<AnnotationElement> as) {
  59         annotationConstruct.setAnnotationElements(as);
  60     }
  61 
  62     /**
  63      * Returns the name of the setting (for example, {@code "threshold"}).
  64      *
  65      * @return the name, not {@code null}
  66      */
  67     public String getName() {
  68         return name;
  69     }
  70 
  71     /**
  72      * Returns a human-readable name that describes the setting (for example,
  73      * {@code "Threshold"}).
  74      * <p>
  75      * If the setting lacks a label, the label for the type that is associated with this
  76      * setting is returned, or {@code null} if doesn't exist
  77      *
  78      * @return a human-readable name, or {@code null} if doesn't exist
  79      */
  80     public String getLabel() {
  81         String label = annotationConstruct.getLabel();
  82         if (label == null) {
  83             label = type.getLabel();
  84         }
  85         return label;
  86     }
  87 
  88     /**
  89      * Returns a sentence that describes the setting (for example
  90      * {@code "Record event with duration
  91      * above or equal to threshold"}).
  92      * <p>
  93      * If the setting lacks a description, the description for the type that is
  94      * associated with this setting is returned, or {@code null} if doesn't exist.
  95      *
  96      * @return the description, or {@code null} if doesn't exist
  97      */
  98     public String getDescription() {
  99         String description = annotationConstruct.getDescription();
 100         if (description == null) {
 101             description = type.getDescription();
 102         }
 103         return description;
 104     }
 105 
 106     /**
 107      * Returns a textual identifier that specifies how a value that is represented by
 108      * this {@code SettingDescriptor} object is interpreted or formatted.
 109      * <p>
 110      * For example, if the setting descriptor represents a percentage, then
 111      * {@code "jdk.jfr.Percentage"} hints to a client that a value of "0.5"
 112      * is formatted as "50%".
 113      * <p>
 114      * The JDK provides the following predefined content types:
 115      * <ul>
 116      * <li>jdk.jfr.Percentage</li>
 117      * <li>jdk.jfr.Timespan</li>
 118      * <li>jdk.jfr.Timestamp</li>
 119      * <li>jdk.jfr.Frequency</li>
 120      * <li>jdk.jfr.Flag</li>
 121      * <li>jdk.jfr.MemoryAddress</li>
 122      * <li>jdk.jfr.DataAmount</li>
 123      * <li>jdk.jfr.NetworkAddress</li>
 124      * </ul>
 125      * <p>
 126      * User-defined content types can be created by using {@link ContentType}.
 127      * <p>
 128      * If the setting lacks a content type, the content type for the type
 129      * that is associated with this setting is returned, or {@code null} if not
 130      * available.
 131      *
 132      * @return the content type, or {@code null} if doesn't exist
 133      *
 134      * @see ContentType
 135      */
 136     public String getContentType() {
 137         for (AnnotationElement anno : getAnnotationElements()) {
 138             for (AnnotationElement meta : anno.getAnnotationElements()) {
 139                 if (meta.getTypeName().equals(ContentType.class.getName())) {
 140                     return anno.getTypeName();
 141                 }
 142             }
 143         }
 144         for (AnnotationElement anno : type.getAnnotationElements()) {
 145             for (AnnotationElement meta : anno.getAnnotationElements()) {
 146                 if (meta.getTypeName().equals(ContentType.class.getName())) {
 147                     return anno.getTypeName();
 148                 }
 149             }
 150         }
 151         return null;
 152     }
 153 
 154     /**
 155      * Returns the fully qualified class name of the type that is associated with this
 156      * setting descriptor.
 157      *
 158      * @return the type name, not {@code null}
 159      *
 160      * @see SettingDescriptor#getTypeId()
 161      */
 162     public String getTypeName() {
 163         return type.getName();
 164     }
 165 
 166     /**
 167      * Returns a unique ID for the type in the Java Virtual Machine (JVM).
 168      * <p>
 169      * The ID might not be the same between JVM instances.
 170      *
 171      * @return the type ID, not negative
 172      */
 173     public long getTypeId() {
 174         return type.getId();
 175     }
 176 
 177     /**
 178      * Returns the first annotation for the specified type if an annotation
 179      * element with the same name is available, {@code null} otherwise.
 180      *
 181      * @param <A> the type of the annotation to query for and return if available
 182      * @param annotationType the Class object that corresponds to the annotation
 183      *        type, not {@code null}
 184      * @return this element's annotation for the specified annotation type if
 185      *         available, {@code null} otherwise
 186      */
 187     public <A extends Annotation> A getAnnotation(Class<A> annotationType) {
 188         Objects.requireNonNull(annotationType);
 189         return annotationConstruct.getAnnotation(annotationType);
 190     }
 191 
 192     /**
 193      * Returns an immutable list of annotation elements for this value
 194      * descriptor.
 195      *
 196      * @return a list of annotations, not {@code null}
 197      */
 198     public List<AnnotationElement> getAnnotationElements() {
 199         return Collections.unmodifiableList(annotationConstruct.getUnmodifiableAnnotationElements());
 200     }
 201 
 202     /**
 203      * Returns the default value for this setting descriptor.
 204      *
 205      * @return the default value, not {@code null}
 206      */
 207     public String getDefaultValue() {
 208         return defaultValue;
 209     }
 210 
 211     // package private
 212     Type getType() {
 213         return type;
 214     }
 215 }