HHH-18979 add additional static factory methods for Restriction/Range

and add some javadoc

Author: gavinking

hibernate-core/src/main/java/org/hibernate/query/Restriction.java

@@ -29,6 +29,12 @@
  * <p>
  * Each restriction pairs an {@linkplain SingularAttribute attribute} of the
  * entity with a {@link Range} of allowed values for the attribute.
+ * <p>
+ * A parameter of a {@linkplain org.hibernate.annotations.processing.Find
+ * finder method} or {@linkplain org.hibernate.annotations.processing.HQL
+ * HQL query method} may be declared with type {@code Restriction<? super E>},
+ * {@code List<Restriction<? super E>>}, or {@code Restriction<? super E>...}
+ * (varargs) where {@code E} is the entity type returned by the query.
  *
  * @param <X> The entity result type of the query
  *
@@ -163,19 +169,35 @@ static <T> Restriction<T> notLike(SingularAttribute<T, String> attribute, String
 	}
 
 	static <T> Restriction<T> startsWith(SingularAttribute<T, String> attribute, String prefix) {
-		return like( attribute, escape( prefix ) + '%' );
+		return startsWith( attribute, prefix, true );
 	}
 
-	static <T> Restriction<T> endWith(SingularAttribute<T, String> attribute, String suffix) {
-		return like( attribute, '%' + escape( suffix ) );
+	static <T> Restriction<T> endsWith(SingularAttribute<T, String> attribute, String suffix) {
+		return endsWith( attribute, suffix, true );
 	}
 
 	static <T> Restriction<T> contains(SingularAttribute<T, String> attribute, String substring) {
-		return like( attribute, '%' + escape( substring ) + '%' );
+		return contains( attribute, substring, true );
 	}
 
 	static <T> Restriction<T> notContains(SingularAttribute<T, String> attribute, String substring) {
-		return contains( attribute, substring ).negated();
+		return notContains( attribute, substring, true );
+	}
+
+	static <T> Restriction<T> startsWith(SingularAttribute<T, String> attribute, String prefix, boolean caseSensitive) {
+		return restrict( attribute, Range.prefix( prefix, caseSensitive ) );
+	}
+
+	static <T> Restriction<T> endsWith(SingularAttribute<T, String> attribute, String suffix, boolean caseSensitive) {
+		return restrict( attribute, Range.suffix( suffix, caseSensitive ) );
+	}
+
+	static <T> Restriction<T> contains(SingularAttribute<T, String> attribute, String substring, boolean caseSensitive) {
+		return restrict( attribute, Range.containing( substring, caseSensitive ) );
+	}
+
+	static <T> Restriction<T> notContains(SingularAttribute<T, String> attribute, String substring, boolean caseSensitive) {
+		return contains( attribute, substring, caseSensitive ).negated();
 	}
 
 	static <T> Restriction<T> all(List<? extends Restriction<? super T>> restrictions) {
@@ -199,16 +221,4 @@ static <T> Restriction<T> any(Restriction<? super T>... restrictions) {
 	static <T> Restriction<T> unrestricted() {
 		return new Unrestricted<>();
 	}
-
-	private static String escape(String literal) {
-		final var result = new StringBuilder();
-		for ( int i = 0; i < literal.length(); i++ ) {
-			final char ch = literal.charAt( i );
-			if ( ch=='%' || ch=='_' || ch=='\\' ) {
-				result.append('\\');
-			}
-			result.append( ch );
-		}
-		return result.toString();
-	}
 }

hibernate-core/src/main/java/org/hibernate/query/range/Range.java

@@ -15,6 +15,10 @@
 
 /**
  * Specifies an allowed set of range of values for a value being restricted.
+ * <p>
+ * A parameter of a {@linkplain org.hibernate.annotations.processing.Find
+ * finder method} may be declared with type {@code Range<T>} where {@code T}
+ * is the type of the matching field of property of the entity.
  *
  * @param <U> The type of the value being restricted
  *
@@ -87,11 +91,47 @@ static Range<String> pattern(String pattern) {
 		return pattern( pattern, true );
 	}
 
+	static Range<String> prefix(String prefix, boolean caseSensitive) {
+		return pattern( escape( prefix ) + '%', caseSensitive );
+	}
+
+	static Range<String> suffix(String suffix, boolean caseSensitive) {
+		return pattern( '%' + escape( suffix ), caseSensitive );
+	}
+
+	static Range<String> containing(String substring, boolean caseSensitive) {
+		return pattern( '%' + escape( substring ) + '%', caseSensitive );
+	}
+
+	static Range<String> prefix(String prefix) {
+		return prefix( prefix, true );
+	}
+
+	static Range<String> suffix(String suffix) {
+		return pattern( suffix, true );
+	}
+
+	static Range<String> containing(String substring) {
+		return pattern( substring, true );
+	}
+
 	static <U> Range<U> empty(Class<U> type) {
 		return new EmptyRange<>( type );
 	}
 
 	static <U> Range<U> full(Class<U> type) {
 		return new FullRange<>( type );
 	}
+
+	private static String escape(String literal) {
+		final var result = new StringBuilder();
+		for ( int i = 0; i < literal.length(); i++ ) {
+			final char ch = literal.charAt( i );
+			if ( ch=='%' || ch=='_' || ch=='\\' ) {
+				result.append('\\');
+			}
+			result.append( ch );
+		}
+		return result.toString();
+	}
 }

hibernate-core/src/test/java/org/hibernate/orm/test/query/restriction/RestrictionTest.java

@@ -20,7 +20,7 @@
 import static org.hibernate.query.Restriction.any;
 import static org.hibernate.query.Restriction.between;
 import static org.hibernate.query.Restriction.contains;
-import static org.hibernate.query.Restriction.endWith;
+import static org.hibernate.query.Restriction.endsWith;
 import static org.hibernate.query.Restriction.equal;
 import static org.hibernate.query.Restriction.equalIgnoringCase;
 import static org.hibernate.query.Restriction.greaterThan;
@@ -105,7 +105,7 @@ void test(SessionFactoryScope scope) {
 		assertEquals( 0, noBooks.size() );
 		List<Book> books1 = scope.fromSession( session ->
 				session.createSelectionQuery( "from Book", Book.class)
-						.addRestriction( endWith(title, "Hibernate") )
+						.addRestriction( endsWith(title, "Hibernate") )
 						.getResultList() );
 		assertEquals( 1, books1.size() );
 		List<Book> books2 = scope.fromSession( session ->