Polishing.

Refactor BinaryOperation to InfixOperation, add static factory method for consistent creation, tweak Javadoc.

See #2320
Original pull request: #2321

Author: mp911de

spring-data-jdbc/src/main/java/org/springframework/data/jdbc/core/convert/RowDocumentExtractorSupport.java

@@ -16,13 +16,13 @@
 package org.springframework.data.jdbc.core.convert;
 
 import java.util.ArrayList;
-import java.util.Comparator;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.TreeMap;
 
 import org.jspecify.annotations.Nullable;
+
 import org.springframework.data.mapping.MappingException;
 import org.springframework.data.relational.core.mapping.AggregatePath;
 import org.springframework.data.relational.core.mapping.RelationalMappingContext;
@@ -491,26 +491,34 @@ private abstract static class CollectionContainer {
 
 	private static class ListContainer extends CollectionContainer {
 
-		private final Map<Number, Object> list = new TreeMap<>(Comparator.comparing(Number::longValue));
+		private final Map<Integer, @Nullable Object> list = new TreeMap<>();
+		private @Nullable Exception addException;
 
 		@Override
 		public void add(Object key, @Nullable Object value) {
-			list.put(((Number) key).intValue(), value);
+			int index = ((Number) key).intValue();
+			if (index < 0 && addException == null) {
+				addException = new MappingException("Can't add negative indices (%d)".formatted(index));
+			}
+			list.put(index, value);
 		}
 
 		@Override
 		public List<@Nullable Object> get() {
 
 			List<@Nullable Object> result = new ArrayList<>(list.size());
-
 			list.forEach((index, o) -> {
 
-				int intValue = index.intValue();
-				if (intValue < 0) {
-					throw new MappingException("Can't build a List with negativ index = " + intValue);
+				if (index < 0) {
+
+					String message = "Can't build a List using negative indices (%d)".formatted(index);
+					if (addException != null) {
+						throw new MappingException(message, addException);
+					}
+					throw new MappingException(message);
 				}
 
-				while (result.size() < intValue) {
+				while (result.size() < index) {
 					result.add(null);
 				}
 

spring-data-jdbc/src/test/java/org/springframework/data/jdbc/core/convert/RowDocumentResultSetExtractorUnitTests.java

@@ -271,11 +271,15 @@ void extractSingleUnorderedListReference() {
 			@Test // GH-2320
 			void failsOnNegativeListIndex() {
 
-				assertThatExceptionOfType(MappingException.class).isThrownBy(() -> //
+				MappingException exception = catchThrowableOfType(MappingException.class, () -> //
 				testerFor(WithList.class).resultSet(rsc -> {
 					rsc.withPaths("id").withKey("withoutIds").withPath("withoutIds.name") //
 							.withRow(1, -1, "Dummy Alfred");
 				}).run(document -> {}));
+
+				assertThat(exception).hasMessage("Can't build a List using negative indices (-1)");
+				assertThat(exception.getCause()).isInstanceOf(MappingException.class)
+						.hasMessage("Can't add negative indices (-1)");
 			}
 		}
 	}

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/BinaryOperation.java

@@ -70,7 +70,7 @@ public static Expression cast(Expression expression, String targetType) {
 	 * {@link Expression}. Otherwise, it creates and returns a {@link TupleExpression} that represents multiple columns as
 	 * a single expression.
 	 *
-	 * @param columns the list of {@link Column}s to include in the expression; must not be {@literal null}.
+	 * @param columns the list of {@link Column}s to include in the expression.
 	 * @return an {@link Expression} corresponding to the input columns: either a single column or a
 	 *         {@link TupleExpression} for multiple columns.
 	 * @since 4.0
@@ -83,12 +83,30 @@ public static Expression of(List<Column> columns) {
 		return new TupleExpression(columns);
 	}
 
-	public static BinaryOperation plus(Expression left, Expression right) {
-		return new BinaryOperation(left, "+", right);
+	/**
+	 * Creates an {@link InfixOperation arithmetic operation} that adds {@code right} to {@code left} using the {@code +}
+	 * operator.
+	 *
+	 * @param left the left-hand operand.
+	 * @param right the right-hand operand.
+	 * @return the addition {@link InfixOperation}.
+	 * @since 4.1.1
+	 */
+	public static InfixOperation plus(Expression left, Expression right) {
+		return InfixOperation.create(left, "+", right);
 	}
 
-	public static BinaryOperation minus(Expression left, Expression right) {
-		return new BinaryOperation(left, "-", right);
+	/**
+	 * Creates an {@link InfixOperation arithmetic operation} that subtracts {@code right} from {@code left} using the
+	 * {@code -} operator.
+	 *
+	 * @param left the left-hand operand.
+	 * @param right the right-hand operand.
+	 * @return the subtraction {@link InfixOperation}.
+	 * @since 4.1.1
+	 */
+	public static InfixOperation minus(Expression left, Expression right) {
+		return InfixOperation.create(left, "-", right);
 	}
 
 	// Utility constructor.

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/Expressions.java

@@ -0,0 +1,118 @@
+/*
+ * Copyright 2026-present 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.relational.core.sql;
+
+import org.springframework.util.Assert;
+
+/**
+ * Represents an infix (two expressions combined with an operator) operation between two {@link Expression}s such as
+ * arithmetic operations {@code a + b} or concatenation {@code a || b}.
+ * <p>
+ * Results in a rendered expression: {@code <left> <operator> <right>} (e.g. {@code col + 4}). For conditional
+ * expressions use {@link Comparison} instead of a raw {@code InfixOperation}.
+ *
+ * @author Jens Schauder
+ * @author Mark Paluch
+ * @since 4.1.1
+ * @see Comparison
+ */
+public class InfixOperation extends AbstractSegment implements Expression {
+
+	private final Expression left;
+	private final String operator;
+	private final Expression right;
+
+	private InfixOperation(Expression left, String operator, Expression right) {
+		super(left, right);
+		this.left = left;
+		this.operator = operator;
+		this.right = right;
+	}
+
+	/**
+	 * Create a new {@link InfixOperation} using {@link Expression}s and an operator.
+	 *
+	 * @param left the left {@link Expression}.
+	 * @param operator the operator.
+	 * @param right the right {@link Expression}.
+	 * @return the {@link InfixOperation} operation.
+	 */
+	public static InfixOperation create(Expression left, String operator, Expression right) {
+
+		Assert.notNull(left, "Left expression must not be null");
+		Assert.notNull(operator, "Operator must not be null");
+		Assert.notNull(right, "Right expression must not be null");
+
+		return new InfixOperation(left, operator, right);
+	}
+
+	public Expression getLeft() {
+		return left;
+	}
+
+	public String getOperator() {
+		return operator;
+	}
+
+	public Expression getRight() {
+		return right;
+	}
+
+	/**
+	 * Creates a new {@code InfixOperation} aliased to {@code alias}.
+	 *
+	 * @param alias must not be {@literal null} or empty.
+	 * @return the new {@code InfixOperation} using the {@code alias}.
+	 * @since 4.1.1
+	 */
+	public InfixOperation as(String alias) {
+		return new AliasedInfixOperation(this, SqlIdentifier.unquoted(alias));
+	}
+
+	/**
+	 * Creates a new {@code InfixOperation} aliased to {@code alias}.
+	 *
+	 * @param alias must not be {@literal null} or empty.
+	 * @return the new {@code InfixOperation} using the {@code alias}.
+	 * @since 4.1.1
+	 */
+	public InfixOperation as(SqlIdentifier alias) {
+		return new AliasedInfixOperation(this, alias);
+	}
+
+	@Override
+	public String toString() {
+		return left + " " + operator + " " + right;
+	}
+
+	private static class AliasedInfixOperation extends InfixOperation implements Aliased {
+
+		private final SqlIdentifier alias;
+
+		AliasedInfixOperation(InfixOperation operation, SqlIdentifier alias) {
+
+			super(operation.left, operation.operator, operation.right);
+			this.alias = alias;
+		}
+
+		@Override
+		public SqlIdentifier getAlias() {
+			return alias;
+		}
+
+	}
+
+}

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/InfixOperation.java

@@ -115,9 +115,9 @@ Delegation enterMatched(Expression segment) {
 			CastVisitor visitor = new CastVisitor(context);
 			partRenderer = visitor;
 			return Delegation.delegateTo(visitor);
-		} else if (segment instanceof BinaryOperation) {
+		} else if (segment instanceof InfixOperation) {
 
-			BinaryOperationVisitor visitor = new BinaryOperationVisitor(context);
+			InfixOperationVisitor visitor = new InfixOperationVisitor(context);
 			partRenderer = visitor;
 			return Delegation.delegateTo(visitor);
 		} else if (segment instanceof CaseExpression) {

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/render/ExpressionVisitor.java

@@ -18,29 +18,29 @@
 import java.util.StringJoiner;
 
 import org.jspecify.annotations.Nullable;
-import org.springframework.data.relational.core.sql.BinaryOperation;
+import org.springframework.data.relational.core.sql.InfixOperation;
 import org.springframework.data.relational.core.sql.Visitable;
 import org.springframework.util.Assert;
 
 /**
- * Renders a {@link BinaryOperation} by delegating to an {@link ExpressionVisitor} for each operand and joining the
+ * Renders a {@link InfixOperation} by delegating to an {@link ExpressionVisitor} for each operand and joining the
  * rendered parts with the operator.
  *
  * @author Jens Schauder
- * @since 4.2
+ * @since 4.1.1
  */
-class BinaryOperationVisitor extends TypedSubtreeVisitor<BinaryOperation> implements PartRenderer {
+class InfixOperationVisitor extends TypedSubtreeVisitor<InfixOperation> implements PartRenderer {
 
 	private final RenderContext context;
 	private @Nullable StringJoiner joiner;
 	private @Nullable ExpressionVisitor expressionVisitor;
 
-	BinaryOperationVisitor(RenderContext context) {
+	InfixOperationVisitor(RenderContext context) {
 		this.context = context;
 	}
 
 	@Override
-	Delegation enterMatched(BinaryOperation operation) {
+	Delegation enterMatched(InfixOperation operation) {
 
 		joiner = new StringJoiner(" " + operation.getOperator() + " ");
 		return super.enterMatched(operation);