package com.atlassian.stash.internal.scheduling;

import com.atlassian.scheduler.SchedulerService;
import com.atlassian.scheduler.SchedulerServiceException;

import javax.annotation.Nonnull;

/**
 * Describes a component which provides one or more scheduled jobs to be registered with the {@code SchedulerService}.
 *
 * @since 3.2
 */
public interface ScheduledJobSource {

    /**
     * Registers job runners and schedules jobs.
     *
     * @param schedulerService the scheduler to register jobs and runners with
     * @throws SchedulerServiceException if the {@code SchedulerService} throws an exception
     */
    void schedule(@Nonnull SchedulerService schedulerService) throws SchedulerServiceException;

    /**
     * Unregisters job runners. In general implementations should <i>not</i> unschedule jobs. Unscheduling a job
     * applies to all nodes in the cluster, for {@code RunMode.RUN_ONCE_PER_CLUSTER}, and shutting down a single
     * node should not prevent the remaining nodes from continuing to run jobs. For simplicity/consistency even
     * {@code RunMode.RUN_LOCALLY} jobs should not be unregistered; they will be garbage collected after the
     * application has shutdown.
     *
     * @param schedulerService
     * @throws SchedulerServiceException
     */
    void unschedule(@Nonnull SchedulerService schedulerService) throws SchedulerServiceException;
}
