Feature/639 policy store api paging docu

CHANGELOG.md

@@ -36,12 +36,11 @@ _**For better traceability add the corresponding GitHub issue number in each cha
 - Integration Test Policy Store API Unhappy Path. #519
 - Support for SingleLevelUsageAsPlanned. #470
 - Documentation to describe the delegate process. #470
-- Added file for CC BY 4.0 license for TRG 7. #681
-- Paging for Policy Store API GET policies. #639
-  - New endpoint GET /irs/policies/paged.
-  - Supports sorting by multiple of the properties "bpn", "validUntil", "policyId", "createdOn", "action" with ascending / descending order. 
-  - Supports filtering by multiple of properties "bpn", "validUntil", "policyId" (AND).
-    - note: filtering by "createdOn", "validUntil" has not been implemted yet
+- Added file for CC BY 4.0 license for TRG 7 #681
+- Paging endpoint for Policy Store API: `GET /irs/policies/paged`. #639
+    - Supports multi-sort for the properties "bpn", "validUntil", "policyId", "createdOn", "action" with ascending / descending order.
+    - Supports AND-connected multi-filtering by the properties "bpn", "validUntil", "policyId".
+        - Note: filtering by "createdOn", "validUntil" will be implemented in a subsequent story.
 
 ## [5.1.4] - 2024-05-27
 

docs/src/api/irs-api.yaml

@@ -860,7 +860,7 @@ paths:
       - api_key: []
       summary: Lists the registered policies that should be accepted in EDC negotiation.
       tags:
-      - Item Relationship Service
+        - Policy Store API
     post:
       description: Register a policy that should be accepted in EDC negotiation.
       operationId: registerAllowedPolicy
@@ -917,7 +917,7 @@ paths:
       - api_key: []
       summary: Register a policy that should be accepted in EDC negotiation.
       tags:
-      - Item Relationship Service
+        - Policy Store API
     put:
       description: Updates existing policies.
       operationId: updateAllowedPolicy
@@ -970,7 +970,65 @@ paths:
       - api_key: []
       summary: Updates existing policies.
       tags:
-      - Item Relationship Service
+        - Policy Store API
+  /irs/policies/paged:
+    get:
+      description: |
+        Fetch a page of policies with options to filter and sort.
+
+        - **Filtering:**
+          `search=<property>,[EQUALS|STARTS_WITH|BEFORE_LOCAL_DATE|AFTER_LOCAL_DATE],<value>`.
+          Example: 'search=BPN,STARTS_WITH,BPNL12&search=policyId,STARTS_WITH,policy2'.
+
+        - **Sorting:**
+          `sort=<property>,[asc|desc]`.
+          Example: 'sort=BPN,asc&sort=policyId,desc'.
+
+        - **Paging:**
+          Example: `page=1&size=20`
+      operationId: getPoliciesPaged
+      parameters:
+        - description: List of business partner numbers.
+          in: query
+          name: businessPartnerNumbers
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                error:
+                  $ref: '#/components/examples/get-policies-paged-result'
+              schema:
+                $ref: '#/components/schemas/Page'
+          description: Successfully retrieved the paged policies
+        "401":
+          content:
+            application/json:
+              examples:
+                error:
+                  $ref: '#/components/examples/error-response-401'
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+          description: No valid authentication credentials.
+        "403":
+          content:
+            application/json:
+              examples:
+                error:
+                  $ref: '#/components/examples/error-response-403'
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+          description: Authorization refused by server.
+      security:
+        - api_key: [ ]
+      summary: Find policies.
+      tags:
+        - Policy Store API
   /irs/policies/{policyId}:
     delete:
       description: Removes a policy that should no longer be accepted in EDC negotiation.
@@ -1015,7 +1073,7 @@ paths:
       - api_key: []
       summary: Removes a policy that should no longer be accepted in EDC negotiation.
       tags:
-      - Item Relationship Service
+        - Policy Store API
   /irs/policies/{policyId}/bpnl/{bpnl}:
     delete:
       description: Removes a policy from BPNL that should no longer be accepted in
@@ -1032,7 +1090,7 @@ paths:
         required: true
         schema:
           type: string
-          pattern: "(BPN)[LSA][\\w\\d]{10}[\\w\\d]{2}"
+          pattern: "(BPNL)[\\w\\d]{10}[\\w\\d]{2}"
       responses:
         "200":
           description: OK
@@ -1068,7 +1126,7 @@ paths:
       summary: Removes a policy from BPNL that should no longer be accepted in EDC
         negotiation.
       tags:
-      - Item Relationship Service
+        - Policy Store API
 components:
   examples:
     aspect-models-list:
@@ -1459,6 +1517,69 @@ components:
         relationships: []
         submodels: []
         tombstones: []
+    get-policies-paged-result:
+      value:
+        content:
+          - bpn: BPNL1234567890AB
+            policy:
+              createdOn: 2024-07-08T12:01:19.4677109+02:00
+              permissions:
+                - action: use
+                  constraint:
+                    and: [ ]
+                    or:
+                      - leftOperand: Membership
+                        operator:
+                          '@id': eq
+                        rightOperand: active
+                      - leftOperand: FrameworkAgreement.traceability
+                        operator:
+                          '@id': eq
+                        rightOperand: active
+                      - leftOperand: PURPOSE
+                        operator:
+                          '@id': eq
+                        rightOperand: ID 3.1 Trace
+                - action: access
+                  constraint:
+                    and: [ ]
+                    or:
+                      - leftOperand: Membership
+                        operator:
+                          '@id': eq
+                        rightOperand: active
+                      - leftOperand: FrameworkAgreement.traceability
+                        operator:
+                          '@id': eq
+                        rightOperand: active
+                      - leftOperand: PURPOSE
+                        operator:
+                          '@id': eq
+                        rightOperand: ID 3.1 Trace
+              policyId: 13a8523f-c80a-40b8-9e43-faab47fbceaa
+              validUntil: 2025-07-08T12:01:19.4677109+02:00
+        empty: false
+        first: false
+        last: true
+        number: 1
+        numberOfElements: 1
+        pageable:
+          offset: 10
+          pageNumber: 1
+          pageSize: 10
+          paged: true
+          sort:
+            empty: true
+            sorted: false
+            unsorted: true
+          unpaged: false
+        size: 10
+        sort:
+          empty: true
+          sorted: false
+          unsorted: true
+        totalElements: 11
+        totalPages: 2
     job-handle:
       value:
         id: 6c311d29-5753-46d4-b32c-19b918ea93b0
@@ -2331,6 +2452,39 @@ components:
         lexicalValue:
           type: string
           example: piece
+    Page:
+      type: object
+      additionalProperties: false
+      properties:
+        content:
+          type: array
+          items:
+            type: object
+        empty:
+          type: boolean
+        first:
+          type: boolean
+        last:
+          type: boolean
+        number:
+          type: integer
+          format: int32
+        numberOfElements:
+          type: integer
+          format: int32
+        pageable:
+          $ref: '#/components/schemas/PageableObject'
+        size:
+          type: integer
+          format: int32
+        sort:
+          $ref: '#/components/schemas/SortObject'
+        totalElements:
+          type: integer
+          format: int64
+        totalPages:
+          type: integer
+          format: int32
     PageResult:
       type: object
       additionalProperties: false
@@ -2354,6 +2508,25 @@ components:
         totalElements:
           type: integer
           format: int32
+    PageableObject:
+      type: object
+      additionalProperties: false
+      properties:
+        offset:
+          type: integer
+          format: int64
+        pageNumber:
+          type: integer
+          format: int32
+        pageSize:
+          type: integer
+          format: int32
+        paged:
+          type: boolean
+        sort:
+          $ref: '#/components/schemas/SortObject'
+        unpaged:
+          type: boolean
     PartChainIdentificationKey:
       type: object
       additionalProperties: false
@@ -2757,6 +2930,16 @@ components:
           type: string
         payload:
           $ref: '#/components/schemas/AssetAdministrationShellDescriptor'
+    SortObject:
+      type: object
+      additionalProperties: false
+      properties:
+        empty:
+          type: boolean
+        sorted:
+          type: boolean
+        unsorted:
+          type: boolean
     Submodel:
       type: object
       additionalProperties: false

irs-api/src/main/java/org/eclipse/tractusx/irs/configuration/OpenApiExamples.java

@@ -23,7 +23,13 @@
  ********************************************************************************/
 package org.eclipse.tractusx.irs.configuration;
 
+import static org.eclipse.tractusx.irs.edc.client.policy.ConstraintConstants.ACTIVE_MEMBERSHIP;
+import static org.eclipse.tractusx.irs.edc.client.policy.ConstraintConstants.FRAMEWORK_AGREEMENT_TRACEABILITY_ACTIVE;
+import static org.eclipse.tractusx.irs.edc.client.policy.ConstraintConstants.PURPOSE_ID_3_1_TRACE;
+
+import java.time.OffsetDateTime;
 import java.time.ZonedDateTime;
+import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 import java.util.UUID;
@@ -66,11 +72,18 @@
 import org.eclipse.tractusx.irs.component.enums.ProcessStep;
 import org.eclipse.tractusx.irs.component.enums.ProcessingState;
 import org.eclipse.tractusx.irs.dtos.ErrorResponse;
+import org.eclipse.tractusx.irs.edc.client.policy.Constraints;
+import org.eclipse.tractusx.irs.edc.client.policy.Permission;
+import org.eclipse.tractusx.irs.edc.client.policy.Policy;
+import org.eclipse.tractusx.irs.edc.client.policy.PolicyType;
 import org.eclipse.tractusx.irs.ess.service.NotificationSummary;
+import org.eclipse.tractusx.irs.policystore.models.PolicyWithBpn;
 import org.eclipse.tractusx.irs.semanticshub.AspectModel;
 import org.eclipse.tractusx.irs.semanticshub.AspectModels;
 import org.eclipse.tractusx.irs.util.JsonUtil;
 import org.springframework.beans.support.PagedListHolder;
+import org.springframework.data.domain.PageImpl;
+import org.springframework.data.domain.PageRequest;
 import org.springframework.http.HttpStatus;
 
 /**
@@ -139,6 +152,28 @@ public void createExamples(final Components components) {
         components.addExamples("canceled-job-response", createCanceledJobResponse());
         components.addExamples("complete-job-list-processing-state", createJobListProcessingState());
         components.addExamples("aspect-models-list", createAspectModelsResult());
+        components.addExamples("get-policies-paged-result", createPageOfPolicies());
+    }
+
+    private Example createPageOfPolicies() {
+        final PageImpl<PolicyWithBpn> page = new PageImpl<>(List.of(new PolicyWithBpn("BPNL1234567890AB",
+                Policy.builder()
+                      .policyId("13a8523f-c80a-40b8-9e43-faab47fbceaa")
+                      .createdOn(OffsetDateTime.parse("2024-07-08T12:01:19.4677109+02:00"))
+                      .validUntil(OffsetDateTime.parse("2025-07-08T12:01:19.4677109+02:00"))
+                      .permissions(createPermissions())
+                      .build())), PageRequest.of(1, 10), 1);
+        return toExample(page);
+    }
+
+    private List<Permission> createPermissions() {
+        return List.of(new Permission(PolicyType.USE, createConstraints()),
+                new Permission(PolicyType.ACCESS, createConstraints()));
+    }
+
+    private Constraints createConstraints() {
+        return new Constraints(Collections.emptyList(),
+                List.of(ACTIVE_MEMBERSHIP, FRAMEWORK_AGREEMENT_TRACEABILITY_ACTIVE, PURPOSE_ID_3_1_TRACE));
     }
 
     private Example createAspectModelsResult() {
@@ -394,22 +429,24 @@ private Tombstone createTombstone() {
     }
 
     private Shell createShell() {
-        return new Shell(EXAMPLE_ID,
-                AssetAdministrationShellDescriptor.builder()
-                                                           .description(List.of(LangString.builder()
-                                                                                .language("en")
-                                                                                .text("The shell for a vehicle")
-                                                                                .build()))
-                                                           .globalAssetId("urn:uuid:a45a2246-f6e1-42da-b47d-5c3b58ed62e9")
-                                                           .idShort("future concept x")
-                                                           .id("urn:uuid:882fc530-b69b-4707-95f6-5dbc5e9baaa8")
-                                                           .specificAssetIds(List.of(IdentifierKeyValuePair.builder()
-                                                                                                 .name("engineserialid")
-                                                                                                 .value("12309481209312")
-                                                                                                 .build()))
-                                                           .submodelDescriptors(List.of(createBaseSubmodelDescriptor(),
-                                                         createPartSubmodelDescriptor()))
-                                                           .build());
+        return new Shell(EXAMPLE_ID, AssetAdministrationShellDescriptor.builder()
+                                                                       .description(List.of(LangString.builder()
+                                                                                                      .language("en")
+                                                                                                      .text("The shell for a vehicle")
+                                                                                                      .build()))
+                                                                       .globalAssetId(
+                                                                               "urn:uuid:a45a2246-f6e1-42da-b47d-5c3b58ed62e9")
+                                                                       .idShort("future concept x")
+                                                                       .id("urn:uuid:882fc530-b69b-4707-95f6-5dbc5e9baaa8")
+                                                                       .specificAssetIds(
+                                                                               List.of(IdentifierKeyValuePair.builder()
+                                                                                                             .name("engineserialid")
+                                                                                                             .value("12309481209312")
+                                                                                                             .build()))
+                                                                       .submodelDescriptors(
+                                                                               List.of(createBaseSubmodelDescriptor(),
+                                                                                       createPartSubmodelDescriptor()))
+                                                                       .build());
     }
 
     private Relationship createRelationship() {

irs-api/src/test/java/org/eclipse/tractusx/irs/IrsApplicationTests.java

@@ -107,6 +107,7 @@ void generatedOpenApiMatchesContract() throws Exception {
         } catch (AssertionError e) {
             // write changed API to file for easier comparison
             Files.writeString(Paths.get("../docs/src/api/irs-api.actual.yaml"), generatedYaml);
+            throw e;
         }
 
     }