1 package com.atlassian.scheduler.status;
2
3 import com.atlassian.annotations.PublicApi;
4 import com.atlassian.scheduler.JobRunner;
5 import com.atlassian.scheduler.SchedulerRuntimeException;
6 import com.atlassian.scheduler.SchedulerService;
7 import com.atlassian.scheduler.config.JobConfig;
8 import com.atlassian.scheduler.config.JobId;
9 import com.atlassian.scheduler.config.JobRunnerKey;
10 import com.atlassian.scheduler.config.RunMode;
11 import com.atlassian.scheduler.config.Schedule;
12
13 import javax.annotation.CheckForNull;
14 import javax.annotation.Nonnull;
15 import javax.annotation.concurrent.Immutable;
16 import java.io.Serializable;
17 import java.util.Date;
18 import java.util.Map;
19
20 /**
21 * All the static details for a given scheduled job. This is similar to a {@link JobConfig},
22 * but also includes information about the job's current state, such as whether it is
23 * currently {@link #isRunnable() runnable}.
24 *
25 * @see JobConfig
26 * @see RunDetails
27 */
28 @Immutable
29 @PublicApi
30 public interface JobDetails {
31 /**
32 * Returns the job ID that was used to {@link SchedulerService#scheduleJob(JobId, JobConfig) schedule}
33 * this job, or the one that was generated for it if the job was scheduled
34 * {@link SchedulerService#scheduleJobWithGeneratedId(JobConfig) without specifying one}.
35 *
36 * @return the job ID
37 */
38 @Nonnull
39 JobId getJobId();
40
41 /**
42 * Returns the {@link JobConfig#getJobRunnerKey() job runner key} that was specified when this job was
43 * {@link SchedulerService#scheduleJob(JobId, JobConfig) scheduled}.
44 *
45 * @return the job runner key
46 */
47 @Nonnull
48 JobRunnerKey getJobRunnerKey();
49
50 /**
51 * Returns the {@link JobConfig#getRunMode() configured run mode} that was specified
52 * when this job was {@link SchedulerService#scheduleJob(JobId, JobConfig) scheduled}.
53 *
54 * @return the run mode
55 */
56 @Nonnull
57 RunMode getRunMode();
58
59 /**
60 * Returns the schedule that the Job will run under.
61 *
62 * @return the schedule that the Job will run under.
63 */
64 @Nonnull
65 Schedule getSchedule();
66
67 /**
68 * Returns the next time at which this job will run, if known.
69 * <p>
70 * <em>OPTIONAL</em> — Scheduler implementations are not required to provide this
71 * information. The return value will be {@code null} if:
72 * </p>
73 * <ul>
74 * <li>The job will never run again because its schedule does not match any time in the future.</li>
75 * <li>The next time the job will run is so far in the future that the scheduler service gave up
76 * on trying to figure out when the next run would be.</li>
77 * <li>The scheduler implementation does not provide this information.</li>
78 * </ul>
79 *
80 * @return the next time at which this job will run, if known; {@code null} otherwise.
81 */
82 @CheckForNull
83 Date getNextRunTime();
84
85 /**
86 * Returns the configured runtime parameters for this job.
87 * <p>
88 * <strong>WARNING</strong>: If this job was created by a plugin that is not currently active,
89 * then it may not actually be possible to access the job's parameters, and this method will throw
90 * a {@link SchedulerRuntimeException}. Callers are encouraged to first call the
91 * {@link #isRunnable()} method, as a {@code false} return value from that method usually
92 * <em>guarantees</em> that this method will fail.
93 * </p>
94 *
95 * @return the configured runtime parameters for this job.
96 * @throws SchedulerRuntimeException if the parameters could not be loaded, likely because the
97 * job runner is not registered
98 */
99 @Nonnull
100 Map<String, Serializable> getParameters();
101
102 /**
103 * Returns {@code true} if this job could be successfully run at this time. This requires it to have
104 * a registered {@link JobRunner} whose class loader can successfully reconstruct the job's
105 * {@link JobConfig#getParameters() parameter map}.
106 *
107 * @return {@code true} if this job is currently runnable; {@code false} otherwise
108 */
109 boolean isRunnable();
110 }
111