package com.easyagents.scheduler;

import java.time.Duration;
import java.time.Instant;

/**
 * 调度执行事件监听器，适合接入日志、指标和诊断事件。
 */
public interface ScheduleExecutionListener {

    /**
     * Handler 开始执行时回调。
     *
     * @param context 触发上下文
     */
    default void onStarted(ScheduleFireContext context) {
    }

    /**
     * Handler 成功完成时回调。
     *
     * @param context 触发上下文
     * @param duration 执行耗时
     */
    default void onSucceeded(ScheduleFireContext context, Duration duration) {
    }

    /**
     * Handler 执行失败时回调。
     *
     * @param context 触发上下文
     * @param duration 失败前执行耗时
     * @param failure 原始失败原因
     */
    default void onFailed(ScheduleFireContext context, Duration duration, Throwable failure) {
    }

    /**
     * 调度计划发生 Misfire 时回调。
     *
     * @param scheduleId 任务标识
     * @param expectedFireTime 原计划触发时间，底层无法提供时为空
     */
    default void onMisfired(ScheduleId scheduleId, Instant expectedFireTime) {
    }
}
