More Javadoc editing

Author: Jay Bryant

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/BatchConfigurationException.java

@@ -16,9 +16,9 @@
 package org.springframework.batch.core.configuration;
 
 /**
- * Represents an error has occurred in the configuration of base batch infrastructure
- * (creation of a {@link org.springframework.batch.core.repository.JobRepository} for
- * example.
+ * Represents that an error has occurred in the configuration of the base batch
+ * infrastructure (the creation of a {@link org.springframework.batch.core.repository.JobRepository},
+ * for example).
  *
  * @author Michael Minella
  * @author Mahmoud Ben Hassine
@@ -29,6 +29,8 @@ public class BatchConfigurationException extends RuntimeException {
 	private static final long serialVersionUID = 1L;
 
 	/**
+	 * Create an exception with the given {@Link Throwable}.
+	 *
 	 * @param t an exception to be wrapped
 	 */
 	public BatchConfigurationException(Throwable t) {

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/DuplicateJobException.java

@@ -36,6 +36,8 @@ public DuplicateJobException(String msg) {
 	}
 
 	/**
+	 * Create an exception with the given message and the given exception.
+	 *
 	 * @param msg error message.
 	 * @param e instance of {@link Throwable} that is the cause of the exception.
 	 */

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/JobFactory.java

@@ -32,7 +32,7 @@ public interface JobFactory {
 	Job createJob();
 
 	/**
-	 * @return The {@link String} containing the {@link Job} name.
+	 * @return The {@link String} that contains the {@link Job} name.
 	 */
 	String getJobName();
 

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/JobRegistry.java

@@ -35,8 +35,9 @@ public interface JobRegistry extends ListableJobLocator {
 	void register(JobFactory jobFactory) throws DuplicateJobException;
 
 	/**
-	 * Unregisters a previously registered {@link Job}. If it was not previously
-	 * registered there is no error.
+	 * Unregisters a previously registered {@link Job}. If it was not
+	 * previously registered, there is no error.
+	 *
 	 * @param jobName the {@link Job} to unregister.
 	 */
 	void unregister(String jobName);

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/StepRegistry.java

@@ -22,7 +22,7 @@
 import java.util.Collection;
 
 /**
- * Registry keeping track of all the {@link Step} defined in a
+ * Registry keeping track of all the {@link Step} instances defined in a
  * {@link org.springframework.batch.core.Job}.
  *
  * @author Sebastien Gerard

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/AbstractBatchConfiguration.java

@@ -40,9 +40,8 @@
 import org.springframework.util.Assert;
 
 /**
- * Base {@code Configuration} class providing common structure for enabling and using
- * Spring Batch. Customization is available by implementing the {@link BatchConfigurer}
- * interface.
+ * Base {@code Configuration} class that provides a common structure for enabling and using Spring Batch.
+ * Customization is available by implementing the {@link BatchConfigurer} interface.
  *
  * @author Dave Syer
  * @author Michael Minella
@@ -66,7 +65,7 @@ public abstract class AbstractBatchConfiguration implements ImportAware, Initial
 	/**
 	 * Establish the {@link JobBuilderFactory} for the batch execution.
 	 * @return The instance of the {@link JobBuilderFactory}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	@Bean
 	public JobBuilderFactory jobBuilders() throws Exception {
@@ -76,7 +75,7 @@ public JobBuilderFactory jobBuilders() throws Exception {
 	/**
 	 * Establish the {@link StepBuilderFactory} for the batch execution.
 	 * @return The instance of the {@link StepBuilderFactory}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	@Bean
 	public StepBuilderFactory stepBuilders() throws Exception {
@@ -86,31 +85,31 @@ public StepBuilderFactory stepBuilders() throws Exception {
 	/**
 	 * Establish the {@link JobRepository} for the batch execution.
 	 * @return The instance of the {@link JobRepository}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	@Bean
 	public abstract JobRepository jobRepository() throws Exception;
 
 	/**
 	 * Establish the {@link JobLauncher} for the batch execution.
 	 * @return The instance of the {@link JobLauncher}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	@Bean
 	public abstract JobLauncher jobLauncher() throws Exception;
 
 	/**
 	 * Establish the {@link JobExplorer} for the batch execution.
 	 * @return The instance of the {@link JobExplorer}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	@Bean
 	public abstract JobExplorer jobExplorer() throws Exception;
 
 	/**
 	 * Establish the {@link JobRegistry} for the batch execution.
 	 * @return The instance of the {@link JobRegistry}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	@Bean
 	public JobRegistry jobRegistry() throws Exception {
@@ -120,7 +119,7 @@ public JobRegistry jobRegistry() throws Exception {
 	/**
 	 * Establish the {@link PlatformTransactionManager} for the batch execution.
 	 * @return The instance of the {@link PlatformTransactionManager}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	public abstract PlatformTransactionManager transactionManager() throws Exception;
 

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/BatchConfigurationSelector.java

@@ -21,9 +21,8 @@
 import org.springframework.util.Assert;
 
 /**
- * Base {@code Configuration} class providing common structure for enabling and using
- * Spring Batch. Customization is available by implementing the {@link BatchConfigurer}
- * interface.
+ * Base {@code Configuration} class that provides common structure for enabling and using Spring Batch. Customization is
+ * available by implementing the {@link BatchConfigurer} interface.
  *
  * @author Dave Syer
  * @since 2.2
@@ -50,4 +49,4 @@ public String[] selectImports(AnnotationMetadata importingClassMetadata) {
 		return imports;
 	}
 
-}
+}

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/BatchConfigurer.java

@@ -21,8 +21,7 @@
 import org.springframework.transaction.PlatformTransactionManager;
 
 /**
- * Strategy interface for users to provide as a factory for custom components needed by a
- * Batch system.
+ * Strategy interface that users can provide as a factory for custom components needed by a Batch system.
  *
  * @author Dave Syer
  *

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/DefaultBatchConfigurer.java

@@ -47,19 +47,19 @@ public class DefaultBatchConfigurer implements BatchConfigurer {
 	private JobExplorer jobExplorer;
 
 	/**
-	 * Create a new {@link DefaultBatchConfigurer} with the passed datasource. This
-	 * constructor will configure a default {@link DataSourceTransactionManager}.
+	 * Create a new {@link DefaultBatchConfigurer} with the passed datasource. This constructor
+	 * configures a default {@link DataSourceTransactionManager}.
+	 *
 	 * @param dataSource to use for the job repository and job explorer
 	 */
 	public DefaultBatchConfigurer(DataSource dataSource) {
 		this(dataSource, new DataSourceTransactionManager(dataSource));
 	}
 
 	/**
-	 * Create a new {@link DefaultBatchConfigurer} with the passed datasource and
-	 * transaction manager.
-	 * @param dataSource to use for the job repository and job explorer
-	 * @param transactionManager to use for the job repository
+	 * Create a new {@link DefaultBatchConfigurer} with the given datasource and transaction manager.
+	 * @param dataSource The data source to use for the job repository and job explorer.
+	 * @param transactionManager The transaction manager to use for the job repository.
 	 */
 	public DefaultBatchConfigurer(DataSource dataSource, PlatformTransactionManager transactionManager) {
 		Assert.notNull(dataSource, "DataSource must not be null");

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/EnableBatchProcessing.java

@@ -64,8 +64,8 @@
  * }
  * </pre>
  *
- * The user should provide a {@link DataSource} as a bean in the context, or else
- * implement {@link BatchConfigurer} in the configuration class itself, e.g.
+ * You should provide a {@link DataSource} as a bean in the context or else implement {@link BatchConfigurer} in
+ * the configuration class itself -- for example:
  *
  * <pre class="code">
  * &#064;Configuration
@@ -87,41 +87,30 @@
  * }
  * </pre>
  *
- * If multiple {@link javax.sql.DataSource}s are defined in the context, the primary
- * autowire candidate will be used, otherwise an exception will be thrown.
+ * If multiple {@link javax.sql.DataSource} instances are defined in the context, the primary autowire candidate
+ * is used. Otherwise, an exception is thrown.
  *
- * Note that only one of your configuration classes needs to have the
- * <code>&#064;EnableBatchProcessing</code> annotation. Once you have an
- * <code>&#064;EnableBatchProcessing</code> class in your configuration you will have an
- * instance of {@link StepScope} and {@link org.springframework.batch.core.scope.JobScope}
- * so your beans inside steps can have <code>&#064;Scope("step")</code> and
- * <code>&#064;Scope("job")</code> respectively. You will also be able to
- * <code>&#064;Autowired</code> some useful stuff into your context:
+ * Note that only one of your configuration classes needs to have the <code>&#064;EnableBatchProcessing</code>
+ * annotation. Once you have an <code>&#064;EnableBatchProcessing</code> class in your configuration, you have an
+ * instance of {@link StepScope} and {@link org.springframework.batch.core.scope.JobScope}, so your beans inside steps
+ * can have <code>&#064;Scope("step")</code> and <code>&#064;Scope("job")</code> respectively. You can also
+ * use <code>&#064;Autowired</code> to insert some useful stuff into your context:
  *
  * <ul>
- * <li>a {@link JobRepository} (bean name "jobRepository" of type
- * {@link org.springframework.batch.core.repository.support.SimpleJobRepository})</li>
- * <li>a {@link JobLauncher} (bean name "jobLauncher" of type
- * {@link org.springframework.batch.core.launch.support.SimpleJobLauncher})</li>
- * <li>a {@link JobRegistry} (bean name "jobRegistry" of type
- * {@link org.springframework.batch.core.configuration.support.MapJobRegistry})</li>
- * <li>a {@link org.springframework.batch.core.explore.JobExplorer} (bean name
- * "jobExplorer" of type
- * {@link org.springframework.batch.core.explore.support.SimpleJobExplorer})</li>
- * <li>a {@link JobBuilderFactory} (bean name "jobBuilders") as a convenience to prevent
- * you from having to inject the job repository into every job, as in the examples
- * above</li>
- * <li>a {@link StepBuilderFactory} (bean name "stepBuilders") as a convenience to prevent
- * you from having to inject the job repository and transaction manager into every
- * step</li>
+ * <li>a {@link JobRepository} (bean name "jobRepository" of type {@link org.springframework.batch.core.repository.support.SimpleJobRepository})</li>
+ * <li>a {@link JobLauncher} (bean name "jobLauncher" of type {@link org.springframework.batch.core.launch.support.SimpleJobLauncher})</li>
+ * <li>a {@link JobRegistry} (bean name "jobRegistry" of type {@link org.springframework.batch.core.configuration.support.MapJobRegistry})</li>
+ * <li>a {@link org.springframework.batch.core.explore.JobExplorer} (bean name "jobExplorer" of type {@link org.springframework.batch.core.explore.support.SimpleJobExplorer})</li>
+ * <li>a {@link JobBuilderFactory} (bean name "jobBuilders") as a convenience to prevent you from having to inject the
+ * job repository into every job, as in the earlier examples</li>
+ * <li>a {@link StepBuilderFactory} (bean name "stepBuilders") as a convenience to prevent you from having to inject the
+ * job repository and transaction manager into every step</li>
  * </ul>
  *
- * The transaction manager provided by this annotation will be of type
- * {@link org.springframework.jdbc.datasource.DataSourceTransactionManager} configured
- * with the {@link javax.sql.DataSource} provided within the context.
+ * The transaction manager provided by this annotation is of type {@link org.springframework.jdbc.datasource.DataSourceTransactionManager}
+ * and is configured with the {@link javax.sql.DataSource} provided within the context.
  *
- * In order to use a custom transaction manager, a custom {@link BatchConfigurer} should
- * be provided. For example:
+ * To use a custom transaction manager, you should provide a custom {@link BatchConfigurer} -- for example:
  *
  * <pre class="code">
  * &#064;Configuration
@@ -143,13 +132,11 @@
  * }
  * </pre>
  *
- * If the configuration is specified as <code>modular=true</code> then the context will
- * also contain an {@link AutomaticJobRegistrar}. The job registrar is useful for
- * modularizing your configuration if there are multiple jobs. It works by creating
- * separate child application contexts containing job configurations and registering those
- * jobs. The jobs can then create steps and other dependent components without needing to
- * worry about bean definition name clashes. Beans of type
- * {@link ApplicationContextFactory} will be registered automatically with the job
+ * If the configuration is specified as <code>modular=true</code>, the context also contains an
+ * {@link AutomaticJobRegistrar}. The job registrar is useful for modularizing your configuration if there are multiple
+ * jobs. It works by creating separate child application contexts to contain job configurations and register those
+ * jobs. The jobs can then create steps and other dependent components without needing to worry about bean definition
+ * name clashes. Beans of type {@link ApplicationContextFactory} are automatically registered with the job
  * registrar. Example:
  *
  * <pre class="code">
@@ -172,13 +159,12 @@
  * }
  * </pre>
  *
- * Note that a modular parent context in general should <em>not</em> itself contain
- * &#64;Bean definitions for job, especially if a {@link BatchConfigurer} is provided,
- * because cyclic configuration dependencies are otherwise likely to develop.
+ * Note that a modular parent context, in general, should <em>not</em> itself contain &#64;Bean definitions for job,
+ * especially if a {@link BatchConfigurer} is provided, because cyclic configuration dependencies are likely
+ * to develop.
  *
  * <p>
- * For reference, the first example above can be compared to the following Spring XML
- * configuration:
+ * For reference, compare the first example shown earlier to the following Spring XML configuration:
  *
  * <pre class="code">
  * {@code
@@ -208,12 +194,12 @@
 public @interface EnableBatchProcessing {
 
 	/**
-	 * Indicate whether the configuration is going to be modularized into multiple
-	 * application contexts. If true then you should not create any &#64;Bean Job
-	 * definitions in this context, but rather supply them in separate (child) contexts
-	 * through an {@link ApplicationContextFactory}.
-	 * @return boolean indicating whether the configuration is going to be modularized
-	 * into multiple application contexts. Defaults to false.
+	 * Indicate whether the configuration is going to be modularized into multiple application contexts. If true,
+	 * you should not create any &#64;Bean Job definitions in this context but, rather, supply them in separate (child)
+	 * contexts through an {@link ApplicationContextFactory}.
+	 *
+	 * @return boolean indicating whether the configuration is going to be
+	 * modularized into multiple application contexts. Defaults to {@code false}.
 	 */
 	boolean modular() default false;
 

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/JobBuilderFactory.java

@@ -19,8 +19,7 @@
 import org.springframework.batch.core.repository.JobRepository;
 
 /**
- * Convenient factory for a {@link JobBuilder} which sets the {@link JobRepository}
- * automatically.
+ * Convenient factory for a {@link JobBuilder} that sets the {@link JobRepository} automatically.
  *
  * @author Dave Syer
  * @author Mahmoud Ben Hassine
@@ -38,9 +37,9 @@ public JobBuilderFactory(JobRepository jobRepository) {
 	}
 
 	/**
-	 * Creates a job builder and initializes its job repository. Note that if the builder
-	 * is used to create a @Bean definition then the name of the job and the bean name
-	 * might be different.
+	 * Creates a job builder and initializes its job repository. Note that, if the builder is used to create a @Bean
+	 * definition, the name of the job and the bean name might be different.
+	 *
 	 * @param name the name of the job
 	 * @return a job builder
 	 */

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/JobScope.java

@@ -24,10 +24,10 @@
 
 /**
  * <p>
- * Convenient annotation for job scoped beans that defaults the proxy mode, so that it
- * doesn't have to be specified explicitly on every bean definition. Use this on any
- * &#64;Bean that needs to inject &#64;Values from the job context, and any bean that
- * needs to share a lifecycle with a job execution (e.g. an JobExecutionListener). E.g.
+ * Convenient annotation for job-scoped beans that defaults the proxy mode, so that it does not have to be specified
+ * explicitly on every bean definition. Use this on any &#64;Bean that needs to inject &#64;Values from the job
+ * context, and any bean that needs to share a lifecycle with a job execution (such as an JobExecutionListener).
+ * The following listing shows an example:
  * </p>
  *
  * <pre class="code">
@@ -54,4 +54,4 @@
 @Documented
 public @interface JobScope {
 
-}
+}

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/ModularBatchConfiguration.java

@@ -46,8 +46,9 @@ public class ModularBatchConfiguration extends SimpleBatchConfiguration {
 
 	/**
 	 * Creates a {@link AutomaticJobRegistrar} bean.
-	 * @return New instance of {@link AutomaticJobRegistrar}.
-	 * @throws Exception The {@link Exception} thrown if an error occurs.
+	 *
+	 * @return a new instance of {@link AutomaticJobRegistrar}.
+	 * @throws an {@link Exception} if an error occurs.
 	 */
 	@Bean
 	public AutomaticJobRegistrar jobRegistrar() throws Exception {

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/SimpleBatchConfiguration.java

@@ -35,9 +35,8 @@
 import org.springframework.transaction.PlatformTransactionManager;
 
 /**
- * Base {@code Configuration} class providing common structure for enabling and using
- * Spring Batch. Customization is available by implementing the {@link BatchConfigurer}
- * interface.
+ * Base {@code Configuration} class to provide a common structure for enabling and using Spring Batch.
+ * Customization is available by implementing the {@link BatchConfigurer} interface.
  *
  * @author Dave Syer
  * @author Mahmoud Ben Hassine

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/StepBuilderFactory.java

@@ -45,9 +45,9 @@ public StepBuilderFactory(JobRepository jobRepository, PlatformTransactionManage
 	}
 
 	/**
-	 * Creates a step builder and initializes its job repository and transaction manager.
-	 * Note that if the builder is used to create a @Bean definition then the name of
-	 * the step and the bean name might be different.
+	 * Creates a step builder and initializes its job repository and transaction manager. Note that, if the builder is
+	 * used to create a @Bean definition, the name of the step and the bean name might be different.
+	 *
 	 * @param name the name of the step
 	 * @return a step builder
 	 */