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 /**
  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 }