package com.bonus.job.service;

import java.util.List;
import org.quartz.SchedulerException;
import com.bonus.common.core.exception.job.TaskException;
import com.bonus.job.domain.SysJob;

/**
 * 定时任务调度信息服务层接口，提供定时任务的管理和操作功能。
 *
 * @author bonus
 */
public interface ISysJobService {

    /**
     * 获取quartz调度器的计划任务列表。
     *
     * @param job 查询条件，可以为null。
     * @return 返回符合条件的调度任务集合。
     */
    List<SysJob> selectJobList(SysJob job);

    /**
     * 通过调度任务ID查询调度任务详细信息。
     *
     * @param jobId 调度任务ID。
     * @return 返回对应的调度任务对象，如果没有找到则返回null。
     */
    SysJob selectJobById(Long jobId);

    /**
     * 暂停指定的调度任务。
     *
     * @param job 要暂停的调度任务信息。
     * @return 返回操作结果，成功返回1，失败返回0。
     * @throws SchedulerException 如果调度器操作失败。
     */
    int pauseJob(SysJob job) throws SchedulerException;

    /**
     * 恢复指定的调度任务。
     *
     * @param job 要恢复的调度任务信息。
     * @return 返回操作结果，成功返回1，失败返回0。
     * @throws SchedulerException 如果调度器操作失败。
     */
    int resumeJob(SysJob job) throws SchedulerException;

    /**
     * 删除指定的调度任务以及其对应的触发器。
     *
     * @param job 要删除的调度任务信息。
     * @return 返回操作结果，成功返回1，失败返回0。
     * @throws SchedulerException 如果调度器操作失败。
     */
    int deleteJob(SysJob job) throws SchedulerException;

    /**
     * 批量删除指定的调度任务。
     *
     * @param jobIds 要删除的任务ID数组。
     * @throws SchedulerException 如果调度器操作失败。
     */
    void deleteJobByIds(Long[] jobIds) throws SchedulerException;

    /**
     * 修改调度任务的状态。
     *
     * @param job 包含新状态的调度任务信息。
     * @return 返回操作结果，成功返回1，失败返回0。
     * @throws SchedulerException 如果调度器操作失败。
     */
    int changeStatus(SysJob job) throws SchedulerException;

    /**
     * 立即执行指定的调度任务。
     *
     * @param job 要立即执行的调度任务信息。
     * @return 返回操作结果，成功返回true，失败返回false。
     * @throws SchedulerException 如果调度器操作失败。
     */
    boolean run(SysJob job) throws SchedulerException;

    /**
     * 新增一个调度任务。
     *
     * @param job 要新增的调度任务信息。
     * @return 返回操作结果，成功返回1，失败返回0。
     * @throws SchedulerException 如果调度器操作失败。
     * @throws TaskException 如果任务相关的错误发生。
     */
    int insertJob(SysJob job) throws SchedulerException, TaskException;

    /**
     * 更新现有的调度任务。
     *
     * @param job 包含更新信息的调度任务对象。
     * @return 返回操作结果，成功返回1，失败返回0。
     * @throws SchedulerException 如果调度器操作失败。
     * @throws TaskException 如果任务相关的错误发生。
     */
    int updateJob(SysJob job) throws SchedulerException, TaskException;

    /**
     * 校验给定的cron表达式是否有效。
     *
     * @param cronExpression 要校验的cron表达式。
     * @return 如果cron表达式有效则返回true，否则返回false。
     */
    boolean checkCronExpressionIsValid(String cronExpression);
}