two API improvements to EntityGraphs

1. make fetch/load graph distinction clearer in the XxxxLoadAccess APIs
2. addPluralSubgraph(), which is missing in JPA

hibernate-core/src/main/java/org/hibernate/IdentifierLoadAccess.java

@@ -43,10 +43,21 @@ public interface IdentifierLoadAccess<T> {
 	 */
 	IdentifierLoadAccess<T> withReadOnly(boolean readOnly);
 
-	default IdentifierLoadAccess<T> with(RootGraph<T> graph) {
+	default IdentifierLoadAccess<T> fetching(RootGraph<T> graph) {
+		return with( graph, GraphSemantic.FETCH );
+	}
+	default IdentifierLoadAccess<T> loading(RootGraph<T> graph) {
 		return with( graph, GraphSemantic.LOAD );
 	}
 
+	/**
+	 * @deprecated use {@link #loading}
+	 */
+	@Deprecated(since = "6.3")
+	default IdentifierLoadAccess<T> with(RootGraph<T> graph) {
+		return loading( graph );
+	}
+
 	IdentifierLoadAccess<T> with(RootGraph<T> graph, GraphSemantic semantic);
 
 	/**

hibernate-core/src/main/java/org/hibernate/MultiIdentifierLoadAccess.java

@@ -36,6 +36,17 @@ public interface MultiIdentifierLoadAccess<T> {
 	 */
 	MultiIdentifierLoadAccess<T> with(CacheMode cacheMode);
 
+	default MultiIdentifierLoadAccess<T> fetching(RootGraph<T> graph) {
+		return with( graph, GraphSemantic.FETCH );
+	}
+	default MultiIdentifierLoadAccess<T> loading(RootGraph<T> graph) {
+		return with( graph, GraphSemantic.LOAD );
+	}
+
+	/**
+	 * @deprecated use {@link #loading}
+	 */
+	@Deprecated(since = "6.3")
 	default MultiIdentifierLoadAccess<T> with(RootGraph<T> graph) {
 		return with( graph, GraphSemantic.LOAD );
 	}
@@ -46,7 +57,7 @@ public interface MultiIdentifierLoadAccess<T> {
 	 * Specify a batch size for loading the entities (how many at a time).  The default is
 	 * to use a batch sizing strategy defined by the Dialect in use.  Any greater-than-one
 	 * value here will override that default behavior.  If giving an explicit value here,
-	 * care should be taken to not exceed the capabilities of of the underlying database.
+	 * care should be taken to not exceed the capabilities of the underlying database.
 	 * <p>
 	 * Note that overall a batch-size is considered a hint.  How the underlying loading
 	 * mechanism interprets that is completely up to that underlying loading mechanism.

hibernate-core/src/main/java/org/hibernate/NaturalIdMultiLoadAccess.java

@@ -35,9 +35,17 @@ public interface NaturalIdMultiLoadAccess<T> {
 	 */
 	NaturalIdMultiLoadAccess<T> with(CacheMode cacheMode);
 
+	default NaturalIdMultiLoadAccess<T> fetching(RootGraph<T> graph) {
+		return with( graph, GraphSemantic.FETCH );
+	}
+	default NaturalIdMultiLoadAccess<T> loading(RootGraph<T> graph) {
+		return with( graph, GraphSemantic.LOAD );
+	}
+
 	/**
-	 * Define a load graph to be used when retrieving the entity
+	 * @deprecated use {@link #loading}
 	 */
+	@Deprecated(since = "6.3")
 	default NaturalIdMultiLoadAccess<T> with(RootGraph<T> graph) {
 		return with( graph, GraphSemantic.LOAD );
 	}

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

@@ -8,6 +8,7 @@ package org.hibernate.graph;
 
 import java.util.List;
 
+import jakarta.persistence.metamodel.PluralAttribute;
 import org.hibernate.metamodel.model.domain.ManagedDomainType;
 import org.hibernate.metamodel.model.domain.PersistentAttribute;
 
@@ -23,6 +24,21 @@ import org.hibernate.metamodel.model.domain.PersistentAttribute;
  */
 @SuppressWarnings({"unused", "UnusedReturnValue"})
 public interface Graph<J> extends GraphNode<J> {
+
+	/**
+	 * Add a subgraph rooted at a plural attribute, allowing
+	 * further nodes to be added to the subgraph.
+	 *
+	 * @apiNote This method is missing in JPA, and nodes cannot be
+	 *          added in a typesafe way to subgraphs representing
+	 *          fetched collections
+	 *
+	 * @since 6.3
+	 */
+	default <AJ> SubGraph<AJ> addPluralSubgraph(PluralAttribute<? extends J, ?, AJ> attribute) {
+		return addSubGraph( attribute.getName() );
+	}
+
 	/**
 	 * Graphs apply only to {@link jakarta.persistence.metamodel.ManagedType}s.
 	 *
@@ -111,7 +127,6 @@ public interface Graph<J> extends GraphNode<J> {
 
 	<AJ> SubGraph<? extends AJ> addSubGraph(PersistentAttribute<? extends J, AJ> attribute, Class<? extends AJ> type) throws CannotContainSubGraphException;
 
-
 	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 	// key sub graph nodes