Clarify behaviour of PropertyPath, both in tests and documentation.

Author: schauder

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

@@ -41,6 +41,7 @@
  * @author Christoph Strobl
  * @author Mark Paluch
  * @author Mariusz Mączkowski
+ * @author Jens Schauder
  */
 public class PropertyPath implements Streamable<PropertyPath> {
 
@@ -108,12 +109,53 @@ public TypeInformation<?> getOwningType() {
 	}
 
 	/**
-	 * Returns the name of the {@link PropertyPath}.
+	 * Extracts the {@link PropertyPath} chain from the given source {@link String} and {@link TypeInformation}. <br />
+	 * Uses {@link #SPLITTER} by default and {@link #SPLITTER_FOR_QUOTED} for {@link Pattern#quote(String) quoted}
+	 * literals. Separate parts of the path may be separated by {@code "."} or by {@code "_"} or by camel case. When the
+	 * match to properties is ambiguous longer property names are preferred. So for "userAddressCity" the interpretation
+	 * "userAddress.city" is preferred over "user.address.city".
 	 *
-	 * @return the name will never be {@literal null}.
+	 * @param source must not be {@literal null}.
+	 * @param type
+	 * @return
 	 */
-	public String getSegment() {
-		return name;
+	public static PropertyPath from(String source, TypeInformation<?> type) {
+
+		Assert.hasText(source, "Source must not be null or empty!");
+		Assert.notNull(type, "TypeInformation must not be null or empty!");
+
+		return cache.computeIfAbsent(Key.of(type, source), it -> {
+
+			List<String> iteratorSource = new ArrayList<>();
+
+			Matcher matcher = isQuoted(it.path) ? SPLITTER_FOR_QUOTED.matcher(it.path.replace("\\Q", "").replace("\\E", ""))
+					: SPLITTER.matcher("_" + it.path);
+
+			while (matcher.find()) {
+				iteratorSource.add(matcher.group(1));
+			}
+
+			Iterator<String> parts = iteratorSource.iterator();
+
+			PropertyPath result = null;
+			Stack<PropertyPath> current = new Stack<>();
+
+			while (parts.hasNext()) {
+				if (result == null) {
+					result = create(parts.next(), it.type, current);
+					current.push(result);
+				} else {
+					current.push(create(parts.next(), current));
+				}
+			}
+
+			if (result == null) {
+				throw new IllegalStateException(
+						String.format("Expected parsing to yield a PropertyPath from %s but got null!", source));
+			}
+
+			return result;
+		});
 	}
 
 	/**
@@ -156,14 +198,20 @@ public TypeInformation<?> getTypeInformation() {
 	}
 
 	/**
-	 * Returns the next nested {@link PropertyPath}.
+	 * Returns the first part of the {@link PropertyPath}.
 	 *
-	 * @return the next nested {@link PropertyPath} or {@literal null} if no nested {@link PropertyPath} available.
-	 * @see #hasNext()
+	 * <pre>
+	 * {@code
+	 * PropertyPath.from("a.b.c", Some.class).getSegment();
+	 * }
+	 * </pre>
+	 *
+	 * will result in {@code "a"}
+	 *
+	 * @return the name will never be {@literal null}.
 	 */
-	@Nullable
-	public PropertyPath next() {
-		return next;
+	public String getSegment() {
+		return name;
 	}
 
 	/**
@@ -214,37 +262,23 @@ public PropertyPath nested(String path) {
 		return PropertyPath.from(lookup, owningType);
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see java.lang.Iterable#iterator()
+	/**
+	 * Returns the {@link PropertyPath} path that results from removing the first element of the current one.
+	 *
+	 * <pre>
+	 * {@code
+	 * System.out.println(PropertyPath.from("a.b.c", Some.class).next().toDotPath());
+	 * }
+	 * </pre>
+	 *
+	 * Will result in the output: {@code b.c}
+	 *
+	 * @return the next nested {@link PropertyPath} or {@literal null} if no nested {@link PropertyPath} available.
+	 * @see #hasNext()
 	 */
-	public Iterator<PropertyPath> iterator() {
-
-		return new Iterator<PropertyPath>() {
-
-			private @Nullable PropertyPath current = PropertyPath.this;
-
-			public boolean hasNext() {
-				return current != null;
-			}
-
-			@Nullable
-			public PropertyPath next() {
-
-				PropertyPath result = current;
-
-				if (result == null) {
-					return null;
-				}
-
-				this.current = result.next();
-				return result;
-			}
-
-			public void remove() {
-				throw new UnsupportedOperationException();
-			}
-		};
+	@Nullable
+	public PropertyPath next() {
+		return next;
 	}
 
 	/*
@@ -332,51 +366,55 @@ public static PropertyPath from(String source, Class<?> type) {
 	}
 
 	/**
-	 * Extracts the {@link PropertyPath} chain from the given source {@link String} and {@link TypeInformation}. <br />
-	 * Uses {@link #SPLITTER} by default and {@link #SPLITTER_FOR_QUOTED} for {@link Pattern#quote(String) quoted}
-	 * literals.
+	 * Returns an {@link Iterator<PropertyPath>} that iterates over all the partial property paths with the same leaf type
+	 * but decreasing length.
 	 *
-	 * @param source must not be {@literal null}.
-	 * @param type
-	 * @return
+	 * <pre>
+	 * {@code
+	 * PropertyPath propertyPath = PropertyPath.from("a.b.c", Some.class);
+	 * for (p : propertyPath.iterator()) {
+	 *     System.out.println(p.toDotPath());
+	 * };
+	 * }
+	 * </pre>
+	 *
+	 * Results in the output:
+	 * 
+	 * <pre>
+	 * {@code
+	 * a.b.c
+	 * b.c
+	 * c
+	 * }
+	 * </pre>
 	 */
-	public static PropertyPath from(String source, TypeInformation<?> type) {
-
-		Assert.hasText(source, "Source must not be null or empty!");
-		Assert.notNull(type, "TypeInformation must not be null or empty!");
-
-		return cache.computeIfAbsent(Key.of(type, source), it -> {
+	public Iterator<PropertyPath> iterator() {
 
-			List<String> iteratorSource = new ArrayList<>();
+		return new Iterator<PropertyPath>() {
 
-			Matcher matcher = isQuoted(it.path) ? SPLITTER_FOR_QUOTED.matcher(it.path.replace("\\Q", "").replace("\\E", ""))
-					: SPLITTER.matcher("_" + it.path);
+			private @Nullable PropertyPath current = PropertyPath.this;
 
-			while (matcher.find()) {
-				iteratorSource.add(matcher.group(1));
+			public boolean hasNext() {
+				return current != null;
 			}
 
-			Iterator<String> parts = iteratorSource.iterator();
+			@Nullable
+			public PropertyPath next() {
 
-			PropertyPath result = null;
-			Stack<PropertyPath> current = new Stack<>();
+				PropertyPath result = current;
 
-			while (parts.hasNext()) {
 				if (result == null) {
-					result = create(parts.next(), it.type, current);
-					current.push(result);
-				} else {
-					current.push(create(parts.next(), current));
+					return null;
 				}
-			}
 
-			if (result == null) {
-				throw new IllegalStateException(
-						String.format("Expected parsing to yield a PropertyPath from %s but got null!", source));
+				this.current = result.next();
+				return result;
 			}
 
-			return result;
-		});
+			public void remove() {
+				throw new UnsupportedOperationException();
+			}
+		};
 	}
 
 	private static boolean isQuoted(String source) {

src/test/java/org/springframework/data/mapping/PropertyPathUnitTests.java

@@ -24,7 +24,6 @@
 import java.util.regex.Pattern;
 
 import org.junit.jupiter.api.Test;
-
 import org.springframework.data.util.ClassTypeInformation;
 import org.springframework.data.util.TypeInformation;
 
@@ -34,6 +33,7 @@
  * @author Oliver Gierke
  * @author Christoph Strobl
  * @author Mark Paluch
+ * @author Jens Schauder
  */
 @SuppressWarnings("unused")
 public class PropertyPathUnitTests {
@@ -188,6 +188,16 @@ public void returnsCorrectIteratorForMultipleElement() {
 		assertThat(iterator.hasNext()).isFalse();
 	}
 
+	@Test
+	public void nextReturnsPathWithoutFirstElement() {
+
+		PropertyPath propertyPath = PropertyPath.from("bar.user.name", Sample.class);
+
+		final PropertyPath next = propertyPath.next();
+		assertThat(next).isNotNull();
+		assertThat(next.toDotPath()).isEqualTo("user.name");
+	}
+
 	@Test // DATACMNS-139
 	public void rejectsInvalidPropertyWithLeadingUnderscore() {