Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

improvements to Javadoc for hints

This commit is contained in:
Gavin King 2022-01-06 10:01:20 +01:00
parent 17a06e2ffa
commit 30f627ce39
6 changed files with 73 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
hibernate-core/src/main/java/org/hibernate/annotations/QueryHints.java
View File

@ -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.
* <p/>
* 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 {
* <li>String as "whitespace"-separated list of the spaces</li>
* </ul>
*
* 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

2
hibernate-core/src/main/java/org/hibernate/boot/model/naming/ObjectNameNormalizer.java
View File

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

2
hibernate-core/src/main/java/org/hibernate/boot/spi/MappingDefaults.java
View File

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

4
hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java
View File

@ -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.
*
* <p>
* 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}.
*
* <p>
* Subclasses should be immutable.
*
* @author Gavin King, David Channon

37
hibernate-core/src/main/java/org/hibernate/graph/GraphSemantic.java
View File

@ -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".
* <ul>
* <li>Attributes explicitly specified using an {@link org.hibernate.graph.AttributeNode}s are treated as
* {@link jakarta.persistence.FetchType#EAGER} and fetched via a join or subsequent select.
* <li>Attributes not explicitly specified are treated as {@link jakarta.persistence.FetchType#LAZY} and
* are not fetched.
* </ul>
*/
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".
* <ul>
* <li>Attributes explicitly specified using an {@link org.hibernate.graph.AttributeNode}s are treated as
* {@link jakarta.persistence.FetchType#EAGER} and fetched via a join or subsequent select.
* <li>Attributes not explicitly specified are treated as {@code FetchType.LAZY} or {@code FetchType.EAGER}
* depending on the mapping of the attribute, instead of forcing {@code FetchType.LAZY}.
* </ul>
*/
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;
}

38
hibernate-core/src/main/java/org/hibernate/jpa/QueryHints.java
View File

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