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.launch;
17  
18  import java.util.List;
19  import java.util.Map;
20  import java.util.Set;
21  
22  import org.springframework.batch.core.Job;
23  import org.springframework.batch.core.JobExecution;
24  import org.springframework.batch.core.JobInstance;
25  import org.springframework.batch.core.JobParameters;
26  import org.springframework.batch.core.JobParametersIncrementer;
27  import org.springframework.batch.core.JobParametersInvalidException;
28  import org.springframework.batch.core.StepExecution;
29  import org.springframework.batch.core.UnexpectedJobExecutionException;
30  import org.springframework.batch.core.repository.JobExecutionAlreadyRunningException;
31  import org.springframework.batch.core.repository.JobInstanceAlreadyCompleteException;
32  import org.springframework.batch.core.repository.JobRestartException;
33  
34  /**
35   * Low level interface for inspecting and controlling jobs with access only to
36   * primitive and collection types. Suitable for a command-line client (e.g. that
37   * launches a new process for each operation), or a remote launcher like a JMX
38   * console.
39   * 
40   * @author Dave Syer
41   * @since 2.0
42   */
43  public interface JobOperator {
44  
45  	/**
46  	 * List the {@link JobExecution JobExecutions} associated with a particular
47  	 * {@link JobInstance}, in reverse order of creation (and therefore usually
48  	 * of execution).
49  	 * 
50  	 * @param instanceId the id of a {@link JobInstance}
51  	 * @return the id values of all the {@link JobExecution JobExecutions}
52  	 * associated with this instance
53  	 * @throws NoSuchJobInstanceException
54  	 */
55  	List<Long> getExecutions(long instanceId) throws NoSuchJobInstanceException;
56  
57  	/**
58  	 * List the {@link JobInstance JobInstances} for a given job name, in
59  	 * reverse order of creation (and therefore usually of first execution).
60  	 * 
61  	 * @param jobName the job name that all the instances have
62  	 * @param start the start index of the instances
63  	 * @param count the maximum number of values to return
64  	 * @return the id values of the {@link JobInstance JobInstances}
65  	 * @throws NoSuchJobException
66  	 */
67  	List<Long> getJobInstances(String jobName, int start, int count) throws NoSuchJobException;
68  
69  	/**
70  	 * Get the id values of all the running {@link JobExecution JobExecutions}
71  	 * with the given job name.
72  	 * 
73  	 * @param jobName the name of the job to search under
74  	 * @return the id values of the running {@link JobExecution} instances
75  	 * @throws NoSuchJobException if there are no {@link JobExecution
76  	 * JobExecutions} with that job name
77  	 */
78  	Set<Long> getRunningExecutions(String jobName) throws NoSuchJobException;
79  
80  	/**
81  	 * Get the {@link JobParameters} as an easily readable String.
82  	 * 
83  	 * @param executionId the id of an existing {@link JobExecution}
84  	 * @return the job parameters that were used to launch the associated
85  	 * instance
86  	 * @throws NoSuchJobExecutionException if the id was not associated with any
87  	 * {@link JobExecution}
88  	 */
89  	String getParameters(long executionId) throws NoSuchJobExecutionException;
90  
91  	/**
92  	 * Start a new instance of a job with the parameters specified.
93  	 * 
94  	 * @param jobName the name of the {@link Job} to launch
95  	 * @param parameters the parameters to launch it with (comma or newline
96  	 * separated name=value pairs)
97  	 * @return the id of the {@link JobExecution} that is launched
98  	 * @throws NoSuchJobException if there is no {@link Job} with the specified
99  	 * name
100 	 * @throws JobInstanceAlreadyExistsException if a job instance with this
101 	 * name and parameters already exists
102 	 * @throws JobParametersInvalidException 
103 	 */
104 	Long start(String jobName, String parameters) throws NoSuchJobException, JobInstanceAlreadyExistsException, JobParametersInvalidException;
105 
106 	/**
107 	 * Restart a failed or stopped {@link JobExecution}. Fails with an exception
108 	 * if the id provided does not exist or corresponds to a {@link JobInstance}
109 	 * that in normal circumstances already completed successfully.
110 	 * 
111 	 * @param executionId the id of a failed or stopped {@link JobExecution}
112 	 * @return the id of the {@link JobExecution} that was started
113 	 * 
114 	 * @throws JobInstanceAlreadyCompleteException if the job was already
115 	 * successfully completed
116 	 * @throws NoSuchJobExecutionException if the id was not associated with any
117 	 * {@link JobExecution}
118 	 * @throws NoSuchJobException if the {@link JobExecution} was found, but its
119 	 * corresponding {@link Job} is no longer available for launching
120 	 * @throws JobRestartException if there is a non-specific error with the
121 	 * restart (e.g. corrupt or inconsistent restart data)
122 	 * @throws JobParametersInvalidException if the parameters are not valid for
123 	 * this job
124 	 */
125 	Long restart(long executionId) throws JobInstanceAlreadyCompleteException, NoSuchJobExecutionException,
126 			NoSuchJobException, JobRestartException, JobParametersInvalidException;
127 
128 	/**
129 	 * Launch the next in a sequence of {@link JobInstance} determined by the
130 	 * {@link JobParametersIncrementer} attached to the specified job. If the
131 	 * previous instance is still in a failed state, this method should still
132 	 * create a new instance and run it with different parameters (as long as
133 	 * the {@link JobParametersIncrementer} is working).<br/>
134 	 * <br/>
135 	 * 
136 	 * The last three exception described below should be extremely unlikely,
137 	 * but cannot be ruled out entirely. It points to some other thread or
138 	 * process trying to use this method (or a similar one) at the same time.
139 	 * 
140 	 * @param jobName the name of the job to launch
141 	 * @return the {@link JobExecution} id of the execution created when the job
142 	 * is launched
143 	 * @throws NoSuchJobException if there is no such job definition available
144 	 * @throws JobParametersNotFoundException if the parameters cannot be found
145 	 * @throws JobParametersInvalidException 
146 	 * @throws UnexpectedJobExecutionException 
147 	 * @throws UnexpectedJobExecutionException if an unexpected condition arises
148 	 */
149 	Long startNextInstance(String jobName) throws NoSuchJobException, JobParametersNotFoundException,
150 			JobRestartException, JobExecutionAlreadyRunningException, JobInstanceAlreadyCompleteException, UnexpectedJobExecutionException, JobParametersInvalidException;
151 
152 	/**
153 	 * Send a stop signal to the {@link JobExecution} with the supplied id. The
154 	 * signal is successfully sent if this method returns true, but that doesn't
155 	 * mean that the job has stopped. The only way to be sure of that is to poll
156 	 * the job execution status.
157 	 * 
158 	 * @param executionId the id of a running {@link JobExecution}
159 	 * @return true if the message was successfully sent (does not guarantee
160 	 * that the job has stopped)
161 	 * @throws NoSuchJobExecutionException if there is no {@link JobExecution}
162 	 * with the id supplied
163 	 * @throws JobExecutionNotRunningException if the {@link JobExecution} is
164 	 * not running (so cannot be stopped)
165 	 */
166 	boolean stop(long executionId) throws NoSuchJobExecutionException, JobExecutionNotRunningException;
167 
168 	/**
169 	 * Summarise the {@link JobExecution} with the supplied id, giving details
170 	 * of status, start and end times etc.
171 	 * 
172 	 * @param executionId the id of an existing {@link JobExecution}
173 	 * @return a String summarising the state of the job execution
174 	 * @throws NoSuchJobExecutionException if there is no {@link JobExecution}
175 	 * with the supplied id
176 	 */
177 	String getSummary(long executionId) throws NoSuchJobExecutionException;
178 
179 	/**
180 	 * Summarise the {@link StepExecution} instances belonging to the
181 	 * {@link JobExecution} with the supplied id, giving details of status,
182 	 * start and end times etc.
183 	 * 
184 	 * @param executionId the id of an existing {@link JobExecution}
185 	 * @return a map of step execution id to String summarising the state of the
186 	 * execution
187 	 * @throws NoSuchJobExecutionException if there is no {@link JobExecution}
188 	 * with the supplied id
189 	 */
190 	Map<Long, String> getStepExecutionSummaries(long executionId) throws NoSuchJobExecutionException;
191 
192 	/**
193 	 * List the available job names that can be launched with
194 	 * {@link #start(String, String)}.
195 	 * 
196 	 * @return a set of job names
197 	 */
198 	Set<String> getJobNames();
199 
200     /**
201      * Mark the {@link JobExecution} as ABANDONED. If a stop signal is ignored
202      * because the process died this is the best way to mark a job as finished
203      * with (as opposed to STOPPED). An abandoned job execution can be
204      * restarted, but a stopping one cannot.
205      *
206      * @param jobExecutionId the job execution id to abort
207      * @return the {@link JobExecution} that was aborted
208      * @throws NoSuchJobExecutionException
209      * @throws JobExecutionAlreadyRunningException if the job is running (it
210      * should be stopped first)
211      */
212     JobExecution abandon(long jobExecutionId) throws NoSuchJobExecutionException, JobExecutionAlreadyRunningException;
213 }