Polishing of annotation model for object creators.

Move to @PersistenceCreator as canonical annotation to explicitly express constructors and methods to be used to create domain object instances from persistence operations. Removed @factorymethod as it's not needed anymore. @PersistenceConstructor is now deprecated.

Renamed EntityCreatorMetadata(Support|Discoverer) to InstanceCreatorMetadata(Support|Discoverer) to avoid further manifestation of the notion of an entity in the metamodel as it's not used to only handle entities.

Author: odrotbohm

src/main/asciidoc/object-mapping.adoc

@@ -17,9 +17,9 @@ This means we need two fundamental steps:
 Spring Data automatically tries to detect a persistent entity's constructor to be used to materialize objects of that type.
 The resolution algorithm works as follows:
 
-1. If there is a single static factory method annotated with `@FactoryMethod` then it is used.
+1. If there is a single static factory method annotated with `@PersistenceCreator` then it is used.
 2. If there is a single constructor, it is used.
-3. If there are multiple constructors and exactly one is annotated with `@PersistenceConstructor`, it is used.
+3. If there are multiple constructors and exactly one is annotated with `@PersistenceCreator`, it is used.
 4. If there's a no-argument constructor, it is used.
 Other constructors will be ignored.
 
@@ -205,9 +205,9 @@ Even if the intent is that the calculation should be preferred, it's important t
 <4> The `comment` property is mutable is populated by setting its field directly.
 <5> The `remarks` properties are mutable and populated by setting the `comment` field directly or by invoking the setter method for
 <6> The class exposes a factory method and a constructor for object creation.
-The core idea here is to use factory methods instead of additional constructors to avoid the need for constructor disambiguation through `@PersistenceConstructor`.
+The core idea here is to use factory methods instead of additional constructors to avoid the need for constructor disambiguation through `@PersistenceCreator`.
 Instead, defaulting of properties is handled within the factory method.
-If you want Spring Data to use the factory method for object instantiation, annotate it with `@FactoryMethod`.
+If you want Spring Data to use the factory method for object instantiation, annotate it with `@PersistenceCreator`.
 
 [[mapping.general-recommendations]]
 == General recommendations
@@ -217,7 +217,7 @@ Also, this avoids your domain objects to be littered with setter methods that al
 If you need those, prefer to make them package protected so that they can only be invoked by a limited amount of co-located types.
 Constructor-only materialization is up to 30% faster than properties population.
 * _Provide an all-args constructor_ -- Even if you cannot or don't want to model your entities as immutable values, there's still value in providing a constructor that takes all properties of the entity as arguments, including the mutable ones, as this allows the object mapping to skip the property population for optimal performance.
-* _Use factory methods instead of overloaded constructors to avoid ``@PersistenceConstructor``_ -- With an all-argument constructor needed for optimal performance, we usually want to expose more application use case specific constructors that omit things like auto-generated identifiers etc.
+* _Use factory methods instead of overloaded constructors to avoid ``@PersistenceCreator``_ -- With an all-argument constructor needed for optimal performance, we usually want to expose more application use case specific constructors that omit things like auto-generated identifiers etc.
 It's an established pattern to rather use static factory methods to expose these variants of the all-args constructor.
 * _Make sure you adhere to the constraints that allow the generated instantiator and property accessor classes to be used_ --
 * _For identifiers to be generated, still use a final field in combination with an all-arguments persistence constructor (preferred) or a `with…` method_ --
@@ -307,14 +307,14 @@ data class Person(val id: String, val name: String)
 ----
 ====
 
-The class above compiles to a typical class with an explicit constructor.We can customize this class by adding another constructor and annotate it with `@PersistenceConstructor` to indicate a constructor preference:
+The class above compiles to a typical class with an explicit constructor.We can customize this class by adding another constructor and annotate it with `@PersistenceCreator` to indicate a constructor preference:
 
 ====
 [source,kotlin]
 ----
 data class Person(var id: String, val name: String) {
 
-    @PersistenceConstructor
+    @PersistenceCreator
     constructor(id: String) : this(id, "unknown")
 }
 ----

src/main/java/org/springframework/data/annotation/FactoryMethod.java

@@ -25,9 +25,11 @@
  *
  * @author Jon Brisbin
  * @author Mark Paluch
+ * @author Oliver Drotbohm
+ * @deprecated in favor of {@link EntityCreatorAnnotation} since 3.0, to be removed in 3.1
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.CONSTRUCTOR, ElementType.ANNOTATION_TYPE })
-@EntityCreatorAnnotation
-public @interface PersistenceConstructor {
-}
+@PersistenceCreator
+@Deprecated
+public @interface PersistenceConstructor {}

src/main/java/org/springframework/data/annotation/PersistenceConstructor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011-2021 the original author or authors.
+ * Copyright 2011-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.
@@ -24,9 +24,9 @@
  * Marker annotation to declare a constructor or factory method annotation as factory/preferred constructor annotation.
  *
  * @author Mark Paluch
+ * @author Oliver Drotbohm
  * @since 3.0
  */
 @Retention(RetentionPolicy.RUNTIME)
-@Target({ ElementType.ANNOTATION_TYPE })
-public @interface EntityCreatorAnnotation {
-}
+@Target({ ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+public @interface PersistenceCreator {}

src/main/java/org/springframework/data/annotation/EntityCreatorAnnotation.java renamed to src/main/java/org/springframework/data/annotation/PersistenceCreator.java

@@ -26,7 +26,7 @@
  * @author Mark Paluch
  * @since 3.0
  */
-public final class FactoryMethod<T, P extends PersistentProperty<P>> extends EntityCreatorMetadataSupport<T, P> {
+public final class FactoryMethod<T, P extends PersistentProperty<P>> extends InstanceCreatorMetadataSupport<T, P> {
 
 	/**
 	 * Creates a new {@link FactoryMethod} from the given {@link Constructor} and {@link Parameter}s.
@@ -49,5 +49,4 @@ public FactoryMethod(Method factoryMethod, Parameter<Object, P>... parameters) {
 	public Method getFactoryMethod() {
 		return (Method) getExecutable();
 	}
-
 }

src/main/java/org/springframework/data/mapping/FactoryMethod.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021 the original author or authors.
+ * Copyright 2021-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.
@@ -18,12 +18,13 @@
 import java.util.List;
 
 /**
- * Metadata describing a mechanism to create an entity instance.
+ * Metadata describing a mechanism to create instances of persistent types.
  *
  * @author Mark Paluch
+ * @author Oliver Drotbohm
  * @since 3.0
  */
-public interface EntityCreatorMetadata<P extends PersistentProperty<P>> {
+public interface InstanceCreatorMetadata<P extends PersistentProperty<P>> {
 
 	/**
 	 * Check whether the given {@link PersistentProperty} is being used as creator parameter.

src/main/java/org/springframework/data/mapping/EntityCreatorMetadata.java renamed to src/main/java/org/springframework/data/mapping/InstanceCreatorMetadata.java

@@ -28,22 +28,23 @@
  * persistent data to objects.
  *
  * @author Mark Paluch
+ * @author Oliver Drotbohm
  * @since 3.0
  */
-class EntityCreatorMetadataSupport<T, P extends PersistentProperty<P>> implements EntityCreatorMetadata<P> {
+class InstanceCreatorMetadataSupport<T, P extends PersistentProperty<P>> implements InstanceCreatorMetadata<P> {
 
 	private final Executable executable;
 	private final List<Parameter<Object, P>> parameters;
 	private final Map<PersistentProperty<?>, Boolean> isPropertyParameterCache = new ConcurrentHashMap<>();
 
 	/**
-	 * Creates a new {@link EntityCreatorMetadataSupport} from the given {@link Executable} and {@link Parameter}s.
+	 * Creates a new {@link InstanceCreatorMetadataSupport} from the given {@link Executable} and {@link Parameter}s.
 	 *
 	 * @param executable must not be {@literal null}.
 	 * @param parameters must not be {@literal null}.
 	 */
 	@SafeVarargs
-	public EntityCreatorMetadataSupport(Executable executable, Parameter<Object, P>... parameters) {
+	public InstanceCreatorMetadataSupport(Executable executable, Parameter<Object, P>... parameters) {
 
 		Assert.notNull(executable, "Executable must not be null!");
 		Assert.notNull(parameters, "Parameters must not be null!");
@@ -72,7 +73,7 @@ public List<Parameter<Object, P>> getParameters() {
 
 	/**
 	 * Returns whether the given {@link PersistentProperty} is referenced in a creator argument of the
-	 * {@link PersistentEntity} backing this {@link EntityCreatorMetadataSupport}.
+	 * {@link PersistentEntity} backing this {@link InstanceCreatorMetadataSupport}.
 	 * <p>
 	 * Results of this call are cached and reused on the next invocation. Calling this method for a
 	 * {@link PersistentProperty} that was not yet added to its owning {@link PersistentEntity} will capture that state

src/main/java/org/springframework/data/mapping/EntityCreatorMetadataSupport.java renamed to src/main/java/org/springframework/data/mapping/InstanceCreatorMetadataSupport.java

@@ -56,7 +56,7 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> extends It
 	PreferredConstructor<T, P> getPersistenceConstructor();
 
 	/**
-	 * Returns the {@link EntityCreatorMetadata} to be used to instantiate objects of this {@link PersistentEntity}.
+	 * Returns the {@link InstanceCreatorMetadata} to be used to instantiate objects of this {@link PersistentEntity}.
 	 *
 	 * @return {@literal null} in case no suitable creation mechanism for automatic construction can be found. This
 	 *         usually indicates that the instantiation of the object of that persistent entity is done through either a
@@ -65,7 +65,7 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> extends It
 	 * @since 3.0
 	 */
 	@Nullable
-	EntityCreatorMetadata<P> getEntityCreator();
+	InstanceCreatorMetadata<P> getEntityCreator();
 
 	/**
 	 * Returns whether the given {@link PersistentProperty} is referred to by a constructor argument of the

src/main/java/org/springframework/data/mapping/PersistentEntity.java

@@ -35,7 +35,7 @@
  * @author Myeonghyeon Lee
  * @author Xeno Amess
  */
-public final class PreferredConstructor<T, P extends PersistentProperty<P>> extends EntityCreatorMetadataSupport<T, P> {
+public final class PreferredConstructor<T, P extends PersistentProperty<P>> extends InstanceCreatorMetadataSupport<T, P> {
 
 	private final List<Parameter<Object, P>> parameters;
 

src/main/java/org/springframework/data/mapping/PreferredConstructor.java

@@ -63,7 +63,7 @@ public class BasicPersistentEntity<T, P extends PersistentProperty<P>> implement
 
 	private static final String TYPE_MISMATCH = "Target bean of type %s is not of type of the persistent entity (%s)!";
 
-	private final @Nullable EntityCreatorMetadata<P> creator;
+	private final @Nullable InstanceCreatorMetadata<P> creator;
 	private final TypeInformation<T> information;
 	private final List<P> properties;
 	private final List<P> persistentPropertiesCache;
@@ -109,7 +109,7 @@ public BasicPersistentEntity(TypeInformation<T> information, @Nullable Comparato
 		this.properties = new ArrayList<>();
 		this.persistentPropertiesCache = new ArrayList<>();
 		this.comparator = comparator;
-		this.creator = EntityCreatorMetadataDiscoverer.discover(this);
+		this.creator = InstanceCreatorMetadataDiscoverer.discover(this);
 		this.associations = comparator == null ? new HashSet<>() : new TreeSet<>(new AssociationComparator<>(comparator));
 
 		this.propertyCache = new HashMap<>(16, 1f);
@@ -134,7 +134,7 @@ public PreferredConstructor<T, P> getPersistenceConstructor() {
 	}
 
 	@Override
-	public EntityCreatorMetadata<P> getEntityCreator() {
+	public InstanceCreatorMetadata<P> getEntityCreator() {
 		return creator;
 	}
 

src/main/java/org/springframework/data/mapping/model/BasicPersistentEntity.java

@@ -33,7 +33,7 @@
 import org.springframework.beans.BeanInstantiationException;
 import org.springframework.cglib.core.ReflectUtils;
 import org.springframework.core.NativeDetector;
-import org.springframework.data.mapping.EntityCreatorMetadata;
+import org.springframework.data.mapping.InstanceCreatorMetadata;
 import org.springframework.data.mapping.FactoryMethod;
 import org.springframework.data.mapping.Parameter;
 import org.springframework.data.mapping.PersistentEntity;
@@ -227,15 +227,15 @@ static Object[] allocateArguments(int argumentCount) {
 
 	/**
 	 * Creates a dynamically generated {@link ObjectInstantiator} for the given {@link PersistentEntity} and
-	 * {@link EntityCreatorMetadata}. There will always be exactly one {@link ObjectInstantiator} instance per
+	 * {@link InstanceCreatorMetadata}. There will always be exactly one {@link ObjectInstantiator} instance per
 	 * {@link PersistentEntity}.
 	 *
 	 * @param entity
 	 * @param constructor
 	 * @return
 	 */
 	ObjectInstantiator createObjectInstantiator(PersistentEntity<?, ?> entity,
-			@Nullable EntityCreatorMetadata<?> constructor) {
+			@Nullable InstanceCreatorMetadata<?> constructor) {
 
 		try {
 			return (ObjectInstantiator) this.generator.generateCustomInstantiatorClass(entity, constructor).newInstance();
@@ -287,7 +287,7 @@ public <T, E extends PersistentEntity<? extends T, P>, P extends PersistentPrope
 	 * @return
 	 */
 	static <P extends PersistentProperty<P>, T> Object[] extractInvocationArguments(
-			@Nullable EntityCreatorMetadata<P> constructor, ParameterValueProvider<P> provider) {
+			@Nullable InstanceCreatorMetadata<P> constructor, ParameterValueProvider<P> provider) {
 
 		if (constructor == null || !constructor.hasParameters()) {
 			return allocateArguments(0);
@@ -400,7 +400,7 @@ static class ObjectInstantiatorClassGenerator {
 		 * @return
 		 */
 		public Class<?> generateCustomInstantiatorClass(PersistentEntity<?, ?> entity,
-				@Nullable EntityCreatorMetadata<?> constructor) {
+				@Nullable InstanceCreatorMetadata<?> constructor) {
 
 			var className = generateClassName(entity);
 			var type = entity.getType();
@@ -441,7 +441,7 @@ private String generateClassName(PersistentEntity<?, ?> entity) {
 		 * @return
 		 */
 		public byte[] generateBytecode(String internalClassName, PersistentEntity<?, ?> entity,
-				@Nullable EntityCreatorMetadata<?> entityCreator) {
+				@Nullable InstanceCreatorMetadata<?> entityCreator) {
 
 			var cw = new ClassWriter(ClassWriter.COMPUTE_MAXS);
 
@@ -476,7 +476,7 @@ private void visitDefaultConstructor(ClassWriter cw) {
 		 * @param entityCreator
 		 */
 		private void visitCreateMethod(ClassWriter cw, PersistentEntity<?, ?> entity,
-				@Nullable EntityCreatorMetadata<?> entityCreator) {
+				@Nullable InstanceCreatorMetadata<?> entityCreator) {
 
 			var entityTypeResourcePath = Type.getInternalName(entity.getType());
 

src/main/java/org/springframework/data/mapping/model/ClassGeneratingEntityInstantiator.java

@@ -25,8 +25,8 @@
 import org.springframework.core.DefaultParameterNameDiscoverer;
 import org.springframework.core.ParameterNameDiscoverer;
 import org.springframework.core.annotation.MergedAnnotations;
-import org.springframework.data.annotation.EntityCreatorAnnotation;
-import org.springframework.data.mapping.EntityCreatorMetadata;
+import org.springframework.data.annotation.PersistenceCreator;
+import org.springframework.data.mapping.InstanceCreatorMetadata;
 import org.springframework.data.mapping.FactoryMethod;
 import org.springframework.data.mapping.MappingException;
 import org.springframework.data.mapping.Parameter;
@@ -40,7 +40,7 @@
  * @author Mark Paluch
  * @since 3.0
  */
-class EntityCreatorMetadataDiscoverer {
+class InstanceCreatorMetadataDiscoverer {
 
 	private static final ParameterNameDiscoverer PARAMETER_NAME_DISCOVERER = new DefaultParameterNameDiscoverer();
 
@@ -53,13 +53,13 @@ class EntityCreatorMetadataDiscoverer {
 	 * @return
 	 */
 	@Nullable
-	public static <T, P extends PersistentProperty<P>> EntityCreatorMetadata<P> discover(PersistentEntity<T, P> entity) {
+	public static <T, P extends PersistentProperty<P>> InstanceCreatorMetadata<P> discover(PersistentEntity<T, P> entity) {
 
 		var declaredConstructors = entity.getType().getDeclaredConstructors();
 		var declaredMethods = entity.getType().getDeclaredMethods();
 
-		var hasAnnotatedFactoryMethod = findAnnotation(EntityCreatorAnnotation.class, declaredMethods);
-		var hasAnnotatedConstructor = findAnnotation(EntityCreatorAnnotation.class, declaredConstructors);
+		var hasAnnotatedFactoryMethod = findAnnotation(PersistenceCreator.class, declaredMethods);
+		var hasAnnotatedConstructor = findAnnotation(PersistenceCreator.class, declaredConstructors);
 
 		if (hasAnnotatedConstructor && hasAnnotatedFactoryMethod) {
 			throw new MappingException(
@@ -92,7 +92,7 @@ private static <T, P extends PersistentProperty<P>> List<Method> discoverFactory
 				continue;
 			}
 
-			if (findAnnotation(EntityCreatorAnnotation.class, method)) {
+			if (findAnnotation(PersistenceCreator.class, method)) {
 				candidates.add(method);
 			}
 		}
@@ -124,11 +124,11 @@ private static <T, P extends PersistentProperty<P>> FactoryMethod<Object, P> get
 
 	private static void validateMethod(Method method) {
 
-		if (MergedAnnotations.from(method).isPresent(EntityCreatorAnnotation.class)) {
+		if (MergedAnnotations.from(method).isPresent(PersistenceCreator.class)) {
 
 			if (!Modifier.isStatic(method.getModifiers())) {
 				throw new MappingException(
-						"@Factory can only be used on static methods. Offending method: %s".formatted(method));
+						"@PersistenceCreator can only be used on static methods. Offending method: %s".formatted(method));
 			}
 		}
 	}

src/main/java/org/springframework/data/mapping/model/EntityCreatorMetadataDiscoverer.java renamed to src/main/java/org/springframework/data/mapping/model/InstanceCreatorMetadataDiscoverer.java

@@ -24,7 +24,7 @@
 import java.util.List;
 import java.util.stream.IntStream;
 
-import org.springframework.data.mapping.EntityCreatorMetadata;
+import org.springframework.data.mapping.InstanceCreatorMetadata;
 import org.springframework.data.mapping.Parameter;
 import org.springframework.data.mapping.PersistentEntity;
 import org.springframework.data.mapping.PersistentProperty;
@@ -201,7 +201,7 @@ public <T, E extends PersistentEntity<? extends T, P>, P extends PersistentPrope
 		}
 
 		private <P extends PersistentProperty<P>, T> Object[] extractInvocationArguments(
-				@Nullable EntityCreatorMetadata<P> entityCreator, ParameterValueProvider<P> provider) {
+				@Nullable InstanceCreatorMetadata<P> entityCreator, ParameterValueProvider<P> provider) {
 
 			if (entityCreator == null) {
 				throw new IllegalArgumentException("EntityCreator must not be null!");