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 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 8
  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 }