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()	Answers a new instance of the same class as the receiver, whose slots have been filled in with the values in the slots of the receiver.
boolean	equals(Object o)	Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
protected void	finalize()	Deprecated, for removal: This API element is subject to removal in a future version. May cause performance issues, deadlocks and hangs.
final Class<? extends Object>	getClass()	Answers the unique instance of java.lang.Class which represents the class of the receiver.
int	hashCode()	Answers an integer hash code for the receiver.
final void	notify()	Causes one thread which is waiting on the receiver to be made ready to run.
final void	notifyAll()	Causes all threads which are waiting on the receiver to be made ready to run.
String	toString()	Answers a string containing a concise, human-readable description of the receiver.
final void	wait()	Causes the thread which sent this message to be made not ready to run pending some change in the receiver (as indicated by notify or notifyAll).
final void	wait(long time)	Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by notify or notifyAll) or the expiration of the timeout.
final void	wait(long time, int frac)	Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by notify or notifyAll) or the expiration of the timeout.

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