add joins to entity types (range variables)

see #128, #466
jakartaee · Aug 25, 2023 · bf65599 · bf65599
1 parent 750fbe9
commit bf65599
Show file tree

Hide file tree

Showing 5 changed files with 230 additions and 89 deletions.
diff --git a/api/src/main/java/jakarta/persistence/criteria/From.java b/api/src/main/java/jakarta/persistence/criteria/From.java
@@ -17,6 +17,7 @@
 
 package jakarta.persistence.criteria;
 
+import jakarta.persistence.metamodel.EntityType;
 import jakarta.persistence.metamodel.SingularAttribute;
 import jakarta.persistence.metamodel.CollectionAttribute;
 import jakarta.persistence.metamodel.ListAttribute;
@@ -68,6 +69,40 @@ public interface From<Z, X> extends Path<X>, FetchParent<Z, X> {
      */
     From<Z, X> getCorrelationParent();
 
+    /**
+     * Create and add an inner join to the given entity.
+     * @param entityClass  the target entity class
+     * @return the resulting join
+     * @since 3.2
+     */
+    <Y> Join<X, Y> join(Class<Y> entityClass);
+
+    /**
+     * Create and add a join to the given entity.
+     * @param entityClass  the target entity class
+     * @param joinType  join type
+     * @return the resulting join
+     * @since 3.2
+     */
+    <Y> Join<X, Y> join(Class<Y> entityClass, JoinType joinType);
+
+    /**
+     * Create and add an inner join to the given entity.
+     * @param entity  metamodel entity representing the join target
+     * @return the resulting join
+     * @since 3.2
+     */
+    <Y> Join<X, Y> join(EntityType<Y> entity);
+
+    /**
+     * Create and add a join to the given entity.
+     * @param entity  metamodel entity representing the join target
+     * @param joinType  join type
+     * @return the resulting join
+     * @since 3.2
+     */
+    <Y> Join<X, Y> join(EntityType<Y> entity, JoinType joinType);
+
     /**
      *  Create an inner join to the specified single-valued 
      *  attribute.
@@ -150,7 +185,7 @@ public interface From<Z, X> extends Path<X>, FetchParent<Z, X> {
      */
     <K, V> MapJoin<X, K, V> join(MapAttribute<? super X, K, V> map, JoinType jt);
 
-	
+
     //String-based:
 
     /**

diff --git a/api/src/main/java/jakarta/persistence/criteria/Join.java b/api/src/main/java/jakarta/persistence/criteria/Join.java
@@ -58,8 +58,10 @@ public interface Join<Z, X> extends From<Z, X> {
     Predicate getOn();
 
     /**
-     * Return the metamodel attribute corresponding to the join.
-     * @return metamodel attribute corresponding to the join
+     * Return the metamodel attribute representing the join
+     * target, if any, or null if the target of the join is an
+     * entity type.
+     * @return metamodel attribute or null
      */
     Attribute<? super Z, ?> getAttribute();
 

diff --git a/api/src/main/java/jakarta/persistence/criteria/JoinType.java b/api/src/main/java/jakarta/persistence/criteria/JoinType.java
@@ -17,22 +17,28 @@
 package jakarta.persistence.criteria;
 
 /**
- * Defines the three types of joins.
+ * Defines the three varieties of join.
  *
- * Right outer joins and right outer fetch joins are not required
- * to be supported. Applications that use <code>RIGHT</code> join
- * types will not be portable.
+ * <p>Support for {@link #RIGHT} outer joins is not required. Applications
+ * which make use of right joins might not be portable between providers or
+ * between SQL databases.
  *
  * @since 2.0
  */
 public enum JoinType {
 
-    /** Inner join. */
+    /**
+     * Inner join.
+     */
     INNER, 
 
-    /** Left outer join. */
+    /**
+     * Left outer join.
+     */
     LEFT, 
 
-    /** Right outer join. */
-    RIGHT
+    /**
+     * Right outer join.
+     */
+    RIGHT,
 }