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

document correspondence between @NamedQuery members and query hints

This commit is contained in:
Gavin 2022-12-28 11:25:00 +01:00 committed by Gavin King
parent 7cc701902d
commit 81851dc985
6 changed files with 53 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQuery.java
View File

@ -22,7 +22,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Declares a named query written in native SQL.
* <p>
* 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.
* <p>
* 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}.
* <p>
* Should not be used in conjunction with {@link #resultSetMapping()}
*/
Class<?> resultClass() default void.class;
/**
* The name of a {@link jakarta.persistence.SqlResultSetMapping}.
* <p>
* 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;

26
hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java
View File

@ -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.
* <p>
* 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.
* <p>
* 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;
}

2
hibernate-core/src/main/java/org/hibernate/jpa/AvailableHints.java
View File

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

2
hibernate-core/src/main/java/org/hibernate/jpa/HibernateHints.java
View File

@ -14,7 +14,7 @@ import org.hibernate.query.Query;
* load and lock scenarios.
* <p>
* Some hints are only effective in certain scenarios, which is noted on
* each constant's documentation
* each constant's documentation.
*
* @author Steve Ebersole
*/

2
hibernate-core/src/main/java/org/hibernate/jpa/SpecHints.java
View File

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

6
hibernate-core/src/main/java/org/hibernate/query/CommonQueryContract.java
View File

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