From cf0c41903b8a141ce852a03cc8272801f533e7d7 Mon Sep 17 00:00:00 2001 From: Gavin King Date: Wed, 25 Oct 2023 21:44:14 +0200 Subject: [PATCH] minor clarification to what is returned by getResultList() / getResultStream() see #537 --- .../main/java/jakarta/persistence/Query.java | 6 ++++-- .../java/jakarta/persistence/TypedQuery.java | 21 +++++++++++-------- 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/api/src/main/java/jakarta/persistence/Query.java b/api/src/main/java/jakarta/persistence/Query.java index cb014283..9c059ac3 100644 --- a/api/src/main/java/jakarta/persistence/Query.java +++ b/api/src/main/java/jakarta/persistence/Query.java @@ -39,7 +39,8 @@ public interface Query { /** * Execute a SELECT query and return the query results as an untyped * {@link List}. - * @return a list of the results + * @return a list of the results, or an empty list if there are + * no results * @throws IllegalStateException if called for a Jakarta * Persistence query language UPDATE or DELETE statement * @throws QueryTimeoutException if the query execution exceeds @@ -68,7 +69,8 @@ public interface Query { * however persistence provider may choose to override this method * to provide additional capabilities. * - * @return a stream of the results + * @return a stream of the results, or an empty stream if there + * are no results * @throws IllegalStateException if called for a Jakarta * Persistence query language UPDATE or DELETE statement * @throws QueryTimeoutException if the query execution exceeds diff --git a/api/src/main/java/jakarta/persistence/TypedQuery.java b/api/src/main/java/jakarta/persistence/TypedQuery.java index 92642b29..080c9f97 100644 --- a/api/src/main/java/jakarta/persistence/TypedQuery.java +++ b/api/src/main/java/jakarta/persistence/TypedQuery.java @@ -37,8 +37,9 @@ public interface TypedQuery extends Query { /** * Execute a SELECT query and return the query results as a typed - * {@link List}. - * @return a list of the results + * {@link List List<X>}. + * @return a list of the results, each of type {@link X}, or an + * empty list if there are no results * @throws IllegalStateException if called for a Jakarta * Persistence query language UPDATE or DELETE statement * @throws QueryTimeoutException if the query execution exceeds @@ -60,13 +61,14 @@ public interface TypedQuery extends Query { /** * Execute a SELECT query and return the query result as a typed - * {@link java.util.stream.Stream}. + * {@link java.util.stream.Stream Stream<X>}. * - *

By default, this method delegates to {@code getResultList().stream()}, - * however, persistence provider may choose to override this method - * to provide additional capabilities. + *

By default, this method delegates to {@link List#stream() + * getResultList().stream()}, however, persistence provider may + * choose to override this method to provide additional capabilities. * - * @return a stream of the results + * @return a stream of the results, each of type {@link X}, or an + * empty stream if there are no results * @throws IllegalStateException if called for a Jakarta * Persistence query language UPDATE or DELETE statement * @throws QueryTimeoutException if the query execution exceeds @@ -93,7 +95,7 @@ default Stream getResultStream() { /** * Execute a SELECT query that returns a single result. - * @return the result + * @return the result, of type {@link X} * @throws NoResultException if there is no result * @throws NonUniqueResultException if more than one result * @throws IllegalStateException if called for a Jakarta @@ -117,7 +119,8 @@ default Stream getResultStream() { /** * Execute a SELECT query that returns a single untyped result. - * @return the result, or null if there is no result + * @return the result, of type {@link X}, or null if there is no + * result * @throws NonUniqueResultException if more than one result * @throws IllegalStateException if called for a Jakarta * Persistence query language UPDATE or DELETE statement