+ * The following example shows how to implement an {@code Event} class. + * + *
+ *
+ * import jdk.jfr.Event;
+ * import jdk.jfr.Description;
+ * import jdk.jfr.Label;
+ *
+ * public class Example {
+ *
+ * @Label("Hello World")
+ * @Description("Helps programmer getting started")
+ * static class HelloWorld extends Event {
+ * @Label("Message")
+ * String message;
+ * }
+ *
+ * public static void main(String... args) {
+ * HelloWorld hwe = new HelloWorld();
+ * hwe.message = "hello, world!";
+ * hwe.commit();
+ * }
+ * }
+ *
+ *
+ * + * After an event is allocated and its field members are populated, it can be + * written to the Flight Recorder system by using the {@code #commit()} method. + *
+ * By default, an event is enabled. To disable an event annotate the + * {@link Event} class with {@code @Enabled(false)}. + *
+ * Supported field types are the Java primitives: {@code boolean}, {@code char}, + * {@code byte}, {@code short}, {@code int}, {@code long}, {@code float}, and + * {@code double}. Supported reference types are: {@code String}, {@code Thread} + * and {@code Class}. Arrays, enums, and other reference types are silently + * ignored and not included. Fields that are of the supported types can be + * excluded by using the transient modifier. Static fields, even of the + * supported types, are not included. + *
+ * Tools can visualize data in a meaningful way when annotations are used (for + * example, {@code Label}, {@code Description}, and {@code Timespan}). + * Annotations applied to an {@link Event} class or its fields are included if + * they are present (indirectly, directly, or associated), have the + * {@code MetadataDefinition} annotation, and they do not contain enums, arrays, + * or classes. + *
+ * Gathering data to store in an event can be expensive. The + * {@link Event#shouldCommit} method can be used to verify whether an event + * instance would actually be written to the system when the {@code #commit()} + * method is invoked. If {@link Event#shouldCommit} returns false, then those + * operations can be avoided. + * + * @since 9 + */ +@Enabled(true) +@StackTrace(true) +@Registered(true) +abstract public class Event { + /** + * Sole constructor, for invocation by subclass constructors, typically + * implicit. + */ + protected Event() { + } + + /** + * Starts the timing of this event. + */ + final public void begin() { + } + + /** + * Ends the timing of this event. + * + * The {@code end} method must be invoked after the {@code begin} method. + */ + final public void end() { + } + + /** + * Writes the field values, time stamp, and event duration to the Flight + * Recorder system. + *
+ * If the event starts with an invocation of the {@code begin} method, but does + * not end with an explicit invocation of the {@code end} method, then the event + * ends when the {@code commit} method is invoked. + */ + final public void commit() { + } + + /** + * Returns {@code true} if at least one recording is running, and the + * enabled setting for this event is set to {@code true}, otherwise + * {@code false} is returned. + * + * @return {@code true} if event is enabled, {@code false} otherwise + */ + final public boolean isEnabled() { + return false; + } + + /** + * Returns {@code true} if the enabled setting for this event is set to + * {@code true} and if the duration is within the threshold for the event, + * {@code false} otherwise. The threshold is the minimum threshold for all + * running recordings. + * + * @return {@code true} if the event can be written to the Flight Recorder + * system, {@code false} otherwise + */ + final public boolean shouldCommit() { + return false; + } + + /** + * Sets a field value. + *
+ * Applicable only if the event is dynamically defined using the + * {@code EventFactory} class. + *
+ * The supplied {@code index} corresponds to the index of the + * {@link ValueDescriptor} object passed to the factory method of the + * {@code EventFactory} class. + * + * @param index the index of the field that is passed to + * {@code EventFactory#create(String, java.util.List, java.util.List)} + * @param value value to set, can be {@code null} + * @throws UnsupportedOperationException if it's not a dynamically generated + * event + * @throws IndexOutOfBoundsException if {@code index} is less than {@code 0} or + * greater than or equal to the number of fields specified for the event + * + * @see EventType#getFields() + * @see EventFactory + */ + final public void set(int index, Object value) { + } +}