diff --git a/spring-batch-core/src/main/java/org/springframework/batch/core/explore/JobExplorer.java b/spring-batch-core/src/main/java/org/springframework/batch/core/explore/JobExplorer.java index 85c69655f..f10a5fa30 100644 --- a/spring-batch-core/src/main/java/org/springframework/batch/core/explore/JobExplorer.java +++ b/spring-batch-core/src/main/java/org/springframework/batch/core/explore/JobExplorer.java @@ -1,5 +1,5 @@ /* - * Copyright 2006-2023 the original author or authors. + * Copyright 2006-2025 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -40,6 +40,25 @@ import org.springframework.lang.Nullable; */ public interface JobExplorer { + /* + * =================================================================================== + * Job operations + * =================================================================================== + */ + + /** + * Query the repository for all unique {@link JobInstance} names (sorted + * alphabetically). + * @return the list of job names that have been executed. + */ + List getJobNames(); + + /* + * =================================================================================== + * Job instance operations + * =================================================================================== + */ + /** * Fetch {@link JobInstance} values in descending order of creation (and, therefore, * usually, of first execution). @@ -50,6 +69,16 @@ public interface JobExplorer { */ List getJobInstances(String jobName, int start, int count); + /** + * Fetch {@link JobInstance} values in descending order of creation (and, therefore, + * usually of first execution) with a 'like' or wildcard criteria. + * @param jobName The name of the job for which to query. + * @param start The start index of the instances to return. + * @param count The maximum number of instances to return. + * @return a list of {@link JobInstance} for the requested job name. + */ + List findJobInstancesByJobName(String jobName, int start, int count); + /** * Find the last job instance, by ID, for the given job. * @param jobName The name of the job. @@ -62,31 +91,6 @@ public interface JobExplorer { throw new UnsupportedOperationException(); } - /** - * Retrieve a {@link JobExecution} by its ID. The complete object graph for this - * execution should be returned (unless otherwise indicated), including the parent - * {@link JobInstance} and associated {@link ExecutionContext} and - * {@link StepExecution} instances (also including their execution contexts). - * @param executionId The job execution ID. - * @return the {@link JobExecution} that has this ID or {@code null} if not found. - */ - @Nullable - JobExecution getJobExecution(@Nullable Long executionId); - - /** - * Retrieve a {@link StepExecution} by its ID and parent {@link JobExecution} ID. The - * execution context for the step should be available in the result, and the parent - * job execution should have its primitive properties, but it may not contain the job - * instance information. - * @param jobExecutionId The parent job execution ID. - * @param stepExecutionId The step execution ID. - * @return the {@link StepExecution} that has this ID or {@code null} if not found. - * - * @see #getJobExecution(Long) - */ - @Nullable - StepExecution getStepExecution(@Nullable Long jobExecutionId, @Nullable Long stepExecutionId); - /** * @param instanceId {@link Long} The ID for the {@link JobInstance} to obtain. * @return the {@code JobInstance} that has this ID, or {@code null} if not found. @@ -107,6 +111,34 @@ public interface JobExplorer { throw new UnsupportedOperationException(); } + /** + * Query the repository for the number of unique {@link JobInstance} objects + * associated with the supplied job name. + * @param jobName The name of the job for which to query. + * @return the number of {@link JobInstance}s that exist within the associated job + * repository. + * @throws NoSuchJobException thrown when there is no {@link JobInstance} for the + * jobName specified. + */ + long getJobInstanceCount(@Nullable String jobName) throws NoSuchJobException; + + /* + * =================================================================================== + * Job execution operations + * =================================================================================== + */ + + /** + * Retrieve a {@link JobExecution} by its ID. The complete object graph for this + * execution should be returned (unless otherwise indicated), including the parent + * {@link JobInstance} and associated {@link ExecutionContext} and + * {@link StepExecution} instances (also including their execution contexts). + * @param executionId The job execution ID. + * @return the {@link JobExecution} that has this ID or {@code null} if not found. + */ + @Nullable + JobExecution getJobExecution(@Nullable Long executionId); + /** * Retrieve job executions by their job instance. The corresponding step executions * may not be fully hydrated (for example, their execution context may be missing), @@ -142,32 +174,24 @@ public interface JobExplorer { */ Set findRunningJobExecutions(@Nullable String jobName); - /** - * Query the repository for all unique {@link JobInstance} names (sorted - * alphabetically). - * @return the list of job names that have been executed. + /* + * =================================================================================== + * Step execution operations + * =================================================================================== */ - List getJobNames(); /** - * Fetch {@link JobInstance} values in descending order of creation (and, therefore, - * usually of first execution) with a 'like' or wildcard criteria. - * @param jobName The name of the job for which to query. - * @param start The start index of the instances to return. - * @param count The maximum number of instances to return. - * @return a list of {@link JobInstance} for the requested job name. + * Retrieve a {@link StepExecution} by its ID and parent {@link JobExecution} ID. The + * execution context for the step should be available in the result, and the parent + * job execution should have its primitive properties, but it may not contain the job + * instance information. + * @param jobExecutionId The parent job execution ID. + * @param stepExecutionId The step execution ID. + * @return the {@link StepExecution} that has this ID or {@code null} if not found. + * + * @see #getJobExecution(Long) */ - List findJobInstancesByJobName(String jobName, int start, int count); - - /** - * Query the repository for the number of unique {@link JobInstance} objects - * associated with the supplied job name. - * @param jobName The name of the job for which to query. - * @return the number of {@link JobInstance}s that exist within the associated job - * repository. - * @throws NoSuchJobException thrown when there is no {@link JobInstance} for the - * jobName specified. - */ - long getJobInstanceCount(@Nullable String jobName) throws NoSuchJobException; + @Nullable + StepExecution getStepExecution(@Nullable Long jobExecutionId, @Nullable Long stepExecutionId); } diff --git a/spring-batch-core/src/main/java/org/springframework/batch/core/repository/JobRepository.java b/spring-batch-core/src/main/java/org/springframework/batch/core/repository/JobRepository.java index b8db9253b..b4c7d3da8 100644 --- a/spring-batch-core/src/main/java/org/springframework/batch/core/repository/JobRepository.java +++ b/spring-batch-core/src/main/java/org/springframework/batch/core/repository/JobRepository.java @@ -1,5 +1,5 @@ /* - * Copyright 2006-2023 the original author or authors. + * Copyright 2006-2025 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -50,6 +50,12 @@ import java.util.List; */ public interface JobRepository { + /* + * =================================================================================== + * Read only operations + * =================================================================================== + */ + /** * Retrieve the names of all job instances sorted alphabetically - i.e. jobs that have * ever been executed. @@ -74,6 +80,28 @@ public interface JobRepository { return Collections.emptyList(); } + /** + * Check if an instance of this job already exists with the parameters provided. + * @param jobName the name of the job + * @param jobParameters the parameters to match + * @return true if a {@link JobInstance} already exists for this job name and job + * parameters + */ + boolean isJobInstanceExists(String jobName, JobParameters jobParameters); + + /** + * @param jobName {@link String} name of the job. + * @param jobParameters {@link JobParameters} parameters for the job instance. + * @return the {@link JobInstance} with the given name and parameters, or + * {@code null}. + * + * @since 5.0 + */ + @Nullable + default JobInstance getJobInstance(String jobName, JobParameters jobParameters) { + throw new UnsupportedOperationException(); + } + /** * Return all {@link JobExecution}s for given {@link JobInstance}, sorted backwards by * creation order (so the first element is the most recent). @@ -86,13 +114,33 @@ public interface JobRepository { } /** - * Check if an instance of this job already exists with the parameters provided. - * @param jobName the name of the job - * @param jobParameters the parameters to match - * @return true if a {@link JobInstance} already exists for this job name and job - * parameters + * @param jobName the name of the job that might have run + * @param jobParameters parameters identifying the {@link JobInstance} + * @return the last execution of job if exists, null otherwise + */ + @Nullable + JobExecution getLastJobExecution(String jobName, JobParameters jobParameters); + + /** + * @param jobInstance {@link JobInstance} instance containing the step executions. + * @param stepName the name of the step execution that might have run. + * @return the last execution of step for the given job instance. + */ + @Nullable + StepExecution getLastStepExecution(JobInstance jobInstance, String stepName); + + /** + * @param jobInstance {@link JobInstance} instance containing the step executions. + * @param stepName the name of the step execution that might have run. + * @return the execution count of the step within the given job instance. + */ + long getStepExecutionCount(JobInstance jobInstance, String stepName); + + /* + * =================================================================================== + * Write/Update operations + * =================================================================================== */ - boolean isJobInstanceExists(String jobName, JobParameters jobParameters); /** * Create a new {@link JobInstance} with the name and job parameters provided. @@ -187,42 +235,6 @@ public interface JobRepository { */ void updateExecutionContext(JobExecution jobExecution); - /** - * @param jobName {@link String} name of the job. - * @param jobParameters {@link JobParameters} parameters for the job instance. - * @return the {@link JobInstance} with the given name and parameters, or - * {@code null}. - * - * @since 5.0 - */ - @Nullable - default JobInstance getJobInstance(String jobName, JobParameters jobParameters) { - throw new UnsupportedOperationException(); - } - - /** - * @param jobInstance {@link JobInstance} instance containing the step executions. - * @param stepName the name of the step execution that might have run. - * @return the last execution of step for the given job instance. - */ - @Nullable - StepExecution getLastStepExecution(JobInstance jobInstance, String stepName); - - /** - * @param jobInstance {@link JobInstance} instance containing the step executions. - * @param stepName the name of the step execution that might have run. - * @return the execution count of the step within the given job instance. - */ - long getStepExecutionCount(JobInstance jobInstance, String stepName); - - /** - * @param jobName the name of the job that might have run - * @param jobParameters parameters identifying the {@link JobInstance} - * @return the last execution of job if exists, null otherwise - */ - @Nullable - JobExecution getLastJobExecution(String jobName, JobParameters jobParameters); - /** * Delete the step execution along with its execution context. * @param stepExecution the step execution to delete