diff --git a/documentation/src/main/asciidoc/repositories/Pagination.adoc b/documentation/src/main/asciidoc/repositories/Pagination.adoc index 33555767110c..c6be16c2ee20 100644 --- a/documentation/src/main/asciidoc/repositories/Pagination.adoc +++ b/documentation/src/main/asciidoc/repositories/Pagination.adoc @@ -65,8 +65,8 @@ But since Hibernate Data Repositories already validates the content of the `@Ord Dynamic sorting criteria are expressed using the types `Sort` and `Order`: -- an instance of `Sort` represents a single criterion for sorting query results, and -- an instance of `Order` packages multiple ``Sort``s together. +- an instance of https://jakarta.ee/specifications/data/1.0/apidocs/jakarta.data/jakarta/data/sort[`Sort`] represents a single criterion for sorting query results, and +- an instance of https://jakarta.ee/specifications/data/1.0/apidocs/jakarta.data/jakarta/data/order[`Order`] packages multiple ``Sort``ing criteria together. A query method may accept an instance of `Sort`. @@ -107,6 +107,18 @@ var books = Dynamic sorting criteria may be combined with static criteria. +[TIP] +==== +If the entity has entity supertypes, use a lower bounded wildcard in the repository method declaration, for example: +[source,java] +---- +@Find +List books(@Pattern String title, Year yearPublished, + Order order); +---- +This lets the caller sort by fields of the supertype. +==== + [source,java] ---- @Find @@ -120,13 +132,13 @@ We're not convinced this is very useful in practice. [[limits]] === Limits -A `Limit` is the simplest way to express a subrange of query results. +A https://jakarta.ee/specifications/data/1.0/apidocs/jakarta.data/jakarta/data/limit[`Limit`] is the simplest way to express a subrange of query results. It specifies: - `maxResults`, the maximum number of results to be returned from the database server to the client, and, -- optionally, `startAt`, an offset from the very first result. +- optionally, `startAt`, the position of the first result to be returned to the client. -These values map directly the familiar `setMaxResults()` and `setFirstResults()` of the Jakarta Persistence `Query` interface. +These values map directly to the familiar `setMaxResults()` and `setFirstResult()` of the Jakarta Persistence `Query` interface. [source,java] ---- @@ -142,12 +154,15 @@ var books = Limit.of(MAX_RESULTS)); ---- +[CAUTION] +Whereas `Query.setFirstResult()` is an _offset_ of the first result to be returned, with `setFirstResult(0)` meaning "no offset", `Limit.startAt` numbers results from one, with `Limit.range(1, n)` meaning "at most _n_ results, starting from the first result". + A more sophisticated approach is provided by `PageRequest`. [[offset-based-pagination]] === Offset-based pagination -A `PageRequest` is superficially similar to a `Limit`, except that it's specified in terms of: +A https://jakarta.ee/specifications/data/1.0/apidocs/jakarta.data/jakarta/data/page/pagerequest[`PageRequest`] is superficially similar to a `Limit`, except that it's specified in terms of: - a page `size`, and - a numbered `page`. @@ -176,7 +191,7 @@ The easiest way to be sure that you have a well-defined total order is to specif For this reason, we specified `@OrderBy("isbn")` in the previous example. ==== -However, a repository method which accepts a `PageRequest` may return a `Page` instead of a `List`, making it easier to implement pagination. +However, a repository method which accepts a `PageRequest` may return a https://jakarta.ee/specifications/data/1.0/apidocs/jakarta.data/jakarta/data/page/page[`Page`] of results instead of a `List`, making it easier to implement pagination. [source,java] ---- @@ -238,7 +253,7 @@ For key-based pagination, it's _essential_ that the query has a total order. ==== From our point of view as users of Jakarta Data, key-based pagination works almost exactly like offset-based pagination. -The difference is that we must declare our repository method to return `CursoredPage`. +The difference is that we must declare our repository method to return https://jakarta.ee/specifications/data/1.0/apidocs/jakarta.data/jakarta/data/page/cursoredpage[`CursoredPage`]. [source,java] ---- diff --git a/documentation/src/main/asciidoc/repositories/Reactive.adoc b/documentation/src/main/asciidoc/repositories/Reactive.adoc index 9e760d020430..687ceeda4c92 100644 --- a/documentation/src/main/asciidoc/repositories/Reactive.adoc +++ b/documentation/src/main/asciidoc/repositories/Reactive.adoc @@ -3,22 +3,27 @@ Hibernate Data Repositories provides repositories backed by https://hibernate.org/reactive/[Hibernate Reactive] for use in reactive programming. The methods of a reactive repository are non-blocking, and so every operation returns a reactive stream. -This is an extension to the programming model defined by Jakarta Data. [NOTE] ==== -The Jakarta Data specification has not yet defined a way to write repositories for use in reactive programming, but the spec was written to accommodate such extensions, and this capability might be standardized in a future release. +Jakarta Data 1.0 does not define a way to write repositories for use in reactive programming, but the spec was written to accommodate such extensions. +This capability is being written into Data 1.1 under the more general category of _asynchronous repositories_. ==== In Hibernate Data Repositories we use https://smallrye.io/smallrye-mutiny/[Mutiny] to work with reactive streams. -[WARNING] +[CAUTION] ==== -If and when Jakarta Data _does_ provide standard support for reactive repositories, the functionality will almost certainly be based on Java's `CompletionStage`, and not on Mutiny. +A future version of Hibernate Data Repositories will also allow the use of `CompletionStage` from `java.util.concurrent`. +Asynchronous repositories based on Mutiny are unlikely to ever be portable to other implementations of Jakarta Data. ==== In our opinion, Mutiny is a _much_ more comfortable API than `CompletionStage`. +[TIP] +The documentation for Hibernate Reactive contains a https://hibernate.org/reactive/documentation/3.0/reference/html_single/#_apis_for_chaining_reactive_operations[comparison table] that's useful if you're more familiar with `CompletionStage`. + + === Defining a reactive repository In the following code example we notice the two requirements for a reactive repository in Hibernate Data Repositories: