add CriteriaSelect to fix mistake in design of union/intersect for cr…

…iteria API

api/src/main/java/jakarta/persistence/EntityManager.java

@@ -21,6 +21,7 @@
 import java.util.Map;
 import java.util.List;
 
+import jakarta.persistence.criteria.CriteriaSelect;
 import jakarta.persistence.metamodel.Metamodel;
 import jakarta.persistence.criteria.CriteriaBuilder;
 import jakarta.persistence.criteria.CriteriaQuery;
@@ -970,6 +971,18 @@ void refresh(Object entity,
      */
     <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery);
 
+    /**
+     * Create an instance of {@link TypedQuery} for executing a
+     * criteria query, which may be a union or intersection of
+     * top-level queries.
+     * @param criteriaQuery  a criteria query object
+     * @return the new query instance
+     * @throws IllegalArgumentException if the criteria query is
+     *         found to be invalid
+     * @since 3.2
+     */
+    <T> TypedQuery<T> createQuery(CriteriaSelect<T> criteriaQuery);
+
     /**
      * Create an instance of {@link Query} for executing a criteria
      * update query.

api/src/main/java/jakarta/persistence/criteria/CriteriaBuilder.java

@@ -1807,7 +1807,7 @@ <T> Expression<T> function(String name, Class<T> type,
      *         the results of the given queries
      * @since 3.2
      */
-    <T> CriteriaQuery<T> union(CriteriaQuery<? extends T> left, CriteriaQuery<? extends T> right);
+    <T> CriteriaSelect<T> union(CriteriaSelect<? extends T> left, CriteriaSelect<? extends T> right);
 
     /**
      * Create a query which is the union of the given queries,
@@ -1816,15 +1816,15 @@ <T> Expression<T> function(String name, Class<T> type,
      *         the results of the given queries
      * @since 3.2
      */
-    <T> CriteriaQuery<T> unionAll(CriteriaQuery<? extends T> left, CriteriaQuery<? extends T> right);
+    <T> CriteriaSelect<T> unionAll(CriteriaSelect<? extends T> left, CriteriaSelect<? extends T> right);
 
     /**
      * Create a query which is the intersection of the given queries.
      * @return a new criteria query which returns the intersection of
      *         the results of the given queries
      * @since 3.2
      */
-    <T> CriteriaQuery<T> intersect(CriteriaQuery<? super T> left, CriteriaQuery<? super T> right);
+    <T> CriteriaSelect<T> intersect(CriteriaSelect<? super T> left, CriteriaSelect<? super T> right);
 
     /**
      * Create a query which is the intersection of the given queries,
@@ -1833,7 +1833,7 @@ <T> Expression<T> function(String name, Class<T> type,
      *         the results of the given queries
      * @since 3.2
      */
-    <T> CriteriaQuery<T> intersectAll(CriteriaQuery<? super T> left, CriteriaQuery<? super T> right);
+    <T> CriteriaSelect<T> intersectAll(CriteriaSelect<? super T> left, CriteriaSelect<? super T> right);
 
     /**
      * Create a query by (setwise) subtraction of the second query
@@ -1843,7 +1843,7 @@ <T> Expression<T> function(String name, Class<T> type,
      *         results of the first query
      * @since 3.2
      */
-    <T> CriteriaQuery<T> except(CriteriaQuery<T> left, CriteriaQuery<?> right);
+    <T> CriteriaSelect<T> except(CriteriaSelect<T> left, CriteriaSelect<?> right);
 
     /**
      * Create a query by (setwise) subtraction of the second query
@@ -1853,7 +1853,7 @@ <T> Expression<T> function(String name, Class<T> type,
      *         results of the first query
      * @since 3.2
      */
-    <T> CriteriaQuery<T> exceptAll(CriteriaQuery<T> left, CriteriaQuery<?> right);
+    <T> CriteriaSelect<T> exceptAll(CriteriaSelect<T> left, CriteriaSelect<?> right);
 }
 
 

api/src/main/java/jakarta/persistence/criteria/CriteriaQuery.java

@@ -29,7 +29,7 @@
  *
  * @since 2.0
  */
-public interface CriteriaQuery<T> extends AbstractQuery<T> {
+public interface CriteriaQuery<T> extends AbstractQuery<T>, CriteriaSelect<T> {
 
     /**
      * Specify the item that is to be returned in the query result.

api/src/main/java/jakarta/persistence/criteria/CriteriaSelect.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0,
+ * or the Eclipse Distribution License v. 1.0 which is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
+ */
+
+// Contributors:
+//     Gavin King     - 3.2
+//     Lukas Jungmann - 3.2
+
+package jakarta.persistence.criteria;
+
+/**
+ * Abstracts over {@linkplain CriteriaQuery top-level queries} and
+ * {@linkplain CriteriaBuilder#union unions} and
+ * {@linkplain CriteriaBuilder#intersect intersections} of top-level
+ * queries.
+ *
+ * @param <T>  the type returned by the query
+ *
+ * @since 3.2
+ */
+public interface CriteriaSelect<T> {
+}

spec/src/main/asciidoc/ch03-entity-operations.adoc

@@ -862,6 +862,18 @@ public interface EntityManager extends AutoCloseable {
      */
     public <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery);
 
+    /**
+     * Create an instance of <code>TypedQuery</code> for executing a
+     * criteria query, which may be a union or intersection of
+     * top-level queries.
+     * @param criteriaQuery  a criteria query object
+     * @return the new query instance
+     * @throws IllegalArgumentException if the criteria query is
+     *         found to be invalid
+     * @since 3.2
+     */
+    <T> TypedQuery<T> createQuery(CriteriaSelect<T> criteriaQuery);
+
     /**
      * Create an instance of <code>Query</code> for executing a criteria
      * update query.

spec/src/main/asciidoc/ch06-criteria-api.adoc

@@ -1875,6 +1875,59 @@ Expression<?>... args);
      */
     <X, T extends X> Root<T> treat(Root<X> root, Class<T> type);
 
+    /**
+     * Create a query which is the union of the given queries.
+     * @return a new criteria query which returns the union of
+     *         the results of the given queries
+     * @since 3.2
+     */
+    <T> CriteriaSelect<T> union(CriteriaSelect<? extends T> left, CriteriaSelect<? extends T> right);
+
+    /**
+     * Create a query which is the union of the given queries,
+     * without elimination of duplicate results.
+     * @return a new criteria query which returns the union of
+     *         the results of the given queries
+     * @since 3.2
+     */
+    <T> CriteriaSelect<T> unionAll(CriteriaSelect<? extends T> left, CriteriaSelect<? extends T> right);
+
+    /**
+     * Create a query which is the intersection of the given queries.
+     * @return a new criteria query which returns the intersection of
+     *         the results of the given queries
+     * @since 3.2
+     */
+    <T> CriteriaSelect<T> intersect(CriteriaSelect<? super T> left, CriteriaSelect<? super T> right);
+
+    /**
+     * Create a query which is the intersection of the given queries,
+     * without elimination of duplicate results.
+     * @return a new criteria query which returns the intersection of
+     *         the results of the given queries
+     * @since 3.2
+     */
+    <T> CriteriaSelect<T> intersectAll(CriteriaSelect<? super T> left, CriteriaSelect<? super T> right);
+
+    /**
+     * Create a query by (setwise) subtraction of the second query
+     * from the first query.
+     * @return a new criteria query which returns the result of
+     *         subtracting the results of the second query from the
+     *         results of the first query
+     * @since 3.2
+     */
+    <T> CriteriaSelect<T> except(CriteriaSelect<T> left, CriteriaSelect<?> right);
+
+    /**
+     * Create a query by (setwise) subtraction of the second query
+     * from the first query, without elimination of duplicate results.
+     * @return a new criteria query which returns the result of
+     *         subtracting the results of the second query from the
+     *         results of the first query
+     * @since 3.2
+     */
+    <T> CriteriaSelect<T> exceptAll(CriteriaSelect<T> left, CriteriaSelect<?> right);
 }
 ----