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 event = new HelloWorld();
51 * event.message = "hello, world!";
52 * event.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
82 * {@code Event#commit()commit} method is invoked. If
83 * {@link Event#shouldCommit()} returns false, then those operations can be
84 * avoided.
85 *
86 * @since 9
87 */
88 @Enabled(true)
89 @StackTrace(true)
90 @Registered(true)
91 abstract public class Event {
92 /**
93 * Sole constructor, for invocation by subclass constructors, typically
94 * implicit.
95 */
96 protected Event() {
97 }
98
99 /**
100 * Starts the timing of this event.
101 */
102 final public void begin() {
103 }
104
105 /**
106 * Ends the timing of this event.
107 *
108 * The {@code end} method must be invoked after the {@code begin} method.
109 */
110 final public void end() {
111 }
112
113 /**
114 * Writes the field values, time stamp, and event duration to the Flight
115 * Recorder system.
116 * <p>
117 * If the event starts with an invocation of the {@code begin} method, but does
118 * not end with an explicit invocation of the {@code end} method, then the event
119 * ends when the {@code commit} method is invoked.
120 */
121 final public void commit() {
122 }
123
124 /**
125 * Returns {@code true} if at least one recording is running, and the
126 * enabled setting for this event is set to {@code true}, otherwise
127 * {@code false} is returned.
128 *
129 * @return {@code true} if event is enabled, {@code false} otherwise
130 */
131 final public boolean isEnabled() {
132 return false;
133 }
134
135 /**
136 * Returns {@code true} if the enabled setting for this event is set to
137 * {@code true} and if the duration is within the threshold for the event,
138 * {@code false} otherwise. The threshold is the minimum threshold for all
139 * running recordings.
140 *
141 * @return {@code true} if the event can be written to the Flight Recorder
142 * system, {@code false} otherwise
143 */
144 final public boolean shouldCommit() {
145 return false;
146 }
147
148 /**
149 * Sets a field value.
150 * <p>
151 * Applicable only if the event is dynamically defined using the
152 * {@code EventFactory} class.
153 * <p>
154 * The supplied {@code index} corresponds to the index of the
155 * {@link ValueDescriptor} object passed to the factory method of the
156 * {@code EventFactory} class.
157 *
158 * @param index the index of the field that is passed to
159 * {@code EventFactory#create(String, java.util.List, java.util.List)}
160 * @param value value to set, can be {@code null}
161 * @throws UnsupportedOperationException if it's not a dynamically generated
162 * event
163 * @throws IndexOutOfBoundsException if {@code index} is less than {@code 0} or
164 * greater than or equal to the number of fields specified for the event
165 *
166 * @see EventType#getFields()
167 * @see EventFactory
168 */
169 final public void set(int index, Object value) {
170 }
171 }