slightly improve some Javadoc on metamodel-related stuff

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

@@ -16,8 +16,6 @@ import javax.naming.Referenceable;
 
 import org.hibernate.boot.spi.SessionFactoryOptions;
 import org.hibernate.engine.spi.FilterDefinition;
-import org.hibernate.metadata.ClassMetadata;
-import org.hibernate.metadata.CollectionMetadata;
 import org.hibernate.stat.Statistics;
 
 import jakarta.persistence.EntityGraph;

hibernate-core/src/main/java/org/hibernate/metamodel/MappingMetamodel.java

@@ -27,7 +27,7 @@ import org.hibernate.sql.ast.tree.from.TableGroup;
 import org.hibernate.type.spi.TypeConfiguration;
 
 /**
- * Access to information about the runtime relational O/R mapping model
+ * Access to information about the runtime relational O/R mapping model.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/metamodel/RuntimeMetamodels.java

@@ -14,20 +14,26 @@ import org.hibernate.metamodel.model.domain.JpaMetamodel;
 import org.hibernate.metamodel.model.domain.NavigableRole;
 
 /**
- * Access to Hibernate's runtime metamodels which includes its domain-model (JPA impl) and its
+ * Entry point providing access to the runtime metamodels:
- * relational-mapping model
+ * <ul>
+ * <li>the {@linkplain JpaMetamodel domain model}, our implementation of the
+ *     JPA-defined {@linkplain jakarta.persistence.metamodel.Metamodel model}
+ *     of the Java types, and
+ * <li>our {@linkplain MappingMetamodel relational mapping model} of how these
+ *     types are made persistent.
+ * </ul>
  *
  * @author Steve Ebersole
  */
 @Incubating
 public interface RuntimeMetamodels {
 	/**
-	 * Access to the JPA / domain metamodel
+	 * Access to the JPA / domain metamodel.
 	 */
 	JpaMetamodel getJpaMetamodel();
 
 	/**
-	 * Access to the relational-mapping model
+	 * Access to the relational mapping model.
 	 */
 	MappingMetamodel getMappingMetamodel();
 
@@ -47,7 +53,7 @@ public interface RuntimeMetamodels {
 	}
 
 	/**
-		@deprecated Use {@link #getEmbedded(NavigableRole)} instead
+	 * @deprecated Use {@link #getEmbedded(NavigableRole)} instead
 	 */
 	@Deprecated
 	EmbeddableValuedModelPart getEmbedded(String role);

hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/JpaMetamodel.java

@@ -13,6 +13,7 @@ import jakarta.persistence.metamodel.EmbeddableType;
 import jakarta.persistence.metamodel.EntityType;
 import jakarta.persistence.metamodel.ManagedType;
 
+import jakarta.persistence.metamodel.Metamodel;
 import org.hibernate.Incubating;
 import org.hibernate.graph.spi.RootGraphImplementor;
 import org.hibernate.jpa.spi.JpaCompliance;
@@ -21,7 +22,8 @@ import org.hibernate.service.ServiceRegistry;
 import org.hibernate.type.spi.TypeConfiguration;
 
 /**
- * Hibernate extension to the JPA {@link jakarta.persistence.metamodel.Metamodel} contract
+ * Extensions to the JPA-defined {@linkplain Metamodel metamodel} of
+ * persistent Java types.
  *
  * @see MappingMetamodel
  *
@@ -29,7 +31,7 @@ import org.hibernate.type.spi.TypeConfiguration;
  * @author Steve Ebersole
  */
 @Incubating
-public interface JpaMetamodel extends jakarta.persistence.metamodel.Metamodel {
+public interface JpaMetamodel extends Metamodel {
 
 	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 	// Context

hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/MappingMetamodelImpl.java

@@ -85,12 +85,10 @@ import static org.hibernate.metamodel.internal.JpaMetaModelPopulationSetting.det
 import static org.hibernate.metamodel.internal.JpaStaticMetaModelPopulationSetting.determineJpaStaticMetaModelPopulationSetting;
 
 /**
- * Hibernate implementation of the JPA {@link jakarta.persistence.metamodel.Metamodel} contract.
+ * Implementation of the JPA-defined contract {@link jakarta.persistence.metamodel.Metamodel}.
- *
+ * <p>
- * Really more of the mapping model then the domain model, though it does have reference to the `JpaMetamodel`
+ * Really more of the {@linkplain MappingMetamodel mapping model} than the domain model, though
- *
+ * it does have reference to the {@link org.hibernate.metamodel.model.domain.JpaMetamodel}.
- * NOTE : we suppress deprecation warnings because at the moment we still implement a deprecated API so
- * have to reference deprecated things
  *
  * @author Steve Ebersole
  * @author Emmanuel Bernard
@@ -100,6 +98,9 @@ public class MappingMetamodelImpl implements MappingMetamodelImplementor, Metamo
 	// todo : Integrate EntityManagerLogger into CoreMessageLogger
 	private static final EntityManagerMessageLogger log = HEMLogging.messageLogger( MappingMetamodelImpl.class );
 
+	//NOTE: we suppress deprecation warnings because at the moment we
+	//implement a deprecated API so have to override deprecated things
+
 	private static final String[] EMPTY_IMPLEMENTORS = ArrayHelper.EMPTY_STRING_ARRAY;
 
 	private final SessionFactoryImplementor sessionFactory;
@@ -384,7 +385,7 @@ public class MappingMetamodelImpl implements MappingMetamodelImplementor, Metamo
 		representationStrategy.visitEntityNameResolvers( entityNameResolvers::add );
 	}
 
-	@Override
+	@Override @SuppressWarnings("deprecation")
 	public java.util.Collection<EntityNameResolver> getEntityNameResolvers() {
 		return entityNameResolvers;
 	}
@@ -578,12 +579,12 @@ public class MappingMetamodelImpl implements MappingMetamodelImplementor, Metamo
 		}
 	}
 
-	@Override
+	@Override @SuppressWarnings("deprecation")
 	public Map<String, EntityPersister> entityPersisters() {
 		return entityPersisterMap;
 	}
 
-	@Override
+	@Override @SuppressWarnings("deprecation")
 	public CollectionPersister collectionPersister(String role) {
 		final CollectionPersister persister = collectionPersisterMap.get( role );
 		if ( persister == null ) {
@@ -592,17 +593,17 @@ public class MappingMetamodelImpl implements MappingMetamodelImplementor, Metamo
 		return persister;
 	}
 
-	@Override
+	@Override @SuppressWarnings("deprecation")
 	public Map<String, CollectionPersister> collectionPersisters() {
 		return collectionPersisterMap;
 	}
 
-	@Override
+	@Override @SuppressWarnings("deprecation")
 	public EntityPersister entityPersister(Class<?> entityClass) {
 		return getEntityDescriptor( entityClass.getName() );
 	}
 
-	@Override
+	@Override @SuppressWarnings("deprecation")
 	public EntityPersister entityPersister(String entityName) throws MappingException {
 		EntityPersister result = entityPersisterMap.get( entityName );
 		if ( result == null ) {
@@ -660,7 +661,7 @@ public class MappingMetamodelImpl implements MappingMetamodelImplementor, Metamo
 		return collectionPersisterMap.get( role );
 	}
 
-	@Override
+	@Override @SuppressWarnings("deprecation")
 	public Set<String> getCollectionRolesByEntityParticipant(String entityName) {
 		return collectionRolesByEntityParticipant.get( entityName );
 	}

hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/spi/JpaMetamodelImplementor.java

@@ -9,7 +9,7 @@ package org.hibernate.metamodel.model.domain.spi;
 import org.hibernate.metamodel.model.domain.JpaMetamodel;
 
 /**
- * SPI extension of JpaMetamodel
+ * SPI extending {@link JpaMetamodel}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/metamodel/spi/MetamodelImplementor.java

@@ -19,12 +19,13 @@ import org.hibernate.persister.collection.CollectionPersister;
 import org.hibernate.persister.entity.EntityPersister;
 
 /**
- * Hibernate extension to the JPA {@link Metamodel} contract
+ * Extensions to the JPA-defined {@link Metamodel} contract.
  *
  * @author Steve Ebersole
  *
- * @deprecated - Use {@link MappingMetamodel} or {@link org.hibernate.metamodel.model.domain.JpaMetamodel}
+ * @deprecated Use {@link MappingMetamodel} or
- * instead.  See {@link org.hibernate.metamodel.RuntimeMetamodels}
+ *             {@link org.hibernate.metamodel.model.domain.JpaMetamodel}
+ *             instead. See {@link org.hibernate.metamodel.RuntimeMetamodels}.
  */
 @Deprecated(since = "6.0")
 public interface MetamodelImplementor extends MappingMetamodel, Metamodel {

hibernate-core/src/main/java/org/hibernate/metamodel/spi/RuntimeMetamodelsImplementor.java

@@ -10,6 +10,8 @@ import org.hibernate.metamodel.RuntimeMetamodels;
 import org.hibernate.metamodel.model.domain.spi.JpaMetamodelImplementor;
 
 /**
+ * SPI extending {@link RuntimeMetamodels}.
+ *
  * @author Steve Ebersole
  */
 public interface RuntimeMetamodelsImplementor extends RuntimeMetamodels {

hibernate-core/src/main/java/org/hibernate/persister/entity/EntityPersister.java

@@ -102,14 +102,12 @@ public interface EntityPersister
 		extends EntityMappingType, Loadable, RootTableGroupProducer, AttributeSource {
 
 	/**
-	 * The property name of the "special" identifier property in HQL
+	 * Finish the initialization of this object.
-	 */
+	 * <p>
-	String ENTITY_ID = "id";
+	 * The method {@link InFlightEntityMappingType#prepareMappingModel}
-
+	 * must have been called for every entity persister before this method
-	/**
+	 * is invoked.
-	 * Finish the initialization of this object. {@link InFlightEntityMappingType#prepareMappingModel}
+	 * <p>
-	 * must be called for all entity persisters before calling this method.
-	 * <p/>
 	 * Called only once per {@link org.hibernate.SessionFactory} lifecycle,
 	 * after all entity persisters have been instantiated.
 	 *
@@ -118,9 +116,10 @@ public interface EntityPersister
 	void postInstantiate() throws MappingException;
 
 	/**
-	 * Return the SessionFactory to which this persister "belongs".
+	 * Return the {@link org.hibernate.SessionFactory} to which this persister
+	 * belongs.
 	 *
-	 * @return The owning SessionFactory.
+	 * @return The owning {@code SessionFactory}.
 	 */
 	SessionFactoryImplementor getFactory();
 
@@ -158,13 +157,14 @@ public interface EntityPersister
 	/**
 	 * The strategy to use for SQM mutation statements where the target entity
 	 * has multiple tables. Returns {@code null} to indicate that the entity
-	 * does not define multiple tables
+	 * does not have multiple tables.
 	 */
 	SqmMultiTableMutationStrategy getSqmMultiTableMutationStrategy();
 
 	SqmMultiTableInsertStrategy getSqmMultiTableInsertStrategy();
+
 	/**
-	 * Retrieve the underlying entity metamodel instance...
+	 * Retrieve the underlying entity metamodel instance.
 	 *
 	 *@return The metamodel
 	 */
@@ -173,14 +173,15 @@ public interface EntityPersister
 	/**
 	 * Called from {@link EnhancementAsProxyLazinessInterceptor} to trigger load of
 	 * the entity's non-lazy state as well as the named attribute we are accessing
-	 * if it is still uninitialized after fetching non-lazy state
+	 * if it is still uninitialized after fetching non-lazy state.
 	 */
 	default Object initializeEnhancedEntityUsedAsProxy(
 			Object entity,
 			String nameOfAttributeBeingAccessed,
 			SharedSessionContractImplementor session) {
 		throw new UnsupportedOperationException(
-				"Initialization of entity enhancement used to act like a proxy is not supported by this EntityPersister : " + getClass().getName()
+				"Initialization of entity enhancement used to act like a proxy is not supported by this EntityPersister : "
+						+ getClass().getName()
 		);
 	}
 
@@ -280,8 +281,8 @@ public interface EntityPersister
 	boolean hasSubselectLoadableCollections();
 
 	/**
-	 * Determine whether this entity has any non-{@linkplain org.hibernate.engine.spi.CascadeStyles#NONE none}
+	 * Determine whether this entity has any
-	 * cascading.
+	 * (non-{@linkplain org.hibernate.engine.spi.CascadeStyles#NONE none}) cascading.
 	 *
 	 * @return True if the entity has any properties with a cascade other than NONE;
 	 *         false otherwise (aka, no cascading).
@@ -289,8 +290,8 @@ public interface EntityPersister
 	boolean hasCascades();
 
 	/**
-	 * Determine whether this entity has any {@linkplain org.hibernate.engine.spi.CascadeStyles#DELETE delete}
+	 * Determine whether this entity has any
-	 * cascading.
+	 * {@linkplain org.hibernate.engine.spi.CascadeStyles#DELETE delete cascading}.
 	 *
 	 * @return True if the entity has any properties with a cascade other than NONE;
 	 *         false otherwise.
@@ -407,12 +408,9 @@ public interface EntityPersister
 	 */
 	BasicType<?> getVersionType();
 
+	@SuppressWarnings("unchecked")
 	default VersionJavaType<Object> getVersionJavaType() {
-		final BasicType<?> versionType = getVersionType();
+		return (VersionJavaType<Object>) getVersionType().getJavaTypeDescriptor();
-		//noinspection unchecked
-		return versionType == null
-				? null
-				: (VersionJavaType<Object>) versionType.getJavaTypeDescriptor();
 	}
 
 	/**
@@ -431,11 +429,12 @@ public interface EntityPersister
 	boolean hasNaturalIdentifier();
 
 	/**
-	 * If the entity defines a natural id ({@link #hasNaturalIdentifier()}), which
+	 * If the entity defines a natural id, that is, if
-	 * properties make up the natural id.
+	 * {@link #hasNaturalIdentifier()} returns {@code true}, the indices
+	 * of the properties which make up the natural id.
 	 *
-	 * @return The indices of the properties making of the natural id; or
+	 * @return The indices of the properties making up the natural id;
-	 * null, if no natural id is defined.
+	 *         or null, if no natural id is defined.
 	 */
 	int[] getNaturalIdentifierProperties();
 
@@ -479,8 +478,8 @@ public interface EntityPersister
 	}
 
 	/**
-	 * Determine whether this entity defines any lazy properties (ala
+	 * Determine whether this entity defines any lazy properties (when bytecode
-	 * bytecode instrumentation).
+	 * instrumentation is enabled).
 	 *
 	 * @return True if the entity has properties mapped as lazy; false otherwise.
 	 */
@@ -488,13 +487,15 @@ public interface EntityPersister
 
 	default NaturalIdLoader<?> getNaturalIdLoader() {
 		throw new UnsupportedOperationException(
-				"EntityPersister implementation `" + getClass().getName() + "` does not support `NaturalIdLoader`"
+				"EntityPersister implementation '" + getClass().getName()
+						+ "' does not support 'NaturalIdLoader'"
 		);
 	}
 
 	default MultiNaturalIdLoader<?> getMultiNaturalIdLoader() {
 		throw new UnsupportedOperationException(
-				"EntityPersister implementation `" + getClass().getName() + "` does not support `MultiNaturalIdLoader`"
+				"EntityPersister implementation '" + getClass().getName()
+						+ "' does not support 'MultiNaturalIdLoader'"
 		);
 	}
 
@@ -655,7 +656,8 @@ public interface EntityPersister
 	/**
 	 * Does this class have a cache.
 	 *
-	 * @deprecated Use {@link #canReadFromCache()} and/or {@link #canWriteToCache()} depending on need
+	 * @deprecated Use {@link #canReadFromCache()} and/or {@link #canWriteToCache()}
+	 *             depending on need
 	 */
 	@Deprecated
 	boolean hasCache();
@@ -699,8 +701,9 @@ public interface EntityPersister
 	boolean isSelectBeforeUpdateRequired();
 
 	/**
-	 * Get the current database state of the object, in a "hydrated" form, without
+	 * Get the current database state of the object, in a "hydrated" form,
-	 * resolving identifiers
+	 * without resolving identifiers.
+	 *
 	 * @return null if there is no row in the database
 	 */
 	Object[] getDatabaseSnapshot(Object id, SharedSessionContractImplementor session) throws HibernateException;
@@ -708,9 +711,9 @@ public interface EntityPersister
 	Object getIdByUniqueKey(Object key, String uniquePropertyName, SharedSessionContractImplementor session);
 
 	/**
-	 * Get the current version of the object, or return null if there is no row for
+	 * Get the current version of the object, or return null if there is no
-	 * the given identifier. In the case of unversioned data, return any object
+	 * row for the given identifier. In the case of unversioned data, return
-	 * if the row exists.
+	 * any object if the row exists.
 	 */
 	Object getCurrentVersion(Object id, SharedSessionContractImplementor session) throws HibernateException;
 
@@ -811,7 +814,7 @@ public interface EntityPersister
 	Class<?> getMappedClass();
 
 	/**
-	 * Does the class implement the {@link org.hibernate.classic.Lifecycle} interface.
+	 * Does the class implement the {@link org.hibernate.classic.Lifecycle} interface?
 	 */
 	boolean implementsLifecycle();
 
@@ -826,7 +829,7 @@ public interface EntityPersister
 	}
 
 	/**
-	 * Set the given values to the mapped properties of the given object
+	 * Set the given values to the mapped properties of the given object.
 	 *
 	 * @deprecated Use {@link #setValues} instead
 	 */
@@ -838,7 +841,7 @@ public interface EntityPersister
 	}
 
 	/**
-	 * Set the value of a particular property
+	 * Set the value of a particular property of the given instance.
 	 *
 	 * @deprecated Use {@link #setValue} instead
 	 */
@@ -871,7 +874,8 @@ public interface EntityPersister
 	Object getPropertyValue(Object object, String propertyName);
 
 	/**
-	 * Get the identifier of an instance (throw an exception if no identifier property)
+	 * Get the identifier of an instance from the object's identifier property.
+	 * Throw an exception if it has no identifier property.
 	 */
 	Object getIdentifier(Object entity, SharedSessionContractImplementor session);
 
@@ -881,7 +885,8 @@ public interface EntityPersister
 	void setIdentifier(Object entity, Object id, SharedSessionContractImplementor session);
 
 	/**
-	 * Get the version number (or timestamp) from the object's version property (or return null if not versioned)
+	 * Get the version number (or timestamp) from the object's version property.
+	 * Return {@code null} if it is not versioned.
 	 */
 	Object getVersion(Object object) throws HibernateException;
 
@@ -906,29 +911,39 @@ public interface EntityPersister
 	boolean hasUninitializedLazyProperties(Object object);
 
 	/**
-	 * Set the identifier and version of the given instance back to its "unsaved" value.
+	 * Set the identifier and version of the given instance back to its "unsaved"
+	 * value, that is, the value it had before it was made persistent.
 	 */
 	void resetIdentifier(Object entity, Object currentId, Object currentVersion, SharedSessionContractImplementor session);
 
 	/**
-	 * A request has already identified the entity-name of this persister as the mapping for the given instance.
+	 * Obtain the {@code EntityPersister} for the concrete class of the given
-	 * However, we still need to account for possible subclassing and potentially re-route to the more appropriate
+	 * entity instance which participates in a mapped inheritance hierarchy
+	 * with this persister. The given instance must be an instance of a subclass
+	 * of the persistent class managed by this persister.
+	 * <p>
+	 * A request has already identified the entity name of this persister as the
+	 * mapping for the given instance. However, we still need to account for
+	 * possible subclassing and potentially reroute to the more appropriate
 	 * persister.
-	 * <p/>
+	 * <p>
-	 * For example, a request names {@code Animal} as the entity-name which gets resolved to this persister.  But the
+	 * For example, a request names {@code Animal} as the entity name which gets
-	 * actual instance is really an instance of {@code Cat} which is a subclass of {@code Animal}.  So, here the
+	 * resolved to this persister.  But the actual instance is really an instance
-	 * {@code Animal} persister is being asked to return the persister specific to {@code Cat}.
+	 * of {@code Cat} which is a subclass of {@code Animal}. So, here the
-	 * <p/>
+	 * {@code Animal} persister is being asked to return the persister specific
-	 * It is also possible that the instance is actually an {@code Animal} instance in the above example in which
+	 * to {@code Cat}.
-	 * case we would return {@code this} from this method.
+	 * <p>
+	 * It's also possible that the instance is actually an {@code Animal} instance
+	 * in the above example in which case we would return {@code this} from this
+	 * method.
 	 *
 	 * @param instance The entity instance
 	 * @param factory Reference to the SessionFactory
 	 *
 	 * @return The appropriate persister
 	 *
-	 * @throws HibernateException Indicates that instance was deemed to not be a subclass of the entity mapped by
+	 * @throws HibernateException Indicates that instance was deemed to not be a
-	 * this persister.
+	 *                            subclass of the entity mapped by this persister.
 	 */
 	EntityPersister getSubclassEntityPersister(Object instance, SessionFactoryImplementor factory);
 
@@ -977,4 +992,13 @@ public interface EntityPersister
 	}
 
 	boolean canUseReferenceCacheEntries();
+
+	/**
+	 * The property name of the "special" identifier property in HQL
+	 *
+	 * @deprecated this feature of HQL is now deprecated
+	 */
+	@Deprecated(since = "6.2")
+	String ENTITY_ID = "id";
+
 }