Fix property path composition, introduce TCK for PropertyPath, simplify equality and hashing checks.

Author: mp911de

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

@@ -59,6 +59,7 @@ static <T, P> TypedPropertyPath<T, P> of(TypedPropertyPath<T, P> propertyPath) {
 	 * @return the typed property path.
 	 * @since 4.1
 	 */
+	@SuppressWarnings({ "unchecked", "rawtypes" })
 	static <T, P> TypedPropertyPath<T, P> ofMany(TypedPropertyPath<T, ? extends Iterable<P>> propertyPath) {
 		return (TypedPropertyPath) TypedPropertyPaths.of(propertyPath);
 	}
@@ -71,22 +72,25 @@ static <T, P> TypedPropertyPath<T, P> ofMany(TypedPropertyPath<T, ? extends Iter
 	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()}).
+	 * <p>
+	 * For example:
 	 *
 	 * <pre class="code">
 	 * PropertyPath.from("a.b.c", Some.class).getSegment();
 	 * </pre>
 	 *
 	 * results in {@code a}.
 	 *
-	 * @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() {
 
@@ -103,57 +107,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.
 	 *
 	 * <pre class="code">
 	 * PropertyPath.from("a.b.c", Some.class).next().toDotPath();
 	 * </pre>
 	 *
 	 * results in the output: {@code b.c}
 	 *
-	 * @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() {
 
@@ -162,16 +181,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}.
@@ -186,8 +196,7 @@ 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:
 	 *
 	 * <pre class="code">
 	 * PropertyPath propertyPath = PropertyPath.from("a.b.c", Some.class);
@@ -197,9 +206,9 @@ default PropertyPath nested(String path) {
 	 * results in the dot paths:
 	 *
 	 * <pre class="code">
-	 * a.b.c
-	 * b.c
-	 * c
+	 * a.b.c             (this object)
+	 * b.c               (next() object)
+	 * c                 (next().next() object)
 	 * </pre>
 	 */
 	@Override

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

@@ -0,0 +1,62 @@
+/*
+ * 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.util.Objects;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Utility class for {@link PropertyPath} implementations.
+ *
+ * @author Mark Paluch
+ * @since 4.1
+ */
+class PropertyPathUtil {
+
+	/**
+	 * 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();
+	}
+
+	/**
+	 * 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.
+	 */
+	public 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());
+	}
+
+}

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

@@ -177,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);
 	}
 
 	/**

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

@@ -35,7 +35,7 @@
  * <pre class="code">
  * TypedPropertyPath&lt;Person, String&gt; name = TypedPropertyPath.of(Person::getName);
  * </pre>
- * 
+ *
  * The resulting object can be used to obtain the {@link #toDotPath() dot-path} and to interact with the targetting
  * property. Typed paths allow for composition to navigate nested object structures using
  * {@link #then(TypedPropertyPath)}: