OpenJDK 27 · jdk.jfr.Event · APIdia, the JavaDoc alternative

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 Event#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.

Access	Constructor and Description
protected	Event() Sole constructor, for invocation by subclass constructors, typically implicit.

Method Summary

Modifier and Type	Method and Description
public final void	begin() Overrides jdk.internal.event.Event.begin. Starts the timing of this event.
public final void	commit() Overrides jdk.internal.event.Event.commit. Writes the field values, time stamp, and event duration to the Flight Recorder system.
public final void	end() Overrides jdk.internal.event.Event.end. Ends the timing of this event.
public final boolean	Returns: `true` if event is enabled, `false` otherwise isEnabled() Overrides jdk.internal.event.Event.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.
public final void	set(int the index of the field that is passed to `EventFactory#create(java.util.List, java.util.List)` index, Object value to set, can be `null` value) Overrides jdk.internal.event.Event.set. Sets a field value.
public final boolean	Returns: `true` if the event can be written to the Flight Recorder system, `false` otherwise shouldCommit() Overrides jdk.internal.event.Event.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.

Constructor Detail

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

Method Detail

begin	back to summary
public final void begin() Overrides jdk.internal.event.Event.begin. Starts the timing of this event. Annotations @Override

begin

back to summary

public final void begin()

Overrides jdk.internal.event.Event.begin.

Starts the timing of this event.

Annotations

@Override

commit back to summary

commit	back to summary
public final void commit() Overrides jdk.internal.event.Event.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. Annotations @Override

public final void commit()

Overrides jdk.internal.event.Event.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.

Annotations

@Override

end back to summary

end	back to summary
public final void end() Overrides jdk.internal.event.Event.end. Ends the timing of this event. The `end` method must be invoked after the `begin` method. Annotations @Override

public final void end()

Overrides jdk.internal.event.Event.end.

Ends the timing of this event. The end method must be invoked after the begin method.

Annotations

@Override

isEnabled back to summary

isEnabled	back to summary
public final boolean isEnabled() Overrides jdk.internal.event.Event.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:boolean `true` if event is enabled, `false` otherwise Annotations @Override

public final boolean isEnabled()

Overrides jdk.internal.event.Event.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:boolean

true if event is enabled, false otherwise

Annotations

@Override

set back to summary

set	back to summary
public final void set(int index, Object value) Overrides jdk.internal.event.Event.set. 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:int the index of the field that is passed to `EventFactory#create(java.util.List, java.util.List)` value:Object value to set, can be `null` Annotations @Override Exceptions 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`

public final void set(int index, Object value)

Overrides jdk.internal.event.Event.set.

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:int: the index of the field that is passed to EventFactory#create(java.util.List, java.util.List)
value:Object: value to set, can be null

Annotations

@Override

Exceptions

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

shouldCommit back to summary

shouldCommit	back to summary
public final boolean shouldCommit() Overrides jdk.internal.event.Event.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:boolean `true` if the event can be written to the Flight Recorder system, `false` otherwise Annotations @Override

public final boolean shouldCommit()

Overrides jdk.internal.event.Event.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:boolean

true if the event can be written to the Flight Recorder system, false otherwise

Annotations

@Override

public abstract Class Event

Constructor Summary

Method Summary

Constructor Detail

Method Detail