Documentation.

Author: mp911de

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

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

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

@@ -50,10 +50,52 @@
 import org.springframework.util.StringUtils;
 
 /**
- * Utility to parse Single Abstract Method (SAM) method references and lambdas to extract the owning type and the member
- * that is being accessed from it.
+ * Utility to parse and introspect objects implementing a Single Abstract Method (SAM) interfaces (functional
+ * interfaces) through lambda expressions and method references. 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.
+ * <p>
+ * Objects can be Java method references and lambda expressions. The actual interface is not constrained by a base type,
+ * however the object must:
+ * <ul>
+ * <li>Implement a functional Java interface</li>
+ * <li>Must be the top-level lambda (i.e. not wrapped or a functional composition)</li>
+ * <li>Implement Serializable (either through the actual interface or through inference)</li>
+ * <li>Declare a single method to be implemented</li>
+ * <li>Accept a single method argument and return a value</li>
+ * </ul>
+ * Ideally, the interface has a similar format to {@link Function}, for example:
+ *
+ * <pre class="code">
+ * interface XtoYFunction<X, Y> (optional: extends Serializable) {
+ *   Y &lt;method-name&gt;(X someArgument);
+ * }
+ * </pre>
+ *
+ * This parser extracts the owning type and the member that is being accessed from it.
+ * <p>
+ * Supported ways to implement such an object are:
+ * <ul>
+ * <li>Method references, e.g. {@code SomeType::getSomeProperty}</li>
+ * <li>Lambda expressions that access a property (no-arg method calls), e.g.
+ * {@code someType -> someType.getSomeProperty()}</li>
+ * <li>Lambda expressions that access a field, e.g. {@code someType -> someType.someField}</li>
+ * </ul>
+ * Unsupported:
+ * <ul>
+ * <li>Constructor references, e.g. {@code SomeType::new}</li>
+ * <li>Method calls to methods accepting one or more arguments</li>
+ * <li>Lambda expressions that do more than property access, e.g. {@code someType -> {
+ * someType.setSomeProperty("value"); return someType.getSomeProperty(); }}</li>
+ * <li>Arithmetic operations, arbitrary calls</li>
+ * <li>Objects created through functional composition (i.e. {@code Function.andThen(…)} or wrappers around the
+ * object</li>
+ * </ul>
  *
  * @author Mark Paluch
+ * @since 4.1
  */
 class SamParser {
 
@@ -88,6 +130,17 @@ private static boolean isEnabled(String property, boolean defaultValue) {
 		this.entryPoints = Arrays.asList(entryPoints);
 	}
 
+	/**
+	 * Parse the given lambda object and extract a reference to a {@link Member} such as a field or method.
+	 * <p>
+	 * Ideally used with an interface resembling {@link java.util.function.Function}
+	 *
+	 * @param classLoader class loader providing access to types used within the lambda.
+	 * @param lambdaObject the actual lambda object, must be {@link java.io.Serializable}.
+	 * @return the member reference.
+	 * @throws InvalidDataAccessApiUsageException if the lambda object doesn't represent a valid property reference or
+	 *           hits any of the mentioned limitations.
+	 */
 	public MemberReference parse(ClassLoader classLoader, Object lambdaObject) {
 
 		try {

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

@@ -59,6 +59,7 @@
  * @param <T> the owning type of the property path segment, but typically the root type for composed property paths.
  * @param <P> the property value type at this path segment.
  * @author Mark Paluch
+ * @since 4.1
  * @see PropertyPath
  * @see #of(TypedPropertyPath)
  * @see #then(TypedPropertyPath)
@@ -69,15 +70,15 @@ public interface TypedPropertyPath<T, P> extends PropertyPath, Serializable {
 	/**
 	 * Syntax sugar to create a {@link TypedPropertyPath} from a method reference or lambda.
 	 * <p>
-	 * This method returns a resolved {@link TypedPropertyPath} by introspecting the given lambda.
+	 * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method reference or lambda.
 	 *
-	 * @param lambda the method reference or lambda.
+	 * @param propertyPath the method reference or lambda.
 	 * @param <T> owning type.
 	 * @param <P> property type.
 	 * @return the typed property path.
 	 */
-	static <T, P> TypedPropertyPath<T, P> of(TypedPropertyPath<T, P> lambda) {
-		return TypedPropertyPaths.of(lambda);
+	static <T, P> TypedPropertyPath<T, P> of(TypedPropertyPath<T, P> propertyPath) {
+		return TypedPropertyPaths.of(propertyPath);
 	}
 
 	/**
@@ -121,13 +122,15 @@ default Iterator<PropertyPath> iterator() {
 	}
 
 	/**
-	 * Extend the property path by appending the {@code next} path segment and returning a new property path instance..
+	 * Extend the property path by appending the {@code next} path segment and returning a new property path instance.
 	 *
-	 * @param next the next property path segment accepting a property path owned by the {@code P} type.
+	 * @param next the next property path segment as method reference or lambda accepting the owner object {@code P} type
+	 *          and returning {@code N} as result of accessing a property.
 	 * @param <N> the new property value type.
 	 * @return a new composed {@code TypedPropertyPath}.
 	 */
 	default <N> TypedPropertyPath<T, N> then(TypedPropertyPath<P, N> next) {
 		return TypedPropertyPaths.compose(this, of(next));
 	}
+
 }

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

@@ -31,6 +31,9 @@
 
 /**
  * Utility class to parse and resolve {@link TypedPropertyPath} instances.
+ *
+ * @author Mark Paluch
+ * @since 4.1
  */
 class TypedPropertyPaths {
 
@@ -46,12 +49,13 @@ class TypedPropertyPaths {
 	public static PropertyPathInformation getPropertyPathInformation(TypedPropertyPath<?, ?> lambda) {
 
 		Map<Object, PropertyPathInformation> cache;
+		ClassLoader cl = lambda.getClass().getClassLoader();
 		synchronized (lambdas) {
-			cache = lambdas.computeIfAbsent(lambda.getClass().getClassLoader(), k -> new ConcurrentReferenceHashMap<>());
+			cache = lambdas.computeIfAbsent(cl, k -> new ConcurrentReferenceHashMap<>());
 		}
 		Map<Object, PropertyPathInformation> lambdaMap = cache;
 
-		return lambdaMap.computeIfAbsent(lambda, o -> extractPath(lambda.getClass().getClassLoader(), lambda));
+		return lambdaMap.computeIfAbsent(lambda, o -> extractPath(cl, lambda));
 	}
 
 	private static PropertyPathInformation extractPath(ClassLoader classLoader, TypedPropertyPath<?, ?> lambda) {
@@ -106,38 +110,41 @@ public static PropertyPathInformation ofMethod(SamParser.MethodInformation metho
 			String methodName = method.getMember().getName();
 
 			if (descriptor == null) {
-				String propertyName;
-
-				if (methodName.startsWith("is")) {
-					propertyName = Introspector.decapitalize(methodName.substring(2));
-				} else if (methodName.startsWith("get")) {
-					propertyName = Introspector.decapitalize(methodName.substring(3));
-				} else {
-					propertyName = methodName;
-				}
 
+				String propertyName = getPropertyName(methodName);
 				TypeInformation<?> owner = TypeInformation.of(method.owner());
 				TypeInformation<?> fallback = owner.getProperty(propertyName);
+
 				if (fallback != null) {
 					return new PropertyPathInformation(owner, fallback,
 								propertyName);
 				}
 
 				throw new IllegalArgumentException(
-						"Cannot find PropertyDescriptor from method %s.%s".formatted(method.owner().getName(), methodName));
+						"Cannot find PropertyDescriptor from method '%s.%s()'".formatted(method.owner().getName(), methodName));
 			}
 
 			return new PropertyPathInformation(TypeInformation.of(method.getOwner()), TypeInformation.of(method.getType()),
 					descriptor.getName());
 		}
 
+		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 static PropertyPathInformation ofField(SamParser.FieldInformation field) {
 			return new PropertyPathInformation(TypeInformation.of(field.owner()), TypeInformation.of(field.getType()),
 					field.getMember().getName());
 		}
 	}
 
-
 	static class ResolvedTypedPropertyPath<T, P> implements TypedPropertyPath<T, P> {
 
 		private final TypedPropertyPath<T, P> function;
@@ -191,7 +198,7 @@ public boolean equals(Object obj) {
 				return true;
 			if (obj == null || obj.getClass() != this.getClass())
 				return false;
-			var that = (ResolvedTypedPropertyPath) obj;
+			var that = (ResolvedTypedPropertyPath<?, ?>) obj;
 			return Objects.equals(this.function, that.function) && Objects.equals(this.information, that.information);
 		}
 
@@ -206,8 +213,6 @@ public String toString() {
 		}
 	}
 
-
-
 	record ComposedPropertyPath<T, M, R>(TypedPropertyPath<T, M> first, TypedPropertyPath<M, R> second,
 			String dotPath) implements TypedPropertyPath<T, R> {
 
@@ -270,5 +275,7 @@ public Iterator<PropertyPath> iterator() {
 		public String toString() {
 			return getOwningType().getType().getSimpleName() + "." + toDotPath();
 		}
+
 	}
+
 }