org.springframework.batch.core.launch.JobOperator Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of spring-batch-core Show documentation
Show all versions of spring-batch-core Show documentation
Core domain for batch processing, expressing a domain of Jobs, Steps, Chunks, etc
/*
* Copyright 2006-2023 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.batch.core.launch;
import java.util.List;
import java.util.Map;
import java.util.Properties;
import java.util.Set;
import org.springframework.batch.core.Job;
import org.springframework.batch.core.JobExecution;
import org.springframework.batch.core.JobInstance;
import org.springframework.batch.core.JobParameters;
import org.springframework.batch.core.JobParametersIncrementer;
import org.springframework.batch.core.JobParametersInvalidException;
import org.springframework.batch.core.StepExecution;
import org.springframework.batch.core.UnexpectedJobExecutionException;
import org.springframework.batch.core.repository.JobExecutionAlreadyRunningException;
import org.springframework.batch.core.repository.JobInstanceAlreadyCompleteException;
import org.springframework.batch.core.repository.JobRestartException;
import org.springframework.lang.Nullable;
/**
* Low level interface for inspecting and controlling jobs with access only to primitive
* and collection types. Suitable for a command-line client (e.g. that launches a new
* process for each operation), or a remote launcher like a JMX console.
*
* @author Dave Syer
* @author Mahmoud Ben Hassine
* @since 2.0
*/
public interface JobOperator {
/**
* List the {@link JobExecution JobExecutions} associated with a particular
* {@link JobInstance}, in reverse order of creation (and therefore usually of
* execution).
* @param instanceId the id of a {@link JobInstance}
* @return the id values of all the {@link JobExecution JobExecutions} associated with
* this instance
* @throws NoSuchJobInstanceException if the {@link JobInstance} associated with the
* {@code instanceId} cannot be found.
*/
List getExecutions(long instanceId) throws NoSuchJobInstanceException;
/**
* List the {@link JobInstance JobInstances} for a given job name, in reverse order of
* creation (and therefore usually of first execution).
* @param jobName the job name that all the instances have
* @param start the start index of the instances
* @param count the maximum number of values to return
* @return the id values of the {@link JobInstance JobInstances}
* @throws NoSuchJobException is thrown if no {@link JobInstance}s for the jobName
* exist.
*/
List getJobInstances(String jobName, int start, int count) throws NoSuchJobException;
/**
* @param jobName {@link String} name of the job.
* @param jobParameters {@link JobParameters} parameters for the job instance.
* @return the {@link JobInstance} with the given name and parameters, or
* {@code null}.
*
* @since 5.0
*/
@Nullable
default JobInstance getJobInstance(String jobName, JobParameters jobParameters) {
throw new UnsupportedOperationException();
}
/**
* Get the id values of all the running {@link JobExecution JobExecutions} with the
* given job name.
* @param jobName the name of the job to search under
* @return the id values of the running {@link JobExecution} instances
* @throws NoSuchJobException if there are no {@link JobExecution JobExecutions} with
* that job name
*/
Set getRunningExecutions(String jobName) throws NoSuchJobException;
/**
* Get the {@link JobParameters} as a human readable String (new line separated
* key=value pairs).
* @param executionId the id of an existing {@link JobExecution}
* @return the job parameters that were used to launch the associated instance
* @throws NoSuchJobExecutionException if the id was not associated with any
* {@link JobExecution}
*/
String getParameters(long executionId) throws NoSuchJobExecutionException;
/**
* Start a new instance of a job with the parameters specified.
* @param jobName the name of the {@link Job} to launch
* @param parameters the parameters to launch it with (new line separated key=value
* pairs)
* @return the id of the {@link JobExecution} that is launched
* @throws NoSuchJobException if there is no {@link Job} with the specified name
* @throws JobInstanceAlreadyExistsException if a job instance with this name and
* parameters already exists
* @throws JobParametersInvalidException thrown if any of the job parameters are
* invalid.
* @deprecated use {@link #start(String, Properties)} instead. Will be removed in
* v5.2.
*/
@Deprecated(since = "5.0.1", forRemoval = true)
Long start(String jobName, String parameters)
throws NoSuchJobException, JobInstanceAlreadyExistsException, JobParametersInvalidException;
/**
* Start a new instance of a job with the parameters specified.
* @param jobName the name of the {@link Job} to launch
* @param parameters the parameters to launch it with
* @return the id of the {@link JobExecution} that is launched
* @throws NoSuchJobException if there is no {@link Job} with the specified name
* @throws JobInstanceAlreadyExistsException if a job instance with this name and
* parameters already exists
* @throws JobParametersInvalidException thrown if any of the job parameters are
* invalid.
*/
default Long start(String jobName, Properties parameters)
throws NoSuchJobException, JobInstanceAlreadyExistsException, JobParametersInvalidException {
throw new UnsupportedOperationException();
}
/**
* Restart a failed or stopped {@link JobExecution}. Fails with an exception if the id
* provided does not exist or corresponds to a {@link JobInstance} that in normal
* circumstances already completed successfully.
* @param executionId the id of a failed or stopped {@link JobExecution}
* @return the id of the {@link JobExecution} that was started
* @throws JobInstanceAlreadyCompleteException if the job was already successfully
* completed
* @throws NoSuchJobExecutionException if the id was not associated with any
* {@link JobExecution}
* @throws NoSuchJobException if the {@link JobExecution} was found, but its
* corresponding {@link Job} is no longer available for launching
* @throws JobRestartException if there is a non-specific error with the restart (e.g.
* corrupt or inconsistent restart data)
* @throws JobParametersInvalidException if the parameters are not valid for this job
*/
Long restart(long executionId) throws JobInstanceAlreadyCompleteException, NoSuchJobExecutionException,
NoSuchJobException, JobRestartException, JobParametersInvalidException;
/**
* Launch the next in a sequence of {@link JobInstance} determined by the
* {@link JobParametersIncrementer} attached to the specified job. If the previous
* instance is still in a failed state, this method should still create a new instance
* and run it with different parameters (as long as the
* {@link JobParametersIncrementer} is working).
*
*
* The last three exception described below should be extremely unlikely, but cannot
* be ruled out entirely. It points to some other thread or process trying to use this
* method (or a similar one) at the same time.
* @param jobName the name of the job to launch
* @return the {@link JobExecution} id of the execution created when the job is
* launched
* @throws NoSuchJobException if there is no such job definition available
* @throws JobParametersNotFoundException if the parameters cannot be found
* @throws JobParametersInvalidException thrown if some of the job parameters are
* invalid.
* @throws UnexpectedJobExecutionException if an unexpected condition arises
* @throws JobRestartException thrown if a job is restarted illegally.
* @throws JobExecutionAlreadyRunningException thrown if attempting to restart a job
* that is already executing.
* @throws JobInstanceAlreadyCompleteException thrown if attempting to restart a
* completed job.
*/
Long startNextInstance(String jobName) throws NoSuchJobException, JobParametersNotFoundException,
JobRestartException, JobExecutionAlreadyRunningException, JobInstanceAlreadyCompleteException,
UnexpectedJobExecutionException, JobParametersInvalidException;
/**
* Send a stop signal to the {@link JobExecution} with the supplied id. The signal is
* successfully sent if this method returns true, but that doesn't mean that the job
* has stopped. The only way to be sure of that is to poll the job execution status.
* @param executionId the id of a running {@link JobExecution}
* @return true if the message was successfully sent (does not guarantee that the job
* has stopped)
* @throws NoSuchJobExecutionException if there is no {@link JobExecution} with the id
* supplied
* @throws JobExecutionNotRunningException if the {@link JobExecution} is not running
* (so cannot be stopped)
*/
boolean stop(long executionId) throws NoSuchJobExecutionException, JobExecutionNotRunningException;
/**
* Summarise the {@link JobExecution} with the supplied id, giving details of status,
* start and end times etc.
* @param executionId the id of an existing {@link JobExecution}
* @return a String summarising the state of the job execution
* @throws NoSuchJobExecutionException if there is no {@link JobExecution} with the
* supplied id
*/
String getSummary(long executionId) throws NoSuchJobExecutionException;
/**
* Summarise the {@link StepExecution} instances belonging to the {@link JobExecution}
* with the supplied id, giving details of status, start and end times etc.
* @param executionId the id of an existing {@link JobExecution}
* @return a map of step execution id to String summarising the state of the execution
* @throws NoSuchJobExecutionException if there is no {@link JobExecution} with the
* supplied id
*/
Map getStepExecutionSummaries(long executionId) throws NoSuchJobExecutionException;
/**
* List the available job names that can be launched with
* {@link #start(String, Properties)}.
* @return a set of job names
*/
Set getJobNames();
/**
* Mark the {@link JobExecution} as ABANDONED. If a stop signal is ignored because the
* process died this is the best way to mark a job as finished with (as opposed to
* STOPPED). An abandoned job execution cannot be restarted by the framework.
* @param jobExecutionId the job execution id to abort
* @return the {@link JobExecution} that was aborted
* @throws NoSuchJobExecutionException thrown if there is no job execution for the
* jobExecutionId.
* @throws JobExecutionAlreadyRunningException if the job is running (it should be
* stopped first)
*/
JobExecution abandon(long jobExecutionId) throws NoSuchJobExecutionException, JobExecutionAlreadyRunningException;
}