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 e1c364f893..9b21f7e1db 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 @@ -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 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,24 +61,24 @@ 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) */ @@ -86,27 +86,26 @@ default JobInstance getLastJobInstance(String jobName) { 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 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,38 +117,37 @@ 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 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 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 findJobInstancesByJobName(String jobName, int start, int count); /** - * Query the repository for the number of unique {@link JobInstance}s associated with + * Query the repository for the number of unique {@link JobInstance} objects associated with * the supplied job name. - * @param jobName the name of the job to query for + * @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 + * repository. + * @throws {@code NoSuchJobException} thrown when there is no {@link JobInstance} for the * jobName specified. */ int getJobInstanceCount(@Nullable String jobName) throws NoSuchJobException; diff --git a/spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/AbstractJobExplorerFactoryBean.java b/spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/AbstractJobExplorerFactoryBean.java index 71ded02e89..e23a950e26 100644 --- a/spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/AbstractJobExplorerFactoryBean.java +++ b/spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/AbstractJobExplorerFactoryBean.java @@ -25,7 +25,7 @@ /** * A {@link FactoryBean} that automates the creation of a {@link SimpleJobExplorer}. - * Declares abstract methods for providing DAO object implementations. + * It declares abstract methods for providing DAO object implementations. * * @see JobExplorerFactoryBean * @author Dave Syer @@ -35,32 +35,41 @@ public abstract class AbstractJobExplorerFactoryBean implements FactoryBean { /** - * @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 diff --git a/spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/JobExplorerFactoryBean.java b/spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/JobExplorerFactoryBean.java index 128733ac38..a243fa7ee9 100644 --- a/spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/JobExplorerFactoryBean.java +++ b/spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/JobExplorerFactoryBean.java @@ -45,9 +45,8 @@ 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,10 +74,10 @@ protected long getNextKey() { private Charset charset = StandardCharsets.UTF_8; /** - * A custom implementation of the {@link ExecutionContextSerializer}. The default, if + * A custom implementation of {@link ExecutionContextSerializer}. The default, if * not injected, is the {@link Jackson2ExecutionContextStringSerializer}. - * @param serializer used to serialize/deserialize an - * {@link org.springframework.batch.item.ExecutionContext} + * @param serializer The serializer used to serialize or deserialize an + * {@link org.springframework.batch.item.ExecutionContext}. * @see ExecutionContextSerializer */ public void setSerializer(ExecutionContextSerializer serializer) { @@ -86,17 +85,19 @@ public void setSerializer(ExecutionContextSerializer 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) { @@ -104,8 +105,9 @@ public void setJdbcOperations(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; @@ -113,18 +115,18 @@ public void setTablePrefix(String 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 */ diff --git a/spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/SimpleJobExplorer.java b/spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/SimpleJobExplorer.java index 5e6b59238f..76d400de36 100644 --- a/spring-batch-core/src/main/java/org/springframework/batch/core/explore/support/SimpleJobExplorer.java +++ b/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() { }