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}