feat: Add paging query param in tracker exporter favor of skipPaging (#…

…16196)

to align with metadata and other endpoints

dhis-2/dhis-test-web-api/src/test/java/org/hisp/dhis/webapi/controller/tracker/export/ExportControllerPaginationTest.java

@@ -143,6 +143,35 @@ void shouldGetPaginatedItemsWithDefaults() {
     assertHasNoMember(page, "pageCount");
   }
 
+  @Test
+  void shouldGetPaginatedItemsWithPagingSetToTrue() {
+    TrackedEntity to = trackedEntity();
+    Event from1 = event(enrollment(to));
+    Event from2 = event(enrollment(to));
+    Relationship r1 = relationship(from1, to);
+    Relationship r2 = relationship(from2, to);
+
+    JsonPage page =
+        GET("/tracker/relationships?trackedEntity={uid}&paging=true", to.getUid())
+            .content(HttpStatus.OK)
+            .asObject(JsonPage.class);
+
+    assertContainsOnly(
+        List.of(r1.getUid(), r2.getUid()),
+        page.getList("instances", JsonRelationship.class)
+            .toList(JsonRelationship::getRelationship));
+    assertEquals(1, page.getPager().getPage());
+    assertEquals(50, page.getPager().getPageSize());
+    assertHasNoMember(page.getPager(), "total");
+    assertHasNoMember(page.getPager(), "pageCount");
+
+    // assert deprecated fields
+    assertEquals(1, page.getPage());
+    assertEquals(50, page.getPageSize());
+    assertHasNoMember(page, "total");
+    assertHasNoMember(page, "pageCount");
+  }
+
   @Test
   void shouldGetPaginatedItemsWithDefaultsAndTotals() {
     TrackedEntity to = trackedEntity();
@@ -260,6 +289,32 @@ void shouldGetNonPaginatedItemsWithSkipPaging() {
     assertHasNoMember(page, "pageCount");
   }
 
+  @Test
+  void shouldGetNonPaginatedItemsWithPagingSetToFalse() {
+    TrackedEntity to = trackedEntity();
+    Event from1 = event(enrollment(to));
+    Event from2 = event(enrollment(to));
+    Relationship r1 = relationship(from1, to);
+    Relationship r2 = relationship(from2, to);
+
+    JsonPage page =
+        GET("/tracker/relationships?trackedEntity={uid}&paging=false", to.getUid())
+            .content(HttpStatus.OK)
+            .asObject(JsonPage.class);
+
+    assertContainsOnly(
+        List.of(r1.getUid(), r2.getUid()),
+        page.getList("instances", JsonRelationship.class)
+            .toList(JsonRelationship::getRelationship));
+    assertHasNoMember(page, "pager");
+
+    // assert deprecated fields
+    assertHasNoMember(page, "page");
+    assertHasNoMember(page, "pageSize");
+    assertHasNoMember(page, "total");
+    assertHasNoMember(page, "pageCount");
+  }
+
   private TrackedEntityType trackedEntityTypeAccessible() {
     TrackedEntityType type = trackedEntityType();
     type.getSharing().addUserAccess(userAccess());

dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/tracker/export/PageRequestParams.java

@@ -54,15 +54,35 @@ public interface PageRequestParams {
   /**
    * Indicates whether to return all items {@code skipPaging=true} or a page of items {@code
    * skipPaging=false}.
+   *
+   * @deprecated use {@link #getPaging} instead
    */
+  @Deprecated(since = "2.41")
   Boolean getSkipPaging();
 
+  /**
+   * Indicates whether to return all items {@code paging=false} or a page of items {@code
+   * paging=true}.
+   */
+  Boolean getPaging();
+
   /**
    * Indicates whether to return a page of items or all items. By default, responses are paginated.
+   *
+   * <p>Note: this assumes {@link #getPaging()} and {@link #getSkipPaging()} have been validated.
+   * Preference is given to {@link #getPaging()} as the other parameter is deprecated.
    */
   @OpenApi.Ignore
   default boolean isPaged() {
-    return !Boolean.TRUE.equals(getSkipPaging());
+    if (getPaging() != null) {
+      return Boolean.TRUE.equals(getPaging());
+    }
+
+    if (getSkipPaging() != null) {
+      return Boolean.FALSE.equals(getSkipPaging());
+    }
+
+    return true;
   }
 
   /** Indicates whether to include the total number of items and pages in the paginated response. */

dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/tracker/export/RequestParamsValidator.java

@@ -404,6 +404,13 @@ private static boolean orgUnitModeDoesNotRequireOrgUnit(
 
   public static void validatePaginationParameters(PageRequestParams params)
       throws BadRequestException {
+    if (params.getPaging() != null
+        && params.getSkipPaging() != null
+        && params.getPaging().equals(params.getSkipPaging())) {
+      throw new BadRequestException(
+          "Paging can either be enabled or disabled. Prefer 'paging' as 'skipPaging' will be removed.");
+    }
+
     if (!params.isPaged()
         && (ObjectUtils.firstNonNull(params.getPage(), params.getPageSize()) != null
             || Boolean.TRUE.equals(params.getTotalPages()))) {

dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/tracker/export/enrollment/EnrollmentRequestParams.java

@@ -65,7 +65,20 @@ public class EnrollmentRequestParams implements PageRequestParams {
   @OpenApi.Property(defaultValue = "false")
   private Boolean totalPages = false;
 
-  private Boolean skipPaging = false;
+  /**
+   * @deprecated use {@link #paging} instead
+   */
+  @Deprecated(since = "2.41")
+  @OpenApi.Property(defaultValue = "false")
+  private Boolean skipPaging;
+
+  // TODO(tracker): set paging=true once skipPaging is removed. Both cannot have a default right
+  // now. This would lead to invalid parameters if the user passes the other param i.e.
+  // skipPaging==paging.
+  // PageRequestParams.isPaged handles the default case of skipPaging==paging==null => paging
+  // enabled
+  @OpenApi.Property(defaultValue = "true")
+  private Boolean paging;
 
   private List<OrderCriteria> order = new ArrayList<>();
 

dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/tracker/export/event/EventRequestParams.java

@@ -76,7 +76,20 @@ public class EventRequestParams implements PageRequestParams {
   @OpenApi.Property(defaultValue = "false")
   private Boolean totalPages = false;
 
-  private Boolean skipPaging = false;
+  /**
+   * @deprecated use {@link #paging} instead
+   */
+  @Deprecated(since = "2.41")
+  @OpenApi.Property(defaultValue = "false")
+  private Boolean skipPaging;
+
+  // TODO(tracker): set paging=true once skipPaging is removed. Both cannot have a default right
+  // now. This would lead to invalid parameters if the user passes the other param i.e.
+  // skipPaging==paging.
+  // PageRequestParams.isPaged handles the default case of skipPaging==paging==null => paging
+  // enabled
+  @OpenApi.Property(defaultValue = "true")
+  private Boolean paging;
 
   private List<OrderCriteria> order = new ArrayList<>();
 

dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/tracker/export/event/EventsExportController.java

@@ -120,7 +120,6 @@ public EventsExportController(
   Page<ObjectNode> getEvents(EventRequestParams requestParams)
       throws BadRequestException, ForbiddenException {
     validatePaginationParameters(requestParams);
-
     EventOperationParams eventOperationParams = eventParamsMapper.map(requestParams);
 
     if (requestParams.isPaged()) {

dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/tracker/export/relationship/RelationshipRequestParams.java

@@ -58,7 +58,20 @@ public class RelationshipRequestParams implements PageRequestParams {
   @OpenApi.Property(defaultValue = "false")
   private Boolean totalPages = false;
 
-  private Boolean skipPaging = false;
+  /**
+   * @deprecated use {@link #paging} instead
+   */
+  @Deprecated(since = "2.41")
+  @OpenApi.Property(defaultValue = "false")
+  private Boolean skipPaging;
+
+  // TODO(tracker): set paging=true once skipPaging is removed. Both cannot have a default right
+  // now. This would lead to invalid parameters if the user passes the other param i.e.
+  // skipPaging==paging.
+  // PageRequestParams.isPaged handles the default case of skipPaging==paging==null => paging
+  // enabled
+  @OpenApi.Property(defaultValue = "true")
+  private Boolean paging;
 
   private List<OrderCriteria> order = new ArrayList<>();
 

dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/tracker/export/trackedentity/TrackedEntitiesExportController.java

@@ -131,6 +131,7 @@ Page<ObjectNode> getTrackedEntities(
       throws BadRequestException, ForbiddenException, NotFoundException {
     validatePaginationParameters(requestParams);
     TrackedEntityOperationParams operationParams = paramsMapper.map(requestParams, currentUser);
+
     if (requestParams.isPaged()) {
       PageParams pageParams =
           new PageParams(

dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/tracker/export/trackedentity/TrackedEntityRequestParams.java

@@ -72,7 +72,20 @@ public class TrackedEntityRequestParams implements PageRequestParams {
   @OpenApi.Property(defaultValue = "false")
   private Boolean totalPages = false;
 
-  private Boolean skipPaging = false;
+  /**
+   * @deprecated use {@link #paging} instead
+   */
+  @Deprecated(since = "2.41")
+  @OpenApi.Property(defaultValue = "false")
+  private Boolean skipPaging;
+
+  // TODO(tracker): set paging=true once skipPaging is removed. Both cannot have a default right
+  // now. This would lead to invalid parameters if the user passes the other param i.e.
+  // skipPaging==paging.
+  // PageRequestParams.isPaged handles the default case of skipPaging==paging==null => paging
+  // enabled
+  @OpenApi.Property(defaultValue = "true")
+  private Boolean paging;
 
   private List<OrderCriteria> order = new ArrayList<>();
 

dhis-2/dhis-web-api/src/test/java/org/hisp/dhis/webapi/controller/tracker/export/PageRequestParamsTest.java

@@ -29,9 +29,13 @@
 
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.params.provider.Arguments.arguments;
 
+import java.util.stream.Stream;
 import lombok.Data;
-import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
 
 class PageRequestParamsTest {
 
@@ -41,27 +45,41 @@ private static class PaginationParameters implements PageRequestParams {
     private Integer pageSize;
     private Boolean totalPages;
     private Boolean skipPaging;
+    private Boolean paging;
   }
 
-  @Test
-  void shouldBePagedIfSkipPagingIsNull() {
-    PaginationParameters parameters = new PaginationParameters();
-
-    assertTrue(parameters.isPaged());
+  private static Stream<Arguments> pagingEnabled() {
+    return Stream.of(
+        arguments(null, null),
+        arguments(true, null),
+        arguments(true, false),
+        arguments(true, true));
   }
 
-  @Test
-  void shouldBePagedIfSkipPagingIsFalse() {
+  @MethodSource("pagingEnabled")
+  @ParameterizedTest
+  void shouldBePaged(Boolean paging, Boolean skipPaging) {
     PaginationParameters parameters = new PaginationParameters();
-    parameters.setSkipPaging(false);
+    parameters.setPaging(paging);
+    parameters.setSkipPaging(skipPaging);
 
     assertTrue(parameters.isPaged());
   }
 
-  @Test
-  void shouldBeUnpagedIfSkipPagingIsTrue() {
+  private static Stream<Arguments> pagingDisabled() {
+    return Stream.of(
+        arguments(null, true),
+        arguments(false, null),
+        arguments(false, true),
+        arguments(false, false));
+  }
+
+  @MethodSource("pagingDisabled")
+  @ParameterizedTest
+  void shouldBeUnPaged(Boolean paging, Boolean skipPaging) {
     PaginationParameters parameters = new PaginationParameters();
-    parameters.setSkipPaging(true);
+    parameters.setPaging(paging);
+    parameters.setSkipPaging(skipPaging);
 
     assertFalse(parameters.isPaged());
   }

dhis-2/dhis-web-api/src/test/java/org/hisp/dhis/webapi/controller/tracker/export/RequestParamsValidatorTest.java

@@ -375,27 +375,29 @@ private static class PaginationParameters implements PageRequestParams {
     private Integer pageSize;
     private Boolean totalPages;
     private Boolean skipPaging;
+    private Boolean paging;
   }
 
   private static Stream<Arguments> mutuallyExclusivePaginationParameters() {
     return Stream.of(
-        arguments(null, 1, null, true),
-        arguments(null, 1, false, true),
-        arguments(null, 1, false, true),
-        arguments(1, 1, false, true),
-        arguments(1, 1, true, true),
-        arguments(null, null, true, true));
+        arguments(null, 1, null, true, false),
+        arguments(null, 1, false, true, false),
+        arguments(null, 1, false, true, false),
+        arguments(1, 1, false, true, false),
+        arguments(1, 1, true, true, false),
+        arguments(null, null, true, true, false));
   }
 
   @MethodSource("mutuallyExclusivePaginationParameters")
   @ParameterizedTest
   void shouldFailWhenGivenMutuallyExclusivePaginationParameters(
-      Integer page, Integer pageSize, Boolean totalPages, Boolean skipPaging) {
+      Integer page, Integer pageSize, Boolean totalPages, Boolean skipPaging, Boolean paging) {
     PaginationParameters paginationParameters = new PaginationParameters();
     paginationParameters.setPage(page);
     paginationParameters.setPageSize(pageSize);
     paginationParameters.setTotalPages(totalPages);
     paginationParameters.setSkipPaging(skipPaging);
+    paginationParameters.setPaging(paging);
 
     Exception exception =
         assertThrows(
@@ -404,31 +406,54 @@ void shouldFailWhenGivenMutuallyExclusivePaginationParameters(
     assertStartsWith("Paging cannot be skipped with", exception.getMessage());
   }
 
+  private static Stream<Arguments> mutuallyExclusiveSkipPaginationParameters() {
+    return Stream.of(arguments(1, 1, false, false, false), arguments(1, 1, false, true, true));
+  }
+
+  @MethodSource("mutuallyExclusiveSkipPaginationParameters")
+  @ParameterizedTest
+  void shouldFailWhenGivenMutuallyExclusiveSkipPaginationParameters(
+      Integer page, Integer pageSize, Boolean totalPages, Boolean skipPaging, Boolean paging) {
+    PaginationParameters paginationParameters = new PaginationParameters();
+    paginationParameters.setPage(page);
+    paginationParameters.setPageSize(pageSize);
+    paginationParameters.setTotalPages(totalPages);
+    paginationParameters.setSkipPaging(skipPaging);
+    paginationParameters.setPaging(paging);
+
+    Exception exception =
+        assertThrows(
+            BadRequestException.class, () -> validatePaginationParameters(paginationParameters));
+
+    assertStartsWith("Paging can either be enabled or disabled", exception.getMessage());
+  }
+
   private static Stream<Arguments> validPaginationParameters() {
     return Stream.of(
-        arguments(null, null, null, null),
-        arguments(null, null, null, false),
-        arguments(null, 1, true, null),
-        arguments(null, 1, false, null),
-        arguments(null, 1, false, false),
-        arguments(null, null, true, false),
-        arguments(1, 1, false, false),
-        arguments(null, null, true, null),
-        arguments(null, 1, true, false),
-        arguments(null, null, null, true),
-        arguments(null, null, false, true));
+        arguments(null, null, null, null, null),
+        arguments(null, null, null, false, true),
+        arguments(null, 1, true, null, null),
+        arguments(null, 1, false, null, null),
+        arguments(null, 1, false, false, true),
+        arguments(null, null, true, false, true),
+        arguments(1, 1, false, false, true),
+        arguments(null, null, true, null, null),
+        arguments(null, 1, true, false, true),
+        arguments(null, null, null, true, false),
+        arguments(null, null, false, true, false));
   }
 
   @MethodSource("validPaginationParameters")
   @ParameterizedTest
   void shouldPassWhenGivenValidPaginationParameters(
-      Integer page, Integer pageSize, Boolean totalPages, Boolean skipPaging)
+      Integer page, Integer pageSize, Boolean totalPages, Boolean skipPaging, Boolean paging)
       throws BadRequestException {
     PaginationParameters paginationParameters = new PaginationParameters();
     paginationParameters.setPage(page);
     paginationParameters.setPage(pageSize);
     paginationParameters.setTotalPages(totalPages);
     paginationParameters.setSkipPaging(skipPaging);
+    paginationParameters.setPaging(paging);
 
     validatePaginationParameters(paginationParameters);
   }