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}