Introduce Queryable annotation and add Schema derivation.

This commit decouples queryable encryption from explicit encryption and introduces the Queryable annotation to represent different query types like range and equality.
Additionally it removes value conversion from range encryption and fixes update mapping of range encrypted fields.

Original Pull Request: #4885

Author: christophstrobl

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

@@ -39,6 +39,7 @@
 import org.springframework.data.mapping.PropertyPath;
 import org.springframework.data.mapping.context.MappingContext;
 import org.springframework.data.mapping.model.ConvertingPropertyAccessor;
+import org.springframework.data.mongodb.core.CollectionOptions.EncryptedFieldsOptions;
 import org.springframework.data.mongodb.core.CollectionOptions.TimeSeriesOptions;
 import org.springframework.data.mongodb.core.convert.MongoConverter;
 import org.springframework.data.mongodb.core.convert.MongoJsonSchemaMapper;
@@ -379,7 +380,11 @@ public CreateCollectionOptions convertToCreateCollectionOptions(@Nullable Collec
 		collectionOptions.getChangeStreamOptions().ifPresent(it -> result
 				.changeStreamPreAndPostImagesOptions(new ChangeStreamPreAndPostImagesOptions(it.getPreAndPostImages())));
 
-		collectionOptions.getEncryptedFields().ifPresent(result::encryptedFields);
+		collectionOptions.getEncryptedFieldsOptions().map(EncryptedFieldsOptions::toDocument).ifPresent(encryptedFields -> {
+			if (!encryptedFields.isEmpty()) {
+				result.encryptedFields(encryptedFields);
+			}
+		});
 		return result;
 	}
 

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

@@ -31,14 +31,19 @@
 import org.springframework.data.mongodb.core.mapping.Field;
 import org.springframework.data.mongodb.core.mapping.MongoPersistentEntity;
 import org.springframework.data.mongodb.core.mapping.MongoPersistentProperty;
+import org.springframework.data.mongodb.core.mapping.Queryable;
+import org.springframework.data.mongodb.core.mapping.RangeEncrypted;
 import org.springframework.data.mongodb.core.schema.IdentifiableJsonSchemaProperty.ArrayJsonSchemaProperty;
 import org.springframework.data.mongodb.core.schema.IdentifiableJsonSchemaProperty.EncryptedJsonSchemaProperty;
 import org.springframework.data.mongodb.core.schema.IdentifiableJsonSchemaProperty.ObjectJsonSchemaProperty;
+import org.springframework.data.mongodb.core.schema.IdentifiableJsonSchemaProperty.QueryableJsonSchemaProperty;
 import org.springframework.data.mongodb.core.schema.JsonSchemaObject;
 import org.springframework.data.mongodb.core.schema.JsonSchemaObject.Type;
 import org.springframework.data.mongodb.core.schema.JsonSchemaProperty;
 import org.springframework.data.mongodb.core.schema.MongoJsonSchema;
 import org.springframework.data.mongodb.core.schema.MongoJsonSchema.MongoJsonSchemaBuilder;
+import org.springframework.data.mongodb.core.schema.QueryCharacteristic;
+import org.springframework.data.mongodb.core.schema.QueryCharacteristics;
 import org.springframework.data.mongodb.core.schema.TypedJsonSchemaObject;
 import org.springframework.data.util.TypeInformation;
 import org.springframework.util.Assert;
@@ -291,7 +296,35 @@ private JsonSchemaProperty applyEncryptionDataIfNecessary(MongoPersistentPropert
 		if (!ObjectUtils.isEmpty(encrypted.keyId())) {
 			enc = enc.keys(property.getEncryptionKeyIds());
 		}
-		return enc;
+
+		Queryable queryable = property.findAnnotation(Queryable.class);
+		if (queryable == null || !StringUtils.hasText(queryable.queryType())) {
+			return enc;
+		}
+
+		QueryCharacteristic characteristic = new QueryCharacteristic() {
+
+			@Override
+			public String queryType() {
+				return queryable.queryType();
+			}
+
+			@Override
+			public Document toDocument() {
+
+				Document options = QueryCharacteristic.super.toDocument();
+
+				if (queryable.contentionFactor() >= 0) {
+					options.put("contention", queryable.contentionFactor());
+				}
+				if (!queryable.queryAttributes().isEmpty()) {
+					options.putAll(Document.parse(queryable.queryAttributes()));
+				}
+
+				return options;
+			}
+		};
+		return new QueryableJsonSchemaProperty(enc, QueryCharacteristics.of(List.of(characteristic)));
 	}
 
 	private JsonSchemaProperty createObjectSchemaPropertyForEntity(List<MongoPersistentProperty> path,

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

@@ -16,12 +16,12 @@
 package org.springframework.data.mongodb.core.convert;
 
 import org.bson.conversions.Bson;
-
 import org.springframework.data.convert.ValueConversionContext;
 import org.springframework.data.mapping.model.PropertyValueProvider;
 import org.springframework.data.mapping.model.SpELContext;
 import org.springframework.data.mongodb.core.mapping.MongoPersistentProperty;
 import org.springframework.data.util.TypeInformation;
+import org.springframework.lang.CheckReturnValue;
 import org.springframework.lang.Nullable;
 
 /**
@@ -38,7 +38,7 @@ public class MongoConversionContext implements ValueConversionContext<MongoPersi
 
 	@Nullable private final MongoPersistentProperty persistentProperty;
 	@Nullable private final SpELContext spELContext;
-	@Nullable private final String fieldNameAndQueryOperator;
+	@Nullable private final OperatorContext operatorContext;
 
 	public MongoConversionContext(PropertyValueProvider<MongoPersistentProperty> accessor,
 			@Nullable MongoPersistentProperty persistentProperty, MongoConverter mongoConverter) {
@@ -53,19 +53,19 @@ public MongoConversionContext(PropertyValueProvider<MongoPersistentProperty> acc
 
 	public MongoConversionContext(PropertyValueProvider<MongoPersistentProperty> accessor,
 			@Nullable MongoPersistentProperty persistentProperty, MongoConverter mongoConverter,
-			@Nullable String fieldNameAndQueryOperator) {
-		this(accessor, persistentProperty, mongoConverter, null, fieldNameAndQueryOperator);
+			@Nullable OperatorContext operatorContext) {
+		this(accessor, persistentProperty, mongoConverter, null, operatorContext);
 	}
 
 	public MongoConversionContext(PropertyValueProvider<MongoPersistentProperty> accessor,
 			@Nullable MongoPersistentProperty persistentProperty, MongoConverter mongoConverter,
-			@Nullable SpELContext spELContext, @Nullable String fieldNameAndQueryOperator) {
+			@Nullable SpELContext spELContext, @Nullable OperatorContext operatorContext) {
 
 		this.accessor = accessor;
 		this.persistentProperty = persistentProperty;
 		this.mongoConverter = mongoConverter;
 		this.spELContext = spELContext;
-		this.fieldNameAndQueryOperator = fieldNameAndQueryOperator;
+		this.operatorContext = operatorContext;
 	}
 
 	@Override
@@ -78,6 +78,17 @@ public MongoPersistentProperty getProperty() {
 		return persistentProperty;
 	}
 
+	/**
+	 *
+	 * @param operatorContext
+	 * @return new instance of {@link MongoConversionContext}.
+	 * @since 4.5
+	 */
+	@CheckReturnValue
+	public MongoConversionContext forOperator(@Nullable OperatorContext operatorContext) {
+		return new MongoConversionContext(accessor, persistentProperty, mongoConverter, spELContext, operatorContext);
+	}
+
 	@Nullable
 	public Object getValue(String propertyPath) {
 		return accessor.getPropertyValue(getProperty().getOwner().getRequiredPersistentProperty(propertyPath));
@@ -101,7 +112,78 @@ public SpELContext getSpELContext() {
 	}
 
 	@Nullable
-	public String getFieldNameAndQueryOperator() {
-		return fieldNameAndQueryOperator;
+	public OperatorContext getOperatorContext() {
+		return operatorContext;
+	}
+
+	/**
+	 * The {@link OperatorContext} provides access to the actual conversion intent like a write operation or a query
+	 * operator such as {@literal $gte}.
+	 * 
+	 * @since 4.5
+	 */
+	public interface OperatorContext {
+
+		/**
+		 * The operator the conversion is used in.
+		 * @return {@literal write} for simple write operations during save, or a query operator.
+		 */
+		String getOperator();
+
+		/**
+		 * The context path the operator is used in.
+		 * @return never {@literal null}.
+		 */
+		String getPath();
+
+		boolean isWriteOperation();
+	}
+
+	public static class WriteOperatorContext implements OperatorContext {
+
+		private final String path;
+
+		public WriteOperatorContext(String path) {
+			this.path = path;
+		}
+
+		@Override
+		public String getOperator() {
+			return "write";
+		}
+
+		@Override
+		public String getPath() {
+			return path;
+		}
+
+		@Override
+		public boolean isWriteOperation() {
+			return true;
+		}
+	}
+
+	public static class QueryOperatorContext implements OperatorContext {
+
+		private final String operator;
+		private final String path;
+
+		public QueryOperatorContext(@Nullable String operator, String path) {
+			this.operator = operator != null ? operator : "$eq";
+			this.path = path;
+		}
+
+		public String getOperator() {
+			return operator;
+		}
+
+		public String getPath() {
+			return path;
+		}
+
+		@Override
+		public boolean isWriteOperation() {
+			return false;
+		}
 	}
 }

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

@@ -37,7 +37,6 @@
 import org.bson.Document;
 import org.bson.conversions.Bson;
 import org.bson.types.ObjectId;
-
 import org.springframework.core.convert.ConversionService;
 import org.springframework.core.convert.converter.Converter;
 import org.springframework.data.annotation.Reference;
@@ -58,6 +57,8 @@
 import org.springframework.data.mongodb.core.aggregation.AggregationExpression;
 import org.springframework.data.mongodb.core.aggregation.RelaxedTypeBasedAggregationOperationContext;
 import org.springframework.data.mongodb.core.convert.MappingMongoConverter.NestedDocument;
+import org.springframework.data.mongodb.core.convert.MongoConversionContext.OperatorContext;
+import org.springframework.data.mongodb.core.convert.MongoConversionContext.QueryOperatorContext;
 import org.springframework.data.mongodb.core.mapping.FieldName;
 import org.springframework.data.mongodb.core.mapping.MongoPersistentEntity;
 import org.springframework.data.mongodb.core.mapping.MongoPersistentProperty;
@@ -672,18 +673,21 @@ private Object convertValue(Field documentField, Object sourceValue, Object valu
 
 		MongoPersistentProperty property = documentField.getProperty();
 
-		String fieldNameAndQueryOperator = property != null && !property.getFieldName().equals(documentField.name)
-				? property.getFieldName() + "." + documentField.name
-				: documentField.name;
-
-		MongoConversionContext conversionContext = new MongoConversionContext(NoPropertyPropertyValueProvider.INSTANCE,
-				property, converter, fieldNameAndQueryOperator);
+		OperatorContext criteriaContext = new QueryOperatorContext(
+				isKeyword(documentField.name) ? documentField.name : "$eq", property.getFieldName());
+		MongoConversionContext conversionContext;
+		if (valueConverter instanceof MongoConversionContext mcc) {
+			conversionContext = mcc.forOperator(criteriaContext);
+		} else {
+			conversionContext = new MongoConversionContext(NoPropertyPropertyValueProvider.INSTANCE, property, converter,
+					criteriaContext);
+		}
 
 		return convertValueWithConversionContext(documentField, sourceValue, value, valueConverter, conversionContext);
 	}
 
 	@Nullable
-	private Object convertValueWithConversionContext(Field documentField, Object sourceValue, Object value,
+	protected Object convertValueWithConversionContext(Field documentField, Object sourceValue, Object value,
 			PropertyValueConverter<Object, Object, ValueConversionContext<MongoPersistentProperty>> valueConverter,
 			MongoConversionContext conversionContext) {
 
@@ -707,10 +711,7 @@ private Object convertValueWithConversionContext(Field documentField, Object sou
 
 			return BsonUtils.mapValues(document, (key, val) -> {
 				if (isKeyword(key)) {
-					MongoConversionContext fieldConversionContext = new MongoConversionContext(
-							NoPropertyPropertyValueProvider.INSTANCE, property, converter,
-							conversionContext.getFieldNameAndQueryOperator() + "." + key);
-					return convertValueWithConversionContext(documentField, val, val, valueConverter, fieldConversionContext);
+					return convertValueWithConversionContext(documentField, val, val, valueConverter, conversionContext.forOperator(new QueryOperatorContext(key, conversionContext.getOperatorContext().getPath())));
 				}
 				return val;
 			});
@@ -1624,7 +1625,7 @@ public MongoConverter getConverter() {
 		return converter;
 	}
 
-	private enum NoPropertyPropertyValueProvider implements PropertyValueProvider<MongoPersistentProperty> {
+	enum NoPropertyPropertyValueProvider implements PropertyValueProvider<MongoPersistentProperty> {
 
 		INSTANCE;
 

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

@@ -24,10 +24,13 @@
 import org.bson.Document;
 import org.bson.conversions.Bson;
 import org.springframework.core.convert.converter.Converter;
+import org.springframework.data.convert.PropertyValueConverter;
+import org.springframework.data.convert.ValueConversionContext;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.domain.Sort.Order;
 import org.springframework.data.mapping.Association;
 import org.springframework.data.mapping.context.MappingContext;
+import org.springframework.data.mongodb.core.convert.MongoConversionContext.WriteOperatorContext;
 import org.springframework.data.mongodb.core.mapping.MongoPersistentEntity;
 import org.springframework.data.mongodb.core.mapping.MongoPersistentProperty;
 import org.springframework.data.mongodb.core.query.Query;
@@ -160,6 +163,13 @@ protected Entry<String, Object> getMappedObjectForField(Field field, Object rawV
 		return super.getMappedObjectForField(field, rawValue);
 	}
 
+	protected Object convertValueWithConversionContext(Field documentField, Object sourceValue, Object value,
+		PropertyValueConverter<Object, Object, ValueConversionContext<MongoPersistentProperty>> valueConverter,
+		MongoConversionContext conversionContext) {
+
+		return super.convertValueWithConversionContext(documentField, sourceValue, value, valueConverter, conversionContext.forOperator(new WriteOperatorContext(documentField.name)));
+	}
+
 	private Entry<String, Object> getMappedUpdateModifier(Field field, Object rawValue) {
 		Object value;
 

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

@@ -16,6 +16,7 @@
 package org.springframework.data.mongodb.core.convert.encryption;
 
 import org.springframework.data.mongodb.core.convert.MongoConversionContext;
+import org.springframework.data.mongodb.core.convert.MongoConversionContext.OperatorContext;
 import org.springframework.data.mongodb.core.encryption.EncryptionContext;
 import org.springframework.data.mongodb.core.mapping.MongoPersistentProperty;
 import org.springframework.data.util.TypeInformation;
@@ -70,7 +71,7 @@ public <T> T write(@Nullable Object value, TypeInformation<T> target) {
 
 	@Override
 	@Nullable
-	public String getFieldNameAndQueryOperator() {
-		return conversionContext.getFieldNameAndQueryOperator();
+	public OperatorContext getOperatorContext() {
+		return conversionContext.getOperatorContext();
 	}
 }