From 60884a4c3a9b7f47c42a9f77063406d74a44ddd1 Mon Sep 17 00:00:00 2001 From: Gavin Date: Wed, 28 Dec 2022 12:39:25 +0100 Subject: [PATCH] get rid of "NOTE :" which looks terrible in compiled javadoc - use @implNot / @apiNot instead --- .../java/org/hibernate/QueryException.java | 6 +-- .../org/hibernate/SessionFactoryObserver.java | 8 ++-- .../internal/AbstractEntityInsertAction.java | 5 ++- .../internal/BulkOperationCleanupAction.java | 4 +- .../hibernate/annotations/UuidGenerator.java | 8 ++-- .../org/hibernate/boot/MetadataBuilder.java | 6 +-- .../internal/ExplodedArchiveDescriptor.java | 2 +- .../JarFileBasedArchiveDescriptor.java | 2 +- .../JarInputStreamBasedArchiveDescriptor.java | 5 ++- .../beanvalidation/ActivationContext.java | 7 ++-- .../jaxb/hbm/internal/FlushModeConverter.java | 10 ++--- .../marshall/FlushModeMarshalling.java | 8 ++-- .../hibernate/boot/model/TypeContributor.java | 3 -- .../model/naming/ImplicitNamingStrategy.java | 5 ++- .../source/spi/EntityHierarchySource.java | 2 +- .../model/source/spi/ToolingHintContext.java | 10 ++--- .../classloading/spi/ClassLoaderService.java | 6 +-- .../org/hibernate/cfg/AvailableSettings.java | 6 ++- .../java/org/hibernate/dialect/Dialect.java | 38 +++++++++---------- .../pagination/AbstractLimitHandler.java | 16 ++++---- .../dialect/unique/UniqueDelegate.java | 2 +- .../internal/StatefulPersistenceContext.java | 10 ++--- .../java/org/hibernate/engine/jdbc/Size.java | 8 ++-- .../DriverManagerConnectionProviderImpl.java | 4 +- .../jdbc/internal/JdbcCoordinatorImpl.java | 4 +- .../engine/jdbc/spi/SqlExceptionHelper.java | 4 +- .../spi/AbstractParameterDescriptor.java | 2 +- .../org/hibernate/engine/spi/ActionQueue.java | 4 +- .../org/hibernate/engine/spi/EntityKey.java | 8 ++-- ...lkInsertionCapableIdentifierGenerator.java | 5 +-- .../hibernate/id/EntityIdentifierNature.java | 18 +++++---- .../hibernate/id/enhanced/TableGenerator.java | 26 +++++++------ .../id/uuid/CustomVersionOneStrategy.java | 6 +-- .../hibernate/integrator/spi/Integrator.java | 10 +++-- .../hibernate/internal/util/BytesHelper.java | 6 +-- .../metamodel/mapping/ValueMapping.java | 9 ++--- .../internal/EmbeddableMappingTypeImpl.java | 4 +- .../domain/AbstractIdentifiableType.java | 4 +- .../metamodel/spi/EmbeddableInstantiator.java | 8 ++-- .../hibernate/persister/entity/Loadable.java | 6 +-- .../hibernate/procedure/ProcedureCall.java | 12 +++--- .../internal/PropertyAccessBasicImpl.java | 2 +- .../PropertyAccessCompositeUserTypeImpl.java | 2 +- .../internal/PropertyAccessEmbeddedImpl.java | 10 ++--- .../internal/PropertyAccessEnhancedImpl.java | 3 +- .../internal/PropertyAccessMapImpl.java | 4 +- .../internal/PropertyAccessMixedImpl.java | 2 +- .../PropertyAccessStrategyNoopImpl.java | 2 - .../org/hibernate/query/SelectionQuery.java | 18 ++++----- .../criteria/HibernateCriteriaBuilder.java | 20 +++++----- .../query/procedure/ProcedureParameter.java | 2 +- .../hibernate/query/results/package-info.java | 10 ++--- .../query/sqm/UnknownEntityException.java | 6 +-- .../FunctionArgumentTypeResolver.java | 2 +- .../function/FunctionReturnTypeResolver.java | 4 +- .../java/org/hibernate/service/Service.java | 2 +- .../hibernate/service/ServiceRegistry.java | 8 ++-- .../org/hibernate/sql/ast/SqlTreePrinter.java | 2 +- .../sql/exec/spi/StatementCreatorHelper.java | 4 +- .../AbstractInformationExtractorImpl.java | 4 +- .../extract/spi/InformationExtractor.java | 2 +- .../type/descriptor/JdbcTypeNameMapper.java | 2 +- 62 files changed, 212 insertions(+), 216 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/QueryException.java b/hibernate-core/src/main/java/org/hibernate/QueryException.java index d927aa9c4d..9200537e3d 100644 --- a/hibernate-core/src/main/java/org/hibernate/QueryException.java +++ b/hibernate-core/src/main/java/org/hibernate/QueryException.java @@ -111,9 +111,9 @@ public class QueryException extends HibernateException { /** * Called from {@link #wrapWithQueryString(String)} when we really need to * generate a new {@code QueryException} (or subclass). - *

- * NOTE : implementors should take care to use {@link #getOriginalMessage()} - * for the message, not {@link #getMessage()} + * + * @implNote implementors should take care to use {@link #getOriginalMessage()} + * for the message, not {@link #getMessage()} * * @param queryString The query string * diff --git a/hibernate-core/src/main/java/org/hibernate/SessionFactoryObserver.java b/hibernate-core/src/main/java/org/hibernate/SessionFactoryObserver.java index 9fb0c75971..a3cebcce02 100644 --- a/hibernate-core/src/main/java/org/hibernate/SessionFactoryObserver.java +++ b/hibernate-core/src/main/java/org/hibernate/SessionFactoryObserver.java @@ -32,10 +32,10 @@ public interface SessionFactoryObserver extends Serializable { /** * Callback to indicate that the given factory is about to close. The passed factory * reference should be usable since it is only about to close. - *

- * NOTE : defined as default to allow for existing SessionFactoryObserver impls to work - * in 5.2. Starting in 6.0 the default will be removed and SessionFactoryObserver impls - * will be required to implement this new method. + * + * @apiNote defined as default to allow for existing {@code SessionFactoryObserver} + * implementations to work in 5.2. Starting in 6.0 the default will be + * removed and implementations will be required to implement this new method. * * @param factory The factory about to be closed. * diff --git a/hibernate-core/src/main/java/org/hibernate/action/internal/AbstractEntityInsertAction.java b/hibernate-core/src/main/java/org/hibernate/action/internal/AbstractEntityInsertAction.java index 219277727e..db39fec3ae 100644 --- a/hibernate-core/src/main/java/org/hibernate/action/internal/AbstractEntityInsertAction.java +++ b/hibernate-core/src/main/java/org/hibernate/action/internal/AbstractEntityInsertAction.java @@ -67,9 +67,10 @@ public abstract class AbstractEntityInsertAction extends EntityAction { /** * Returns the entity state. + *

+ * Note that the call to {@link #nullifyTransientReferencesIfNotAlready} + * can modify the entity state. * - * NOTE: calling {@link #nullifyTransientReferencesIfNotAlready} can modify the - * entity state. * @return the entity state. * * @see #nullifyTransientReferencesIfNotAlready diff --git a/hibernate-core/src/main/java/org/hibernate/action/internal/BulkOperationCleanupAction.java b/hibernate-core/src/main/java/org/hibernate/action/internal/BulkOperationCleanupAction.java index 02cfa035c6..7f4c085dbd 100644 --- a/hibernate-core/src/main/java/org/hibernate/action/internal/BulkOperationCleanupAction.java +++ b/hibernate-core/src/main/java/org/hibernate/action/internal/BulkOperationCleanupAction.java @@ -35,8 +35,8 @@ import org.hibernate.sql.ast.tree.insert.InsertSelectStatement; /** * An {@link org.hibernate.engine.spi.ActionQueue} {@link Executable} for * ensuring shared cache cleanup in relation to performed bulk HQL queries. - *

- * NOTE: currently this executes for {@code INSERT} queries as well as + * + * @implNote Currently this executes for {@code INSERT} queries as well as * {@code UPDATE} and {@code DELETE} queries. For {@code INSERT} it is * really not needed as we'd have no invalid entity/collection data to * clean up (we'd still need to invalidate the appropriate update-timestamps diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/UuidGenerator.java b/hibernate-core/src/main/java/org/hibernate/annotations/UuidGenerator.java index 9eb146db03..b6117cadec 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/UuidGenerator.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/UuidGenerator.java @@ -38,11 +38,11 @@ public @interface UuidGenerator { */ RANDOM, /** - * Applies a time-based generation strategy consistent with IETF RFC 4122. Uses - * IP address rather than mac address. + * Applies a time-based generation strategy consistent with IETF RFC 4122. + * Uses IP address rather than mac address. * - * NOTE : Can be a bottleneck due to the need to synchronize in order to increment an - * internal count as part of the algorithm. + * @implNote Can be a bottleneck due to the need to synchronize in order + * to increment an internal count as part of the algorithm. */ TIME } 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 3db9b9408e..0a99741809 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/MetadataBuilder.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/MetadataBuilder.java @@ -142,10 +142,10 @@ public interface MetadataBuilder { * Allows specifying a specific Jandex index to use for reading annotation information. *

* It is important to understand that if a Jandex index is passed in, it is expected that - * this Jandex index already contains all entries for all classes. No additional indexing will be + * this Jandex index already contains all entries for all classes. No additional indexing will be * done in this case. - *

- * NOTE : Here for future expansion. At the moment the passed Jandex index is not used. + * + * @apiNote Here for future expansion. At the moment the passed Jandex index is not used. * * @param jandexView The Jandex index to use. * diff --git a/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ExplodedArchiveDescriptor.java b/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ExplodedArchiveDescriptor.java index 55814a6829..bfdbd02e14 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ExplodedArchiveDescriptor.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ExplodedArchiveDescriptor.java @@ -24,7 +24,7 @@ import org.hibernate.boot.archive.spi.InputStreamAccess; import static org.hibernate.internal.log.UrlMessageBundle.URL_MESSAGE_LOGGER; /** - * Descriptor for exploded (directory) archives + * An {@code ArchiveDescriptor} for exploded (directory) archives. * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarFileBasedArchiveDescriptor.java b/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarFileBasedArchiveDescriptor.java index 7b014dff8d..f1af430878 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarFileBasedArchiveDescriptor.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarFileBasedArchiveDescriptor.java @@ -27,7 +27,7 @@ import org.hibernate.boot.archive.spi.InputStreamAccess; import static org.hibernate.internal.log.UrlMessageBundle.URL_MESSAGE_LOGGER; /** - * An ArchiveDescriptor implementation leveraging the {@link JarFile} API for processing. + * An {@code ArchiveDescriptor} implementation leveraging the {@link JarFile} API for processing. * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarInputStreamBasedArchiveDescriptor.java b/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarInputStreamBasedArchiveDescriptor.java index 0c5aa54c1b..a0da59880f 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarInputStreamBasedArchiveDescriptor.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarInputStreamBasedArchiveDescriptor.java @@ -22,8 +22,9 @@ import org.hibernate.boot.archive.spi.InputStreamAccess; import static org.hibernate.internal.log.UrlMessageBundle.URL_MESSAGE_LOGGER; /** - * An ArchiveDescriptor implementation that works on archives accessible through a {@link JarInputStream}. - * NOTE : This is less efficient implementation than {@link JarFileBasedArchiveDescriptor} + * An {@code ArchiveDescriptor} that works on archives accessible through a {@link JarInputStream}. + * + * @implNote This is less efficient implementation than {@link JarFileBasedArchiveDescriptor}. * * @author Emmanuel Bernard * @author Steve Ebersole diff --git a/hibernate-core/src/main/java/org/hibernate/boot/beanvalidation/ActivationContext.java b/hibernate-core/src/main/java/org/hibernate/boot/beanvalidation/ActivationContext.java index e263ef4787..da4d625e7c 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/beanvalidation/ActivationContext.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/beanvalidation/ActivationContext.java @@ -20,11 +20,10 @@ import org.hibernate.service.spi.SessionFactoryServiceRegistry; public interface ActivationContext { /** * Access the requested validation mode(s). - *

- * IMPL NOTE : the legacy code allowed multiple mode values to be specified, so that is why it is multi-valued here. + * + * @implNote The legacy code allowed multiple mode values to be specified, so that is why it is multivalued here. * However, I cannot find any good reasoning why it was defined that way and even JPA states it should be a single - * value. For 4.1 (in maintenance) I think it makes the most sense to not mess with it. Discuss for - * 4.2 and beyond. + * value. For 4.1 (in maintenance) I think it makes the most sense to not mess with it. Discuss for 4.2 and beyond. * * @return The requested validation modes */ diff --git a/hibernate-core/src/main/java/org/hibernate/boot/jaxb/hbm/internal/FlushModeConverter.java b/hibernate-core/src/main/java/org/hibernate/boot/jaxb/hbm/internal/FlushModeConverter.java index 23881dbb53..25f94df397 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/jaxb/hbm/internal/FlushModeConverter.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/jaxb/hbm/internal/FlushModeConverter.java @@ -12,11 +12,11 @@ import org.hibernate.FlushMode; import org.hibernate.HibernateException; /** - * JAXB marshalling for the FlushMode enum - *

- * NOTE : The XML schemas define the use of {@code "never"}, which corresponds - * to the removed FlushMode#NEVER. Here we will also handle mapping - * FlushMode#NEVER to FlushMode#MANUAL + * JAXB marshalling for the {@link FlushMode} enum. + * + * @implNote The XML schemas define the use of {@code "never"}, which corresponds + * to the removed {@code FlushMode#NEVER}. Here we will also remap + * {@code FlushMode#NEVER} to {@link FlushMode#MANUAL}. * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/boot/jaxb/mapping/marshall/FlushModeMarshalling.java b/hibernate-core/src/main/java/org/hibernate/boot/jaxb/mapping/marshall/FlushModeMarshalling.java index dedaab648a..3f99522705 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/jaxb/mapping/marshall/FlushModeMarshalling.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/jaxb/mapping/marshall/FlushModeMarshalling.java @@ -13,10 +13,10 @@ import org.hibernate.HibernateException; /** * JAXB marshalling for {@link FlushMode} - *

- * NOTE : The XML schemas define the use of {@code "never"}, which corresponds - * to the removed FlushMode#NEVER. Here we will also handle mapping - * FlushMode#NEVER to FlushMode#MANUAL + * + * @implNote The XML schemas define the use of {@code "never"}, which corresponds + * to the removed {@code FlushMode#NEVER}. Here we will also remap + * {@code FlushMode#NEVER} to {@link FlushMode#MANUAL}. * * @author Steve Ebersole */ 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 5128b6bdfe..5f3b399dfb 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 @@ -12,9 +12,6 @@ import org.hibernate.service.ServiceRegistry; * Contract for contributing types. * * @author Steve Ebersole - * - * NOTE: Cherry-pick of HHH-7998 from metamodel. For merging simplicity, just - * keep it in the o.h.metamodel.spi package. */ public interface TypeContributor { /** diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/naming/ImplicitNamingStrategy.java b/hibernate-core/src/main/java/org/hibernate/boot/model/naming/ImplicitNamingStrategy.java index 44d3a25d22..07b8aeb72e 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/model/naming/ImplicitNamingStrategy.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/model/naming/ImplicitNamingStrategy.java @@ -38,14 +38,15 @@ import org.hibernate.Incubating; * An {@code ImplicitNamingStrategy} may be selected using the configuration property * {@value org.hibernate.cfg.AvailableSettings#IMPLICIT_NAMING_STRATEGY}. * + * @apiNote The method names here mostly favor the JPA terminology, + * for example, "secondary table" rather than "join". + * * @see PhysicalNamingStrategy * * @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. diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/source/spi/EntityHierarchySource.java b/hibernate-core/src/main/java/org/hibernate/boot/model/source/spi/EntityHierarchySource.java index 55a50bf9e7..b0790cf7ba 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/model/source/spi/EntityHierarchySource.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/model/source/spi/EntityHierarchySource.java @@ -25,7 +25,7 @@ public interface EntityHierarchySource { /** * The inheritance type/strategy for the hierarchy. *

- * NOTE : The entire hierarchy must comply with the same inheritance strategy. + * The entire hierarchy must have with the same inheritance strategy. * * @return The inheritance type. */ diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/source/spi/ToolingHintContext.java b/hibernate-core/src/main/java/org/hibernate/boot/model/source/spi/ToolingHintContext.java index 2e08b2a498..ac862c41d4 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/model/source/spi/ToolingHintContext.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/model/source/spi/ToolingHintContext.java @@ -15,11 +15,11 @@ import org.hibernate.mapping.MetaAttribute; /** * Represents a collection of "tooling hints" ({@code } mapping info) keyed by a name. - *

- * NOTE : historically these were called "meta attributes", but as these are values used solely - * by external tooling it was decided to begin calling them tooling hints. For temporary - * backwards compatibility (temporary until we move away from o.h.mapping model) you will - * see mixed usage. + * + * @apiNote Historically, these were called "meta attributes", but as these are values used solely + * by external tooling it was decided to begin calling them tooling hints. For temporary + * backwards compatibility (temporary until we move away from o.h.mapping model) you will + * see mixed usage. * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/boot/registry/classloading/spi/ClassLoaderService.java b/hibernate-core/src/main/java/org/hibernate/boot/registry/classloading/spi/ClassLoaderService.java index 88028fcb35..2b6e9bcaf8 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/registry/classloading/spi/ClassLoaderService.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/registry/classloading/spi/ClassLoaderService.java @@ -88,9 +88,9 @@ public interface ClassLoaderService extends ResourceLocator, ResourceStreamLocat /** * Discovers and instantiates implementations of the named service contract. - *

- * NOTE : the terms service here is used differently than {@link Service}. Instead here we are talking about - * services as defined by {@link java.util.ServiceLoader}. + * + * @apiNote The term "service" here does not refer to a {@link Service}. + * Here it refers to a Java {@link java.util.ServiceLoader}. * * @param serviceContract The java type defining the service contract * @param The type of the service contract diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java index 7e14a80ac4..cf319a5172 100644 --- a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java +++ b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java @@ -2904,8 +2904,9 @@ public interface AvailableSettings { * @see jakarta.persistence.CacheRetrieveMode * * @deprecated Use {@link #JAKARTA_SHARED_CACHE_RETRIEVE_MODE} instead + * + * @apiNote This is not a legal property for an {@code EntityManagerFactory}. */ - //NOTE : Not a valid EMF property @Deprecated @SuppressWarnings("DeprecatedIsStillUsed") String JPA_SHARED_CACHE_RETRIEVE_MODE = "javax.persistence.cache.retrieveMode"; @@ -2917,8 +2918,9 @@ public interface AvailableSettings { * @see jakarta.persistence.CacheStoreMode * * @deprecated Use {@link #JAKARTA_SHARED_CACHE_STORE_MODE} instead + * + * @apiNote This is not a legal property for an {@code EntityManagerFactory}. */ - //NOTE: Not a valid EMF property @Deprecated @SuppressWarnings("DeprecatedIsStillUsed") String JPA_SHARED_CACHE_STORE_MODE = "javax.persistence.cache.storeMode"; diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java index 91cc6e4477..3ee71063c5 100644 --- a/hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java +++ b/hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java @@ -2097,8 +2097,8 @@ public abstract class Dialect implements ConversionContext { /** * For dropping a type, can the phrase "{@code if exists} be * applied before the type name? - *

- * NOTE : Only one or the other (or neither) of this and + * + * @apiNote Only one or the other (or neither) of this and * {@link #supportsIfExistsAfterTypeName} should return true. * * @return {@code true} if {@code if exists} can be applied before the type name @@ -2110,8 +2110,8 @@ public abstract class Dialect implements ConversionContext { /** * For dropping a type, can the phrase {@code if exists} be * applied after the type name? - *

- * NOTE : Only one or the other (or neither) of this and + * + * @apiNote Only one or the other (or neither) of this and * {@link #supportsIfExistsBeforeTypeName} should return true. * * @return {@code true} if {@code if exists} can be applied after the type name @@ -2936,8 +2936,8 @@ public abstract class Dialect implements ConversionContext { /** * For dropping a table, can the phrase "{@code if exists} be * applied before the table name? - *

- * NOTE : Only one or the other (or neither) of this and + * + * @apiNote Only one or the other (or neither) of this and * {@link #supportsIfExistsAfterTableName} should return true. * * @return {@code true} if {@code if exists} can be applied before the table name @@ -2949,8 +2949,8 @@ public abstract class Dialect implements ConversionContext { /** * For dropping a table, can the phrase {@code if exists} be * applied after the table name? - *

- * NOTE : Only one or the other (or neither) of this and + * + * @apiNote Only one or the other (or neither) of this and * {@link #supportsIfExistsBeforeTableName} should return true. * * @return {@code true} if {@code if exists} can be applied after the table name @@ -2963,8 +2963,8 @@ public abstract class Dialect implements ConversionContext { * For dropping a constraint with an {@code alter table} statement, * can the phrase {@code if exists} be applied before the constraint * name? - *

- * NOTE : Only one or the other (or neither) of this and + * + * @apiNote Only one or the other (or neither) of this and * {@link #supportsIfExistsAfterConstraintName} should return true * * @return {@code true} if {@code if exists} can be applied before the constraint name @@ -2976,8 +2976,8 @@ public abstract class Dialect implements ConversionContext { /** * For dropping a constraint with an {@code alter table}, can the phrase * {@code if exists} be applied after the constraint name? - *

- * NOTE : Only one or the other (or neither) of this and + * + * @apiNote Only one or the other (or neither) of this and * {@link #supportsIfExistsBeforeConstraintName} should return true. * * @return {@code true} if {@code if exists} can be applied after the constraint name @@ -3141,8 +3141,8 @@ public abstract class Dialect implements ConversionContext { * {@link ResultSet#isAfterLast} and * {@link ResultSet#isBeforeFirst}. Certain drivers do not * allow access to these methods for forward only cursors. - *

- * NOTE : this is highly driver dependent! + * + * @apiNote This is highly driver dependent! * * @return True if methods like {@link ResultSet#isAfterLast} and * {@link ResultSet#isBeforeFirst} are supported for forward @@ -3215,8 +3215,8 @@ public abstract class Dialect implements ConversionContext { * {@link Clob#setString(long, String)}, * {@link Clob#setString(long, String, int, int)}, * or {@link Clob#truncate(long)}. - *

- * NOTE : I do not know the correct answer currently for + * + * @implNote I do not know the correct answer currently for * databases which (1) are not part of the cruise control process * or (2) do not {@link #supportsExpectedLobUsagePattern}. * @@ -3235,9 +3235,9 @@ public abstract class Dialect implements ConversionContext { *

* Again, part of the trickiness here is the fact that this is largely * driver dependent. - *

- * NOTE: all database I have tested which {@link #supportsExpectedLobUsagePattern()} - * also support the ability to materialize a LOB outside the owning transaction... + * + * @implNote All database I have tested which {@link #supportsExpectedLobUsagePattern()} + * also support the ability to materialize a LOB outside the owning transaction. * * @return True if unbounded materialization is supported; false otherwise. * @since 3.2 diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/pagination/AbstractLimitHandler.java b/hibernate-core/src/main/java/org/hibernate/dialect/pagination/AbstractLimitHandler.java index f032633e3c..6cb9ec0036 100644 --- a/hibernate-core/src/main/java/org/hibernate/dialect/pagination/AbstractLimitHandler.java +++ b/hibernate-core/src/main/java/org/hibernate/dialect/pagination/AbstractLimitHandler.java @@ -116,15 +116,13 @@ public abstract class AbstractLimitHandler implements LimitHandler { } /** - * Hibernate {@link Query#setFirstResult(int)} accepts - * a zero-based offset. Does this dialect require a one-based offset to be - * specified in the offset clause? - *

- * NOTE: what gets passed into - * {@link AbstractLimitHandler#processSql(String, Limit)} - * is the zero-based offset. Handlers which do not {@link #supportsVariableLimit} - * should take care to perform any needed first-row-conversion calls prior - * to injecting the limit values into the SQL string. + * The API method {@link Query#setFirstResult(int)} accepts a zero-based offset. + * Does this dialect require a one-based offset to be specified in the offset clause? + * + * @implNote The value passed into {@link AbstractLimitHandler#processSql(String, Limit)} + * has a zero-based offset. Handlers which do not {@link #supportsVariableLimit} + * should take care to perform any needed first-row-conversion calls prior to + * injecting the limit values into the SQL string. * * @param zeroBasedFirstResult The user-supplied, zero-based first row offset. * diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/unique/UniqueDelegate.java b/hibernate-core/src/main/java/org/hibernate/dialect/unique/UniqueDelegate.java index 0b43899126..aeef884907 100644 --- a/hibernate-core/src/main/java/org/hibernate/dialect/unique/UniqueDelegate.java +++ b/hibernate-core/src/main/java/org/hibernate/dialect/unique/UniqueDelegate.java @@ -76,7 +76,7 @@ public interface UniqueDelegate { * @param table The table for which to generate the unique constraints fragment * @param context A context for SQL string generation * @return The fragment, typically in the form {@code ", unique(col1, col2), unique(col20)"}. - * NOTE: The leading comma is important! + * The leading comma is important! */ String getTableCreationUniqueConstraintsFragment(Table table, SqlStringGenerationContext context); diff --git a/hibernate-core/src/main/java/org/hibernate/engine/internal/StatefulPersistenceContext.java b/hibernate-core/src/main/java/org/hibernate/engine/internal/StatefulPersistenceContext.java index 5f756c60d7..b48e0c4f0a 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/internal/StatefulPersistenceContext.java +++ b/hibernate-core/src/main/java/org/hibernate/engine/internal/StatefulPersistenceContext.java @@ -72,12 +72,12 @@ import static org.hibernate.engine.internal.ManagedTypeHelper.asPersistentAttrib import static org.hibernate.engine.internal.ManagedTypeHelper.isPersistentAttributeInterceptable; /** - * A stateful implementation of the {@link PersistenceContext} contract meaning that we maintain this + * A stateful implementation of the {@link PersistenceContext} contract, meaning that we maintain this * state throughout the life of the persistence context. - *

- * IMPL NOTE: There is meant to be a one-to-one correspondence between a {@link org.hibernate.internal.SessionImpl} - * and a PersistentContext. Event listeners and other Session collaborators then use the PersistentContext to drive - * their processing. + * + * @implNote There is meant to be a one-to-one correspondence between a {@link org.hibernate.internal.SessionImpl} + * and a {@link PersistenceContext}. Event listeners and other session collaborators then use the + * {@code PersistenceContext} to drive their processing. * * @author Steve Ebersole * @author Sanne Grinovero diff --git a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/Size.java b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/Size.java index 626d06f2e7..1603d3c39b 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/Size.java +++ b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/Size.java @@ -12,10 +12,10 @@ import java.io.Serializable; /** * Models size restrictions/requirements on a column's datatype. - *

- * IMPL NOTE: since we do not necessarily know the datatype up front, and therefore do not necessarily know - * whether length or precision/scale sizing is needed, we simply account for both here. Additionally LOB - * definitions, by standard, are allowed a "multiplier" consisting of 'K' (Kb), 'M' (Mb) or 'G' (Gb). + * + * @implNote Since we do not necessarily know the datatype up front, and therefore do not necessarily know + * whether length or precision/scale sizing is needed, we simply account for both here. Additionally, LOB + * sizes, by standard, are allowed a "multiplier", {@code K} (Kb), {@code M} (Mb) or {@code G} (Gb). * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/internal/DriverManagerConnectionProviderImpl.java b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/internal/DriverManagerConnectionProviderImpl.java index d79891bbb2..907bbac14e 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/internal/DriverManagerConnectionProviderImpl.java +++ b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/internal/DriverManagerConnectionProviderImpl.java @@ -44,8 +44,8 @@ import static org.hibernate.internal.log.ConnectionPoolingLogger.CONNECTIONS_MES /** * A connection provider that uses the {@link DriverManager} directly to open connections and provides * a very rudimentary connection pool. - *

- * IMPL NOTE : not intended for production use! + * + * @implNote Not intended for use in production systems! * * @author Gavin King * @author Steve Ebersole diff --git a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/internal/JdbcCoordinatorImpl.java b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/internal/JdbcCoordinatorImpl.java index 24a6917aab..24cbc8cb74 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/internal/JdbcCoordinatorImpl.java +++ b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/internal/JdbcCoordinatorImpl.java @@ -45,9 +45,7 @@ import org.hibernate.resource.jdbc.spi.LogicalConnectionImplementor; import org.hibernate.resource.transaction.backend.jdbc.spi.JdbcResourceTransaction; /** - * Standard Hibernate implementation of {@link JdbcCoordinator} - *

- * IMPL NOTE : Custom serialization handling! + * Standard implementation of {@link JdbcCoordinator}. * * @author Steve Ebersole * @author Brett Meyer diff --git a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/SqlExceptionHelper.java b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/SqlExceptionHelper.java index f6c2dde309..cccd23b162 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/SqlExceptionHelper.java +++ b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/SqlExceptionHelper.java @@ -73,10 +73,8 @@ public class SqlExceptionHelper { /** * Inject the exception converter to use. - *

- * NOTE : {@code null} is allowed and signifies to use the default. * - * @param sqlExceptionConverter The converter to use. + * @param sqlExceptionConverter the converter to use, or {@code null} if the default converter should be used */ public void setSqlExceptionConverter(SQLExceptionConverter sqlExceptionConverter) { this.sqlExceptionConverter = sqlExceptionConverter == null ? DEFAULT_CONVERTER : sqlExceptionConverter; diff --git a/hibernate-core/src/main/java/org/hibernate/engine/query/spi/AbstractParameterDescriptor.java b/hibernate-core/src/main/java/org/hibernate/engine/query/spi/AbstractParameterDescriptor.java index f83a79f1e5..eccd25bb73 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/query/spi/AbstractParameterDescriptor.java +++ b/hibernate-core/src/main/java/org/hibernate/engine/query/spi/AbstractParameterDescriptor.java @@ -13,7 +13,7 @@ import org.hibernate.metamodel.model.domain.internal.EntityTypeImpl; import org.hibernate.query.QueryParameter; /** - * NOTE: Consider this contract (and its sub-contracts) as incubating as we transition to 6.0 and SQM + * @apiNote Consider this contract (and its subcontracts) as incubating as we transition to 6.0 and SQM. * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/engine/spi/ActionQueue.java b/hibernate-core/src/main/java/org/hibernate/engine/spi/ActionQueue.java index 1b43efdcef..5395fde3e2 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/spi/ActionQueue.java +++ b/hibernate-core/src/main/java/org/hibernate/engine/spi/ActionQueue.java @@ -1041,8 +1041,8 @@ public class ActionQueue { * certain that we do not circumvent this FK ordering to the extent of causing constraint violations. *

* Sorts the insert actions using more hashes. - *

- * NOTE: this class is not thread-safe. + * + * @implNote This class is not thread-safe. * * @author Jay Erb */ diff --git a/hibernate-core/src/main/java/org/hibernate/engine/spi/EntityKey.java b/hibernate-core/src/main/java/org/hibernate/engine/spi/EntityKey.java index 7bcde8db29..10d98d0185 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/spi/EntityKey.java +++ b/hibernate-core/src/main/java/org/hibernate/engine/spi/EntityKey.java @@ -36,10 +36,10 @@ public final class EntityKey implements Serializable { /** * Construct a unique identifier for an entity class instance. - *

- * NOTE : This signature has changed to accommodate both entity mode and multi-tenancy, both of which relate to - * the Session to which this key belongs. To help minimize the impact of these changes in the future, the - * {@link SessionImplementor#generateEntityKey} method was added to hide the session-specific changes. + * + * @apiNote This signature has changed to accommodate both entity mode and multi-tenancy, both of which relate to + * the session to which this key belongs. To help minimize the impact of these changes in the future, the + * {@link SessionImplementor#generateEntityKey} method was added to hide the session-specific changes. * * @param id The entity id * @param persister The entity persister diff --git a/hibernate-core/src/main/java/org/hibernate/id/BulkInsertionCapableIdentifierGenerator.java b/hibernate-core/src/main/java/org/hibernate/id/BulkInsertionCapableIdentifierGenerator.java index ab5838d55a..a07400f191 100644 --- a/hibernate-core/src/main/java/org/hibernate/id/BulkInsertionCapableIdentifierGenerator.java +++ b/hibernate-core/src/main/java/org/hibernate/id/BulkInsertionCapableIdentifierGenerator.java @@ -18,9 +18,8 @@ import org.hibernate.generator.Generator; public interface BulkInsertionCapableIdentifierGenerator extends Generator { /** * Given the configuration of this generator, is identifier generation as part of bulk insertion supported? - *

- * IMPL NOTE : Mainly here to allow stuff like SequenceStyleGenerator which *can* support this based on - * configuration + * + * @apiNote Mainly here to allow stuff like SequenceStyleGenerator which can support this based on configuration * * @return {@code true} if bulk insertions are supported; {@code false} otherwise. */ diff --git a/hibernate-core/src/main/java/org/hibernate/id/EntityIdentifierNature.java b/hibernate-core/src/main/java/org/hibernate/id/EntityIdentifierNature.java index 60c6ca180d..36da5ee916 100644 --- a/hibernate-core/src/main/java/org/hibernate/id/EntityIdentifierNature.java +++ b/hibernate-core/src/main/java/org/hibernate/id/EntityIdentifierNature.java @@ -22,19 +22,21 @@ public enum EntityIdentifierNature { /** * What Hibernate used to term an "embedded composite identifier", which is not to be confused with the JPA - * term embedded. Resolved as a tuple of basic type values and mapped over multiple singular attributes. - * Specifically a composite identifier where there is no single attribute representing the composite value. - * Equivalent of: