Polishing.

Refine temporal literal handling. Update documentation.

See #3172
Original pull request: #3187

Author: mp911de

spring-data-jpa/src/main/java/org/springframework/data/jpa/domain/JpaSort.java

@@ -18,19 +18,22 @@
 import jakarta.persistence.metamodel.Attribute;
 import jakarta.persistence.metamodel.PluralAttribute;
 
-import org.springframework.data.domain.Sort;
-import org.springframework.lang.Nullable;
-import org.springframework.util.Assert;
-
 import java.io.Serial;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.List;
 
+import org.springframework.data.domain.Sort;
+import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
+
 /**
- * Sort option for queries that wraps JPA meta-model {@link Attribute}s for sorting.
+ * Sort option for queries that wraps JPA metamodel {@link Attribute}s for sorting.
+ * <p>
+ * {@link JpaSort#unsafe} accepts unsafe sort expressions, i. e. the String provided is not necessarily a property but
+ * can be an arbitrary expression piped into the query execution.
  *
  * @author Thomas Darimont
  * @author Oliver Gierke
@@ -44,7 +47,7 @@ public class JpaSort extends Sort {
 	@Serial private static final long serialVersionUID = 1L;
 
 	private JpaSort(Direction direction, List<Path<?, ?>> paths) {
-		this(Collections.<Order>emptyList(), direction, paths);
+		this(Collections.<Order> emptyList(), direction, paths);
 	}
 
 	private JpaSort(List<Order> orders, @Nullable Direction direction, List<Path<?, ?>> paths) {
@@ -76,7 +79,7 @@ public static JpaSort of(JpaSort.Path<?, ?>... paths) {
 	/**
 	 * Creates a new {@link JpaSort} for the given direction and attributes.
 	 *
-	 * @param direction  the sorting direction.
+	 * @param direction the sorting direction.
 	 * @param attributes must not be {@literal null} or empty.
 	 */
 	public static JpaSort of(Direction direction, Attribute<?, ?>... attributes) {
@@ -87,7 +90,7 @@ public static JpaSort of(Direction direction, Attribute<?, ?>... attributes) {
 	 * Creates a new {@link JpaSort} for the given direction and {@link Path}s.
 	 *
 	 * @param direction the sorting direction.
-	 * @param paths     must not be {@literal null} or empty.
+	 * @param paths must not be {@literal null} or empty.
 	 */
 	public static JpaSort of(Direction direction, Path<?, ?>... paths) {
 		return new JpaSort(direction, Arrays.asList(paths));
@@ -96,7 +99,7 @@ public static JpaSort of(Direction direction, Path<?, ?>... paths) {
 	/**
 	 * Returns a new {@link JpaSort} with the given sorting criteria added to the current one.
 	 *
-	 * @param direction  can be {@literal null}.
+	 * @param direction can be {@literal null}.
 	 * @param attributes must not be {@literal null}.
 	 * @return
 	 */
@@ -111,7 +114,7 @@ public JpaSort and(@Nullable Direction direction, Attribute<?, ?>... attributes)
 	 * Returns a new {@link JpaSort} with the given sorting criteria added to the current one.
 	 *
 	 * @param direction can be {@literal null}.
-	 * @param paths     must not be {@literal null}.
+	 * @param paths must not be {@literal null}.
 	 * @return
 	 */
 	public JpaSort and(@Nullable Direction direction, Path<?, ?>... paths) {
@@ -130,7 +133,7 @@ public JpaSort and(@Nullable Direction direction, Path<?, ?>... paths) {
 	/**
 	 * Returns a new {@link JpaSort} with the given sorting criteria added to the current one.
 	 *
-	 * @param direction  can be {@literal null}.
+	 * @param direction can be {@literal null}.
 	 * @param properties must not be {@literal null} or empty.
 	 * @return
 	 */
@@ -148,7 +151,7 @@ public JpaSort andUnsafe(@Nullable Direction direction, String... properties) {
 			orders.add(new JpaOrder(direction, property));
 		}
 
-		return new JpaSort(orders, direction, Collections.<Path<?, ?>>emptyList());
+		return new JpaSort(orders, direction, Collections.<Path<?, ?>> emptyList());
 	}
 
 	/**
@@ -219,7 +222,7 @@ public static JpaSort unsafe(String... properties) {
 	/**
 	 * Creates new unsafe {@link JpaSort} based on given {@link Direction} and properties.
 	 *
-	 * @param direction  must not be {@literal null}.
+	 * @param direction must not be {@literal null}.
 	 * @param properties must not be {@literal null} or empty.
 	 * @return
 	 */
@@ -235,7 +238,7 @@ public static JpaSort unsafe(Direction direction, String... properties) {
 	/**
 	 * Creates new unsafe {@link JpaSort} based on given {@link Direction} and properties.
 	 *
-	 * @param direction  must not be {@literal null}.
+	 * @param direction must not be {@literal null}.
 	 * @param properties must not be {@literal null} or empty.
 	 * @return
 	 */
@@ -327,7 +330,7 @@ public static class JpaOrder extends Order {
 		 * {@link Sort#DEFAULT_DIRECTION}
 		 *
 		 * @param direction can be {@literal null}, will default to {@link Sort#DEFAULT_DIRECTION}.
-		 * @param property  must not be {@literal null}.
+		 * @param property must not be {@literal null}.
 		 */
 		private JpaOrder(@Nullable Direction direction, String property) {
 			this(direction, property, NullHandling.NATIVE);
@@ -337,16 +340,16 @@ private JpaOrder(@Nullable Direction direction, String property) {
 		 * Creates a new {@link Order} instance. if order is {@literal null} then order defaults to
 		 * {@link Sort#DEFAULT_DIRECTION}.
 		 *
-		 * @param direction        can be {@literal null}, will default to {@link Sort#DEFAULT_DIRECTION}.
-		 * @param property         must not be {@literal null}.
+		 * @param direction can be {@literal null}, will default to {@link Sort#DEFAULT_DIRECTION}.
+		 * @param property must not be {@literal null}.
 		 * @param nullHandlingHint can be {@literal null}, will default to {@link NullHandling#NATIVE}.
 		 */
 		private JpaOrder(@Nullable Direction direction, String property, NullHandling nullHandlingHint) {
 			this(direction, property, false, nullHandlingHint, true);
 		}
 
 		private JpaOrder(@Nullable Direction direction, String property, boolean ignoreCase, NullHandling nullHandling,
-						 boolean unsafe) {
+				boolean unsafe) {
 
 			super(direction, property, ignoreCase, nullHandling);
 			this.unsafe = unsafe;