Event (Java SE 26 & JDK 26)
Description: declaration: module: jdk.jfr, package: jdk.jfr, class: Event
Keywords: jdk.jfr.Event class

# Class Event

java.lang.Object
jdk.jfr.Event

public abstract class Event extends Object
Base class for events, to be subclassed in order to define events and their fields.

The following example shows how to implement an `Event` class.

    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();
        }
    }

After an event is allocated and its field members are populated, it can be written to the Flight Recorder system by using the `commit()` method.

By default, an event is enabled. To disable an event annotate the `Event` class with `@Enabled(false)`.

Supported field types are the Java primitives: `boolean`, `char`, `byte`, `short`, `int`, `long`, `float`, and `double`. Supported reference types are: `String`, `Thread` and `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, `Label`, `Description`, and `Timespan`). Annotations applied to an `Event` class or its fields are included if they are present (indirectly, directly, or associated), have the `MetadataDefinition` annotation, and they do not contain enums, arrays, or classes.

Gathering data to store in an event can be expensive. The `shouldCommit()` method can be used to verify whether an event instance would actually be written to the system when the `commit()` method is invoked. If `shouldCommit()` returns false, then those operations can be avoided.

Since:
  9

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Event()`
  Sole constructor, for invocation by subclass constructors, typically implicit.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final void`
  `begin()`
  Starts the timing of this event.
  `final void`
  `commit()`
  Writes the field values, time stamp, and event duration to the Flight Recorder system.
  `final void`
  `end()`
  Ends the timing of this event.
  `final boolean`
  `isEnabled()`
  Returns `true` if at least one recording is running, and the enabled setting for this event is set to `true`, otherwise `false` is returned.
  `final void`
  `set(int index, Object value)`
  Sets a field value.
  `final boolean`
  `shouldCommit()`
  Returns `true` if the enabled setting for this event is set to `true` and if the duration is within the threshold for the event, `false` otherwise.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Constructor Details

  - ### Event

    protected Event()
    Sole constructor, for invocation by subclass constructors, typically implicit.

- ## Method Details

  - ### begin

    public final void begin()
    Starts the timing of this event.

  - ### end

    public final void end()
    Ends the timing of this event. The `end` method must be invoked after the `begin` method.

  - ### commit

    public final void commit()
    Writes the field values, time stamp, and event duration to the Flight Recorder system.

    If the event starts with an invocation of the `begin` method, but does not end with an explicit invocation of the `end` method, then the event ends when the `commit` method is invoked.

  - ### isEnabled

    public final boolean isEnabled()
    Returns `true` if at least one recording is running, and the enabled setting for this event is set to `true`, otherwise `false` is returned.
    Returns:
      `true` if event is enabled, `false` otherwise

  - ### shouldCommit

    public final boolean shouldCommit()
    Returns `true` if the enabled setting for this event is set to `true` and if the duration is within the threshold for the event, `false` otherwise. The threshold is the minimum threshold for all running recordings.
    Returns:
      `true` if the event can be written to the Flight Recorder system, `false` otherwise

  - ### set

    public final void set(int index, Object value)
    Sets a field value.

    Applicable only if the event is dynamically defined using the `EventFactory` class.

    The supplied `index` corresponds to the index of the `ValueDescriptor` object passed to the factory method of the `EventFactory` class.

    Parameters:
      `index` - the index of the field that is passed to `EventFactory.create(java.util.List, java.util.List)`
      `value` - value to set, can be `null`
    Throws:
      `UnsupportedOperationException` - if it's not a dynamically generated event
      `IndexOutOfBoundsException` - if `index` is less than `0` or greater than or equal to the number of fields specified for the event
    See Also:
      - `EventType.getFields()`
      - `EventFactory`