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.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 9

    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 Collections.unmodifiableList(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 }