001/*
002 * Copyright 2006-2007 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.springframework.batch.core.launch;
017
018import java.util.List;
019import java.util.Map;
020import java.util.Set;
021
022import org.springframework.batch.core.Job;
023import org.springframework.batch.core.JobExecution;
024import org.springframework.batch.core.JobInstance;
025import org.springframework.batch.core.JobParameters;
026import org.springframework.batch.core.JobParametersIncrementer;
027import org.springframework.batch.core.JobParametersInvalidException;
028import org.springframework.batch.core.StepExecution;
029import org.springframework.batch.core.UnexpectedJobExecutionException;
030import org.springframework.batch.core.repository.JobExecutionAlreadyRunningException;
031import org.springframework.batch.core.repository.JobInstanceAlreadyCompleteException;
032import org.springframework.batch.core.repository.JobRestartException;
033
034/**
035 * Low level interface for inspecting and controlling jobs with access only to
036 * primitive and collection types. Suitable for a command-line client (e.g. that
037 * launches a new process for each operation), or a remote launcher like a JMX
038 * console.
039 * 
040 * @author Dave Syer
041 * @since 2.0
042 */
043public interface JobOperator {
044
045        /**
046         * List the {@link JobExecution JobExecutions} associated with a particular
047         * {@link JobInstance}, in reverse order of creation (and therefore usually
048         * of execution).
049         * 
050         * @param instanceId the id of a {@link JobInstance}
051         * @return the id values of all the {@link JobExecution JobExecutions}
052         * associated with this instance
053         * @throws NoSuchJobInstanceException if the {@link JobInstance} associated with the
054         *      {@code instanceId} cannot be found.
055         */
056        List<Long> getExecutions(long instanceId) throws NoSuchJobInstanceException;
057
058        /**
059         * List the {@link JobInstance JobInstances} for a given job name, in
060         * reverse order of creation (and therefore usually of first execution).
061         * 
062         * @param jobName the job name that all the instances have
063         * @param start the start index of the instances
064         * @param count the maximum number of values to return
065         * @return the id values of the {@link JobInstance JobInstances}
066         * @throws NoSuchJobException is thrown if no {@link JobInstance}s for the jobName exist.
067         */
068        List<Long> getJobInstances(String jobName, int start, int count) throws NoSuchJobException;
069
070        /**
071         * Get the id values of all the running {@link JobExecution JobExecutions}
072         * with the given job name.
073         * 
074         * @param jobName the name of the job to search under
075         * @return the id values of the running {@link JobExecution} instances
076         * @throws NoSuchJobException if there are no {@link JobExecution
077         * JobExecutions} with that job name
078         */
079        Set<Long> getRunningExecutions(String jobName) throws NoSuchJobException;
080
081        /**
082         * Get the {@link JobParameters} as an easily readable String.
083         * 
084         * @param executionId the id of an existing {@link JobExecution}
085         * @return the job parameters that were used to launch the associated
086         * instance
087         * @throws NoSuchJobExecutionException if the id was not associated with any
088         * {@link JobExecution}
089         */
090        String getParameters(long executionId) throws NoSuchJobExecutionException;
091
092        /**
093         * Start a new instance of a job with the parameters specified.
094         * 
095         * @param jobName the name of the {@link Job} to launch
096         * @param parameters the parameters to launch it with (comma or newline
097         * separated name=value pairs)
098         * @return the id of the {@link JobExecution} that is launched
099         * @throws NoSuchJobException if there is no {@link Job} with the specified
100         * name
101         * @throws JobInstanceAlreadyExistsException if a job instance with this
102         * name and parameters already exists
103         * @throws JobParametersInvalidException thrown if any of the job parameters are invalid.
104         */
105        Long start(String jobName, String parameters) throws NoSuchJobException, JobInstanceAlreadyExistsException, JobParametersInvalidException;
106
107        /**
108         * Restart a failed or stopped {@link JobExecution}. Fails with an exception
109         * if the id provided does not exist or corresponds to a {@link JobInstance}
110         * that in normal circumstances already completed successfully.
111         * 
112         * @param executionId the id of a failed or stopped {@link JobExecution}
113         * @return the id of the {@link JobExecution} that was started
114         * 
115         * @throws JobInstanceAlreadyCompleteException if the job was already
116         * successfully completed
117         * @throws NoSuchJobExecutionException if the id was not associated with any
118         * {@link JobExecution}
119         * @throws NoSuchJobException if the {@link JobExecution} was found, but its
120         * corresponding {@link Job} is no longer available for launching
121         * @throws JobRestartException if there is a non-specific error with the
122         * restart (e.g. corrupt or inconsistent restart data)
123         * @throws JobParametersInvalidException if the parameters are not valid for
124         * this job
125         */
126        Long restart(long executionId) throws JobInstanceAlreadyCompleteException, NoSuchJobExecutionException,
127                        NoSuchJobException, JobRestartException, JobParametersInvalidException;
128
129        /**
130         * Launch the next in a sequence of {@link JobInstance} determined by the
131         * {@link JobParametersIncrementer} attached to the specified job. If the
132         * previous instance is still in a failed state, this method should still
133         * create a new instance and run it with different parameters (as long as
134         * the {@link JobParametersIncrementer} is working).<br>
135         * <br>
136         * 
137         * The last three exception described below should be extremely unlikely,
138         * but cannot be ruled out entirely. It points to some other thread or
139         * process trying to use this method (or a similar one) at the same time.
140         * 
141         * @param jobName the name of the job to launch
142         * @return the {@link JobExecution} id of the execution created when the job
143         * is launched
144         *
145         * @throws NoSuchJobException if there is no such job definition available
146         * @throws JobParametersNotFoundException if the parameters cannot be found
147         * @throws JobParametersInvalidException thrown if some of the job parameters are invalid.
148         * @throws UnexpectedJobExecutionException if an unexpected condition arises
149         * @throws JobRestartException thrown if a job is restarted illegally.
150         * @throws JobExecutionAlreadyRunningException thrown if attempting to restart a job that is already executing.
151         * @throws JobInstanceAlreadyCompleteException thrown if attempting to restart a completed job.
152         */
153        Long startNextInstance(String jobName) throws NoSuchJobException, JobParametersNotFoundException,
154                        JobRestartException, JobExecutionAlreadyRunningException, JobInstanceAlreadyCompleteException, UnexpectedJobExecutionException, JobParametersInvalidException;
155
156        /**
157         * Send a stop signal to the {@link JobExecution} with the supplied id. The
158         * signal is successfully sent if this method returns true, but that doesn't
159         * mean that the job has stopped. The only way to be sure of that is to poll
160         * the job execution status.
161         * 
162         * @param executionId the id of a running {@link JobExecution}
163         * @return true if the message was successfully sent (does not guarantee
164         * that the job has stopped)
165         * @throws NoSuchJobExecutionException if there is no {@link JobExecution}
166         * with the id supplied
167         * @throws JobExecutionNotRunningException if the {@link JobExecution} is
168         * not running (so cannot be stopped)
169         */
170        boolean stop(long executionId) throws NoSuchJobExecutionException, JobExecutionNotRunningException;
171
172        /**
173         * Summarise the {@link JobExecution} with the supplied id, giving details
174         * of status, start and end times etc.
175         * 
176         * @param executionId the id of an existing {@link JobExecution}
177         * @return a String summarising the state of the job execution
178         * @throws NoSuchJobExecutionException if there is no {@link JobExecution}
179         * with the supplied id
180         */
181        String getSummary(long executionId) throws NoSuchJobExecutionException;
182
183        /**
184         * Summarise the {@link StepExecution} instances belonging to the
185         * {@link JobExecution} with the supplied id, giving details of status,
186         * start and end times etc.
187         * 
188         * @param executionId the id of an existing {@link JobExecution}
189         * @return a map of step execution id to String summarising the state of the
190         * execution
191         * @throws NoSuchJobExecutionException if there is no {@link JobExecution}
192         * with the supplied id
193         */
194        Map<Long, String> getStepExecutionSummaries(long executionId) throws NoSuchJobExecutionException;
195
196        /**
197         * List the available job names that can be launched with
198         * {@link #start(String, String)}.
199         * 
200         * @return a set of job names
201         */
202        Set<String> getJobNames();
203
204        /**
205         * Mark the {@link JobExecution} as ABANDONED. If a stop signal is ignored
206         * because the process died this is the best way to mark a job as finished
207         * with (as opposed to STOPPED). An abandoned job execution cannot be
208         * restarted by the framework.
209         *
210         * @param jobExecutionId the job execution id to abort
211         * @return the {@link JobExecution} that was aborted
212         * @throws NoSuchJobExecutionException thrown if there is no job execution for the jobExecutionId.
213         * @throws JobExecutionAlreadyRunningException if the job is running (it
214         * should be stopped first)
215         */
216        JobExecution abandon(long jobExecutionId) throws NoSuchJobExecutionException, JobExecutionAlreadyRunningException;
217}