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}