HHH-19023 add operations on EntityGraphs to allow for session-free graph creation

Author: gavinking

hibernate-core/src/main/java/org/hibernate/graph/EntityGraphs.java

@@ -18,9 +18,13 @@
 import jakarta.persistence.Subgraph;
 import jakarta.persistence.TypedQuery;
 
+import jakarta.persistence.metamodel.EntityType;
 import org.hibernate.engine.spi.SessionImplementor;
+import org.hibernate.graph.internal.RootGraphImpl;
 import org.hibernate.graph.spi.GraphImplementor;
 import org.hibernate.graph.spi.RootGraphImplementor;
+import org.hibernate.metamodel.RepresentationMode;
+import org.hibernate.metamodel.model.domain.EntityDomainType;
 import org.hibernate.query.SelectionQuery;
 
 /**
@@ -33,6 +37,43 @@
  */
 public final class EntityGraphs {
 
+	/**
+	 * Create a new entity graph rooted at the given entity, without
+	 * needing a reference to the session or session factory.
+	 *
+	 * @param rootType The {@link EntityType} representing the root
+	 *                 entity of the graph
+	 * @return a new mutable {@link EntityGraph}
+	 *
+	 * @since 7.0
+	 */
+	public static <T> EntityGraph<T> createGraph(EntityType<T> rootType) {
+		return new RootGraphImpl<>( null, (EntityDomainType<T>) rootType );
+	}
+
+	/**
+	 * Create a new entity graph rooted at the given
+	 * {@linkplain RepresentationMode#MAP dynamic entity}, without
+	 * needing a reference to the session or session factory.
+	 *
+	 * @param rootType The {@link EntityType} representing the root
+	 *                 entity of the graph, which must be a dynamic
+	 *                 entity
+	 * @return a new mutable {@link EntityGraph}
+	 *
+	 * @since 7.0
+	 */
+	public static EntityGraph<Map<String,?>> createGraphForDynamicEntity(EntityType<?> rootType) {
+		final EntityDomainType<?> domainType = (EntityDomainType<?>) rootType;
+		if ( domainType.getRepresentationMode() != RepresentationMode.MAP ) {
+			throw new IllegalArgumentException( "Entity '" + domainType.getHibernateEntityName()
+												+ "' is not a dynamic entity" );
+		}
+		@SuppressWarnings("unchecked") //Safe, because we just checked
+		final EntityDomainType<Map<String, ?>> dynamicEntity = (EntityDomainType<Map<String, ?>>) domainType;
+		return new RootGraphImpl<>( null, dynamicEntity );
+	}
+
 	/**
 	 * Merges multiple entity graphs into a single graph that specifies the
 	 * fetching/loading of all attributes the input graphs specify.

hibernate-core/src/main/java/org/hibernate/graph/Graph.java

@@ -7,6 +7,7 @@
 import java.util.List;
 
 import jakarta.persistence.metamodel.Attribute;
+import jakarta.persistence.metamodel.EntityType;
 import jakarta.persistence.metamodel.ManagedType;
 import jakarta.persistence.metamodel.MapAttribute;
 import jakarta.persistence.metamodel.PluralAttribute;
@@ -33,12 +34,17 @@
  * <p>
  * Extends the JPA-defined {@link jakarta.persistence.Graph} with additional operations.
  * <p>
- * There are a range of ways to create {@code Graph}s:
+ * There are a range of ways to define {@code Graph}s:
  * <ul>
  * <li>programmatically, beginning with {@link org.hibernate.Session#createEntityGraph(Class)},
  * <li>using the {@link jakarta.persistence.NamedEntityGraph @NamedEntityGraph} annotation, or
  * <li>using the mini-language understood by {@link GraphParser}.
  * </ul>
+ * <p>
+ * When a graph is defined programmatically, the new graph is usually instantiated by calling
+ * {@link jakarta.persistence.EntityManager#createEntityGraph(Class)}. However, this requires
+ * a reference to and {@code EntityManager}, which might not always be convenient. An
+ * alternative is provided by {@link EntityGraphs#createGraph(EntityType)}.
  *
  * @apiNote Historically, both {@link jakarta.persistence.EntityGraph} and this interface
  * declared operations with incorrect generic types, leading to unsound code. This was

hibernate-core/src/main/java/org/hibernate/graph/RootGraph.java

@@ -5,6 +5,7 @@
 package org.hibernate.graph;
 
 import jakarta.persistence.EntityGraph;
+import jakarta.persistence.metamodel.EntityType;
 
 /**
  * Extends the JPA-defined {@link EntityGraph} with additional operations.
@@ -13,6 +14,13 @@
  * @author Andrea Boriero
  *
  * @see SubGraph
+ * @see org.hibernate.Session#createEntityGraph(Class)
+ * @see org.hibernate.Session#createEntityGraph(String)
+ * @see org.hibernate.Session#createEntityGraph(Class, String)
+ * @see org.hibernate.SessionFactory#findEntityGraphByName(String)
+ * @see org.hibernate.SessionFactory#createGraphForDynamicEntity(String)
+ * @see EntityGraphs#createGraph(EntityType)
+ * @see EntityGraphs#createGraphForDynamicEntity(EntityType)
  */
 public interface RootGraph<J> extends Graph<J>, EntityGraph<J> {