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  
17  package org.springframework.batch.core.repository;
18  
19  import org.springframework.batch.core.Job;
20  import org.springframework.batch.core.JobExecution;
21  import org.springframework.batch.core.JobInstance;
22  import org.springframework.batch.core.JobParameters;
23  import org.springframework.batch.core.Step;
24  import org.springframework.batch.core.StepExecution;
25  import org.springframework.batch.core.repository.dao.JobExecutionDao;
26  import org.springframework.batch.core.repository.dao.JobInstanceDao;
27  import org.springframework.batch.item.ExecutionContext;
28  import org.springframework.transaction.annotation.Isolation;
29  
30  /**
31   * <p>
32   * Repository responsible for persistence of batch meta-data entities.
33   * </p>
34   * 
35   * @see JobInstance
36   * @see JobExecution
37   * @see StepExecution
38   * 
39   * @author Lucas Ward
40   * @author Dave Syer
41   * @author Robert Kasanicky
42   */
43  public interface JobRepository {
44  
45  	/**
46  	 * Check if an instance of this job already exists with the parameters
47  	 * provided.
48  	 * 
49  	 * @param jobName the name of the job
50  	 * @param jobParameters the parameters to match
51  	 * @return true if a {@link JobInstance} already exists for this job name
52  	 * and job parameters
53  	 */
54  	boolean isJobInstanceExists(String jobName, JobParameters jobParameters);
55  
56  	/**
57  	 * <p>
58  	 * Create a {@link JobExecution} for a given {@link Job} and
59  	 * {@link JobParameters}. If matching {@link JobInstance} already exists,
60  	 * the job must be restartable and it's last JobExecution must *not* be
61  	 * completed. If matching {@link JobInstance} does not exist yet it will be
62  	 * created.
63  	 * </p>
64  	 * 
65  	 * <p>
66  	 * If this method is run in a transaction (as it normally would be) with
67  	 * isolation level at {@link Isolation#REPEATABLE_READ} or better, then this
68  	 * method should block if another transaction is already executing it (for
69  	 * the same {@link JobParameters} and job name). The first transaction to
70  	 * complete in this scenario obtains a valid {@link JobExecution}, and
71  	 * others throw {@link JobExecutionAlreadyRunningException} (or timeout).
72  	 * There are no such guarantees if the {@link JobInstanceDao} and
73  	 * {@link JobExecutionDao} do not respect the transaction isolation levels
74  	 * (e.g. if using a non-relational data-store, or if the platform does not
75  	 * support the higher isolation levels).
76  	 * </p>
77  	 * 
78  	 * @param jobName the name of the job that is to be executed </p>
79  	 * 
80  	 * @param jobParameters the runtime parameters for the job
81  	 * 
82  	 * @return a valid {@link JobExecution} for the arguments provided
83  	 * @throws JobExecutionAlreadyRunningException if there is a
84  	 * {@link JobExecution} already running for the job instance with the
85  	 * provided job and parameters.
86  	 * @throws JobRestartException if one or more existing {@link JobInstance}s
87  	 * is found with the same parameters and {@link Job#isRestartable()} is
88  	 * false.
89  	 * @throws JobInstanceAlreadyCompleteException if a {@link JobInstance} is
90  	 * found and was already completed successfully.
91  	 * 
92  	 */
93  	JobExecution createJobExecution(String jobName, JobParameters jobParameters)
94  			throws JobExecutionAlreadyRunningException, JobRestartException, JobInstanceAlreadyCompleteException;
95  
96  	/**
97  	 * Update the {@link JobExecution} (but not its {@link ExecutionContext}).
98  	 * 
99  	 * Preconditions: {@link JobExecution} must contain a valid
100 	 * {@link JobInstance} and be saved (have an id assigned).
101 	 * 
102 	 * @param jobExecution
103 	 */
104 	void update(JobExecution jobExecution);
105 
106 	/**
107 	 * Save the {@link StepExecution} and its {@link ExecutionContext}. ID will
108 	 * be assigned - it is not permitted that an ID be assigned before calling
109 	 * this method. Instead, it should be left blank, to be assigned by a
110 	 * {@link JobRepository}.
111 	 * 
112 	 * Preconditions: {@link StepExecution} must have a valid {@link Step}.
113 	 * 
114 	 * @param stepExecution
115 	 */
116 	void add(StepExecution stepExecution);
117 
118 	/**
119 	 * Update the {@link StepExecution} (but not its {@link ExecutionContext}).
120 	 * 
121 	 * Preconditions: {@link StepExecution} must be saved (have an id assigned).
122 	 * 
123 	 * @param stepExecution
124 	 */
125 	void update(StepExecution stepExecution);
126 
127 	/**
128 	 * Persist the updated {@link ExecutionContext}s of the given
129 	 * {@link StepExecution}.
130 	 * 
131 	 * @param stepExecution
132 	 */
133 	void updateExecutionContext(StepExecution stepExecution);
134 
135 	/**
136 	 * Persist the updated {@link ExecutionContext} of the given
137 	 * {@link JobExecution}.
138 	 * @param jobExecution
139 	 */
140 	void updateExecutionContext(JobExecution jobExecution);
141 
142 	/**
143 	 * @param stepName the name of the step execution that might have run.
144 	 * @return the last execution of step for the given job instance.
145 	 */
146 	StepExecution getLastStepExecution(JobInstance jobInstance, String stepName);
147 
148 	/**
149 	 * @param stepName the name of the step execution that might have run.
150 	 * @return the execution count of the step within the given job instance.
151 	 */
152 	int getStepExecutionCount(JobInstance jobInstance, String stepName);
153 
154 	/**
155 	 * @param jobName the name of the job that might have run
156 	 * @param jobParameters parameters identifying the {@link JobInstance}
157 	 * @return the last execution of job if exists, null otherwise
158 	 */
159 	JobExecution getLastJobExecution(String jobName, JobParameters jobParameters);
160 
161 }