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 org.springframework.batch.core.Job;
019import org.springframework.batch.core.JobExecution;
020import org.springframework.batch.core.JobParameters;
021import org.springframework.batch.core.JobParametersInvalidException;
022import org.springframework.batch.core.repository.JobExecutionAlreadyRunningException;
023import org.springframework.batch.core.repository.JobInstanceAlreadyCompleteException;
024import org.springframework.batch.core.repository.JobRestartException;
025
026/**
027 * Simple interface for controlling jobs, including possible ad-hoc executions,
028 * based on different runtime identifiers. It is extremely important to note
029 * that this interface makes absolutely no guarantees about whether or not calls
030 * to it are executed synchronously or asynchronously. The javadocs for specific
031 * implementations should be checked to ensure callers fully understand how the
032 * job will be run.
033 * 
034 * @author Lucas Ward
035 * @author Dave Syer
036 */
037
038public interface JobLauncher {
039
040        /**
041         * Start a job execution for the given {@link Job} and {@link JobParameters}
042         * . If a {@link JobExecution} was able to be created successfully, it will
043         * always be returned by this method, regardless of whether or not the
044         * execution was successful. If there is a past {@link JobExecution} which
045         * has paused, the same {@link JobExecution} is returned instead of a new
046         * one created. A exception will only be thrown if there is a failure to
047         * start the job. If the job encounters some error while processing, the
048         * JobExecution will be returned, and the status will need to be inspected.
049         *
050         * @param job the job to be executed.
051         * @param jobParameters the parameters passed to this execution of the job.
052         * @return the {@link JobExecution} if it returns synchronously. If the
053         * implementation is asynchronous, the status might well be unknown.
054         * 
055         * @throws JobExecutionAlreadyRunningException if the JobInstance identified
056         * by the properties already has an execution running.
057         * @throws IllegalArgumentException if the job or jobInstanceProperties are
058         * null.
059         * @throws JobRestartException if the job has been run before and
060         * circumstances that preclude a re-start.
061         * @throws JobInstanceAlreadyCompleteException if the job has been run
062         * before with the same parameters and completed successfully
063         * @throws JobParametersInvalidException if the parameters are not valid for
064         * this job
065         */
066        public JobExecution run(Job job, JobParameters jobParameters) throws JobExecutionAlreadyRunningException,
067                        JobRestartException, JobInstanceAlreadyCompleteException, JobParametersInvalidException;
068
069}