From 257bfdb3914b25f66ce8a66cc8263e899b5846f9 Mon Sep 17 00:00:00 2001 From: Gavin King Date: Sat, 29 Oct 2022 10:09:06 +0200 Subject: [PATCH] slightly improve some Javadoc on metamodel-related stuff --- .../java/org/hibernate/SessionFactory.java | 2 - .../hibernate/metamodel/MappingMetamodel.java | 2 +- .../metamodel/RuntimeMetamodels.java | 16 +- .../metamodel/model/domain/JpaMetamodel.java | 6 +- .../domain/internal/MappingMetamodelImpl.java | 27 ++-- .../domain/spi/JpaMetamodelImplementor.java | 2 +- .../metamodel/spi/MetamodelImplementor.java | 7 +- .../spi/RuntimeMetamodelsImplementor.java | 2 + .../persister/entity/EntityPersister.java | 138 ++++++++++-------- 9 files changed, 118 insertions(+), 84 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/SessionFactory.java b/hibernate-core/src/main/java/org/hibernate/SessionFactory.java index b1b7676fdd..6c4e545fea 100644 --- a/hibernate-core/src/main/java/org/hibernate/SessionFactory.java +++ b/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; diff --git a/hibernate-core/src/main/java/org/hibernate/metamodel/MappingMetamodel.java b/hibernate-core/src/main/java/org/hibernate/metamodel/MappingMetamodel.java index 47ecbfaf42..bfd4251a28 100644 --- a/hibernate-core/src/main/java/org/hibernate/metamodel/MappingMetamodel.java +++ b/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 */ diff --git a/hibernate-core/src/main/java/org/hibernate/metamodel/RuntimeMetamodels.java b/hibernate-core/src/main/java/org/hibernate/metamodel/RuntimeMetamodels.java index 01c45d6126..c0e519ba27 100644 --- a/hibernate-core/src/main/java/org/hibernate/metamodel/RuntimeMetamodels.java +++ b/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 - * relational-mapping model + * Entry point providing access to the runtime metamodels: + * * * @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); diff --git a/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/JpaMetamodel.java b/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/JpaMetamodel.java index e8ab2a329d..87b41369ae 100644 --- a/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/JpaMetamodel.java +++ b/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 diff --git a/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/MappingMetamodelImpl.java b/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/MappingMetamodelImpl.java index d7eebf8c76..4bf7587007 100644 --- a/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/MappingMetamodelImpl.java +++ b/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. - * - * Really more of the mapping model then the domain model, though it does have reference to the `JpaMetamodel` - * - * NOTE : we suppress deprecation warnings because at the moment we still implement a deprecated API so - * have to reference deprecated things + * Implementation of the JPA-defined contract {@link jakarta.persistence.metamodel.Metamodel}. + *

+ * 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}. * * @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 getEntityNameResolvers() { return entityNameResolvers; } @@ -578,12 +579,12 @@ public class MappingMetamodelImpl implements MappingMetamodelImplementor, Metamo } } - @Override + @Override @SuppressWarnings("deprecation") public Map 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 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 getCollectionRolesByEntityParticipant(String entityName) { return collectionRolesByEntityParticipant.get( entityName ); } diff --git a/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/spi/JpaMetamodelImplementor.java b/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/spi/JpaMetamodelImplementor.java index 1f3490b058..c9eb087e37 100644 --- a/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/spi/JpaMetamodelImplementor.java +++ b/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 */ diff --git a/hibernate-core/src/main/java/org/hibernate/metamodel/spi/MetamodelImplementor.java b/hibernate-core/src/main/java/org/hibernate/metamodel/spi/MetamodelImplementor.java index 0bededf4c6..d7bf193d36 100644 --- a/hibernate-core/src/main/java/org/hibernate/metamodel/spi/MetamodelImplementor.java +++ b/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} - * instead. See {@link org.hibernate.metamodel.RuntimeMetamodels} + * @deprecated Use {@link MappingMetamodel} or + * {@link org.hibernate.metamodel.model.domain.JpaMetamodel} + * instead. See {@link org.hibernate.metamodel.RuntimeMetamodels}. */ @Deprecated(since = "6.0") public interface MetamodelImplementor extends MappingMetamodel, Metamodel { diff --git a/hibernate-core/src/main/java/org/hibernate/metamodel/spi/RuntimeMetamodelsImplementor.java b/hibernate-core/src/main/java/org/hibernate/metamodel/spi/RuntimeMetamodelsImplementor.java index 48446facab..551ad75440 100644 --- a/hibernate-core/src/main/java/org/hibernate/metamodel/spi/RuntimeMetamodelsImplementor.java +++ b/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 { diff --git a/hibernate-core/src/main/java/org/hibernate/persister/entity/EntityPersister.java b/hibernate-core/src/main/java/org/hibernate/persister/entity/EntityPersister.java index 9ef66c033d..b30db8bf87 100644 --- a/hibernate-core/src/main/java/org/hibernate/persister/entity/EntityPersister.java +++ b/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 - */ - String ENTITY_ID = "id"; - - /** - * Finish the initialization of this object. {@link InFlightEntityMappingType#prepareMappingModel} - * must be called for all entity persisters before calling this method. - *

+ * Finish the initialization of this object. + *

+ * The method {@link InFlightEntityMappingType#prepareMappingModel} + * must have been called for every entity persister before this method + * is invoked. + *

* 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(); @@ -157,14 +156,15 @@ 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 + * has multiple tables. Returns {@code null} to indicate that the entity + * 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,20 +281,20 @@ public interface EntityPersister boolean hasSubselectLoadableCollections(); /** - * Determine whether this entity has any non-{@linkplain org.hibernate.engine.spi.CascadeStyles#NONE none} - * cascading. + * Determine whether this entity has any + * (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). + * false otherwise (aka, no cascading). */ boolean hasCascades(); /** - * Determine whether this entity has any {@linkplain org.hibernate.engine.spi.CascadeStyles#DELETE delete} - * cascading. + * Determine whether this entity has any + * {@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. + * false otherwise. */ default boolean hasCascadeDelete() { //bad default implementation for compatibility @@ -407,12 +408,9 @@ public interface EntityPersister */ BasicType getVersionType(); + @SuppressWarnings("unchecked") default VersionJavaType getVersionJavaType() { - final BasicType versionType = getVersionType(); - //noinspection unchecked - return versionType == null - ? null - : (VersionJavaType) versionType.getJavaTypeDescriptor(); + return (VersionJavaType) getVersionType().getJavaTypeDescriptor(); } /** @@ -431,11 +429,12 @@ public interface EntityPersister boolean hasNaturalIdentifier(); /** - * If the entity defines a natural id ({@link #hasNaturalIdentifier()}), which - * properties make up the natural id. + * If the entity defines a natural id, that is, if + * {@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 - * null, if no natural id is defined. + * @return The indices of the properties making up the natural id; + * 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 - * bytecode instrumentation). + * Determine whether this entity defines any lazy properties (when bytecode + * 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 - * resolving identifiers + * Get the current database state of the object, in a "hydrated" form, + * 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 - * the given identifier. In the case of unversioned data, return any object - * if the row exists. + * Get the current version of the object, or return null if there is no + * row for the given identifier. In the case of unversioned data, return + * 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. - * However, we still need to account for possible subclassing and potentially re-route to the more appropriate + * Obtain the {@code EntityPersister} for the concrete class of the given + * 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. + *

+ * 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. - *

- * For example, a request names {@code Animal} as the entity-name which gets resolved to this persister. But the - * actual instance is really an instance of {@code Cat} which is a subclass of {@code Animal}. So, here the - * {@code Animal} persister is being asked to return the persister specific to {@code Cat}. - *

- * It is 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. + *

+ * For example, a request names {@code Animal} as the entity name which gets + * resolved to this persister. But the actual instance is really an instance + * of {@code Cat} which is a subclass of {@code Animal}. So, here the + * {@code Animal} persister is being asked to return the persister specific + * to {@code Cat}. + *

+ * 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 - * this persister. + * @throws HibernateException Indicates that instance was deemed to not be a + * 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"; + }