public abstract class Event extends Object
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.
Modifier | Constructor | Description |
---|---|---|
protected |
Sole constructor, for invocation by subclass constructors, typically implicit. |
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 |
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. |
protected Event()
public final void begin()
public final void end()
end
method must be invoked after the begin
method.public final void commit()
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.
public final boolean isEnabled()
true
if at least one recording is running, and the enabled setting for this event is set to true
, otherwise false
is returned.true
if event is enabled, false
otherwisepublic final boolean shouldCommit()
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.true
if the event can be written to the Flight Recorder system, false
otherwisepublic final void set(int index, Object 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.
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
UnsupportedOperationException
- if it's not a dynamically generated eventIndexOutOfBoundsException
- if index
is less than 0
or greater than or equal to the number of fields specified for the event
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.jfr/jdk/jfr/Event.html