Make domain model entities immutable

This commit introduces several major changes to make the
domain model entities immutable:

- It removes the setter of the Entity id
- It creates all entities with an assigned ID as well as
their dependencies which cannot be changed after creation
- The type of the identity field has been changed to a
primitive long in order to avoid nullability issues
- Shallow entity creation has been removed from all DAOs
- All entity creation is now centralized in the job repository
(ie removal of JobExecution#creatStepExecution). Note that
StepExecution#createStepContribution is an exception since
StepContribution is not an Entity
- Superfluous methods "add" and "save" have been removed and
replaced with clearly defined CRUD operations
- Move restartability logic from JobRepository to JobOperator

These changes are important enablers for cleaner and safer APIs.

Resolves #1870

Author: fmbenhassine

spring-batch-core/src/main/java/org/springframework/batch/core/Entity.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.
@@ -17,6 +17,7 @@
 package org.springframework.batch.core;
 
 import java.io.Serializable;
+import java.util.Objects;
 
 import org.springframework.util.ClassUtils;
 
@@ -32,46 +33,25 @@
  */
 public class Entity implements Serializable {
 
-	private Long id;
+	private final long id;
 
-	private volatile Integer version;
-
-	/**
-	 * Default constructor for {@link Entity}.
-	 * <p>
-	 * The ID defaults to zero.
-	 */
-	public Entity() {
-		super();
-	}
+	private Integer version;
 
 	/**
 	 * The constructor for the {@link Entity} where the ID is established.
 	 * @param id The ID for the entity.
 	 */
-	public Entity(Long id) {
-		super();
-
-		// Commented out because StepExecutions are still created in a disconnected
-		// manner. The Repository should create them, then this can be uncommented.
-		// Assert.notNull(id, "Entity id must not be null.");
+	public Entity(long id) {
 		this.id = id;
 	}
 
 	/**
 	 * @return The ID associated with the {@link Entity}.
 	 */
-	public Long getId() {
+	public long getId() {
 		return id;
 	}
 
-	/**
-	 * @param id The ID for the {@link Entity}.
-	 */
-	public void setId(Long id) {
-		this.id = id;
-	}
-
 	/**
 	 * @return the version.
 	 */
@@ -108,47 +88,16 @@ public String toString() {
 		return String.format("%s: id=%d, version=%d", ClassUtils.getShortName(getClass()), id, version);
 	}
 
-	/**
-	 * Attempt to establish identity based on {@code id} if both exist. If either
-	 * {@code id} does not exist, use {@code Object.equals()}.
-	 *
-	 * @see java.lang.Object#equals(java.lang.Object)
-	 */
 	@Override
-	public boolean equals(Object other) {
-		if (other == this) {
-			return true;
-		}
-		if (other == null) {
-			return false;
-		}
-		if (!(other instanceof Entity entity)) {
-			return false;
-		}
-		if (id == null || entity.getId() == null) {
+	public boolean equals(Object o) {
+		if (!(o instanceof Entity entity))
 			return false;
-		}
-		return id.equals(entity.getId());
+		return id == entity.id;
 	}
 
-	/**
-	 * Use {@code id}, if it exists, to establish a hash code. Otherwise fall back to
-	 * {@code Object.hashCode()}. It is based on the same information as {@code equals},
-	 * so, if that changes, this will. Note that this follows the contract of
-	 * {@code Object.hashCode()} but will cause problems for anyone adding an unsaved
-	 * {@link Entity} to a {@code Set} because {@code Set.contains()} almost certainly
-	 * returns false for the {@link Entity} after it is saved. Spring Batch does not store
-	 * any of its entities in sets as a matter of course, so this is internally
-	 * consistent. Clients should not be exposed to unsaved entities.
-	 *
-	 * @see java.lang.Object#hashCode()
-	 */
 	@Override
 	public int hashCode() {
-		if (id == null) {
-			return System.identityHashCode(this);
-		}
-		return 39 + 87 * id.hashCode();
+		return Objects.hashCode(id);
 	}
 
 }

spring-batch-core/src/main/java/org/springframework/batch/core/job/AbstractJob.java

@@ -277,8 +277,8 @@ public final void execute(JobExecution execution) {
 		Observation observation = MicrometerMetrics
 			.createObservation(BatchMetrics.METRICS_PREFIX + "job", this.observationRegistry)
 			.highCardinalityKeyValue(BatchMetrics.METRICS_PREFIX + "job.instanceId",
-					execution.getJobInstance().getId().toString())
-			.highCardinalityKeyValue(BatchMetrics.METRICS_PREFIX + "job.executionId", execution.getId().toString())
+					String.valueOf(execution.getJobInstance().getId()))
+			.highCardinalityKeyValue(BatchMetrics.METRICS_PREFIX + "job.executionId", String.valueOf(execution.getId()))
 			.lowCardinalityKeyValue(BatchMetrics.METRICS_PREFIX + "job.name", execution.getJobInstance().getJobName())
 			.start();
 		try (Observation.Scope scope = observation.openScope()) {

spring-batch-core/src/main/java/org/springframework/batch/core/job/JobExecution.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.
@@ -16,14 +16,12 @@
 
 package org.springframework.batch.core.job;
 
-import java.io.IOException;
-import java.io.ObjectInputStream;
 import java.time.LocalDateTime;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.HashSet;
-import java.util.LinkedHashSet;
+import java.util.LinkedList;
 import java.util.List;
 import java.util.Set;
 import java.util.concurrent.CopyOnWriteArrayList;
@@ -50,85 +48,38 @@ public class JobExecution extends Entity {
 
 	private JobInstance jobInstance;
 
-	private volatile Collection<StepExecution> stepExecutions = Collections.synchronizedSet(new LinkedHashSet<>());
+	private final List<StepExecution> stepExecutions = Collections.synchronizedList(new LinkedList<>());
 
-	private volatile BatchStatus status = BatchStatus.STARTING;
+	private BatchStatus status = BatchStatus.STARTING;
 
-	private volatile LocalDateTime startTime = null;
+	private LocalDateTime createTime = LocalDateTime.now();
 
-	private volatile LocalDateTime createTime = LocalDateTime.now();
+	private LocalDateTime startTime = null;
 
-	private volatile LocalDateTime endTime = null;
+	private LocalDateTime endTime = null;
 
-	private volatile LocalDateTime lastUpdated = null;
+	private LocalDateTime lastUpdated = null;
 
-	private volatile ExitStatus exitStatus = ExitStatus.UNKNOWN;
+	private ExitStatus exitStatus = ExitStatus.UNKNOWN;
 
-	private volatile ExecutionContext executionContext = new ExecutionContext();
+	private ExecutionContext executionContext = new ExecutionContext();
 
-	private transient volatile List<Throwable> failureExceptions = new CopyOnWriteArrayList<>();
+	private final 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();
-		this.stepExecutions = original.getStepExecutions();
-		this.status = original.getStatus();
-		this.startTime = original.getStartTime();
-		this.createTime = original.getCreateTime();
-		this.endTime = original.getEndTime();
-		this.lastUpdated = original.getLastUpdated();
-		this.exitStatus = original.getExitStatus();
-		this.executionContext = original.getExecutionContext();
-		this.failureExceptions = original.getFailureExceptions();
-		this.setId(original.getId());
-		this.setVersion(original.getVersion());
-	}
-
-	/**
-	 * Because a JobExecution is not valid unless the job is set, this constructor is the
-	 * only valid one from a modeling point of view.
-	 * @param job The job of which this execution is a part.
-	 * @param id A {@link Long} that represents the {@code id} for the
-	 * {@code JobExecution}.
+	 * Create a new {@link JobExecution} instance. Because a JobExecution is not valid
+	 * unless the job instance is set, this constructor is the only valid one from a
+	 * modeling point of view.
+	 * @param jobInstance The job instance of which this execution is a part.
+	 * @param id of the {@code JobExecution}.
 	 * @param jobParameters A {@link JobParameters} instance for this
 	 * {@code JobExecution}.
 	 */
-	public JobExecution(JobInstance job, Long id, @Nullable JobParameters jobParameters) {
+	// TODO add execution context parameter
+	public JobExecution(long id, JobInstance jobInstance, JobParameters jobParameters) {
 		super(id);
-		this.jobInstance = job;
-		this.jobParameters = jobParameters == null ? new JobParameters() : jobParameters;
-	}
-
-	/**
-	 * Constructor for transient (unsaved) instances.
-	 * @param job The enclosing {@link JobInstance}.
-	 * @param jobParameters The {@link JobParameters} instance for this
-	 * {@code JobExecution}.
-	 */
-	public JobExecution(JobInstance job, JobParameters jobParameters) {
-		this(job, null, jobParameters);
-	}
-
-	/**
-	 * Constructor that accepts the job execution {@code id} and {@link JobParameters}.
-	 * @param id The job execution {@code 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 {@code id}.
-	 * @param id The job execution {@code id}.
-	 */
-	public JobExecution(Long id) {
-		this(null, id, null);
+		this.jobInstance = jobInstance;
+		this.jobParameters = jobParameters;
 	}
 
 	/**
@@ -204,15 +155,14 @@ public void upgradeStatus(BatchStatus status) {
 	}
 
 	/**
-	 * Convenience getter for the {@code id} of the enclosing job. Useful for DAO
+	 * Convenience getter for the {@code id} of the enclosing job instance. Useful for DAO
 	 * implementations.
-	 * @return the {@code id} of the enclosing job.
+	 * @return the {@code id} of the enclosing job instance.
 	 */
-	public Long getJobId() {
-		if (jobInstance != null) {
-			return jobInstance.getId();
-		}
-		return null;
+	// TODO why is that needed for DAO implementations? should not be needed with the new
+	// model
+	public long getJobInstanceId() {
+		return this.jobInstance.getId();
 	}
 
 	/**
@@ -230,29 +180,18 @@ public ExitStatus getExitStatus() {
 	}
 
 	/**
-	 * @return the Job that is executing.
+	 * @return the Job instance that is executing.
 	 */
 	public JobInstance getJobInstance() {
-		return jobInstance;
+		return this.jobInstance;
 	}
 
 	/**
 	 * Accessor for the step executions.
 	 * @return the step executions that were registered.
 	 */
 	public Collection<StepExecution> getStepExecutions() {
-		return List.copyOf(stepExecutions);
-	}
-
-	/**
-	 * Register a step execution with the current job execution.
-	 * @param stepName the name of the step the new execution is associated with.
-	 * @return an empty {@link StepExecution} associated with this {@code JobExecution}.
-	 */
-	public StepExecution createStepExecution(String stepName) {
-		StepExecution stepExecution = new StepExecution(stepName, this);
-		this.stepExecutions.add(stepExecution);
-		return stepExecution;
+		return List.copyOf(this.stepExecutions);
 	}
 
 	/**
@@ -305,11 +244,19 @@ public void setCreateTime(LocalDateTime createTime) {
 	}
 
 	/**
-	 * Add a step execution from an existing instance.
+	 * Add a step execution.
 	 * @param stepExecution The {@code stepExecution} execution to be added.
 	 */
 	public void addStepExecution(StepExecution stepExecution) {
-		stepExecutions.add(stepExecution);
+		this.stepExecutions.add(stepExecution);
+	}
+
+	/**
+	 * Add some step executions.
+	 * @param stepExecutions The step executions to add to the current list.
+	 */
+	public void addStepExecutions(List<StepExecution> stepExecutions) {
+		this.stepExecutions.addAll(stepExecutions);
 	}
 
 	/**
@@ -364,33 +311,11 @@ public synchronized List<Throwable> getAllFailureExceptions() {
 		return new ArrayList<>(allExceptions);
 	}
 
-	/**
-	 * Deserialize and ensure transient fields are re-instantiated when read back.
-	 * @param stream instance of {@link ObjectInputStream}.
-	 * @throws IOException if an error occurs during read.
-	 * @throws ClassNotFoundException thrown if the class is not found.
-	 */
-	private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException {
-		stream.defaultReadObject();
-		failureExceptions = new ArrayList<>();
-	}
-
 	@Override
 	public String toString() {
 		return super.toString() + String.format(
 				", startTime=%s, endTime=%s, lastUpdated=%s, status=%s, exitStatus=%s, job=[%s], jobParameters=[%s]",
 				startTime, endTime, lastUpdated, status, exitStatus, jobInstance, jobParameters);
 	}
 
-	/**
-	 * Add some step executions. For internal use only.
-	 * @param stepExecutions The step executions to add to the current list.
-	 */
-	public void addStepExecutions(List<StepExecution> stepExecutions) {
-		if (stepExecutions != null) {
-			this.stepExecutions.removeAll(stepExecutions);
-			this.stepExecutions.addAll(stepExecutions);
-		}
-	}
-
 }