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.Arrays;
30 import java.util.Collections;
31 import java.util.LinkedHashMap;
32 import java.util.List;
33 import java.util.Map;
34 import java.util.Objects;
35
36 import jdk.jfr.internal.JVMSupport;
37 import jdk.jfr.internal.MetadataRepository;
38 import jdk.jfr.internal.PlatformEventType;
39 import jdk.jfr.internal.Type;
40 import jdk.jfr.internal.Utils;
41
42 /**
43 * Describes an event, its fields, settings and annotations.
44 *
45 * @since 9
46 */
47 public final class EventType {
48 private final PlatformEventType platformEventType;
49 private final List<String> UNCATEGORIZED = Collections.singletonList("Uncategorized");
50 private Map<String, ValueDescriptor> cache; // create lazy to avoid memory overhead
51 // helper constructor
52 EventType(PlatformEventType platformEventType) {
53 this.platformEventType = platformEventType;
54 }
55
56 /**
57 * Returns an immutable list of descriptors that describe the event fields of
58 * this event type.
59 *
60 * @return the list of field descriptors, not {@code null}
61 */
62 public List<ValueDescriptor> getFields() {
63 return platformEventType.getFields();
64 }
65
66 /**
67 * Returns the field with the specified name, or {@code null} if it doesn't
68 * exist.
69 *
70 * @return a value descriptor that describes the field, or <code>null</code> if
71 * the field with the specified name doesn't exist
72 *
73 * @return a value descriptor, or <code>null</code> if it doesn't exist
74 */
75 public ValueDescriptor getField(String name) {
76 Objects.requireNonNull(name);
77 if (cache == null) {
78 List<ValueDescriptor> fields = getFields();
79 Map<String, ValueDescriptor> newCache = new LinkedHashMap<String, ValueDescriptor>(fields.size());
80 for (ValueDescriptor v :fields) {
81 newCache.put(v.getName(), v);
82 }
83 cache = newCache;
84 }
85 return cache.get(name);
86 }
87
88 /**
89 * Returns an identifier for the event (for example,
90 * {@code "jdk.jfr.CPULoad"}).
91 * <p>
92 * The identifier is the fully qualified name of the event class, if not set using
93 * the {@link Name} annotation.
94 *
95 * @return the name, not {@code null}
96 *
97 * @see Name
98 */
99 public String getName() {
100 return platformEventType.getName();
101 }
102
103 /**
104 * Returns a human-readable name (for example, {@code "CPU Load"}).
105 * <p>
106 * The label of an event class can be set with {@link Label}.
107 *
108 * @return the label, or {@code null} if a label is not been set
109 *
110 * @see Label
111 */
112 public String getLabel() {
113 return platformEventType.getLabel();
114 }
115
116 /**
117 * Returns a unique ID for this event type in the Java Virtual Machine (JVM).
118 *
119 * @return the ID that is used in the JVM
120 */
121 public long getId() {
122 return platformEventType.getId();
123 }
124
125 /**
126 * Returns an immutable list of annotation elements for this event type.
127 *
128 * @return an immutable list of annotations or an empty list if no
129 * annotations exists, not {@code null}
130 */
131 public List<AnnotationElement> getAnnotationElements() {
132 return platformEventType.getAnnotationElements();
133 }
134
135 /**
136 * Returns {@code true} if the event is enabled and at least one recording is
137 * running, {@code false} otherwise.
138 * <p>
139 * By default, the event is enabled. The event can be enabled or disabled by
140 * setting the enabled setting to {@code true} or {@code false}, programmatically or by using a
141 * configuration file. The event can also be disabled by annotating event with
142 * the {@code @Enabled(false)} annotation.
143 *
144 * @return true if event is enabled, false otherwise
145 *
146 * @see Enabled
147 * @see Recording#enable(Class)
148 */
149 public boolean isEnabled() {
150 return platformEventType.isEnabled();
151 }
152
153 /**
154 * Returns a short sentence that describes the event class.
155 * <p>
156 * The description of an event class can be set with {@link Description}.
157 *
158 * @return the description, or {@code null} if no description exists
159 *
160 * @see Description
161 */
162 public String getDescription() {
163 return platformEventType.getDescription();
164 }
165
166 /**
167 * Returns the first annotation for the specified type if an annotation
168 * element with the same name is directly present, otherwise {@code null}.
169 *
170 * @param <A> the type of the annotation to query for and return if present
171 * @param annotationClass the {@code Class} object that corresponds to the
172 * annotation type, not {@code null}
173 * @return this element's annotation for the specified annotation type if
174 * directly present, else {@code null}
175 */
176 public <A extends Annotation> A getAnnotation(Class<A> annotationClass) {
177 Objects.requireNonNull(annotationClass);
178 return platformEventType.getAnnotation(annotationClass);
179 }
180
181 /**
182 * Returns the event type for an event class, or {@code null} if it doesn't
183 * exist.
184 *
185 * @param eventClass the event class, not {@code null}
186 * @return the event class, or null if class doesn't exist
187 *
188 * @throws IllegalArgumentException if {@code eventClass} is an abstract class
189 *
190 * @throws IllegalStateException if the class is annotated with
191 * {@code Registered(false)}, but not manually registered
192 */
193 public static EventType getEventType(Class<? extends Event> eventClass) {
194 Objects.requireNonNull(eventClass);
195 Utils.ensureValidEventSubclass(eventClass);
196 JVMSupport.ensureWithInternalError();
197 return MetadataRepository.getInstance().getEventType(eventClass);
198 }
199
200 /**
201 * Returns an immutable list of the setting descriptors that describe the available
202 * event settings for this event type.
203 *
204 * @return the list of setting descriptors for this event type, not
205 * {@code null}
206 */
207 public List<SettingDescriptor> getSettingDescriptors() {
208 return Collections.unmodifiableList(platformEventType.getSettings());
209 }
210
211 /**
212 * Returns the list of human-readable names that makes up the categories for
213 * this event type (for example, "Java Application", "Statistics").
214 *
215 * @return an immutable list of category names, or a list with the name
216 * "Uncategorized" if no category is set
217 *
218 * @see Category
219 */
220 public List<String> getCategoryNames() {
221 Category c = platformEventType.getAnnotation(Category.class);
222 if (c == null) {
223 return UNCATEGORIZED;
224 }
225 return Collections.unmodifiableList(Arrays.asList(c.value()));
226 }
227
228 // package private
229 Type getType() {
230 return platformEventType;
231 }
232
233 // package private
234 PlatformEventType getPlatformEventType() {
235 return platformEventType;
236 }
237 }