FINERACT-2749: ft v2 paginated endpoints to resolve ambiguous OpenAPI response typing

fineract-provider/src/main/java/org/apache/fineract/commands/api/v2/AuditsV2Api.java

@@ -0,0 +1,30 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.commands.api.v2;
+
+import jakarta.ws.rs.core.UriInfo;
+import org.apache.fineract.commands.data.AuditData;
+import org.apache.fineract.commands.data.request.AuditRequest;
+import org.apache.fineract.infrastructure.core.service.Page;
+
+public interface AuditsV2Api {
+
+    Page<AuditData> retrieveAllAudits(UriInfo uriInfo, AuditRequest auditRequest, Integer offset, Integer limit, String orderBy,
+            String sortOrder, boolean includeJson);
+}

fineract-provider/src/main/java/org/apache/fineract/commands/api/v2/AuditsV2ApiDelegate.java

@@ -0,0 +1,98 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.commands.api.v2;
+
+import jakarta.ws.rs.core.UriInfo;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.commands.data.AuditData;
+import org.apache.fineract.commands.data.request.AuditRequest;
+import org.apache.fineract.commands.service.AuditReadPlatformService;
+import org.apache.fineract.infrastructure.core.api.ApiRequestParameterHelper;
+import org.apache.fineract.infrastructure.core.data.PaginationParameters;
+import org.apache.fineract.infrastructure.core.service.Page;
+import org.apache.fineract.infrastructure.security.utils.SQLBuilder;
+import org.springframework.stereotype.Component;
+
+@Component
+@RequiredArgsConstructor
+public class AuditsV2ApiDelegate implements AuditsV2Api {
+
+    private final AuditReadPlatformService auditReadPlatformService;
+    private final ApiRequestParameterHelper apiRequestParameterHelper;
+
+    @Override
+    public Page<AuditData> retrieveAllAudits(UriInfo uriInfo, AuditRequest auditRequest, Integer offset, Integer limit, String orderBy,
+            String sortOrder, boolean includeJson) {
+        final PaginationParameters parameters = PaginationParameters.builder().paged(true).limit(limit).offset(offset).orderBy(orderBy)
+                .sortOrder(sortOrder).build();
+        final SQLBuilder extraCriteria = getExtraCriteria(auditRequest);
+        return auditReadPlatformService.retrievePaginatedAuditEntries(extraCriteria, includeJson, parameters);
+    }
+
+    private SQLBuilder getExtraCriteria(AuditRequest auditRequest) {
+        SQLBuilder extraCriteria = new SQLBuilder();
+        extraCriteria.addNonNullCriteria("aud.action_name = ", auditRequest.getActionName());
+        if (auditRequest.getEntityName() != null) {
+            extraCriteria.addCriteria("aud.entity_name like", auditRequest.getEntityName() + "%");
+        }
+        extraCriteria.addNonNullCriteria("aud.resource_id = ", auditRequest.getResourceId());
+        extraCriteria.addNonNullCriteria("aud.maker_id = ", auditRequest.getMakerId());
+        extraCriteria.addNonNullCriteria("aud.checker_id = ", auditRequest.getCheckerId());
+        if (auditRequest.getMakerDateTimeFrom() != null) {
+            extraCriteria.addSubOperation((SQLBuilder criteria) -> {
+                criteria.addNonNullCriteria("aud.made_on_date >= ", auditRequest.getMakerDateTimeFrom(),
+                        SQLBuilder.WhereLogicalOperator.NONE);
+                criteria.addNonNullCriteria("aud.made_on_date_utc >= ", auditRequest.getMakerDateTimeFrom(),
+                        SQLBuilder.WhereLogicalOperator.OR);
+            });
+        }
+        if (auditRequest.getMakerDateTimeTo() != null) {
+            extraCriteria.addSubOperation((SQLBuilder criteria) -> {
+                criteria.addNonNullCriteria("aud.made_on_date <= ", auditRequest.getMakerDateTimeTo(),
+                        SQLBuilder.WhereLogicalOperator.NONE);
+                criteria.addNonNullCriteria("aud.made_on_date_utc <= ", auditRequest.getMakerDateTimeTo(),
+                        SQLBuilder.WhereLogicalOperator.OR);
+            });
+        }
+        if (auditRequest.getCheckerDateTimeFrom() != null) {
+            extraCriteria.addSubOperation((SQLBuilder criteria) -> {
+                criteria.addNonNullCriteria("aud.checked_on_date >= ", auditRequest.getCheckerDateTimeFrom(),
+                        SQLBuilder.WhereLogicalOperator.NONE);
+                criteria.addNonNullCriteria("aud.checked_on_date_utc >= ", auditRequest.getCheckerDateTimeFrom(),
+                        SQLBuilder.WhereLogicalOperator.OR);
+            });
+        }
+        if (auditRequest.getCheckerDateTimeTo() != null) {
+            extraCriteria.addSubOperation((SQLBuilder criteria) -> {
+                criteria.addNonNullCriteria("aud.checked_on_date <= ", auditRequest.getCheckerDateTimeTo(),
+                        SQLBuilder.WhereLogicalOperator.NONE);
+                criteria.addNonNullCriteria("aud.checked_on_date_utc <= ", auditRequest.getCheckerDateTimeTo(),
+                        SQLBuilder.WhereLogicalOperator.OR);
+            });
+        }
+        extraCriteria.addNonNullCriteria("aud.status = ", auditRequest.getStatus());
+        extraCriteria.addNonNullCriteria("aud.office_id = ", auditRequest.getOfficeId());
+        extraCriteria.addNonNullCriteria("aud.group_id = ", auditRequest.getGroupId());
+        extraCriteria.addNonNullCriteria("aud.client_id = ", auditRequest.getClientId());
+        extraCriteria.addNonNullCriteria("aud.loan_id = ", auditRequest.getLoanId());
+        extraCriteria.addNonNullCriteria("aud.savings_account_id = ", auditRequest.getSavingsAccountId());
+
+        return extraCriteria;
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/commands/api/v2/AuditsV2ApiResource.java

@@ -0,0 +1,67 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.commands.api.v2;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.ws.rs.BeanParam;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.Context;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.UriInfo;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.commands.data.AuditData;
+import org.apache.fineract.commands.data.request.AuditRequest;
+import org.apache.fineract.infrastructure.core.api.ApiRequestParameterHelper;
+import org.apache.fineract.infrastructure.core.service.Page;
+import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
+import org.springframework.stereotype.Component;
+
+@Path("/v2/audits")
+@Component
+@Tag(name = "AuditsV2", description = "V2 endpoint that always returns a paged response (totalFilteredRecords + pageItems) for audits, removing the ambiguous paged response typing of the v1 endpoint.")
+@RequiredArgsConstructor
+public class AuditsV2ApiResource {
+
+    private static final String RESOURCE_NAME_FOR_PERMISSIONS = "AUDIT";
+
+    private final PlatformSecurityContext context;
+    private final AuditsV2ApiDelegate delegate;
+    private final ApiRequestParameterHelper apiRequestParameterHelper;
+
+    @GET
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(summary = "List Audits", operationId = "retrieveAllAuditsV2", description = "Get a paged list of audits that match the criteria supplied and sorted by audit id in descending order, and are within the requestors' data scope. Unlike the v1 endpoint, this endpoint always returns a paged response containing totalFilteredRecords and pageItems.\n\n"
+            + "Example Requests:\n\n" + "audits\n\n" + "audits?fields=madeOnDate,maker,processingResult\n\n" + "audits?officeId=1\n\n"
+            + "audits?officeId=1&includeJson=true")
+    public Page<AuditData> retrieveAllAudits(@Context final UriInfo uriInfo, @BeanParam AuditRequest auditRequest,
+            @QueryParam("offset") @Parameter(description = "offset") final Integer offset,
+            @QueryParam("limit") @Parameter(description = "limit") final Integer limit,
+            @QueryParam("orderBy") @Parameter(description = "orderBy") final String orderBy,
+            @QueryParam("sortOrder") @Parameter(description = "sortOrder") final String sortOrder) {
+
+        context.authenticatedUser().validateHasReadPermission(RESOURCE_NAME_FOR_PERMISSIONS);
+        final boolean includeJson = apiRequestParameterHelper.process(uriInfo.getQueryParameters()).isIncludeJson();
+        return delegate.retrieveAllAudits(uriInfo, auditRequest, offset, limit, orderBy, sortOrder, includeJson);
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/group/api/v2/CentersV2Api.java

@@ -0,0 +1,29 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.group.api.v2;
+
+import org.apache.fineract.infrastructure.core.data.PaginationParameters;
+import org.apache.fineract.infrastructure.core.service.Page;
+import org.apache.fineract.infrastructure.core.service.SearchParameters;
+import org.apache.fineract.portfolio.group.data.CenterData;
+
+public interface CentersV2Api {
+
+    Page<CenterData> retrieveAllCenters(SearchParameters searchParameters, PaginationParameters parameters);
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/group/api/v2/CentersV2ApiDelegate.java

@@ -0,0 +1,39 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.group.api.v2;
+
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.infrastructure.core.data.PaginationParameters;
+import org.apache.fineract.infrastructure.core.service.Page;
+import org.apache.fineract.infrastructure.core.service.SearchParameters;
+import org.apache.fineract.portfolio.group.data.CenterData;
+import org.apache.fineract.portfolio.group.service.CenterReadPlatformService;
+import org.springframework.stereotype.Component;
+
+@Component
+@RequiredArgsConstructor
+public class CentersV2ApiDelegate implements CentersV2Api {
+
+    private final CenterReadPlatformService centerReadPlatformService;
+
+    @Override
+    public Page<CenterData> retrieveAllCenters(SearchParameters searchParameters, PaginationParameters parameters) {
+        return centerReadPlatformService.retrievePagedAll(searchParameters, parameters);
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/group/api/v2/CentersV2ApiResource.java

@@ -0,0 +1,75 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.group.api.v2;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.MediaType;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.infrastructure.core.data.PaginationParameters;
+import org.apache.fineract.infrastructure.core.service.Page;
+import org.apache.fineract.infrastructure.core.service.SearchParameters;
+import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
+import org.apache.fineract.infrastructure.security.service.SqlValidator;
+import org.apache.fineract.portfolio.group.api.GroupingTypesApiConstants;
+import org.apache.fineract.portfolio.group.data.CenterData;
+import org.springframework.stereotype.Component;
+
+@Path("/v2/centers")
+@Component
+@Tag(name = "CentersV2", description = "V2 endpoint that always returns a paged response (totalFilteredRecords + pageItems) for centers, removing the ambiguous paged response typing of the v1 endpoint. The non-paged meeting-date lookup branch of the v1 endpoint is intentionally omitted.")
+@RequiredArgsConstructor
+public class CentersV2ApiResource {
+
+    private final PlatformSecurityContext context;
+    private final CentersV2ApiDelegate delegate;
+    private final SqlValidator sqlValidator;
+
+    @GET
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(summary = "List Centers", operationId = "retrieveAllCentersV2", description = "Get a paged list of centers that match the criteria supplied and sorted by hierarchy. Unlike the v1 endpoint, this endpoint always returns a paged response containing totalFilteredRecords and pageItems.\n\n"
+            + "Example Requests:\n\n" + "centers\n\n" + "centers?fields=name,officeName,joinedDate\n\n" + "centers?offset=10&limit=50\n\n"
+            + "centers?orderBy=name&sortOrder=DESC")
+    public Page<CenterData> retrieveAllCenters(@QueryParam("officeId") @Parameter(description = "officeId") final Long officeId,
+            @QueryParam("staffId") @Parameter(description = "staffId") final Long staffId,
+            @QueryParam("externalId") @Parameter(description = "externalId") final String externalId,
+            @QueryParam("name") @Parameter(description = "name") final String name,
+            @QueryParam("underHierarchy") @Parameter(description = "underHierarchy") final String hierarchy,
+            @QueryParam("offset") @Parameter(description = "offset") final Integer offset,
+            @QueryParam("limit") @Parameter(description = "limit") final Integer limit,
+            @QueryParam("orderBy") @Parameter(description = "orderBy") final String orderBy,
+            @QueryParam("sortOrder") @Parameter(description = "sortOrder") final String sortOrder) {
+
+        context.authenticatedUser().validateHasReadPermission(GroupingTypesApiConstants.CENTER_RESOURCE_NAME);
+        sqlValidator.validate(orderBy);
+        sqlValidator.validate(sortOrder);
+        sqlValidator.validate(externalId);
+        sqlValidator.validate(hierarchy);
+        final PaginationParameters parameters = PaginationParameters.builder().paged(true).limit(limit).offset(offset).orderBy(orderBy)
+                .sortOrder(sortOrder).build();
+        final SearchParameters searchParameters = SearchParameters.builder().limit(limit).officeId(officeId).externalId(externalId)
+                .name(name).hierarchy(hierarchy).offset(offset).orderBy(orderBy).sortOrder(sortOrder).staffId(staffId).build();
+        return delegate.retrieveAllCenters(searchParameters, parameters);
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/group/api/v2/GroupsV2Api.java

@@ -0,0 +1,29 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.group.api.v2;
+
+import org.apache.fineract.infrastructure.core.data.PaginationParameters;
+import org.apache.fineract.infrastructure.core.service.Page;
+import org.apache.fineract.infrastructure.core.service.SearchParameters;
+import org.apache.fineract.portfolio.group.data.GroupGeneralData;
+
+public interface GroupsV2Api {
+
+    Page<GroupGeneralData> retrieveAllGroups(SearchParameters searchParameters, PaginationParameters parameters);
+}