HHH-16651 clean up API of the engine.profile package

FetchProfile should really be immutable so lets move toward that

hibernate-core/src/main/java/org/hibernate/engine/profile/Association.java

@@ -5,10 +5,11 @@
  * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
  */
 package org.hibernate.engine.profile;
+
 import org.hibernate.persister.entity.EntityPersister;
 
 /**
- * Models the association of a given fetch.
+ * Identifies the association referenced by a {@link Fetch}.
  *
  * @author Steve Ebersole
  */
@@ -29,15 +30,29 @@ public class Association {
 		this.role = owner.getEntityName() + '.' + associationPath;
 	}
 
+	/**
+	 * The persister of the owning entity.
+	 */
 	public EntityPersister getOwner() {
 		return owner;
 	}
 
+	/**
+	 * The property path
+	 */
 	public String getAssociationPath() {
 		return associationPath;
 	}
 
+	/**
+	 * The fully qualified role name
+	 */
 	public String getRole() {
 		return role;
 	}
+
+	@Override
+	public String toString() {
+		return "Association[" + role + "]";
+	}
 }

hibernate-core/src/main/java/org/hibernate/engine/profile/Fetch.java

@@ -9,7 +9,7 @@ package org.hibernate.engine.profile;
 import java.util.Locale;
 
 /**
- * Models an individual fetch override within a profile.
+ * Models an individual fetch override within a {@link FetchProfile}.
  *
  * @author Steve Ebersole
  */
@@ -18,7 +18,7 @@ public class Fetch {
 	private final Style style;
 
 	/**
-	 * Constructs a Fetch
+	 * Constructs a {@link Fetch}.
 	 *
 	 * @param association The association to be fetched
 	 * @param style How to fetch it
@@ -28,10 +28,16 @@ public class Fetch {
 		this.style = style;
 	}
 
+	/**
+	 * The association to which the fetch style applies.
+	 */
 	public Association getAssociation() {
 		return association;
 	}
 
+	/**
+	 * The fetch style applied to the association.
+	 */
 	public Style getStyle() {
 		return style;
 	}

hibernate-core/src/main/java/org/hibernate/engine/profile/FetchProfile.java

@@ -9,6 +9,7 @@ package org.hibernate.engine.profile;
 import java.util.HashMap;
 import java.util.Map;
 
+import org.hibernate.Internal;
 import org.hibernate.internal.CoreLogging;
 import org.hibernate.internal.CoreMessageLogger;
 import org.hibernate.type.BagType;
@@ -45,7 +46,8 @@ public class FetchProfile {
 	private Fetch bagJoinFetch;
 
 	/**
-	 * Constructs a FetchProfile, supplying its unique name (unique within the SessionFactory).
+	 * Constructs a {@link FetchProfile} with the given unique name.
+	 * Fetch profile names must be unique within a given {@code SessionFactory}.
 	 *
 	 * @param name The name under which we are bound in the sessionFactory
 	 */
@@ -54,36 +56,44 @@ public class FetchProfile {
 	}
 
 	/**
-	 * Add a fetch override to the profile.
+	 * Add a {@linkplain Fetch fetch override} to the profile.
 	 *
 	 * @param association The association to be fetched
 	 * @param fetchStyleName The name of the fetch style to apply
+	 *
+	 * @deprecated No longer used
 	 */
-	@SuppressWarnings({ "UnusedDeclaration" })
+	@Deprecated(forRemoval = true)
 	public void addFetch(Association association, String fetchStyleName) {
-		addFetch( association, Fetch.Style.parse( fetchStyleName ) );
+		addFetch( new Fetch( association, Fetch.Style.parse( fetchStyleName ) ) );
 	}
 
 	/**
-	 * Add a fetch override to the profile.
+	 * Add a {@linkplain Fetch fetch override} to the profile.
 	 *
 	 * @param association The association to be fetched
 	 * @param style The style to apply
+	 *
+	 * @deprecated No longer used
 	 */
+	@Deprecated(forRemoval = true)
 	public void addFetch(Association association, Fetch.Style style) {
 		addFetch( new Fetch( association, style ) );
 	}
 
 	/**
-	 * Add a fetch override to the profile.
+	 * Add a {@linkplain Fetch fetch override} to the profile.
 	 *
-	 * @param fetch The fetch to add.
+	 * @param fetch The fetch override to add.
 	 */
+	@Internal
 	public void addFetch(final Fetch fetch) {
-		final String fetchAssociactionRole = fetch.getAssociation().getRole();
-		final Type associationType = fetch.getAssociation().getOwner().getPropertyType( fetch.getAssociation().getAssociationPath() );
+		final Association association = fetch.getAssociation();
+		final String role = association.getRole();
+		final Type associationType =
+				association.getOwner().getPropertyType( association.getAssociationPath() );
 		if ( associationType.isCollectionType() ) {
-			LOG.tracev( "Handling request to add collection fetch [{0}]", fetchAssociactionRole );
+			LOG.tracev( "Handling request to add collection fetch [{0}]", role );
 
 			// couple of things for which to account in the case of collection
 			// join fetches
@@ -92,7 +102,7 @@ public class FetchProfile {
 				// processed collection join fetches
 				if ( associationType instanceof BagType ) {
 					if ( containsJoinFetchedCollection ) {
-						LOG.containsJoinFetchedCollection( fetchAssociactionRole );
+						LOG.containsJoinFetchedCollection( role );
 						// EARLY EXIT!!!
 						return;
 					}
@@ -113,57 +123,54 @@ public class FetchProfile {
 				containsJoinFetchedCollection = true;
 			}
 		}
-		fetches.put( fetchAssociactionRole, fetch );
+		fetches.put( role, fetch );
 	}
 
 	/**
-	 * Getter for property 'name'.
-	 *
-	 * @return Value for property 'name'.
+	 * The name of this fetch profile
 	 */
 	public String getName() {
 		return name;
 	}
 
 	/**
-	 * Getter for property 'fetches'.  Map of {@link Fetch} instances, keyed by association {@code role}
-	 *
-	 * @return Value for property 'fetches'.
+	 * A map of {@link Fetch} instances, keyed by association role
 	 */
-	@SuppressWarnings({ "UnusedDeclaration" })
 	public Map<String,Fetch> getFetches() {
 		return fetches;
 	}
 
 	/**
-	 * Obtain the fetch associated with the given role.
+	 * Obtain the {@linkplain Fetch fetch override} associated with
+	 * the given role.
 	 *
-	 * @param role The role identifying the fetch
+	 * @param role The role name identifying the association
 	 *
-	 * @return The fetch, or {@code null} if a matching one was not found
+	 * @return The {@code Fetch}, or {@code null} if there was
+	 *         no {@code Fetch} for the given association
 	 */
 	public Fetch getFetchByRole(String role) {
 		return fetches.get( role );
 	}
 
 	/**
-	 * Getter for property 'containsJoinFetchedCollection', which flags whether
-	 * this fetch profile contained any collection join fetches.
+	 * Does this fetch profile contain any collection join fetches?
 	 *
-	 * @return Value for property 'containsJoinFetchedCollection'.
+	 * @deprecated No longer used
 	 */
-	@SuppressWarnings({ "UnusedDeclaration" })
+	@Deprecated(forRemoval = true)
 	public boolean isContainsJoinFetchedCollection() {
 		return containsJoinFetchedCollection;
 	}
 
 	/**
-	 * Getter for property 'containsJoinFetchedBag', which flags whether this
-	 * fetch profile contained any bag join fetches
+	 * Does this fetch profile contained any bag join fetches?
+	 *
+	 * @deprecated No longer used
 	 *
 	 * @return Value for property 'containsJoinFetchedBag'.
 	 */
-	@SuppressWarnings({ "UnusedDeclaration" })
+	@Deprecated(forRemoval = true)
 	public boolean isContainsJoinFetchedBag() {
 		return containsJoinFetchedBag;
 	}

hibernate-core/src/main/java/org/hibernate/internal/FetchProfileHelper.java

@@ -61,7 +61,7 @@ public class FetchProfileHelper {
 			}
 
 			// then register the association with the FetchProfile
-			fetchProfile.addFetch( association, fetchStyle );
+			fetchProfile.addFetch( new Fetch( association, fetchStyle ) );
 		}
 		return fetchProfile;
 	}