diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQuery.java b/hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQuery.java index bbc2c267ab..865fab3a9b 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQuery.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQuery.java @@ -22,7 +22,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; /** * Declares a named query written in native SQL. *

- * Extends {@link jakarta.persistence.NamedNativeQuery} with additional settings. + * Whereas {@link jakarta.persistence.NamedNativeQuery} allows settings to be + * specified using stringly-typed {@link jakarta.persistence.QueryHint}s, this + * annotation is typesafe. + *

+ * Note that the members of this annotation correspond to hints enumerated by + * {@link org.hibernate.jpa.AvailableHints}. * * @author Emmanuel Bernard * @@ -47,12 +52,14 @@ public @interface NamedNativeQuery { /** * The resulting {@code Class}. + *

* Should not be used in conjunction with {@link #resultSetMapping()} */ Class resultClass() default void.class; /** * The name of a {@link jakarta.persistence.SqlResultSetMapping}. + *

* Should not be used in conjunction with {@link #resultClass()}. */ String resultSetMapping() default ""; @@ -61,6 +68,7 @@ public @interface NamedNativeQuery { * The flush mode for the query. * * @see org.hibernate.query.CommonQueryContract#setFlushMode(jakarta.persistence.FlushModeType) + * @see org.hibernate.jpa.HibernateHints#HINT_FLUSH_MODE */ FlushModeType flushMode() default FlushModeType.PERSISTENCE_CONTEXT; @@ -69,6 +77,7 @@ public @interface NamedNativeQuery { * Default is {@code false}, that is, not cacheable. * * @see org.hibernate.query.SelectionQuery#setCacheable(boolean) + * @see org.hibernate.jpa.HibernateHints#HINT_CACHEABLE */ boolean cacheable() default false; @@ -76,6 +85,7 @@ public @interface NamedNativeQuery { * If the query results are cacheable, the name of the query cache region. * * @see org.hibernate.query.SelectionQuery#setCacheRegion(String) + * @see org.hibernate.jpa.HibernateHints#HINT_CACHE_REGION */ String cacheRegion() default ""; @@ -83,6 +93,7 @@ public @interface NamedNativeQuery { * The number of rows fetched by the JDBC driver per trip. * * @see org.hibernate.query.SelectionQuery#setFetchSize(int) + * @see org.hibernate.jpa.HibernateHints#HINT_FETCH_SIZE */ int fetchSize() default -1; @@ -91,6 +102,8 @@ public @interface NamedNativeQuery { * Default is no timeout. * * @see org.hibernate.query.CommonQueryContract#setTimeout(int) + * @see org.hibernate.jpa.HibernateHints#HINT_TIMEOUT + * @see org.hibernate.jpa.SpecHints#HINT_SPEC_QUERY_TIMEOUT */ int timeout() default -1; @@ -99,6 +112,7 @@ public @interface NamedNativeQuery { * Useful when engaging with DBA. * * @see org.hibernate.query.CommonQueryContract#setComment(String) + * @see org.hibernate.jpa.HibernateHints#HINT_COMMENT */ String comment() default ""; @@ -106,6 +120,7 @@ public @interface NamedNativeQuery { * The cache storage mode for objects returned by this query. * * @see org.hibernate.query.Query#setCacheMode(CacheMode) + * @see org.hibernate.jpa.SpecHints#HINT_SPEC_CACHE_STORE_MODE */ CacheStoreMode cacheStoreMode() default CacheStoreMode.USE; @@ -113,6 +128,7 @@ public @interface NamedNativeQuery { * The cache retrieval mode for objects returned by this query. * * @see org.hibernate.query.Query#setCacheMode(CacheMode) + * @see org.hibernate.jpa.SpecHints#HINT_SPEC_CACHE_RETRIEVE_MODE */ CacheRetrieveMode cacheRetrieveMode() default CacheRetrieveMode.USE; @@ -122,6 +138,8 @@ public @interface NamedNativeQuery { * @deprecated use {@link #cacheStoreMode()} and * {@link #cacheRetrieveMode()} since * {@link CacheModeType} is deprecated + * + * @see org.hibernate.jpa.HibernateHints#HINT_CACHE_MODE */ @Deprecated(since = "6.2") @Remove //TODO: actually, we won't remove it, we'll change its @@ -129,10 +147,11 @@ public @interface NamedNativeQuery { CacheModeType cacheMode() default CacheModeType.NORMAL; /** - * Whether the query results should be marked read-only. + * Whether the results should be loaded in read-only mode. * Default is {@code false}. * * @see org.hibernate.query.SelectionQuery#setReadOnly(boolean) + * @see org.hibernate.jpa.HibernateHints#HINT_READ_ONLY */ boolean readOnly() default false; @@ -140,6 +159,7 @@ public @interface NamedNativeQuery { * The query spaces involved in this query. * * @see org.hibernate.query.SynchronizeableQuery + * @see org.hibernate.jpa.HibernateHints#HINT_NATIVE_SPACES */ String[] querySpaces() default {}; @@ -150,6 +170,8 @@ public @interface NamedNativeQuery { * @deprecated Calling database procedures and functions through * {@link org.hibernate.query.NativeQuery} is no longer supported; * use {@link jakarta.persistence.NamedStoredProcedureQuery} instead. + * + * @see org.hibernate.jpa.HibernateHints#HINT_CALLABLE_FUNCTION */ @Deprecated( since = "6.0" ) boolean callable() default false; diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java b/hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java index c3406545cb..bc9e152a2b 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java @@ -12,7 +12,6 @@ import java.lang.annotation.Target; import jakarta.persistence.CacheRetrieveMode; import jakarta.persistence.CacheStoreMode; -import org.hibernate.CacheMode; import org.hibernate.Remove; import static java.lang.annotation.ElementType.PACKAGE; @@ -22,7 +21,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; /** * Declares a named query written in HQL or JPQL. *

- * Extends {@link jakarta.persistence.NamedQuery} with additional settings. + * Whereas {@link jakarta.persistence.NamedQuery} allows settings to be specified + * using stringly-typed {@link jakarta.persistence.QueryHint}s, this annotation + * is typesafe. + *

+ * Note that the members of this annotation correspond to hints enumerated by + * {@link org.hibernate.jpa.AvailableHints}. * * @author Carlos Gonzalez-Cadenas * @@ -47,6 +51,7 @@ public @interface NamedQuery { * The flush mode for this query. * * @see org.hibernate.query.CommonQueryContract#setFlushMode(jakarta.persistence.FlushModeType) + * @see org.hibernate.jpa.HibernateHints#HINT_FLUSH_MODE */ FlushModeType flushMode() default FlushModeType.PERSISTENCE_CONTEXT; @@ -55,6 +60,7 @@ public @interface NamedQuery { * Default is {@code false}, that is, not cacheable. * * @see org.hibernate.query.SelectionQuery#setCacheable(boolean) + * @see org.hibernate.jpa.HibernateHints#HINT_CACHEABLE */ boolean cacheable() default false; @@ -62,6 +68,7 @@ public @interface NamedQuery { * If the query results are cacheable, the name of the query cache region. * * @see org.hibernate.query.SelectionQuery#setCacheRegion(String) + * @see org.hibernate.jpa.HibernateHints#HINT_CACHE_REGION */ String cacheRegion() default ""; @@ -69,6 +76,7 @@ public @interface NamedQuery { * The number of rows fetched by the JDBC driver per trip. * * @see org.hibernate.query.SelectionQuery#setFetchSize(int) + * @see org.hibernate.jpa.HibernateHints#HINT_FETCH_SIZE */ int fetchSize() default -1; @@ -77,6 +85,8 @@ public @interface NamedQuery { * Default is no timeout. * * @see org.hibernate.query.CommonQueryContract#setTimeout(int) + * @see org.hibernate.jpa.HibernateHints#HINT_TIMEOUT + * @see import org.hibernate.jpa.SpecHints#HINT_SPEC_QUERY_TIMEOUT */ int timeout() default -1; @@ -85,20 +95,23 @@ public @interface NamedQuery { * Useful when engaging with DBA. * * @see org.hibernate.query.CommonQueryContract#setComment(String) + * @see org.hibernate.jpa.HibernateHints#HINT_COMMENT */ String comment() default ""; /** * The cache storage mode for objects returned by this query. * - * @see org.hibernate.query.Query#setCacheMode(CacheMode) + * @see org.hibernate.query.Query#setCacheStoreMode(CacheStoreMode) + * @see org.hibernate.jpa.SpecHints#HINT_SPEC_CACHE_STORE_MODE */ CacheStoreMode cacheStoreMode() default CacheStoreMode.USE; /** * The cache retrieval mode for objects returned by this query. * - * @see org.hibernate.query.Query#setCacheMode(CacheMode) + * @see org.hibernate.query.Query#setCacheRetrieveMode(CacheRetrieveMode) + * @see org.hibernate.jpa.SpecHints#HINT_SPEC_CACHE_RETRIEVE_MODE */ CacheRetrieveMode cacheRetrieveMode() default CacheRetrieveMode.USE; @@ -108,6 +121,8 @@ public @interface NamedQuery { * @deprecated use {@link #cacheStoreMode()} and * {@link #cacheRetrieveMode()} since * {@link CacheModeType} is deprecated + * + * @see org.hibernate.jpa.HibernateHints#HINT_CACHE_MODE */ @Deprecated(since = "6.2") @Remove //TODO: actually, we won't remove it, we'll change its @@ -115,10 +130,11 @@ public @interface NamedQuery { CacheModeType cacheMode() default CacheModeType.NORMAL; /** - * Whether the results should be read-only. + * Whether the results should be loaded in read-only mode. * Default is {@code false}. * * @see org.hibernate.query.SelectionQuery#setReadOnly(boolean) + * @see org.hibernate.jpa.HibernateHints#HINT_READ_ONLY */ boolean readOnly() default false; } diff --git a/hibernate-core/src/main/java/org/hibernate/jpa/AvailableHints.java b/hibernate-core/src/main/java/org/hibernate/jpa/AvailableHints.java index 9e2104f04b..7bdba124e7 100644 --- a/hibernate-core/src/main/java/org/hibernate/jpa/AvailableHints.java +++ b/hibernate-core/src/main/java/org/hibernate/jpa/AvailableHints.java @@ -14,7 +14,7 @@ import org.hibernate.jpa.internal.HintsCollector; import jakarta.persistence.LockModeType; /** - * Combined set of Hibernate and Jakarta Persistence hints + * Combined set of Hibernate and Jakarta Persistence hints. * * @see jakarta.persistence.EntityManager#setProperty(String, Object) * @see jakarta.persistence.EntityManager#find(Class, Object, Map) diff --git a/hibernate-core/src/main/java/org/hibernate/jpa/HibernateHints.java b/hibernate-core/src/main/java/org/hibernate/jpa/HibernateHints.java index 760b69920d..a26c37dade 100644 --- a/hibernate-core/src/main/java/org/hibernate/jpa/HibernateHints.java +++ b/hibernate-core/src/main/java/org/hibernate/jpa/HibernateHints.java @@ -14,7 +14,7 @@ import org.hibernate.query.Query; * load and lock scenarios. *

* Some hints are only effective in certain scenarios, which is noted on - * each constant's documentation + * each constant's documentation. * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/jpa/SpecHints.java b/hibernate-core/src/main/java/org/hibernate/jpa/SpecHints.java index 8d3ae181fc..12775a5363 100644 --- a/hibernate-core/src/main/java/org/hibernate/jpa/SpecHints.java +++ b/hibernate-core/src/main/java/org/hibernate/jpa/SpecHints.java @@ -14,7 +14,7 @@ import jakarta.persistence.LockModeType; /** * The hints explicitly defined by the Jakarta Persistence specification - * which are available for both queries and loading + * which are available for both queries and loading. * * @see jakarta.persistence.EntityManager#setProperty * @see jakarta.persistence.EntityManager#find(Class, Object, Map) diff --git a/hibernate-core/src/main/java/org/hibernate/query/CommonQueryContract.java b/hibernate-core/src/main/java/org/hibernate/query/CommonQueryContract.java index 0dbfa45fe8..19f635e229 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/CommonQueryContract.java +++ b/hibernate-core/src/main/java/org/hibernate/query/CommonQueryContract.java @@ -118,7 +118,11 @@ public interface CommonQueryContract { CommonQueryContract setComment(String comment); /** - * Apply hints to the query. + * Set a hint. The hints understood by Hibernate are enumerated by + * {@link org.hibernate.jpa.AvailableHints}. + * + * @see org.hibernate.jpa.HibernateHints + * @see org.hibernate.jpa.SpecHints */ CommonQueryContract setHint(String hintName, Object value);