From 30f627ce3995b73b99c3f345ad34a61af4cc1ed0 Mon Sep 17 00:00:00 2001 From: Gavin King Date: Thu, 6 Jan 2022 10:01:20 +0100 Subject: [PATCH] improvements to Javadoc for hints --- .../org/hibernate/annotations/QueryHints.java | 29 ++++++++------ .../model/naming/ObjectNameNormalizer.java | 2 +- .../hibernate/boot/spi/MappingDefaults.java | 2 +- .../java/org/hibernate/dialect/Dialect.java | 4 +- .../org/hibernate/graph/GraphSemantic.java | 37 ++++++++++++------ .../java/org/hibernate/jpa/QueryHints.java | 38 ++++++++++++------- 6 files changed, 73 insertions(+), 39 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/QueryHints.java b/hibernate-core/src/main/java/org/hibernate/annotations/QueryHints.java index 7ad7a9809c..584d84448b 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/QueryHints.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/QueryHints.java @@ -9,8 +9,12 @@ package org.hibernate.annotations; import org.hibernate.FlushMode; /** - * Consolidation of hints available to Hibernate JPA queries. Mainly used to define features available on - * Hibernate queries that have no corollary in JPA queries. + * List of hints that may be passed to {@link jakarta.persistence.Query#setHint(String, Object)} + * to control execution of a query. Each of these hints corresponds to a typesafe operation of + * the {@link org.hibernate.query.Query} interface, and so hints are only necessary for programs + * working with the JPA APIs. + * + * @see org.hibernate.jpa.QueryHints */ public class QueryHints { /** @@ -44,7 +48,7 @@ public class QueryHints { public static final String CACHEABLE = "org.hibernate.cacheable"; /** - * Is the procedure a function? Note: only valid for named stored procedures. + * Is the named stored procedure a function? */ public static final String CALLABLE_FUNCTION = "org.hibernate.callableFunction"; @@ -101,17 +105,20 @@ public class QueryHints { public static final String TIMEOUT_JAKARTA_JPA = "jakarta.persistence.query.timeout"; /** - * Available to apply lock mode to a native SQL query since JPA requires that - * {@link jakarta.persistence.Query#setLockMode} throw an IllegalStateException if called for a native query. + * Apply lock mode to a native SQL query since JPA requires that + * {@link jakarta.persistence.Query#setLockMode} throw an {@code IllegalStateException} + * if called for a native query. *

* Accepts a {@link jakarta.persistence.LockModeType} or a {@link org.hibernate.LockMode} */ public static final String NATIVE_LOCKMODE = "org.hibernate.lockMode"; /** - * Hint to enable/disable the follow-on-locking mechanism provided by {@link org.hibernate.dialect.Dialect#useFollowOnLocking(QueryParameters)}. - * A value of {@code true} enables follow-on-locking, whereas a value of {@code false} disables it. - * If the value is {@code null}, the {@code Dialect} strategy is going to be used instead. + * Hint to enable/disable the follow-on-locking mechanism provided by + * {@link org.hibernate.dialect.Dialect#useFollowOnLocking(String, org.hibernate.query.spi.QueryOptions)}. + * A value of {@code true} enables follow-on-locking, whereas a value of + * {@code false} disables it. If the value is {@code null}, the + * {@code Dialect}'s default strategy is used. * * @since 5.2 */ @@ -126,11 +133,11 @@ public class QueryHints { *

  • String as "whitespace"-separated list of the spaces
    • * * - * Note that the passed space need not match to any real spaces/tables in + * Note that the passed space need not match any real spaces/tables in * the underlying query. This can be used to completely circumvent * the auto-flush checks as well as any cache invalidation that might - * occur as part of a flush. See the documentation on SynchronizeableQuery - * for details. See also {@link FlushMode#MANUAL} + * occur as part of a flush. See {@link org.hibernate.query.SynchronizeableQuery} + * and {@link FlushMode#MANUAL} for more information. * * @see org.hibernate.SynchronizeableQuery * @see #FLUSH_MODE diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/naming/ObjectNameNormalizer.java b/hibernate-core/src/main/java/org/hibernate/boot/model/naming/ObjectNameNormalizer.java index 90bd1fcf73..a0a2cae8e3 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/model/naming/ObjectNameNormalizer.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/model/naming/ObjectNameNormalizer.java @@ -24,7 +24,7 @@ public abstract class ObjectNameNormalizer { * This implements the rules set forth in JPA 2 (section "2.13 Naming of Database Objects") which * states that the double-quote (") is the character which should be used to denote a {@code quoted * identifier}. Here, we handle recognizing that and converting it to the more elegant - * backtick (`) approach used in Hibernate.. Additionally we account for applying what JPA2 terms + * backtick (`) approach used in Hibernate. Additionally, we account for applying what JPA2 terms * "globally quoted identifiers". * * @param identifierText The identifier to be quoting-normalized. diff --git a/hibernate-core/src/main/java/org/hibernate/boot/spi/MappingDefaults.java b/hibernate-core/src/main/java/org/hibernate/boot/spi/MappingDefaults.java index 1ad7e19043..2e61c175f2 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/spi/MappingDefaults.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/spi/MappingDefaults.java @@ -43,7 +43,7 @@ public interface MappingDefaults { * * {@code true} indicates that all identifier encountered within this context should be * quoted. {@code false} indicates indicates that identifiers within this context are - * onl;y quoted if explicitly quoted. + * only quoted if explicitly quoted. * * @return {@code true}/{@code false} */ 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 8b99cd7584..8b33e678b8 100644 --- a/hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java +++ b/hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java @@ -177,13 +177,13 @@ import static org.hibernate.type.descriptor.DateTimeUtils.appendAsTimestampWithM /** * Represents a dialect of SQL implemented by a particular RDBMS. Subclasses * implement Hibernate compatibility with different database platforms. - * + *

    * Subclasses must provide a public constructor that registers a set of type * mappings from JDBC type codes to database native type names, along with * default Hibernate properties. This constructor may have no parameters, or * it may have a single parameter of type * {@link org.hibernate.engine.jdbc.dialect.spi.DialectResolutionInfo}. - * + *

    * Subclasses should be immutable. * * @author Gavin King, David Channon diff --git a/hibernate-core/src/main/java/org/hibernate/graph/GraphSemantic.java b/hibernate-core/src/main/java/org/hibernate/graph/GraphSemantic.java index ceb0817234..baef287fbf 100644 --- a/hibernate-core/src/main/java/org/hibernate/graph/GraphSemantic.java +++ b/hibernate-core/src/main/java/org/hibernate/graph/GraphSemantic.java @@ -7,26 +7,31 @@ package org.hibernate.graph; /** - * JPA defines 2 distinct semantics for applying an EntityGraph. This - * enumeration captures those 2 semantics. + * JPA specifies two distinct ways to apply an {@link jakarta.persistence.EntityGraph}, + * as a {@link #FETCH "fetch graph"}, or as a {@link #LOAD "load graph"}. * * @author Steve Ebersole */ public enum GraphSemantic { /** - * Indicates a "fetch graph" EntityGraph. Attributes explicitly specified - * as AttributeNodes are treated as FetchType.EAGER (via join fetch or - * subsequent select). Attributes that are not specified are treated as - * FetchType.LAZY invariably. + * Indicates that an {@link jakarta.persistence.EntityGraph} should be interpreted as a JPA "fetch graph". + *

    */ FETCH( "javax.persistence.fetchgraph", "jakarta.persistence.fetchgraph" ), /** - * Indicates a "load graph" EntityGraph. Attributes explicitly specified - * as AttributeNodes are treated as FetchType.EAGER (via join fetch or - * subsequent select). Attributes that are not specified are treated as - * FetchType.LAZY or FetchType.EAGER depending on the attribute's definition - * in metadata. + * Indicates that an {@link jakarta.persistence.EntityGraph} should be interpreted as a JPA "load graph". + * */ LOAD( "javax.persistence.loadgraph", "jakarta.persistence.loadgraph" ); @@ -38,10 +43,20 @@ public enum GraphSemantic { this.jakartaJpaHintName = jakartaJpaHintName; } + /** + * The hint name that should be used with JPA. + * + * @see jakarta.persistence.Query#setHint(String, Object) + */ public String getJpaHintName() { return jpaHintName; } + /** + * The hint name that should be used with Jakarta Persistence. + * + * @see jakarta.persistence.Query#setHint(String, Object) + */ public String getJakartaJpaHintName() { return jakartaJpaHintName; } diff --git a/hibernate-core/src/main/java/org/hibernate/jpa/QueryHints.java b/hibernate-core/src/main/java/org/hibernate/jpa/QueryHints.java index c9e72f78df..47f2489d5b 100644 --- a/hibernate-core/src/main/java/org/hibernate/jpa/QueryHints.java +++ b/hibernate-core/src/main/java/org/hibernate/jpa/QueryHints.java @@ -26,7 +26,11 @@ import static org.hibernate.annotations.QueryHints.TIMEOUT_JAKARTA_JPA; import static org.hibernate.annotations.QueryHints.TIMEOUT_JPA; /** - * Defines the supported JPA query hints + * List of all supported hints that may be passed to {@link jakarta.persistence.Query#setHint(String, Object)}, + * including those defined by {@link org.hibernate.annotations.QueryHints}, and those defined by the enumerated + * instances of {@link GraphSemantic}. + * + * @see org.hibernate.annotations.QueryHints */ public class QueryHints { /** @@ -58,8 +62,8 @@ public class QueryHints { public static final String HINT_FETCH_SIZE = FETCH_SIZE; /** - * The hint key for specifying whether the query results should be cached for the next (cached) execution of the - * "same query". + * The hint key for specifying whether the query results should be cached for the next (cached) execution + * of the "same query". */ public static final String HINT_CACHEABLE = CACHEABLE; @@ -70,8 +74,8 @@ public class QueryHints { public static final String HINT_CACHE_REGION = CACHE_REGION; /** - * The hint key for specifying that objects loaded into the persistence context as a result of this query execution - * should be associated with the persistence context as read-only. + * The hint key for specifying that objects loaded into the persistence context as a result of this query + * execution should be associated with the persistence context as read-only. */ public static final String HINT_READONLY = READ_ONLY; @@ -87,6 +91,10 @@ public class QueryHints { */ public static final String HINT_FLUSH_MODE = FLUSH_MODE; + /** + * The hint key for specifying the lock mode ({@link jakarta.persistence.LockModeType} or + * {@link org.hibernate.LockMode}) to use for execution of a native query. + */ public static final String HINT_NATIVE_LOCKMODE = NATIVE_LOCKMODE; /** @@ -96,11 +104,9 @@ public class QueryHints { public static final String HINT_FETCHGRAPH = GraphSemantic.FETCH.getJpaHintName(); /** - * Hint providing a "fetchgraph" EntityGraph. Attributes explicitly specified as AttributeNodes are treated as - * FetchType.EAGER (via join fetch or subsequent select). + * Hint providing a {@link jakarta.persistence.EntityGraph} that should be interpreted as a "fetch graph". * - * Note: Currently, attributes that are not specified are treated as FetchType.LAZY or FetchType.EAGER depending - * on the attribute's definition in metadata, rather than forcing FetchType.LAZY. + * @see GraphSemantic#FETCH */ public static final String JAKARTA_HINT_FETCH_GRAPH = GraphSemantic.FETCH.getJakartaJpaHintName(); @@ -111,9 +117,9 @@ public class QueryHints { public static final String HINT_LOADGRAPH = GraphSemantic.LOAD.getJpaHintName(); /** - * Hint providing a "loadgraph" EntityGraph. Attributes explicitly specified as AttributeNodes are treated as - * FetchType.EAGER (via join fetch or subsequent select). Attributes that are not specified are treated as - * FetchType.LAZY or FetchType.EAGER depending on the attribute's definition in metadata + * Hint providing a {@link jakarta.persistence.EntityGraph} that should be interpreted as a "load graph". + * + * @see GraphSemantic#LOAD */ public static final String JAKARTA_HINT_LOAD_GRAPH = GraphSemantic.LOAD.getJakartaJpaHintName(); @@ -133,10 +139,16 @@ public class QueryHints { */ public static final String JAKARTA_HINT_LOADGRAPH = GraphSemantic.LOAD.getJakartaJpaHintName(); + /** + * The hint key to enable or disable the default follow-on-locking mechanism provided by + * {@link org.hibernate.dialect.Dialect#useFollowOnLocking(String, org.hibernate.query.spi.QueryOptions)}. + */ public static final String HINT_FOLLOW_ON_LOCKING = FOLLOW_ON_LOCKING; /** - * See {@link org.hibernate.annotations.QueryHints#NATIVE_SPACES} + * Hint key for specifying query spaces to be applied to a native (SQL) query. + * + * @see org.hibernate.annotations.QueryHints#NATIVE_SPACES */ public static final String HINT_NATIVE_SPACES = NATIVE_SPACES;