diff --git a/hibernate-core/src/main/java/org/hibernate/query/Query.java b/hibernate-core/src/main/java/org/hibernate/query/Query.java index 2a107f73a3..1d3c30d5a0 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/Query.java +++ b/hibernate-core/src/main/java/org/hibernate/query/Query.java @@ -128,10 +128,22 @@ public interface Query extends TypedQuery, CommonQueryContract { */ List list(); + /** + * Return the query results as a List. If the query contains + * multiple results per row, the results are returned in an instance + * of Object[]. + * + * @return the results as a list + */ default List getResultList() { return list(); } + /** + * Retrieve a Stream over the query results. + * + * @return The results as a {@link Stream} + */ default Stream getResultStream() { return stream(); } @@ -146,20 +158,34 @@ public interface Query extends TypedQuery, CommonQueryContract { */ R uniqueResult(); + /** + * Convenience method to return a single instance that matches + * the query, or {@code null} if the query returns no results. + * + * @return the single result or null + * + * @throws NonUniqueResultException if there is more than one matching result + */ default R getSingleResult() { return uniqueResult(); } + /** + * Convenience method to return a single instance that matches + * the query, as an {@link Optional}. + * + * @return the single result as an Optional + * + * @throws NonUniqueResultException if there is more than one matching result + */ Optional uniqueResultOptional(); /** * Retrieve a Stream over the query results. *

* In the initial implementation (5.2) this returns a simple sequential Stream. The plan - * is to return a a smarter stream in 6.x leveraging the SQM model. - * + * is to return a smarter stream in 6.x leveraging the SQM model. *

- * * You should call {@link Stream#close()} after processing the stream * so that the underlying resources are deallocated right away. * @@ -167,7 +193,9 @@ public interface Query extends TypedQuery, CommonQueryContract { * * @since 5.2 */ - Stream stream(); + default Stream stream() { + return getResultStream(); + } /** * Obtain the comment currently associated with this query. Provided SQL commenting is enabled @@ -246,8 +274,14 @@ public interface Query extends TypedQuery, CommonQueryContract { */ Query setLockMode(String alias, LockMode lockMode); + /** + * Set a {@link TupleTransformer} + */ Query setTupleTransformer(TupleTransformer transformer); + /** + * Set a {@link ResultListTransformer} + */ Query setResultListTransformer(ResultListTransformer transformer); /** @@ -329,43 +363,6 @@ public interface Query extends TypedQuery, CommonQueryContract { */

Query setParameter(int position, P val, BasicTypeReference

type); - /** - * Bind a named query parameter as some form of date/time using - * the indicated temporal-type. - * - * @param name the parameter name - * @param val the possibly-null parameter value - * @param temporalType the temporal-type to use in binding the date/time - * - * @return {@code this}, for method chaining - */ -

Query setParameter(String name, P val, TemporalType temporalType); - - /** - * Bind a positional query parameter as some form of date/time using - * the indicated temporal-type. - * - * @param position the position of the parameter in the query - * string, numbered from {@code 0}. - * @param val the possibly-null parameter value - * @param temporalType the temporal-type to use in binding the date/time - * - * @return {@code this}, for method chaining - */ -

Query setParameter(int position, P val, TemporalType temporalType); - - /** - * Bind a query parameter as some form of date/time using the indicated - * temporal-type. - * - * @param parameter The query parameter memento - * @param val the possibly-null parameter value - * @param temporalType the temporal-type to use in binding the date/time - * - * @return {@code this}, for method chaining - */ -

Query setParameter(QueryParameter

parameter, P val, TemporalType temporalType); - /** * Bind a query parameter using the supplied Type * @@ -388,83 +385,6 @@ public interface Query extends TypedQuery, CommonQueryContract { */

Query setParameter(QueryParameter

parameter, P val, BasicTypeReference

type); - Query setParameter(Parameter param, Instant value, TemporalType temporalType); - - Query setParameter( - Parameter param, - LocalDateTime value, - TemporalType temporalType); - - Query setParameter( - Parameter param, - ZonedDateTime value, - TemporalType temporalType); - - Query setParameter( - Parameter param, - OffsetDateTime value, - TemporalType temporalType); - - Query setParameter(String name, Instant value, TemporalType temporalType); - - Query setParameter(String name, LocalDateTime value, TemporalType temporalType); - - Query setParameter(String name, ZonedDateTime value, TemporalType temporalType); - - Query setParameter(String name, OffsetDateTime value, TemporalType temporalType); - - Query setParameter(int position, Instant value, TemporalType temporalType); - - Query setParameter(int position, LocalDateTime value, TemporalType temporalType); - - Query setParameter(int position, ZonedDateTime value, TemporalType temporalType); - - Query setParameter(int position, OffsetDateTime value, TemporalType temporalType); - - - // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - // covariant overrides - CommonQueryContract - - @Override - Query setHibernateFlushMode(FlushMode flushMode); - - @Override - Query setCacheable(boolean cacheable); - - @Override - Query setCacheRegion(String cacheRegion); - - @Override - Query setCacheMode(CacheMode cacheMode); - - @Override - Query setTimeout(int timeout); - - @Override - Query setFetchSize(int fetchSize); - - @Override - Query setReadOnly(boolean readOnly); - - - // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - // covariant overrides - jakarta.persistence.Query/TypedQuery - - @Override - Query setMaxResults(int maxResult); - - @Override - Query setFirstResult(int startPosition); - - @Override - Query setHint(String hintName, Object value); - - @Override - Query setFlushMode(FlushModeType flushMode); - - @Override - Query setLockMode(LockModeType lockMode); - /** * Bind a named query parameter using its inferred Type. If the parameter is * defined in such a way that the Type cannot be inferred from its usage context then @@ -497,26 +417,6 @@ public interface Query extends TypedQuery, CommonQueryContract { @Override Query setParameter(Parameter param, T value); - @Override - Query setParameter(Parameter param, Calendar value, TemporalType temporalType); - - @Override - Query setParameter(Parameter param, Date value, TemporalType temporalType); - - @Override - Query setParameter(String name, Calendar value, TemporalType temporalType); - - @Override - Query setParameter(String name, Date value, TemporalType temporalType); - - @Override - Query setParameter(int position, Calendar value, TemporalType temporalType); - - @Override - Query setParameter(int position, Date value, TemporalType temporalType); - - - /** * Bind multiple values to a query parameter using its inferred Type. The Hibernate type of the parameter values is * first detected via the usage/position in the query and if not sufficient secondly @@ -706,12 +606,57 @@ public interface Query extends TypedQuery, CommonQueryContract { * matching key names with parameter names and mapping value types to * Hibernate types using heuristics. * - * @param bean a java.util.Map + * @param bean a {@link Map} of names to arguments * * @return {@code this}, for method chaining */ Query setProperties(@SuppressWarnings("rawtypes") Map bean); + // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + // covariant overrides - CommonQueryContract + + @Override + Query setHibernateFlushMode(FlushMode flushMode); + + @Override + Query setCacheable(boolean cacheable); + + @Override + Query setCacheRegion(String cacheRegion); + + @Override + Query setCacheMode(CacheMode cacheMode); + + @Override + Query setTimeout(int timeout); + + @Override + Query setFetchSize(int fetchSize); + + @Override + Query setReadOnly(boolean readOnly); + + // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + // covariant overrides - jakarta.persistence.Query/TypedQuery + + @Override + Query setMaxResults(int maxResult); + + @Override + Query setFirstResult(int startPosition); + + @Override + Query setHint(String hintName, Object value); + + @Override + Query setFlushMode(FlushModeType flushMode); + + @Override + Query setLockMode(LockModeType lockMode); + + // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + // deprecated methods + /** * @deprecated (since 5.2) Use {@link #setTupleTransformer} or {@link #setResultListTransformer} */ @@ -722,4 +667,183 @@ public interface Query extends TypedQuery, CommonQueryContract { setResultListTransformer( transformer ); return this; } + + /** + * Bind a positional query parameter as some form of date/time using + * the indicated temporal-type. + * + * @param position the position of the parameter in the query + * string, numbered from 0. + * @param val the possibly-null parameter value + * @param temporalType the temporal-type to use in binding the date/time + * + * @return {@code this}, for method chaining + * + * @deprecated use {@link #setParameter(int, Object)} + * passing a {@link java.time.LocalDate}, {@link java.time.LocalTime}, + * or {@link java.time.LocalDateTime} + */ + @Deprecated + Query setParameter(int position, Object val, TemporalType temporalType); + + /** + * Bind a named query parameter as some form of date/time using + * the indicated temporal-type. + * + * @param name the parameter name + * @param val the possibly-null parameter value + * @param temporalType the temporal-type to use in binding the date/time + * + * @return {@code this}, for method chaining + * + * @deprecated use {@link #setParameter(String, Object)} + * passing a {@link java.time.LocalDate}, {@link java.time.LocalTime}, + * or {@link java.time.LocalDateTime} + */ + @Deprecated + Query setParameter(String name, Object val, TemporalType temporalType); + + /** + * Bind a query parameter as some form of date/time using the indicated + * temporal-type. + * + * @param parameter The query parameter memento + * @param val the possibly-null parameter value + * @param temporalType the temporal-type to use in binding the date/time + * + * @return {@code this}, for method chaining + * + * @deprecated use {@link #setParameter(int, Object)} + * passing a {@link java.time.LocalDate}, {@link java.time.LocalTime}, + * or {@link java.time.LocalDateTime} + */ + @Deprecated +

Query setParameter(QueryParameter

parameter, P val, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(Parameter, Object)} + */ + @Override @Deprecated + Query setParameter(Parameter param, Calendar value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(Parameter, Object)}, + * passing a {@link java.time.LocalDate}, {@link java.time.LocalTime}, + * or {@link java.time.LocalDateTime} + */ + @Override @Deprecated + Query setParameter(Parameter param, Date value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(String, Object)}, + * passing a {@link java.time.LocalDate}, {@link java.time.LocalTime}, + * or {@link java.time.LocalDateTime} + */ + @Override @Deprecated + Query setParameter(String name, Calendar value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(String, Object)} + * passing a {@link java.time.LocalDate}, {@link java.time.LocalTime}, + * or {@link java.time.LocalDateTime} + */ + @Override @Deprecated + Query setParameter(String name, Date value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(int, Object)} + * passing a {@link java.time.LocalDate}, {@link java.time.LocalTime}, + * or {@link java.time.LocalDateTime} + */ + @Override @Deprecated + Query setParameter(int position, Calendar value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(int, Object)} + * passing a {@link java.time.LocalDate}, {@link java.time.LocalTime}, + * or {@link java.time.LocalDateTime} + */ + @Override @Deprecated + Query setParameter(int position, Date value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(Parameter, Object)} + */ + @Deprecated + Query setParameter(Parameter param, Instant value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(Parameter, Object)} + */ + @Deprecated + Query setParameter( + Parameter param, + LocalDateTime value, + TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(Parameter, Object)} + */ + @Deprecated + Query setParameter( + Parameter param, + ZonedDateTime value, + TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(Parameter, Object)} + */ + @Deprecated + Query setParameter( + Parameter param, + OffsetDateTime value, + TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(String, Object)} + */ + @Deprecated + Query setParameter(String name, Instant value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(String, Object)} + */ + @Deprecated + Query setParameter(String name, LocalDateTime value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(String, Object)} + */ + @Deprecated + Query setParameter(String name, ZonedDateTime value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(String, Object)} + */ + @Deprecated + Query setParameter(String name, OffsetDateTime value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(int, Object)} + */ + @Deprecated + Query setParameter(int position, Instant value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(int, Object)} + */ + @Deprecated + Query setParameter(int position, LocalDateTime value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(int, Object)} + */ + @Deprecated + Query setParameter(int position, ZonedDateTime value, TemporalType temporalType); + + /** + * @deprecated use {@link #setParameter(int, Object)} + */ + @Deprecated + Query setParameter(int position, OffsetDateTime value, TemporalType temporalType); } diff --git a/hibernate-core/src/main/java/org/hibernate/query/QueryProducer.java b/hibernate-core/src/main/java/org/hibernate/query/QueryProducer.java index aa1f10f806..22e6bbce7d 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/QueryProducer.java +++ b/hibernate-core/src/main/java/org/hibernate/query/QueryProducer.java @@ -20,20 +20,6 @@ import jakarta.persistence.criteria.CriteriaUpdate; * @author Steve Ebersole */ public interface QueryProducer { - /** - * Create a {@link Query} instance for the named query. - * - * @param queryName the name of a pre-defined, named query - * - * @return The Query instance for manipulation and execution - * - * @throws IllegalArgumentException if a query has not been - * defined with the given name or if the query string is - * found to be invalid - */ - @SuppressWarnings("rawtypes") - Query getNamedQuery(String queryName); - /** * Create a {@link Query} instance for the given HQL/JPQL query string. * @@ -42,8 +28,9 @@ public interface QueryProducer { * @return The Query instance for manipulation and execution * * @see jakarta.persistence.EntityManager#createQuery(String) + * @deprecated use {@link #createQuery(String, Class)} */ - @SuppressWarnings("rawtypes") + @Deprecated @SuppressWarnings("rawtypes") Query createQuery(String queryString); /** @@ -70,8 +57,10 @@ public interface QueryProducer { * found to be invalid * * @see jakarta.persistence.EntityManager#createNamedQuery(String) + * + * @deprecated use {@link #createNamedQuery(String, Class)} */ - @SuppressWarnings("rawtypes") + @Deprecated @SuppressWarnings("rawtypes") Query createNamedQuery(String name); /** @@ -100,8 +89,10 @@ public interface QueryProducer { * @return The NativeQuery instance for manipulation and execution * * @see jakarta.persistence.EntityManager#createNativeQuery(String) + * + * @deprecated use {@link #createNativeQuery(String, Class)} */ - @SuppressWarnings("rawtypes") + @Deprecated @SuppressWarnings("rawtypes") NativeQuery createNativeQuery(String sqlString); /** @@ -128,29 +119,25 @@ public interface QueryProducer { * * @see jakarta.persistence.EntityManager#createNativeQuery(String,Class) * @see jakarta.persistence.SqlResultSetMapping + * + * @deprecated use {@link #createNativeQuery(String, String, Class)} */ - @SuppressWarnings("rawtypes") + @Deprecated @SuppressWarnings("rawtypes") NativeQuery createNativeQuery(String sqlString, String resultSetMappingName); /** - * Get a NativeQuery instance for a named native SQL query + * Create a NativeQuery instance for the given native (SQL) query using + * implicit mapping to the specified Java type. * - * @param name The name of the pre-defined query + * @param sqlString Native (SQL) query string + * @param resultSetMappingName The explicit result mapping name * * @return The NativeQuery instance for manipulation and execution - */ - @SuppressWarnings("rawtypes") - NativeQuery getNamedNativeQuery(String name); - - /** - * Get a NativeQuery instance for a named native SQL query * - * @param name The name of the pre-defined query - * - * @return The NativeQuery instance for manipulation and execution + * @see jakarta.persistence.EntityManager#createNativeQuery(String,Class) + * @see jakarta.persistence.SqlResultSetMapping */ - @SuppressWarnings("rawtypes") - NativeQuery getNamedNativeQuery(String name, String resultSetMapping); + NativeQuery createNativeQuery(String sqlString, String resultSetMappingName, Class resultClass); /** * Create a Query for the given JPA {@link CriteriaQuery} @@ -174,4 +161,44 @@ public interface QueryProducer { */ @SuppressWarnings("rawtypes") Query createQuery(CriteriaDelete deleteQuery); + + /** + * Create a {@link Query} instance for the named query. + * + * @param queryName the name of a pre-defined, named query + * + * @return The Query instance for manipulation and execution + * + * @throws IllegalArgumentException if a query has not been + * defined with the given name or if the query string is + * found to be invalid + * + * @deprecated use {@link #createNamedQuery(String, Class)} + c */ + @Deprecated @SuppressWarnings("rawtypes") + Query getNamedQuery(String queryName); + + /** + * Get a NativeQuery instance for a named native SQL query + * + * @param name The name of the pre-defined query + * + * @return The NativeQuery instance for manipulation and execution + * + * @deprecated use {@link #createNamedQuery(String, Class)} + */ + @Deprecated @SuppressWarnings("rawtypes") + NativeQuery getNamedNativeQuery(String name); + + /** + * Get a NativeQuery instance for a named native SQL query + * + * @param name The name of the pre-defined query + * + * @return The NativeQuery instance for manipulation and execution + * + * @deprecated use {@link #createNamedQuery(String, Class)} + */ + @Deprecated @SuppressWarnings("rawtypes") + NativeQuery getNamedNativeQuery(String name, String resultSetMapping); }