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 /**
29 * Base class for events, to be subclassed in order to define events and their
30 * fields.
31 * <p>
32 * The following example shows how to implement an {@code Event} class.
33 *
34 * <pre>
35 * <code>
36 * import jdk.jfr.Event;
37 * import jdk.jfr.Description;
38 * import jdk.jfr.Label;
39 *
40 * public class Example {
41 *
42 * @Label("Hello World")
43 * @Description("Helps programmer getting started")
44 * static class HelloWorld extends Event {
45 * @Label("Message")
46 * String message;
47 * }
48 *
49 * public static void main(String... args) {
50 * HelloWorld hwe = new HelloWorld();
51 * hwe.message = "hello, world!";
52 * hwe.commit();
53 * }
54 * }
55 * </code>
56 * </pre>
57 * <p>
58 * After an event is allocated and its field members are populated, it can be
59 * written to the Flight Recorder system by using the {@code #commit()} method.
60 * <p>
61 * By default, an event is enabled. To disable an event annotate the
62 * {@link Event} class with {@code @Enabled(false)}.
63 * <p>
64 * Supported field types are the Java primitives: {@code boolean}, {@code char},
65 * {@code byte}, {@code short}, {@code int}, {@code long}, {@code float}, and
66 * {@code double}. Supported reference types are: {@code String}, {@code Thread}
67 * and {@code Class}. Arrays, enums, and other reference types are silently
68 * ignored and not included. Fields that are of the supported types can be
69 * excluded by using the transient modifier. Static fields, even of the
70 * supported types, are not included.
71 * <p>
72 * Tools can visualize data in a meaningful way when annotations are used (for
73 * example, {@code Label}, {@code Description}, and {@code Timespan}).
74 * Annotations applied to an {@link Event} class or its fields are included if
75 * they are present (indirectly, directly, or associated), have the
76 * {@code MetadataDefinition} annotation, and they do not contain enums, arrays,
77 * or classes.
78 * <p>
79 * Gathering data to store in an event can be expensive. The
80 * {@link Event#shouldCommit} method can be used to verify whether an event
81 * instance would actually be written to the system when the {@code #commit()}
82 * method is invoked. If {@link Event#shouldCommit} returns false, then those
83 * operations can be avoided.
84 *
85 * @since 9
86 */
87 @Enabled(true)
88 @StackTrace(true)
89 @Registered(true)
90 abstract public class Event {
91 /**
92 * Sole constructor, for invocation by subclass constructors, typically
93 * implicit.
94 */
95 protected Event() {
96 }
97
98 /**
99 * Starts the timing of this event.
100 */
101 final public void begin() {
102 }
103
104 /**
105 * Ends the timing of this event.
106 *
107 * The {@code end} method must be invoked after the {@code begin} method.
108 */
109 final public void end() {
110 }
111
112 /**
113 * Writes the field values, time stamp, and event duration to the Flight
114 * Recorder system.
115 * <p>
116 * If the event starts with an invocation of the {@code begin} method, but does
117 * not end with an explicit invocation of the {@code end} method, then the event
118 * ends when the {@code commit} method is invoked.
119 */
120 final public void commit() {
121 }
122
123 /**
124 * Returns {@code true} if at least one recording is running, and the
125 * enabled setting for this event is set to {@code true}, otherwise
126 * {@code false} is returned.
127 *
128 * @return {@code true} if event is enabled, {@code false} otherwise
129 */
130 final public boolean isEnabled() {
131 return false;
132 }
133
134 /**
135 * Returns {@code true} if the enabled setting for this event is set to
136 * {@code true} and if the duration is within the threshold for the event,
137 * {@code false} otherwise. The threshold is the minimum threshold for all
138 * running recordings.
139 *
140 * @return {@code true} if the event can be written to the Flight Recorder
141 * system, {@code false} otherwise
142 */
143 final public boolean shouldCommit() {
144 return false;
145 }
146
147 /**
148 * Sets a field value.
149 * <p>
150 * Applicable only if the event is dynamically defined using the
151 * {@code EventFactory} class.
152 * <p>
153 * The supplied {@code index} corresponds to the index of the
154 * {@link ValueDescriptor} object passed to the factory method of the
155 * {@code EventFactory} class.
156 *
157 * @param index the index of the field that is passed to
158 * {@code EventFactory#create(String, java.util.List, java.util.List)}
159 * @param value value to set, can be {@code null}
160 * @throws UnsupportedOperationException if it's not a dynamically generated
161 * event
162 * @throws IndexOutOfBoundsException if {@code index} is less than {@code 0} or
163 * greater than or equal to the number of fields specified for the event
164 *
165 * @see EventType#getFields()
166 * @see EventFactory
167 */
168 final public void set(int index, Object value) {
169 }
170 }