HHH-18990 introduce Path, allowing Restrictions on compound paths

Author: gavinking

documentation/src/main/asciidoc/introduction/Interacting.adoc

@@ -1085,6 +1085,18 @@ Unfortunately, `Restriction` and `Order` can't be used with JPA's `TypedQuery` i
 
 Alternatively, `Restriction` and `Order` can be used with <<paging-and-ordering,generated query or finder methods>>, and even with link:{doc-data-repositories-url}[Jakarta Data repositories].
 
+The interface link:{doc-javadoc-url}org/hibernate/query/Path.html[`Path`] may be used to express restrictions on fields of an embedded or associated entity class.
+
+[source,java]
+----
+List<Book> booksForPublisher =
+        session.createSelectionQuery("from Book", Book.class)
+                .addRestriction(Path.root(Book_.publisher)
+                                .get(Publisher_.name)
+                                .equalTo(publisherName))
+                .getResultList();
+----
+
 Programmatic restrictions, and especially programmatic ordering, are often used together with pagination.
 
 [[pagination]]

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

@@ -15,6 +15,8 @@
  *
  * @param <X> The entity type
  * @param <U> The attribute type
+ *
+ * @author Gavin King
  */
 record AttributeRange<X, U>(SingularAttribute<X, U> attribute, Range<U> range) implements Restriction<X> {
 	@Override

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

@@ -13,6 +13,8 @@
  *
  * @param restrictions The restrictions to be AND-ed
  * @param <X> The entity type
+ *
+ * @author Gavin King
  */
 record Conjunction<X>(java.util.List<? extends Restriction<? super X>> restrictions)
 		implements Restriction<X> {

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

@@ -13,6 +13,8 @@
  *
  * @param restrictions The restrictions to be OR-ed
  * @param <X> The entity type
+ *
+ * @author Gavin King
  */
 record Disjunction<X>(java.util.List<? extends Restriction<? super X>> restrictions)
 		implements Restriction<X> {

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

@@ -17,6 +17,8 @@
  *
  * @param <X> The entity type
  * @param <U> The attribute type
+ *
+ * @author Gavin King
  */
 record NamedAttributeRange<X, U>(Class<X> entity, String attributeName, Range<U> range) implements Restriction<X> {
 	@Override

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

@@ -13,6 +13,8 @@
  *
  * @param restriction The restriction to be negated
  * @param <X> The entity type
+ *
+ * @author Gavin King
  */
 record Negation<X>(Restriction<X> restriction) implements Restriction<X> {
 	@Override

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

@@ -0,0 +1,69 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.query;
+
+import jakarta.persistence.criteria.Root;
+import jakarta.persistence.metamodel.SingularAttribute;
+import org.hibernate.Incubating;
+import org.hibernate.query.range.Range;
+
+import java.util.List;
+
+/**
+ * Allows construction of a {@link Restriction} on a compound path.
+ * <p>
+ * A compound path is a sequence of attribute references rooted at
+ * the root entity type of the query.
+ * <pre>
+ * session.createSelectionQuery("from Book", Book.class)
+ *         .addRestriction(root(publisher).get(name).equalTo("Manning"))
+ *         .getResultList()
+ * </pre>
+ * A compound path-based restriction has the same semantics as the
+ * equivalent implicit join in HQL.
+ *
+ * @param <X> The root entity type
+ * @param <U> The leaf attribute type
+ *
+ * @see Restriction
+ *
+ * @author Gavin King
+ *
+ * @since 7.0
+ */
+@Incubating
+public interface Path<X,U> {
+	jakarta.persistence.criteria.Path<U> path(Root<? extends X> root);
+
+	default <V> Path<X, V> get(SingularAttribute<? super U, V> attribute) {
+		return new PathElement<>( this, attribute );
+	}
+
+	static <X, U> Path<X, U> root(SingularAttribute<? super X, U> attribute) {
+		return new PathRoot<X>().get( attribute );
+	}
+
+	default Restriction<X> restrict(Range<U> range) {
+		return new PathRange<>( this, range );
+	}
+
+	default Restriction<X> equalTo(U value) {
+		return restrict( Range.singleValue( value ) );
+	}
+
+	default Restriction<X> notEqualTo(U value) {
+		return equalTo( value ).negated();
+	}
+
+	default Restriction<X> in(List<U> values) {
+		return restrict( Range.valueList( values ) );
+	}
+
+	default Restriction<X> notIn(List<U> values) {
+		return in( values ).negated();
+	}
+
+	//TODO: between, lessThan, greaterThan?
+}

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

@@ -0,0 +1,20 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.query;
+
+import jakarta.persistence.criteria.Root;
+import jakarta.persistence.metamodel.SingularAttribute;
+
+/**
+ * A non-root element of a {@link Path}.
+ *
+ * @author Gavin King
+ */
+record PathElement<X, U, V>(Path<? super X, U> parent, SingularAttribute<? super U, V> attribute) implements Path<X, V> {
+	@Override
+	public jakarta.persistence.criteria.Path<V> path(Root<? extends X> root) {
+		return parent.path( root ).get( attribute );
+	}
+}

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

@@ -0,0 +1,30 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.query;
+
+import jakarta.persistence.criteria.CriteriaBuilder;
+import jakarta.persistence.criteria.Predicate;
+import jakarta.persistence.criteria.Root;
+import org.hibernate.query.range.Range;
+
+/**
+ * Restricts a path from an entity to a given {@link Range}.
+ *
+ * @param <X> The entity type
+ * @param <U> The attribute type
+ *
+ * @author Gavin King
+ */
+record PathRange<X, U>(Path<X, U> path, Range<U> range) implements Restriction<X> {
+	@Override
+	public Restriction<X> negated() {
+		return new Negation<>( this );
+	}
+
+	@Override
+	public Predicate toPredicate(Root<? extends X> root, CriteriaBuilder builder) {
+		return range.toPredicate( path.path( root ), builder );
+	}
+}

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

@@ -0,0 +1,21 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.query;
+
+import jakarta.persistence.criteria.Root;
+
+/**
+ * A root element of a {@link Path}.
+ *
+ * @author Gavin King
+ */
+record PathRoot<X>() implements Path<X, X> {
+	@Override
+	@SuppressWarnings("unchecked")
+	public jakarta.persistence.criteria.Path<X> path(Root<? extends X> root) {
+		// unchecked cast only to get rid of the upper bound
+		return (jakarta.persistence.criteria.Path<X>) root;
+	}
+}