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. ValueDescriptor(Type type, String name, List<AnnotationElement> annotations, int dimension, boolean constantPool, String fieldName)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 */ ValueDescriptor(Class<?> type, String name)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 */ ValueDescriptor(Class<?> type, String name, List<AnnotationElement> annotations)133 public ValueDescriptor(Class<?> type, String name, List<AnnotationElement> annotations) { 134 this(type, name, new ArrayList<>(annotations), false); 135 } 136 137 ValueDescriptor(Class<?> type, String name, List<AnnotationElement> annotations, boolean allowArray)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 */ getLabel()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 */ getName()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 */ getDescription()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 */ getContentType()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 */ getTypeName()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 */ getTypeId()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 */ isArray()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 */ getAnnotation(Class<A> annotationType)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 */ getAnnotationElements()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 */ getFields()290 public List<ValueDescriptor> getFields() { 291 if (type.isSimpleType()) { 292 return Collections.emptyList(); 293 } 294 return type.getFields(); 295 } 296 297 // package private getType()298 Type getType() { 299 return type; 300 } 301 302 // package private setAnnotations(List<AnnotationElement> anno)303 void setAnnotations(List<AnnotationElement> anno) { 304 annotationConstruct.setAnnotationElements(anno); 305 } 306 307 // package private isConstantPool()308 boolean isConstantPool() { 309 return constantPool; 310 } 311 312 // package private getJavaFieldName()313 String getJavaFieldName() { 314 return javaFieldName; 315 } 316 317 // package private isUnsigned()318 boolean isUnsigned() { 319 return annotationConstruct.hasUnsigned(); 320 } 321 322 } 323