Polishing.

Refine API naming towards merge/property instead of combine/specify. Tweak documentation. Introduce Resolution.ofValue(…) for easier creation.

See #3870
Original pull request: #3986.

Author: mp911de

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

@@ -94,13 +94,8 @@ public MongoJsonSchemaCreator filter(Predicate<JsonSchemaPropertyContext> filter
 	}
 
 	@Override
-	public PropertySpecifier specify(String path) {
-		return new PropertySpecifier() {
-			@Override
-			public MongoJsonSchemaCreator types(Class<?>... types) {
-				return specifyTypesFor(path, types);
-			}
-		};
+	public PropertySpecifier property(String path) {
+		return types -> withTypesFor(path, types);
 	}
 
 	/**
@@ -111,7 +106,7 @@ public MongoJsonSchemaCreator types(Class<?>... types) {
 	 * @return new instance of {@link MongoJsonSchemaCreator}.
 	 * @since 3.4
 	 */
-	public MongoJsonSchemaCreator specifyTypesFor(String path, Class<?>... types) {
+	public MongoJsonSchemaCreator withTypesFor(String path, Class<?>... types) {
 
 		LinkedMultiValueMap<String, Class<?>> clone = mergeProperties.clone();
 		for (Class<?> type : types) {
@@ -213,7 +208,7 @@ private JsonSchemaProperty computeSchemaForProperty(List<MongoPersistentProperty
 					}
 				}
 				return targetProperties.size() == 1 ? targetProperties.iterator().next()
-						: JsonSchemaProperty.combined(targetProperties);
+						: JsonSchemaProperty.merged(targetProperties);
 			}
 		}
 

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

@@ -79,17 +79,17 @@ public interface MongoJsonSchemaCreator {
 	MongoJsonSchema createSchemaFor(Class<?> type);
 
 	/**
-	 * Create a combined {@link MongoJsonSchema} out of the individual schemas of the given types by combining their
+	 * Create a merged {@link MongoJsonSchema} out of the individual schemas of the given types by merging their
 	 * properties into one large {@link MongoJsonSchema schema}.
-	 * 
+	 *
 	 * @param types must not be {@literal null} nor contain {@literal null}.
 	 * @return new instance of {@link MongoJsonSchema}.
 	 * @since 3.4
 	 */
-	default MongoJsonSchema combineSchemaFor(Class<?>... types) {
+	default MongoJsonSchema mergedSchemaFor(Class<?>... types) {
 
 		MongoJsonSchema[] schemas = Arrays.stream(types).map(this::createSchemaFor).toArray(MongoJsonSchema[]::new);
-		return MongoJsonSchema.combined(schemas);
+		return MongoJsonSchema.merge(schemas);
 	}
 
 	/**
@@ -108,32 +108,32 @@ default MongoJsonSchema combineSchemaFor(Class<?>... types) {
 	 * @return new instance of {@link PropertySpecifier}.
 	 * @since 3.4
 	 */
-	PropertySpecifier specify(String path);
+	PropertySpecifier property(String path);
 
 	/**
 	 * The context in which a specific {@link #getProperty()} is encountered during schema creation.
-	 * 
+	 *
 	 * @since 3.3
 	 */
 	interface JsonSchemaPropertyContext {
 
 		/**
 		 * The path to a given field/property in dot notation.
-		 * 
+		 *
 		 * @return never {@literal null}.
 		 */
 		String getPath();
 
 		/**
 		 * The current property.
-		 * 
+		 *
 		 * @return never {@literal null}.
 		 */
 		MongoPersistentProperty getProperty();
 
 		/**
 		 * Obtain the {@link MongoPersistentEntity} for a given property.
-		 * 
+		 *
 		 * @param property must not be {@literal null}.
 		 * @param <T>
 		 * @return {@literal null} if the property is not an entity. It is nevertheless recommend to check
@@ -234,7 +234,6 @@ static MongoJsonSchemaCreator create() {
 	}
 
 	/**
-	 * @since 3.4
 	 * @author Christoph Strobl
 	 * @since 3.4
 	 */
@@ -246,6 +245,6 @@ interface PropertySpecifier {
 		 * @param types must not be {@literal null}.
 		 * @return the source
 		 */
-		MongoJsonSchemaCreator types(Class<?>... types);
+		MongoJsonSchemaCreator withTypes(Class<?>... types);
 	}
 }

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

@@ -236,14 +236,14 @@ static JsonSchemaProperty required(JsonSchemaProperty property) {
 	}
 
 	/**
-	 * Combines multiple {@link JsonSchemaProperty} with potentially different attributes into one.
+	 * Merges multiple {@link JsonSchemaProperty} with potentially different attributes into one.
 	 *
 	 * @param properties must not be {@literal null}.
 	 * @return new instance of {@link JsonSchemaProperty}.
 	 * @since 3.4
 	 */
-	static JsonSchemaProperty combined(Collection<JsonSchemaProperty> properties) {
-		return new CombinedJsonSchemaProperty(properties);
+	static JsonSchemaProperty merged(Collection<JsonSchemaProperty> properties) {
+		return new MergedJsonSchemaProperty(properties);
 	}
 
 	/**

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/schema/CombinedJsonSchema.java renamed to spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/schema/MergedJsonSchema.java

@@ -24,29 +24,30 @@
 import org.bson.Document;
 
 /**
- * {@link MongoJsonSchema} implementation that is capable of combining properties of different schemas into one.
+ * {@link MongoJsonSchema} implementation that is capable of merging properties from different schemas into a single
+ * one.
  *
  * @author Christoph Strobl
  * @since 3.4
  */
-class CombinedJsonSchema implements MongoJsonSchema {
+class MergedJsonSchema implements MongoJsonSchema {
 
 	private final List<MongoJsonSchema> schemaList;
 	private final BiFunction<Map<String, Object>, Map<String, Object>, Document> mergeFunction;
 
-	CombinedJsonSchema(List<MongoJsonSchema> schemaList, ConflictResolutionFunction conflictResolutionFunction) {
+	MergedJsonSchema(List<MongoJsonSchema> schemaList, ConflictResolutionFunction conflictResolutionFunction) {
 		this(schemaList, new TypeUnifyingMergeFunction(conflictResolutionFunction));
 	}
 
-	CombinedJsonSchema(List<MongoJsonSchema> schemaList,
+	MergedJsonSchema(List<MongoJsonSchema> schemaList,
 			BiFunction<Map<String, Object>, Map<String, Object>, Document> mergeFunction) {
 
 		this.schemaList = new ArrayList<>(schemaList);
 		this.mergeFunction = mergeFunction;
 	}
 
 	@Override
-	public MongoJsonSchema combineWith(Collection<MongoJsonSchema> sources) {
+	public MongoJsonSchema mergeWith(Collection<MongoJsonSchema> sources) {
 
 		schemaList.addAll(sources);
 		return this;

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/schema/CombinedJsonSchemaProperty.java renamed to spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/schema/MergedJsonSchemaProperty.java

@@ -30,24 +30,24 @@
  * @author Christoph Strobl
  * @since 3.4
  */
-class CombinedJsonSchemaProperty implements JsonSchemaProperty {
+class MergedJsonSchemaProperty implements JsonSchemaProperty {
 
 	private final Iterable<JsonSchemaProperty> properties;
 	private final BiFunction<Map<String, Object>, Map<String, Object>, Document> mergeFunction;
 
-	CombinedJsonSchemaProperty(Iterable<JsonSchemaProperty> properties) {
+	MergedJsonSchemaProperty(Iterable<JsonSchemaProperty> properties) {
 		this(properties, (k, a, b) -> {
 			throw new IllegalStateException(
-					String.format("Error resolving conflict for %s. No conflict resolution function defined.", k));
+					String.format("Error resolving conflict for '%s'. No conflict resolution function defined.", k));
 		});
 	}
 
-	CombinedJsonSchemaProperty(Iterable<JsonSchemaProperty> properties,
+	MergedJsonSchemaProperty(Iterable<JsonSchemaProperty> properties,
 			ConflictResolutionFunction conflictResolutionFunction) {
 		this(properties, new TypeUnifyingMergeFunction(conflictResolutionFunction));
 	}
 
-	CombinedJsonSchemaProperty(Iterable<JsonSchemaProperty> properties,
+	MergedJsonSchemaProperty(Iterable<JsonSchemaProperty> properties,
 			BiFunction<Map<String, Object>, Map<String, Object>, Document> mergeFunction) {
 
 		this.properties = properties;

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

@@ -25,6 +25,7 @@
 import org.bson.Document;
 import org.springframework.data.mongodb.core.schema.TypedJsonSchemaObject.ObjectJsonSchemaObject;
 import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
 
 /**
  * Interface defining MongoDB-specific JSON schema object. New objects can be built with {@link #builder()}, for
@@ -79,7 +80,7 @@ default Document toDocument() {
 
 	/**
 	 * Create the {@link Document} defining the schema. <br />
-	 * Property and field names need to be mapped to the domain type ones by running the {@link Document} through a
+	 * Property and field names need to be mapped to the domain type property by running the {@link Document} through a
 	 * {@link org.springframework.data.mongodb.core.convert.JsonSchemaMapper} to apply field name customization.
 	 *
 	 * @return never {@literal null}.
@@ -108,69 +109,69 @@ static MongoJsonSchema of(Document document) {
 	}
 
 	/**
-	 * Create a new {@link MongoJsonSchema} combining properties from the given sources.
+	 * Create a new {@link MongoJsonSchema} merging properties from the given sources.
 	 *
 	 * @param sources must not be {@literal null}.
 	 * @return new instance of {@link MongoJsonSchema}.
 	 * @since 3.4
 	 */
-	static MongoJsonSchema combined(MongoJsonSchema... sources) {
-		return combined((path, a, b) -> {
-			throw new IllegalStateException(
-					String.format("Failure combining schema for path %s holding values a) %s and b) %s.", path.dotPath(), a, b));
+	static MongoJsonSchema merge(MongoJsonSchema... sources) {
+		return merge((path, left, right) -> {
+			throw new IllegalStateException(String.format("Cannot merge schema for path '%s' holding values '%s' and '%s'.",
+					path.dotPath(), left, right));
 		}, sources);
 	}
 
 	/**
-	 * Create a new {@link MongoJsonSchema} combining properties from the given sources.
+	 * Create a new {@link MongoJsonSchema} merging properties from the given sources.
 	 *
 	 * @param sources must not be {@literal null}.
 	 * @return new instance of {@link MongoJsonSchema}.
 	 * @since 3.4
 	 */
-	static MongoJsonSchema combined(ConflictResolutionFunction mergeFunction, MongoJsonSchema... sources) {
-		return new CombinedJsonSchema(Arrays.asList(sources), mergeFunction);
+	static MongoJsonSchema merge(ConflictResolutionFunction mergeFunction, MongoJsonSchema... sources) {
+		return new MergedJsonSchema(Arrays.asList(sources), mergeFunction);
 	}
 
 	/**
-	 * Create a new {@link MongoJsonSchema} combining properties from the given sources.
+	 * Create a new {@link MongoJsonSchema} merging properties from the given sources.
 	 *
 	 * @param sources must not be {@literal null}.
 	 * @return new instance of {@link MongoJsonSchema}.
 	 * @since 3.4
 	 */
-	default MongoJsonSchema combineWith(MongoJsonSchema... sources) {
-		return combineWith(Arrays.asList(sources));
+	default MongoJsonSchema mergeWith(MongoJsonSchema... sources) {
+		return mergeWith(Arrays.asList(sources));
 	}
 
 	/**
-	 * Create a new {@link MongoJsonSchema} combining properties from the given sources.
+	 * Create a new {@link MongoJsonSchema} merging properties from the given sources.
 	 *
 	 * @param sources must not be {@literal null}.
 	 * @return new instance of {@link MongoJsonSchema}.
 	 * @since 3.4
 	 */
-	default MongoJsonSchema combineWith(Collection<MongoJsonSchema> sources) {
-		return combineWith(sources, (path, a, b) -> {
-			throw new IllegalStateException(
-					String.format("Failure combining schema for path %s holding values a) %s and b) %s.", path.dotPath(), a, b));
+	default MongoJsonSchema mergeWith(Collection<MongoJsonSchema> sources) {
+		return mergeWith(sources, (path, left, right) -> {
+			throw new IllegalStateException(String.format("Cannot merge schema for path '%s' holding values '%s' and '%s'.",
+					path.dotPath(), left, right));
 		});
 	}
 
 	/**
-	 * Create a new {@link MongoJsonSchema} combining properties from the given sources.
+	 * Create a new {@link MongoJsonSchema} merging properties from the given sources.
 	 *
 	 * @param sources must not be {@literal null}.
 	 * @return new instance of {@link MongoJsonSchema}.
 	 * @since 3.4
 	 */
-	default MongoJsonSchema combineWith(Collection<MongoJsonSchema> sources,
+	default MongoJsonSchema mergeWith(Collection<MongoJsonSchema> sources,
 			ConflictResolutionFunction conflictResolutionFunction) {
 
 		List<MongoJsonSchema> schemaList = new ArrayList<>(sources.size() + 1);
 		schemaList.add(this);
 		schemaList.addAll(new ArrayList<>(sources));
-		return new CombinedJsonSchema(schemaList, conflictResolutionFunction);
+		return new MergedJsonSchema(schemaList, conflictResolutionFunction);
 	}
 
 	/**
@@ -183,8 +184,8 @@ static MongoJsonSchemaBuilder builder() {
 	}
 
 	/**
-	 * A resolution function that may be called on conflicting paths. Eg. when trying to merge properties with different
-	 * values into one.
+	 * A resolution function that is called on conflicting paths when trying to merge properties with different values
+	 * into a single value.
 	 *
 	 * @author Christoph Strobl
 	 * @since 3.4
@@ -193,12 +194,14 @@ static MongoJsonSchemaBuilder builder() {
 	interface ConflictResolutionFunction {
 
 		/**
+		 * Resolve the conflict for two values under the same {@code path}.
+		 *
 		 * @param path the {@link Path} leading to the conflict.
-		 * @param a can be {@literal null}.
-		 * @param b can be {@literal null}.
+		 * @param left can be {@literal null}.
+		 * @param right can be {@literal null}.
 		 * @return never {@literal null}.
 		 */
-		Resolution resolveConflict(Path path, @Nullable Object a, @Nullable Object b);
+		Resolution resolveConflict(Path path, @Nullable Object left, @Nullable Object right);
 
 		/**
 		 * @author Christoph Strobl
@@ -218,7 +221,7 @@ interface Path {
 		}
 
 		/**
-		 * The result after processing a conflict when combining schemas. May indicate to {@link #SKIP skip} the entry
+		 * The result after processing a conflict when merging schemas. May indicate to {@link #SKIP skip} the entry
 		 * entirely.
 		 *
 		 * @author Christoph Strobl
@@ -260,6 +263,42 @@ public Object setValue(Object value) {
 			static Resolution skip() {
 				return SKIP;
 			}
+
+			/**
+			 * Construct a resolution for a {@link Path} using the given {@code value}.
+			 *
+			 * @param path the conflicting path.
+			 * @param value the value to apply.
+			 * @return
+			 */
+			static Resolution ofValue(Path path, Object value) {
+
+				Assert.notNull(path, "Path must not be null");
+
+				return ofValue(path.currentElement(), value);
+			}
+
+			/**
+			 * Construct a resolution from a {@code key} and {@code value}.
+			 *
+			 * @param key name of the path segment, typically {@link Path#currentElement()}
+			 * @param value the value to apply.
+			 * @return
+			 */
+			static Resolution ofValue(String key, Object value) {
+
+				return new Resolution() {
+					@Override
+					public String getKey() {
+						return key;
+					}
+
+					@Override
+					public Object getValue() {
+						return value;
+					}
+				};
+			}
 		}
 	}