Documentation, polishing.

Author: mp911de

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

@@ -131,6 +131,14 @@ 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);
 ----

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

@@ -45,38 +45,39 @@
  * @author Johannes Englmeier
  * @see PropertyReference
  * @see TypedPropertyPath
+ * @see java.beans.PropertyDescriptor
  */
 public interface PropertyPath extends Streamable<PropertyPath> {
 
 	/**
-	 * Syntax sugar to create a {@link TypedPropertyPath} from a method reference or lambda.
+	 * Syntax sugar to create a {@link TypedPropertyPath} from a method reference to a Java beans property.
 	 * <p>
-	 * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method reference or lambda.
+	 * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method reference.
 	 *
-	 * @param propertyPath the method reference or lambda.
+	 * @param property the method reference referring to a Java beans property.
 	 * @param <T> owning type.
 	 * @param <P> property type.
 	 * @return the typed property path.
 	 * @since 4.1
 	 */
-	static <T, P> TypedPropertyPath<T, P> of(PropertyReference<T, P> propertyPath) {
-		return TypedPropertyPaths.of(propertyPath);
+	static <T, P> TypedPropertyPath<T, P> of(PropertyReference<T, P> property) {
+		return TypedPropertyPaths.of(property);
 	}
 
 	/**
-	 * Syntax sugar to create a {@link TypedPropertyPath} from a method reference or lambda for a collection property.
+	 * Syntax sugar to create a {@link TypedPropertyPath} from a method reference to a Java beans collection property.
 	 * <p>
-	 * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method reference or lambda.
+	 * This method returns a resolved {@link TypedPropertyPath} by introspecting the given method reference.
 	 *
-	 * @param propertyPath the method reference or lambda.
+	 * @param property the method reference referring to a property.
 	 * @param <T> owning type.
 	 * @param <P> property type.
 	 * @return the typed property path.
 	 * @since 4.1
 	 */
 	@SuppressWarnings({ "unchecked", "rawtypes" })
-	static <T, P> TypedPropertyPath<T, P> ofMany(PropertyReference<T, ? extends Iterable<P>> propertyPath) {
-		return (TypedPropertyPath) TypedPropertyPaths.of(propertyPath);
+	static <T, P> TypedPropertyPath<T, P> ofMany(PropertyReference<T, ? extends Iterable<P>> property) {
+		return (TypedPropertyPath) TypedPropertyPaths.of(property);
 	}
 
 	/**

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

@@ -30,7 +30,7 @@
  * reference, for example:
  *
  * <pre class="code">
- * PropertyReference&lt;Person, String&gt; name = PropertyReference.of(Person::getName);
+ * PropertyReference.property(Person::getName);
  * </pre>
  *
  * The resulting object can be used to obtain the {@link #getName() property name} and to interact with the target
@@ -56,18 +56,23 @@
  * @param <P> 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<T, P extends @Nullable Object> extends Serializable {
 
 	/**
-	 * Syntax sugar to create a {@link PropertyReference} from a method reference. Suitable for static imports.
+	 * Syntax sugar to create a {@link PropertyReference} from a method reference to a Java beans property. Suitable for
+	 * static imports.
 	 * <p>
 	 * This method returns a resolved {@link PropertyReference} by introspecting the given method reference.
 	 *
-	 * @param property the method reference.
+	 * @param property the method reference to a Java beans property.
 	 * @param <T> owning type.
 	 * @param <P> property type.
 	 * @return the typed property reference.
@@ -77,11 +82,11 @@ public interface PropertyReference<T, P extends @Nullable Object> extends Serial
 	}
 
 	/**
-	 * Syntax sugar to create a {@link PropertyReference} from a method reference.
+	 * Syntax sugar to create a {@link PropertyReference} from a method reference to a Java beans property.
 	 * <p>
 	 * This method returns a resolved {@link PropertyReference} by introspecting the given method reference.
 	 *
-	 * @param property the method reference.
+	 * @param property the method reference to a Java beans property.
 	 * @param <T> owning type.
 	 * @param <P> property type.
 	 * @return the typed property reference.
@@ -91,13 +96,13 @@ public interface PropertyReference<T, P extends @Nullable Object> extends Serial
 	}
 
 	/**
-	 * Syntax sugar to create a {@link PropertyReference} from a method reference or lambda for a collection property.
+	 * Syntax sugar to create a {@link PropertyReference} from a method reference to a Java beans property.
 	 * <p>
 	 * This method returns a resolved {@link PropertyReference} by introspecting the given method reference. Note that
 	 * {@link #get(Object)} becomes unusable for collection properties as the property type adapted from
 	 * {@code Iterable &lt;P&gt;} and a single {@code P} cannot represent a collection of items.
 	 *
-	 * @param property the method reference.
+	 * @param property the method reference to a Java beans property.
 	 * @param <T> owning type.
 	 * @param <P> property type.
 	 * @return the typed property reference.
@@ -170,8 +175,8 @@ default boolean isCollection() {
 	 * 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 or lambda accepting the owner object {@code P} type
-	 *          and returning {@code N} as result of accessing a property.
+	 * @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 <N> the new property value type.
 	 * @return a new composed {@code TypedPropertyPath}.
 	 */
@@ -186,8 +191,8 @@ default boolean isCollection() {
 	 * Note that {@link #get(Object)} becomes unusable for collection properties as the property type adapted from
 	 * {@code Iterable &lt;P&gt;} and a single {@code P} cannot represent a collection of items.
 	 *
-	 * @param 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 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 <N> the new property value type.
 	 * @return a new composed {@code TypedPropertyPath}.
 	 */

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

@@ -252,12 +252,12 @@ public TypeInformation<P> getTypeInformation() {
 
 		@Override
 		public boolean equals(@Nullable Object obj) {
-			return PropertyUtil.equals(this, obj);
+			return PropertyPathUtil.equals(this, obj);
 		}
 
 		@Override
 		public int hashCode() {
-			return PropertyUtil.hashCode(this);
+			return PropertyPathUtil.hashCode(this);
 		}
 
 		@Override

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

@@ -141,17 +141,7 @@ public MemberDescriptor read(Object lambdaObject) {
 		SerializedLambda lambda = serialize(lambdaObject);
 
 		if (isKotlinPropertyReference(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);
-			}
+			return KotlinDelegate.read(lambda);
 		}
 
 		assertNotConstructor(lambda);
@@ -178,11 +168,6 @@ public MemberDescriptor read(Object lambdaObject) {
 				+ ". The given value is not a lambda or method reference.");
 	}
 
-	public static boolean isKotlinPropertyReference(SerializedLambda lambda) {
-		return KotlinDetector.isKotlinReflectPresent() && lambda.getCapturedArgCount() == 1
-				&& lambda.getCapturedArg(0) != null && KotlinDetector.isKotlinType(lambda.getCapturedArg(0).getClass());
-	}
-
 	private void assertNotConstructor(SerializedLambda lambda) {
 
 		if (lambda.getImplMethodKind() == MethodHandleInfo.REF_newInvokeSpecial
@@ -219,7 +204,7 @@ private MemberDescriptor getMemberDescriptor(Object lambdaObject, SerializedLamb
 		}
 	}
 
-	static SerializedLambda serialize(Object lambda) {
+	private static SerializedLambda serialize(Object lambda) {
 
 		try {
 			Method method = lambda.getClass().getDeclaredMethod("writeReplace");
@@ -231,6 +216,40 @@ static SerializedLambda serialize(Object lambda) {
 		}
 	}
 
+	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.
+	 * <p>
+	 * 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;
@@ -306,14 +325,14 @@ public void visitInsn(int opcode) {
 		@Override
 		public void visitLdcInsn(Object value) {
 			errors.add(new ReadingError(line,
-					"Lambda expressions may only contain method calls to getters, record components, or field access", null));
+					"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, "Setting a field not allowed", null));
+				errors.add(new ReadingError(line, String.format("Code attempts to set field '%s'", name), null));
 				return;
 			}
 
@@ -334,7 +353,7 @@ public void visitFieldInsn(int opcode, String owner, String name, String descrip
 		public void visitMethodInsn(int opcode, String owner, String name, String descriptor, boolean isInterface) {
 
 			if (opcode == Opcodes.INVOKESPECIAL && name.equals("<init>")) {
-				errors.add(new ReadingError(line, "Lambda must not invoke constructors", null));
+				errors.add(new ReadingError(line, "Constructor calls not supported.", null));
 				return;
 			}
 
@@ -356,8 +375,8 @@ public void visitMethodInsn(int opcode, String owner, String name, String descri
 				Type[] argumentTypes = Type.getArgumentTypes(descriptor);
 				String signature = Arrays.stream(argumentTypes).map(Type::getClassName).collect(Collectors.joining(", "));
 				errors.add(new ReadingError(line,
-						"Cannot derive a method reference from method invocation '%s(%s)' on a different type than the owning one.%nExpected owning type: '%s', but was: '%s'"
-								.formatted(name, signature, this.owningType.getClassName(), ownerType.getClassName())));
+						"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;
 			}
 

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

@@ -177,12 +177,12 @@ public boolean hasNext() {
 
 	@Override
 	public boolean equals(@Nullable Object o) {
-		return PropertyUtil.equals(this, o);
+		return PropertyPathUtil.equals(this, o);
 	}
 
 	@Override
 	public int hashCode() {
-		return PropertyUtil.hashCode(this);
+		return PropertyPathUtil.hashCode(this);
 	}
 
 	/**