Module jdk.jfr
Package jdk.jfr

Class EventFactory


  • public final class EventFactory
extends Object
    Class for defining events at runtime.

    It's highly recommended that events are defined at compile time, if the field layout is known, as it allows the JVM to aggressively optimize the code, possibly removing all instrumentation if Flight Recorder is inactive or event is disabled.

    To define events at compile time, see Event.

    Example, 

     
 List<ValueDescriptor> fields = new ArrayList<>();
 List<AnnotationElement> messageAnnotations = Collections.singletonList(new AnnotationElement(Label.class, "Message"));
 fields.add(new ValueDescriptor(String.class, "message", messageAnnotations));
 List<AnnotationElement> numberAnnotations = Collections.singletonList(new AnnotationElement(Label.class, "Number"));
 fields.add(new ValueDescriptor(int.class, "number", numberAnnotations));

 String[] category = { "Example", "Getting Started" };
 List<AnnotationElement> eventAnnotations = new ArrayList<>();
 eventAnnotations.add(new AnnotationElement(Name.class, "com.example.HelloWorld"));
 eventAnnotations.add(new AnnotationElement(Label.class, "Hello World"));
 eventAnnotations.add(new AnnotationElement(Description.class, "Helps programmer getting started"));
 eventAnnotations.add(new AnnotationElement(Category.class, category));

 EventFactory f = EventFactory.create(eventAnnotations, fields);

 Event event = f.newEvent();
 event.set(0, "hello, world!");
 event.set(1, 4711);
 event.commit();
    Since:
    9

    • Method Detail

      • create

        public static EventFactory create​(List<AnnotationElement> annotationElements,
                                  List<ValueDescriptor> fields)
        Creates an EventFactory.

        The order of the value descriptors determines the index to use when setting event values.

        Parameters:
        annotationElements - list of AnnotationElement that describes the annotations on the event, not null
        fields - list ValueDescriptor that describes the fields of the event, not null
        Returns:
        event factory, not null
        Throws:
        IllegalArgumentException - if the input is not valid. This can happen if the field type or name is not valid in the Java language or an annotation element references a type that can't be found.
        SecurityException - if a security manager exists and the caller does not have FlightRecorderPermission("registerEvent")
        See Also:
        Event.set(int, Object)

      • newEvent

        public Event newEvent​()
        Instantiates an event, so it can be populated with data and committed.

        Use Event.set(int, Object) to set a value.

        Returns:
        an event instance, not null

      • getEventType

        public EventType getEventType​()
        Returns the event type associated with this factory.
        Returns:
        event type associated with this factory, not null
        Throws:
        IllegalStateException - if the event factory was created with the annotation Registered(false) and not registered manually before the invocation of this method

      • register

        public void register​()
        Registers an unregistered event.

        By default the event class associated with this factory is registered when the event factory is created, unless the event has the Registered annotation.

        Registered events can write data to Flight Recorder and their EventType can be obtained by calling FlightRecorder.getEventTypes().

        If the event class associated with this factory is already registered, the call to this method will be ignored.

        Throws:
        SecurityException - if a security manager exists and the caller does not have FlightRecorderPermission("registerEvent")
        See Also:
        Registered, FlightRecorder.register(Class)

      • unregister

        public void unregister​()
        Unregisters the event associated with this factory.

        Unregistered events can't write data to Flight Recorder and their EventType can't be obtained by calling FlightRecorder.getEventTypes().

        If the event class associated with this factory is already registered, the call to this method will be ignored.

        Throws:
        SecurityException - if a security manager exists and the caller does not have FlightRecorderPermission("registerEvent")
        See Also:
        Registered, FlightRecorder.unregister(Class)