Incorporate design review feedback.

Author: mp911de

src/jmh/java/org/springframework/data/core/SerializableLambdaReaderBenchmarks.java

@@ -28,19 +28,19 @@
 @Testable
 public class SerializableLambdaReaderBenchmarks extends BenchmarkSettings {
 
-	private static final SerializableLambdaReader reader = new SerializableLambdaReader(MemberReference.class);
+	private static final SerializableLambdaReader reader = new SerializableLambdaReader(PropertyReference.class);
 
 	@Benchmark
 	public Object benchmarkMethodReference() {
 
-		MemberReference<Person, String> methodReference = Person::firstName;
+		PropertyReference<Person, String> methodReference = Person::firstName;
 		return reader.read(methodReference);
 	}
 
 	@Benchmark
 	public Object benchmarkLambda() {
 
-		MemberReference<Person, String> methodReference = person -> person.firstName();
+		PropertyReference<Person, String> methodReference = person -> person.firstName();
 		return reader.read(methodReference);
 	}
 

src/jmh/java/org/springframework/data/core/TypedPropertyPathBenchmarks.java

@@ -29,32 +29,32 @@ public class TypedPropertyPathBenchmarks extends BenchmarkSettings {
 
 	@Benchmark
 	public Object benchmarkMethodReference() {
-		return TypedPropertyPath.ofProperty(Person::firstName);
+		return TypedPropertyPath.path(Person::firstName);
 	}
 
 	@Benchmark
 	public Object benchmarkComposedMethodReference() {
-		return TypedPropertyPath.ofProperty(Person::address).then(Address::city);
+		return TypedPropertyPath.path(Person::address).then(Address::city);
 	}
 
 	@Benchmark
 	public TypedPropertyPath<Person, String> benchmarkLambda() {
-		return TypedPropertyPath.ofProperty(person -> person.firstName());
+		return TypedPropertyPath.path(person -> person.firstName());
 	}
 
 	@Benchmark
 	public TypedPropertyPath<Person, String> benchmarkComposedLambda() {
-		return TypedPropertyPath.ofProperty((Person person) -> person.address()).then(address -> address.city());
+		return TypedPropertyPath.path((Person person) -> person.address()).then(address -> address.city());
 	}
 
 	@Benchmark
 	public Object dotPath() {
-		return TypedPropertyPath.ofProperty(Person::firstName).toDotPath();
+		return TypedPropertyPath.path(Person::firstName).toDotPath();
 	}
 
 	@Benchmark
 	public Object composedDotPath() {
-		return TypedPropertyPath.ofProperty(Person::address).then(Address::city).toDotPath();
+		return TypedPropertyPath.path(Person::address).then(Address::city).toDotPath();
 	}
 
 	record Person(String firstName, String lastName, Address address) {

src/main/java/org/springframework/data/convert/PropertyValueConverterRegistrar.java

@@ -20,6 +20,7 @@
 import java.util.function.Function;
 
 import org.springframework.data.convert.PropertyValueConverter.FunctionPropertyValueConverter;
+import org.springframework.data.core.PropertyReference;
 import org.springframework.data.mapping.PersistentProperty;
 import org.springframework.data.util.MethodInvocationRecorder;
 import org.springframework.lang.Contract;
@@ -50,11 +51,25 @@ public class PropertyValueConverterRegistrar<P extends PersistentProperty<P>> {
 	 *
 	 * @param <T> the domain type
 	 * @param <S> the property type
-	 * @param type the domain type to obtain the property from
 	 * @param property a {@link Function} to describe the property to be referenced.
 	 * Usually a method handle to a getter.
 	 * @return will never be {@literal null}.
 	 */
+	public <T, S> WritingConverterRegistrationBuilder<T, S, P> registerConverter(PropertyReference<T, S> property) {
+		return new WritingConverterRegistrationBuilder<>(property.getOwningType().getType(), property.getName(), this);
+	}
+
+	/**
+	 * Starts a converter registration by pointing to a property of a domain type.
+	 *
+	 * @param <T> the domain type
+	 * @param <S> the property type
+	 * @param type the domain type to obtain the property from
+	 * @param property a {@link Function} to describe the property to be referenced. Usually a method handle to a getter.
+	 * @return will never be {@literal null}.
+	 * @deprecated since 4.1, use {@link #registerConverter(PropertyReference)} instead.
+	 */
+	@Deprecated(since = "4.1")
 	public <T, S> WritingConverterRegistrationBuilder<T, S, P> registerConverter(Class<T> type, Function<T, S> property) {
 
 		String propertyName = MethodInvocationRecorder.forProxyOf(type).record(property).getPropertyPath()

src/main/java/org/springframework/data/core/MemberReference.java

@@ -24,6 +24,19 @@
 
 /**
  * Abstraction of a {@link PropertyPath} within a domain class.
+ * <p>
+ * Property paths allow to navigate nested properties such as {@code address.city.name} and provide metadata for each
+ * segment of the path. Paths are represented in dot-path notation and are resolved from an owning type, for example:
+ *
+ * <pre class="code">
+ * PropertyPath.from("address.city.name", Person.class);
+ * </pre>
+ *
+ * Paths are cached on a best-effort basis using a weak reference cache to avoid repeated introspection if GC pressure
+ * permits.
+ * <p>
+ * A typed variant of {@link PropertyPath} is available as {@link TypedPropertyPath} through
+ * {@link #of(PropertyReference)} to leverage method references for a type-safe usage across application code.
  *
  * @author Oliver Gierke
  * @author Christoph Strobl
@@ -79,10 +92,10 @@ static <T, P> TypedPropertyPath<T, P> ofMany(PropertyReference<T, ? extends Iter
 	 * For example:
 	 *
 	 * <pre class="code">
-	 * PropertyPath.from("a.b.c", Some.class).getSegment();
+	 * PropertyPath.from("address.city.name", Person.class).getSegment();
 	 * </pre>
 	 *
-	 * results in {@code a}.
+	 * results in {@code address}.
 	 *
 	 * @return the current property path segment.
 	 */
@@ -149,10 +162,10 @@ default boolean isCollection() {
 	 * Returns the next {@code PropertyPath} segment in the property path chain.
 	 *
 	 * <pre class="code">
-	 * PropertyPath.from("a.b.c", Some.class).next().toDotPath();
+	 * PropertyPath.from("address.city.name", Person.class).next().toDotPath();
 	 * </pre>
 	 *
-	 * results in the output: {@code b.c}
+	 * results in the output: {@code city.name}.
 	 *
 	 * @return the next {@code PropertyPath} or {@literal null} if the path does not contain further segments.
 	 * @see #hasNext()
@@ -201,16 +214,16 @@ default PropertyPath nested(String path) {
 	 * Returns an {@link Iterator Iterator of PropertyPath} that iterates over all property path segments. For example:
 	 *
 	 * <pre class="code">
-	 * PropertyPath propertyPath = PropertyPath.from("a.b.c", Some.class);
-	 * propertyPath.forEach(p -> p.toDotPath());
+	 * PropertyPath path = PropertyPath.from("address.city.name", Person.class);
+	 * path.forEach(p -> p.toDotPath());
 	 * </pre>
 	 *
 	 * results in the dot paths:
 	 *
 	 * <pre class="code">
-	 * a.b.c             (this object)
-	 * b.c               (next() object)
-	 * c                 (next().next() object)
+	 * address.city.name     (this object)
+	 * city.name             (next() object)
+	 * city.name             (next().next() object)
 	 * </pre>
 	 */
 	@Override

src/main/java/org/springframework/data/core/PropertyPath.java

@@ -22,13 +22,12 @@
 /**
  * Interface providing type-safe property references.
  * <p>
- * This functional interface is typically implemented through method references and lambda expressions that allow for
- * compile-time type safety and refactoring support. Instead of string-based property names that are easy to miss when
- * changing the domain model, {@code PropertyReference} leverages Java's declarative method references and lambda
- * expressions to ensure type-safe property access.
+ * This functional interface is typically implemented through method references that allow for compile-time type safety
+ * and refactoring support. Instead of string-based property names that are easy to miss when changing the domain model,
+ * {@code PropertyReference} leverages Java's declarative method references to ensure type-safe property access.
  * <p>
- * Create a typed property reference using the static factory method {@link #of(PropertyReference)} with a method
- * reference or lambda, for example:
+ * Create a typed property reference using the static factory method {@link #property(PropertyReference)} with a method
+ * reference, for example:
  *
  * <pre class="code">
  * PropertyReference&lt;Person, String&gt; name = PropertyReference.of(Person::getName);
@@ -64,11 +63,25 @@
 public interface PropertyReference<T, P extends @Nullable Object> extends Serializable {
 
 	/**
-	 * Syntax sugar to create a {@link PropertyReference} from a method reference or lambda.
+	 * Syntax sugar to create a {@link PropertyReference} from a method reference. Suitable for static imports.
 	 * <p>
-	 * This method returns a resolved {@link PropertyReference} by introspecting the given method reference or lambda.
+	 * This method returns a resolved {@link PropertyReference} by introspecting the given method reference.
 	 *
-	 * @param property the method reference or lambda.
+	 * @param property the method reference.
+	 * @param <T> owning type.
+	 * @param <P> property type.
+	 * @return the typed property reference.
+	 */
+	static <T, P extends @Nullable Object> PropertyReference<T, P> property(PropertyReference<T, P> property) {
+		return of(property);
+	}
+
+	/**
+	 * Syntax sugar to create a {@link PropertyReference} from a method reference.
+	 * <p>
+	 * This method returns a resolved {@link PropertyReference} by introspecting the given method reference.
+	 *
+	 * @param property the method reference.
 	 * @param <T> owning type.
 	 * @param <P> property type.
 	 * @return the typed property reference.
@@ -80,11 +93,11 @@ public interface PropertyReference<T, P extends @Nullable Object> extends Serial
 	/**
 	 * Syntax sugar to create a {@link PropertyReference} from a method reference or lambda for a collection property.
 	 * <p>
-	 * This method returns a resolved {@link PropertyReference} by introspecting the given method reference or lambda.
-	 * Note that {@link #get(Object)} becomes unusable for collection properties as the property type adapted from
+	 * This method returns a resolved {@link PropertyReference} by introspecting the given method reference. Note that
+	 * {@link #get(Object)} becomes unusable for collection properties as the property type adapted from
 	 * {@code Iterable &lt;P&gt;} and a single {@code P} cannot represent a collection of items.
 	 *
-	 * @param property the method reference or lambda.
+	 * @param property the method reference.
 	 * @param <T> owning type.
 	 * @param <P> property type.
 	 * @return the typed property reference.
@@ -104,11 +117,11 @@ static <T, P> PropertyReference<T, P> ofMany(PropertyReference<T, ? extends Iter
 	P get(T obj);
 
 	/**
-	 * Returns the owning type of the referenced property..
+	 * Returns the owning type of the referenced property.
 	 *
 	 * @return the owningType will never be {@literal null}.
 	 */
-	default TypeInformation<?> getOwningType() {
+	default TypeInformation<T> getOwningType() {
 		return PropertyReferences.of(this).getOwningType();
 	}