Add support for property-specific converters.

Closes #1484
Original pull request: #2566.

Author: christophstrobl

src/main/java/org/springframework/data/convert/CustomConversions.java

@@ -33,6 +33,7 @@
 import org.springframework.core.convert.converter.GenericConverter.ConvertiblePair;
 import org.springframework.core.convert.support.GenericConversionService;
 import org.springframework.data.convert.ConverterBuilder.ConverterAware;
+import org.springframework.data.mapping.PersistentProperty;
 import org.springframework.data.mapping.model.SimpleTypeHolder;
 import org.springframework.data.util.Predicates;
 import org.springframework.data.util.Streamable;
@@ -96,6 +97,8 @@ public class CustomConversions {
 	private final Function<ConvertiblePair, Class<?>> getRawWriteTarget = convertiblePair -> getCustomTarget(
 			convertiblePair.getSourceType(), null, writingPairs);
 
+	private PropertyValueConversions propertyValueConversions;
+
 	/**
 	 * @param converterConfiguration the {@link ConverterConfiguration} to apply.
 	 * @since 2.3
@@ -118,6 +121,7 @@ public CustomConversions(ConverterConfiguration converterConfiguration) {
 		this.converters = Collections.unmodifiableList(registeredConverters);
 		this.simpleTypeHolder = new SimpleTypeHolder(customSimpleTypes,
 				converterConfiguration.getStoreConversions().getStoreTypeHolder());
+		this.propertyValueConversions = converterConfiguration.getPropertyValueConversions();
 	}
 
 	/**
@@ -170,6 +174,36 @@ public void registerConvertersIn(ConverterRegistry conversionService) {
 		VavrCollectionConverters.getConvertersToRegister().forEach(it -> registerConverterIn(it, conversionService));
 	}
 
+	/**
+	 * Delegate check if a {@link PropertyValueConverter} for the given {@literal property} is present via
+	 * {@link PropertyValueConversions}.
+	 *
+	 * @param property must not be {@literal null}.
+	 * @return {@literal true} if a specific {@link PropertyValueConverter} is available.
+	 * @see PropertyValueConversions#hasValueConverter(PersistentProperty)
+	 * @since ?
+	 */
+	public boolean hasPropertyValueConverter(PersistentProperty<?> property) {
+		return propertyValueConversions != null ? propertyValueConversions.hasValueConverter(property) : false;
+	}
+
+	/**
+	 * Delegate to obtain the {@link PropertyValueConverter} for the given {@literal property} from
+	 * {@link PropertyValueConversions}.
+	 *
+	 * @param property must not be {@literal null}. param <A> domain specific type
+	 * @param <B> store native type
+	 * @param <C> conversion context type
+	 * @return the suitable {@link PropertyValueConverter} or {@literal null} if none available.
+	 * @see PropertyValueConversions#getValueConverter(PersistentProperty)
+	 * @since ?
+	 */
+	@Nullable
+	public <A, B, C extends PropertyValueConverter.ValueConversionContext> PropertyValueConverter<A, B, C> getPropertyValueConverter(
+			PersistentProperty<?> property) {
+		return propertyValueConversions != null ? propertyValueConversions.getValueConverter(property) : null;
+	}
+
 	/**
 	 * Get all converters and add origin information
 	 *
@@ -862,6 +896,7 @@ protected static class ConverterConfiguration {
 		private final StoreConversions storeConversions;
 		private final List<?> userConverters;
 		private final Predicate<ConvertiblePair> converterRegistrationFilter;
+		private final PropertyValueConversions propertyValueConversions;
 
 		/**
 		 * Create a new ConverterConfiguration holding the given {@link StoreConversions} and user defined converters.
@@ -887,9 +922,16 @@ public ConverterConfiguration(StoreConversions storeConversions, List<?> userCon
 		public ConverterConfiguration(StoreConversions storeConversions, List<?> userConverters,
 				Predicate<ConvertiblePair> converterRegistrationFilter) {
 
+			this(storeConversions, userConverters, converterRegistrationFilter, new SimplePropertyValueConversions());
+		}
+
+		public ConverterConfiguration(StoreConversions storeConversions, List<?> userConverters,
+				Predicate<ConvertiblePair> converterRegistrationFilter, @Nullable PropertyValueConversions propertyValueConversions) {
+
 			this.storeConversions = storeConversions;
 			this.userConverters = new ArrayList<>(userConverters);
 			this.converterRegistrationFilter = converterRegistrationFilter;
+			this.propertyValueConversions = propertyValueConversions;
 		}
 
 		/**
@@ -912,5 +954,14 @@ List<?> getUserConverters() {
 		boolean shouldRegister(ConvertiblePair candidate) {
 			return this.converterRegistrationFilter.test(candidate);
 		}
+
+		/**
+		 * @return the configured {@link PropertyValueConversions} if set, {@literal null} otherwise.
+		 * @since ?
+		 */
+		@Nullable
+		public PropertyValueConversions getPropertyValueConversions() {
+			return this.propertyValueConversions;
+		}
 	}
 }

src/main/java/org/springframework/data/convert/PropertyConverter.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2022 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.convert;
+
+import static java.lang.annotation.ElementType.*;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.data.convert.PropertyValueConverter.ObjectToObjectPropertyValueConverter;
+
+/**
+ * Annotation to define usage of a {@link PropertyValueConverter} to read/write the property.
+ * <p>
+ * Consult the store specific documentation for details and support notes.
+ *
+ * @author Christoph Strobl
+ * @since ?
+ */
+@Target(FIELD)
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+public @interface PropertyConverter {
+
+	/**
+	 * The {@link PropertyValueConverter} type handling the value conversion of the annotated property.
+	 *
+	 * @return the configured {@link PropertyValueConverter}. {@link ObjectToObjectPropertyValueConverter} by default.
+	 */
+	Class<? extends PropertyValueConverter<?, ?, ? extends PropertyValueConverter.ValueConversionContext>> value() default ObjectToObjectPropertyValueConverter.class;
+
+}

src/main/java/org/springframework/data/convert/PropertyValueConversions.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2022 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.convert;
+
+import org.springframework.data.mapping.PersistentProperty;
+import org.springframework.lang.Nullable;
+
+/**
+ * {@link PropertyValueConversions} provides access to {@link PropertyValueConverter converters} that may only be
+ * applied to a specific property. Other than {@link org.springframework.core.convert.converter.Converter converters}
+ * registered in {@link CustomConversions} the property based variants accept and allow returning {@literal null} values
+ * and provide access to a store specific {@link PropertyValueConverter.ValueConversionContext conversion context}.
+ * 
+ * @author Christoph Strobl
+ * @since ?
+ * @currentBook The Desert Prince - Peter V. Brett
+ */
+public interface PropertyValueConversions {
+
+	/**
+	 * Check if a {@link PropertyValueConverter} is present for the given {@literal property}.
+	 *
+	 * @param property must not be {@literal null}.
+	 * @return {@literal true} if a specific {@link PropertyValueConverter} is available.
+	 */
+	default boolean hasValueConverter(PersistentProperty<?> property) {
+		return getValueConverter(property) != null;
+	}
+
+	/**
+	 * Get the {@link PropertyValueConverter} for the given {@literal property} if present.
+	 *
+	 * @param property must not be {@literal null}. param <A> domain specific type
+	 * @param <B> store native type
+	 * @param <C> conversion context type
+	 * @return the suitable {@link PropertyValueConverter} or {@literal null} if none available.
+	 */
+	@Nullable
+	<A, B, C extends PropertyValueConverter.ValueConversionContext> PropertyValueConverter<A, B, C> getValueConverter(
+			PersistentProperty<?> property);
+}

src/main/java/org/springframework/data/convert/PropertyValueConverter.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2021 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.convert;
+
+import org.springframework.data.mapping.PersistentProperty;
+import org.springframework.lang.Nullable;
+
+/**
+ * {@link PropertyValueConverter} provides a symmetric way of converting certain properties from domain to store
+ * specific values.
+ * <p>
+ * A {@link PropertyValueConverter} is, other than a {@link ReadingConverter} or {@link WritingConverter}, only applied
+ * to special annotated fields which allows a fine grained conversion of certain values within a specific context.
+ *
+ * @author Christoph Strobl
+ * @param <A> domain specific type
+ * @param <B> store native type
+ * @since 2.7
+ */
+public interface PropertyValueConverter<A, B, C extends PropertyValueConverter.ValueConversionContext> {
+
+	/**
+	 * Convert the given store specific value into it's domain value representation. Typically a {@literal read}
+	 * operation.
+	 *
+	 * @param nativeValue can be {@literal null}.
+	 * @param context never {@literal null}.
+	 * @return the converted value. Can be {@literal null}.
+	 */
+	@Nullable
+	A /*read*/ nativeToDomain(@Nullable B nativeValue, C context);
+
+	/**
+	 * Convert the given domain specific value into it's native store representation. Typically a {@literal write}
+	 * operation.
+	 *
+	 * @param domainValue can be {@literal null}.
+	 * @param context never {@literal null}.
+	 * @return the converted value. Can be {@literal null}.
+	 */
+	@Nullable
+	B /*write*/ domainToNative(@Nullable A domainValue, C context);
+
+	/**
+	 * @author Christoph Strobl
+	 */
+	interface ValueConversionContext {
+
+		PersistentProperty<?> getProperty();
+	}
+
+	/**
+	 * NoOp {@link PropertyValueConverter} implementation.
+	 *
+	 * @author Christoph Strobl
+	 */
+	enum ObjectToObjectPropertyValueConverter implements PropertyValueConverter<Object, Object, ValueConversionContext> {
+
+		INSTANCE;
+
+		@Override
+		public Object nativeToDomain(Object value, ValueConversionContext context) {
+			return value;
+		}
+
+		@Override
+		public Object domainToNative(Object value, ValueConversionContext context) {
+			return value;
+		}
+	}
+
+}