https://openjdk.java.net/ 
/*
 * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package jdk.jfr;


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. 

import jdk.jfr.Event;
import jdk.jfr.Description;
import jdk.jfr.Label;
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 Event#commit()commit method is invoked. If shouldCommit() returns false, then those operations can be avoided. 
Since:9
/**
 * Base class for events, to be subclassed in order to define events and their
 * fields.
 * <p>
 * The following example shows how to implement an {@code Event} class.
 *
 * <pre>
 * <code>
 * import jdk.jfr.Event;
 * import jdk.jfr.Description;
 * import jdk.jfr.Label;
 *
 * public class Example {
 *
 *   &#064;Label("Hello World")
 *   &#064;Description("Helps programmer getting started")
 *   static class HelloWorld extends Event {
 *       &#064;Label("Message")
 *       String message;
 *   }
 *
 *   public static void main(String... args) {
 *       HelloWorld event = new HelloWorld();
 *       event.message = "hello, world!";
 *       event.commit();
 *   }
 * }
 * </code>
 * </pre>
 * <p>
 * After an event is allocated and its field members are populated, it can be
 * written to the Flight Recorder system by using the {@code #commit()} method.
 * <p>
 * By default, an event is enabled. To disable an event annotate the
 * {@link Event} class with {@code @Enabled(false)}.
 * <p>
 * Supported field types are the Java primitives: {@code boolean}, {@code char},
 * {@code byte}, {@code short}, {@code int}, {@code long}, {@code float}, and
 * {@code double}. Supported reference types are: {@code String}, {@code Thread}
 * and {@code 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.
 * <p>
 * Tools can visualize data in a meaningful way when annotations are used (for
 * example, {@code Label}, {@code Description}, and {@code Timespan}).
 * Annotations applied to an {@link Event} class or its fields are included if
 * they are present (indirectly, directly, or associated), have the
 * {@code MetadataDefinition} annotation, and they do not contain enums, arrays,
 * or classes.
 * <p>
 * Gathering data to store in an event can be expensive. The
 * {@link Event#shouldCommit()} method can be used to verify whether an event
 * instance would actually be written to the system when the
 * {@code Event#commit()commit} method is invoked. If
 * {@link Event#shouldCommit()} returns false, then those operations can be
 * avoided.
 *
 * @since 9
 */
@Enabled(true)
@StackTrace(true)
@Registered(true)
abstract public class Event extends jdk.internal.event.Event {
    
Sole constructor, for invocation by subclass constructors, typically
implicit.

/**
     * Sole constructor, for invocation by subclass constructors, typically
     * implicit.
     */
    protected Event() {
    }

    
Starts the timing of this event.

/**
     * Starts the timing of this event.
     */
    final public void begin() {
    }

    
Ends the timing of this event. The end method must be invoked after the begin method. 
/**
     * Ends the timing of this event.
     *
     * The {@code end} method must be invoked after the {@code begin} method.
     */
    final public void end() {
    }

    
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. 
/**
     * Writes the field values, time stamp, and event duration to the Flight
     * Recorder system.
     * <p>
     * If the event starts with an invocation of the {@code begin} method, but does
     * not end with an explicit invocation of the {@code end} method, then the event
     * ends when the {@code commit} method is invoked.
     */
    final public void commit() {
    }

    
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
/**
     * Returns {@code true} if at least one recording is running, and the
     * enabled setting for this event is set to {@code true}, otherwise
     * {@code false} is returned.
     *
     * @return {@code true} if event is enabled, {@code false} otherwise
     */
    final public boolean isEnabled() {
        return false;
    }

    
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
/**
     * Returns {@code true} if the enabled setting for this event is set to
     * {@code true} and if the duration is within the threshold for the event,
     * {@code false} otherwise. The threshold is the minimum threshold for all
     * running recordings.
     *
     * @return {@code true} if the event can be written to the Flight Recorder
     *         system, {@code false} otherwise
     */
    final public boolean shouldCommit() {
        return false;
    }

    
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. 
Params:
  • index – the index of the field that is passed to EventFactory#create(String, java.util.List, java.util.List)
  • value – value to set, can be null
Throws:
See Also:
/**
     * Sets a field value.
     * <p>
     * Applicable only if the event is dynamically defined using the
     * {@code EventFactory} class.
     * <p>
     * The supplied {@code index} corresponds to the index of the
     * {@link ValueDescriptor} object passed to the factory method of the
     * {@code EventFactory} class.
     *
     * @param index the index of the field that is passed to
     *        {@code EventFactory#create(String, java.util.List, java.util.List)}
     * @param value value to set, can be {@code null}
     * @throws UnsupportedOperationException if it's not a dynamically generated
     *         event
     * @throws IndexOutOfBoundsException if {@code index} is less than {@code 0} or
     *         greater than or equal to the number of fields specified for the event
     *
     * @see EventType#getFields()
     * @see EventFactory
     */
    final public void set(int index, Object value) {
    }
}