HHH-8774 : Add Javadoc for load plans

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

@@ -66,6 +66,7 @@ public abstract class AbstractAnyReference implements FetchSource {
 
 	@Override
 	public String getQuerySpaceUid() {
+		// TODO: should this throw UnsupportedOperationException?
 		return null;
 	}
 

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/AttributeFetch.java

@@ -34,7 +34,8 @@ public interface AttributeFetch extends Fetch {
 
 	/**
 	 * Returns the {@link AttributeDefinition} for attribute being fetched.
-	 * @return
+	 *
+	 * @return The fetched attribute definition.
 	 */
 	public AttributeDefinition getFetchedAttributeDefinition();
 }

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/BidirectionalEntityReference.java

@@ -24,10 +24,14 @@
 package org.hibernate.loader.plan.spi;
 
 /**
- * Represents the circular side of a bi-directional entity .  Wraps a reference to an EntityReference
- * as an EntityFetch.  We can use the special type as a trigger in AliasResolutionContext, etc to lookup information
- * based on the wrapped reference.
+ * Represents the circular side of a bi-directional entity association. Wraps a reference to the associated
+ * (target) EntityReference.
  * <p/>
+ * The {@link org.hibernate.loader.plan.exec.spi.EntityReferenceAliases} for this object is the same as
+ * for its target EntityReference, and can be looked up via
+ * {@link org.hibernate.loader.plan.exec.spi.AliasResolutionContext#resolveEntityReferenceAliases(String)}
+ * using the value returned by {@link #getQuerySpaceUid()}.
+ *
  * This relies on reference lookups against the EntityReference instances, therefore this allows representation of the
  * circularity but with a little protection against potential stack overflows.  This is unfortunately still a cyclic
  * graph.  An alternative approach is to make the graph acyclic (DAG) would be to follow the process I adopted in the
@@ -45,4 +49,12 @@ public interface BidirectionalEntityReference extends EntityReference {
 	 * @return The targeted EntityReference
 	 */
 	public EntityReference getTargetEntityReference();
+
+	/**
+	 * The query space UID returned using {@link #getQuerySpaceUid()} must
+	 * be the same as returned by {@link #getTargetEntityReference()#getQuerySpaceUid()}
+	 *
+	 * @return The query space UID.
+	 */
+	public String getQuerySpaceUid();
 }

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/CollectionAttributeFetch.java

@@ -31,6 +31,11 @@ import org.hibernate.type.CollectionType;
  * @author Steve Ebersole
  */
 public interface CollectionAttributeFetch extends AttributeFetch, CollectionReference {
+	/**
+	 * Get the Hibernate Type that describes the fetched attribute as a {@link CollectionType}.
+	 *
+	 * @return The Type of the fetched attribute
+	 */
 	@Override
 	public CollectionType getFetchedType();
 

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/CollectionFetchableElement.java

@@ -24,7 +24,7 @@
 package org.hibernate.loader.plan.spi;
 
 /**
- * A collection element which can be a FetchSource.
+ * A collection element which is a {@link FetchSource}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/CollectionFetchableIndex.java

@@ -24,7 +24,7 @@
 package org.hibernate.loader.plan.spi;
 
 /**
- * A collection index which can be a FetchSource.
+ * A collection index which is a {@link FetchSource}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/CollectionReference.java

@@ -27,7 +27,7 @@ import org.hibernate.loader.PropertyPath;
 import org.hibernate.persister.collection.CollectionPersister;
 
 /**
- * Represents a reference to a persistent collection either as a Return or as a Fetch
+ * Represents a reference to a persistent collection either as a Return or as a {@link CollectionAttributeFetch}.
  *
  * @author Steve Ebersole
  */
@@ -41,7 +41,7 @@ public interface CollectionReference {
 	public String getQuerySpaceUid();
 
 	/**
-	 * Retrieves the CollectionPersister describing the collection associated with this Return.
+	 * Retrieves the CollectionPersister describing the collection associated with this CollectionReference.
 	 *
 	 * @return The CollectionPersister.
 	 */
@@ -51,7 +51,7 @@ public interface CollectionReference {
 	 * Retrieve the metadata about the index of this collection *as a FetchSource*.  Will return
 	 * {@code null} when:<ul>
 	 *     <li>the collection is not indexed</li>
-	 *     <li>the index is not a composite or entity (cannot act as a FetchSource)</li>
+	 *     <li>the index is not a composite, entity, or "any" (cannot act as a FetchSource)</li>
 	 * </ul>
 	 * <p/>
 	 * Works only for map keys, since a List index (int type) cannot act as a FetchSource.
@@ -63,7 +63,7 @@ public interface CollectionReference {
 
 	/**
 	 * Retrieve the metadata about the elements of this collection *as a FetchSource*.  Will return
-	 * {@code null} when the element is not a composite or entity (cannot act as a FetchSource).
+	 * {@code null} when the element is not a composite, entity, or "any" (cannot act as a FetchSource).
 	 * Works only for map keys, since a List index cannot be anything other than an int which cannot be a FetchSource.
 	 * <p/>
 	 *

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/CompositeAttributeFetch.java

@@ -24,6 +24,8 @@
 package org.hibernate.loader.plan.spi;
 
 /**
+ * Models the requested fetching of a composite attribute.
+ *
  * @author Gail Badner
  */
 public interface CompositeAttributeFetch extends CompositeFetch, AttributeFetch {

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/CompositeFetch.java

@@ -24,7 +24,9 @@
 package org.hibernate.loader.plan.spi;
 
 /**
- * Models the requested fetching of a composite attribute.
+ * Models the requested fetching of a composition (component/embeddable), which may or may not be an attribute.
+ *
+ * @see CompositeAttributeFetch
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/EntityFetch.java

@@ -26,9 +26,16 @@ package org.hibernate.loader.plan.spi;
 import org.hibernate.type.EntityType;
 
 /**
+ * Models the requested fetching of an entity attribute.
+ *
  * @author Steve Ebersole
  */
 public interface EntityFetch extends AttributeFetch, EntityReference {
+	/**
+	 * Get the Hibernate Type that describes the fetched attribute as an {@link EntityType}.
+	 *
+	 * @return The Type of the fetched attribute
+	 */
 	@Override
 	EntityType getFetchedType();
 }

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/EntityReference.java

@@ -26,7 +26,7 @@ package org.hibernate.loader.plan.spi;
 import org.hibernate.persister.entity.EntityPersister;
 
 /**
- * Represents a reference to an entity either as a return or as a fetch
+ * Represents a reference to an entity either as a return, fetch, or collection element or index.
  *
  * @author Steve Ebersole
  */
@@ -48,7 +48,7 @@ public interface EntityReference extends FetchSource {
 	public EntityPersister getEntityPersister();
 
 	/**
-	 * Get the description of this entity's identifier.
+	 * Get the description of this entity's identifier descriptor.
 	 *
 	 * @return The identifier description.
 	 */

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/Fetch.java

@@ -73,7 +73,6 @@ public interface Fetch {
 
 
 	// Hoping to make these go away ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 	public String getAdditionalJoinConditions();
 
 	/**

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/FetchSource.java

@@ -34,12 +34,17 @@ import org.hibernate.loader.PropertyPath;
 public interface FetchSource {
 
 	/**
-	 * Get the property path to this fetch owner
+	 * Get the property path to this fetch source
 	 *
 	 * @return The property path
 	 */
 	public PropertyPath getPropertyPath();
 
+	/**
+	 * Get the UID for this fetch source's query space.
+	 *
+	 * @return The query space UID.
+	 */
 	public String getQuerySpaceUid();
 
 	/**
@@ -59,73 +64,15 @@ public interface FetchSource {
 	/**
 	 * Resolve the "current" {@link EntityReference}, or null if none.
 	 *
-	 * If this object is an {@link EntityReference}, then this object is returned.
-	 *
-	 * If this object is a {@link CompositeFetch}, then the nearest {@link EntityReference}
-	 * will be resolved from its source, if possible.
+	 * If this object is an {@link EntityReference}, then this object is returned;
+	 * otherwise, if this object is a {@link Fetch}, then the nearest
+	 * {@link EntityReference} will be resolved from its source, if possible.
 	 *
 	 * If no EntityReference can be resolved, null is return.
 	 *
 	 *  @return the "current" EntityReference or null if none.
-	 *  otherwise, if this object is also a {@link Fetch}, then
 	 * .
 	 * @see org.hibernate.loader.plan.spi.Fetch#getSource().
-	 * 	 */
-	public EntityReference resolveEntityReference();
-
-	// Stuff I can hopefully remove ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-	/**
-	 * The idea of addFetch() below has moved to {@link org.hibernate.loader.plan.build.spi.ExpandingFetchSource}.
-	 * <p/>
-	 * Most of the others are already part of Fetch
 	 */
-
-
-//
-//
-//
-//	/**
-//	 * Returns the type of the specified fetch.
-//	 *
-//	 * @param fetch - the owned fetch.
-//	 *
-//	 * @return the type of the specified fetch.
-//	 */
-//	public Type getType(Fetch fetch);
-//
-//	/**
-//	 * Is the specified fetch nullable?
-//	 *
-//	 * @param fetch - the owned fetch.
-//	 *
-//	 * @return true, if the fetch is nullable; false, otherwise.
-//	 */
-//	public boolean isNullable(Fetch fetch);
-//
-//	/**
-//	 * Generates the SQL select fragments for the specified fetch.  A select fragment is the column and formula
-//	 * references.
-//	 *
-//	 * @param fetch - the owned fetch.
-//	 * @param alias The table alias to apply to the fragments (used to qualify column references)
-//	 *
-//	 * @return the select fragments
-//	 */
-//	public String[] toSqlSelectFragments(Fetch fetch, String alias);
-//
-//	/**
-//	 * Contract to add fetches to this owner.  Care should be taken in calling this method; it is intended
-//	 * for Hibernate usage
-//	 *
-//	 * @param fetch The fetch to add
-//	 */
-//	public void addFetch(Fetch fetch);
-//
-//
-//	public SqlSelectFragmentResolver toSqlSelectFragmentResolver();
-//
-//
-//
-
+	public EntityReference resolveEntityReference();
 }

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/Join.java

@@ -28,23 +28,51 @@ package org.hibernate.loader.plan.spi;
  * metamodel-driven LoadPlans, this would be joins indicated by the metamodel.
  */
 public interface Join {
-	// todo : would be good to have the SQL alias info here because we know it when we would be building this Join,
-	// and to do it afterwards would require lot of logic to recreate.
-	// But we do want this model to be workable in Search/OGM as well, plus the HQL parser has shown time-and-again
-	// that it is best to put off resolving and injecting physical aliases etc until as-late-as-possible.
-
-	// todo : do we know enough here to declare the "owner" side?  aka, the "fk direction"
-	// and if we do ^^, is that enough to figure out the SQL aliases more easily (see above)?
-
+	/**
+	 * Get the {@link QuerySpace} from the left-hand-side of the join.
+	 *
+	 * @return the query space from the left-hand-side of the join.
+	 */
 	public QuerySpace getLeftHandSide();
 
+	/**
+	 * Get the {@link QuerySpace} from the right-hand-side of the join.
+	 *
+	 * @return the query space from the right-hand-side of the join.
+	 */
 	public QuerySpace getRightHandSide();
 
+	/**
+	 * Indicates if the joined attribute is required to be non-null.
+	 *
+	 * @return true, if the joined attribute is required to be non-null; false, otherwise.
+	 */
 	public boolean isRightHandSideRequired();
 
 	// Ugh!  This part will unfortunately be SQL specific :( ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+	/**
+	 * Resolves the column names prefixed by the specified alias on the
+	 * left-hand-side of the join.
+	 *
+	 * @param leftHandSideTableAlias The table alias used to prefix the columns.
+	 * @return the aliased columns on the left-hand-side of the join.
+	 */
 	public String[] resolveAliasedLeftHandSideJoinConditionColumns(String leftHandSideTableAlias);
+
+	/**
+	 * Resolves the raw (unaliased) column names on the right-hand-side of the join.
+	 *
+	 * @return the columns on the right-hand-side of the join.
+	 */
 	public String[] resolveNonAliasedRightHandSideJoinConditionColumns();
+
+	/**
+	 * Gets any additional conditions on the right-hand-side of the join using
+	 * the specified table alias.
+	 *
+	 * @param rhsTableAlias The table alias.
+	 * @return additional conditions on the right-hand-side of the join.
+	 */
 	public String getAnyAdditionalJoinConditions(String rhsTableAlias);
 }

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/JoinDefinedByMetadata.java

@@ -39,5 +39,11 @@ public interface JoinDefinedByMetadata extends Join {
 	 * @return The property name
 	 */
 	public String getJoinedPropertyName();
+
+	/**
+	 * Get the property type of the joined property.
+	 *
+	 * @return The property type.
+	 */
 	public Type getJoinedPropertyType();
 }

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/LoadPlan.java

@@ -75,6 +75,8 @@ public interface LoadPlan {
 	 *         {@link org.hibernate.loader.plan.spi.ScalarReturn} elements, but no {@link org.hibernate.loader.plan.spi.CollectionReturn}.
 	 *     </li>
 	 * </ul>
+	 * <p/>
+	 * When generating SQL, the Returns provide columns/formulas used in the "select clause".
 	 *
 	 * @return The Returns for this LoadPlan.
 	 *
@@ -83,11 +85,11 @@ public interface LoadPlan {
 	public List<? extends Return> getReturns();
 
 	/**
-	 * todo : document this...
+	 * Gets the {@link QuerySpaces} for the load plan, which contains a {@link QuerySpace}
+	 * reference for each non-scalar return and for each entity, collection, and composite
+	 * {@link FetchSource}.
 	 * <p/>
-	 * this is the stuff that was added in this plan package...  splitting the "from clause" and "select clause"
-	 * graphs and removing all (started) SQL references.  QuerySpaces represents the "from clause".  The
-	 * "select clause" is represented by {@link #getReturns()}.
+	 * When generating SQL, the query spaces provide data for the "from clause" including joins.
 	 *
 	 * @return The QuerySpaces
 	 */
@@ -131,8 +133,8 @@ public interface LoadPlan {
 		 */
 		COLLECTION_INITIALIZER,
 		/**
-		 * We have a mixed load plan, which will have one or more returns of {@link org.hibernate.loader.plan.spi.EntityReturn} and {@link org.hibernate.loader.plan.spi.ScalarReturn}
-		 * (NOT {@link org.hibernate.loader.plan.spi.CollectionReturn}).
+		 * We have a mixed load plan, which will have one or more returns of {@link org.hibernate.loader.plan.spi.EntityReturn}
+		 * and {@link org.hibernate.loader.plan.spi.ScalarReturn} (NOT {@link org.hibernate.loader.plan.spi.CollectionReturn}).
 		 */
 		MIXED
 	}

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/QuerySpace.java

@@ -44,20 +44,19 @@ public interface QuerySpace {
 	public String getUid();
 
 	/**
-	 * Get the QuerySpaces object that is our owner.
+	 * Get the {@link QuerySpaces} object that is our owner.
 	 *
 	 * @return The QuerySpaces containing this QuerySpace
 	 */
 	public QuerySpaces getQuerySpaces();
 
 	/**
-	 * Get the PropertyMapping for this QuerySpace.
+	 * Get the {@link PropertyMapping} for this QuerySpace.
 	 *
 	 * @return The PropertyMapping
 	 */
 	public PropertyMapping getPropertyMapping();
 
-
 	/**
 	 * Get the aliased column names for the specified property in the query space..
 	 *
@@ -71,7 +70,6 @@ public interface QuerySpace {
 	 * Enumeration of the different types of QuerySpaces we can have.
 	 */
 	public static enum Disposition {
-		// todo : account for special distinctions too like COLLECTION INDEX/ELEMENT too?
 		/**
 		 * We have an entity-based QuerySpace.  It is castable to {@link EntityQuerySpace} for more details.
 		 */
@@ -95,11 +93,11 @@ public interface QuerySpace {
 
 	/**
 	 * Obtain all joins which originate from this QuerySpace, in other words, all the joins which this QuerySpace is
-	 * the right-hand-side of.
+	 * the left-hand-side of.
 	 * <p/>
-	 * For all the joins returned here, {@link Join#getRightHandSide()} should point back to this QuerySpace such that
+	 * For all the joins returned here, {@link Join#getLeftHandSide()} should point back to this QuerySpace such that
 	 * <code>
-	 *     space.getJoins().forEach{ join -> join.getRightHandSide() == space }
+	 *     space.getJoins().forEach{ join -> join.getLeftHandSide() == space }
 	 * </code>
 	 * is true for all.
 	 *

hibernate-core/src/main/java/org/hibernate/loader/plan/spi/QuerySpaceUidNotRegisteredException.java

@@ -36,7 +36,7 @@ public class QuerySpaceUidNotRegisteredException extends HibernateException {
 	}
 
 	private static String generateMessage(String uid) {
-		return "Given uid [" + uid + "] could not be resolved to QuerySpace";
+		return "Given uid [" + uid + "] could not be resolved to a QuerySpace";
 	}
 
 	public QuerySpaceUidNotRegisteredException(String uid, Throwable cause) {