Documentation.

Author: mp911de

src/main/antora/modules/ROOT/pages/property-paths.adoc

@@ -0,0 +1,51 @@
+[[type-safe-property-references]]
+= Type-safe Property References
+
+Type-safe property references address a common source of friction in data access code: The reliance on literal, dot-separated property path strings.
+Such stringly-typed references are fragile during refactoring difficult to identify as they often lack context.
+Type-safe property paths favor explicitness and compiler validation by deriving property paths from Java method references.
+
+A property path is a simple, transportable representation of object navigation.
+When expressed as a method-reference the compiler participates in validation and IDEs provide meaningful refactoring support.
+The result is code that reads naturally, fails fast on renames, and integrates cleanly with existing query and sorting abstractions, for example:
+
+[source,java]
+----
+TypedPropertyPath.of(Person::getAddress)
+                 .then(Address::getCity);
+----
+
+The expression above constructs a path equivalent to `address.city` while remaining resilient to refactoring.
+Property resolution is performed by inspecting the supplied method references; any mismatch becomes visible at compile time.
+
+By comparing a literal-based approach as the following example you can immediately spot the same intent while the mechanism of using strings removes any type context:
+
+.Stringly-typed programming
+[source,java]
+----
+Sort.by("address.city", "address.street")
+----
+
+You can also use it inline for operations like sorting:
+
+.Type-safe Property Path
+[source,java]
+----
+Sort.by(Person::getFirstName, Person::getLastName);
+----
+
+`TypedPropertyPath` can integrate seamlessly with query abstractions or criteria builders:
+
+.Type-safe Property Path
+[source,java]
+----
+Criteria.where(Person::getAddress)
+        .then(Address::getCity)
+        .is("New York");
+----
+
+Adopting type-safe property references aligns with modern Spring development principles.
+Providing declarative, type-safe, and fluent APIs leads to simpler reasoning about data access eliminating an entire category of potential bugs through IDE refactoring support and early feedback on invalid properties by the compiler.
+
+Lambda introspection is cached for efficiency enabling repeatable use.
+The JVM reuses static lambda instances contributing to minimal overhead of one-time parsing.

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

@@ -0,0 +1,147 @@
+/*
+ * Copyright 2025 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.core;
+
+import java.lang.invoke.SerializedLambda;
+import java.lang.reflect.Field;
+import java.lang.reflect.Member;
+import java.lang.reflect.Method;
+
+import org.springframework.asm.Type;
+import org.springframework.core.ResolvableType;
+import org.springframework.util.ClassUtils;
+import org.springframework.util.ReflectionUtils;
+
+/**
+ * Interface representing a member reference such as a field or method.
+ *
+ * @author Mark Paluch
+ * @since 4.1
+ */
+sealed interface MemberDescriptor
+		permits MemberDescriptor.MethodDescriptor.FieldDescriptor, MemberDescriptor.MethodDescriptor {
+
+	/**
+	 * @return class owning the member, can be the declaring class or a subclass.
+	 */
+	Class<?> getOwner();
+
+	/**
+	 * @return the member (field or method).
+	 */
+	Member getMember();
+
+	/**
+	 * @return field type or method return type.
+	 */
+	ResolvableType getType();
+
+	/**
+	 * Create {@link MethodDescriptor} from a serialized lambda representing a method reference.
+	 */
+	static MethodDescriptor ofMethodReference(ClassLoader classLoader, SerializedLambda lambda)
+			throws ClassNotFoundException {
+		return ofMethod(classLoader, Type.getObjectType(lambda.getImplClass()).getClassName(), lambda.getImplMethodName());
+	}
+
+	/**
+	 * Create {@link MethodDescriptor} from owner type and method name.
+	 */
+	static MethodDescriptor ofMethod(ClassLoader classLoader, String ownerClassName, String name)
+			throws ClassNotFoundException {
+		Class<?> owner = ClassUtils.forName(ownerClassName, classLoader);
+		return MethodDescriptor.create(owner, name);
+	}
+
+	/**
+	 * Create {@link MethodDescriptor.FieldDescriptor} from owner type, field name and field type.
+	 */
+	public static MethodDescriptor.FieldDescriptor ofField(ClassLoader classLoader, String ownerClassName, String name,
+			String fieldType) throws ClassNotFoundException {
+
+		Class<?> owner = ClassUtils.forName(ownerClassName, classLoader);
+		Class<?> type = ClassUtils.forName(fieldType, classLoader);
+
+		return FieldDescriptor.create(owner, name, type);
+	}
+
+	/**
+	 * Value object describing a {@link Method} in the context of an owning class.
+	 *
+	 * @param owner
+	 * @param method
+	 */
+	record MethodDescriptor(Class<?> owner, Method method) implements MemberDescriptor {
+
+		static MethodDescriptor create(Class<?> owner, String methodName) {
+			Method method = ReflectionUtils.findMethod(owner, methodName);
+			if (method == null) {
+				throw new IllegalArgumentException("Method '%s.%s()' not found".formatted(owner.getName(), methodName));
+			}
+			return new MethodDescriptor(owner, method);
+		}
+
+		@Override
+		public Class<?> getOwner() {
+			return owner();
+		}
+
+		@Override
+		public Method getMember() {
+			return method();
+		}
+
+		@Override
+		public ResolvableType getType() {
+			return ResolvableType.forMethodReturnType(method(), owner());
+		}
+
+	}
+
+	/**
+	 * Value object describing a {@link Field} in the context of an owning class.
+	 *
+	 * @param owner
+	 * @param field
+	 */
+	record FieldDescriptor(Class<?> owner, Field field) implements MemberDescriptor {
+
+		static FieldDescriptor create(Class<?> owner, String fieldName, Class<?> fieldType) {
+
+			Field field = ReflectionUtils.findField(owner, fieldName, fieldType);
+			if (field == null) {
+				throw new IllegalArgumentException("Field '%s.%s' not found".formatted(owner.getName(), fieldName));
+			}
+			return new FieldDescriptor(owner, field);
+		}
+
+		@Override
+		public Class<?> getOwner() {
+			return owner();
+		}
+
+		@Override
+		public Field getMember() {
+			return field();
+		}
+
+		@Override
+		public ResolvableType getType() {
+			return ResolvableType.forField(field(), owner());
+		}
+
+	}
+}

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

@@ -37,7 +37,8 @@ public static Member resolve(Object object) {
 		Assert.notNull(object, "Object must not be null");
 		Assert.isInstanceOf(Serializable.class, object, "Object must be Serializable");
 
-		return new SamParser(MemberReference.class).parse(object.getClass().getClassLoader(), object).getMember();
+		return new SerializableLambdaReader(MemberReference.class).read(object)
+				.getMember();
 	}
 
 }

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

@@ -35,16 +35,17 @@
 public interface PropertyPath extends Streamable<PropertyPath> {
 
 	/**
-	 * Syntax sugar to create a {@link TypedPropertyPath} from an existing one, ideal for method handles.
+	 * Syntax sugar to create a {@link TypedPropertyPath} from a method reference or lambda.
+	 * <p>
+	 * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method reference or lambda.
 	 *
-	 * @param propertyPath
-	 * @return
+	 * @param propertyPath the method reference or lambda.
 	 * @param <T> owning type.
-	 * @param <R> property type.
-	 * @since xxx
+	 * @param <P> property type.
+	 * @return the typed property path.
 	 */
-	public static <T, R> TypedPropertyPath<T, R> of(TypedPropertyPath<T, R> propertyPath) {
-		return TypedPropertyPath.of(propertyPath);
+	static <T, P> TypedPropertyPath<T, P> of(TypedPropertyPath<T, P> propertyPath) {
+		return TypedPropertyPaths.of(propertyPath);
 	}
 
 	/**