Add missing docs for batch.core and batch.core.configuration packages

Issue spring-projects#4068

spring-batch-core/src/main/java/org/springframework/batch/core/BatchStatus.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.
@@ -37,8 +37,47 @@ public enum BatchStatus {
 	 * steps that have finished processing, but were not successful, and where
 	 * they should be skipped on a restart (so FAILED is the wrong status).
 	 */
-	COMPLETED, STARTING, STARTED, STOPPING, STOPPED, FAILED, ABANDONED, UNKNOWN;
 
+	/**
+	 * The batch job has successfully completed its execution.
+	 */
+	COMPLETED,
+	/**
+	 * Status of a batch job prior to its execution.
+	 */
+	STARTING,
+	/**
+	 * Status of a batch job that is running.
+	 */
+	STARTED,
+	/**
+	 * Status of batch job waiting for a step to complete before stopping the batch job.
+	 */
+	STOPPING,
+	/**
+	 * Status of a batch job that has been stopped by request.
+	 */
+	STOPPED,
+	/**
+	 * Status of a batch job that has failed during its execution.
+	 */
+	FAILED,
+	/**
+	 * Status of a batch job that did not stop properly and can not be restarted.
+	 */
+	ABANDONED,
+	/**
+	 * Status of a batch job that is in an uncertain state.
+	 */
+	UNKNOWN;
+
+	/**
+	 * Convenience method to return the higher value status of the statuses pass in to the method.
+	 *
+	 * @param status1 The first status to check.
+	 * @param status2 The second status to check.
+	 * @return The higher value status of the two statuses.
+	 */
 	public static BatchStatus max(BatchStatus status1, BatchStatus status2) {
 		return status1.isGreaterThan(status2) ? status1 : status2;
 	}

spring-batch-core/src/main/java/org/springframework/batch/core/ChunkListener.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.
@@ -29,7 +29,10 @@
  */
 public interface ChunkListener extends StepListener {
 
-	static final String ROLLBACK_EXCEPTION_KEY = "sb_rollback_exception";
+	/**
+	 * The key for retrieving the rollback exception.
+	 */
+	String ROLLBACK_EXCEPTION_KEY = "sb_rollback_exception";
 
 	/**
 	 * Callback before the chunk is executed, but inside the transaction.

spring-batch-core/src/main/java/org/springframework/batch/core/Entity.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2013 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.
@@ -37,10 +37,20 @@ public class Entity implements Serializable {
 
 	private volatile Integer version;
 
+	/**
+	 * Default constructor for {@link Entity}.
+	 *
+	 * The ID defaults to zero.
+	 */
 	public Entity() {
 		super();
 	}
 
+	/**
+	 * The constructor for the {@link Entity} where the ID is established.
+	 *
+	 * @param id The ID for the entity.
+	 */
 	public Entity(Long id) {
 		super();
 
@@ -50,10 +60,16 @@ public Entity(Long id) {
 		this.id = id;
 	}
 
+	/**
+	 * @return The ID associated with the {@link Entity}.
+	 */
 	public Long getId() {
 		return id;
 	}
 
+	/**
+	 * @param id The ID for the {@link Entity}.
+	 */
 	public void setId(Long id) {
 		this.id = id;
 	}

spring-batch-core/src/main/java/org/springframework/batch/core/ExitStatus.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.
@@ -74,10 +74,21 @@ public class ExitStatus implements Serializable, Comparable<ExitStatus> {
 
 	private final String exitDescription;
 
+	/**
+	 * Constructor that accepts the exit code and sets the exit description to an empty {@link String}.
+	 *
+	 * @param exitCode The exit code to be used for the {@link ExitStatus}.
+	 */
 	public ExitStatus(String exitCode) {
 		this(exitCode, "");
 	}
 
+	/**
+	 * Constructor that establishes the exit code and the exit description for the {@link ExitStatus}.
+	 *
+	 * @param exitCode The exit code to be used for the {@link ExitStatus}.
+	 * @param exitDescription The exit description to be used for the {@link ExitStatus}.
+	 */
 	public ExitStatus(String exitCode, String exitDescription) {
 		super();
 		this.exitCode = exitCode;

spring-batch-core/src/main/java/org/springframework/batch/core/JobExecution.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.
@@ -65,6 +65,11 @@ public class JobExecution extends Entity {
 
 	private transient volatile List<Throwable> failureExceptions = new CopyOnWriteArrayList<>();
 
+	/**
+	 * Constructor that sets the state of the instance to the {@link JobExecution} parameter.
+	 *
+	 * @param original The {@link JobExecution} to be copied.
+	 */
 	public JobExecution(JobExecution original) {
 		this.jobParameters = original.getJobParameters();
 		this.jobInstance = original.getJobInstance();
@@ -98,45 +103,83 @@ public JobExecution(JobInstance job, Long id, @Nullable JobParameters jobParamet
 	/**
 	 * Constructor for transient (unsaved) instances.
 	 *
-	 * @param job the enclosing {@link JobInstance}
-	 * @param jobParameters {@link JobParameters} instance for this JobExecution.
+	 * @param job The enclosing {@link JobInstance}.
+	 * @param jobParameters The {@link JobParameters} instance for this JobExecution.
 	 */
 	public JobExecution(JobInstance job, JobParameters jobParameters) {
 		this(job, null, jobParameters);
 	}
 
+	/**
+	 * Constructor that accepts the job execution ID and {@link JobParameters}.
+	 *
+	 * @param id The job execution ID.
+	 * @param jobParameters The {@link JobParameters} for the {@link JobExecution}.
+	 */
 	public JobExecution(Long id, JobParameters jobParameters) {
 		this(null, id, jobParameters);
 	}
 
+	/**
+	 * Constructor that accepts the job execution ID.
+	 *
+	 * @param id The job execution ID.
+	 */
 	public JobExecution(Long id) {
 		this(null, id, null);
 	}
 
+	/**
+	 * @return The current {@link JobParameters}.
+	 */
 	public JobParameters getJobParameters() {
 		return this.jobParameters;
 	}
 
+	/**
+	 * @return The current end time.
+	 */
 	public Date getEndTime() {
 		return endTime;
 	}
 
+	/**
+	 * Set the {@link JobInstance} used by the {@link JobExecution}.
+	 *
+	 * @param jobInstance The {@link JobInstance} used by the {@link JobExecution}.
+	 */
 	public void setJobInstance(JobInstance jobInstance) {
 		this.jobInstance = jobInstance;
 	}
 
+	/**
+	 * Set the end time.
+	 *
+	 * @param endTime The {@link Date} to be used for the end time.
+	 */
 	public void setEndTime(Date endTime) {
 		this.endTime = endTime;
 	}
 
+	/**
+	 * @return The current start time.
+	 */
 	public Date getStartTime() {
 		return startTime;
 	}
 
+	/**
+	 * Set the start time.
+	 *
+	 * @param startTime The {@link Date} to be used for the start time.
+	 */
 	public void setStartTime(Date startTime) {
 		this.startTime = startTime;
 	}
 
+	/**
+	 * @return The current {@link BatchStatus}.
+	 */
 	public BatchStatus getStatus() {
 		return status;
 	}
@@ -297,6 +340,10 @@ public void setLastUpdated(Date lastUpdated) {
 		this.lastUpdated = lastUpdated;
 	}
 
+	/**
+	 * Retrieve a list of exceptions.
+	 * @return The {@link List} of {@link Throwable} objects.
+	 */
 	public List<Throwable> getFailureExceptions() {
 		return failureExceptions;
 	}

spring-batch-core/src/main/java/org/springframework/batch/core/JobInstance.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.
@@ -43,6 +43,12 @@ public class JobInstance extends Entity {
 
 	private final String jobName;
 
+	/**
+	 * Constructor for {@link JobInstance}.
+	 *
+	 * @param id The instance ID.
+	 * @param jobName The name associated with the {@link JobInstance}.
+	 */
 	public JobInstance(Long id, String jobName) {
 		super(id);
 		Assert.hasLength(jobName, "A jobName is required");
@@ -61,6 +67,9 @@ public String toString() {
 		return super.toString() + ", Job=[" + jobName + "]";
 	}
 
+	/**
+	 * @return The current instance ID.
+	 */
 	public long getInstanceId() {
 		return super.getId();
 	}

spring-batch-core/src/main/java/org/springframework/batch/core/JobInterruptedException.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.
@@ -33,10 +33,21 @@ public class JobInterruptedException extends JobExecutionException {
 
 	private BatchStatus status = BatchStatus.STOPPED;
 
+	/**
+	 * Constructor that sets the message for the exception.
+	 *
+	 * @param msg The message for the exception.
+	 */
 	public JobInterruptedException(String msg) {
 		super(msg);
 	}
 
+	/**
+	 * Constructor that sets the message for the exception.
+	 *
+	 * @param msg The message for the exception.
+	 * @param status The desired {@link BatchStatus} of the surrounding execution after interruption.
+	 */
 	public JobInterruptedException(String msg, BatchStatus status) {
 		super(msg);
 		this.status = status;

spring-batch-core/src/main/java/org/springframework/batch/core/JobParameter.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.
@@ -125,6 +125,9 @@ public JobParameter(Double parameter) {
 		this(parameter, true);
 	}
 
+	/**
+	 * @return The identifying flag.  It is set to true if the job parameter is identifying.
+	 */
 	public boolean isIdentifying() {
 		return identifying;
 	}
@@ -168,10 +171,25 @@ public int hashCode() {
 	}
 
 	/**
-	 * Enumeration representing the type of a JobParameter.
+	 * Enumeration representing the type of {@link JobParameter}.
 	 */
 	public enum ParameterType {
 
-		STRING, DATE, LONG, DOUBLE;
+		/**
+		 * String parameter type.
+		 */
+		STRING,
+		/**
+		 * Date parameter type.
+		 */
+		DATE,
+		/**
+		 * Long parameter type.
+		 */
+		LONG,
+		/**
+		 * Double parameter type.
+		 */
+		DOUBLE;
 	}
 }