Rename Embedded annotation to Unwrapped.

The meaning of embedding a Document in MongoDB is different compared to column based stores. Typically the term is used for a Document in Document approach and not for flattening out a values into the enclosing Document.

Closes: spring-projects#3600
Original pull request: spring-projects#3604.

Author: christophstrobl

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

@@ -62,10 +62,10 @@
 import org.springframework.data.mapping.model.SpELExpressionParameterValueProvider;
 import org.springframework.data.mongodb.CodecRegistryProvider;
 import org.springframework.data.mongodb.MongoDatabaseFactory;
-import org.springframework.data.mongodb.core.mapping.Embedded;
-import org.springframework.data.mongodb.core.mapping.Embedded.OnEmpty;
 import org.springframework.data.mongodb.core.mapping.MongoPersistentEntity;
 import org.springframework.data.mongodb.core.mapping.MongoPersistentProperty;
+import org.springframework.data.mongodb.core.mapping.Unwrapped;
+import org.springframework.data.mongodb.core.mapping.Unwrapped.OnEmpty;
 import org.springframework.data.mongodb.core.mapping.event.AfterConvertCallback;
 import org.springframework.data.mongodb.core.mapping.event.AfterConvertEvent;
 import org.springframework.data.mongodb.core.mapping.event.AfterLoadEvent;
@@ -447,10 +447,10 @@ private void readProperties(ConversionContext context, MongoPersistentEntity<?>
 				continue;
 			}
 
-			if (prop.isEmbedded()) {
+			if (prop.isUnwrapped()) {
 
 				accessor.setProperty(prop,
-						readEmbedded(context, documentAccessor, prop, mappingContext.getRequiredPersistentEntity(prop)));
+						readUnwrapped(context, documentAccessor, prop, mappingContext.getRequiredPersistentEntity(prop)));
 				continue;
 			}
 
@@ -500,17 +500,17 @@ private void readAssociation(Association<MongoPersistentProperty> association, P
 	}
 
 	@Nullable
-	private Object readEmbedded(ConversionContext context, DocumentAccessor documentAccessor,
+	private Object readUnwrapped(ConversionContext context, DocumentAccessor documentAccessor,
 			MongoPersistentProperty prop,
-			MongoPersistentEntity<?> embeddedEntity) {
+			MongoPersistentEntity<?> unwrappedEntity) {
 
-		if (prop.findAnnotation(Embedded.class).onEmpty().equals(OnEmpty.USE_EMPTY)) {
-			return read(context, embeddedEntity, (Document) documentAccessor.getDocument());
+		if (prop.findAnnotation(Unwrapped.class).onEmpty().equals(OnEmpty.USE_EMPTY)) {
+			return read(context, unwrappedEntity, (Document) documentAccessor.getDocument());
 		}
 
-		for (MongoPersistentProperty persistentProperty : embeddedEntity) {
+		for (MongoPersistentProperty persistentProperty : unwrappedEntity) {
 			if (documentAccessor.hasValue(persistentProperty)) {
-				return read(context, embeddedEntity, (Document) documentAccessor.getDocument());
+				return read(context, unwrappedEntity, (Document) documentAccessor.getDocument());
 			}
 		}
 		return null;
@@ -680,7 +680,7 @@ protected void writePropertyInternal(@Nullable Object obj, DocumentAccessor acce
 		TypeInformation<?> valueType = ClassTypeInformation.from(obj.getClass());
 		TypeInformation<?> type = prop.getTypeInformation();
 
-		if (prop.isEmbedded()) {
+		if (prop.isUnwrapped()) {
 
 			Document target = new Document();
 			writeInternal(obj, target, mappingContext.getPersistentEntity(prop));

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

@@ -144,7 +144,7 @@ public Document getMappedObject(Bson query, @Nullable MongoPersistentEntity<?> e
 				Field field = createPropertyField(entity, key, mappingContext);
 
 				// TODO: move to dedicated method
-				if (field.getProperty() != null && field.getProperty().isEmbedded()) {
+				if (field.getProperty() != null && field.getProperty().isUnwrapped()) {
 
 					Object theNestedObject = BsonUtils.get(query, key);
 					Document mappedValue = (Document) getMappedValue(field, theNestedObject);
@@ -189,13 +189,13 @@ public Document getMappedSort(Document sortObject, @Nullable MongoPersistentEnti
 			return new Document();
 		}
 
-		sortObject = filterEmbeddedObjects(sortObject, entity);
+		sortObject = filterUnwrappedObjects(sortObject, entity);
 
 		Document mappedSort = new Document();
 		for (Map.Entry<String, Object> entry : BsonUtils.asMap(sortObject).entrySet()) {
 
 			Field field = createPropertyField(entity, entry.getKey(), mappingContext);
-			if (field.getProperty() != null && field.getProperty().isEmbedded()) {
+			if (field.getProperty() != null && field.getProperty().isUnwrapped()) {
 				continue;
 			}
 
@@ -219,7 +219,7 @@ public Document getMappedFields(Document fieldsObject, @Nullable MongoPersistent
 
 		Assert.notNull(fieldsObject, "FieldsObject must not be null!");
 
-		fieldsObject = filterEmbeddedObjects(fieldsObject, entity);
+		fieldsObject = filterUnwrappedObjects(fieldsObject, entity);
 
 		Document mappedFields = getMappedObject(fieldsObject, entity);
 		mapMetaAttributes(mappedFields, entity, MetaMapping.FORCE);
@@ -241,7 +241,7 @@ private void mapMetaAttributes(Document source, @Nullable MongoPersistentEntity<
 		}
 	}
 
-	private Document filterEmbeddedObjects(Document fieldsObject, @Nullable MongoPersistentEntity<?> entity) {
+	private Document filterUnwrappedObjects(Document fieldsObject, @Nullable MongoPersistentEntity<?> entity) {
 
 		if (fieldsObject.isEmpty() || entity == null) {
 			return fieldsObject;
@@ -258,13 +258,13 @@ private Document filterEmbeddedObjects(Document fieldsObject, @Nullable MongoPer
 						.getPersistentPropertyPath(path);
 				MongoPersistentProperty property = mappingContext.getPersistentPropertyPath(path).getRequiredLeafProperty();
 
-				if (property.isEmbedded() && property.isEntity()) {
+				if (property.isUnwrapped() && property.isEntity()) {
 
-					MongoPersistentEntity<?> embeddedEntity = mappingContext.getRequiredPersistentEntity(property);
+					MongoPersistentEntity<?> unwrappedEntity = mappingContext.getRequiredPersistentEntity(property);
 
-					for (MongoPersistentProperty embedded : embeddedEntity) {
+					for (MongoPersistentProperty unwrappedProperty : unwrappedEntity) {
 
-						DotPath dotPath = DotPath.from(persistentPropertyPath.toDotPath()).append(embedded.getName());
+						DotPath dotPath = DotPath.from(persistentPropertyPath.toDotPath()).append(unwrappedProperty.getName());
 						target.put(dotPath.toString(), field.getValue());
 					}
 
@@ -564,7 +564,7 @@ protected Object convertSimpleOrDocument(Object source, @Nullable MongoPersisten
 	@Nullable
 	protected Object delegateConvertToMongoType(Object source, @Nullable MongoPersistentEntity<?> entity) {
 
-		if (entity != null && entity.isEmbedded()) {
+		if (entity != null && entity.isUnwrapped()) {
 			return converter.convertToMongoType(source, entity);
 		}
 

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

@@ -133,7 +133,7 @@ public static boolean isUpdateObject(@Nullable Document updateObj) {
 	@Override
 	protected Object delegateConvertToMongoType(Object source, @Nullable MongoPersistentEntity<?> entity) {
 
-		if(entity != null && entity.isEmbedded()) {
+		if(entity != null && entity.isUnwrapped()) {
 			return converter.convertToMongoType(source, entity);
 		}
 

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

@@ -137,7 +137,7 @@ private void potentiallyAddIndexForProperty(MongoPersistentEntity<?> root, Mongo
 		try {
 			if (persistentProperty.isEntity()) {
 				indexes.addAll(resolveIndexForEntity(mappingContext.getPersistentEntity(persistentProperty),
-						persistentProperty.isEmbedded() ? "" : persistentProperty.getFieldName(), Path.of(persistentProperty),
+						persistentProperty.isUnwrapped() ? "" : persistentProperty.getFieldName(), Path.of(persistentProperty),
 						root.getCollection(), guard));
 			}
 
@@ -187,7 +187,7 @@ private void guardAndPotentiallyAddIndexForProperty(MongoPersistentProperty pers
 
 		DotPath propertyDotPath = DotPath.from(dotPath);
 
-		if (!persistentProperty.isEmbedded()) {
+		if (!persistentProperty.isUnwrapped()) {
 			propertyDotPath = propertyDotPath.append(persistentProperty.getFieldName());
 		}
 
@@ -216,11 +216,11 @@ private List<IndexDefinitionHolder> createIndexDefinitionHolderForProperty(Strin
 
 		List<IndexDefinitionHolder> indices = new ArrayList<>(2);
 
-		if (persistentProperty.isEmbedded() && (persistentProperty.isAnnotationPresent(Indexed.class)
+		if (persistentProperty.isUnwrapped() && (persistentProperty.isAnnotationPresent(Indexed.class)
 				|| persistentProperty.isAnnotationPresent(HashIndexed.class)
 				|| persistentProperty.isAnnotationPresent(GeoSpatialIndexed.class))) {
 			throw new InvalidDataAccessApiUsageException(
-					String.format("Index annotation not allowed on embedded object for path '%s'.", dotPath));
+					String.format("Index annotation not allowed on unwrapped object for path '%s'.", dotPath));
 		}
 
 		if (persistentProperty.isAnnotationPresent(Indexed.class)) {

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

@@ -133,10 +133,10 @@ public MongoPersistentEntity<?> getPersistentEntity(MongoPersistentProperty pers
 
 		MongoPersistentEntity<?> entity = super.getPersistentEntity(persistentProperty);
 
-		if(entity == null || !persistentProperty.isEmbedded()) {
+		if(entity == null || !persistentProperty.isUnwrapped()) {
 			return entity;
 		}
 
-		return new EmbeddedMongoPersistentEntity<>(entity, new EmbeddedEntityContext(persistentProperty));
+		return new UnwrappedMongoPersistentEntity<>(entity, new UnwrapEntityContext(persistentProperty));
 	}
 }

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

@@ -95,10 +95,10 @@ default boolean isSharded() {
 	}
 
 	/**
-	 * @return {@literal true} if the entity should be embedded.
+	 * @return {@literal true} if the entity should be unwrapped.
 	 * @since 3.2
 	 */
-	default boolean isEmbedded() {
+	default boolean isUnwrapped() {
 		return false;
 	}
 

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

@@ -124,11 +124,11 @@ default boolean hasExplicitWriteTarget() {
 	}
 
 	/**
-	 * @return {@literal true} if the property should be embedded.
+	 * @return {@literal true} if the property should be unwrapped.
 	 * @since 3.2
 	 */
-	default boolean isEmbedded() {
-		return isEntity() && isAnnotationPresent(Embedded.class);
+	default boolean isUnwrapped() {
+		return isEntity() && isAnnotationPresent(Unwrapped.class);
 	}
 
 	/**
@@ -145,7 +145,7 @@ enum PropertyToFieldNameConverter implements Converter<MongoPersistentProperty,
 		 * @see org.springframework.core.convert.converter.Converter#convert(java.lang.Object)
 		 */
 		public String convert(MongoPersistentProperty source) {
-			if (!source.isEmbedded()) {
+			if (!source.isUnwrapped()) {
 				return source.getFieldName();
 			}
 			return "";

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/mapping/EmbeddedEntityContext.java renamed to spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/mapping/UnwrapEntityContext.java

@@ -19,11 +19,11 @@
  * @author Christoph Strobl
  * @since 3.2
  */
-class EmbeddedEntityContext {
+class UnwrapEntityContext {
 
 	private final MongoPersistentProperty property;
 
-	public EmbeddedEntityContext(MongoPersistentProperty property) {
+	public UnwrapEntityContext(MongoPersistentProperty property) {
 		this.property = property;
 	}
 

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/mapping/Embedded.java renamed to spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/mapping/Unwrapped.java

@@ -26,35 +26,35 @@
 import org.springframework.core.annotation.AliasFor;
 
 /**
- * The annotation to configure a value object as embedded (flattened out) in the target document.
+ * The annotation to configure a value object as flattened out in the target document.
  * <p />
  * Depending on the {@link OnEmpty value} of {@link #onEmpty()} the property is set to {@literal null} or an empty
- * instance in the case all embedded values are {@literal null} when reading from the result set.
+ * instance in the case all unwrapped values are {@literal null} when reading from the result set.
  *
  * @author Christoph Strobl
  * @since 3.2
  */
 @Documented
 @Retention(value = RetentionPolicy.RUNTIME)
 @Target(value = { ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.METHOD })
-public @interface Embedded {
+public @interface Unwrapped {
 
 	/**
-	 * Set the load strategy for the embedded object if all contained fields yield {@literal null} values.
+	 * Set the load strategy for the unwrapped object if all contained fields yield {@literal null} values.
 	 * <p />
-	 * {@link Nullable @Embedded.Nullable} and {@link Empty @Embedded.Empty} offer shortcuts for this.
+	 * {@link Nullable @Unwrapped.Nullable} and {@link Empty @Unwrapped.Empty} offer shortcuts for this.
 	 *
 	 * @return never {@link} null.
 	 */
 	OnEmpty onEmpty();
 
 	/**
-	 * @return prefix for columns in the embedded value object. An empty {@link String} by default.
+	 * @return prefix for columns in the unwrapped value object. An empty {@link String} by default.
 	 */
 	String prefix() default "";
 
 	/**
-	 * Load strategy to be used {@link Embedded#onEmpty()}.
+	 * Load strategy to be used {@link Unwrapped#onEmpty()}.
 	 *
 	 * @author Christoph Strobl
 	 */
@@ -63,74 +63,74 @@ enum OnEmpty {
 	}
 
 	/**
-	 * Shortcut for a nullable embedded property.
+	 * Shortcut for a nullable unwrapped property.
 	 *
 	 * <pre class="code">
-	 * &#64;Embedded.Nullable private Address address;
+	 * &#64;Unwrapped.Nullable private Address address;
 	 * </pre>
 	 *
 	 * as alternative to the more verbose
 	 *
 	 * <pre class="code">
-	 * &#64;Embedded(onEmpty = USE_NULL) &#64;javax.annotation.Nonnull(when = When.MAYBE) private Address address;
+	 * &#64;Unwrapped(onEmpty = USE_NULL) &#64;javax.annotation.Nonnull(when = When.MAYBE) private Address address;
 	 * </pre>
 	 *
 	 * @author Christoph Strobl
-	 * @see Embedded#onEmpty()
+	 * @see Unwrapped#onEmpty()
 	 */
-	@Embedded(onEmpty = OnEmpty.USE_NULL)
+	@Unwrapped(onEmpty = OnEmpty.USE_NULL)
 	@Documented
 	@Retention(RetentionPolicy.RUNTIME)
 	@Target({ ElementType.FIELD, ElementType.METHOD })
 	@javax.annotation.Nonnull(when = When.MAYBE)
 	@interface Nullable {
 
 		/**
-		 * @return prefix for columns in the embedded value object. An empty {@link String} by default.
+		 * @return prefix for columns in the unwrapped value object. An empty {@link String} by default.
 		 */
-		@AliasFor(annotation = Embedded.class, attribute = "prefix")
+		@AliasFor(annotation = Unwrapped.class, attribute = "prefix")
 		String prefix() default "";
 
 		/**
-		 * @return value for columns in the embedded value object. An empty {@link String} by default.
+		 * @return value for columns in the unwrapped value object. An empty {@link String} by default.
 		 */
-		@AliasFor(annotation = Embedded.class, attribute = "prefix")
+		@AliasFor(annotation = Unwrapped.class, attribute = "prefix")
 		String value() default "";
 	}
 
 	/**
-	 * Shortcut for an empty embedded property.
+	 * Shortcut for an empty unwrapped property.
 	 *
 	 * <pre class="code">
-	 * &#64;Embedded.Empty private Address address;
+	 * &#64;Unwrapped.Empty private Address address;
 	 * </pre>
 	 *
 	 * as alternative to the more verbose
 	 *
 	 * <pre class="code">
-	 * &#64;Embedded(onEmpty = USE_EMPTY) &#64;javax.annotation.Nonnull(when = When.NEVER) private Address address;
+	 * &#64;Unwrapped(onEmpty = USE_EMPTY) &#64;javax.annotation.Nonnull(when = When.NEVER) private Address address;
 	 * </pre>
 	 *
 	 * @author Christoph Strobl
-	 * @see Embedded#onEmpty()
+	 * @see Unwrapped#onEmpty()
 	 */
-	@Embedded(onEmpty = OnEmpty.USE_EMPTY)
+	@Unwrapped(onEmpty = OnEmpty.USE_EMPTY)
 	@Documented
 	@Retention(RetentionPolicy.RUNTIME)
 	@Target({ ElementType.FIELD, ElementType.METHOD })
 	@javax.annotation.Nonnull(when = When.NEVER)
 	@interface Empty {
 
 		/**
-		 * @return prefix for columns in the embedded value object. An empty {@link String} by default.
+		 * @return prefix for columns in the unwrapped value object. An empty {@link String} by default.
 		 */
-		@AliasFor(annotation = Embedded.class, attribute = "prefix")
+		@AliasFor(annotation = Unwrapped.class, attribute = "prefix")
 		String prefix() default "";
 
 		/**
-		 * @return value for columns in the embedded value object. An empty {@link String} by default.
+		 * @return value for columns in the unwrapped value object. An empty {@link String} by default.
 		 */
-		@AliasFor(annotation = Embedded.class, attribute = "prefix")
+		@AliasFor(annotation = Unwrapped.class, attribute = "prefix")
 		String value() default "";
 	}
 }