1 /*
2 * Copyright 2009-2010 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.springframework.batch.admin.service;
17
18 import java.util.Collection;
19
20 import org.springframework.batch.core.Job;
21 import org.springframework.batch.core.JobExecution;
22 import org.springframework.batch.core.JobInstance;
23 import org.springframework.batch.core.JobParameters;
24 import org.springframework.batch.core.JobParametersIncrementer;
25 import org.springframework.batch.core.JobParametersInvalidException;
26 import org.springframework.batch.core.Step;
27 import org.springframework.batch.core.StepExecution;
28 import org.springframework.batch.core.launch.JobExecutionNotRunningException;
29 import org.springframework.batch.core.launch.NoSuchJobException;
30 import org.springframework.batch.core.launch.NoSuchJobExecutionException;
31 import org.springframework.batch.core.launch.NoSuchJobInstanceException;
32 import org.springframework.batch.core.repository.JobExecutionAlreadyRunningException;
33 import org.springframework.batch.core.repository.JobInstanceAlreadyCompleteException;
34 import org.springframework.batch.core.repository.JobRepository;
35 import org.springframework.batch.core.repository.JobRestartException;
36 import org.springframework.batch.core.step.NoSuchStepException;
37 import org.springframework.batch.core.step.tasklet.Tasklet;
38
39 /**
40 * Interface for general purpose monitoring and management of Batch jobs. The
41 * features here can generally be composed from existing Spring Batch interfaces
42 * (although for performance reasons, implementations might choose
43 * special-purpose optimisations via a relation database, for instance).
44 *
45 * @author Dave Syer
46 *
47 */
48 public interface JobService {
49
50 /**
51 * Convenience method to determine if a job is available for launching. Job
52 * names returned from {@link #listJobs(int, int)} might be in the
53 * repository, but not be launchable if the host application has no
54 * configuration for them.
55 *
56 * @param jobName the name of the job
57 * @return true if the job is available for launching
58 */
59 boolean isLaunchable(String jobName);
60
61 /**
62 * Launch a job with the parameters provided. If an instance with the
63 * parameters provided has already failed (and is not abandoned) it will be
64 * restarted.
65 *
66 * @param jobName the job name
67 * @param params the {@link JobParameters}
68 * @return the resulting {@link JobExecution} if successful
69 *
70 * @throws NoSuchJobException
71 * @throws JobExecutionAlreadyRunningException
72 * @throws JobRestartException
73 * @throws JobInstanceAlreadyCompleteException
74 * @throws JobParametersInvalidException
75 */
76 JobExecution launch(String jobName, JobParameters params) throws NoSuchJobException,
77 JobExecutionAlreadyRunningException, JobRestartException, JobInstanceAlreadyCompleteException,
78 JobParametersInvalidException;
79
80 /**
81 * Get the last {@link JobParameters} used to execute a job successfully.
82 *
83 * @param jobName the name of the job
84 * @return the last parameters used to execute this job or empty if there
85 * are none
86 *
87 * @throws NoSuchJobException
88 */
89 JobParameters getLastJobParameters(String jobName) throws NoSuchJobException;
90
91 /**
92 * Launch a job with the parameters provided.
93 *
94 * @param jobExecutionId the job execution to restart
95 * @return the resulting {@link JobExecution} if successful
96 *
97 * @throws NoSuchJobExecutionException
98 * @throws JobExecutionAlreadyRunningException
99 * @throws JobRestartException
100 * @throws JobInstanceAlreadyCompleteException
101 * @throws NoSuchJobException
102 * @throws JobParametersInvalidException
103 */
104 JobExecution restart(Long jobExecutionId) throws NoSuchJobExecutionException, JobExecutionAlreadyRunningException,
105 JobRestartException, JobInstanceAlreadyCompleteException, NoSuchJobException, JobParametersInvalidException;
106
107 /**
108 * Launch a job with the parameters provided. JSR-352 supports restarting of jobs with a new set of parameters.
109 * This method exposes this functionality
110 *
111 * @param jobExecutionId the job execution to restart
112 * @param params the job parameters to use in the restart
113 * @return the resulting {@link JobExecution} if successful
114 *
115 * @throws NoSuchJobExecutionException
116 * @throws JobExecutionAlreadyRunningException
117 * @throws JobRestartException
118 * @throws JobInstanceAlreadyCompleteException
119 * @throws NoSuchJobException
120 * @throws JobParametersInvalidException
121 */
122 JobExecution restart(Long jobExecutionId, JobParameters params) throws NoSuchJobExecutionException, JobExecutionAlreadyRunningException,
123 JobRestartException, JobInstanceAlreadyCompleteException, NoSuchJobException, JobParametersInvalidException;
124
125 /**
126 * Send a signal to a job execution to stop processing. This method does not
127 * guarantee that the processing will stop, only that the signal will be
128 * delivered. It is up to the individual {@link Job} and {@link Step}
129 * implementations to ensure that the signal is obeyed. In particular, if
130 * users provide a custom {@link Tasklet} to a {@link Step} it must check
131 * the signal in the {@link JobExecution} itself.
132 *
133 * @param jobExecutionId the job execution id to stop
134 * @return the {@link JobExecution} that was stopped
135 * @throws NoSuchJobExecutionException
136 * @throws JobExecutionNotRunningException
137 */
138 JobExecution stop(Long jobExecutionId) throws NoSuchJobExecutionException, JobExecutionNotRunningException;
139
140 /**
141 * Mark the {@link JobExecution} as ABANDONED. If a stop signal is ignored
142 * because the process died this is the best way to mark a job as finished
143 * with (as opposed to STOPPED). An abandoned job execution can be
144 * restarted, but a stopping one cannot.
145 *
146 * @param jobExecutionId the job execution id to abort
147 * @return the {@link JobExecution} that was aborted
148 * @throws NoSuchJobExecutionException
149 * @throws JobExecutionAlreadyRunningException if the job is running (it
150 * should be stopped first)
151 */
152 JobExecution abandon(Long jobExecutionId) throws NoSuchJobExecutionException, JobExecutionAlreadyRunningException;
153
154 /**
155 * Query the job names in the system, either launchable or not. If not
156 * launchable, then there must be a history of the job having been launched
157 * previously in the {@link JobRepository}.
158 *
159 * @param start the start index of the job names to return
160 * @param count the maximum number of job names to return
161 * @return a collection of job names
162 */
163 Collection<String> listJobs(int start, int count);
164
165 /**
166 * Count the total number of jobs that can be returned by
167 * {@link #listJobs(int, int)}.
168 *
169 * @return the total number of jobs
170 */
171 int countJobs();
172
173 /**
174 * Get a {@link JobInstance job instance} by id.
175 *
176 * @param jobInstanceId the id of the instance
177 * @return a {@link JobInstance job instance}
178 * @throws NoSuchJobInstanceException
179 */
180 JobInstance getJobInstance(long jobInstanceId) throws NoSuchJobInstanceException;
181
182 /**
183 * List the {@link JobInstance job instances} in descending order of
184 * creation (usually close to order of execution).
185 *
186 * @param jobName the name of the job
187 * @param start the index of the first to return
188 * @param count the maximum number of instances to return
189 * @return a collection of {@link JobInstance job instances}
190 * @throws NoSuchJobException
191 */
192 Collection<JobInstance> listJobInstances(String jobName, int start, int count) throws NoSuchJobException;
193
194 /**
195 * Count the number of {@link JobInstance job instances} in the repository
196 * for a given job name.
197 *
198 * @param jobName the name of the job
199 * @return the number of job instances available
200 * @throws NoSuchJobException
201 */
202 int countJobInstances(String jobName) throws NoSuchJobException;
203
204 /**
205 * List the {@link JobExecution job executions} for a job in descending
206 * order of creation (usually close to execution order).
207 *
208 * @param jobName the job name
209 * @param start the start index of the first job execution
210 * @param count the maximum number of executions to return
211 * @return a collection of {@link JobExecution}
212 * @throws NoSuchJobException
213 */
214 Collection<JobExecution> listJobExecutionsForJob(String jobName, int start, int count) throws NoSuchJobException;
215
216 /**
217 * Count the job executions in the repository for a job.
218 *
219 * @param jobName the job name
220 * @return the number of executions
221 * @throws NoSuchJobException
222 */
223 int countJobExecutionsForJob(String jobName) throws NoSuchJobException;
224
225 /**
226 * Get all the job executions for a given job instance. On a sunny day there
227 * would be only one. If there have been failures and restarts there may be
228 * many, and they will be listed in reverse order of primary key.
229 *
230 * @param jobName the name of the job
231 * @param jobInstanceId the id of the job instance
232 * @return all the job executions
233 * @throws NoSuchJobException
234 */
235 Collection<JobExecution> getJobExecutionsForJobInstance(String jobName, Long jobInstanceId)
236 throws NoSuchJobException;
237
238 /**
239 * List the {@link JobExecution job executions} in descending order of
240 * creation (usually close to execution order).
241 *
242 * @param start the index of the first execution to return
243 * @param count the maximum number of executions
244 * @return a collection of {@link JobExecution}
245 */
246 Collection<JobExecution> listJobExecutions(int start, int count);
247
248 /**
249 * Count the maximum number of executions that could be returned by
250 * {@link #listJobExecutions(int, int)}.
251 *
252 * @return the number of job executions in the job repository
253 */
254 int countJobExecutions();
255
256 /**
257 * Get a {@link JobExecution} by id.
258 *
259 * @param jobExecutionId the job execution id
260 * @return the {@link JobExecution}
261 *
262 * @throws NoSuchJobExecutionException
263 */
264 JobExecution getJobExecution(Long jobExecutionId) throws NoSuchJobExecutionException;
265
266 /**
267 * Get the {@link StepExecution step executions} for a given job execution
268 * (by id).
269 *
270 * @param jobExecutionId the parent job execution id
271 * @return the step executions for the job execution
272 *
273 * @throws NoSuchJobExecutionException
274 */
275 Collection<StepExecution> getStepExecutions(Long jobExecutionId) throws NoSuchJobExecutionException;
276
277 /**
278 * List the {@link StepExecution step executions} for a step in descending
279 * order of creation (usually close to execution order).
280 * @param jobName the name of the job associated with the step (or a pattern
281 * with wildcards)
282 * @param stepName the step name (or a pattern with wildcards)
283 * @param start the start index of the first execution
284 * @param count the maximum number of executions to return
285 *
286 * @return a collection of {@link StepExecution}
287 * @throws NoSuchStepException
288 */
289 Collection<StepExecution> listStepExecutionsForStep(String jobName, String stepName, int start, int count)
290 throws NoSuchStepException;
291
292 /**
293 * Count the step executions in the repository for a given step name (or
294 * pattern).
295 * @param jobName the job name (or a pattern with wildcards)
296 * @param stepName the step name (or a pattern with wildcards)
297 *
298 * @return the number of executions
299 * @throws NoSuchStepException
300 */
301 int countStepExecutionsForStep(String jobName, String stepName) throws NoSuchStepException;
302
303 /**
304 * Locate a {@link StepExecution} from its id and that of its parent
305 * {@link JobExecution}.
306 *
307 * @param jobExecutionId the job execution id
308 * @param stepExecutionId the step execution id
309 * @return the {@link StepExecution}
310 *
311 * @throws NoSuchStepExecutionException
312 * @throws NoSuchJobExecutionException
313 */
314 StepExecution getStepExecution(Long jobExecutionId, Long stepExecutionId) throws NoSuchStepExecutionException,
315 NoSuchJobExecutionException;
316
317 /**
318 * Send a stop signal to all running job executions.
319 *
320 * @return the number of executions affected
321 */
322 int stopAll();
323
324 /**
325 * Check if a job has a {@link JobParametersIncrementer}.
326 *
327 * @param jobName the job name
328 * @return true if the job exists and has an incrementer
329 */
330 boolean isIncrementable(String jobName);
331
332 /**
333 * Get the names of the steps in a job (or a historical list of recent
334 * execution names if the Job is not launchable).
335 *
336 * @param jobName the name of the job
337 * @throws NoSuchJobException if the job name cannot be located
338 */
339 Collection<String> getStepNamesForJob(String jobName) throws NoSuchJobException;
340
341 }