001/* 002 * Copyright 2006-2018 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 */ 016 017package org.springframework.batch.core.repository.dao; 018 019import java.util.List; 020 021import org.springframework.batch.core.JobExecution; 022import org.springframework.batch.core.JobInstance; 023import org.springframework.batch.core.JobParameters; 024import org.springframework.batch.core.launch.NoSuchJobException; 025import org.springframework.lang.Nullable; 026 027/** 028 * Data Access Object for job instances. 029 * 030 * @author Lucas Ward 031 * @author Robert Kasanicky 032 * @author Michael Minella 033 * @author Mahmoud Ben Hassine 034 * 035 */ 036public interface JobInstanceDao { 037 038 /** 039 * Create a JobInstance with given name and parameters. 040 * 041 * PreConditions: JobInstance for given name and parameters must not already 042 * exist 043 * 044 * PostConditions: A valid job instance will be returned which has been 045 * persisted and contains an unique Id. 046 * 047 * @param jobName {@link String} containing the name of the job. 048 * @param jobParameters {@link JobParameters} containing the parameters for 049 * the JobInstance. 050 * @return JobInstance {@link JobInstance} instance that was created. 051 */ 052 JobInstance createJobInstance(String jobName, JobParameters jobParameters); 053 054 /** 055 * Find the job instance that matches the given name and parameters. If no 056 * matching job instances are found, then returns null. 057 * 058 * @param jobName the name of the job 059 * @param jobParameters the parameters with which the job was executed 060 * @return {@link JobInstance} object matching the job name and 061 * {@link JobParameters} or {@code null} 062 */ 063 @Nullable 064 JobInstance getJobInstance(String jobName, JobParameters jobParameters); 065 066 /** 067 * Fetch the job instance with the provided identifier. 068 * 069 * @param instanceId the job identifier 070 * @return the job instance with this identifier or {@code null} if it doesn't exist 071 */ 072 @Nullable 073 JobInstance getJobInstance(@Nullable Long instanceId); 074 075 /** 076 * Fetch the JobInstance for the provided JobExecution. 077 * 078 * @param jobExecution the JobExecution 079 * @return the JobInstance for the provided execution or {@code null} if it doesn't exist. 080 */ 081 @Nullable 082 JobInstance getJobInstance(JobExecution jobExecution); 083 084 /** 085 * Fetch the last job instances with the provided name, sorted backwards by 086 * primary key. 087 * 088 * if using the JdbcJobInstance, you can provide the jobName with a wildcard 089 * (e.g. *Job) to return 'like' job names. (e.g. *Job will return 'someJob' 090 * and 'otherJob') 091 * 092 * @param jobName the job name 093 * @param start the start index of the instances to return 094 * @param count the maximum number of objects to return 095 * @return the job instances with this name or empty if none 096 */ 097 List<JobInstance> getJobInstances(String jobName, int start, int count); 098 099 /** 100 * Retrieve the names of all job instances sorted alphabetically - i.e. jobs 101 * that have ever been executed. 102 * 103 * @return the names of all job instances 104 */ 105 List<String> getJobNames(); 106 107 /** 108 * Fetch the last job instances with the provided name, sorted backwards by 109 * primary key, using a 'like' criteria 110 * 111 * @param jobName {@link String} containing the name of the job. 112 * @param start int containing the offset of where list of job instances 113 * results should begin. 114 * @param count int containing the number of job instances to return. 115 * @return a list of {@link JobInstance} for the job name requested. 116 */ 117 List<JobInstance> findJobInstancesByName(String jobName, int start, int count); 118 119 120 /** 121 * Query the repository for the number of unique {@link JobInstance}s 122 * associated with the supplied job name. 123 * 124 * @param jobName the name of the job to query for 125 * @return the number of {@link JobInstance}s that exist within the 126 * associated job repository 127 * 128 * @throws NoSuchJobException thrown if no Job has the jobName specified. 129 */ 130 int getJobInstanceCount(@Nullable String jobName) throws NoSuchJobException; 131 132}