HHH-8774 : Add Javadoc for load plans

hibernate-core/src/main/java/org/hibernate/loader/plan/build/internal/AbstractLoadPlanBuildingAssociationVisitationStrategy.java

@@ -73,13 +73,13 @@ import org.jboss.logging.Logger;
 import org.jboss.logging.MDC;
 
 /**
- * A LoadPlanBuilderStrategy is a strategy for building a LoadPlan.  LoadPlanBuilderStrategy is also a
+ * A LoadPlanBuildingAssociationVisitationStrategy is a strategy for building a LoadPlan.
- * AssociationVisitationStrategy, which is used in conjunction with visiting associations via walking
+ * LoadPlanBuildingAssociationVisitationStrategy is also a AssociationVisitationStrategy, which is used in
- * metamodel definitions.
+ * conjunction with visiting associations via walking metamodel definitions.
  * <p/>
- * So this strategy defines a AssociationVisitationStrategy that walks the metamodel defined associations after
+ * So this strategy defines a AssociationVisitationStrategy that walks the metamodel-defined associations after
- * which is can then build a LoadPlan based on the visited associations.  {@link #determineFetchStrategy} Is the
+ * which is can then build a LoadPlan based on the visited associations. {@link #determineFetchStrategy} is the
- * main decision point
+ * main decision point that determines if an association is walked.
  *
  * @author Steve Ebersole
  *
@@ -98,11 +98,21 @@ public abstract class AbstractLoadPlanBuildingAssociationVisitationStrategy
 
 	private final ArrayDeque<ExpandingFetchSource> fetchSourceStack = new ArrayDeque<ExpandingFetchSource>();
 
+	/**
+	 * Constructs an AbstractLoadPlanBuildingAssociationVisitationStrategy.
+	 *
+	 * @param sessionFactory The session factory.
+	 */
 	protected AbstractLoadPlanBuildingAssociationVisitationStrategy(SessionFactoryImplementor sessionFactory) {
 		this.sessionFactory = sessionFactory;
 		this.querySpaces = new QuerySpacesImpl( sessionFactory );
 	}
 
+	/**
+	 * Gets the session factory.
+	 *
+	 * @return The session factory.
+	 */
 	protected SessionFactoryImplementor sessionFactory() {
 		return sessionFactory;
 	}

hibernate-core/src/main/java/org/hibernate/loader/plan/build/internal/CascadeStyleLoadPlanBuildingAssociationVisitationStrategy.java

@@ -45,6 +45,15 @@ public class CascadeStyleLoadPlanBuildingAssociationVisitationStrategy
 
 	private final CascadingAction cascadeActionToMatch;
 
+	/**
+	 * Constructs a CascadeStyleLoadPlanBuildingAssociationVisitationStrategy.
+	 *
+	 * @param cascadeActionToMatch The particular cascading action that an attribute definition must match
+	 *                             to eagerly fetch that attribute.
+	 * @param sessionFactory The session factory
+	 * @param loadQueryInfluencers The options which can influence the SQL query needed to perform the load.
+	 * @param lockMode The lock mode.
+	 */
 	public CascadeStyleLoadPlanBuildingAssociationVisitationStrategy(
 			CascadingAction cascadeActionToMatch,
 			SessionFactoryImplementor sessionFactory,

hibernate-core/src/main/java/org/hibernate/loader/plan/build/internal/FetchStyleLoadPlanBuildingAssociationVisitationStrategy.java

@@ -31,6 +31,7 @@ import org.hibernate.engine.FetchTiming;
 import org.hibernate.engine.spi.LoadQueryInfluencers;
 import org.hibernate.engine.spi.SessionFactoryImplementor;
 import org.hibernate.internal.CoreLogging;
+import org.hibernate.loader.plan.build.spi.LoadPlanBuildingAssociationVisitationStrategy;
 import org.hibernate.loader.plan.spi.CollectionReturn;
 import org.hibernate.loader.plan.spi.EntityReturn;
 import org.hibernate.loader.plan.spi.LoadPlan;
@@ -40,7 +41,7 @@ import org.hibernate.persister.walking.spi.AssociationAttributeDefinition;
 import org.jboss.logging.Logger;
 
 /**
- * LoadPlanBuilderStrategy implementation used for building LoadPlans based on metamodel-defined fetching.  Built
+ * {@link LoadPlanBuildingAssociationVisitationStrategy} implementation used for building LoadPlans based on metamodel-defined fetching.  Built
  * LoadPlans contain a single root return object, either an {@link EntityReturn} or a {@link CollectionReturn}.
  *
  * @author Steve Ebersole
@@ -54,6 +55,13 @@ public class FetchStyleLoadPlanBuildingAssociationVisitationStrategy
 
 	private Return rootReturn;
 
+	/**
+	 * Constructs a FetchStyleLoadPlanBuildingAssociationVisitationStrategy.
+	 *
+	 * @param sessionFactory The session factory
+	 * @param loadQueryInfluencers The options which can influence the SQL query needed to perform the load.
+	 * @param lockMode The lock mode.
+	 */
 	public FetchStyleLoadPlanBuildingAssociationVisitationStrategy(
 			SessionFactoryImplementor sessionFactory,
 			LoadQueryInfluencers loadQueryInfluencers,
@@ -106,6 +114,14 @@ public class FetchStyleLoadPlanBuildingAssociationVisitationStrategy
 		return fetchStrategy;
 	}
 
+	/**
+	 * If required by this strategy, returns a different {@link FetchStrategy} from what is specified
+	 * for the given association attribute.
+	 *
+	 * @param attributeDefinition The association attribute definition.
+	 * @param fetchStrategy The fetch strategy for <code>attributeDefinition</code>.
+	 * @return the {@link FetchStrategy}, possibly adjusted by this strategy.
+	 */
 	protected FetchStrategy adjustJoinFetchIfNeeded(
 			AssociationAttributeDefinition attributeDefinition,
 			FetchStrategy fetchStrategy) {
@@ -130,26 +146,4 @@ public class FetchStyleLoadPlanBuildingAssociationVisitationStrategy
 	protected boolean isTooManyCollections() {
 		return CollectionReturn.class.isInstance( rootReturn );
 	}
-
-//	@Override
-//	protected EntityReturn buildRootEntityReturn(EntityDefinition entityDefinition) {
-//		final String entityName = entityDefinition.getEntityPersister().getEntityName();
-//		return new EntityReturn(
-//				sessionFactory(),
-//				LockMode.NONE, // todo : for now
-//				entityName
-//		);
-//	}
-//
-//	@Override
-//	protected CollectionReturn buildRootCollectionReturn(CollectionDefinition collectionDefinition) {
-//		final CollectionPersister persister = collectionDefinition.getCollectionPersister();
-//		final String collectionRole = persister.getRole();
-//		return new CollectionReturn(
-//				sessionFactory(),
-//				LockMode.NONE, // todo : for now
-//				persister.getOwnerEntityPersister().getEntityName(),
-//				StringHelper.unqualify( collectionRole )
-//		);
-//	}
 }

hibernate-core/src/main/java/org/hibernate/loader/plan/build/internal/LoadPlanImpl.java

@@ -30,6 +30,7 @@ import org.hibernate.internal.CoreLogging;
 import org.hibernate.loader.plan.spi.CollectionReturn;
 import org.hibernate.loader.plan.spi.EntityReturn;
 import org.hibernate.loader.plan.spi.LoadPlan;
+import org.hibernate.loader.plan.spi.QuerySpace;
 import org.hibernate.loader.plan.spi.QuerySpaces;
 import org.hibernate.loader.plan.spi.Return;
 
@@ -61,6 +62,9 @@ public class LoadPlanImpl implements LoadPlan {
 	 * Creates a {@link Disposition#ENTITY_LOADER} LoadPlan.
 	 *
 	 * @param rootReturn The EntityReturn representation of the entity being loaded.
+	 * @param querySpaces The QuerySpaces containing all the {@link QuerySpace} references
+	 *                    required for <code>rootReturn</code> and joined entity, collection,
+	 *                    and composite references.
 	 */
 	public LoadPlanImpl(EntityReturn rootReturn, QuerySpaces querySpaces) {
 		this( Collections.singletonList( rootReturn ), querySpaces, Disposition.ENTITY_LOADER, false );
@@ -70,6 +74,9 @@ public class LoadPlanImpl implements LoadPlan {
 	 * Creates a {@link Disposition#COLLECTION_INITIALIZER} LoadPlan.
 	 *
 	 * @param rootReturn The CollectionReturn representation of the collection being initialized.
+	 * @param querySpaces The QuerySpaces containing all the {@link QuerySpace} references
+	 *                    required for <code>rootReturn</code> and joined entity, collection,
+	 *                    and composite references.
 	 */
 	public LoadPlanImpl(CollectionReturn rootReturn, QuerySpaces querySpaces) {
 		this( Collections.singletonList( rootReturn ), querySpaces, Disposition.COLLECTION_INITIALIZER, false );
@@ -79,6 +86,9 @@ public class LoadPlanImpl implements LoadPlan {
 	 * Creates a {@link Disposition#MIXED} LoadPlan.
 	 *
 	 * @param returns The mixed Return references
+	 * @param querySpaces The QuerySpaces containing all the {@link QuerySpace} references
+	 *                    required for <code>rootReturn</code> and joined entity, collection,
+	 *                    and composite references.
 	 * @param areLazyAttributesForceFetched Should lazy attributes (bytecode enhanced laziness) be fetched also?  This
 	 * effects the eventual SQL SELECT-clause which is why we have it here.  Currently this is "all-or-none"; you
 	 * can request that all lazy properties across all entities in the loadplan be force fetched or none.  There is