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.ArrayList;
  30 import java.util.Collections;
  31 import java.util.List;
  32 import java.util.Objects;
  33 
  34 import jdk.jfr.internal.AnnotationConstruct;
  35 import jdk.jfr.internal.Type;
  36 import jdk.jfr.internal.Utils;
  37 
  38 /**
  39  * Describes the event fields and annotation elements.
  40  *
  41  * @since 8
  42  */
  43 public final class ValueDescriptor {
  44 
  45     private final AnnotationConstruct annotationConstruct;
  46     private final Type type;
  47     private final String name;
  48     private final boolean isArray;
  49     private final boolean constantPool;
  50     private final String javaFieldName;
  51 
  52     // package private, invoked by jdk.internal.
  53     ValueDescriptor(Type type, String name, List<AnnotationElement> annotations, int dimension, boolean constantPool, String fieldName) {
  54         Objects.requireNonNull(annotations);
  55         if (dimension < 0) {
  56             throw new IllegalArgumentException("Dimension must be positive");
  57         }
  58         this.name = Objects.requireNonNull(name, "Name of value descriptor can't be null");
  59         this.type = Objects.requireNonNull(type);
  60         this.isArray = dimension > 0;
  61         this.constantPool = constantPool;
  62         this.annotationConstruct = new AnnotationConstruct(annotations);
  63         this.javaFieldName = fieldName;
  64     }
  65 
  66     /**
  67      * <p>
  68      * Constructs a value descriptor, useful for dynamically creating event types and
  69      * annotations.
  70      * <P>
  71      * The following types are supported:
  72      * <ul>
  73      * <li>{@code byte.class}
  74      * <li>{@code short.class}
  75      * <li>{@code int.class}
  76      * <li>{@code long.class}
  77      * <li>{@code char.class}
  78      * <li>{@code float.class}
  79      * <li>{@code double.class}
  80      * <li>{@code boolean.class}
  81      * <li>{@code String.class}
  82      * <li>{@code Class.class}
  83      * <li>{@code Thread.class}
  84      * </ul>
  85      *
  86      * <p>
  87      * The name must be a valid Java identifier (for example, {@code "maxThroughput"}). See 3.8
  88      * Java Language Specification for more information.
  89      *
  90      * @param type the type, not {@code null}
  91      * @param name the name, not {@code null}
  92      *
  93      * @throws SecurityException if a security manager is present and the caller
  94      *         doesn't have {@code FlightRecorderPermission("registerEvent")}
  95      *
  96      */
  97     public ValueDescriptor(Class<?> type, String name) {
  98         this(type, name, Collections.<AnnotationElement> emptyList());
  99     }
 100 
 101     /**
 102      * <p>
 103      * Constructs a value descriptor, useful for dynamically creating event types and
 104      * annotations.
 105      * <P>
 106      * The following types are supported:
 107      * <ul>
 108      * <li>{@code byte.class}
 109      * <li>{@code short.class}
 110      * <li>{@code int.class}
 111      * <li>{@code long.class}
 112      * <li>{@code char.class}
 113      * <li>{@code float.class}
 114      * <li>{@code double.class}
 115      * <li>{@code boolean.class}
 116      * <li>{@code String.class}
 117      * <li>{@code Class.class}
 118      * <li>{@code Thread.class}
 119      * </ul>
 120      *
 121      * <p>
 122      * The name must be a valid Java identifier (for example, {@code "maxThroughput"}). See 3.8
 123      * Java Language Specification for more information.
 124      *
 125      * @param type the type, not {@code null}
 126      * @param name the name, not {@code null}
 127      * @param annotations the annotations on the value descriptors, not
 128      *        {@code null}
 129      *
 130      * @throws SecurityException if a security manager is present and the caller
 131      *         doesn't have {@code FlightRecorderPermission("registerEvent")}
 132      */
 133     public ValueDescriptor(Class<?> type, String name, List<AnnotationElement> annotations) {
 134         this(type, name, new ArrayList<>(annotations), false);
 135     }
 136 
 137 
 138     ValueDescriptor(Class<?> type, String name, List<AnnotationElement> annotations, boolean allowArray) {
 139         Objects.requireNonNull(annotations);
 140         Utils.checkRegisterPermission();
 141         if (!allowArray) {
 142             if (type.isArray()) {
 143                 throw new IllegalArgumentException("Array types are not allowed");
 144             }
 145         }
 146         this.name = Objects.requireNonNull(name, "Name of value descriptor can't be null");
 147         this.type = Objects.requireNonNull(Utils.getValidType(Objects.requireNonNull(type), Objects.requireNonNull(name)));
 148         this.annotationConstruct = new AnnotationConstruct(annotations);
 149         this.javaFieldName = name; // Needed for dynamic events
 150         this.isArray = type.isArray();
 151         // Assume we always want to store String and Thread in constant pool
 152         this.constantPool = type == Class.class || type == Thread.class;
 153     }
 154 
 155     /**
 156      * Returns a human-readable name that describes the value (for example,
 157      * {@code "Maximum Throughput"}).
 158      *
 159      * @return a human-readable name, or {@code null} if doesn't exist
 160      */
 161     public String getLabel() {
 162         return annotationConstruct.getLabel();
 163     }
 164 
 165     /**
 166      * Returns the name of the value (for example, {@code "maxThroughput"}).
 167      *
 168      * @return the name, not {@code null}
 169      */
 170     public String getName() {
 171         return name;
 172     }
 173 
 174     /**
 175      * Returns a sentence describing the value (for example, {@code "Maximum
 176      * throughput in the transaction system. Value is reset after each new
 177      * batch."}).
 178      *
 179      * @return the description, or {@code null} if doesn't exist
 180      */
 181     public String getDescription() {
 182         return annotationConstruct.getDescription();
 183     }
 184 
 185     /**
 186      * Returns a textual identifier that specifies how a value represented by
 187      * this {@link ValueDescriptor} is interpreted or formatted.
 188      * <p>
 189      * For example, if the value descriptor's type is {@code float} and the
 190      * event value is {@code 0.5f}, a content type of
 191      * {@code "jdk.jfr.Percentage"} hints to a client that the value is a
 192      * percentage and that it should be rendered as {@code "50%"}.
 193      * <p>
 194      * The JDK provides the following predefined content types:
 195      * <ul>
 196      * <li>jdk.jfr.Percentage</li>
 197      * <li>jdk.jfr.Timespan</li>
 198      * <li>jdk.jfr.Timestamp</li>
 199      * <li>jdk.jfr.Frequency</li>
 200      * <li>jdk.jfr.Flag</li>
 201      * <li>jdk.jfr.MemoryAddress</li>
 202      * <li>jdk.jfr.DataAmount</li>
 203      * <li>jdk.jfr.NetworkAddress</li>
 204      * </ul>
 205      * <p>
 206      * User-defined content types can be created by using the {@link ContentType} class.
 207      *
 208      * @return the content type, or {@code null} if doesn't exist
 209      *
 210      * @see ContentType
 211      */
 212     public String getContentType() {
 213         for (AnnotationElement anno : getAnnotationElements()) {
 214             for (AnnotationElement meta : anno.getAnnotationElements()) {
 215                 if (meta.getTypeName().equals(ContentType.class.getName())) {
 216                     return anno.getTypeName();
 217                 }
 218             }
 219         }
 220         return null;
 221     }
 222 
 223     /**
 224      * Returns the fully qualified class name of the type that is associated with
 225      * this value descriptor.
 226      *
 227      * @return the type name, not {@code null}
 228      *
 229      * @see ValueDescriptor#getTypeId()
 230      */
 231     public String getTypeName() {
 232         if (type.isSimpleType()) {
 233             return type.getFields().get(0).getTypeName();
 234         }
 235         return type.getName();
 236     }
 237 
 238     /**
 239      * Returns a unique ID for the type in the Java virtual Machine (JVM).
 240      *
 241      * The ID might not be the same between JVM instances.
 242      *
 243      * @return the type ID, not negative
 244      */
 245     public long getTypeId() {
 246         return type.getId();
 247     }
 248 
 249     /**
 250      * Returns if this value descriptor is an array type.
 251      *
 252      * @return {@code true} if it is an array type, {@code false} otherwise
 253      */
 254     public boolean isArray() {
 255         return isArray;
 256     }
 257 
 258     /**
 259      * Returns the first annotation for the specified type if an annotation
 260      * element with the same name is directly present for this value descriptor,
 261      * {@code null} otherwise.
 262      *
 263      * @param <A> the type of the annotation to query for and return if present
 264      * @param annotationType the Class object that corresponds to the annotation
 265      *        type, not {@code null}
 266      * @return this element's annotation for the specified annotation type if
 267      *         directly present, else {@code null}
 268      */
 269     public <A extends Annotation> A getAnnotation(Class<A> annotationType) {
 270         Objects.requireNonNull(annotationType);
 271         return annotationConstruct.getAnnotation(annotationType);
 272     }
 273 
 274     /**
 275      * Returns an immutable list of annotation elements for this value
 276      * descriptor.
 277      *
 278      * @return a list of annotations, not {@code null}
 279      */
 280     public List<AnnotationElement> getAnnotationElements() {
 281         return annotationConstruct.getUnmodifiableAnnotationElements();
 282     }
 283 
 284     /**
 285      * Returns an immutable list of value descriptors if the type is complex,
 286      * else an empty list.
 287      *
 288      * @return a list of value descriptors, not {@code null}
 289      */
 290     public List<ValueDescriptor> getFields() {
 291         if (type.isSimpleType()) {
 292             return Collections.emptyList();
 293         }
 294         return type.getFields();
 295     }
 296 
 297     // package private
 298     Type getType() {
 299         return type;
 300     }
 301 
 302     // package private
 303     void setAnnotations(List<AnnotationElement> anno) {
 304         annotationConstruct.setAnnotationElements(anno);
 305     }
 306 
 307     // package private
 308     boolean isConstantPool() {
 309         return constantPool;
 310     }
 311 
 312     // package private
 313     String getJavaFieldName() {
 314         return javaFieldName;
 315     }
 316 
 317     // package private
 318     boolean isUnsigned() {
 319         return annotationConstruct.hasUnsigned();
 320     }
 321 
 322 }