1 /*

     2  * Copyright (c) 2016, 2018, 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 9

    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 }