add readme doc for pagination

Author: lucas-amiaud

plume-db-querydsl/README.md

@@ -64,3 +64,114 @@ Code generation
 To generate Querydsl entities, a good choice is to use this
 [Querydsl code generator](https://github.com/Coreoz/Plume/tree/master/plume-db-querydsl-codegen).
 
+Pagination
+----------
+**Overview**:
+
+The `SqlPaginatedQuery` class provides a robust and flexible mechanism for paginating results in a QueryDSL query. It abstracts the pagination logic into two generic interfaces —`Slice` and `Page`— which represent paginated results in different ways.
+
+- `Page<U>`: A `Page` contains a list of results, total count of items, total number of pages, and a flag to indicate if there are more pages available.
+- `Slice<U>`: A `Slice` contains a list of results and a flag to indicate if there are more items to be fetched, without calculating the total number of items or pages.
+
+This allows you to manage and paginate large datasets efficiently when working with QueryDSL.
+
+**Key Features**:
+
+- **Pagination Logic**: Handles offset-based pagination by calculating the number of records to skip (`offset`) and the number of records to fetch (`limit`) using the page number and page size.
+- **Sorting Support**: Allows dynamic sorting of query results by providing an `Expression` and an `Order` (ascending/descending).
+- **Efficient Slicing**: Fetches a "slice" of data without loading the entire dataset, useful when you only need to know if there are more results to load (e.g., in infinite scroll scenarios).
+- **Full Page Information**: Provides detailed information about the paginated dataset, including the total count, total pages, and whether there are more results.
+
+**Working with Pagination from a WebService**:
+
+First, you need to create a translation between the API sort key and a table column.
+This can be done like this: 
+
+```java
+public enum SortPath {
+
+    // users
+    USER_LIST_EMAIL("email", QUser.user.email),
+    USER_LIST_FIRST_NAME("first_name", QUser.user.firstName),
+    USER_LIST_LAST_NAME("last_name", QUser.user.lastName),
+    USER_LIST_LAST_LOGIN_DATE("last_login_date", QUser.user.lastLogin),
+    // more complex cases
+    PRIORITY(
+        "user_priority",
+        new CaseBuilder()
+            .when(QUser.user.priority.eq(StudyPriority.MEDIUM.name())).then(1)
+            .when(QUser.user.priority.eq(StudyPriority.HIGH.name())).then(2)
+            .when(QUser.user.priority.eq(StudyPriority.VERY_HIGH.name())).then(3)
+            .otherwise(1)
+    ),
+    ;
+
+    private final String sortKey;
+    private final Expression<?> path;
+
+    @Nullable
+    public static SortPath fromSortKey(String sortKey) {
+        return Arrays.stream(SortPath.values())
+            .filter(entry -> entry.sortKey.equals(sortKey))
+            .findFirst()
+            .orElse(null);
+    }
+}
+```
+
+Then declare your WebService:
+
+```java
+@POST
+@Path("/search")
+@Operation(description = "Retrieves admin users")
+@Consumes(MediaType.APPLICATION_JSON)
+public Page<AdminUser> searchUsers(
+    @QueryParam("page") Long page,
+    @QueryParam("size") Long size,
+    @QueryParam("sort") String sort,
+    @QueryParam("sortDirection") Order sortDirection,
+    UserSearchRequest userSearchRequest
+) {
+    // check the pagination that comes from the API call
+    if (page < 1) {
+        throw new WsException(WsError.REQUEST_INVALID, List.of("page"));
+    }
+    if (size < 1) {
+        throw new WsException(WsError.REQUEST_INVALID, List.of("size"));
+    }
+    return usersDao.searchUsers(
+        userSearchRequest,
+        page,
+        size,
+        SortPath.fromSortKey(sort),
+        sortDirection
+    );
+}
+```
+
+Then apply the pagination from the API call with `SqlPaginatedQuery` : 
+
+```java
+public Page<AdminUser> searchUsers(
+    UserSearchRequest userSearchRequest,
+    Long page,
+    Long size,
+    Expression<?> path,
+    Order sortDirection
+) {
+    return SqlPaginatedQuery
+        .fromQuery(
+            this.transactionManagerQuerydsl.selectQuery()
+                .select(QUser.user)
+                .from(QUser.user)
+                .where(
+                    QUser.user.firstName.containsIgnoreCase(userSearchRequest.searchText())
+                        .or(QUser.user.lastName.containsIgnoreCase(userSearchRequest.searchText()))
+                        .or(QUser.user.email.containsIgnoreCase(userSearchRequest.searchText()))
+                )
+        )
+        .withSort(path, sortDirection)
+        .fetchPage(page, size);
+}
+```

plume-db-querydsl/src/test/java/com/coreoz/plume/db/querydsl/pagination/SqlPaginatedQueryTest.java

@@ -38,10 +38,9 @@ public void fetch_page_with_correct_pagination_should_paginate_users() {
             .withSort(QUser.user.name, Order.DESC)
             .fetchPage(1, 10);
 
-        assertThat(page.pagesCount()).isNotZero();
-        assertThat(page.totalCount()).isNotZero();
-        assertThat(page.items()).isNotEmpty();
-        assertThat(page.pagesCount()).isNotZero();
+        assertThat(page.pagesCount()).isEqualTo(1);
+        assertThat(page.totalCount()).isEqualTo(10);
+        assertThat(page.items()).hasSize(10);
         assertThat(page.hasMore()).isFalse();
     }
 
@@ -56,10 +55,9 @@ public void fetch_page_with_wrong_pagination_should_return_empty_items() {
             .withSort(QUser.user.name, Order.DESC)
             .fetchPage(2, 10);
 
-        assertThat(page.pagesCount()).isNotZero();
-        assertThat(page.totalCount()).isNotZero();
+        assertThat(page.pagesCount()).isEqualTo(1);
+        assertThat(page.totalCount()).isEqualTo(10);
         assertThat(page.items()).isEmpty();
-        assertThat(page.pagesCount()).isNotZero();
         assertThat(page.hasMore()).isFalse();
     }
 
@@ -74,8 +72,8 @@ public void fetch_page_with_minimum_page_and_page_size_should_return_results() {
             .withSort(QUser.user.name, Order.ASC)
             .fetchPage(1, 1); // Minimum page number and page size
 
-        assertThat(page.pagesCount()).isNotZero();
-        assertThat(page.totalCount()).isNotZero();
+        assertThat(page.pagesCount()).isEqualTo(10);
+        assertThat(page.totalCount()).isEqualTo(10);
         assertThat(page.items()).hasSize(1); // Only one item expected due to page size of 1
         assertThat(page.hasMore()).isTrue(); // Has more items since page size is small
     }
@@ -91,8 +89,8 @@ public void fetch_page_with_page_size_larger_than_total_results_should_return_al
             .withSort(QUser.user.name, Order.ASC)
             .fetchPage(1, 100); // Large page size compared to available results
 
-        assertThat(page.totalCount()).isGreaterThan(0);
-        assertThat(page.items().size()).isLessThanOrEqualTo(100); // Should return all available users
+        assertThat(page.totalCount()).isEqualTo(10);
+        assertThat(page.items()).hasSize(10); // Should return all available users
         assertThat(page.hasMore()).isFalse(); // No more items because page size exceeds total results
     }
 
@@ -130,9 +128,9 @@ public void fetch_page_without_sorting_should_paginate_users() {
             )
             .fetchPage(1, 10); // No sorting applied
 
-        assertThat(page.pagesCount()).isNotZero();
-        assertThat(page.totalCount()).isNotZero();
-        assertThat(page.items()).isNotEmpty();
+        assertThat(page.pagesCount()).isEqualTo(1);
+        assertThat(page.totalCount()).isEqualTo(10);
+        assertThat(page.items()).hasSize(10);
         assertThat(page.hasMore()).isFalse(); // Assuming there aren't more than 10 users in the test
     }
 

plume-db/src/main/java/com/coreoz/plume/db/pagination/Page.java

@@ -3,16 +3,15 @@
 import javax.annotation.Nonnull;
 import java.util.List;
 import java.util.function.Function;
-import java.util.stream.Collectors;
 
 /**
  * Represents a page of data in a paginated structure.
  *
  * @param items the items in the page
  * @param totalCount the total number of items in the collection
  * @param pagesCount the total number of pages
- * @param currentPage the current page
- * @param hasMore boolean set to true if there is another page after
+ * @param currentPage the current page, starts at 1
+ * @param hasMore boolean set to true if there is another page after this one
  *
  * @param <T> The type of items contained in the page.
  */

plume-db/src/main/java/com/coreoz/plume/db/pagination/Slice.java

@@ -8,7 +8,7 @@
  * Represents a portion (or slice) of a larger dataset.
  *
  * @param items the items in the slice
- * @param hasMore boolean set to true if there is another slice after
+ * @param hasMore boolean set to true if there is another slice after this one
  *
  * @param <T> The type of elements contained in the slice.
  */