/*
 * 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;


Callback interface to monitor Flight Recorder's life cycle.
Since:
9/**
 * Callback interface to monitor Flight Recorder's life cycle.
 *
 * @since 9
 */
public interface FlightRecorderListener {

    
Receives notification when Flight Recorder is initialized.

This method is also be invoked when a listener is added to an already
initialized Flight Recorder.
 This method allows clients to implement their own initialization mechanism that is executed before a FlightRecorder instance is returned by FlightRecorder#getFlightRecorder(). 
Params:
recorder – Flight Recorder instance, not null
See Also:
FlightRecorder.addListener(FlightRecorderListener)
Implementation Note:
This method should return as soon as possible, to avoid blocking initialization of Flight Recorder. To avoid deadlocks or unexpected behavior, this method should not call FlightRecorder.getFlightRecorder() or start new recordings.
Implementation Requirements:
The default implementation of this method is empty./**
     * Receives notification when Flight Recorder is initialized.
     * <p>
     * This method is also be invoked when a listener is added to an already
     * initialized Flight Recorder.
     * <p>
     * This method allows clients to implement their own initialization mechanism
     * that is executed before a {@code FlightRecorder} instance is returned by
     * {@code FlightRecorder#getFlightRecorder()}.
     *
     * @implNote This method should return as soon as possible, to avoid blocking
     *           initialization of Flight Recorder. To avoid deadlocks or unexpected
     *           behavior, this method should not call
     *           {@link FlightRecorder#getFlightRecorder()} or start new recordings.
     *
     * @implSpec The default implementation of this method is empty.
     *
     * @param recorder Flight Recorder instance, not {@code null}
     *
     * @see FlightRecorder#addListener(FlightRecorderListener)
     */
    default void recorderInitialized(FlightRecorder recorder) {
    }

    
Receives notification when the state of a recording changes.
 Callback is invoked when a recording reaches the RUNNING, STOPPED and CLOSED state. 
Params:
recording – the recording where the state change occurred, not null
See Also:
FlightRecorder.addListener(FlightRecorderListener)
RecordingState
Implementation Note:
The implementation of this method should return as soon as possible
          to avoid blocking normal operation of Flight Recorder.
Implementation Requirements:
The default implementation of this method is empty./**
     * Receives notification when the state of a recording changes.
     * <p>
     * Callback is invoked when a recording reaches the {@code RUNNING},
     * {@code STOPPED} and {@code CLOSED} state.
     *
     * @implNote The implementation of this method should return as soon as possible
     *           to avoid blocking normal operation of Flight Recorder.
     *
     * @implSpec The default implementation of this method is empty.
     *
     * @param recording the recording where the state change occurred, not
     *        {@code null}
     *
     * @see FlightRecorder#addListener(FlightRecorderListener)
     * @see RecordingState
     *
     */
    default void recordingStateChanged(Recording recording) {
    }
}