Editing pass

for grammar, spelling, consistency and (most importantly) clarity.

Author: Jay Bryant

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2019 the original author or authors.
+ * Copyright 2006-2022 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.
@@ -26,8 +26,8 @@
 import org.springframework.lang.Nullable;
 
 /**
- * Entry point for browsing executions of running or historical jobs and steps. Since the
- * data may be re-hydrated from persistent storage, it may not contain volatile fields
+ * Entry point for browsing the executions of running or historical jobs and steps. Since
+ * the data may be re-hydrated from persistent storage, it cannot contain volatile fields
  * that would have been present when the execution was active.
  *
  * @author Dave Syer
@@ -39,19 +39,19 @@
 public interface JobExplorer {
 
 	/**
-	 * Fetch {@link JobInstance} values in descending order of creation (and therefore
-	 * usually of first execution).
-	 * @param jobName the name of the job to query
-	 * @param start the start index of the instances to return
-	 * @param count the maximum number of instances to return
-	 * @return the {@link JobInstance} values up to a maximum of count values
+	 * Fetch {@link JobInstance} values in descending order of creation (and, therefore,
+	 * usually, of first execution).
+	 * @param jobName The name of the job to query.
+	 * @param start The start index of the instances to return.
+	 * @param count The maximum number of instances to return.
+	 * @return the {@link JobInstance} values up to a maximum of count values.
 	 */
 	List<JobInstance> getJobInstances(String jobName, int start, int count);
 
 	/**
-	 * Find the last job instance by Id for the given job.
-	 * @param jobName name of the job
-	 * @return the last job instance by Id if any or null otherwise
+	 * Find the last job instance, by ID, for the given job.
+	 * @param jobName The name of the job.
+	 * @return the last job instance by Id if any or {@code null} otherwise.
 	 *
 	 * @since 4.2
 	 */
@@ -61,52 +61,53 @@ default JobInstance getLastJobInstance(String jobName) {
 	}
 
 	/**
-	 * Retrieve a {@link JobExecution} by its id. The complete object graph for this
-	 * execution should be returned (unless otherwise indicated) including the parent
+	 * 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} with this id, or null if not found
+	 * @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
+	 * 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 may not contain the job
+	 * 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} with this id, or null if not found
+	 * @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} id for the jobInstance to obtain.
-	 * @return the {@link JobInstance} with this id, or null
+	 * @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.
 	 */
 	@Nullable
 	JobInstance getJobInstance(@Nullable Long instanceId);
 
 	/**
 	 * Retrieve job executions by their job instance. The corresponding step executions
-	 * may not be fully hydrated (e.g. their execution context may be missing), depending
-	 * on the implementation. Use {@link #getStepExecution(Long, Long)} to hydrate them in
-	 * that case.
-	 * @param jobInstance the {@link JobInstance} to query
-	 * @return the set of all executions for the specified {@link JobInstance}
+	 * may not be fully hydrated (for example, their execution context may be missing),
+	 * depending on the implementation. In that case, use
+	 * {@link #getStepExecution(Long, Long)} to hydrate them.
+	 * @param jobInstance The {@link JobInstance} to query.
+	 * @return the set of all executions for the specified {@link JobInstance}.
 	 */
 	List<JobExecution> getJobExecutions(JobInstance jobInstance);
 
 	/**
 	 * Find the last {@link JobExecution} that has been created for a given
 	 * {@link JobInstance}.
-	 * @param jobInstance the {@link JobInstance}
-	 * @return the last {@link JobExecution} that has been created for this instance or
+	 * @param jobInstance The {@code JobInstance} for which to find the last
+	 * {@code JobExecution}.
+	 * @return the last {@code JobExecution} that has been created for this instance or
 	 * {@code null} if no job execution is found for the given job instance.
 	 *
 	 * @since 4.2
@@ -118,39 +119,39 @@ default JobExecution getLastJobExecution(JobInstance jobInstance) {
 
 	/**
 	 * Retrieve running job executions. The corresponding step executions may not be fully
-	 * hydrated (e.g. their execution context may be missing), depending on the
-	 * implementation. Use {@link #getStepExecution(Long, Long)} to hydrate them in that
-	 * case.
-	 * @param jobName the name of the job
-	 * @return the set of running executions for jobs with the specified name
+	 * hydrated (for example, their execution context may be missing), depending on the
+	 * implementation. In that case, use {@link #getStepExecution(Long, Long)} to hydrate
+	 * them.
+	 * @param jobName The name of the job.
+	 * @return the set of running executions for jobs with the specified name.
 	 */
 	Set<JobExecution> findRunningJobExecutions(@Nullable String jobName);
 
 	/**
 	 * Query the repository for all unique {@link JobInstance} names (sorted
 	 * alphabetically).
-	 * @return the set of job names that have been executed
+	 * @return the set of job names that have been executed.
 	 */
 	List<String> getJobNames();
 
 	/**
-	 * Fetch {@link JobInstance} values in descending order of creation (and there for
-	 * usually of first execution) with a 'like'/wildcard criteria.
-	 * @param jobName the name of the job to query for.
-	 * @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 job name requested.
+	 * 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<JobInstance> findJobInstancesByJobName(String jobName, int start, int count);
 
 	/**
-	 * Query the repository for the number of unique {@link JobInstance}s associated with
-	 * the supplied job name.
-	 * @param jobName the name of the job to query for
+	 * 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.
+	 * repository.
+	 * @throws {@code NoSuchJobException} thrown when there is no {@link JobInstance} for
+	 * the jobName specified.
 	 */
 	int getJobInstanceCount(@Nullable String jobName) throws NoSuchJobException;
 

spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/AbstractJobExplorerFactoryBean.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2021 the original author or authors.
+ * Copyright 2006-2022 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.
@@ -24,8 +24,8 @@
 import org.springframework.beans.factory.FactoryBean;
 
 /**
- * A {@link FactoryBean} that automates the creation of a {@link SimpleJobExplorer}.
- * Declares abstract methods for providing DAO object implementations.
+ * A {@link FactoryBean} that automates the creation of a {@link SimpleJobExplorer}. It
+ * declares abstract methods for providing DAO object implementations.
  *
  * @see JobExplorerFactoryBean
  * @author Dave Syer
@@ -35,32 +35,37 @@
 public abstract class AbstractJobExplorerFactoryBean implements FactoryBean<JobExplorer> {
 
 	/**
-	 * @return fully configured {@link JobInstanceDao} implementation.
-	 * @throws Exception thrown if error occurs during JobInstanceDao creation.
+	 * Creates a job instance data access object (DAO).
+	 * @return a fully configured {@link JobInstanceDao} implementation.
+	 * @throws {@code Exception} thrown if error occurs during JobInstanceDao creation.
 	 */
 	protected abstract JobInstanceDao createJobInstanceDao() throws Exception;
 
 	/**
-	 * @return fully configured {@link JobExecutionDao} implementation.
-	 * @throws Exception thrown if error occurs during JobExecutionDao creation.
+	 * Creates a job execution data access object (DAO).
+	 * @return a fully configured {@link JobExecutionDao} implementation.
+	 * @throws {@code Exception} thrown if error occurs during JobExecutionDao creation.
 	 */
 	protected abstract JobExecutionDao createJobExecutionDao() throws Exception;
 
 	/**
-	 * @return fully configured {@link StepExecutionDao} implementation.
-	 * @throws Exception thrown if error occurs during StepExecutionDao creation.
+	 * Creates a step execution data access object (DAO).
+	 * @return a fully configured {@link StepExecutionDao} implementation.
+	 * @throws {@code Exception} thrown if error occurs during StepExecutionDao creation.
 	 */
 	protected abstract StepExecutionDao createStepExecutionDao() throws Exception;
 
 	/**
+	 * Creates an execution context instance data access object (DAO).
 	 * @return fully configured {@link ExecutionContextDao} implementation.
-	 * @throws Exception thrown if error occurs during ExecutionContextDao creation.
+	 * @throws {@code Exception} thrown if error occurs during ExecutionContextDao
+	 * creation.
 	 */
 	protected abstract ExecutionContextDao createExecutionContextDao() throws Exception;
 
 	/**
-	 * The type of object to be returned from {@link #getObject()}.
-	 * @return JobExplorer.class
+	 * Returns the type of object to be returned from {@link #getObject()}.
+	 * @return {@code JobExplorer.class}
 	 * @see org.springframework.beans.factory.FactoryBean#getObjectType()
 	 */
 	@Override

spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/JobExplorerFactoryBean.java

@@ -45,9 +45,9 @@
 import org.springframework.util.Assert;
 
 /**
- * A {@link FactoryBean} that automates the creation of a {@link SimpleJobExplorer} using
- * JDBC DAO implementations. Requires the user to describe what kind of database they are
- * using.
+ * A {@link FactoryBean} that automates the creation of a {@link SimpleJobExplorer} by
+ * using JDBC DAO implementations. Requires the user to describe what kind of database
+ * they use.
  *
  * @author Dave Syer
  * @author Mahmoud Ben Hassine
@@ -75,56 +75,58 @@ protected long getNextKey() {
 	private Charset charset = StandardCharsets.UTF_8;
 
 	/**
-	 * A custom implementation of the {@link ExecutionContextSerializer}. The default, if
-	 * not injected, is the {@link Jackson2ExecutionContextStringSerializer}.
-	 * @param serializer used to serialize/deserialize an
-	 * {@link org.springframework.batch.item.ExecutionContext}
+	 * A custom implementation of {@link ExecutionContextSerializer}. The default, if not
+	 * injected, is the {@link Jackson2ExecutionContextStringSerializer}.
+	 * @param serializer The serializer used to serialize or deserialize an
+	 * {@link org.springframework.batch.item.ExecutionContext}.
 	 * @see ExecutionContextSerializer
 	 */
 	public void setSerializer(ExecutionContextSerializer serializer) {
 		this.serializer = serializer;
 	}
 
 	/**
+	 * Sets the data source.
+	 *
 	 * Public setter for the {@link DataSource}.
-	 * @param dataSource a {@link DataSource}
+	 * @param dataSource A {@code DataSource}.
 	 */
 	public void setDataSource(DataSource dataSource) {
 		this.dataSource = dataSource;
 	}
 
 	/**
-	 * Public setter for the {@link JdbcOperations}. If this property is not set
-	 * explicitly, a new {@link JdbcTemplate} will be created for the configured
-	 * DataSource by default.
+	 * Public setter for the {@link JdbcOperations}. If this property is not explicitly
+	 * set, a new {@link JdbcTemplate} is created, by default, for the configured
+	 * {@link DataSource}.
 	 * @param jdbcOperations a {@link JdbcOperations}
 	 */
 	public void setJdbcOperations(JdbcOperations jdbcOperations) {
 		this.jdbcOperations = jdbcOperations;
 	}
 
 	/**
-	 * Sets the table prefix for all the batch meta-data tables.
-	 * @param tablePrefix prefix for the batch meta-data tables
+	 * Sets the table prefix for all the batch metadata tables.
+	 * @param tablePrefix The table prefix for the batch metadata tables.
 	 */
 	public void setTablePrefix(String tablePrefix) {
 		this.tablePrefix = tablePrefix;
 	}
 
 	/**
 	 * The lob handler to use when saving {@link ExecutionContext} instances. Defaults to
-	 * null which works for most databases.
-	 * @param lobHandler Large object handler for saving
-	 * {@link org.springframework.batch.item.ExecutionContext}
+	 * {@code null}, which works for most databases.
+	 * @param lobHandler Large object handler for saving an
+	 * {@link org.springframework.batch.item.ExecutionContext}.
 	 */
 	public void setLobHandler(LobHandler lobHandler) {
 		this.lobHandler = lobHandler;
 	}
 
 	/**
-	 * Set the {@link Charset} to use when deserializing the execution context. Defaults
+	 * Sets the {@link Charset} to use when deserializing the execution context. Defaults
 	 * to "UTF-8". Must not be {@code null}.
-	 * @param charset to use when deserializing the execution context.
+	 * @param charset The character set to use when deserializing the execution context.
 	 * @see JdbcExecutionContextDao#setCharset(Charset)
 	 * @since 5.0
 	 */

spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/SimpleJobExplorer.java

@@ -31,7 +31,7 @@
 import java.util.Set;
 
 /**
- * Implementation of {@link JobExplorer} using the injected DAOs.
+ * Implementation of {@link JobExplorer} that uses the injected DAOs.
  *
  * @author Dave Syer
  * @author Lucas Ward
@@ -55,8 +55,8 @@ public class SimpleJobExplorer implements JobExplorer {
 	private ExecutionContextDao ecDao;
 
 	/**
-	 * Provide default constructor with low visibility in case user wants to use use
-	 * aop:proxy-target-class="true" for AOP interceptor.
+	 * Provides a default constructor with low visibility in case you want to use
+	 * aop:proxy-target-class="true" for the AOP interceptor.
 	 */
 	SimpleJobExplorer() {
 	}