add getNamedEntityGraphs() to EntityType

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

@@ -31,9 +31,9 @@
  * @see Subgraph
  * @see NamedEntityGraph
  *
- * @see EntityManager#createEntityGraph(Class)
- * @see EntityManager#createEntityGraph(String)
- * @see EntityManager#getEntityGraph(String)
+ * @see GraphFactory#createEntityGraph(Class)
+ * @see GraphFactory#createEntityGraph(String)
+ * @see GraphFactory#getEntityGraph(String)
  * @see EntityManagerFactory#addNamedEntityGraph(String, EntityGraph)
  * @see EntityManager#find(EntityGraph, Object, FindOption...)
  *

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

@@ -19,7 +19,6 @@
 package jakarta.persistence;
 
 import java.util.Map;
-import java.util.List;
 
 import jakarta.persistence.criteria.CriteriaSelect;
 import jakarta.persistence.metamodel.Metamodel;
@@ -189,7 +188,7 @@
  * 
  * @since 1.0
  */
-public interface EntityManager extends AutoCloseable {
+public interface EntityManager extends GraphFactory, AutoCloseable {
 
     /**
      * Make a new entity instance managed and persistent, resulting in
@@ -1325,46 +1324,6 @@ StoredProcedureQuery createStoredProcedureQuery(
      */
     Metamodel getMetamodel();
 
-    /**
-     * Create a new mutable {@link EntityGraph}, allowing dynamic
-     * definition of an entity graph.
-     * @param rootType class of entity graph
-     * @return entity graph
-     * @since 2.1
-     */
-    <T> EntityGraph<T> createEntityGraph(Class<T> rootType);
-
-    /**
-     * Obtain a mutable copy of a named {@link EntityGraph}, or
-     * return null if there is no entity graph with the given
-     * name.
-     * @param graphName name of an entity graph
-     * @return entity graph
-     * @since 2.1
-     */
-    EntityGraph<?> createEntityGraph(String graphName);
-
-    /**
-     * Obtain a named {@link EntityGraph}. The returned instance
-     * of {@code EntityGraph} should be considered immutable.
-     * @param graphName  name of an existing entity graph
-     * @return named entity graph
-     * @throws IllegalArgumentException if there is no entity
-     *         of graph with the given name
-     * @since 2.1
-     */
-    EntityGraph<?> getEntityGraph(String graphName);
-
-    /**
-     * Return all named {@link EntityGraph}s that are defined for
-     * the given entity class type.
-     * @param entityClass  entity class
-     * @return list of all entity graphs defined for the entity
-     * @throws IllegalArgumentException if the class is not an entity
-     * @since 2.1
-     */
-    <T> List<EntityGraph<? super T>> getEntityGraphs(Class<T> entityClass);
-
     /**
      * Execute the given action using the database connection underlying this
      * {@code EntityManager}. Usually, the connection is a JDBC connection, but a

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

@@ -121,7 +121,7 @@
  *
  * @since 1.0
  */
-public interface EntityManagerFactory extends AutoCloseable {
+public interface EntityManagerFactory extends GraphFactory, AutoCloseable {
 
     /**
      * Create a new application-managed {@link EntityManager}. This
@@ -338,7 +338,8 @@ public interface EntityManagerFactory extends AutoCloseable {
     /**
      * Add a named copy of the given {@link EntityGraph} to this
      * {@code EntityManagerFactory}. If an entity graph with the
-     * given name already exists, it is replaced.
+     * given name already exists, it is replaced. The graph may
+     * be later retrieved via {@link #getEntityGraph(String)}.
      * @param graphName  name for the entity graph
      * @param entityGraph  entity graph
      * @since 2.1
@@ -358,19 +359,6 @@ public interface EntityManagerFactory extends AutoCloseable {
      */
     <R> Map<String, TypedQueryReference<R>> getNamedQueries(Class<R> resultType);
 
-    /**
-     * A map keyed by {@linkplain NamedEntityGraph#name graph name}, containing
-     * every named {@linkplain EntityGraph entity graph} whose entity type is
-     * assignable to the given Java type.
-     * @param entityType any Java type, including {@code Object.class}
-     *                   meaning all entity graphs
-     * @return a map keyed by graph name
-     * @param <E> the specified upper bound on the entity graph types
-     *
-     * @since 3.2
-     */
-    <E> Map<String, EntityGraph<? extends E>> getNamedEntityGraphs(Class<E> entityType);
-
     /**
      * Create a new application-managed {@link EntityManager} with an active
      * transaction, and execute the given function, passing the {@code EntityManager}

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

@@ -0,0 +1,115 @@
+/*
+ * Copyright (c) 2008, 2023 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      - 4.0
+
+package jakarta.persistence;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * An object which acts as a source of {@linkplain EntityGraph entity graphs}.
+ * <p>
+ * Note that entity graphs may also be obtained via the
+ * {@linkplain jakarta.persistence.metamodel.EntityType static metamodel}.
+ *
+ * @see EntityManagerFactory
+ * @see EntityManager
+ *
+ * @since 4.0
+ */
+public interface GraphFactory {
+
+    /**
+     * Create a new mutable {@link EntityGraph}, allowing programmatic
+     * definition of the graph.
+     * @param rootType the root entity type of the new graph
+     * @return a trivial entity graph with only a root node
+     * @see jakarta.persistence.metamodel.EntityType#createEntityGraph()
+     * @since 2.1
+     */
+    <T> EntityGraph<T> createEntityGraph(Class<T> rootType);
+
+    /**
+     * Obtain a mutable copy of a named {@link EntityGraph}, or return
+     * {@code null} if there is no entity graph with the given name.
+     * @param graphName the name of an existing entity graph
+     * @return a copy of the entity graph with the given name,
+     *         or {@code null} if there is no such graph
+     * @since 2.1
+     */
+    EntityGraph<?> createEntityGraph(String graphName);
+
+    /**
+     * Obtain a mutable copy of a named {@link EntityGraph}.
+     * @param rootType the root entity type of the graph
+     * @param graphName the name of an existing entity graph
+     * @return a copy of the entity graph with the given name
+     * @throws IllegalArgumentException if there is no entity
+     *         graph with the given name, or if the entity
+     *         graph with the given name does not have exactly
+     *         the given root entity type
+     * @since 4.0
+     */
+    <T> EntityGraph<T> createEntityGraph(Class<T> rootType, String graphName);
+
+    /**
+     * Obtain a named {@link EntityGraph}. The returned instance of
+     * {@code EntityGraph} should be considered immutable.
+     * @param graphName the name of an existing entity graph
+     * @return the entity graph with the given name
+     * @throws IllegalArgumentException if there is no entity
+     *         graph with the given name
+     * @since 2.1
+     */
+    EntityGraph<?> getEntityGraph(String graphName);
+
+    /**
+     * Obtain a named {@link EntityGraph}. The returned instance of
+     * {@code EntityGraph} should be considered immutable.
+     * @param rootType the root entity type of the graph
+     * @param graphName the name of an existing entity graph
+     * @return the entity graph with the given name
+     * @throws IllegalArgumentException if there is no entity
+     *         graph with the given name, or if the entity
+     *         graph with the given name does not have exactly
+     *         the given root entity type
+     * @since 4.0
+     */
+    <T> EntityGraph<T> getEntityGraph(Class<T> rootType, String graphName);
+
+    /**
+     * Return a list of all named {@link EntityGraph}s defined for the
+     * given root entity type or for any one of its entity supertypes.
+     * @param entityClass the root entity type of the graph
+     * @return list of all entity graphs defined for the root entity type
+     * @throws IllegalArgumentException if the class is not an entity
+     * @since 2.1
+     */
+    <T> List<EntityGraph<? super T>> getEntityGraphs(Class<T> entityClass);
+
+    /**
+     * A map keyed by {@linkplain NamedEntityGraph#name graph name},
+     * containing every named {@linkplain EntityGraph entity graph}
+     * whose entity type is assignable to the given Java type.
+     * @param entityType any Java type, including {@code Object.class}
+     *                   meaning all entity graphs
+     * @return a map keyed by graph name
+     * @param <E> the specified upper bound on the entity graph types
+     * @see jakarta.persistence.metamodel.EntityType#getNamedEntityGraphs()
+     * @since 3.2
+     */
+    <E> Map<String, EntityGraph<? extends E>> getNamedEntityGraphs(Class<E> entityType);
+
+}

api/src/main/java/jakarta/persistence/metamodel/EntityType.java

@@ -11,11 +11,17 @@
  */
 
 // Contributors:
+//     Gavin King      - 4.0
 //     Linda DeMichiel - 2.1
 //     Linda DeMichiel - 2.0
 
 package jakarta.persistence.metamodel;
 
+import jakarta.persistence.EntityGraph;
+import jakarta.persistence.NamedEntityGraph;
+
+import java.util.Map;
+
 /**
  * An instance of {@code EntityType} represents
  * an {@linkplain jakarta.persistence.Entity entity}
@@ -33,4 +39,23 @@ public interface EntityType<X>
      * @return entity name
      */
     String getName();
+
+    /**
+     * Create a new mutable {@link EntityGraph} with this given root entity type,
+     * allowing programmatic definition of the graph.
+     * @return a trivial entity graph with only a root node
+     * @see jakarta.persistence.GraphFactory#createEntityGraph(Class)
+     * @since 4.0
+     */
+    EntityGraph<X> createEntityGraph();
+
+    /**
+     * A map keyed by {@linkplain NamedEntityGraph#name graph name}, containing
+     * every named {@linkplain EntityGraph entity graph} whose root entity type
+     * is this type.
+     * @return a map keyed by graph name
+     * @see jakarta.persistence.GraphFactory#getNamedEntityGraphs(Class)
+     * @since 4.0
+     */
+    Map<String,EntityGraph<X>> getNamedEntityGraphs();
 }