diff --git a/hibernate-core/src/main/java/org/hibernate/boot/MetadataBuilder.java b/hibernate-core/src/main/java/org/hibernate/boot/MetadataBuilder.java index 49ded502b6..635567e7ad 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/MetadataBuilder.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/MetadataBuilder.java @@ -234,7 +234,8 @@ public interface MetadataBuilder { * Again the premise here is JPA portability, bearing in mind that some * JPA provider need these discriminators. *

- * Its default is defined by the {@value org.hibernate.cfg.AvailableSettings#IMPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS} + * Its default is defined by the + * {@value org.hibernate.cfg.AvailableSettings#IMPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS} * setting if using property-based configuration. * * @param enabled Should we implicitly create discriminator for joined @@ -309,7 +310,8 @@ public interface MetadataBuilder { MetadataBuilder applyBasicType(UserType type, String... keys); /** - * Apply an explicit TypeContributor (implicit application via ServiceLoader will still happen too) + * Apply an explicit {@link TypeContributor} + * (implicit application via {@link java.util.ServiceLoader} will still happen too) * * @param typeContributor The contributor to apply * @@ -318,8 +320,8 @@ public interface MetadataBuilder { MetadataBuilder applyTypes(TypeContributor typeContributor); /** - * Apply a CacheRegionDefinition to be applied to an entity, collection or query while building the - * Metadata object. + * Apply a {@link CacheRegionDefinition} to be applied to an entity, collection, + * or query while building the {@link Metadata} object. * * @param cacheRegionDefinition The cache region definition to apply * @@ -328,26 +330,30 @@ public interface MetadataBuilder { MetadataBuilder applyCacheRegionDefinition(CacheRegionDefinition cacheRegionDefinition); /** - * Apply a ClassLoader for use while building the Metadata. + * Apply a {@link ClassLoader} for use while building the {@link Metadata}. *

- * Ideally we should avoid accessing ClassLoaders when perform 1st phase of bootstrap. This - * is a ClassLoader that can be used in cases when we have to. IN EE managed environments, this - * is the ClassLoader mandated by - * {@link jakarta.persistence.spi.PersistenceUnitInfo#getNewTempClassLoader()}. This ClassLoader - * is thrown away by the container afterwards. The idea being that the Class can still be enhanced - * in the application ClassLoader. In other environments, pass a ClassLoader that performs the - * same function if desired. + * Ideally we should avoid accessing {@code ClassLoader}s when perform 1st phase of bootstrap. + * This is a {@code ClassLoader} that can be used in cases where we absolutely must. + *

+ * In EE managed environments, this is the {@code ClassLoader} mandated by + * {@link jakarta.persistence.spi.PersistenceUnitInfo#getNewTempClassLoader()}. + * This {@code ClassLoader} is discarded by the container afterward, the idea being that the + * {@link Class} can still be enhanced in the application {@code ClassLoader}. + *

+ * In other environments, pass a {@code ClassLoader} that performs the same function, if desired. * - * @param tempClassLoader ClassLoader for use during building the Metadata + * @param tempClassLoader {@code ClassLoader} for use while building the {@code Metadata} * * @return {@code this}, for method chaining */ MetadataBuilder applyTempClassLoader(ClassLoader tempClassLoader); /** - * Apply a specific ordering to the processing of sources. Note that unlike most - * of the methods on this contract that deal with multiple values internally, this - * one *replaces* any already set (its more a setter) instead of adding to. + * Apply a specific ordering to the processing of sources. + *

+ * Unlike most of the methods of this interface (which deal with multiple + * values internally), this one replaces any source processing + * order that was already set. *

* Its default is defined by the {@value org.hibernate.cfg.AvailableSettings#ARTIFACT_PROCESSING_ORDER} * setting if using property-based configuration. @@ -395,7 +401,8 @@ public interface MetadataBuilder { MetadataBuilder applyAttributeConverter(Class> attributeConverterClass); /** - * Adds an AttributeConverter by its Class plus a boolean indicating whether to auto apply it. + * Adds an {@link AttributeConverter} by {@code Class}, + * explicitly indicating whether to auto-apply it. * * @param attributeConverterClass The AttributeConverter class. * @param autoApply Should the AttributeConverter be auto applied to property types as specified @@ -415,7 +422,8 @@ public interface MetadataBuilder { MetadataBuilder applyAttributeConverter(AttributeConverter attributeConverter); /** - * Adds an AttributeConverter instance, explicitly indicating whether to auto-apply. + * Adds an {@link AttributeConverter} instance, + * explicitly indicating whether to auto-apply it. * * @param attributeConverter The AttributeConverter instance. * @param autoApply Should the AttributeConverter be auto applied to property types as specified diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/Caching.java b/hibernate-core/src/main/java/org/hibernate/boot/model/Caching.java index 61e8d32557..d8321bf662 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/model/Caching.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/model/Caching.java @@ -11,7 +11,7 @@ import org.hibernate.cache.spi.access.AccessType; import org.hibernate.internal.util.StringHelper; /** - * Models the caching options for an entity, natural-id or collection. + * Models the caching options for an entity, natural id, or collection. * * @author Steve Ebersole * @author Hardy Ferentschik diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/FunctionContributions.java b/hibernate-core/src/main/java/org/hibernate/boot/model/FunctionContributions.java index ef186148ac..4aa869aad1 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/model/FunctionContributions.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/model/FunctionContributions.java @@ -12,7 +12,11 @@ import org.hibernate.service.ServiceRegistry; import org.hibernate.type.spi.TypeConfiguration; /** - * Defines the target contributing functions, whether via dialects or {@link FunctionContributor} + * Allows custom function descriptors to be contributed to the eventual + * {@link SqmFunctionRegistry}, either by a {@link org.hibernate.dialect.Dialect} + * or by a {@link FunctionContributor}. + * + * @see FunctionContributor * * @author Christian Beikov */ diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/FunctionContributor.java b/hibernate-core/src/main/java/org/hibernate/boot/model/FunctionContributor.java index 91059af292..c228e05d42 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/model/FunctionContributor.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/model/FunctionContributor.java @@ -14,12 +14,15 @@ package org.hibernate.boot.model; -import org.hibernate.query.sqm.function.SqmFunctionRegistry; - /** - * Contract for contributing functions + * On object that contributes custom types and type descriptors, eventually + * to a {@link org.hibernate.query.sqm.function.SqmFunctionRegistry}, via an + * instance of {@link FunctionContributions}. + *

+ * The most common way to integrate a {@code FunctionContributor} is by making + * it discoverable via the Java {@link java.util.ServiceLoader} facility. * - * @see SqmFunctionRegistry + * @see org.hibernate.query.sqm.function.SqmFunctionRegistry * * @author Karel Maesen */ diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/TypeContributions.java b/hibernate-core/src/main/java/org/hibernate/boot/model/TypeContributions.java index 06e18c7256..dc7e961076 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/model/TypeContributions.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/model/TypeContributions.java @@ -17,7 +17,11 @@ import org.hibernate.type.spi.TypeConfiguration; import org.hibernate.usertype.UserType; /** - * Defines the target contributing types, whether via dialects or {@link TypeContributor} + * Allows custom types and type descriptors to be contributed to the eventual + * {@link TypeConfiguration}, either by a {@link org.hibernate.dialect.Dialect} + * or by a {@link TypeContributor}. + * + * @see TypeContributor * * @author Steve Ebersole */ @@ -25,31 +29,31 @@ public interface TypeContributions { TypeConfiguration getTypeConfiguration(); /** - * Add the JavaType to the {@link TypeConfiguration}'s - * {@link JavaTypeRegistry} + * Add the given {@link JavaType} to the {@link JavaTypeRegistry} + * of the eventual {@link TypeConfiguration}. */ default void contributeJavaType(JavaType descriptor) { getTypeConfiguration().getJavaTypeRegistry().addDescriptor( descriptor ); } /** - * Add the JdbcType to the {@link TypeConfiguration}'s - * {@link JdbcTypeRegistry} + * Add the given {@link JdbcType} to the {@link JdbcTypeRegistry} + * of the eventual {@link TypeConfiguration}. */ default void contributeJdbcType(JdbcType descriptor) { getTypeConfiguration().getJdbcTypeRegistry().addDescriptor( descriptor ); } /** - * Registers a UserType as the implicit (auto-applied) type - * for values of type {@link UserType#returnedClass()} + * Register a {@link UserType} as the implicit (auto-applied) + * type for values of type {@link UserType#returnedClass()} */ default void contributeType(UserType type) { contributeType( type, type.returnedClass().getName() ); } /** - * @deprecated See user-guide section `2.2.46. TypeContributor` for details - `basic_types.adoc` + * @deprecated See discussion of {@code TypeContributor} in User Guide. */ @Deprecated(since = "6.0") default void contributeType(BasicType type) { diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/TypeContributor.java b/hibernate-core/src/main/java/org/hibernate/boot/model/TypeContributor.java index 5f3b399dfb..5124923377 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/model/TypeContributor.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/model/TypeContributor.java @@ -9,9 +9,20 @@ package org.hibernate.boot.model; import org.hibernate.service.ServiceRegistry; /** - * Contract for contributing types. + * On object that contributes custom types and type descriptors, eventually + * to a {@link org.hibernate.type.spi.TypeConfiguration}, via an instance + * of {@link TypeContributions}. + *

+ * The most common way to integrate a {@code TypeContributor} is by making + * it discoverable via the Java {@link java.util.ServiceLoader} facility. + *

+ * Alternatively, a {@code TypeContributor} may be supplied to + * {@link org.hibernate.cfg.Configuration#registerTypeContributor(TypeContributor)} + * or even {@link org.hibernate.boot.MetadataBuilder#applyTypes(TypeContributor)}. * * @author Steve Ebersole + * + * @see org.hibernate.type.spi.TypeConfiguration */ public interface TypeContributor { /** diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/TypeDefinition.java b/hibernate-core/src/main/java/org/hibernate/boot/model/TypeDefinition.java index c48d70aa09..d37a08e1cb 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/model/TypeDefinition.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/model/TypeDefinition.java @@ -44,12 +44,13 @@ import org.hibernate.usertype.UserType; import static org.hibernate.mapping.MappingHelper.injectParameters; /** - * Models the information pertaining to a custom type definition supplied by the user. Used - * to delay instantiation of the actual {@link Type} instance. - * + * Models the information pertaining to a custom type definition supplied by the user. + * Used to delay instantiation of the actual {@link Type} instance. + *

* Generally speaking this information would come from annotations - * ({@link org.hibernate.annotations.Type}) or XML mappings. An alternative form of - * supplying custom types is programmatically via one of: