Hibernate/hibernate-orm
1
0
Fork 0
mirror of https://github.com/hibernate/hibernate-orm synced 2025-02-17 00:24:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

improve some javadoc for Query

Browse Source
This commit is contained in:
Gavin King 2022-01-05 13:13:21 +01:00
parent 780fb3e500
commit 261ca55b0f
1 changed files with 52 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
hibernate-core/src/main/java/org/hibernate/query/Query.java
View File

@ -120,27 +120,35 @@ default Query<R> applyLoadGraph(@SuppressWarnings("rawtypes") RootGraph graph) {
ScrollableResults<R> scroll(ScrollMode scrollMode); ScrollableResults<R> scroll(ScrollMode scrollMode);
/** /**
* Return the query results as a {@code List}. If the query contains * Execute the query and return the query results as a {@link List}.
* multiple results per row, the results are returned in an instance * If the query contains multiple items in the selection list, then
* of {@code Object[]}. * by default each result in the list is packaged in an array of type
* {@code Object[]}.
* *
* @return the result list * @return the result list
*/ */
List<R> list(); List<R> list();
/** /**
* Return the query results as a {@link List}. If the query contains * Execute the query and return the query results as a {@link List}.
* multiple results per row, the results are returned in an instance * If the query contains multiple items in the selection list, then
* of {@code Object[]}. * by default each result in the list is packaged in an array of type
* {@code Object[]}.
* *
* @return the results as a list * @return the results as a list
*/ */
default List<R> getResultList() { default List<R> getResultList() {
return list(); return list();
} }
/** /**
* Retrieve a {@link Stream} over the query results. * Execute the query and return the query results as a {@link Stream}.
* If the query contains multiple items in the selection list, then
* by default each result in the stream is packaged in an array of type
* {@code Object[]}.
* <p>
* The client should call {@link Stream#close()} after processing the
* stream so that resources are freed as soon as possible.
* *
* @return The results as a {@link Stream} * @return The results as a {@link Stream}
*/ */
@ -149,8 +157,31 @@ default Stream<R> getResultStream() {
} }
/** /**
* Convenience method to return a single instance that matches * Execute an insert, update, or delete statement, and return the
* the query, or {@code null} if the query returns no results. * number of affected entities.
* <p>
* For use with instances of {@code Query<Void>} created using
* {@link QueryProducer#createStatement(String)},
* {@link QueryProducer#createNamedStatement(String)},
* {@link QueryProducer#createNativeStatement(String)},
* {@link QueryProducer#createQuery(jakarta.persistence.criteria.CriteriaUpdate)}, or
* {@link QueryProducer#createQuery(jakarta.persistence.criteria.CriteriaDelete)}.
*
* @return the number of affected entity instances
* (may differ from the number of affected rows)
*
* @see QueryProducer#createStatement(String)
* @see QueryProducer#createNamedStatement(String)
* @see QueryProducer#createNativeStatement(String)
*
* @see jakarta.persistence.Query#executeUpdate()
*/
@Override
int executeUpdate();
/**
* Execute the query and return the single result of the query,
* or {@code null} if the query returns no results.
* *
* @return the single result or {@code null} * @return the single result or {@code null}
* *
@ -159,8 +190,8 @@ default Stream<R> getResultStream() {
R uniqueResult(); R uniqueResult();
/** /**
* Convenience method to return a single instance that matches * Execute the query and return the single result of the query,
* the query, throwing an exception if the query returns no results. * throwing an exception if the query returns no results.
* *
* @return the single result, only if there is exactly one * @return the single result, only if there is exactly one
* *
@ -170,8 +201,8 @@ default Stream<R> getResultStream() {
R getSingleResult(); R getSingleResult();
/** /**
* Convenience method to return a single instance that matches * Execute the query and return the single result of the query,
* the query, as an {@link Optional}. * as an {@link Optional}.
* *
* @return the single result as an {@code Optional} * @return the single result as an {@code Optional}
* *
@ -180,15 +211,15 @@ default Stream<R> getResultStream() {
Optional<R> uniqueResultOptional(); Optional<R> uniqueResultOptional();
/** /**
* Retrieve a Stream over the query results. * Execute the query and return the query results as a {@link Stream}.
* <p/> * If the query contains multiple items in the selection list, then
* In the initial implementation (5.2) this returns a simple sequential Stream. The plan * by default each result in the stream is packaged in an array of type
* is to return a smarter stream in 6.x leveraging the SQM model. * {@code Object[]}.
* <p> * <p>
* You should call {@link Stream#close()} after processing the stream * The client should call {@link Stream#close()} after processing the
* so that the underlying resources are deallocated right away. * stream so that resources are freed as soon as possible.
* *
* @return The results Stream * @return The results as a {@link Stream}
* *
* @since 5.2 * @since 5.2
*/ */