View Javadoc

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 }