> for more information.
+
+[[property-path-internals]]
+=== Property Path Internals
+
+The `org.springframework.data.core` package is the basis for Spring Data's navigation across domain classes.
+The javadoc:org.springframework.data.core.TypeInformation[] inteface provides type introspection capable of resolving the type of a property. javadoc:org.springframework.data.core.PropertyPath[] represents a textual navigation path through a domain class.
+
+Together they provide:
+
+* Generic type resolution and introspection
+* Property path creation and validation
+* Actual type resolution for complex properties such as collections and maps
+
+[[type-safe-property-references]]
+== Type-safe Property-References
+
+Type-safe property-references eliminate a common source of errors in data access code: Brittle, string-based property references.
+This section explains how method references can be used to express refactoring-safe property paths.
+
+While a property path is a simple representation of object navigation, String-based property paths are inherently fragile during refactoring as they can be easily missed with an increasing distance between the property definition and its usage.
+Type-safe alternatives derive property paths from method references, enabling the compiler to validate property names and IDEs to support refactoring operations.
+
+Consider the practical difference: The following examples express the same intent - sorting by `address.city` - but only the type-safe version benefits from compiler validation and IDE support:
+
+[tabs]
+======
+Java::
++
+[source,java,role="primary"]
+----
+// Static import variant
+path(Person::getAddress)
+ .then(Address::getCity);
+
+// Composition factory method
+path(Person::getAddress, Address::getCity);
+
+// Fluent composition
+TypedPropertyPath.of(Person::getAddress)
+ .then(Address::getCity);
+----
+
+Kotlin::
++
+[source,kotlin,role="secondary"]
+----
+// Kotlin API
+TypedPropertyPath.of(Person::address / Address::city)
+
+// as extension function
+(Person::address / Address::city).toPath()
+----
+======
+
+=== Building Type-safe Property Paths
+
+Type-safe property paths compose method references to construct navigation expressions.
+The following examples demonstrate inline usage and composition:
+
+.Type-safe Property Path Construction
+[tabs]
+======
+Java::
++
+[source,java,role="primary"]
+----
+// Inline usage with Sort
+Sort.by(Person::getFirstName, Person::getLastName);
+
+// Composed navigation
+Sort.by(TypedPropertyPath.of(Person::getAddress).then(Address::getCity),
+ Person::getLastName);
+----
+
+Kotlin::
++
+[source,kotlin,role="secondary"]
+----
+// Inline usage with Sort
+Sort.by(Person::firstName, Person::lastName)
+
+// Composed navigation
+Sort.by(Person::address / Address::city, Person::lastName)
+----
+======
+
+Type-safe property paths integrate seamlessly with query abstractions and criteria builders, enabling declarative query construction without string-based property references:
+
+.Integration with Criteria API
+[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.
diff --git a/src/main/java/org/springframework/data/convert/PropertyValueConverterRegistrar.java b/src/main/java/org/springframework/data/convert/PropertyValueConverterRegistrar.java
index 869b60269e..1606dc7fed 100644
--- a/src/main/java/org/springframework/data/convert/PropertyValueConverterRegistrar.java
+++ b/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> {
*
* @param the domain type
* @param 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 WritingConverterRegistrationBuilder registerConverter(PropertyReference property) {
+ return new WritingConverterRegistrationBuilder<>(property.getOwningType().getType(), property.getName(), this);
+ }
+
+ /**
+ * Starts a converter registration by pointing to a property of a domain type.
+ *
+ * @param the domain type
+ * @param 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 WritingConverterRegistrationBuilder registerConverter(Class type, Function property) {
String propertyName = MethodInvocationRecorder.forProxyOf(type).record(property).getPropertyPath()
diff --git a/src/main/java/org/springframework/data/core/MemberDescriptor.java b/src/main/java/org/springframework/data/core/MemberDescriptor.java
new file mode 100644
index 0000000000..4ce02107f5
--- /dev/null
+++ b/src/main/java/org/springframework/data/core/MemberDescriptor.java
@@ -0,0 +1,250 @@
+/*
+ * 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 kotlin.reflect.KProperty1;
+import kotlin.reflect.jvm.ReflectJvmMapping;
+
+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
+ */
+interface MemberDescriptor {
+
+ /**
+ * @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.
+ */
+ 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.
+ */
+ 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.
+ */
+ 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());
+ }
+
+ }
+
+ interface KotlinMemberDescriptor extends MemberDescriptor {
+
+ KProperty1 getKotlinProperty();
+
+ }
+
+ /**
+ * Value object describing a Kotlin property in the context of an owning class.
+ */
+ record KPropertyReferenceDescriptor(Class owner, KProperty1 property) implements KotlinMemberDescriptor {
+
+ static KPropertyReferenceDescriptor create(Class owner, KProperty1 property) {
+ return new KPropertyReferenceDescriptor(owner, property);
+ }
+
+ @Override
+ public KProperty1 getKotlinProperty() {
+ return property();
+ }
+
+ @Override
+ public Class getOwner() {
+ return owner();
+ }
+
+ @Override
+ public Member getMember() {
+
+ Method javaGetter = ReflectJvmMapping.getJavaGetter(property());
+ if (javaGetter != null) {
+ return javaGetter;
+ }
+
+ Field javaField = ReflectJvmMapping.getJavaField(property());
+
+ if (javaField != null) {
+ return javaField;
+ }
+
+ throw new IllegalStateException("Cannot resolve member for property '%s'".formatted(property().getName()));
+ }
+
+ @Override
+ public ResolvableType getType() {
+
+ Member member = getMember();
+
+ if (member instanceof Method m) {
+ return ResolvableType.forMethodReturnType(m, owner());
+ }
+
+ return ResolvableType.forField((Field) member, owner());
+ }
+
+ }
+
+ /**
+ * Value object describing a Kotlin property in the context of an owning class.
+ */
+ record KPropertyPathDescriptor(KProperty1 property) implements KotlinMemberDescriptor {
+
+ static KPropertyPathDescriptor create(KProperty1 propertyReference) {
+ return new KPropertyPathDescriptor(propertyReference);
+ }
+
+ @Override
+ public KProperty1 getKotlinProperty() {
+ return property();
+ }
+
+ @Override
+ public Class getOwner() {
+ return getMember().getDeclaringClass();
+ }
+
+ @Override
+ public Member getMember() {
+
+ Method javaGetter = ReflectJvmMapping.getJavaGetter(property());
+ if (javaGetter != null) {
+ return javaGetter;
+ }
+
+ Field javaField = ReflectJvmMapping.getJavaField(property());
+
+ if (javaField != null) {
+ return javaField;
+ }
+
+ throw new IllegalStateException("Cannot resolve member for property '%s'".formatted(property().getName()));
+ }
+
+ @Override
+ public ResolvableType getType() {
+
+ Member member = getMember();
+
+ if (member instanceof Method m) {
+ return ResolvableType.forMethodReturnType(m, getOwner());
+ }
+
+ return ResolvableType.forField((Field) member, getOwner());
+ }
+
+ }
+
+}
diff --git a/src/main/java/org/springframework/data/core/PropertyPath.java b/src/main/java/org/springframework/data/core/PropertyPath.java
index 26a06299c9..68b7235e01 100644
--- a/src/main/java/org/springframework/data/core/PropertyPath.java
+++ b/src/main/java/org/springframework/data/core/PropertyPath.java
@@ -19,21 +19,67 @@
import java.util.regex.Pattern;
import org.jspecify.annotations.Nullable;
-
import org.springframework.data.util.Streamable;
import org.springframework.util.Assert;
/**
* Abstraction of a {@link PropertyPath} within a domain class.
+ *
+ * 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:
+ *
+ *
+ * PropertyPath.from("address.city.name", Person.class);
+ *
+ *
+ * Paths are cached on a best-effort basis using a weak reference cache to avoid repeated introspection if GC pressure
+ * permits.
+ *
+ * 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
* @author Mark Paluch
* @author Mariusz Mączkowski
* @author Johannes Englmeier
+ * @see PropertyReference
+ * @see TypedPropertyPath
+ * @see java.beans.PropertyDescriptor
*/
public interface PropertyPath extends Streamable {
+ /**
+ * Syntax sugar to create a {@link TypedPropertyPath} from a method reference to a Java beans property.
+ *
+ * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method reference.
+ *
+ * @param property the method reference referring to a Java beans property.
+ * @param owning type.
+ * @param property type.
+ * @return the typed property path.
+ * @since 4.1
+ */
+ static TypedPropertyPath of(PropertyReference property) {
+ return TypedPropertyPaths.of(property);
+ }
+
+ /**
+ * Syntax sugar to create a {@link TypedPropertyPath} from a method reference to a Java beans collection property.
+ *
+ * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method reference.
+ *
+ * @param property the method reference referring to a property.
+ * @param owning type.
+ * @param property type.
+ * @return the typed property path.
+ * @since 4.1
+ */
+ @SuppressWarnings({ "unchecked", "rawtypes" })
+ static TypedPropertyPath ofMany(PropertyReference> property) {
+ return (TypedPropertyPath) TypedPropertyPaths.of(property);
+ }
+
/**
* Returns the owning type of the {@link PropertyPath}.
*
@@ -42,22 +88,25 @@ public interface PropertyPath extends Streamable {
TypeInformation getOwningType();
/**
- * Returns the first part of the {@link PropertyPath}. For example:
+ * Returns the current property path segment (i.e. first part of {@link #toDotPath()}).
+ *
+ * For example:
*
*
- * PropertyPath.from("a.b.c", Some.class).getSegment();
+ * PropertyPath.from("address.city.name", Person.class).getSegment();
*
*
- * results in {@code a}.
+ * results in {@code address}.
*
- * @return the name will never be {@literal null}.
+ * @return the current property path segment.
*/
String getSegment();
/**
- * Returns the leaf property of the {@link PropertyPath}.
+ * Returns the leaf property of the {@link PropertyPath}. Either this property if the path ends here or the last
+ * property in the chain.
*
- * @return will never be {@literal null}.
+ * @return leaf property.
*/
default PropertyPath getLeafProperty() {
@@ -74,57 +123,72 @@ default PropertyPath getLeafProperty() {
* Returns the type of the leaf property of the current {@link PropertyPath}.
*
* @return will never be {@literal null}.
+ * @see #getLeafProperty()
*/
default Class getLeafType() {
return getLeafProperty().getType();
}
/**
- * Returns the actual type of the property. Will return the plain resolved type for simple properties, the component
- * type for any {@link Iterable} or the value type of a {@link java.util.Map}.
+ * Returns the actual type of the property at this segment. Will return the plain resolved type for simple properties,
+ * the component type for any {@link Iterable} or the value type of {@link java.util.Map} properties.
*
* @return the actual type of the property.
+ * @see #getTypeInformation()
+ * @see TypeInformation#getRequiredActualType()
*/
default Class getType() {
return getTypeInformation().getRequiredActualType().getType();
}
/**
- * Returns the type information of the property.
+ * Returns the type information for the property at this segment.
*
- * @return the actual type of the property.
+ * @return the type information for the property at this segment.
*/
TypeInformation getTypeInformation();
/**
- * Returns the {@link PropertyPath} path that results from removing the first element of the current one. For example:
+ * Returns whether the current property path segment is a collection.
+ *
+ * @return {@literal true} if the current property path segment is a collection.
+ * @see #getTypeInformation()
+ * @see TypeInformation#isCollectionLike()
+ */
+ default boolean isCollection() {
+ return getTypeInformation().isCollectionLike();
+ }
+
+ /**
+ * Returns the next {@code PropertyPath} segment in the property path chain.
*
*
- * PropertyPath.from("a.b.c", Some.class).next().toDotPath();
+ * PropertyPath.from("address.city.name", Person.class).next().toDotPath();
*
*
- * results in the output: {@code b.c}
+ * results in the output: {@code city.name}.
*
- * @return the next nested {@link PropertyPath} or {@literal null} if no nested {@link PropertyPath} available.
+ * @return the next {@code PropertyPath} or {@literal null} if the path does not contain further segments.
* @see #hasNext()
*/
@Nullable
PropertyPath next();
/**
- * Returns whether there is a nested {@link PropertyPath}. If this returns {@literal true} you can expect
- * {@link #next()} to return a non- {@literal null} value.
+ * Returns {@literal true} if the property path contains further segments or {@literal false} if the path ends at this
+ * segment.
*
- * @return
+ * @return {@literal true} if the property path contains further segments or {@literal false} if the path ends at this
+ * segment.
*/
default boolean hasNext() {
return next() != null;
}
/**
- * Returns the {@link PropertyPath} in dot notation.
+ * Returns the {@code PropertyPath} in dot notation.
*
- * @return the {@link PropertyPath} in dot notation.
+ * @return the {@code PropertyPath} in dot notation.
*/
default String toDotPath() {
@@ -133,16 +197,7 @@ default String toDotPath() {
}
/**
- * Returns whether the {@link PropertyPath} is actually a collection.
- *
- * @return {@literal true} whether the {@link PropertyPath} is actually a collection.
- */
- default boolean isCollection() {
- return getTypeInformation().isCollectionLike();
- }
-
- /**
- * Returns the {@link PropertyPath} for the path nested under the current property.
+ * Returns the {@code PropertyPath} for the path nested under the current property.
*
* @param path must not be {@literal null} or empty.
* @return will never be {@literal null}.
@@ -157,20 +212,19 @@ default PropertyPath nested(String path) {
}
/**
- * Returns an {@link Iterator Iterator of PropertyPath} that iterates over all the partial property paths with the
- * same leaf type but decreasing length. For example:
+ * Returns an {@link Iterator Iterator of PropertyPath} that iterates over all property path segments. For example:
*
*
- * 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());
*
*
* results in the dot paths:
*
*
- * a.b.c
- * b.c
- * c
+ * address.city.name (this object)
+ * city.name (next() object)
+ * city.name (next().next() object)
*
*/
@Override
diff --git a/src/main/java/org/springframework/data/core/PropertyPathUtil.java b/src/main/java/org/springframework/data/core/PropertyPathUtil.java
new file mode 100644
index 0000000000..b46c47d84e
--- /dev/null
+++ b/src/main/java/org/springframework/data/core/PropertyPathUtil.java
@@ -0,0 +1,138 @@
+/*
+ * 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.io.Serializable;
+import java.lang.invoke.SerializedLambda;
+import java.lang.reflect.Method;
+import java.util.Objects;
+
+import org.jspecify.annotations.Nullable;
+
+import org.springframework.dao.InvalidDataAccessApiUsageException;
+import org.springframework.util.Assert;
+import org.springframework.util.ReflectionUtils;
+
+/**
+ * Utility class for {@link PropertyPath} and {@link PropertyReference} implementations.
+ *
+ * @author Mark Paluch
+ * @since 4.1
+ */
+public class PropertyPathUtil {
+
+ /**
+ * Resolve a {@link PropertyPath} from a {@link Serializable} lambda implementing a functional interface accepting a
+ * single method argument and returning a value. The form of the interface must follow a design aligned with
+ * {@link org.springframework.core.convert.converter.Converter} or {@link java.util.function.Function}.
+ *
+ * @param obj the serializable lambda object.
+ * @return the resolved property path.
+ */
+ public static PropertyPath resolve(Object obj) {
+
+ Assert.isInstanceOf(Serializable.class, obj, "Object must be Serializable");
+
+ return TypedPropertyPaths.of(new SerializableWrapper((Serializable) obj));
+ }
+
+ private record SerializableWrapper(Serializable serializable) implements PropertyReference {
+
+ @Override
+ public @Nullable Object get(Object obj) {
+ return null;
+ }
+
+ // serializable bridge
+ public SerializedLambda writeReplace() {
+
+ Method method = ReflectionUtils.findMethod(serializable.getClass(), "writeReplace");
+
+ if (method == null) {
+ throw new InvalidDataAccessApiUsageException(
+ "Cannot find writeReplace method on " + serializable.getClass().getName());
+ }
+
+ ReflectionUtils.makeAccessible(method);
+ return (SerializedLambda) ReflectionUtils.invokeMethod(method, serializable);
+ }
+
+ }
+
+ /**
+ * Compute the hash code for the given {@link PropertyPath} based on its {@link Object#toString() string}
+ * representation.
+ *
+ * @param path the property path.
+ * @return property path hash code.
+ */
+ static int hashCode(PropertyPath path) {
+ return path.toString().hashCode();
+ }
+
+ /**
+ * Compute the hash code for the given {@link PropertyReference} based on its {@link Object#toString() string}
+ * representation.
+ *
+ * @param property the property reference
+ * @return property reference hash code.
+ */
+ static int hashCode(PropertyReference property) {
+ return Objects.hash(property.getOwningType(), property.getName());
+ }
+
+ /**
+ * Equality check for {@link PropertyPath} implementations based on their owning type and string representation.
+ *
+ * @param self the property path.
+ * @param o the other object.
+ * @return {@literal true} if both are equal; {@literal false} otherwise.
+ */
+ static boolean equals(PropertyPath self, @Nullable Object o) {
+
+ if (self == o) {
+ return true;
+ }
+
+ if (!(o instanceof PropertyPath that)) {
+ return false;
+ }
+
+ return Objects.equals(self.getOwningType(), that.getOwningType())
+ && Objects.equals(self.toString(), that.toString());
+ }
+
+ /**
+ * Equality check for {@link PropertyReference} implementations based on their owning type and name.
+ *
+ * @param self the property path.
+ * @param o the other object.
+ * @return {@literal true} if both are equal; {@literal false} otherwise.
+ */
+ static boolean equals(PropertyReference self, @Nullable Object o) {
+
+ if (self == o) {
+ return true;
+ }
+
+ if (!(o instanceof PropertyReference that)) {
+ return false;
+ }
+
+ return Objects.equals(self.getOwningType(), that.getOwningType()) && Objects.equals(self.getName(), that.getName());
+ }
+
+}
diff --git a/src/main/java/org/springframework/data/core/PropertyReference.java b/src/main/java/org/springframework/data/core/PropertyReference.java
new file mode 100644
index 0000000000..97e374bf7a
--- /dev/null
+++ b/src/main/java/org/springframework/data/core/PropertyReference.java
@@ -0,0 +1,205 @@
+/*
+ * 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.io.Serializable;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Interface providing type-safe property references.
+ *
+ * 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.
+ *
+ * Create a typed property reference using the static factory method {@link #property(PropertyReference)} with a method
+ * reference, for example:
+ *
+ *
+ * PropertyReference.property(Person::getName);
+ *
+ *
+ * The resulting object can be used to obtain the {@link #getName() property name} and to interact with the target
+ * property. Typed references can be used to compose {@link TypedPropertyPath property paths} to navigate nested object
+ * structures using {@link #then(PropertyReference)}:
+ *
+ *
+ * TypedPropertyPath<Person, String> city = PropertyReference.of(Person::getAddress).then(Address::getCity);
+ *
+ *
+ * The generic type parameters preserve type information across the property path chain: {@code T} represents the owning
+ * type of the current segment (or the root type for composed paths), while {@code P} represents the property value type
+ * at this segment. Composition automatically flows type information forward, ensuring that {@code then()} preserves the
+ * full chain's type safety.
+ *
+ * Implement {@code PropertyReference} using method references (strongly recommended) or lambdas that directly access a
+ * property getter. Constructor references, method calls with parameters, and complex expressions are not supported and
+ * result in {@link org.springframework.dao.InvalidDataAccessApiUsageException}. Unlike method references, introspection
+ * of lambda expressions requires bytecode analysis of the declaration site classes and thus depends on their
+ * availability at runtime.
+ *
+ * @param the owning type of this property.
+ * @param the property value type.
+ * @author Mark Paluch
+ * @since 4.1
+ * @see #property(PropertyReference)
+ * @see #then(PropertyReference)
+ * @see #of(PropertyReference)
+ * @see #ofMany(PropertyReference)
+ * @see TypedPropertyPath
+ * @see java.beans.PropertyDescriptor
+ */
+@FunctionalInterface
+public interface PropertyReference extends Serializable {
+
+ /**
+ * Syntax sugar to create a {@link PropertyReference} from a method reference to a Java beans property. Suitable for
+ * static imports.
+ *
+ * This method returns a resolved {@link PropertyReference} by introspecting the given method reference.
+ *
+ * @param property the method reference to a Java beans property.
+ * @param owning type.
+ * @param property type.
+ * @return the typed property reference.
+ */
+ static PropertyReference property(PropertyReference property) {
+ return of(property);
+ }
+
+ /**
+ * Syntax sugar to create a {@link PropertyReference} from a method reference to a Java beans property.
+ *
+ * This method returns a resolved {@link PropertyReference} by introspecting the given method reference.
+ *
+ * @param property the method reference to a Java beans property.
+ * @param owning type.
+ * @param property type.
+ * @return the typed property reference.
+ */
+ static PropertyReference of(PropertyReference property) {
+ return PropertyReferences.of(property);
+ }
+
+ /**
+ * Syntax sugar to create a {@link PropertyReference} from a method reference to a Java beans property.
+ *
+ * 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 <P>} and a single {@code P} cannot represent a collection of items.
+ *
+ * @param property the method reference to a Java beans property.
+ * @param owning type.
+ * @param property type.
+ * @return the typed property reference.
+ */
+ @SuppressWarnings({ "unchecked", "rawtypes" })
+ static PropertyReference ofMany(PropertyReference> property) {
+ return (PropertyReference) PropertyReferences.of(property);
+ }
+
+ /**
+ * Get the property value for the given object.
+ *
+ * @param obj the object to get the property value from.
+ * @return the property value.
+ */
+ @Nullable
+ P get(T obj);
+
+ /**
+ * Returns the owning type of the referenced property.
+ *
+ * @return the owningType will never be {@literal null}.
+ */
+ default TypeInformation getOwningType() {
+ return PropertyReferences.of(this).getOwningType();
+ }
+
+ /**
+ * Returns the name of the property.
+ *
+ * @return the current property name.
+ */
+ default String getName() {
+ return PropertyReferences.of(this).getName();
+ }
+
+ /**
+ * Returns the actual type of the property at this segment. Will return the plain resolved type for simple properties,
+ * the component type for any {@link Iterable} or the value type of {@link java.util.Map} properties.
+ *
+ * @return the actual type of the property.
+ * @see #getTypeInformation()
+ * @see TypeInformation#getRequiredActualType()
+ */
+ default Class getType() {
+ return getTypeInformation().getRequiredActualType().getType();
+ }
+
+ /**
+ * Returns the type information for the property at this segment.
+ *
+ * @return the type information for the property at this segment.
+ */
+ default TypeInformation getTypeInformation() {
+ return PropertyReferences.of(this).getTypeInformation();
+ }
+
+ /**
+ * Returns whether the property is a collection.
+ *
+ * @return {@literal true} if the property is a collection.
+ * @see #getTypeInformation()
+ * @see TypeInformation#isCollectionLike()
+ */
+ default boolean isCollection() {
+ return getTypeInformation().isCollectionLike();
+ }
+
+ /**
+ * Extend the property to a property path by appending the {@code next} path segment and return a new property path
+ * instance.
+ *
+ * @param next the next property path segment as method reference accepting the owner object {@code P} type and
+ * returning {@code N} as result of accessing the property.
+ * @param the new property value type.
+ * @return a new composed {@code TypedPropertyPath}.
+ */
+ default TypedPropertyPath then(PropertyReference next) {
+ return TypedPropertyPaths.compose(this, next);
+ }
+
+ /**
+ * Extend the property to a property path by appending the {@code next} path segment and return a new property path
+ * instance.
+ *
+ * Note that {@link #get(Object)} becomes unusable for collection properties as the property type adapted from
+ * {@code Iterable <P>} and a single {@code P} cannot represent a collection of items.
+ *
+ * @param next the next property path segment as method reference accepting the owner object {@code P} type and
+ * returning {@code N} as result of accessing the property.
+ * @param the new property value type.
+ * @return a new composed {@code TypedPropertyPath}.
+ */
+ @SuppressWarnings({ "unchecked", "rawtypes" })
+ default TypedPropertyPath thenMany(
+ PropertyReference> next) {
+ return (TypedPropertyPath) TypedPropertyPaths.compose(this, next);
+ }
+
+}
diff --git a/src/main/java/org/springframework/data/core/PropertyReferences.java b/src/main/java/org/springframework/data/core/PropertyReferences.java
new file mode 100644
index 0000000000..98540ecb00
--- /dev/null
+++ b/src/main/java/org/springframework/data/core/PropertyReferences.java
@@ -0,0 +1,320 @@
+/*
+ * 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 kotlin.reflect.KProperty;
+
+import java.beans.Introspector;
+import java.beans.PropertyDescriptor;
+import java.util.Map;
+import java.util.WeakHashMap;
+import java.util.function.Supplier;
+
+import org.jspecify.annotations.Nullable;
+
+import org.springframework.beans.BeanUtils;
+import org.springframework.core.KotlinDetector;
+import org.springframework.core.ResolvableType;
+import org.springframework.data.core.MemberDescriptor.FieldDescriptor;
+import org.springframework.data.core.MemberDescriptor.MethodDescriptor;
+import org.springframework.util.ConcurrentReferenceHashMap;
+
+/**
+ * Utility class to read metadata and resolve {@link PropertyReference} instances.
+ *
+ * @author Mark Paluch
+ * @since 4.1
+ */
+class PropertyReferences {
+
+ private static final Map, ResolvedPropertyReference>> resolved = new WeakHashMap<>();
+
+ private static final SerializableLambdaReader reader = new SerializableLambdaReader(PropertyReference.class,
+ TypedPropertyPath.class, TypedPropertyPaths.class, PropertyReferences.class);
+
+ /**
+ * Introspect {@link PropertyReference} and return an introspected {@link ResolvedPropertyReference} variant.
+ */
+ @SuppressWarnings({ "unchecked", "rawtypes" })
+ public static PropertyReference of(PropertyReference lambda) {
+
+ if (lambda instanceof ResolvedPropertyReferenceSupport) {
+ return lambda;
+ }
+
+ Map, ResolvedPropertyReference> cache;
+ synchronized (resolved) {
+ cache = resolved.computeIfAbsent(lambda.getClass().getClassLoader(), k -> new ConcurrentReferenceHashMap<>());
+ }
+
+ return (PropertyReference) cache.computeIfAbsent(lambda,
+ o -> new ResolvedPropertyReference(o, read(lambda)));
+ }
+
+ /**
+ * Retrieve {@link PropertyMetadata} for a given {@link PropertyReference}.
+ */
+ @SuppressWarnings({ "unchecked", "rawtypes" })
+ public static PropertyReference of(PropertyReference delegate,
+ PropertyMetadata metadata) {
+
+ if (KotlinDetector.isKotlinReflectPresent() && metadata instanceof KPropertyMetadata kmp) {
+ return new ResolvedKPropertyReference(kmp.getProperty(), metadata);
+ }
+
+ return new ResolvedPropertyReference<>(delegate, metadata);
+ }
+
+ private static PropertyMetadata read(PropertyReference lambda) {
+
+ MemberDescriptor reference = reader.read(lambda);
+
+ if (KotlinDetector.isKotlinReflectPresent()
+ && reference instanceof MemberDescriptor.KotlinMemberDescriptor kProperty) {
+
+ if (kProperty instanceof MemberDescriptor.KPropertyPathDescriptor) {
+ throw new IllegalArgumentException("PropertyReference " + kProperty.getKotlinProperty().getName()
+ + " is a property path. Use a single property reference.");
+ }
+
+ return KPropertyMetadata.of(kProperty);
+ }
+
+ if (reference instanceof MethodDescriptor method) {
+ return PropertyMetadata.ofMethod(method);
+ }
+
+ return PropertyMetadata.ofField((FieldDescriptor) reference);
+ }
+
+ /**
+ * Metadata describing a property reference including its owner type, property type, and name.
+ */
+ static class PropertyMetadata {
+
+ private final TypeInformation owner;
+ private final String property;
+ private final TypeInformation propertyType;
+
+ PropertyMetadata(Class owner, String property, ResolvableType propertyType) {
+ this(TypeInformation.of(owner), property, TypeInformation.of(propertyType));
+ }
+
+ PropertyMetadata(TypeInformation owner, String property, TypeInformation propertyType) {
+ this.owner = owner;
+ this.property = property;
+ this.propertyType = propertyType;
+ }
+
+ /**
+ * Create a new {@code PropertyMetadata} from a method.
+ */
+ public static PropertyMetadata ofMethod(MethodDescriptor descriptor) {
+
+ return resolveProperty(descriptor,
+ () -> new IllegalArgumentException("Cannot find PropertyDescriptor from method '%s.%s()'"
+ .formatted(descriptor.owner().getName(), descriptor.getMember().getName())));
+ }
+
+ /**
+ * Create a new {@code PropertyMetadata} from a field.
+ */
+ public static PropertyMetadata ofField(FieldDescriptor field) {
+ return new PropertyMetadata(field.owner(), field.getMember().getName(), field.getType());
+ }
+
+ /**
+ * Resolve {@code PropertyMetadata} from a method descriptor by introspecting bean metadata and return metadata if
+ * available otherwise throw an exception supplied by {@code exceptionSupplier}.
+ *
+ * @param method the method descriptor.
+ * @param exceptionSupplier supplier for exception to be thrown when property cannot be resolved.
+ * @return metadata for the resolved property.
+ * @see BeanUtils
+ */
+ public static PropertyMetadata resolveProperty(MethodDescriptor method,
+ Supplier exceptionSupplier) {
+
+ PropertyDescriptor descriptor = BeanUtils.findPropertyForMethod(method.method());
+ String methodName = method.method().getName();
+
+ if (descriptor == null) {
+
+ String propertyName = getPropertyName(methodName);
+ TypeInformation owner = TypeInformation.of(method.owner());
+ TypeInformation fallback = owner.getProperty(propertyName);
+
+ if (fallback != null) {
+ return new PropertyMetadata(owner, propertyName, fallback);
+ }
+
+ throw exceptionSupplier.get();
+ }
+
+ return new PropertyMetadata(method.owner(), descriptor.getName(), method.getType());
+ }
+
+ private static String getPropertyName(String methodName) {
+
+ if (methodName.startsWith("is")) {
+ return Introspector.decapitalize(methodName.substring(2));
+ } else if (methodName.startsWith("get")) {
+ return Introspector.decapitalize(methodName.substring(3));
+ }
+
+ return methodName;
+ }
+
+ public TypeInformation owner() {
+ return owner;
+ }
+
+ public String property() {
+ return property;
+ }
+
+ public TypeInformation propertyType() {
+ return propertyType;
+ }
+
+ }
+
+ /**
+ * Kotlin-specific {@link PropertyMetadata} implementation.
+ */
+ static class KPropertyMetadata extends PropertyMetadata {
+
+ private final KProperty property;
+
+ KPropertyMetadata(Class owner, KProperty property, ResolvableType propertyType) {
+ super(owner, property.getName(), propertyType);
+ this.property = property;
+ }
+
+ /**
+ * Create a new {@code KPropertyMetadata}.
+ */
+ public static KPropertyMetadata of(MemberDescriptor.KotlinMemberDescriptor descriptor) {
+ return new KPropertyMetadata(descriptor.getOwner(), descriptor.getKotlinProperty(),
+ descriptor.getType());
+ }
+
+ public KProperty getProperty() {
+ return property;
+ }
+ }
+
+ /**
+ * A {@link PropertyReference} implementation that caches resolved metadata to avoid repeated introspection.
+ *
+ * @param the owning type.
+ * @param the property type.
+ */
+ static abstract class ResolvedPropertyReferenceSupport implements PropertyReference {
+
+ private final PropertyMetadata metadata;
+ private final String toString;
+
+ ResolvedPropertyReferenceSupport(PropertyMetadata metadata) {
+ this.metadata = metadata;
+ this.toString = metadata.owner().getType().getSimpleName() + "." + getName();
+ }
+
+ @Override
+ @SuppressWarnings("unchecked")
+ public TypeInformation getOwningType() {
+ return (TypeInformation) metadata.owner();
+ }
+
+ @Override
+ public String getName() {
+ return metadata.property();
+ }
+
+ @Override
+ @SuppressWarnings("unchecked")
+ public TypeInformation getTypeInformation() {
+ return (TypeInformation
) metadata.propertyType();
+ }
+
+ @Override
+ public boolean equals(@Nullable Object obj) {
+ return PropertyPathUtil.equals(this, obj);
+ }
+
+ @Override
+ public int hashCode() {
+ return PropertyPathUtil.hashCode(this);
+ }
+
+ @Override
+ public String toString() {
+ return toString;
+ }
+
+ }
+
+ /**
+ * A {@link PropertyReference} implementation that caches resolved metadata to avoid repeated introspection.
+ *
+ * @param the owning type.
+ * @param the property type.
+ */
+ static class ResolvedPropertyReference extends ResolvedPropertyReferenceSupport {
+
+ private final PropertyReference function;
+
+ ResolvedPropertyReference(PropertyReference function, PropertyMetadata metadata) {
+ super(metadata);
+ this.function = function;
+ }
+
+ @Override
+ public @Nullable P get(T obj) {
+ return function.get(obj);
+ }
+
+ }
+
+ /**
+ * A Kotlin-based {@link PropertyReference} implementation that caches resolved metadata to avoid repeated
+ * introspection.
+ *
+ * @param the owning type.
+ * @param the property type.
+ */
+ static class ResolvedKPropertyReference extends ResolvedPropertyReferenceSupport {
+
+ private final KProperty property;
+
+ @SuppressWarnings("unchecked")
+ ResolvedKPropertyReference(KPropertyMetadata metadata) {
+ this((KProperty
) metadata.getProperty(), metadata);
+ }
+
+ ResolvedKPropertyReference(KProperty
property, PropertyMetadata metadata) {
+ super(metadata);
+ this.property = property;
+ }
+
+ @Override
+ public @Nullable P get(T obj) {
+ return property.call(obj);
+ }
+
+ }
+
+}
diff --git a/src/main/java/org/springframework/data/core/SerializableLambdaReader.java b/src/main/java/org/springframework/data/core/SerializableLambdaReader.java
new file mode 100644
index 0000000000..4ddeef66fe
--- /dev/null
+++ b/src/main/java/org/springframework/data/core/SerializableLambdaReader.java
@@ -0,0 +1,569 @@
+/*
+ * 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 kotlin.jvm.JvmClassMappingKt;
+import kotlin.jvm.internal.PropertyReference;
+import kotlin.reflect.KClass;
+import kotlin.reflect.KProperty1;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.lang.invoke.MethodHandleInfo;
+import java.lang.invoke.SerializedLambda;
+import java.lang.reflect.Member;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.function.Function;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+import org.jspecify.annotations.Nullable;
+import org.springframework.asm.ClassReader;
+import org.springframework.asm.ClassVisitor;
+import org.springframework.asm.Label;
+import org.springframework.asm.MethodVisitor;
+import org.springframework.asm.Opcodes;
+import org.springframework.asm.SpringAsmInfo;
+import org.springframework.asm.Type;
+import org.springframework.core.KotlinDetector;
+import org.springframework.core.SpringProperties;
+import org.springframework.dao.InvalidDataAccessApiUsageException;
+import org.springframework.data.core.MemberDescriptor.KPropertyPathDescriptor;
+import org.springframework.data.core.MemberDescriptor.KPropertyReferenceDescriptor;
+import org.springframework.util.ClassUtils;
+import org.springframework.util.ObjectUtils;
+import org.springframework.util.StringUtils;
+
+/**
+ * Reader to extract references to fields and methods from serializable lambda expressions and method references using
+ * lambda serialization and bytecode analysis. Allows introspection of property access patterns expressed through
+ * functional interfaces without executing the lambda's behavior. Their declarative nature makes method references in
+ * general and a constrained subset of lambda expressions suitable to declare property references in the sense of Java
+ * Beans properties. Although lambdas and method references are primarily used in a declarative functional programming
+ * models to express behavior, lambda serialization allows for further introspection such as parsing the lambda method
+ * bytecode for property or member access information and not taking the functional behavior into account.
+ *
+ * The actual interface is not constrained by a base type, however the object must:
+ *
+ * - Implement a functional Java interface
+ * - Must be the top-level lambda (i.e. not wrapped or a functional composition)
+ * - Implement Serializable (either through the actual interface or through inference)
+ * - Declare a single method to be implemented
+ * - Accept a single method argument and return a value
+ *
+ * Ideally, the interface has a similar format to {@link Function}, for example:
+ *
+ *
+ * interface XtoYFunction (optional: extends Serializable) {
+ * Y <method-name>(X someArgument);
+ * }
+ *
+ *
+ * Supported patterns
+ *
+ * - Method references: {@code Person::getName}
+ * - Property access lambdas: {@code person -> person.getName()}
+ * - Field access lambdas: {@code person -> person.name}
+ *
+ * Unsupported patterns
+ *
+ * - Constructor references: {@code Person::new}
+ * - Methods with arguments: {@code person -> person.setAge(25)}
+ * - Lambda expressions that do more than property access, e.g. {@code person -> { person.setAge(25); return
+ * person.getName(); }}
+ * - Arithmetic operations, arbitrary calls
+ * - Functional composition: {@code Function.andThen(...)}
+ *
+ *
+ * @author Mark Paluch
+ * @since 4.1
+ */
+class SerializableLambdaReader {
+
+ /**
+ * System property that instructs Spring Data to filter stack traces of exceptions thrown during SAM parsing.
+ */
+ public static final String FILTER_STACK_TRACE = "spring.data.lambda-reader.filter-stacktrace";
+
+ /**
+ * System property that instructs Spring Data to include suppressed exceptions during SAM parsing.
+ */
+ public static final String INCLUDE_SUPPRESSED_EXCEPTIONS = "spring.data.lambda-reader.include-suppressed-exceptions";
+
+ private static final Log LOGGER = LogFactory.getLog(SerializableLambdaReader.class);
+ private static final boolean filterStackTrace = isEnabled(FILTER_STACK_TRACE, true);
+ private static final boolean includeSuppressedExceptions = isEnabled(INCLUDE_SUPPRESSED_EXCEPTIONS, false);
+
+ private final List> entryPoints;
+
+ SerializableLambdaReader(Class... entryPoints) {
+ this.entryPoints = Arrays.asList(entryPoints);
+ }
+
+ private static boolean isEnabled(String property, boolean defaultValue) {
+
+ String value = SpringProperties.getProperty(property);
+ return StringUtils.hasText(value) ? Boolean.parseBoolean(value) : defaultValue;
+ }
+
+ /**
+ * Read the given lambda object and extract a reference to a {@link Member} such as a field or method.
+ *
+ * Ideally used with an interface resembling {@link java.util.function.Function}.
+ *
+ * @param lambdaObject the actual lambda object, must be {@link java.io.Serializable}.
+ * @return the member reference.
+ * @throws InvalidDataAccessApiUsageException if the lambda object does not contain a valid property reference or hits
+ * any of the mentioned limitations.
+ */
+ public MemberDescriptor read(Object lambdaObject) {
+
+ SerializedLambda lambda = serialize(lambdaObject);
+
+ if (isKotlinPropertyReference(lambda)) {
+ return KotlinDelegate.read(lambda);
+ }
+
+ assertNotConstructor(lambda);
+
+ try {
+
+ // method reference
+ if ((lambda.getImplMethodKind() == MethodHandleInfo.REF_invokeVirtual
+ || lambda.getImplMethodKind() == MethodHandleInfo.REF_invokeInterface)
+ && !lambda.getImplMethodName().startsWith("lambda$")) {
+ return MemberDescriptor.ofMethodReference(lambdaObject.getClass().getClassLoader(), lambda);
+ }
+
+ // all other lambda forms
+ if (lambda.getImplMethodKind() == MethodHandleInfo.REF_invokeStatic
+ || lambda.getImplMethodKind() == MethodHandleInfo.REF_invokeVirtual) {
+ return getMemberDescriptor(lambdaObject, lambda);
+ }
+ } catch (ReflectiveOperationException | IOException e) {
+ throw new InvalidDataAccessApiUsageException("Cannot extract method or field", e);
+ }
+
+ throw new InvalidDataAccessApiUsageException("Cannot extract method or field from: " + lambdaObject
+ + ". The given value is not a lambda or method reference.");
+ }
+
+ private void assertNotConstructor(SerializedLambda lambda) {
+
+ if (lambda.getImplMethodKind() == MethodHandleInfo.REF_newInvokeSpecial
+ || lambda.getImplMethodKind() == MethodHandleInfo.REF_invokeSpecial) {
+
+ InvalidDataAccessApiUsageException e = new InvalidDataAccessApiUsageException(
+ "Method reference must not be a constructor call");
+
+ if (filterStackTrace) {
+ e.setStackTrace(filterStackTrace(e.getStackTrace(), null));
+ }
+ throw e;
+ }
+ }
+
+ private MemberDescriptor getMemberDescriptor(Object lambdaObject, SerializedLambda lambda) throws IOException {
+
+ String implClass = Type.getObjectType(lambda.getImplClass()).getClassName();
+ Type owningType = Type.getArgumentTypes(lambda.getImplMethodSignature())[0];
+ String classFileName = implClass.replace('.', '/') + ".class";
+ InputStream classFile = ClassLoader.getSystemResourceAsStream(classFileName);
+
+ if (classFile == null) {
+ throw new IllegalStateException("Cannot find class file '%s' for lambda introspection".formatted(classFileName));
+ }
+
+ try (classFile) {
+
+ ClassReader cr = new ClassReader(classFile);
+ LambdaReadingVisitor classVisitor = new LambdaReadingVisitor(lambdaObject.getClass().getClassLoader(),
+ lambda.getImplMethodName(), owningType);
+ cr.accept(classVisitor, ClassReader.SKIP_FRAMES);
+ return classVisitor.getMemberReference(lambda);
+ }
+ }
+
+ private static SerializedLambda serialize(Object lambda) {
+
+ try {
+ Method method = lambda.getClass().getDeclaredMethod("writeReplace");
+ method.setAccessible(true);
+ return (SerializedLambda) method.invoke(lambda);
+ } catch (ReflectiveOperationException e) {
+ throw new InvalidDataAccessApiUsageException(
+ "Not a lambda: " + (lambda instanceof Enum ? lambda.getClass().getName() + "#" + lambda : lambda), e);
+ }
+ }
+
+ private static boolean isKotlinPropertyReference(SerializedLambda lambda) {
+
+ return KotlinDetector.isKotlinReflectPresent() //
+ && lambda.getCapturedArgCount() == 1 //
+ && lambda.getCapturedArg(0) != null //
+ && KotlinDetector.isKotlinType(lambda.getCapturedArg(0).getClass());
+ }
+
+ /**
+ * Delegate to detect and read Kotlin property references.
+ *
+ * Inner class delays loading of Kotlin classes.
+ */
+ static class KotlinDelegate {
+
+ public static MemberDescriptor read(SerializedLambda lambda) {
+
+ Object captured = lambda.getCapturedArg(0);
+
+ if (captured instanceof PropertyReference propRef //
+ && propRef.getOwner() instanceof KClass owner //
+ && captured instanceof KProperty1 kProperty) {
+ return new KPropertyReferenceDescriptor(JvmClassMappingKt.getJavaClass(owner), kProperty);
+ }
+
+ if (captured instanceof KPropertyPath propRef) {
+ return KPropertyPathDescriptor.create(propRef);
+ }
+
+ throw new InvalidDataAccessApiUsageException("Cannot extract MemberDescriptor from: " + lambda);
+ }
+
+ }
+
+ class LambdaReadingVisitor extends ClassVisitor {
+
+ private final String implMethodName;
+ private final LambdaMethodVisitor methodVisitor;
+
+ public LambdaReadingVisitor(ClassLoader classLoader, String implMethodName, Type owningType) {
+ super(SpringAsmInfo.ASM_VERSION);
+ this.implMethodName = implMethodName;
+ this.methodVisitor = new LambdaMethodVisitor(classLoader, owningType);
+ }
+
+ public MemberDescriptor getMemberReference(SerializedLambda lambda) {
+ return methodVisitor.resolve(lambda);
+ }
+
+ @Override
+ public @Nullable MethodVisitor visitMethod(int access, String name, String desc, String signature,
+ String[] exceptions) {
+ return name.equals(implMethodName) ? methodVisitor : null;
+ }
+
+ }
+
+ class LambdaMethodVisitor extends MethodVisitor {
+
+ private static final Pattern HEX_PATTERN = Pattern.compile("[0-9a-f]+");
+
+ private static final Set BOXING_TYPES = Set.of(Type.getInternalName(Integer.class),
+ Type.getInternalName(Long.class), Type.getInternalName(Short.class), Type.getInternalName(Byte.class),
+ Type.getInternalName(Float.class), Type.getInternalName(Double.class), Type.getInternalName(Character.class),
+ Type.getInternalName(Boolean.class));
+
+ private static final String BOXING_METHOD = "valueOf";
+
+ private final ClassLoader classLoader;
+ private final Type owningType;
+ private int line;
+ private final List memberDescriptors = new ArrayList<>();
+ private final Set errors = new LinkedHashSet<>();
+
+ public LambdaMethodVisitor(ClassLoader classLoader, Type owningType) {
+ super(SpringAsmInfo.ASM_VERSION);
+ this.classLoader = classLoader;
+ this.owningType = owningType;
+ }
+
+ @Override
+ public void visitLineNumber(int line, Label start) {
+ this.line = line;
+ }
+
+ @Override
+ public void visitInsn(int opcode) {
+
+ // allow primitive and object return
+ if (opcode >= Opcodes.IRETURN && opcode <= Opcodes.RETURN) {
+ return;
+ }
+
+ // we don't care about stack manipulation
+ if (opcode >= Opcodes.DUP && opcode <= Opcodes.DUP2_X2) {
+ return;
+ }
+
+ // no-op
+ if (opcode == Opcodes.NOP) {
+ return;
+ }
+
+ visitLdcInsn("");
+ }
+
+ @Override
+ public void visitLdcInsn(Object value) {
+ errors.add(new ReadingError(line,
+ "Code loads a constant. Only method calls to getters, record components, or field access allowed.", null));
+ }
+
+ @Override
+ public void visitFieldInsn(int opcode, String owner, String name, String descriptor) {
+
+ if (opcode == Opcodes.PUTSTATIC || opcode == Opcodes.PUTFIELD) {
+ errors.add(new ReadingError(line, String.format("Code attempts to set field '%s'", name), null));
+ return;
+ }
+
+ Type fieldType = Type.getType(descriptor);
+
+ try {
+ this.memberDescriptors
+ .add(MemberDescriptor.ofField(classLoader, owningType.getClassName(), name, fieldType.getClassName()));
+ } catch (ReflectiveOperationException e) {
+ if (LOGGER.isTraceEnabled()) {
+ LOGGER.trace("Failed to resolve field '%s.%s'".formatted(owner, name), e);
+ }
+ errors.add(new ReadingError(line, e.getMessage()));
+ }
+ }
+
+ @Override
+ public void visitMethodInsn(int opcode, String owner, String name, String descriptor, boolean isInterface) {
+
+ if (opcode == Opcodes.INVOKESPECIAL && name.equals("")) {
+ errors.add(new ReadingError(line, "Constructor calls not supported.", null));
+ return;
+ }
+
+ int count = Type.getArgumentCount(descriptor);
+
+ if (count != 0) {
+
+ if (BOXING_TYPES.contains(owner) && name.equals(BOXING_METHOD)) {
+ return;
+ }
+
+ errors.add(new ReadingError(line, "Method references must invoke no-arg methods only"));
+ return;
+ }
+
+ Type ownerType = Type.getObjectType(owner);
+ if (!ownerType.equals(this.owningType)) {
+
+ Type[] argumentTypes = Type.getArgumentTypes(descriptor);
+ String signature = Arrays.stream(argumentTypes).map(Type::getClassName).collect(Collectors.joining(", "));
+ errors.add(new ReadingError(line,
+ "Cannot derive method reference from '%s#%s(%s)': Method calls allowed on owning type '%s' only."
+ .formatted(ownerType.getClassName(), name, signature, this.owningType.getClassName())));
+ return;
+ }
+
+ try {
+ this.memberDescriptors.add(MemberDescriptor.ofMethod(classLoader, owningType.getClassName(), name));
+ } catch (ReflectiveOperationException e) {
+
+ if (LOGGER.isTraceEnabled()) {
+ LOGGER.trace("Failed to resolve method '%s.%s'".formatted(owner, name), e);
+ }
+ errors.add(new ReadingError(line, e.getMessage()));
+ }
+ }
+
+ /**
+ * Resolve a {@link MemberDescriptor} from a {@link SerializedLambda}.
+ *
+ * @param lambda the lambda to introspect.
+ * @return the resolved member descriptor.
+ */
+ public MemberDescriptor resolve(SerializedLambda lambda) {
+
+ // TODO composite path information
+ if (errors.isEmpty()) {
+
+ if (memberDescriptors.isEmpty()) {
+ throw new InvalidDataAccessApiUsageException("There is no method or field access");
+ }
+
+ return memberDescriptors.get(memberDescriptors.size() - 1);
+ }
+
+ if (lambda.getImplMethodKind() == MethodHandleInfo.REF_invokeStatic
+ || lambda.getImplMethodKind() == MethodHandleInfo.REF_invokeVirtual) {
+
+ String methodName = getDeclaringMethodName(lambda);
+
+ InvalidDataAccessApiUsageException e = new InvalidDataAccessApiUsageException(
+ "Cannot resolve property path%n%nError%s:%n".formatted(errors.size() > 1 ? "s" : "") + errors.stream()
+ .map(ReadingError::message).map(LambdaMethodVisitor::formatMessage).collect(Collectors.joining()));
+
+ if (includeSuppressedExceptions) {
+ for (ReadingError error : errors) {
+ if (error.e != null) {
+ e.addSuppressed(error.e);
+ }
+ }
+ }
+
+ if (filterStackTrace) {
+ e.setStackTrace(
+ filterStackTrace(e.getStackTrace(), userCode -> createSynthetic(lambda, methodName, userCode)));
+ }
+
+ throw e;
+ }
+
+ throw new InvalidDataAccessApiUsageException("Error resolving " + errors);
+ }
+
+ private static String formatMessage(String args) {
+
+ String[] split = args.split("%n".formatted());
+ StringBuilder builder = new StringBuilder();
+
+ for (int i = 0; i < split.length; i++) {
+
+ if (i == 0) {
+ builder.append("\t* %s%n".formatted(split[i]));
+ } else {
+ builder.append("\t %s%n".formatted(split[i]));
+ }
+ }
+
+ return builder.toString();
+ }
+
+ private static String getDeclaringMethodName(SerializedLambda lambda) {
+
+ String methodName = lambda.getImplMethodName();
+ if (methodName.startsWith("lambda$")) {
+ methodName = methodName.substring("lambda$".length());
+
+ if (methodName.contains("$")) {
+ methodName = methodName.substring(0, methodName.lastIndexOf('$'));
+ }
+
+ if (methodName.contains("$")) {
+ String probe = methodName.substring(methodName.lastIndexOf('$') + 1);
+ if (HEX_PATTERN.matcher(probe).matches()) {
+ methodName = methodName.substring(0, methodName.lastIndexOf('$'));
+ }
+ }
+ }
+ return methodName;
+ }
+
+ private StackTraceElement createSynthetic(SerializedLambda lambda, String methodName, StackTraceElement userCode) {
+
+ Type type = Type.getObjectType(lambda.getCapturingClass());
+
+ return new StackTraceElement(null, userCode.getModuleName(), userCode.getModuleVersion(), type.getClassName(),
+ methodName, ClassUtils.getShortName(type.getClassName()) + ".java", errors.iterator().next().line());
+ }
+ }
+
+ private StackTraceElement[] filterStackTrace(StackTraceElement[] stackTrace,
+ @Nullable Function syntheticSupplier) {
+
+ int filterIndex = findEntryPoint(stackTrace);
+
+ if (filterIndex != -1) {
+
+ int offset = syntheticSupplier == null ? 0 : 1;
+
+ StackTraceElement[] copy = new StackTraceElement[(stackTrace.length - filterIndex) + offset];
+ System.arraycopy(stackTrace, filterIndex, copy, offset, stackTrace.length - filterIndex);
+
+ if (syntheticSupplier != null) {
+ StackTraceElement userCode = copy[1];
+ StackTraceElement synthetic = syntheticSupplier.apply(userCode);
+ copy[0] = synthetic;
+ }
+ return copy;
+ }
+
+ return stackTrace;
+ }
+
+ private int findEntryPoint(StackTraceElement[] stackTrace) {
+
+ int filterIndex = -1;
+
+ for (int i = 0; i < stackTrace.length; i++) {
+
+ if (matchesEntrypoint(stackTrace[i].getClassName())) {
+ filterIndex = i;
+ }
+ }
+
+ return filterIndex;
+ }
+
+ private boolean matchesEntrypoint(String className) {
+
+ if (className.equals(getClass().getName())) {
+ return true;
+ }
+
+ for (Class entryPoint : entryPoints) {
+ if (className.equals(entryPoint.getName())) {
+ return true;
+ }
+ }
+
+ return false;
+ }
+
+ /**
+ * Value object for reading errors.
+ *
+ * @param line
+ * @param message
+ * @param e
+ */
+ record ReadingError(int line, String message, @Nullable Exception e) {
+
+ ReadingError(int line, String message) {
+ this(line, message, null);
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ if (!(o instanceof ReadingError that)) {
+ return false;
+ }
+ if (!ObjectUtils.nullSafeEquals(e, that.e)) {
+ return false;
+ }
+ return ObjectUtils.nullSafeEquals(message, that.message);
+ }
+
+ @Override
+ public int hashCode() {
+ return ObjectUtils.nullSafeHash(message, e);
+ }
+
+ }
+
+}
diff --git a/src/main/java/org/springframework/data/core/SimplePropertyPath.java b/src/main/java/org/springframework/data/core/SimplePropertyPath.java
index be48ce3637..a8dfb2211a 100644
--- a/src/main/java/org/springframework/data/core/SimplePropertyPath.java
+++ b/src/main/java/org/springframework/data/core/SimplePropertyPath.java
@@ -148,16 +148,6 @@ public boolean isCollection() {
return isCollection;
}
- @Override
- public SimplePropertyPath nested(String path) {
-
- Assert.hasText(path, "Path must not be null or empty");
-
- String lookup = toDotPath().concat(".").concat(path);
-
- return SimplePropertyPath.from(lookup, owningType);
- }
-
@Override
public Iterator iterator() {
@@ -187,45 +177,12 @@ public boolean hasNext() {
@Override
public boolean equals(@Nullable Object o) {
-
- if (this == o) {
- return true;
- }
-
- if (!(o instanceof SimplePropertyPath that)) {
- return false;
- }
-
- if (isCollection != that.isCollection) {
- return false;
- }
-
- return Objects.equals(this.owningType, that.owningType) && Objects.equals(this.name, that.name)
- && Objects.equals(this.typeInformation, that.typeInformation)
- && Objects.equals(this.actualTypeInformation, that.actualTypeInformation) && Objects.equals(next, that.next);
+ return PropertyPathUtil.equals(this, o);
}
@Override
public int hashCode() {
- return Objects.hash(owningType, name, typeInformation, actualTypeInformation, isCollection, next);
- }
-
- /**
- * Returns the next {@link SimplePropertyPath}.
- *
- * @return the next {@link SimplePropertyPath}.
- * @throws IllegalStateException it there's no next one.
- */
- private SimplePropertyPath requiredNext() {
-
- SimplePropertyPath result = next;
-
- if (result == null) {
- throw new IllegalStateException(
- "No next path available; Clients should call hasNext() before invoking this method");
- }
-
- return result;
+ return PropertyPathUtil.hashCode(this);
}
/**
diff --git a/src/main/java/org/springframework/data/core/TypedPropertyPath.java b/src/main/java/org/springframework/data/core/TypedPropertyPath.java
new file mode 100644
index 0000000000..66d788b2ce
--- /dev/null
+++ b/src/main/java/org/springframework/data/core/TypedPropertyPath.java
@@ -0,0 +1,247 @@
+/*
+ * 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.io.Serializable;
+import java.util.Collections;
+import java.util.Iterator;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Interface providing type-safe property path navigation through method references expressions.
+ *
+ * This functional interface extends {@link PropertyPath} to provide compile-time type safety and refactoring support.
+ * Instead of using {@link PropertyPath#from(String, TypeInformation) string-based property paths} for textual property
+ * representation that are easy to miss when changing the domain model, {@code TypedPropertyPath} leverages Java's
+ * declarative method references to ensure type-safe property access.
+ *
+ * Create a typed property path using the static factory method {@link #of(TypedPropertyPath)} with a method reference ,
+ * for example:
+ *
+ *
+ * TypedPropertyPath.path(Person::getName);
+ *
+ *
+ * The resulting object can be used to obtain the {@link #toDotPath() dot-path} and to interact with the targeting
+ * property. Typed paths allow for composition to navigate nested object structures using
+ * {@link #then(PropertyReference)}:
+ *
+ *
+ * // factory method chaining
+ * TypedPropertyPath<Person, String> city = TypedPropertyPath.path(Person::getAddress, Address::getCity);
+ *
+ * // fluent API
+ * TypedPropertyPath<Person, String> city = TypedPropertyPath.of(Person::getAddress).then(Address::getCity);
+ *
+ *
+ * The generic type parameters preserve type information across the property path chain: {@code T} represents the owning
+ * type of the current segment (or the root type for composed paths), while {@code P} represents the property value type
+ * at this segment. Composition automatically flows type information forward, ensuring that {@code then()} preserves the
+ * full chain's type safety.
+ *
+ * Implement {@code TypedPropertyPath} using method references (strongly recommended)s that directly access a property
+ * getter. Constructor references, method calls with parameters, and complex expressions are not supported and result in
+ * {@link org.springframework.dao.InvalidDataAccessApiUsageException}. Unlike method references, introspection of lambda
+ * expressions requires bytecode analysis of the declaration site classes and thus depends on their availability at
+ * runtime.
+ *
+ * @param the owning type of this path segment; the root type for composed paths.
+ * @param the property value type at this path segment.
+ * @author Mark Paluch
+ * @since 4.1
+ * @see #path(PropertyReference)
+ * @see #of(PropertyReference)
+ * @see #ofMany(PropertyReference)
+ * @see #then(PropertyReference)
+ * @see PropertyReference
+ * @see PropertyPath#of(PropertyReference)
+ */
+@FunctionalInterface
+public interface TypedPropertyPath extends PropertyPath, Serializable {
+
+ /**
+ * Syntax sugar to create a {@link TypedPropertyPath} from a property described as method reference to a Java beans
+ * property. Suitable for static imports.
+ *
+ * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method reference.
+ *
+ * @param property the method reference to a Java beans property.
+ * @param owning type.
+ * @param property type.
+ * @return the typed property path.
+ */
+ static TypedPropertyPath path(PropertyReference property) {
+ return TypedPropertyPaths.of(property);
+ }
+
+ /**
+ * Syntax sugar to create a composed {@link TypedPropertyPath} from properties described as method reference to a Java
+ * beans property. Suitable for static imports.
+ *
+ * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method references.
+ *
+ * @param owner the owner property.
+ * @param child the nested property.
+ * @param owning type.
+ * @param property type.
+ * @return the typed property path.
+ */
+ static TypedPropertyPath path(PropertyReference owner,
+ PropertyReference child) {
+ return TypedPropertyPaths.compose(owner, child);
+ }
+
+ /**
+ * Syntax sugar to create a composed {@link TypedPropertyPath} from properties described as method reference to a Java
+ * beans property. Suitable for static imports.
+ *
+ * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method references.
+ *
+ * @param owner the owner property.
+ * @param child1 the first nested property.
+ * @param child2 the second nested property.
+ * @param owning type.
+ * @param property type.
+ * @return the typed property path.
+ */
+ static TypedPropertyPath path(PropertyReference owner,
+ PropertyReference child1, PropertyReference child2) {
+ return path(owner, child1).then(child2);
+ }
+
+ /**
+ * Syntax sugar to create a composed {@link TypedPropertyPath} from properties described as method reference to a Java
+ * beans property. Suitable for static imports.
+ *
+ * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method references.
+ *
+ * @param owner the owner property.
+ * @param child1 the first nested property.
+ * @param child2 the second nested property.
+ * @param child3 the third nested property.
+ * @param owning type.
+ * @param property type.
+ * @return the typed property path.
+ */
+ static TypedPropertyPath path(
+ PropertyReference owner, PropertyReference child1,
+ PropertyReference child2, PropertyReference child3) {
+ return path(owner, child1, child2).then(child3);
+ }
+
+ /**
+ * Syntax sugar to create a {@link TypedPropertyPath} from a method reference to a Java beans property.
+ *
+ * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method reference.
+ *
+ * @param property the method reference to a Java beans property.
+ * @param owning type.
+ * @param property type.
+ * @return the typed property path.
+ */
+ static TypedPropertyPath of(TypedPropertyPath property) {
+ return TypedPropertyPaths.of(property);
+ }
+
+ /**
+ * Syntax sugar to create a {@link TypedPropertyPath} from a method reference to a Java beans collection property.
+ *
+ * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method reference.
+ *
+ * Note that {@link #get(Object)} becomes unusable for collection properties as the property type adapted from
+ * {@code Iterable <P>} and a single {@code P} cannot represent a collection of items.
+ *
+ * @param property the method reference to a Java beans collection property.
+ * @param owning type.
+ * @param property type.
+ * @return the typed property path.
+ */
+ @SuppressWarnings({ "unchecked", "rawtypes" })
+ static TypedPropertyPath ofMany(TypedPropertyPath> property) {
+ return (TypedPropertyPath) TypedPropertyPaths.of(property);
+ }
+
+ /**
+ * Get the property value for the given object.
+ *
+ * @param obj the object to get the property value from.
+ * @return the property value.
+ */
+ @Nullable
+ P get(T obj);
+
+ @Override
+ default TypeInformation getOwningType() {
+ return TypedPropertyPaths.of(this).getOwningType();
+ }
+
+ @Override
+ default String getSegment() {
+ return TypedPropertyPaths.of(this).getSegment();
+ }
+
+ @Override
+ default TypeInformation getTypeInformation() {
+ return TypedPropertyPaths.of(this).getTypeInformation();
+ }
+
+ @Override
+ @Nullable
+ default PropertyPath next() {
+ return null;
+ }
+
+ @Override
+ default boolean hasNext() {
+ return false;
+ }
+
+ @Override
+ default Iterator iterator() {
+ return Collections.singletonList((PropertyPath) this).iterator();
+ }
+
+ /**
+ * Extend the property path by appending the {@code next} path segment and return a new property path instance.
+ *
+ * @param next the next property path segment as method reference accepting the owner object {@code P} type and
+ * returning {@code N} as result of accessing a property.
+ * @param the new property value type.
+ * @return a new composed {@code TypedPropertyPath}.
+ */
+ default TypedPropertyPath then(PropertyReference next) {
+ return TypedPropertyPaths.compose(this, next);
+ }
+
+ /**
+ * Extend the property path by appending the {@code next} path segment and return a new property path instance.
+ *
+ * Note that {@link #get(Object)} becomes unusable for collection properties as the property type adapted from
+ * {@code Iterable <P>} and a single {@code P} cannot represent a collection of items.
+ *
+ * @param next the next property path segment as method reference accepting the owner object {@code P} type and
+ * returning {@code N} as result of accessing a property.
+ * @param the new property value type.
+ * @return a new composed {@code TypedPropertyPath}.
+ */
+ @SuppressWarnings({ "unchecked", "rawtypes" })
+ default TypedPropertyPath thenMany(
+ PropertyReference> next) {
+ return (TypedPropertyPath) TypedPropertyPaths.compose(this, PropertyReference.of(next));
+ }
+
+}
diff --git a/src/main/java/org/springframework/data/core/TypedPropertyPaths.java b/src/main/java/org/springframework/data/core/TypedPropertyPaths.java
new file mode 100644
index 0000000000..d82c35904b
--- /dev/null
+++ b/src/main/java/org/springframework/data/core/TypedPropertyPaths.java
@@ -0,0 +1,571 @@
+/*
+ * 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 kotlin.reflect.KProperty;
+import kotlin.reflect.KProperty1;
+import kotlin.reflect.jvm.internal.KProperty1Impl;
+import kotlin.reflect.jvm.internal.KPropertyImpl;
+
+import java.io.Serializable;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import java.util.WeakHashMap;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import org.jspecify.annotations.Nullable;
+
+import org.springframework.core.KotlinDetector;
+import org.springframework.core.ResolvableType;
+import org.springframework.data.core.MemberDescriptor.KPropertyPathDescriptor;
+import org.springframework.data.core.MemberDescriptor.KPropertyReferenceDescriptor;
+import org.springframework.data.core.MemberDescriptor.MethodDescriptor;
+import org.springframework.data.core.PropertyReferences.PropertyMetadata;
+import org.springframework.util.CompositeIterator;
+import org.springframework.util.ConcurrentReferenceHashMap;
+
+/**
+ * Utility class to read metadata and resolve {@link TypedPropertyPath} instances.
+ *
+ * @author Mark Paluch
+ * @since 4.1
+ */
+class TypedPropertyPaths {
+
+ private static final Map>> resolved = new WeakHashMap<>();
+
+ private static final SerializableLambdaReader reader = new SerializableLambdaReader(PropertyPath.class,
+ PropertyReference.class, PropertyReferences.class, TypedPropertyPath.class, TypedPropertyPaths.class);
+
+ /**
+ * Compose a {@link TypedPropertyPath} by appending {@code next}.
+ */
+ public static TypedPropertyPath compose(PropertyReference owner, PropertyReference next) {
+ return compose(of(owner), of(next));
+ }
+
+ /**
+ * Compose a {@link TypedPropertyPath} by appending {@code next}.
+ */
+ public static TypedPropertyPath compose(TypedPropertyPath owner, PropertyReference next) {
+ return compose(of(owner), of(next));
+ }
+
+ /**
+ * Compose a {@link TypedPropertyPath} by appending {@code next}.
+ */
+ @SuppressWarnings({ "rawtypes", "unchecked" })
+ public static TypedPropertyPath compose(TypedPropertyPath owner, TypedPropertyPath next) {
+
+ if (owner instanceof ForwardingPropertyPath fwd) {
+
+ List paths = fwd.stream().map(ForwardingPropertyPath::getSelf).collect(Collectors.toList());
+ Collections.reverse(paths);
+
+ ForwardingPropertyPath result = null;
+ for (PropertyPath path : paths) {
+
+ if (result == null) {
+ result = new ForwardingPropertyPath((TypedPropertyPath) path, next);
+ } else {
+ result = new ForwardingPropertyPath((TypedPropertyPath) path, result);
+ }
+ }
+
+ return result;
+ }
+
+ return new ForwardingPropertyPath<>(of(owner), next);
+ }
+
+ /**
+ * Introspect {@link PropertyReference} and return an introspected {@link ResolvedTypedPropertyPath} variant.
+ */
+ @SuppressWarnings({ "unchecked", "rawtypes" })
+ public static TypedPropertyPath of(PropertyReference lambda) {
+
+ if (lambda instanceof Resolved) {
+ return (TypedPropertyPath) lambda;
+ }
+
+ Map, TypedPropertyPath> cache;
+ synchronized (resolved) {
+ cache = (Map) resolved.computeIfAbsent(lambda.getClass().getClassLoader(),
+ k -> new ConcurrentReferenceHashMap<>());
+ }
+
+ return (TypedPropertyPath) cache.computeIfAbsent(lambda, TypedPropertyPaths::doResolvePropertyReference);
+ }
+
+ @SuppressWarnings({ "rawtypes", "unchecked" })
+ private static TypedPropertyPath doResolvePropertyReference(PropertyReference lambda) {
+
+ if (lambda instanceof PropertyReferences.ResolvedPropertyReferenceSupport resolved) {
+ return new PropertyReferenceWrapper<>(resolved);
+ }
+
+ PropertyMetadata metadata = read(lambda);
+
+ if (KotlinDetector.isKotlinReflectPresent()) {
+ if (metadata instanceof KPropertyPathMetadata kMetadata
+ && kMetadata.getProperty() instanceof KPropertyPath ref) {
+ return KotlinDelegate.of(ref);
+ }
+ }
+
+ return new ResolvedPropertyReference<>(lambda, metadata);
+ }
+
+ /**
+ * Introspect {@link TypedPropertyPath} and return an introspected {@link ResolvedTypedPropertyPath} variant.
+ */
+ @SuppressWarnings({ "unchecked", "rawtypes" })
+ public static TypedPropertyPath of(TypedPropertyPath lambda) {
+
+ if (lambda instanceof Resolved) {
+ return lambda;
+ }
+
+ Map, TypedPropertyPath> cache;
+ synchronized (resolved) {
+ cache = (Map) resolved.computeIfAbsent(lambda.getClass().getClassLoader(),
+ k -> new ConcurrentReferenceHashMap<>());
+ }
+
+ return (TypedPropertyPath) cache.computeIfAbsent(lambda,
+ TypedPropertyPaths::doResolvePropertyPathReference);
+ }
+
+ private static TypedPropertyPath doResolvePropertyPathReference(TypedPropertyPath lambda) {
+
+ PropertyMetadata metadata = read(lambda);
+
+ if (KotlinDetector.isKotlinReflectPresent()) {
+ if (metadata instanceof KPropertyPathMetadata kMetadata
+ && kMetadata.getProperty() instanceof KPropertyPath ref) {
+ return KotlinDelegate.of(ref);
+ }
+ }
+
+ return new ResolvedTypedPropertyPath<>(lambda, metadata);
+ }
+
+ private static PropertyMetadata read(Object lambda) {
+
+ MemberDescriptor reference = reader.read(lambda);
+
+ if (KotlinDetector.isKotlinReflectPresent()) {
+
+ if (reference instanceof KPropertyReferenceDescriptor descriptor) {
+ return KPropertyPathMetadata.of(descriptor);
+ }
+
+ if (reference instanceof KPropertyPathDescriptor descriptor) {
+ return KPropertyPathMetadata.of(descriptor);
+ }
+ }
+
+ if (reference instanceof MethodDescriptor method) {
+ return PropertyMetadata.ofMethod(method);
+ }
+
+ return PropertyMetadata.ofField((MemberDescriptor.MethodDescriptor.FieldDescriptor) reference);
+ }
+
+ /**
+ * Kotlin-specific {@link PropertyMetadata} implementation supporting composed {@link KProperty property paths}.
+ */
+ static class KPropertyPathMetadata extends PropertyMetadata {
+
+ private final KProperty property;
+
+ KPropertyPathMetadata(Class owner, KProperty property, ResolvableType propertyType) {
+ super(owner, property.getName(), propertyType);
+ this.property = property;
+ }
+
+ /**
+ * Create a new {@code KPropertyPathMetadata}.
+ */
+ public static KPropertyPathMetadata of(KPropertyReferenceDescriptor descriptor) {
+ return new KPropertyPathMetadata(descriptor.getOwner(), descriptor.property(), descriptor.getType());
+ }
+
+ /**
+ * Create a new {@code KPropertyPathMetadata}.
+ */
+ public static KPropertyPathMetadata of(KPropertyPathDescriptor descriptor) {
+ return new KPropertyPathMetadata(descriptor.getOwner(), descriptor.property(), descriptor.getType());
+ }
+
+ public KProperty getProperty() {
+ return property;
+ }
+ }
+
+ /**
+ * Delegate to handle property path composition of single-property and property-path KProperty1 references.
+ */
+ static class KotlinDelegate {
+
+ @SuppressWarnings({ "rawtypes", "unchecked" })
+ public static TypedPropertyPath of(Object property) {
+
+ if (property instanceof KPropertyPath paths) {
+
+ TypedPropertyPath parent = of(paths.getProperty());
+ TypedPropertyPath child = of(paths.getLeaf());
+
+ return TypedPropertyPaths.compose(parent, child);
+ }
+
+ if (property instanceof KPropertyImpl impl) {
+
+ Class owner = impl.getJavaField() != null ? impl.getJavaField().getDeclaringClass()
+ : impl.getGetter().getCaller().getMember().getDeclaringClass();
+ KPropertyPathMetadata metadata = TypedPropertyPaths.KPropertyPathMetadata
+ .of(MemberDescriptor.KPropertyReferenceDescriptor.create(owner, (KProperty1) impl));
+ return new TypedPropertyPaths.ResolvedKPropertyPath(metadata);
+ }
+
+ if (property instanceof KProperty1 kProperty) {
+
+ if (kProperty.getGetter().getProperty() instanceof KProperty1Impl impl) {
+ return of(impl);
+ }
+
+ throw new IllegalArgumentException("Property " + kProperty.getName() + " is not a KProperty");
+ }
+
+ throw new IllegalArgumentException("Property " + property + " is not a KProperty");
+ }
+
+ }
+
+ /**
+ * Marker interface to indicate a resolved and processed property path.
+ */
+ interface Resolved {
+
+ }
+
+ /**
+ * A {@link TypedPropertyPath} implementation that caches resolved metadata to avoid repeated introspection.
+ *
+ * @param the owning type.
+ * @param the property type.
+ */
+ static abstract class ResolvedTypedPropertyPathSupport implements TypedPropertyPath, Resolved {
+
+ private final PropertyMetadata metadata;
+ private final List list;
+ private final String toString;
+
+ ResolvedTypedPropertyPathSupport(PropertyMetadata metadata) {
+ this.metadata = metadata;
+ this.list = List.of(this);
+ this.toString = metadata.owner().getType().getSimpleName() + "." + toDotPath();
+ }
+
+ @Override
+ @SuppressWarnings("unchecked")
+ public TypeInformation getOwningType() {
+ return (TypeInformation) metadata.owner();
+ }
+
+ @Override
+ public String getSegment() {
+ return metadata.property();
+ }
+
+ @Override
+ @SuppressWarnings("unchecked")
+ public TypeInformation getTypeInformation() {
+ return (TypeInformation
) metadata.propertyType();
+ }
+
+ @Override
+ public Iterator iterator() {
+ return list.iterator();
+ }
+
+ @Override
+ public Stream stream() {
+ return list.stream();
+ }
+
+ @Override
+ public List toList() {
+ return list;
+ }
+
+ @Override
+ public boolean equals(@Nullable Object obj) {
+ return PropertyPathUtil.equals(this, obj);
+ }
+
+ @Override
+ public int hashCode() {
+ return PropertyPathUtil.hashCode(this);
+ }
+
+ @Override
+ public String toString() {
+ return toString;
+ }
+
+ }
+
+ /**
+ * Wrapper for {@link PropertyReference}.
+ *
+ * @param the owning type.
+ * @param the property type.
+ */
+ static class PropertyReferenceWrapper implements TypedPropertyPath, Resolved {
+
+ private final PropertyReference property;
+ private final List self;
+
+ public PropertyReferenceWrapper(PropertyReference property) {
+ this.property = property;
+ this.self = List.of(this);
+ }
+
+ @Override
+ public @Nullable P get(T obj) {
+ return property.get(obj);
+ }
+
+ @Override
+ public TypeInformation getOwningType() {
+ return property.getOwningType();
+ }
+
+ @Override
+ public String getSegment() {
+ return property.getName();
+ }
+
+ @Override
+ @SuppressWarnings("unchecked")
+ public TypeInformation getTypeInformation() {
+ return (TypeInformation
) property.getTypeInformation();
+ }
+
+ @Override
+ public Iterator iterator() {
+ return self.iterator();
+ }
+
+ @Override
+ public Stream stream() {
+ return self.stream();
+ }
+
+ @Override
+ public List toList() {
+ return self;
+ }
+
+ @Override
+ public boolean equals(@Nullable Object obj) {
+ return PropertyPathUtil.equals(this, obj);
+ }
+
+ @Override
+ public int hashCode() {
+ return PropertyPathUtil.hashCode(this);
+ }
+
+ @Override
+ public String toString() {
+ return property.toString();
+ }
+
+ }
+
+ /**
+ * A {@link TypedPropertyPath} implementation that caches resolved metadata to avoid repeated introspection.
+ *
+ * @param the owning type.
+ * @param the property type.
+ */
+ static class ResolvedPropertyReference extends ResolvedTypedPropertyPathSupport {
+
+ private final PropertyReference function;
+
+ ResolvedPropertyReference(PropertyReference function, PropertyMetadata metadata) {
+ super(metadata);
+ this.function = function;
+ }
+
+ @Override
+ public @Nullable P get(T obj) {
+ return function.get(obj);
+ }
+
+ }
+
+ /**
+ * A {@link TypedPropertyPath} implementation that caches resolved metadata to avoid repeated introspection.
+ *
+ * @param the owning type.
+ * @param the property type.
+ */
+ static class ResolvedTypedPropertyPath extends ResolvedTypedPropertyPathSupport {
+
+ private final TypedPropertyPath function;
+
+ ResolvedTypedPropertyPath(TypedPropertyPath function, PropertyMetadata metadata) {
+ super(metadata);
+ this.function = function;
+ }
+
+ @Override
+ public @Nullable P get(T obj) {
+ return function.get(obj);
+ }
+
+ }
+
+ /**
+ * A Kotlin-based {@link TypedPropertyPath} implementation that caches resolved metadata to avoid repeated
+ * introspection.
+ *
+ * @param the owning type.
+ * @param the property type.
+ */
+ static class ResolvedKPropertyPath extends ResolvedTypedPropertyPathSupport {
+
+ private final KProperty property;
+
+ @SuppressWarnings("unchecked")
+ ResolvedKPropertyPath(KPropertyPathMetadata metadata) {
+ this((KProperty
) metadata.getProperty(), metadata);
+ }
+
+ ResolvedKPropertyPath(KProperty
property, PropertyMetadata metadata) {
+ super(metadata);
+ this.property = property;
+ }
+
+ @Override
+ public @Nullable P get(T obj) {
+ return property.call(obj);
+ }
+
+ }
+
+ /**
+ * Forwarding implementation to compose a linked {@link TypedPropertyPath} graph.
+ *
+ * @param self
+ * @param nextSegment
+ * @param leaf cached leaf property.
+ * @param toStringRepresentation cached toString representation.
+ */
+ record ForwardingPropertyPath(TypedPropertyPath self, TypedPropertyPath nextSegment,
+ PropertyPath leaf, String dotPath, String toStringRepresentation) implements TypedPropertyPath, Resolved {
+
+ public ForwardingPropertyPath(TypedPropertyPath self, TypedPropertyPath nextSegment) {
+ this(self, nextSegment, nextSegment.getLeafProperty(), getDotPath(self, nextSegment),
+ getToString(self, nextSegment));
+ }
+
+ private static String getToString(PropertyPath self, PropertyPath nextSegment) {
+ return self.getOwningType().getType().getSimpleName() + "." + getDotPath(self, nextSegment);
+ }
+
+ private static String getDotPath(PropertyPath self, PropertyPath nextSegment) {
+ return self.getSegment() + "." + nextSegment.toDotPath();
+ }
+
+ public static PropertyPath getSelf(PropertyPath path) {
+ return path instanceof ForwardingPropertyPath fwd ? fwd.self() : path;
+ }
+
+ @Override
+ public @Nullable P get(T obj) {
+ M intermediate = self.get(obj);
+ return intermediate != null ? nextSegment.get(intermediate) : null;
+ }
+
+ @Override
+ public TypeInformation getOwningType() {
+ return self.getOwningType();
+ }
+
+ @Override
+ public String getSegment() {
+ return self.getSegment();
+ }
+
+ @Override
+ public PropertyPath getLeafProperty() {
+ return leaf;
+ }
+
+ @Override
+ public String toDotPath() {
+ return self.getSegment() + "." + nextSegment.toDotPath();
+ }
+
+ @Override
+ @SuppressWarnings("unchecked")
+ public TypeInformation getTypeInformation() {
+ return (TypeInformation
) self.getTypeInformation();
+ }
+
+ @Override
+ public boolean hasNext() {
+ return true;
+ }
+
+ @Override
+ public PropertyPath next() {
+ return nextSegment;
+ }
+
+ @Override
+ public Iterator iterator() {
+
+ CompositeIterator iterator = new CompositeIterator<>();
+ iterator.add(List.of((PropertyPath) this).iterator());
+ iterator.add(nextSegment.iterator());
+ return iterator;
+ }
+
+ @Override
+ public boolean equals(@Nullable Object o) {
+ return PropertyPathUtil.equals(this, o);
+ }
+
+ @Override
+ public int hashCode() {
+ return PropertyPathUtil.hashCode(this);
+ }
+
+ @Override
+ public String toString() {
+ return toStringRepresentation;
+ }
+ }
+
+}
diff --git a/src/main/java/org/springframework/data/domain/ExampleMatcher.java b/src/main/java/org/springframework/data/domain/ExampleMatcher.java
index e59698a719..cc842b8f39 100644
--- a/src/main/java/org/springframework/data/domain/ExampleMatcher.java
+++ b/src/main/java/org/springframework/data/domain/ExampleMatcher.java
@@ -15,6 +15,7 @@
*/
package org.springframework.data.domain;
+import java.util.Arrays;
import java.util.Collection;
import java.util.LinkedHashMap;
import java.util.Map;
@@ -24,6 +25,7 @@
import org.jspecify.annotations.Nullable;
+import org.springframework.data.core.TypedPropertyPath;
import org.springframework.lang.CheckReturnValue;
import org.springframework.lang.Contract;
import org.springframework.util.Assert;
@@ -77,6 +79,21 @@ static ExampleMatcher matchingAll() {
return new TypedExampleMatcher().withMode(MatchMode.ALL);
}
+ /**
+ * Returns a copy of this {@link ExampleMatcher} with the specified {@code propertyPaths}. This instance is immutable
+ * and unaffected by this method call.
+ *
+ * @param ignoredPaths must not be {@literal null} and not empty.
+ * @return new instance of {@link ExampleMatcher}.
+ * @since 4.1
+ */
+ @Contract("_ -> new")
+ @CheckReturnValue
+ default ExampleMatcher withIgnorePaths(TypedPropertyPath... ignoredPaths) {
+ return withIgnorePaths(Arrays.stream(ignoredPaths).map(TypedPropertyPath::of).map(TypedPropertyPath::toDotPath)
+ .toArray(String[]::new));
+ }
+
/**
* Returns a copy of this {@link ExampleMatcher} with the specified {@code propertyPaths}. This instance is immutable
* and unaffected by this method call.
@@ -122,6 +139,22 @@ default ExampleMatcher withIgnoreCase() {
@CheckReturnValue
ExampleMatcher withIgnoreCase(boolean defaultIgnoreCase);
+ /**
+ * Returns a copy of this {@link ExampleMatcher} with the specified {@code GenericPropertyMatcher} for the
+ * {@code propertyPath}. This instance is immutable and unaffected by this method call.
+ *
+ * @param propertyPath must not be {@literal null}.
+ * @param matcherConfigurer callback to configure a {@link GenericPropertyMatcher}, must not be {@literal null}.
+ * @return new instance of {@link ExampleMatcher}.
+ * @since 4.1
+ */
+ @Contract("_, _ -> new")
+ @CheckReturnValue
+ default ExampleMatcher withMatcher(TypedPropertyPath propertyPath,
+ MatcherConfigurer matcherConfigurer) {
+ return withMatcher(propertyPath.toDotPath(), matcherConfigurer);
+ }
+
/**
* Returns a copy of this {@link ExampleMatcher} with the specified {@code GenericPropertyMatcher} for the
* {@code propertyPath}. This instance is immutable and unaffected by this method call.
@@ -143,6 +176,21 @@ default ExampleMatcher withMatcher(String propertyPath, MatcherConfigurer new")
+ @CheckReturnValue
+ default ExampleMatcher withMatcher(TypedPropertyPath propertyPath,
+ GenericPropertyMatcher genericPropertyMatcher) {
+ return withMatcher(propertyPath.toDotPath(), genericPropertyMatcher);
+ }
+
/**
* Returns a copy of this {@link ExampleMatcher} with the specified {@code GenericPropertyMatcher} for the
* {@code propertyPath}. This instance is immutable and unaffected by this method call.
@@ -155,6 +203,22 @@ default ExampleMatcher withMatcher(String propertyPath, MatcherConfigurer new")
+ @CheckReturnValue
+ default ExampleMatcher withTransformer(TypedPropertyPath propertyPath,
+ PropertyValueTransformer propertyValueTransformer) {
+ return withTransformer(propertyPath.toDotPath(), propertyValueTransformer);
+ }
+
/**
* Returns a copy of this {@link ExampleMatcher} with the specified {@code PropertyValueTransformer} for the
* {@code propertyPath}.
@@ -167,6 +231,20 @@ default ExampleMatcher withMatcher(String propertyPath, MatcherConfigurer new")
+ @CheckReturnValue
+ default ExampleMatcher withIgnoreCase(TypedPropertyPath... propertyPaths) {
+ return withIgnoreCase(Arrays.stream(propertyPaths).map(TypedPropertyPath::of).map(TypedPropertyPath::toDotPath)
+ .toArray(String[]::new));
+ }
+
/**
* Returns a copy of this {@link ExampleMatcher} with ignore case sensitivity for the {@code propertyPaths}. This
* instance is immutable and unaffected by this method call.
diff --git a/src/main/java/org/springframework/data/domain/Sort.java b/src/main/java/org/springframework/data/domain/Sort.java
index f3d39640dd..44aad6693d 100644
--- a/src/main/java/org/springframework/data/domain/Sort.java
+++ b/src/main/java/org/springframework/data/domain/Sort.java
@@ -29,6 +29,8 @@
import org.jspecify.annotations.Nullable;
+import org.springframework.data.core.PropertyPath;
+import org.springframework.data.core.TypedPropertyPath;
import org.springframework.data.util.MethodInvocationRecorder;
import org.springframework.data.util.MethodInvocationRecorder.Recorded;
import org.springframework.data.util.Streamable;
@@ -94,6 +96,24 @@ public static Sort by(String... properties) {
: new Sort(DEFAULT_DIRECTION, Arrays.asList(properties));
}
+ /**
+ * Creates a new {@link Sort} for the given properties.
+ *
+ * @param properties must not be {@literal null}.
+ * @return {@link Sort} for the given properties.
+ * @since 4.1
+ */
+ @SafeVarargs
+ public static Sort by(TypedPropertyPath