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 */
016package org.springframework.batch.core.explore;
017
018import java.util.List;
019import java.util.Set;
020
021import org.springframework.batch.core.JobExecution;
022import org.springframework.batch.core.JobInstance;
023import org.springframework.batch.core.StepExecution;
024import org.springframework.batch.core.launch.NoSuchJobException;
025import org.springframework.batch.item.ExecutionContext;
026import org.springframework.lang.Nullable;
027
028/**
029 * Entry point for browsing executions of running or historical jobs and steps.
030 * Since the data may be re-hydrated from persistent storage, it may not contain
031 * volatile fields that would have been present when the execution was active.
032 *
033 * @author Dave Syer
034 * @author Michael Minella
035 * @author Will Schipp
036 * @author Mahmoud Ben Hassine
037 * @since 2.0
038 */
039public interface JobExplorer {
040
041        /**
042         * Fetch {@link JobInstance} values in descending order of creation (and
043         * therefore usually of first execution).
044         *
045         * @param jobName the name of the job to query
046         * @param start the start index of the instances to return
047         * @param count the maximum number of instances to return
048         * @return the {@link JobInstance} values up to a maximum of count values
049         */
050        List<JobInstance> getJobInstances(String jobName, int start, int count);
051
052        /**
053         * Retrieve a {@link JobExecution} by its id. The complete object graph for
054         * this execution should be returned (unless otherwise indicated) including
055         * the parent {@link JobInstance} and associated {@link ExecutionContext}
056         * and {@link StepExecution} instances (also including their execution
057         * contexts).
058         *
059         * @param executionId the job execution id
060         * @return the {@link JobExecution} with this id, or null if not found
061         */
062        @Nullable
063        JobExecution getJobExecution(@Nullable Long executionId);
064
065        /**
066         * Retrieve a {@link StepExecution} by its id and parent
067         * {@link JobExecution} id. The execution context for the step should be
068         * available in the result, and the parent job execution should have its
069         * primitive properties, but may not contain the job instance information.
070         *
071         * @param jobExecutionId the parent job execution id
072         * @param stepExecutionId the step execution id
073         * @return the {@link StepExecution} with this id, or null if not found
074         *
075         * @see #getJobExecution(Long)
076         */
077        @Nullable
078        StepExecution getStepExecution(@Nullable Long jobExecutionId, @Nullable Long stepExecutionId);
079
080        /**
081         * @param instanceId {@link Long} id for the jobInstance to obtain.
082         * @return the {@link JobInstance} with this id, or null
083         */
084        @Nullable
085        JobInstance getJobInstance(@Nullable Long instanceId);
086
087        /**
088         * Retrieve job executions by their job instance. The corresponding step
089         * executions may not be fully hydrated (e.g. their execution context may be
090         * missing), depending on the implementation. Use
091         * {@link #getStepExecution(Long, Long)} to hydrate them in that case.
092         *
093         * @param jobInstance the {@link JobInstance} to query
094         * @return the set of all executions for the specified {@link JobInstance}
095         */
096        List<JobExecution> getJobExecutions(JobInstance jobInstance);
097
098        /**
099         * Retrieve running job executions. The corresponding step executions may
100         * not be fully hydrated (e.g. their execution context may be missing),
101         * depending on the implementation. Use
102         * {@link #getStepExecution(Long, Long)} to hydrate them in that case.
103         *
104         * @param jobName the name of the job
105         * @return the set of running executions for jobs with the specified name
106         */
107        Set<JobExecution> findRunningJobExecutions(@Nullable String jobName);
108
109        /**
110         * Query the repository for all unique {@link JobInstance} names (sorted
111         * alphabetically).
112         *
113         * @return the set of job names that have been executed
114         */
115        List<String> getJobNames();
116        
117        /**
118         * Fetch {@link JobInstance} values in descending order of creation (and
119         * there for usually of first execution) with a 'like'/wildcard criteria.
120         * 
121         * @param jobName the name of the job to query for.
122         * @param start the start index of the instances to return.
123         * @param count the maximum number of instances to return.
124         * @return a list of {@link JobInstance} for the job name requested.
125         */
126        List<JobInstance> findJobInstancesByJobName(String jobName, int start, int count);
127
128        /**
129         * Query the repository for the number of unique {@link JobInstance}s
130         * associated with the supplied job name.
131         *
132         * @param jobName the name of the job to query for
133         * @return the number of {@link JobInstance}s that exist within the
134         * associated job repository
135         *
136         * @throws NoSuchJobException thrown when there is no {@link JobInstance}
137         * for the jobName specified.
138         */
139        int getJobInstanceCount(@Nullable String jobName) throws NoSuchJobException;
140
141}