1 /*
2 * Copyright 2006-2007 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.core.explore;
17
18 import java.util.List;
19 import java.util.Set;
20
21 import org.springframework.batch.core.JobExecution;
22 import org.springframework.batch.core.JobInstance;
23 import org.springframework.batch.core.StepExecution;
24 import org.springframework.batch.item.ExecutionContext;
25
26 /**
27 * Entry point for browsing executions of running or historical jobs and steps.
28 * Since the data may be re-hydrated from persistent storage, it may not contain
29 * volatile fields that would have been present when the execution was active.
30 *
31 * @author Dave Syer
32 *
33 * @since 2.0
34 */
35 public interface JobExplorer {
36
37 /**
38 * Fetch {@link JobInstance} values in descending order of creation (and
39 * therefore usually of first execution).
40 *
41 * @param jobName the name of the job to query
42 * @param start the start index of the instances to return
43 * @param count the maximum number of instances to return
44 * @return the {@link JobInstance} values up to a maximum of count values
45 */
46 List<JobInstance> getJobInstances(String jobName, int start, int count);
47
48 /**
49 * Retrieve a {@link JobExecution} by its id. The complete object graph for
50 * this execution should be returned (unless otherwise indicated) including
51 * the parent {@link JobInstance} and associated {@link ExecutionContext}
52 * and {@link StepExecution} instances (also including their execution
53 * contexts).
54 *
55 * @param executionId the job execution id
56 * @return the {@link JobExecution} with this id, or null if not found
57 */
58 JobExecution getJobExecution(Long executionId);
59
60 /**
61 * Retrieve a {@link StepExecution} by its id and parent
62 * {@link JobExecution} id. The execution context for the step should be
63 * available in the result, and the parent job execution should have its
64 * primitive properties, but may not contain the job instance information.
65 *
66 * @param jobExecutionId the parent job execution id
67 * @param stepExecutionId the step execution id
68 * @return the {@link StepExecution} with this id, or null if not found
69 *
70 * @see #getJobExecution(Long)
71 */
72 StepExecution getStepExecution(Long jobExecutionId, Long stepExecutionId);
73
74 /**
75 * @param instanceId
76 * @return the {@link JobInstance} with this id, or null
77 */
78 JobInstance getJobInstance(Long instanceId);
79
80 /**
81 * Retrieve job executions by their job instance. The corresponding step
82 * executions may not be fully hydrated (e.g. their execution context may be
83 * missing), depending on the implementation. Use
84 * {@link #getStepExecution(Long, Long)} to hydrate them in that case.
85 *
86 * @param jobInstance the {@link JobInstance} to query
87 * @return the set of all executions for the specified {@link JobInstance}
88 */
89 List<JobExecution> getJobExecutions(JobInstance jobInstance);
90
91 /**
92 * Retrieve running job executions. The corresponding step executions may
93 * not be fully hydrated (e.g. their execution context may be missing),
94 * depending on the implementation. Use
95 * {@link #getStepExecution(Long, Long)} to hydrate them in that case.
96 *
97 * @param jobName the name of the job
98 * @return the set of running executions for jobs with the specified name
99 */
100 Set<JobExecution> findRunningJobExecutions(String jobName);
101
102 /**
103 * Query the repository for all unique {@link JobInstance} names (sorted
104 * alphabetically).
105 *
106 * @return the set of job names that have been executed
107 */
108 List<String> getJobNames();
109
110 }