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
ModifierConstructorDescriptionprotected
Event()
Sole constructor, for invocation by subclass constructors, typically implicit. -
Method Summary
Modifier and TypeMethodDescriptionfinal 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
Returnstrue
if at least one recording is running, and the enabled setting for this event is set totrue
, otherwisefalse
is returned.final void
Sets a field value.final boolean
Returnstrue
if the enabled setting for this event is set totrue
and if the duration is within the threshold for the event,false
otherwise.
-
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. Theend
method must be invoked after thebegin
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 theend
method, then the event ends when thecommit
method is invoked. -
isEnabled
public final boolean isEnabled()Returnstrue
if at least one recording is running, and the enabled setting for this event is set totrue
, otherwisefalse
is returned.- Returns:
true
if event is enabled,false
otherwise
-
shouldCommit
public final boolean shouldCommit()Returnstrue
if the enabled setting for this event is set totrue
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
Sets a field value.Applicable only if the event is dynamically defined using the
EventFactory
class.The supplied
index
corresponds to the index of theValueDescriptor
object passed to the factory method of theEventFactory
class.- Parameters:
index
- the index of the field that is passed toEventFactory.create(java.util.List, java.util.List)
value
- value to set, can benull
- Throws:
UnsupportedOperationException
- if it's not a dynamically generated eventIndexOutOfBoundsException
- ifindex
is less than0
or greater than or equal to the number of fields specified for the event- See Also:
-