--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/jdk.jfr/share/classes/jdk/jfr/Event.java Tue May 15 20:24:34 2018 +0200
@@ -0,0 +1,171 @@
+/*
+ * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package jdk.jfr;
+
+/**
+ * Base class for events, to be subclassed in order to define events and their
+ * fields.
+ * <p>
+ * The following example shows how to implement an {@code Event} class.
+ *
+ * <pre>
+ * <code>
+ * 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 event = new HelloWorld();
+ * event.message = "hello, world!";
+ * event.commit();
+ * }
+ * }
+ * </code>
+ * </pre>
+ * <p>
+ * 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.
+ * <p>
+ * By default, an event is enabled. To disable an event annotate the
+ * {@link Event} class with {@code @Enabled(false)}.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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 Event#commit()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.
+ * <p>
+ * 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.
+ * <p>
+ * Applicable only if the event is dynamically defined using the
+ * {@code EventFactory} class.
+ * <p>
+ * 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) {
+ }
+}