Javadoc improvements for naming strategies and Any mappings

hibernate-core/src/main/java/org/hibernate/annotations/Any.java

@@ -9,7 +9,6 @@ package org.hibernate.annotations;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import jakarta.persistence.Column;
 import jakarta.persistence.FetchType;
 
 import static java.lang.annotation.ElementType.FIELD;
@@ -17,29 +16,46 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Maps a discriminated to-one style association pointing to one of several entity types
+ * Maps a to-one cardinality association taking values over several entity types which
- * depending on a local discriminator, as opposed to discriminated inheritance where the
+ * are <em>not</em> related by the usual entity inheritance, using a discriminator
- * discriminator is kept as part of the entity hierarchy (see {@link jakarta.persistence.Inheritance}
+ * value stored on the <em>referring</em> side of the relationship.
- * and {@link jakarta.persistence.InheritanceType#SINGLE_TABLE} for details about discriminated
+ * <p>
- * inheritance mappings).
+ * This is quite different to
- * <p/>
+ * {@linkplain jakarta.persistence.InheritanceType#SINGLE_TABLE discriminated inheritance}
- * For example, if you consider an {@code Order} entity containing {@code Payment} information
+ * where the discriminator is stored along with the referenced entity hierarchy.
- * where {@code Payment} might be of type {@code CashPayment} or {@code CreditCardPayment},
+ * <p>
- * the {@code @Any} approach would be to keep that discriminator and matching value on the
+ * For example, consider an {@code Order} entity containing {@code Payment} information,
- * {@code Order} itself instead as part of the {@code Payment} class. Thought of another way,
+ * where a {@code Payment} might be a {@code CashPayment} or a {@code CreditCardPayment}.
- * the "foreign key" is really made up of the value and discriminator.  Note however that this
+ * An {@code @Any} mapping would store the discriminator value identifying the concrete
- * composite foreign-key is a conceptual and cannot be physical.
+ * type of {@code Payment} along with the state of the associated {@code Order}, instead
+ * of storing it with the {@code Payment} entity itself.
+ * <p>
+ * In this example, {@code Payment} would <em>not</em> be declared as an entity type, and
+ * would not be annotated {@link jakarta.persistence.Entity @Entity}. It might even be an
+ * interface, or at most just a {@linkplain jakarta.persistence.MappedSuperclass mapped
+ * superclass}, of {@code CashPayment} and {@code CreditCardPayment}. So in terms of the
+ * object/relational mappings, {@code CashPayment} and {@code CreditCardPayment} would
+ * <em>not</em> be considered to participate in the same entity inheritance hierarchy.
+ * <p>
+ * It's reasonable to think of the "foreign key" in an {@code Any} mapping is really a
+ * composite value made up of the foreign key and discriminator taken together. Note,
+ * however, that this composite foreign key is only conceptual and cannot be declared
+ * as a physical constraint on the relational database table.
  * <ul>
- *     <li>Use {@link Column} or {@link Formula} to define the "column" to which the
+ *     <li>{@link AnyDiscriminator}, {@link JdbcType}, or {@link JdbcTypeCode} specifies
- *         discriminator is mapped.
+ *         the type of the discriminator.
- *     <li>Use {@link jakarta.persistence.JoinColumn} to describe the key column
+ *     <li>{@link AnyDiscriminatorValues} specifies how discriminator values map to entity
- *     <li>Use {@link AnyDiscriminator}, {@link JdbcType} or {@link JdbcTypeCode} to
+ *         types.
- *         describe the mapping for the discriminator
+ *     <li>{@link jakarta.persistence.Column} or {@link Formula} specifies the column or
- *     <li>Use {@link AnyKeyJavaType}, {@link AnyKeyJavaClass}, {@link AnyKeyJdbcType}
+ *         formula in which the discriminator value is stored.
- *         or {@link AnyKeyJdbcTypeCode} to describe the mapping for the key
+ *     <li>{@link AnyKeyJavaType}, {@link AnyKeyJavaClass}, {@link AnyKeyJdbcType}, or
- *     <li>Use {@link AnyDiscriminatorValues} to specify how discriminator values map
+ *         or {@link AnyKeyJdbcTypeCode} specifies the type of the foreign key.
- *         to entity types
+ *     <li>{@link jakarta.persistence.JoinColumn} specifies the foreign key column.
  * </ul>
+ * Of course, {@code Any} mappings are disfavored, except in extremely special cases,
+ * since it's much more difficult to enforce referential integrity at the database
+ * level.
+ *
  * @see ManyToAny
  */
 @Target({METHOD, FIELD})

hibernate-core/src/main/java/org/hibernate/annotations/AnyDiscriminator.java

@@ -18,11 +18,11 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  * Simplified form for describing the discriminator value mapping as a discrete
- * set.  Follows the pattern of JPA's {@link DiscriminatorColumn#discriminatorType()}.
+ * set. Follows the pattern of JPA's {@link DiscriminatorColumn#discriminatorType()}.
  * <p/>
  * Can be used in conjunction with {@link JdbcType} or {@link JdbcTypeCode} to
- * further describe the underlying mapping.  {@link JdbcType} or {@link JdbcTypeCode}
+ * further describe the underlying mapping. {@link JdbcType} or {@link JdbcTypeCode}
- * can also be used without AnyDiscriminator.
+ * can also be used without {@code AnyDiscriminator}.
  *
  * @see Any
  *

hibernate-core/src/main/java/org/hibernate/annotations/AnyDiscriminatorValue.java

@@ -15,8 +15,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Specifies the mapping for a single any-valued discriminator value
+ * Specifies the mapping of a single {@linkplain Any any}-valued
- * to the corresponding entity
+ * discriminator value to its corresponding entity type.
  *
  * @see Any
  * @see AnyDiscriminator

hibernate-core/src/main/java/org/hibernate/annotations/AnyDiscriminatorValues.java

@@ -14,7 +14,7 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Grouping of AnyDiscriminatorValue
+ * List of {@link AnyDiscriminatorValue}s.
  *
  * @since 6.0
  */

hibernate-core/src/main/java/org/hibernate/annotations/AnyKeyJavaClass.java

@@ -17,7 +17,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Specifies the Java Class to use for the foreign-key handling related to an ANY mapping.
+ * Specifies the Java class to use for the foreign key handling
+ * related to an {@link Any} mapping.
  *
  * The specified class is resolved to a {@link BasicJavaType}
  * via the {@link JavaTypeRegistry}

hibernate-core/src/main/java/org/hibernate/annotations/AnyKeyJdbcType.java

@@ -16,7 +16,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Form of {@link org.hibernate.annotations.JdbcType} used to describe the foreign-key part of an ANY mapping.
+ * Form of {@link org.hibernate.annotations.JdbcType} used to
+ * describe the foreign key part of an {@link Any} mapping.
  *
  * @see Any
  * @see AnyKeyJdbcTypeCode

hibernate-core/src/main/java/org/hibernate/annotations/AnyKeyJdbcTypeCode.java

@@ -14,7 +14,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Form of {@link JdbcTypeCode} used to describe the foreign-key part of an ANY mapping.
+ * Form of {@link JdbcTypeCode} used to describe the foreign key
+ * part of an {@link Any} mapping.
  *
  * @see Any
  * @see AnyKeyJdbcType

hibernate-core/src/main/java/org/hibernate/annotations/ManyToAny.java

@@ -14,9 +14,15 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Declares a many-valued association targeting one of several entity types,
+ * Maps a to-many cardinality association taking values over several
- * depending on a local discriminator column. This is the collection-valued
+ * entity types which are <em>not</em> related by the usual entity
- * form of {@link Any}.
+ * inheritance, using a discriminator value stored in an
+ * {@linkplain jakarta.persistence.JoinTable association table}.
+ * <p>
+ * This is just the many-valued form of {@link Any}, and the
+ * mapping options are similar, except that the
+ * {@link jakarta.persistence.JoinTable @JoinTable} annotation is
+ * used to specify the association table.
  *
  * @see Any
  *

hibernate-core/src/main/java/org/hibernate/annotations/TenantId.java

@@ -20,6 +20,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * Identifies a field of an entity that holds a tenant id
  * in discriminator-based multitenancy.
  *
+ * @see org.hibernate.context.spi.CurrentTenantIdentifierResolver
+ *
  * @author Gavin King
  */
 @ValueGenerationType(generatedBy = TenantIdGeneration.class)

hibernate-core/src/main/java/org/hibernate/boot/MetadataBuilder.java

@@ -66,12 +66,12 @@ public interface MetadataBuilder {
 	MetadataBuilder applyImplicitSchemaName(String implicitSchemaName);
 
 	/**
-	 * Specify the ImplicitNamingStrategy to use in building the Metadata.
+	 * Specify the {@link ImplicitNamingStrategy}.
 	 * <p/>
 	 * Its default is defined by the {@value org.hibernate.cfg.AvailableSettings#IMPLICIT_NAMING_STRATEGY}
 	 * setting if using property-based configuration.
 	 *
-	 * @param namingStrategy The ImplicitNamingStrategy to apply
+	 * @param namingStrategy The {@link ImplicitNamingStrategy}
 	 *
 	 * @return {@code this}, for method chaining
 	 *
@@ -80,12 +80,12 @@ public interface MetadataBuilder {
 	MetadataBuilder applyImplicitNamingStrategy(ImplicitNamingStrategy namingStrategy);
 
 	/**
-	 * Specify the PhysicalNamingStrategy to use in building the Metadata.
+	 * Specify the {@link PhysicalNamingStrategy}.
 	 * <p/>
 	 * Its default is defined by the {@value org.hibernate.cfg.AvailableSettings#PHYSICAL_NAMING_STRATEGY}
 	 * setting if using property-based configuration.
 	 *
-	 * @param namingStrategy The PhysicalNamingStrategy to apply
+	 * @param namingStrategy The {@link PhysicalNamingStrategy}
 	 *
 	 * @return {@code this}, for method chaining
 	 *
@@ -94,8 +94,7 @@ public interface MetadataBuilder {
 	MetadataBuilder applyPhysicalNamingStrategy(PhysicalNamingStrategy namingStrategy);
 
 	/**
-	 * Specify the second-level cache mode to be used.  This is the cache mode in terms of whether or
+	 * Specify the second-level cache mode.
-	 * not to cache.
 	 * <p/>
 	 * Its default is defined by the {@code javax.persistence.sharedCache.mode} setting if using
 	 * property-based configuration.

hibernate-core/src/main/java/org/hibernate/boot/internal/MetadataBuilderImpl.java

@@ -73,8 +73,6 @@ import org.hibernate.metamodel.CollectionClassification;
 import org.hibernate.query.sqm.function.SqmFunctionDescriptor;
 import org.hibernate.service.ServiceRegistry;
 import org.hibernate.type.BasicType;
-import org.hibernate.type.descriptor.java.JavaType;
-import org.hibernate.type.descriptor.jdbc.JdbcType;
 import org.hibernate.type.spi.TypeConfiguration;
 import org.hibernate.usertype.UserType;
 

hibernate-core/src/main/java/org/hibernate/boot/model/naming/ImplicitNamingStrategy.java

@@ -9,46 +9,44 @@ package org.hibernate.boot.model.naming;
 import org.hibernate.Incubating;
 
 /**
- * Pluggable strategy for applying implicit naming rules when an
+ * A set of rules for determining the {@linkplain PhysicalNamingStrategy logical name}
- * explicit name is not given.
+ * of a mapped relational database object when the mapping for an element of the Java
- * <p/>
+ * domain model is not explicitly specified, neither in annotations of the Java code,
- * NOTE: the method names here mostly favor the JPA naming (aka, secondary table rather than join)
+ * nor in an XML-based mapping document.
- * <p/>
+ * <p>
- * Methods fall into 2 main categories:<ul>
+ * For example, if a Java class annotated {@link jakarta.persistence.Entity @Entity}
- *     <li>
+ * has no {@link jakarta.persistence.Table @Table} annotation, then
- *         Table naming<ul>
+ * {@link #determinePrimaryTableName(ImplicitEntityNameSource) determinePrimaryTableName}
- *             <li>
+ * is called with an {@link ImplicitEntityNameSource} providing access to information
- *                 Entity primary table - {@link #determinePrimaryTableName}.  Used when the
+ * about the Java class and its {@link jakarta.persistence.Entity#name() entity name}.
- *                 primary table for an entity is not explicitly named in the metadata.  See
+ * <p>
- *                 {@link jakarta.persistence.Table} for details.
+ * On the other hand, when a logical name <em>is</em> explicitly specified, for example,
- *             </li>
+ * using {@link jakarta.persistence.Table#name() @Table} to specify the table name,
- *             <li>
+ * or {@link jakarta.persistence.Column#name() @Column} to specify a column name, the
- *                 Join table - {@link #determineJoinTableName}.  See {@link jakarta.persistence.JoinTable}
+ * {@code PhysicalNamingStrategy} is not called and has no opportunity to intervene in
- *                 for details.  Join table covers basically any entity association whether in the form
+ * the determination of the logical name.
- *                 of a collection of entities (one-to-many, many-to-many) or a singular entity association
+ * <p>
- *                 (many-to-one, and occasionally one-to-one).
+ * However, a further level of processing is applied to the resulting logical names by
- *             </li>
+ * a {@link PhysicalNamingStrategy} in order to determine the "finally final" physical
- *             <li>
+ * names in the relational database schema.
- *                 Collection table - {@link #determineCollectionTableName} - Collection table
+ * <p>
- *                 refers to any non-entity collection (basic, component/embeddable, any).  See
+ * Whenever reasonable, the use of a custom {@code ImplicitNamingStrategy} is highly
- *                 {@link jakarta.persistence.CollectionTable} for details.
+ * recommended in preference to tedious and repetitive explicit table and column name
- *             </li>
+ * mappings. It's anticipated that most projects using Hibernate will feature a custom
- *             <li>
+ * implementation of {@code ImplicitNamingStrategy}.
- *                 <i>Notice that secondary tables are not mentioned, since they must always be explicitly named</i>
+ * <p>
- *             </li>
+ * An {@code ImplicitNamingStrategy} may be selected using the configuration property
- *         </ul>
+ * {@value org.hibernate.cfg.AvailableSettings#IMPLICIT_NAMING_STRATEGY}.
- *     </li>
- *     <li>
- *         Column naming<ul>
  *
- *         </ul>
+ * @see PhysicalNamingStrategy
- *     </li>
- * </ul>
  *
  * @author Steve Ebersole
  */
 @Incubating
 public interface ImplicitNamingStrategy {
+	// NOTE: the method names here mostly favor the JPA terminology
+	// (for example, "secondary table" rather than "join")
+
 	/**
 	 * Determine the implicit name of an entity's primary table.
 	 *
@@ -60,7 +58,9 @@ public interface ImplicitNamingStrategy {
 
 	/**
 	 * Determine the name of an association join table given the source naming
-	 * information, when a name is not explicitly given.
+	 * information, when a name is not explicitly given. This method is called
+	 * for any sort of association with a join table, no matter what the logical
+	 * cardinality.
 	 *
 	 * @param source The source information
 	 *
@@ -70,7 +70,9 @@ public interface ImplicitNamingStrategy {
 
 	/**
 	 * Determine the name of a collection join table given the source naming
-	 * information, when a name is not explicitly given.
+	 * information, when a name is not explicitly given. This method is called
+	 * only for {@linkplain jakarta.persistence.ElementCollection collections of
+	 * basic or embeddable values}, and never for associations.
 	 *
 	 * @param source The source information
 	 *
@@ -80,7 +82,9 @@ public interface ImplicitNamingStrategy {
 
 
 	/**
-	 * Determine the implicit name for the discriminator column for the given entity
+	 * Determine the {@linkplain jakarta.persistence.DiscriminatorValue discriminator}
+	 * column name for the given entity when it is not explicitly specified using
+	 * {@link jakarta.persistence.DiscriminatorColumn#name()}.
 	 *
 	 * @param source The source information
 	 *
@@ -89,7 +93,9 @@ public interface ImplicitNamingStrategy {
 	Identifier determineDiscriminatorColumnName(ImplicitDiscriminatorColumnNameSource source);
 
 	/**
-	 * Determine the implicit name for the tenant (multi-tenancy) identifier column for the given entity
+	 * Determine the implicit name of the {@linkplain org.hibernate.annotations.TenantId
+	 * tenant identifier} column belonging to a given entity when it is not explicitly
+	 * specified using {@link jakarta.persistence.Column#name()}.
 	 *
 	 * @param source The source information
 	 *
@@ -98,7 +104,9 @@ public interface ImplicitNamingStrategy {
 	Identifier determineTenantIdColumnName(ImplicitTenantIdColumnNameSource source);
 
 	/**
-	 * Determine the implicit name for the identifier column for the given entity
+	 * Determine the name if the {@linkplain jakarta.persistence.Id identifier} column
+	 * belonging to the given entity when it is not explicitly specified using
+	 * {@link jakarta.persistence.Column#name()}.
 	 *
 	 * @param source The source information
 	 *
@@ -107,8 +115,8 @@ public interface ImplicitNamingStrategy {
 	Identifier determineIdentifierColumnName(ImplicitIdentifierColumnNameSource source);
 
 	/**
-	 * Determine the name of an attribute's column given the source naming
+	 * Determine the column name when it is not explicitly specified using
-	 * information, when a name is not explicitly given.
+	 * {@link jakarta.persistence.Column#name()}.
 	 *
 	 * @param source The source information
 	 *
@@ -117,9 +125,11 @@ public interface ImplicitNamingStrategy {
 	Identifier determineBasicColumnName(ImplicitBasicColumnNameSource source);
 
 	/**
-	 * Determine the column name related to {@link jakarta.persistence.JoinColumn}.  In
+	 * Determine the join column name when it is not explicitly specified using
-	 * {@code hbm.xml} terms, this would be a {@code <key/>} defined for a collection
+	 * {@link jakarta.persistence.JoinColumn#name()}.
-	 * or the column associated with a many-to-one.
+	 * <p>
+	 * In {@code hbm.xml} terms, this would be a {@code <key/>} defined for a
+	 * collection or the column associated with a many-to-one.
 	 *
 	 * @param source The source information
 	 *
@@ -128,9 +138,11 @@ public interface ImplicitNamingStrategy {
 	Identifier determineJoinColumnName(ImplicitJoinColumnNameSource source);
 
 	/**
-	 * Determine the column name related to {@link jakarta.persistence.PrimaryKeyJoinColumn}.  In
+	 * Determine the primary key join column name when it is not explicitly specified
-	 * {@code hbm.xml} terms, this would be a {@code <key/>} defined for a {@code <join/>}
+	 * using {@link jakarta.persistence.PrimaryKeyJoinColumn#name()}.
-	 * or a {@code <joined-subclass/>} (others?)
+	 * <p>
+	 * In {@code hbm.xml} terms, this would be a {@code <key/>} defined for a
+	 * {@code <join/>} or a {@code <joined-subclass/>}.
 	 *
 	 * @param source The source information
 	 *
@@ -139,8 +151,9 @@ public interface ImplicitNamingStrategy {
 	Identifier determinePrimaryKeyJoinColumnName(ImplicitPrimaryKeyJoinColumnNameSource source);
 
 	/**
-	 * Determine the column name related to the discriminator portion of an ANY mapping when
+	 * Determine the column name related to the discriminator portion of an
-	 * no explicit column name is given.
+	 * {@link org.hibernate.annotations.Any} mapping when no explicit column
+	 * name is given using {@link jakarta.persistence.Column#name()}.
 	 *
 	 * @param source The source information
 	 *
@@ -149,8 +162,9 @@ public interface ImplicitNamingStrategy {
 	Identifier determineAnyDiscriminatorColumnName(ImplicitAnyDiscriminatorColumnNameSource source);
 
 	/**
-	 * Determine the column name related to the key/id portion of an ANY mapping when
+	 * Determine the join column name related to the key/id portion of an
-	 * no explicit column name is given.
+	 * {@link org.hibernate.annotations.Any} mapping when no explicit join column
+	 * name is given using {@link jakarta.persistence.JoinColumn#name()}.
 	 *
 	 * @param source The source information
 	 *
@@ -158,13 +172,53 @@ public interface ImplicitNamingStrategy {
 	 */
 	Identifier determineAnyKeyColumnName(ImplicitAnyKeyColumnNameSource source);
 
+	/**
+	 * Determine the map key column name when it is not explicitly specified using
+	 * {@link jakarta.persistence.MapKeyColumn#name()}.
+	 *
+	 * @param source The source information
+	 *
+	 * @return The implicit column name.
+	 */
 	Identifier determineMapKeyColumnName(ImplicitMapKeyColumnNameSource source);
 
+	/**
+	 * Determine the list index column name when it is not explicitly specified using
+	 * {@link jakarta.persistence.OrderColumn#name()}.
+	 *
+	 * @param source The source information
+	 *
+	 * @return The implicit column name.
+	 */
 	Identifier determineListIndexColumnName(ImplicitIndexColumnNameSource source);
 
+	/**
+	 * Determine the foreign key name when it is not explicitly specified using
+	 * {@link jakarta.persistence.ForeignKey#name()}.
+	 *
+	 * @param source The source information
+	 *
+	 * @return The determined foreign key name
+	 */
 	Identifier determineForeignKeyName(ImplicitForeignKeyNameSource source);
 
+	/**
+	 * Determine the unique key name when it is not explicitly specified using
+	 * {@link jakarta.persistence.UniqueConstraint#name()}.
+	 *
+	 * @param source The source information
+	 *
+	 * @return The determined foreign key name
+	 */
 	Identifier determineUniqueKeyName(ImplicitUniqueKeyNameSource source);
 
+	/**
+	 * Determine the index name when it is not explicitly specified using
+	 * {@link jakarta.persistence.Index#name()}.
+	 *
+	 * @param source The source information
+	 *
+	 * @return The determined foreign key name
+	 */
 	Identifier determineIndexName(ImplicitIndexNameSource source);
 }

hibernate-core/src/main/java/org/hibernate/boot/model/naming/ImplicitNamingStrategyJpaCompliantImpl.java

@@ -14,8 +14,8 @@ import org.hibernate.boot.spi.MetadataBuildingContext;
 import org.hibernate.internal.util.StringHelper;
 
 /**
- * Implementation of the ImplicitNamingStrategy contract, generally preferring to conform
+ * Implementation of the {@link ImplicitNamingStrategy} contract, generally
- * to JPA standards.
+ * preferring to conform to JPA standards.
  * <p/>
  * For the legacy JPA-based naming standards initially implemented by Hibernate,
  * see/use {@link ImplicitNamingStrategyLegacyJpaImpl}

hibernate-core/src/main/java/org/hibernate/boot/model/naming/PhysicalNamingStrategy.java

@@ -10,37 +10,56 @@ import org.hibernate.Incubating;
 import org.hibernate.engine.jdbc.env.spi.JdbcEnvironment;
 
 /**
- * Pluggable strategy contract for applying physical naming rules for database object names.
+ * A set of rules for determining the physical names of objects in a relational
+ * database schema from the logical names specified by the object/relational
+ * mappings.
+ * <ul>
+ *     <li>A <em>physical name</em> is a name used to interact with the database,
+ *     and will always be used in generated SQL, both DML and DDL.
+ *     <li>A <em>logical name</em> is a name used to within annotations of Java
+ *     code and XML mapping documents.
+ * </ul>
+ * Logical names provide an additional level of indirection between the mappings
+ * and the database schema, and a {@code PhysicalNamingStrategy} even allows the
+ * use of more "natural" naming within the mappings in cases where the relational
+ * schema features especially inelegant legacy naming conventions. For example,
+ * it could shield the mappings from old-fashioned practices like prefixing table
+ * names with {@code TBL_}.
+ * <p>
+ * Note, however, that handwritten native SQL must be written in terms of physical
+ * names, so the abstraction here is in some sense "incomplete".
  * <p>
  * A {@code PhysicalNamingStrategy} may be selected using the configuration property
  * {@value org.hibernate.cfg.AvailableSettings#PHYSICAL_NAMING_STRATEGY}.
  *
+ * @see ImplicitNamingStrategy
+ *
  * @author Steve Ebersole
  */
 @Incubating
 public interface PhysicalNamingStrategy {
 	/**
-	 * Determine the appropriate physical catalog name to use for the  given logical name
+	 * Determine the physical catalog name from the given logical name
 	 */
 	Identifier toPhysicalCatalogName(Identifier logicalName, JdbcEnvironment jdbcEnvironment);
 
 	/**
-	 * Determine the appropriate physical schema name to use for the given logical name
+	 * Determine the physical schema name from the given logical name
 	 */
 	Identifier toPhysicalSchemaName(Identifier logicalName, JdbcEnvironment jdbcEnvironment);
 
 	/**
-	 * Determine the appropriate physical table name to use for the given logical name
+	 * Determine the physical table name from the given logical name
 	 */
 	Identifier toPhysicalTableName(Identifier logicalName, JdbcEnvironment jdbcEnvironment);
 
 	/**
-	 * Determine the appropriate physical sequence name to use for the given logical name
+	 * Determine the physical sequence name from the given logical name
 	 */
 	Identifier toPhysicalSequenceName(Identifier logicalName, JdbcEnvironment jdbcEnvironment);
 
 	/**
-	 * Determine the appropriate physical column name to use for the given logical name
+	 * Determine the physical column name from the given logical name
 	 */
 	Identifier toPhysicalColumnName(Identifier logicalName, JdbcEnvironment jdbcEnvironment);
 }

hibernate-core/src/main/java/org/hibernate/boot/model/naming/PhysicalNamingStrategyStandardImpl.java

@@ -11,7 +11,8 @@ import java.io.Serializable;
 import org.hibernate.engine.jdbc.env.spi.JdbcEnvironment;
 
 /**
- * Standard implementation of the PhysicalNamingStrategy contract.
+ * Standard implementation of the {@link PhysicalNamingStrategy} contract. This is a trivial implementation
+ * where each physical name is taken to be exactly identical to the corresponding logical name.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java

@@ -748,9 +748,7 @@ public interface AvailableSettings {
 	 * Used to specify the {@link org.hibernate.boot.model.naming.ImplicitNamingStrategy}
 	 * class to use. The following shortcut names are defined for this setting:
 	 * <ul>
-	 *     <li>{@code "default"} is an abbreviation for
+	 *     <li>{@code "default"} and {@code "jpa"} are an abbreviations for
-	 *     {@link org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl}
-	 *     <li>{@code "jpa"} is an abbreviation for
 	 *     {@link org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl}
 	 *     <li>{@code "legacy-jpa"} is an abbreviation for
 	 *     {@link org.hibernate.boot.model.naming.ImplicitNamingStrategyLegacyJpaImpl}
@@ -759,9 +757,9 @@ public interface AvailableSettings {
 	 *     <li>{@code "component-path"} is an abbreviation for
 	 *     {@link org.hibernate.boot.model.naming.ImplicitNamingStrategyComponentPathImpl}
 	 * </ul>
-	 * The default is defined by the {@code ImplicitNamingStrategy} registered under the
+	 * By default, the {@code ImplicitNamingStrategy} registered under the key
-	 * {@code "default"} key. If that happens to be empty, the fallback is to use
+	 * {@code "default"} is used. If no strategy is explicitly registered under that key,
-	 * {@link org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl}.
+	 * {@link org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl} is used.
 	 *
 	 * @see org.hibernate.boot.MetadataBuilder#applyImplicitNamingStrategy
 	 *
@@ -771,6 +769,9 @@ public interface AvailableSettings {
 
 	/**
 	 * Specifies the {@link org.hibernate.boot.model.naming.PhysicalNamingStrategy} to use.
+	 * <p>
+	 * By default, {@link org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl}
+	 * is used, in which case physical names are taken to be identical to logical names.
 	 *
 	 * @see org.hibernate.boot.MetadataBuilder#applyPhysicalNamingStrategy
 	 *
@@ -779,13 +780,13 @@ public interface AvailableSettings {
 	String PHYSICAL_NAMING_STRATEGY = "hibernate.physical_naming_strategy";
 
 	/**
-	 * An implicit naming-strategy for database structures (tables, sequences) related
+	 * An implicit naming strategy for database structures (tables, sequences) related
-	 * to identifier-generators
+	 * to identifier generators.
-	 *
+	 * <p>
 	 * Resolution uses the {@link org.hibernate.boot.registry.selector.spi.StrategySelector}
 	 * service and accepts any of the forms discussed on
-	 * {@link StrategySelector#resolveDefaultableStrategy}.
+	 * {@link StrategySelector#resolveDefaultableStrategy(Class, Object, java.util.concurrent.Callable)}.
-	 *
+	 * <p>
 	 * The recognized short names being:<ul>
 	 *     <li>{@value org.hibernate.id.enhanced.SingleNamingStrategy#STRATEGY_NAME}</li>
 	 *     <li>{@value org.hibernate.id.enhanced.LegacyNamingStrategy#STRATEGY_NAME}</li>

hibernate-core/src/main/java/org/hibernate/context/spi/CurrentTenantIdentifierResolver.java

@@ -11,6 +11,8 @@ package org.hibernate.context.spi;
  * for resolving the current tenant identifier for use with {@link CurrentSessionContext}
  * and {@link org.hibernate.SessionFactory#getCurrentSession()}.
  *
+ * @see org.hibernate.annotations.TenantId
+ *
  * @author Steve Ebersole
  */
 public interface CurrentTenantIdentifierResolver {