Polishing.

Extract SequenceEntityCallbackDelegate from IdGeneratingBeforeSaveCallback. Renameto IdGeneratingEntityCallback and move callback to convert package.

Align return values and associate generated sequence value with the entity. Fix test. Add ticket references to tests.

Extract documentation partials.

See #1955
Original pull request: #2028

Author: mp911de

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

@@ -48,22 +48,22 @@ public IdGeneratingEntityCallback(
 	@Override
 	public Object onBeforeSave(Object aggregate, MutableAggregateChange<Object> aggregateChange) {
 
-		Assert.notNull(aggregate, "aggregate must not be null");
+		Assert.notNull(aggregate, "Aggregate must not be null");
 
 		RelationalPersistentEntity<?> entity = context.getRequiredPersistentEntity(aggregate.getClass());
 
 		if (!entity.hasIdProperty()) {
 			return aggregate;
 		}
 
-		RelationalPersistentProperty idProperty = entity.getRequiredIdProperty();
+		RelationalPersistentProperty property = entity.getRequiredIdProperty();
 		PersistentPropertyAccessor<Object> accessor = entity.getPropertyAccessor(aggregate);
 
-		if (!entity.isNew(aggregate) || delegate.hasValue(idProperty, accessor) || !idProperty.hasSequence()) {
+		if (!entity.isNew(aggregate) || delegate.hasValue(property, accessor) || !property.hasSequence()) {
 			return aggregate;
 		}
 
-		delegate.generateSequenceValue(idProperty, accessor);
+		delegate.generateSequenceValue(property, accessor);
 
 		return accessor.getBean();
 	}

spring-data-r2dbc/src/main/java/org/springframework/data/r2dbc/config/AbstractR2dbcConfiguration.java

@@ -33,13 +33,13 @@
 import org.springframework.core.convert.converter.Converter;
 import org.springframework.data.convert.CustomConversions;
 import org.springframework.data.convert.CustomConversions.StoreConversions;
+import org.springframework.data.r2dbc.convert.IdGeneratingEntityCallback;
 import org.springframework.data.r2dbc.convert.MappingR2dbcConverter;
 import org.springframework.data.r2dbc.convert.R2dbcConverter;
 import org.springframework.data.r2dbc.convert.R2dbcCustomConversions;
 import org.springframework.data.r2dbc.core.DefaultReactiveDataAccessStrategy;
 import org.springframework.data.r2dbc.core.R2dbcEntityTemplate;
 import org.springframework.data.r2dbc.core.ReactiveDataAccessStrategy;
-import org.springframework.data.r2dbc.core.mapping.IdGeneratingBeforeSaveCallback;
 import org.springframework.data.r2dbc.dialect.DialectResolver;
 import org.springframework.data.r2dbc.dialect.R2dbcDialect;
 import org.springframework.data.r2dbc.mapping.R2dbcMappingContext;
@@ -185,14 +185,16 @@ public R2dbcMappingContext r2dbcMappingContext(Optional<NamingStrategy> namingSt
 	}
 
 	/**
-	 * Register a {@link IdGeneratingBeforeSaveCallback} using
+	 * Register a {@link IdGeneratingEntityCallback} using
 	 * {@link #r2dbcMappingContext(Optional, R2dbcCustomConversions, RelationalManagedTypes)} and
-	 * {@link #databaseClient()}
+	 * {@link #databaseClient()}.
+	 *
+	 * @since 3.5
 	 */
 	@Bean
-	public IdGeneratingBeforeSaveCallback idGeneratingBeforeSaveCallback(
+	public IdGeneratingEntityCallback idGeneratingBeforeSaveCallback(
 			RelationalMappingContext relationalMappingContext, DatabaseClient databaseClient) {
-		return new IdGeneratingBeforeSaveCallback(relationalMappingContext, getDialect(lookupConnectionFactory()),
+		return new IdGeneratingEntityCallback(relationalMappingContext, getDialect(lookupConnectionFactory()),
 				databaseClient);
 	}
 

spring-data-r2dbc/src/main/java/org/springframework/data/r2dbc/convert/IdGeneratingEntityCallback.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright 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.
+ * 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.r2dbc.convert;
+
+import reactor.core.publisher.Mono;
+
+import org.springframework.data.mapping.PersistentPropertyAccessor;
+import org.springframework.data.mapping.context.MappingContext;
+import org.springframework.data.r2dbc.dialect.R2dbcDialect;
+import org.springframework.data.r2dbc.mapping.OutboundRow;
+import org.springframework.data.r2dbc.mapping.event.BeforeSaveCallback;
+import org.springframework.data.relational.core.mapping.RelationalPersistentEntity;
+import org.springframework.data.relational.core.mapping.RelationalPersistentProperty;
+import org.springframework.data.relational.core.sql.SqlIdentifier;
+import org.springframework.r2dbc.core.DatabaseClient;
+import org.springframework.util.Assert;
+
+/**
+ * Callback for generating identifier values through a database sequence.
+ *
+ * @author Mikhail Polivakha
+ * @author Mark Paluch
+ * @since 3.5
+ */
+public class IdGeneratingEntityCallback implements BeforeSaveCallback<Object> {
+
+	private final MappingContext<RelationalPersistentEntity<?>, ? extends RelationalPersistentProperty> context;
+	private final SequenceEntityCallbackDelegate delegate;
+
+	public IdGeneratingEntityCallback(
+			MappingContext<RelationalPersistentEntity<?>, ? extends RelationalPersistentProperty> context,
+			R2dbcDialect dialect,
+			DatabaseClient databaseClient) {
+
+		this.context = context;
+		this.delegate = new SequenceEntityCallbackDelegate(dialect, databaseClient);
+	}
+
+	@Override
+	public Mono<Object> onBeforeSave(Object entity, OutboundRow row, SqlIdentifier table) {
+
+		Assert.notNull(entity, "Entity must not be null");
+
+		RelationalPersistentEntity<?> persistentEntity = context.getRequiredPersistentEntity(entity.getClass());
+
+		if (!persistentEntity.hasIdProperty()) {
+			return Mono.just(entity);
+		}
+
+		RelationalPersistentProperty property = persistentEntity.getRequiredIdProperty();
+		PersistentPropertyAccessor<Object> accessor = persistentEntity.getPropertyAccessor(entity);
+
+		if (!persistentEntity.isNew(entity) || delegate.hasValue(property, accessor) || !property.hasSequence()) {
+			return Mono.just(entity);
+		}
+
+		Mono<Object> idGenerator = delegate.generateSequenceValue(property, row, accessor);
+
+		return idGenerator.defaultIfEmpty(entity);
+	}
+
+}

spring-data-r2dbc/src/main/java/org/springframework/data/r2dbc/convert/SequenceEntityCallbackDelegate.java

@@ -0,0 +1,108 @@
+/*
+ * Copyright 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.
+ * 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.r2dbc.convert;
+
+import reactor.core.publisher.Mono;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+import org.springframework.data.mapping.PersistentProperty;
+import org.springframework.data.mapping.PersistentPropertyAccessor;
+import org.springframework.data.r2dbc.mapping.OutboundRow;
+import org.springframework.data.relational.core.dialect.Dialect;
+import org.springframework.data.relational.core.mapping.RelationalPersistentProperty;
+import org.springframework.data.relational.core.sql.SqlIdentifier;
+import org.springframework.data.util.ReflectionUtils;
+import org.springframework.r2dbc.core.DatabaseClient;
+import org.springframework.r2dbc.core.Parameter;
+import org.springframework.util.ClassUtils;
+import org.springframework.util.NumberUtils;
+
+/**
+ * Support class for generating identifier values through a database sequence.
+ *
+ * @author Mikhail Polivakha
+ * @author Mark Paluch
+ * @since 3.5
+ * @see org.springframework.data.relational.core.mapping.Sequence
+ */
+class SequenceEntityCallbackDelegate {
+
+	private static final Log LOG = LogFactory.getLog(SequenceEntityCallbackDelegate.class);
+
+	private final Dialect dialect;
+	private final DatabaseClient databaseClient;
+
+	public SequenceEntityCallbackDelegate(Dialect dialect, DatabaseClient databaseClient) {
+		this.dialect = dialect;
+		this.databaseClient = databaseClient;
+	}
+
+	@SuppressWarnings("unchecked")
+	protected Mono<Object> generateSequenceValue(RelationalPersistentProperty property, OutboundRow row,
+			PersistentPropertyAccessor<Object> accessor) {
+
+		Class<?> targetType = ClassUtils.resolvePrimitiveIfNecessary(property.getType());
+
+		return getSequenceValue(property).map(it -> {
+
+			Object sequenceValue = it;
+			if (sequenceValue instanceof Number && Number.class.isAssignableFrom(targetType)) {
+				sequenceValue = NumberUtils.convertNumberToTargetClass((Number) sequenceValue,
+						(Class<? extends Number>) targetType);
+			}
+
+			row.append(property.getColumnName(), Parameter.from(sequenceValue));
+			accessor.setProperty(property, sequenceValue);
+
+			return accessor.getBean();
+		});
+	}
+
+	protected boolean hasValue(PersistentProperty<?> property, PersistentPropertyAccessor<Object> propertyAccessor) {
+
+		Object identifier = propertyAccessor.getProperty(property);
+
+		if (property.getType().isPrimitive()) {
+
+			Object primitiveDefault = ReflectionUtils.getPrimitiveDefault(property.getType());
+			return !primitiveDefault.equals(identifier);
+		}
+
+		return identifier != null;
+	}
+
+	private Mono<Object> getSequenceValue(RelationalPersistentProperty property) {
+
+		SqlIdentifier sequence = property.getSequence();
+
+		if (sequence != null && !dialect.getIdGeneration().sequencesSupported()) {
+			LOG.warn("""
+					Entity type '%s' is marked for sequence usage but configured dialect '%s'
+					does not support sequences. Falling back to identity columns.
+					""".formatted(property.getOwner().getType(), ClassUtils.getQualifiedName(dialect.getClass())));
+			return Mono.empty();
+		}
+
+		String sql = dialect.getIdGeneration().createSequenceQuery(sequence);
+		return databaseClient //
+				.sql(sql) //
+				.map((r, rowMetadata) -> r.get(0)) //
+				.one();
+	}
+
+}