DATAMONGO-2400 - Consider java.time.Instant a store supported native type and add configuration options for other java.time types.

We now use the MongoDB Java driver InstantCodec instead of a dedicated converter. Other java.time types like LocalDate use a different zone offset when writing values which can lead to unexpected behavior. Therefore we added configuration options to MongoCustomConversions that allow to tell the conversion sub system which approach to use when writing those kind of types.

Author: christophstrobl

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/config/MongoConfigurationSupport.java

@@ -31,6 +31,7 @@
 import org.springframework.data.mapping.model.FieldNamingStrategy;
 import org.springframework.data.mapping.model.PropertyNameFieldNamingStrategy;
 import org.springframework.data.mongodb.core.convert.MongoCustomConversions;
+import org.springframework.data.mongodb.core.convert.MongoCustomConversions.MongoConverterConfigurationAdapter;
 import org.springframework.data.mongodb.core.mapping.Document;
 import org.springframework.data.mongodb.core.mapping.MongoMappingContext;
 import org.springframework.util.ClassUtils;
@@ -88,14 +89,35 @@ public MongoMappingContext mongoMappingContext() throws ClassNotFoundException {
 
 	/**
 	 * Register custom {@link Converter}s in a {@link CustomConversions} object if required. These
-	 * {@link CustomConversions} will be registered with the {@link #mappingMongoConverter()} and
-	 * {@link #mongoMappingContext()}. Returns an empty {@link MongoCustomConversions} instance by default.
+	 * {@link CustomConversions} will be registered with the
+	 * {@link org.springframework.data.mongodb.core.convert.MappingMongoConverter} and {@link #mongoMappingContext()}.
+	 * Returns an empty {@link MongoCustomConversions} instance by default. <br />
+	 * <strong>NOTE:</strong> Use {@link #customConversionsConfiguration(MongoConverterConfigurationAdapter)} to configure
+	 * MongoDB native simple types and register custom {@link Converter converters}.
 	 *
 	 * @return must not be {@literal null}.
 	 */
 	@Bean
 	public CustomConversions customConversions() {
-		return new MongoCustomConversions(Collections.emptyList());
+		return new MongoCustomConversions(this::customConversionsConfiguration);
+	}
+
+	/**
+	 * Configuration hook for {@link MongoCustomConversions} creation.
+	 *
+	 * @param converterConfigurationAdapter never {@literal null}.
+	 * @since 2.3
+	 */
+	protected void customConversionsConfiguration(MongoConverterConfigurationAdapter converterConfigurationAdapter) {
+
+		/*
+		 * In case you want to use the MongoDB Java Driver native Codecs for java.time types instead of the converters SpringData 
+		 * ships with, then you may want to call the following here.
+		 *     
+		 * converterConfigurationAdapter.useNativeDriverJavaTimeCodecs() 
+		 * 
+		 * But please, be careful! LocalDate, LocalTime and LocalDateTime will be stored with different values by doing so.
+		 */
 	}
 
 	/**

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

@@ -15,26 +15,42 @@
  */
 package org.springframework.data.mongodb.core.convert;
 
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.LocalTime;
+import java.time.ZoneId;
+import java.time.ZoneOffset;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collection;
 import java.util.Collections;
+import java.util.Date;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Locale;
 import java.util.Set;
+import java.util.function.Consumer;
+import java.util.stream.Collectors;
 
 import org.springframework.core.convert.TypeDescriptor;
+import org.springframework.core.convert.converter.Converter;
+import org.springframework.core.convert.converter.ConverterFactory;
 import org.springframework.core.convert.converter.GenericConverter;
+import org.springframework.core.convert.converter.GenericConverter.ConvertiblePair;
 import org.springframework.data.convert.JodaTimeConverters;
 import org.springframework.data.convert.WritingConverter;
+import org.springframework.data.mapping.model.SimpleTypeHolder;
 import org.springframework.data.mongodb.core.mapping.MongoSimpleTypes;
 import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
 
 /**
  * Value object to capture custom conversion. {@link MongoCustomConversions} also act as factory for
  * {@link org.springframework.data.mapping.model.SimpleTypeHolder}
  *
  * @author Mark Paluch
+ * @author Christoph Strobl
  * @since 2.0
  * @see org.springframework.data.convert.CustomConversions
  * @see org.springframework.data.mapping.model.SimpleTypeHolder
@@ -71,7 +87,30 @@ public class MongoCustomConversions extends org.springframework.data.convert.Cus
 	 * @param converters must not be {@literal null}.
 	 */
 	public MongoCustomConversions(List<?> converters) {
-		super(STORE_CONVERSIONS, converters);
+
+		this(converterConfigurationAdapter -> {
+
+			converterConfigurationAdapter.useSpringDataJavaTimeCodecs();
+			converterConfigurationAdapter.registerConverters(converters);
+		});
+	}
+
+	/**
+	 * Functional style {@link org.springframework.data.convert.CustomConversions} creation giving users a convenient way
+	 * of configuring store specific capabilities by providing deferred hooks to what will be configured when creating the
+	 * {@link org.springframework.data.convert.CustomConversions#CustomConversions(ConverterConfiguration) instance}.
+	 *
+	 * @param conversionConfiguration must not be {@literal null}.
+	 * @since 2.3
+	 */
+	public MongoCustomConversions(Consumer<MongoConverterConfigurationAdapter> conversionConfiguration) {
+
+		super(() -> {
+
+			MongoConverterConfigurationAdapter adapter = new MongoConverterConfigurationAdapter();
+			conversionConfiguration.accept(adapter);
+			return adapter.createConverterConfiguration();
+		});
 	}
 
 	@WritingConverter
@@ -99,4 +138,158 @@ public Object convert(@Nullable Object source, TypeDescriptor sourceType, TypeDe
 			return source != null ? source.toString() : null;
 		}
 	}
+
+	/**
+	 * {@link MongoConverterConfigurationAdapter} encapsulates creation of
+	 * {@link org.springframework.data.convert.CustomConversions.ConverterConfiguration} with MongoDB specifics.
+	 *
+	 * @author Christoph Strobl
+	 * @since 2.3
+	 */
+	public static class MongoConverterConfigurationAdapter {
+
+		/**
+		 * List of {@literal java.time} types having different representation when rendered via the native
+		 * {@link org.bson.codecs.Codec} than the Spring Data {@link Converter}.
+		 */
+		private static final List<Class<?>> JAVA_DRIVER_TIME_SIMPLE_TYPES = Arrays.asList(LocalDate.class, LocalTime.class,
+				LocalDateTime.class);
+
+		private boolean useNativeDriverJavaTimeCodecs = false;
+		private List<Object> customConverters = new ArrayList<>();
+
+		/**
+		 * Set wether or not to use the native MongoDB Java Driver {@link org.bson.codecs.Codec codes} for
+		 * {@link org.bson.codecs.jsr310.LocalDateCodec LocalDate}, {@link org.bson.codecs.jsr310.LocalTimeCodec LocalTime}
+		 * and {@link org.bson.codecs.jsr310.LocalDateTimeCodec LocalDateTime} using a {@link ZoneOffset#UTC}.
+		 *
+		 * @param useNativeDriverJavaTimeCodecs
+		 * @return this.
+		 */
+		public MongoConverterConfigurationAdapter useNativeDriverJavaTimeCodecs(boolean useNativeDriverJavaTimeCodecs) {
+
+			this.useNativeDriverJavaTimeCodecs = useNativeDriverJavaTimeCodecs;
+			return this;
+		}
+
+		/**
+		 * Use the native MongoDB Java Driver {@link org.bson.codecs.Codec codes} for
+		 * {@link org.bson.codecs.jsr310.LocalDateCodec LocalDate}, {@link org.bson.codecs.jsr310.LocalTimeCodec LocalTime}
+		 * and {@link org.bson.codecs.jsr310.LocalDateTimeCodec LocalDateTime} using a {@link ZoneOffset#UTC}.
+		 *
+		 * @return this.
+		 * @see #useNativeDriverJavaTimeCodecs(boolean)
+		 */
+		public MongoConverterConfigurationAdapter useNativeDriverJavaTimeCodecs() {
+			return useNativeDriverJavaTimeCodecs(true);
+		}
+
+		/**
+		 * Use SpringData {@link Converter Jsr310 converters} for
+		 * {@link org.springframework.data.convert.Jsr310Converters.LocalDateToDateConverter LocalDate},
+		 * {@link org.springframework.data.convert.Jsr310Converters.LocalTimeToDateConverter LocalTime} and
+		 * {@link org.springframework.data.convert.Jsr310Converters.LocalDateTimeToDateConverter LocalDateTime} using the
+		 * {@link ZoneId#systemDefault()}.
+		 *
+		 * @return this.
+		 * @see #useNativeDriverJavaTimeCodecs(boolean)
+		 */
+		public MongoConverterConfigurationAdapter useSpringDataJavaTimeCodecs() {
+			return useNativeDriverJavaTimeCodecs(false);
+		}
+
+		/**
+		 * Add a custom {@link Converter} implementation.
+		 *
+		 * @param converter must not be {@literal null}.
+		 * @return this.
+		 */
+		public MongoConverterConfigurationAdapter registerConverter(Converter<?, ?> converter) {
+
+			Assert.notNull(converter, "Converter must not be null!");
+			customConverters.add(converter);
+			return this;
+		}
+
+		/**
+		 * Add a custom {@link ConverterFactory} implementation.
+		 *
+		 * @param converterFactory must not be {@literal null}.
+		 * @return this.
+		 */
+		public MongoConverterConfigurationAdapter registerConverterFactory(ConverterFactory<?, ?> converterFactory) {
+
+			Assert.notNull(converterFactory, "ConverterFactory must not be null!");
+			customConverters.add(converterFactory);
+			return this;
+		}
+
+		/**
+		 * Add {@link Converter converters}, {@link ConverterFactory factories}, ...
+		 *
+		 * @param converters must not be {@literal null} nor contain {@literal null} values.
+		 * @return this.
+		 */
+		public MongoConverterConfigurationAdapter registerConverters(Collection<?> converters) {
+
+			Assert.noNullElements(converters, "Converters must not be null nor contain null values!");
+			customConverters.addAll(converters);
+			return this;
+		}
+
+		ConverterConfiguration createConverterConfiguration() {
+
+			if (!useNativeDriverJavaTimeCodecs) {
+				return new ConverterConfiguration(STORE_CONVERSIONS, this.customConverters);
+			}
+
+			/*
+			 * We need to have those converters using UTC as the default ones would go on with the systemDefault.
+			 */
+			List<Object> converters = new ArrayList<>();
+			converters.add(DateToUtcLocalDateConverter.INSTANCE);
+			converters.add(DateToUtcLocalTimeConverter.INSTANCE);
+			converters.add(DateToUtcLocalDateTimeConverter.INSTANCE);
+			converters.addAll(STORE_CONVERTERS);
+
+			/*
+			 * Right, good catch! We also need to make sure to remove default writing converters for java.time types.
+			 */
+			List<ConvertiblePair> skipConverterRegistrationFor = JAVA_DRIVER_TIME_SIMPLE_TYPES.stream() //
+					.map(it -> new ConvertiblePair(it, Date.class)) //
+					.collect(Collectors.toList()); //
+
+			StoreConversions storeConversions = StoreConversions
+					.of(new SimpleTypeHolder(new HashSet<>(JAVA_DRIVER_TIME_SIMPLE_TYPES), MongoSimpleTypes.HOLDER), converters);
+
+			return new ConverterConfiguration(storeConversions, this.customConverters, skipConverterRegistrationFor);
+		}
+
+		private enum DateToUtcLocalDateTimeConverter implements Converter<Date, LocalDateTime> {
+			INSTANCE;
+
+			@Override
+			public LocalDateTime convert(Date source) {
+				return LocalDateTime.ofInstant(Instant.ofEpochMilli(source.getTime()), ZoneId.of("UTC"));
+			}
+		}
+
+		private enum DateToUtcLocalTimeConverter implements Converter<Date, LocalTime> {
+			INSTANCE;
+
+			@Override
+			public LocalTime convert(Date source) {
+				return DateToUtcLocalDateTimeConverter.INSTANCE.convert(source).toLocalTime();
+			}
+		}
+
+		private enum DateToUtcLocalDateConverter implements Converter<Date, LocalDate> {
+			INSTANCE;
+
+			@Override
+			public LocalDate convert(Date source) {
+				return DateToUtcLocalDateTimeConverter.INSTANCE.convert(source).toLocalDate();
+			}
+		}
+	}
 }

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/mapping/MongoSimpleTypes.java

@@ -16,6 +16,7 @@
 package org.springframework.data.mongodb.core.mapping;
 
 import java.math.BigInteger;
+import java.time.Instant;
 import java.util.Collections;
 import java.util.HashSet;
 import java.util.Set;
@@ -71,6 +72,7 @@ public abstract class MongoSimpleTypes {
 		simpleTypes.add(Pattern.class);
 		simpleTypes.add(Symbol.class);
 		simpleTypes.add(UUID.class);
+		simpleTypes.add(Instant.class);
 
 		simpleTypes.add(BsonBinary.class);
 		simpleTypes.add(BsonBoolean.class);