1 package com.atlassian.scheduler.core;
2
3 import com.atlassian.scheduler.SchedulerServiceException;
4 import com.atlassian.scheduler.core.LifecycleAwareSchedulerService.State;
5
6 import javax.annotation.Nonnull;
7 import java.util.Collection;
8 import java.util.concurrent.TimeUnit;
9
10 public interface SchedulerServiceController {
11 /**
12 * Starts the scheduler if it had never been started or had been placed in {@link #standby()} mode.
13 * If the scheduler was already active, then the request has no effect.
14 *
15 * @throws SchedulerServiceException if the scheduler cannot be started
16 */
17 void start() throws SchedulerServiceException;
18
19 /**
20 * Places the scheduler into standby mode. This stops jobs from running until it is {@link #start() started}
21 * again. If the scheduler was already in standby, then the request has no effect. The standby mode only
22 * affects the local node's ability to schedule jobs. For any
23 * {@link com.atlassian.scheduler.config.RunMode#RUN_ONCE_PER_CLUSTER} jobs the jobs may still run on other
24 * nodes if they exist and have started. If a job should have run while the scheduler was in standby mode, the
25 * implementation may trigger those jobs when restarted, but this is not guaranteed.
26 *
27 * @throws SchedulerServiceException if the scheduler cannot be be placed in standby mode
28 */
29 void standby() throws SchedulerServiceException;
30
31 /**
32 * Permanent shutdown of the scheduler. Once this has been called, no more jobs will be run
33 * and most requests will fail. The scheduler cannot be restarted once it has been shut down.
34 */
35 void shutdown();
36
37 /**
38 * Returns the list of jobs that are currently executing on this node.
39 * In a clustered configuration, this will not reflect any jobs that are running on another
40 * node of the cluster. This is guaranteed to be safe to call even after a {@link #shutdown()}.
41 *
42 * @return the job IDs for all jobs that are currently running on this node.
43 * @since v1.3
44 */
45 @Nonnull
46 Collection<RunningJob> getLocallyRunningJobs();
47
48 /**
49 * Waits for up to {@code timeout} {@code units} for any currently executing jobs to complete.
50 * Note that if the scheduler has not been {@link #shutdown()} or placed in {@link #standby()}
51 * mode, then jobs could start after this returns {@code true}. As with {@link #getLocallyRunningJobs()},
52 * this is only aware of jobs running on this node of the cluster, and it is guaranteed to be safe to
53 * call even after a {@link #shutdown()}.
54 *
55 * @param timeout the timeout period, in the specified units; non-positive values request an immediate
56 * poll — that is, it is equivalent to {@code getLocallyRunningJobs().isEmpty()}
57 * @return {@code true} if the scheduler is now idle; {@code false} if jobs are still executing.
58 * @throws InterruptedException if the current thread is interrupted while waiting for the
59 * scheduler to become idle.
60 * @throws IllegalArgumentException if {@code timeout} is negative
61 * @since v1.3
62 */
63 boolean waitUntilIdle(long timeout, TimeUnit units) throws InterruptedException;
64
65 /**
66 * Returns the scheduler service's running state. The scheduler is initially in {@link State#STANDBY}
67 * and can be moved between this state and {@link State#STANDBY} freely. {@link State#SHUTDOWN} is
68 * terminal — that is, once shut down, the scheduler's state can no longer be changed.
69 *
70 * @return the scheduler service's running state.
71 */
72 @Nonnull
73 State getState();
74 }