Introduce support to create domain objects via factory methods.

Issue #2476.

Author: mp911de

src/main/asciidoc/object-mapping.adoc

@@ -17,12 +17,13 @@ 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 constructor, it is used.
-2. If there are multiple constructors and exactly one is annotated with `@PersistenceConstructor`, it is used.
-3. If there's a no-argument constructor, it is used.
+1. If there is a single static factory method annotated with `@FactoryMethod` 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.
+4. If there's a no-argument constructor, it is used.
 Other constructors will be ignored.
 
-The value resolution assumes constructor argument names to match the property names of the entity, i.e. the resolution will be performed as if the property was to be populated, including all customizations in mapping (different datastore column or field name etc.).
+The value resolution assumes constructor/factory method argument names to match the property names of the entity, i.e. the resolution will be performed as if the property was to be populated, including all customizations in mapping (different datastore column or field name etc.).
 This also requires either parameter names information available in the class file or an `@ConstructorProperties` annotation being present on the constructor.
 
 The value resolution can be customized by using Spring Framework's `@Value` value annotation using a store-specific SpEL expression.
@@ -206,6 +207,7 @@ Even if the intent is that the calculation should be preferred, it's important t
 <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`.
 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`.
 
 [[mapping.general-recommendations]]
 == General recommendations

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

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2011-2021 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marker annotation to declare a constructor or factory method annotation as factory/preferred constructor annotation.
+ *
+ * @author Mark Paluch
+ * @since 3.0
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.ANNOTATION_TYPE })
+public @interface EntityCreatorAnnotation {
+}

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

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2011-2021 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation to declare a {@code static} method as factory method for class instantiation.
+ *
+ * @author Mark Paluch
+ * @since 3.0
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+@EntityCreatorAnnotation
+public @interface FactoryMethod {
+}

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

@@ -21,9 +21,13 @@
 import java.lang.annotation.Target;
 
 /**
+ * Annotation to declare a constructor for instantiation.
+ *
  * @author Jon Brisbin
+ * @author Mark Paluch
  */
 @Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.CONSTRUCTOR)
+@Target({ ElementType.CONSTRUCTOR, ElementType.ANNOTATION_TYPE })
+@EntityCreatorAnnotation
 public @interface PersistenceConstructor {
 }

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

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2021 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.mapping;
+
+import java.util.List;
+
+/**
+ * Metadata describing a mechanism to create an entity instance.
+ *
+ * @author Mark Paluch
+ * @since 3.0
+ */
+public interface EntityCreatorMetadata<P extends PersistentProperty<P>> {
+
+	/**
+	 * Check whether the given {@link PersistentProperty} is being used as creator parameter.
+	 *
+	 * @param property
+	 * @return
+	 */
+	boolean isCreatorParameter(PersistentProperty<?> property);
+
+	/**
+	 * Returns whether the given {@link Parameter} is one referring to parent value (such as an enclosing class or a
+	 * receiver parameter).
+	 *
+	 * @param parameter
+	 * @return
+	 */
+	default boolean isParentParameter(Parameter<?, P> parameter) {
+		return false;
+	}
+
+	/**
+	 * @return the number of parameters.
+	 */
+	default int getParameterCount() {
+		return getParameters().size();
+	}
+
+	/**
+	 * @return the parameters used by this creator.
+	 */
+	List<Parameter<Object, P>> getParameters();
+
+	/**
+	 * @return whether the creator accepts {@link Parameter}s.
+	 */
+	default boolean hasParameters() {
+		return !getParameters().isEmpty();
+	}
+}

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

@@ -0,0 +1,117 @@
+/*
+ * Copyright 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.mapping;
+
+import java.lang.reflect.Executable;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+import org.springframework.util.Assert;
+
+/**
+ * Value object to encapsulate the entity creation mechanism through a {@link Executable} to be used when mapping
+ * persistent data to objects.
+ *
+ * @author Mark Paluch
+ * @since 3.0
+ */
+class EntityCreatorMetadataSupport<T, P extends PersistentProperty<P>> implements EntityCreatorMetadata<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.
+	 *
+	 * @param executable must not be {@literal null}.
+	 * @param parameters must not be {@literal null}.
+	 */
+	@SafeVarargs
+	public EntityCreatorMetadataSupport(Executable executable, Parameter<Object, P>... parameters) {
+
+		Assert.notNull(executable, "Executable must not be null!");
+		Assert.notNull(parameters, "Parameters must not be null!");
+
+		this.executable = executable;
+		this.parameters = Arrays.asList(parameters);
+	}
+
+	/**
+	 * Returns the underlying {@link Executable} that can be invoked reflectively.
+	 *
+	 * @return
+	 */
+	Executable getExecutable() {
+		return executable;
+	}
+
+	/**
+	 * Returns the {@link Parameter}s of the executable.
+	 *
+	 * @return
+	 */
+	public List<Parameter<Object, P>> getParameters() {
+		return parameters;
+	}
+
+	/**
+	 * Returns whether the given {@link PersistentProperty} is referenced in a creator argument of the
+	 * {@link PersistentEntity} backing this {@link EntityCreatorMetadataSupport}.
+	 * <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
+	 * and return the same result after adding {@link PersistentProperty} to its entity.
+	 *
+	 * @param property must not be {@literal null}.
+	 * @return {@literal true} if the {@link PersistentProperty} is used in the creator.
+	 */
+	@Override
+	public boolean isCreatorParameter(PersistentProperty<?> property) {
+
+		Assert.notNull(property, "Property must not be null!");
+
+		Boolean cached = isPropertyParameterCache.get(property);
+
+		if (cached != null) {
+			return cached;
+		}
+
+		boolean result = doGetIsCreatorParameter(property);
+
+		isPropertyParameterCache.put(property, result);
+
+		return result;
+	}
+
+	@Override
+	public String toString() {
+		return executable.toString();
+	}
+
+	private boolean doGetIsCreatorParameter(PersistentProperty<?> property) {
+
+		for (Parameter<?, P> parameter : parameters) {
+			if (parameter.maps(property)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+}

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

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2011-2021 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.mapping;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.Method;
+
+import org.springframework.util.ReflectionUtils;
+
+/**
+ * Value object to encapsulate the factory method to be used when mapping persistent data to objects.
+ *
+ * @author Mark Paluch
+ * @since 3.0
+ */
+public final class FactoryMethod<T, P extends PersistentProperty<P>> extends EntityCreatorMetadataSupport<T, P> {
+
+	/**
+	 * Creates a new {@link FactoryMethod} from the given {@link Constructor} and {@link Parameter}s.
+	 *
+	 * @param factoryMethod must not be {@literal null}.
+	 * @param parameters must not be {@literal null}.
+	 */
+	@SafeVarargs
+	public FactoryMethod(Method factoryMethod, Parameter<Object, P>... parameters) {
+
+		super(factoryMethod, parameters);
+		ReflectionUtils.makeAccessible(factoryMethod);
+	}
+
+	/**
+	 * Returns the underlying {@link Constructor}.
+	 *
+	 * @return
+	 */
+	public Method getFactoryMethod() {
+		return (Method) getExecutable();
+	}
+
+}