slightly improve some Javadoc on metamodel-related stuff

This commit is contained in:
Gavin King 2022-10-29 10:09:06 +02:00
parent f253d8f216
commit 257bfdb391
9 changed files with 118 additions and 84 deletions

View File

@ -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;

View File

@ -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
*/

View File

@ -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:
* <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);

View File

@ -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

View File

@ -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}.
* <p>
* 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<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 );
}

View File

@ -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
*/

View File

@ -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 {

View File

@ -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 {

View File

@ -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.
* <p/>
* Finish the initialization of this object.
* <p>
* The method {@link InFlightEntityMappingType#prepareMappingModel}
* must have been called for every entity persister before this method
* is invoked.
* <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();
@ -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<Object> getVersionJavaType() {
final BasicType<?> versionType = getVersionType();
//noinspection unchecked
return versionType == null
? null
: (VersionJavaType<Object>) versionType.getJavaTypeDescriptor();
return (VersionJavaType<Object>) 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.
* <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/>
* 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}.
* <p/>
* 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.
* <p>
* 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}.
* <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
* 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";
}