Update method names and wording.

- MongoExpresssion#expressionFromString(String) -> MongoExpresssion#create
- AggregationExpression#create(MongoExpression) ->A ggregationExpression#from
- MongoExpression#as -> removed from public API

Author: christophstrobl

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/BindableMongoExpression.java

@@ -25,9 +25,10 @@
 import org.springframework.util.StringUtils;
 
 /**
- * A {@link MongoExpression} using the {@link ParameterBindingDocumentCodec} for parsing the {@literal json} expression.
- * The expression will be wrapped within <code>{ }</code> if necessary. Placeholders like {@code ?0} are resolved when
- * first obtaining the target {@link Document} via {@link #toDocument()}.
+ * A {@link MongoExpression} using the {@link ParameterBindingDocumentCodec} for parsing a raw ({@literal json})
+ * expression. The expression will be wrapped within <code>{ ... }</code> if necessary. The actual parsing and parameter
+ * binding of placeholders like {@code ?0} is delayed upon first call on the the target {@link Document} via
+ * {@link #toDocument()}.
  * <p />
  * 
  * <pre class="code">
@@ -38,16 +39,15 @@
  * { '$toUpper' : '?0' }, "$name"  -> { '$toUpper' : '$name' }
  * </pre>
  * 
- * Some types (like {@link java.util.UUID}) cannot be used directly but require a special {@link org.bson.codecs.Codec}.
- * Make sure to provide a {@link CodecRegistry} containing the required {@link org.bson.codecs.Codec codecs} via
- * {@link #withCodecRegistry(CodecRegistry)}.
+ * Some types might require a special {@link org.bson.codecs.Codec}. If so, make sure to provide a {@link CodecRegistry}
+ * containing the required {@link org.bson.codecs.Codec codec} via {@link #withCodecRegistry(CodecRegistry)}.
  *
  * @author Christoph Strobl
  * @since 3.2
  */
 public class BindableMongoExpression implements MongoExpression {
 
-	private final String json;
+	private final String expressionString;
 
 	@Nullable //
 	private final CodecRegistryProvider codecRegistryProvider;
@@ -60,24 +60,24 @@ public class BindableMongoExpression implements MongoExpression {
 	/**
 	 * Create a new instance of {@link BindableMongoExpression}.
 	 *
-	 * @param json must not be {@literal null}.
+	 * @param expression must not be {@literal null}.
 	 * @param args can be {@literal null}.
 	 */
-	public BindableMongoExpression(String json, @Nullable Object[] args) {
-		this(json, null, args);
+	public BindableMongoExpression(String expression, @Nullable Object[] args) {
+		this(expression, null, args);
 	}
 
 	/**
 	 * Create a new instance of {@link BindableMongoExpression}.
 	 *
-	 * @param json must not be {@literal null}.
+	 * @param expression must not be {@literal null}.
 	 * @param codecRegistryProvider can be {@literal null}.
 	 * @param args can be {@literal null}.
 	 */
-	public BindableMongoExpression(String json, @Nullable CodecRegistryProvider codecRegistryProvider,
+	public BindableMongoExpression(String expression, @Nullable CodecRegistryProvider codecRegistryProvider,
 			@Nullable Object[] args) {
 
-		this.json = wrapJsonIfNecessary(json);
+		this.expressionString = expression;
 		this.codecRegistryProvider = codecRegistryProvider;
 		this.args = args;
 		this.target = Lazy.of(this::parse);
@@ -90,7 +90,7 @@ public BindableMongoExpression(String json, @Nullable CodecRegistryProvider code
 	 * @return new instance of {@link BindableMongoExpression}.
 	 */
 	public BindableMongoExpression withCodecRegistry(CodecRegistry codecRegistry) {
-		return new BindableMongoExpression(json, () -> codecRegistry, args);
+		return new BindableMongoExpression(expressionString, () -> codecRegistry, args);
 	}
 
 	/**
@@ -100,19 +100,27 @@ public BindableMongoExpression withCodecRegistry(CodecRegistry codecRegistry) {
 	 * @return new instance of {@link BindableMongoExpression}.
 	 */
 	public BindableMongoExpression bind(Object... args) {
-		return new BindableMongoExpression(json, codecRegistryProvider, args);
+		return new BindableMongoExpression(expressionString, codecRegistryProvider, args);
 	}
 
 	/*
 	 * (non-Javadoc)
-	 * 
 	 * @see org.springframework.data.mongodb.MongoExpression#toDocument()
 	 */
 	@Override
 	public Document toDocument() {
 		return target.get();
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see java.lang.Object#toString()
+	 */
+	@Override
+	public String toString() {
+		return "BindableMongoExpression{" + "expressionString='" + expressionString + '\'' + ", args=" + args + '}';
+	}
+
 	private String wrapJsonIfNecessary(String json) {
 
 		if (StringUtils.hasText(json) && (json.startsWith("{") && json.endsWith("}"))) {
@@ -124,18 +132,20 @@ private String wrapJsonIfNecessary(String json) {
 
 	private Document parse() {
 
+		String expression = wrapJsonIfNecessary(expressionString);
+
 		if (ObjectUtils.isEmpty(args)) {
 
 			if (codecRegistryProvider == null) {
-				return Document.parse(json);
+				return Document.parse(expression);
 			}
 
-			return Document.parse(json, codecRegistryProvider.getCodecFor(Document.class)
+			return Document.parse(expression, codecRegistryProvider.getCodecFor(Document.class)
 					.orElseGet(() -> new DocumentCodec(codecRegistryProvider.getCodecRegistry())));
 		}
 
 		ParameterBindingDocumentCodec codec = codecRegistryProvider == null ? new ParameterBindingDocumentCodec()
 				: new ParameterBindingDocumentCodec(codecRegistryProvider.getCodecRegistry());
-		return codec.decode(json, args);
+		return codec.decode(expression, args);
 	}
 }

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/MongoExpression.java

@@ -15,8 +15,6 @@
  */
 package org.springframework.data.mongodb;
 
-import java.util.function.Function;
-
 /**
  * Wrapper object for MongoDB expressions like {@code $toUpper : $name} that manifest as {@link org.bson.Document} when
  * passed on to the driver.
@@ -36,7 +34,7 @@
  * @see org.springframework.data.mongodb.core.aggregation.DateOperators
  * @see org.springframework.data.mongodb.core.aggregation.ObjectOperators
  * @see org.springframework.data.mongodb.core.aggregation.SetOperators
- * @see org.springframework.data.mongodb.core.aggregation.StringOperators @
+ * @see org.springframework.data.mongodb.core.aggregation.StringOperators
  */
 @FunctionalInterface
 public interface MongoExpression {
@@ -49,38 +47,27 @@ public interface MongoExpression {
 	org.bson.Document toDocument();
 
 	/**
-	 * Convert this instance to another expression applying the given conversion {@link Function}.
-	 *
-	 * @param function must not be {@literal null}.
-	 * @param <T>
-	 * @return never {@literal null}.
-	 */
-	default <T extends MongoExpression> T as(Function<MongoExpression, T> function) {
-		return function.apply(this);
-	}
-
-	/**
-	 * Create a new {@link MongoExpression} from plain String (eg. {@code $toUpper : $name}). <br />
-	 * The given source value will be wrapped with <code>{ }</code> to match an actual MongoDB {@link org.bson.Document}
+	 * Create a new {@link MongoExpression} from plain {@link String} (eg. {@code $toUpper : $name}). <br />
+	 * The given expression will be wrapped with <code>{ ... }</code> to match an actual MongoDB {@link org.bson.Document}
 	 * if necessary.
 	 *
-	 * @param json must not be {@literal null}.
+	 * @param expression must not be {@literal null}.
 	 * @return new instance of {@link MongoExpression}.
 	 */
-	static MongoExpression expressionFromString(String json) {
-		return new BindableMongoExpression(json, null);
+	static MongoExpression create(String expression) {
+		return new BindableMongoExpression(expression, null);
 	}
 
 	/**
-	 * Create a new {@link MongoExpression} from plain String containing placeholders (eg. {@code $toUpper : ?0}) that
-	 * will be resolved on {@link #toDocument()}. <br />
-	 * The given source value will be wrapped with <code>{ }</code> to match an actual MongoDB {@link org.bson.Document}
+	 * Create a new {@link MongoExpression} from plain {@link String} containing placeholders (eg. {@code $toUpper : ?0})
+	 * that will be resolved on first call of {@link #toDocument()}. <br />
+	 * The given expression will be wrapped with <code>{ ... }</code> to match an actual MongoDB {@link org.bson.Document}
 	 * if necessary.
 	 *
-	 * @param json must not be {@literal null}.
+	 * @param expression must not be {@literal null}.
 	 * @return new instance of {@link MongoExpression}.
 	 */
-	static MongoExpression expressionFromString(String json, Object... args) {
-		return new BindableMongoExpression(json, args);
+	static MongoExpression create(String expression, Object... args) {
+		return new BindableMongoExpression(expression, args);
 	}
 }

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

@@ -300,8 +300,7 @@ Document getMappedFields(@Nullable MongoPersistentEntity<?> entity, Class<?> tar
 					AggregationOperationContext ctx = entity == null ? Aggregation.DEFAULT_CONTEXT
 							: new RelaxedTypeBasedAggregationOperationContext(entity.getType(), mappingContext, queryMapper);
 
-					fields.put(entry.getKey(),
-							((MongoExpression) entry.getValue()).as(AggregationExpression::create).toDocument(ctx));
+					fields.put(entry.getKey(), AggregationExpression.from((MongoExpression) entry.getValue()).toDocument(ctx));
 				} else {
 					fields.put(entry.getKey(), entry.getValue());
 				}

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

@@ -41,14 +41,15 @@ default Document toDocument() {
 	}
 
 	/**
-	 * Create an {@link AggregationExpression} out of a given {@link MongoExpression}. <br />
-	 * If the given expression is already an {@link AggregationExpression} return the very same instance.
+	 * Create an {@link AggregationExpression} out of a given {@link MongoExpression} to ensure the resulting
+	 * {@link MongoExpression#toDocument() Document} is mapped against the {@link AggregationOperationContext}. <br />
+	 * If the given expression is already an {@link AggregationExpression} the very same instance is returned.
 	 *
 	 * @param expression must not be {@literal null}.
 	 * @return never {@literal null}.
 	 * @since 3.2
 	 */
-	static AggregationExpression create(MongoExpression expression) {
+	static AggregationExpression from(MongoExpression expression) {
 
 		if (expression instanceof AggregationExpression) {
 			return AggregationExpression.class.cast(expression);

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

@@ -68,7 +68,7 @@ void afterEach() {
 	void usesMongoExpressionAsIs() {
 
 		Person result = findLuke(fields -> {
-			fields.include("firstname").project(MongoExpression.expressionFromString("'$toUpper' : '$last_name'"))
+			fields.include("firstname").project(MongoExpression.create("'$toUpper' : '$last_name'"))
 					.as("last_name");
 		});
 
@@ -79,7 +79,7 @@ void usesMongoExpressionAsIs() {
 	void usesMongoExpressionWithPlaceholdersAsIs() {
 
 		Person result = findLuke(fields -> {
-			fields.include("firstname").project(MongoExpression.expressionFromString("'$toUpper' : '$?0'", "last_name"))
+			fields.include("firstname").project(MongoExpression.create("'$toUpper' : '$?0'", "last_name"))
 					.as("last_name");
 		});
 

src/main/asciidoc/reference/mongodb.adoc

@@ -1291,7 +1291,7 @@ Starting with MongoDB 4.4 it is possible to use the aggregation expressions synt
 [source,java]
 ----
 query.fields()
-  .project(MongoExpression.expressionFromString("'$toUpper' : '$last_name'")) <1>
+  .project(MongoExpression.create("'$toUpper' : '$last_name'")) <1>
   .as("last_name"); <2>
 
 query.fields()