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 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 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 not available
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 not available
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 not available
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 identifier for the type in the Java virtual Machine (JVM).
240 *
241 * The ID might not be the same between JVM instances.
242 *
243 * @return 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 boolean isUnsigned() {
318 return annotationConstruct.hasUnsigned();
319 }
320
321 }