Make sure big number representation allows for backwards compatibility.

Extend configuration options in a way that allows to register different conversion options for numeric values so users can recreate the 4.x default behaviour using String as default while honoring field specific configuration via the targetType attribute of the Field Annotation.

Author: christophstrobl

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/convert/MongoCustomConversions.java

@@ -155,7 +155,7 @@ public static class MongoConverterConfigurationAdapter {
 				LocalDateTime.class);
 
 		private boolean useNativeDriverJavaTimeCodecs = false;
-		private @Nullable BigDecimalRepresentation bigDecimals;
+		private BigDecimalRepresentation @Nullable [] bigDecimals;
 		private final List<Object> customConverters = new ArrayList<>();
 
 		private final PropertyValueConversions internalValueConversion = PropertyValueConversions.simple(it -> {});
@@ -312,14 +312,14 @@ public MongoConverterConfigurationAdapter useSpringDataJavaTimeCodecs() {
 		 * Configures the representation to for {@link java.math.BigDecimal} and {@link java.math.BigInteger} values in
 		 * MongoDB. Defaults to {@link BigDecimalRepresentation#DECIMAL128}.
 		 *
-		 * @param representation the representation to use.
+		 * @param representations ordered list of representations to use (first one is default)
 		 * @return this.
 		 * @since 4.5
 		 */
-		public MongoConverterConfigurationAdapter bigDecimal(BigDecimalRepresentation representation) {
+		public MongoConverterConfigurationAdapter bigDecimal(BigDecimalRepresentation... representations) {
 
-			Assert.notNull(representation, "BigDecimalDataType must not be null");
-			this.bigDecimals = representation;
+			Assert.notEmpty(representations, "BigDecimalDataType must not be null");
+			this.bigDecimals = representations;
 			return this;
 		}
 
@@ -375,13 +375,15 @@ ConverterConfiguration createConverterConfiguration() {
 			List<Object> storeConverters = new ArrayList<>(STORE_CONVERTERS.size() + 10);
 
 			if (bigDecimals != null) {
-				switch (bigDecimals) {
-					case STRING -> storeConverters.addAll(MongoConverters.getBigNumberStringConverters());
-					case DECIMAL128 -> storeConverters.addAll(MongoConverters.getBigNumberDecimal128Converters());
+				for (BigDecimalRepresentation representation : bigDecimals) {
+					switch (representation) {
+						case STRING -> storeConverters.addAll(MongoConverters.getBigNumberStringConverters());
+						case DECIMAL128 -> storeConverters.addAll(MongoConverters.getBigNumberDecimal128Converters());
+					}
 				}
 			} else if (LOGGER.isInfoEnabled()) {
 				LOGGER.info(
-						"No BigDecimal/BigInteger representation set. Choose [STRING] or [DECIMAL128] to store values in desired format.");
+						"No BigDecimal/BigInteger representation set. Choose [DECIMAL128] and/or [String] to store values in desired format.");
 			}
 
 			if (useNativeDriverJavaTimeCodecs) {

spring-data-mongodb/src/test/java/org/springframework/data/mongodb/core/convert/MappingMongoConverterUnitTests.java

@@ -15,10 +15,22 @@
  */
 package org.springframework.data.mongodb.core.convert;
 
-import static java.time.ZoneId.*;
-import static org.mockito.Mockito.*;
-import static org.springframework.data.mongodb.core.DocumentTestUtils.*;
-import static org.springframework.data.mongodb.test.util.Assertions.*;
+import static java.time.ZoneId.systemDefault;
+import static org.mockito.Mockito.any;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.spy;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+import static org.springframework.data.mongodb.core.DocumentTestUtils.assertTypeHint;
+import static org.springframework.data.mongodb.core.DocumentTestUtils.getAsDocument;
+import static org.springframework.data.mongodb.test.util.Assertions.assertThat;
+import static org.springframework.data.mongodb.test.util.Assertions.assertThatExceptionOfType;
+import static org.springframework.data.mongodb.test.util.Assertions.assertThatThrownBy;
+import static org.springframework.data.mongodb.test.util.Assertions.fail;
 
 import java.math.BigDecimal;
 import java.math.BigInteger;
@@ -53,7 +65,6 @@
 import org.mockito.Mock;
 import org.mockito.Mockito;
 import org.mockito.junit.jupiter.MockitoExtension;
-
 import org.springframework.aop.framework.ProxyFactory;
 import org.springframework.beans.ConversionNotSupportedException;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -62,6 +73,7 @@
 import org.springframework.beans.factory.support.DefaultListableBeanFactory;
 import org.springframework.context.ApplicationContext;
 import org.springframework.context.support.StaticApplicationContext;
+import org.springframework.core.convert.ConversionFailedException;
 import org.springframework.core.convert.ConverterNotFoundException;
 import org.springframework.core.convert.converter.Converter;
 import org.springframework.data.annotation.Id;
@@ -2176,6 +2188,61 @@ void mapsBigDecimalToDecimal128WhenAnnotatedWithFieldTargetType() {
 		assertThat(target.get("bigDecimal")).isEqualTo(new Decimal128(source.bigDecimal));
 	}
 
+	@Test // GH-5037
+	@SuppressWarnings("deprecation")
+	void mapsBigIntegerToDecimal128WhenAnnotatedWithFieldTargetTypeWhenDefaultConversionIsSetToString() {
+
+		converter = createConverter(BigDecimalRepresentation.STRING, BigDecimalRepresentation.DECIMAL128);
+
+		WithExplicitTargetTypes source = new WithExplicitTargetTypes();
+		source.bigDecimal = BigDecimal.valueOf(3.14159D);
+
+		org.bson.Document target = new org.bson.Document();
+		converter.write(source, target);
+
+		assertThat(target.get("bigDecimal")).isEqualTo(new Decimal128(source.bigDecimal));
+	}
+
+	@Test // GH-5037
+	@SuppressWarnings("deprecation")
+	void mapsBigIntegerToStringWhenNotAnnotatedWithFieldTargetTypeAndDefaultConversionIsSetToString() {
+
+		converter = createConverter(BigDecimalRepresentation.STRING, BigDecimalRepresentation.DECIMAL128);
+
+		BigDecimalContainer source = new BigDecimalContainer();
+		source.value = BigDecimal.valueOf(3.14159D);
+		org.bson.Document target = new org.bson.Document();
+		converter.write(source, target);
+		assertThat(target.get("value")).isInstanceOf(String.class);
+	}
+
+	@Test // GH-5037
+	void mapsBigIntegerToStringWhenAnnotatedWithFieldTargetTypeEvenWhenDefaultConverterIsSetToDecimal128() {
+
+		converter = createConverter(BigDecimalRepresentation.DECIMAL128);
+
+		WithExplicitTargetTypes source = new WithExplicitTargetTypes();
+		source.bigIntegerAsString = BigInteger.TWO;
+
+		org.bson.Document target = new org.bson.Document();
+		converter.write(source, target);
+
+		assertThat(target.get("bigIntegerAsString")).isEqualTo(source.bigIntegerAsString.toString());
+	}
+
+	@Test // GH-5037
+	void explicitBigNumberConversionErrorsIfConverterNotRegistered() {
+
+		converter = createConverter(BigDecimalRepresentation.STRING);
+
+		WithExplicitTargetTypes source = new WithExplicitTargetTypes();
+		source.bigInteger = BigInteger.TWO;
+
+		org.bson.Document target = new org.bson.Document();
+
+		assertThatExceptionOfType(ConversionFailedException.class).isThrownBy(() -> converter.write(source, target));
+	}
+
 	@Test // DATAMONGO-2328
 	void mapsDateToLongWhenAnnotatedWithFieldTargetType() {
 
@@ -3198,7 +3265,6 @@ void beanConverter() {
 								return nativeValue.getString("bar");
 							}
 
-
 							@Override
 							public org.bson.@Nullable Document write(@Nullable String domainValue, MongoConversionContext context) {
 								return new org.bson.Document("bar", domainValue);
@@ -3435,7 +3501,7 @@ void usesStringNumericFormat() {
 	}
 
 	private MappingMongoConverter createConverter(
-			MongoCustomConversions.BigDecimalRepresentation bigDecimalRepresentation) {
+			MongoCustomConversions.BigDecimalRepresentation... bigDecimalRepresentation) {
 
 		MongoCustomConversions conversions = MongoCustomConversions.create(
 				it -> it.registerConverter(new ByteBufferToDoubleHolderConverter()).bigDecimal(bigDecimalRepresentation));
@@ -4108,7 +4174,11 @@ static class WithExplicitTargetTypes {
 		@Field(targetType = FieldType.DECIMAL128) //
 		BigDecimal bigDecimal;
 
-		@Field(targetType = FieldType.DECIMAL128) BigInteger bigInteger;
+		@Field(targetType = FieldType.DECIMAL128) //
+		BigInteger bigInteger;
+
+		@Field(targetType = FieldType.STRING) //
+		BigInteger bigIntegerAsString;
 
 		@Field(targetType = FieldType.INT64) //
 		Date dateAsLong;
@@ -4238,7 +4308,6 @@ public SubTypeOfGenericType convert(org.bson.Document source) {
 	@WritingConverter
 	static class TypeImplementingMapToDocumentConverter implements Converter<TypeImplementingMap, org.bson.Document> {
 
-
 		@Override
 		public org.bson.@Nullable Document convert(TypeImplementingMap source) {
 			return new org.bson.Document("1st", source.val1).append("2nd", source.val2);
@@ -4440,7 +4509,6 @@ enum Converter2 implements MongoValueConverter<String, org.bson.Document> {
 			return value.getString("bar");
 		}
 
-
 		@Override
 		public org.bson.@Nullable Document write(@Nullable String value, MongoConversionContext context) {
 			return new org.bson.Document("bar", value);
@@ -4454,7 +4522,6 @@ static class Converter1 implements MongoValueConverter<String, org.bson.Document
 			return value.getString("foo");
 		}
 
-
 		@Override
 		public org.bson.@Nullable Document write(@Nullable String value, MongoConversionContext context) {
 			return new org.bson.Document("foo", value);

src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc

@@ -40,7 +40,7 @@ XML::
 == BigInteger/BigDecimal Conversion Changes
 
 Spring Data no longer defaults BigInteger/BigDecimal conversion via its configuration support classes.
-In order to persist those values the `BigDecimalRepresentation` hast to be set explicitly.
+In order to persist those values the default `BigDecimalRepresentation` hast to be set explicitly.
 
 [source,java]
 ----
@@ -55,3 +55,6 @@ static class Config extends AbstractMongoClientConfiguration {
     // ...
 }
 ----
+
+Users upgrading from prior versions may choose `BigDecimalRepresentation.STRING` as default.
+Those using`@Field(targetType = FieldType.DECIMAL128)` need to define a combination of representations `configAdapter.bigDecimal(BigDecimalRepresentation.STRING, BigDecimalRepresentation.DECIMAL128)` to set defaulting to String while having the `DECIMAL128` converter being registered for usage with explicit target type configuration.

src/main/antora/modules/ROOT/pages/mongodb/mapping/custom-conversions.adoc

@@ -4,7 +4,7 @@ include::{commons}@data-commons::page$custom-conversions.adoc[]
 == Type based Converter
 
 The most trivial way of influencing the mapping result is by specifying the desired native MongoDB target type via the `@Field` annotation.
-This allows to work with non MongoDB types like `BigDecimal` in the domain model while persisting values in native `org.bson.types.Decimal128` format.
+This allows to work with non MongoDB types like `BigDecimal` in the domain model while persisting values in eg. `String` format.
 
 .Explicit target type mapping
 ====
@@ -33,8 +33,7 @@ public class Payment {
 <1> String _id_ values that represent a valid `ObjectId` are converted automatically. See xref:mongodb/template-crud-operations.adoc#mongo-template.id-handling[How the `_id` Field is Handled in the Mapping Layer]
 for details.
 <2> The desired target type is explicitly defined as `String`.
-Otherwise, the
-`BigDecimal` value would have been turned into a `Decimal128`.
+Otherwise.
 <3> `Date` values are handled by the MongoDB driver itself are stored as `ISODate`.
 ====
 
@@ -113,8 +112,10 @@ To persist `BigDecimal` and `BigInteger` values, Spring Data MongoDB converted v
 This approach had several downsides due to lexical instead of numeric comparison for queries, updates, etc.
 
 With MongoDB Server 3.4, `org.bson.types.Decimal128` offers a native representation for `BigDecimal` and `BigInteger`.
-As of Spring Data MongoDB 5.0. the default representation of those types moved to MongoDB native `org.bson.types.Decimal128`.
-You can still use the to the previous `String` variant by configuring the big decimal representation in `MongoCustomConversions` through `MongoCustomConversions.create(config -> config.bigDecimal(BigDecimalRepresentation.STRING))`.
+As of Spring Data MongoDB 5.0. there no longer is a default representation of those types and conversion needs to be configured explicitly.
+You can register multiple formats, 1st being default, and still retain the previous behaviour by configuring the `BigDecimalRepresentation` in `MongoCustomConversions` through `MongoCustomConversions.create(config -> config.bigDecimal(BigDecimalRepresentation.STRING, BigDecimalRepresentation.DECIMAL128))`.
+This allows you to make use of the explicit storage type format via `@Field(targetType = DECIMAL128)` while keeping default conversion set to String.
+Choosing none of the provided representations is valid as long as those values are no persisted.
 
 [NOTE]
 ====