From 861013f3244e01def55a68d7d1bd3328933dec0a Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Mon, 13 Nov 2023 14:20:16 -0600 Subject: [PATCH 1/2] Issue #228 proofread section 4.8: pagination Signed-off-by: Nathan Rauh --- spec/src/main/asciidoc/repository.asciidoc | 27 +++++++++++++++++----- 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/spec/src/main/asciidoc/repository.asciidoc b/spec/src/main/asciidoc/repository.asciidoc index bc7951fb0..fdfe01872 100644 --- a/spec/src/main/asciidoc/repository.asciidoc +++ b/spec/src/main/asciidoc/repository.asciidoc @@ -1069,23 +1069,23 @@ KeysetAwarePage olderThan(int age, Pageable pagination); === Pagination in Jakarta Data -Pagination is a critical aspect of data access and retrieval in many applications, including those developed in Java. It plays a crucial role in ensuring the efficient and user-friendly handling of large datasets. In Jakarta Data, APIs are provided to help Java developers manage and navigate through data efficiently. This session will discuss the importance of pagination in Java development and explore the two main types of pagination: Offset and Keyset. +Dividing up large sets of data into pages is a beneficial strategy for data access and retrieval in many applications, including those developed in Java. Pagination helps improve the efficiency of handling large datasets in a way that is also user-friendly. In Jakarta Data, APIs are provided to help Java developers efficiently manage and navigate through data. This section discusses the importance of pagination in Java development and explores the two types of pagination that are available in Jakarta Data: Offset-based pagination and Keyset cursor-based pagination. image::02-pagination.png[alt=pagiantion sample, width=70%, height=70%] -Pagination is vital to Java developers for several reasons: +Pagination is helpful to Java developers for several reasons: 1. *Performance*: Without pagination, loading large datasets at once can result in slow and resource-intensive operations. By breaking data into smaller, manageable chunks, applications can provide a faster and more responsive user experience. 2. *Resource Efficiency*: Pagination minimizes the memory and CPU resources required for data retrieval. It ensures that only a portion of the dataset is loaded at any given time, reducing the application's resource footprint. -3. *User Experience*: Implementing pagination in applications makes it easier for users to navigate through extensive lists or datasets. It enables users to view data incrementally and access relevant information more quickly. +3. *User Experience*: Leveraging pagination in applications makes it easier for users to navigate through extensive lists or datasets. It enables users to view data incrementally and access relevant information more quickly. 4. *Scalability*: For applications that handle substantial amounts of data, pagination is essential for ensuring scalability. It prevents overloading the system and slowing down the application as the dataset grows. 5. *Responsive User Interfaces*: In web applications and graphical user interfaces (GUIs), pagination is essential for creating responsive, user-friendly interfaces. It allows users to access data with minimal latency. -Jakarta Data supports two main types of pagination: Offset and Keyset. These approaches differ in how they manage and retrieve paginated data: +Jakarta Data supports two types of pagination: Offset and Keyset. These approaches differ in how they manage and retrieve paginated data: Offset pagination is the more traditional form based on position relative to the first record in the dataset. It is typically used with a fixed page size, where a specified number of records is retrieved starting from a given offset position. @@ -1113,6 +1113,18 @@ Offset pagination offers several key features that make it a valuable approach f - *Sequential Order*: Elements are retrieved sequentially based on predefined criteria, such as ascending or descending order of a specific attribute, like an ID. +===== Requirements when using Offset Pagination + +The following requirements must be met when using offset-based pagination: + +* The repository method signature must return `Slice` or `Page`. A repository method with return type of `Slice` or `Page` must raise `UnsupportedOperationException` if the database is incapable of offset pagination. +* The repository method signature must accept a `Pageable` parameter. +* Sort criteria must be provided and should be minimal. +* The combination of provided sort criteria must define a deterministic ordering of entities. +* The entities within each page must be ordered according to the provided sort criteria. +* Except for the highest numbered page, the Jakarta Data provider must return full pages consisting of the maximum page size number of entities. +* Page numbers for offset pagination are computed by taking the entity's 1-based offset after sorting, dividing it by the maximum page size, and rounding up. For example, the 52nd entity is on page 6 when the maximum page size is 10, because 52 / 10 rounded up is 6. Note that the first page number is always 1. + ===== Scenario: Person Entity and People Repository Consider a scenario with a `Person` entity and a corresponding `People` repository: @@ -1270,7 +1282,8 @@ Other types of updates to data, however, will cause duplicate or missed results. * The repository method signature must return `KeysetAwareSlice` or `KeysetAwarePage`. A repository method with return type of `KeysetAwareSlice` or `KeysetAwarePage` must raise `UnsupportedOperationException` if the database is incapable of keyset pagination. * The repository method signature must accept a `Pageable` parameter. * Sort criteria must be provided and should be minimal. -* The combination of provided sort criteria must uniquely identify each entity. +* The combination of provided sort criteria must uniquely identify each entity such that the sort criteria defines a deterministic ordering of entities. +* The entities within each page must be ordered according to the provided sort criteria. * Page numbers for keyset pagination are estimated relative to prior page requests or the observed absence of further results and are not accurate. Page numbers must not be relied upon when using keyset pagination. * Page totals and result totals are not accurate for keyset pagination and must not be relied upon. * A next or previous page can end up being empty. You cannot obtain a next or previous `Pageable` from an empty page because there are no keyset values relative to which to query. @@ -1293,7 +1306,9 @@ Example traversal of pages: [source,java] ---- -for (Pageable p = Pageable.ofSize(25).sortBy(Sort.desc("yearBorn"), Sort.asc("name"), Sort.asc("id"))); +for (Pageable p = Pageable.ofSize(25).sortBy(Sort.desc("yearBorn"), + Sort.asc("name"), + Sort.asc("id"))); p != null; ) { page = customers.withAveragePurchaseAbove(50.0f, p); ... From cc458c5472f1b6f56d6dc5964856f87a149107f6 Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Mon, 13 Nov 2023 14:41:03 -0600 Subject: [PATCH 2/2] Update spec/src/main/asciidoc/repository.asciidoc Co-authored-by: Mark Swatosh --- spec/src/main/asciidoc/repository.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/src/main/asciidoc/repository.asciidoc b/spec/src/main/asciidoc/repository.asciidoc index fdfe01872..594c46645 100644 --- a/spec/src/main/asciidoc/repository.asciidoc +++ b/spec/src/main/asciidoc/repository.asciidoc @@ -1069,7 +1069,7 @@ KeysetAwarePage olderThan(int age, Pageable pagination); === Pagination in Jakarta Data -Dividing up large sets of data into pages is a beneficial strategy for data access and retrieval in many applications, including those developed in Java. Pagination helps improve the efficiency of handling large datasets in a way that is also user-friendly. In Jakarta Data, APIs are provided to help Java developers efficiently manage and navigate through data. This section discusses the importance of pagination in Java development and explores the two types of pagination that are available in Jakarta Data: Offset-based pagination and Keyset cursor-based pagination. +Dividing up large sets of data into pages is a beneficial strategy for data access and retrieval in many applications, including those developed in Java. Pagination helps improve the efficiency of handling large datasets in a way that is also user-friendly. In Jakarta Data, APIs are provided to help Java developers efficiently manage and navigate through data. image::02-pagination.png[alt=pagiantion sample, width=70%, height=70%]