Skip to content

Commit b9fc0e7

Browse files
fmbenhassinefmbenhassine
committed
Rearrange methods in JobExplorer/JobRepository APIs
1 parent 43ac1f1 commit b9fc0e7

File tree

2 files changed

+128
-92
lines changed

2 files changed

+128
-92
lines changed

‎spring-batch-core/src/main/java/org/springframework/batch/core/explore/JobExplorer.java

+73-49
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2006-2023 the original author or authors.
2+
* Copyright 2006-2025 the original author or authors.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -40,6 +40,25 @@
4040
*/
4141
public interface JobExplorer {
4242

43+
/*
44+
* ===================================================================================
45+
* Job operations
46+
* ===================================================================================
47+
*/
48+
49+
/**
50+
* Query the repository for all unique {@link JobInstance} names (sorted
51+
* alphabetically).
52+
* @return the list of job names that have been executed.
53+
*/
54+
List<String> getJobNames();
55+
56+
/*
57+
* ===================================================================================
58+
* Job instance operations
59+
* ===================================================================================
60+
*/
61+
4362
/**
4463
* Fetch {@link JobInstance} values in descending order of creation (and, therefore,
4564
* usually, of first execution).
@@ -50,6 +69,16 @@ public interface JobExplorer {
5069
*/
5170
List<JobInstance> getJobInstances(String jobName, int start, int count);
5271

72+
/**
73+
* Fetch {@link JobInstance} values in descending order of creation (and, therefore,
74+
* usually of first execution) with a 'like' or wildcard criteria.
75+
* @param jobName The name of the job for which to query.
76+
* @param start The start index of the instances to return.
77+
* @param count The maximum number of instances to return.
78+
* @return a list of {@link JobInstance} for the requested job name.
79+
*/
80+
List<JobInstance> findJobInstancesByJobName(String jobName, int start, int count);
81+
5382
/**
5483
* Find the last job instance, by ID, for the given job.
5584
* @param jobName The name of the job.
@@ -62,31 +91,6 @@ default JobInstance getLastJobInstance(String jobName) {
6291
throw new UnsupportedOperationException();
6392
}
6493

65-
/**
66-
* Retrieve a {@link JobExecution} by its ID. The complete object graph for this
67-
* execution should be returned (unless otherwise indicated), including the parent
68-
* {@link JobInstance} and associated {@link ExecutionContext} and
69-
* {@link StepExecution} instances (also including their execution contexts).
70-
* @param executionId The job execution ID.
71-
* @return the {@link JobExecution} that has this ID or {@code null} if not found.
72-
*/
73-
@Nullable
74-
JobExecution getJobExecution(@Nullable Long executionId);
75-
76-
/**
77-
* Retrieve a {@link StepExecution} by its ID and parent {@link JobExecution} ID. The
78-
* execution context for the step should be available in the result, and the parent
79-
* job execution should have its primitive properties, but it may not contain the job
80-
* instance information.
81-
* @param jobExecutionId The parent job execution ID.
82-
* @param stepExecutionId The step execution ID.
83-
* @return the {@link StepExecution} that has this ID or {@code null} if not found.
84-
*
85-
* @see #getJobExecution(Long)
86-
*/
87-
@Nullable
88-
StepExecution getStepExecution(@Nullable Long jobExecutionId, @Nullable Long stepExecutionId);
89-
9094
/**
9195
* @param instanceId {@link Long} The ID for the {@link JobInstance} to obtain.
9296
* @return the {@code JobInstance} that has this ID, or {@code null} if not found.
@@ -107,6 +111,34 @@ default JobInstance getJobInstance(String jobName, JobParameters jobParameters)
107111
throw new UnsupportedOperationException();
108112
}
109113

114+
/**
115+
* Query the repository for the number of unique {@link JobInstance} objects
116+
* associated with the supplied job name.
117+
* @param jobName The name of the job for which to query.
118+
* @return the number of {@link JobInstance}s that exist within the associated job
119+
* repository.
120+
* @throws NoSuchJobException thrown when there is no {@link JobInstance} for the
121+
* jobName specified.
122+
*/
123+
long getJobInstanceCount(@Nullable String jobName) throws NoSuchJobException;
124+
125+
/*
126+
* ===================================================================================
127+
* Job execution operations
128+
* ===================================================================================
129+
*/
130+
131+
/**
132+
* Retrieve a {@link JobExecution} by its ID. The complete object graph for this
133+
* execution should be returned (unless otherwise indicated), including the parent
134+
* {@link JobInstance} and associated {@link ExecutionContext} and
135+
* {@link StepExecution} instances (also including their execution contexts).
136+
* @param executionId The job execution ID.
137+
* @return the {@link JobExecution} that has this ID or {@code null} if not found.
138+
*/
139+
@Nullable
140+
JobExecution getJobExecution(@Nullable Long executionId);
141+
110142
/**
111143
* Retrieve job executions by their job instance. The corresponding step executions
112144
* may not be fully hydrated (for example, their execution context may be missing),
@@ -142,32 +174,24 @@ default JobExecution getLastJobExecution(JobInstance jobInstance) {
142174
*/
143175
Set<JobExecution> findRunningJobExecutions(@Nullable String jobName);
144176

145-
/**
146-
* Query the repository for all unique {@link JobInstance} names (sorted
147-
* alphabetically).
148-
* @return the list of job names that have been executed.
149-
*/
150-
List<String> getJobNames();
151-
152-
/**
153-
* Fetch {@link JobInstance} values in descending order of creation (and, therefore,
154-
* usually of first execution) with a 'like' or wildcard criteria.
155-
* @param jobName The name of the job for which to query.
156-
* @param start The start index of the instances to return.
157-
* @param count The maximum number of instances to return.
158-
* @return a list of {@link JobInstance} for the requested job name.
177+
/*
178+
* ===================================================================================
179+
* Step execution operations
180+
* ===================================================================================
159181
*/
160-
List<JobInstance> findJobInstancesByJobName(String jobName, int start, int count);
161182

162183
/**
163-
* Query the repository for the number of unique {@link JobInstance} objects
164-
* associated with the supplied job name.
165-
* @param jobName The name of the job for which to query.
166-
* @return the number of {@link JobInstance}s that exist within the associated job
167-
* repository.
168-
* @throws NoSuchJobException thrown when there is no {@link JobInstance} for the
169-
* jobName specified.
184+
* Retrieve a {@link StepExecution} by its ID and parent {@link JobExecution} ID. The
185+
* execution context for the step should be available in the result, and the parent
186+
* job execution should have its primitive properties, but it may not contain the job
187+
* instance information.
188+
* @param jobExecutionId The parent job execution ID.
189+
* @param stepExecutionId The step execution ID.
190+
* @return the {@link StepExecution} that has this ID or {@code null} if not found.
191+
*
192+
* @see #getJobExecution(Long)
170193
*/
171-
long getJobInstanceCount(@Nullable String jobName) throws NoSuchJobException;
194+
@Nullable
195+
StepExecution getStepExecution(@Nullable Long jobExecutionId, @Nullable Long stepExecutionId);
172196

173197
}

‎spring-batch-core/src/main/java/org/springframework/batch/core/repository/JobRepository.java

+55-43
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2006-2023 the original author or authors.
2+
* Copyright 2006-2025 the original author or authors.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -50,6 +50,12 @@
5050
*/
5151
public interface JobRepository {
5252

53+
/*
54+
* ===================================================================================
55+
* Read only operations
56+
* ===================================================================================
57+
*/
58+
5359
/**
5460
* Retrieve the names of all job instances sorted alphabetically - i.e. jobs that have
5561
* ever been executed.
@@ -74,6 +80,28 @@ default List<JobInstance> findJobInstancesByName(String jobName, int start, int
7480
return Collections.emptyList();
7581
}
7682

83+
/**
84+
* Check if an instance of this job already exists with the parameters provided.
85+
* @param jobName the name of the job
86+
* @param jobParameters the parameters to match
87+
* @return true if a {@link JobInstance} already exists for this job name and job
88+
* parameters
89+
*/
90+
boolean isJobInstanceExists(String jobName, JobParameters jobParameters);
91+
92+
/**
93+
* @param jobName {@link String} name of the job.
94+
* @param jobParameters {@link JobParameters} parameters for the job instance.
95+
* @return the {@link JobInstance} with the given name and parameters, or
96+
* {@code null}.
97+
*
98+
* @since 5.0
99+
*/
100+
@Nullable
101+
default JobInstance getJobInstance(String jobName, JobParameters jobParameters) {
102+
throw new UnsupportedOperationException();
103+
}
104+
77105
/**
78106
* Return all {@link JobExecution}s for given {@link JobInstance}, sorted backwards by
79107
* creation order (so the first element is the most recent).
@@ -86,13 +114,33 @@ default List<JobExecution> findJobExecutions(JobInstance jobInstance) {
86114
}
87115

88116
/**
89-
* Check if an instance of this job already exists with the parameters provided.
90-
* @param jobName the name of the job
91-
* @param jobParameters the parameters to match
92-
* @return true if a {@link JobInstance} already exists for this job name and job
93-
* parameters
117+
* @param jobName the name of the job that might have run
118+
* @param jobParameters parameters identifying the {@link JobInstance}
119+
* @return the last execution of job if exists, null otherwise
120+
*/
121+
@Nullable
122+
JobExecution getLastJobExecution(String jobName, JobParameters jobParameters);
123+
124+
/**
125+
* @param jobInstance {@link JobInstance} instance containing the step executions.
126+
* @param stepName the name of the step execution that might have run.
127+
* @return the last execution of step for the given job instance.
128+
*/
129+
@Nullable
130+
StepExecution getLastStepExecution(JobInstance jobInstance, String stepName);
131+
132+
/**
133+
* @param jobInstance {@link JobInstance} instance containing the step executions.
134+
* @param stepName the name of the step execution that might have run.
135+
* @return the execution count of the step within the given job instance.
136+
*/
137+
long getStepExecutionCount(JobInstance jobInstance, String stepName);
138+
139+
/*
140+
* ===================================================================================
141+
* Write/Update operations
142+
* ===================================================================================
94143
*/
95-
boolean isJobInstanceExists(String jobName, JobParameters jobParameters);
96144

97145
/**
98146
* Create a new {@link JobInstance} with the name and job parameters provided.
@@ -187,42 +235,6 @@ JobExecution createJobExecution(String jobName, JobParameters jobParameters)
187235
*/
188236
void updateExecutionContext(JobExecution jobExecution);
189237

190-
/**
191-
* @param jobName {@link String} name of the job.
192-
* @param jobParameters {@link JobParameters} parameters for the job instance.
193-
* @return the {@link JobInstance} with the given name and parameters, or
194-
* {@code null}.
195-
*
196-
* @since 5.0
197-
*/
198-
@Nullable
199-
default JobInstance getJobInstance(String jobName, JobParameters jobParameters) {
200-
throw new UnsupportedOperationException();
201-
}
202-
203-
/**
204-
* @param jobInstance {@link JobInstance} instance containing the step executions.
205-
* @param stepName the name of the step execution that might have run.
206-
* @return the last execution of step for the given job instance.
207-
*/
208-
@Nullable
209-
StepExecution getLastStepExecution(JobInstance jobInstance, String stepName);
210-
211-
/**
212-
* @param jobInstance {@link JobInstance} instance containing the step executions.
213-
* @param stepName the name of the step execution that might have run.
214-
* @return the execution count of the step within the given job instance.
215-
*/
216-
long getStepExecutionCount(JobInstance jobInstance, String stepName);
217-
218-
/**
219-
* @param jobName the name of the job that might have run
220-
* @param jobParameters parameters identifying the {@link JobInstance}
221-
* @return the last execution of job if exists, null otherwise
222-
*/
223-
@Nullable
224-
JobExecution getLastJobExecution(String jobName, JobParameters jobParameters);
225-
226238
/**
227239
* Delete the step execution along with its execution context.
228240
* @param stepExecution the step execution to delete

0 commit comments

Comments
 (0)