BFD-4707: Eob updates for previous and next links on patient searches

apps/bfd-server-ng/src/main/java/gov/cms/bfd/server/ng/eob/EobHandler.java

@@ -2,6 +2,7 @@
 
 import static gov.cms.bfd.server.ng.util.MetricTimer.SAMHSA_FILTER_MODE;
 
+import ca.uhn.fhir.rest.api.server.RequestDetails;
 import gov.cms.bfd.server.ng.ClaimFilterOptions;
 import gov.cms.bfd.server.ng.ClaimSecurityStatus;
 import gov.cms.bfd.server.ng.SamhsaFilterMode;
@@ -68,9 +69,13 @@ public Optional<ExplanationOfBenefit> find(final Long fhirId, ClaimFilterOptions
    *
    * @param criteria filter criteria
    * @param options claim filter options
+   * @param requestDetails Hapi FHIR request details
    * @return bundle
    */
-  public Bundle searchByBene(ClaimSearchCriteria criteria, ClaimFilterOptions options) {
+  public Bundle searchByBene(
+      ClaimSearchCriteria criteria,
+      ClaimFilterOptions options,
+      Optional<RequestDetails> requestDetails) {
 
     var beneSk = criteria.beneSk();
     var beneXrefSk = beneficiaryRepository.getXrefSkFromBeneSk(beneSk);
@@ -98,11 +103,18 @@ public Bundle searchByBene(ClaimSearchCriteria criteria, ClaimFilterOptions opti
             () ->
                 filterSamhsaClaims(claims, options.getSamhsaFilterMode())
                     .skip(repositoryCriteria.resolveOffset())
-                    .limit(repositoryCriteria.resolveLimit())
+                    .limit(repositoryCriteria.resolveLimitWithExtra(1))
                     .map(claim -> transformToFhir(claim, options)),
             _ -> Tags.of(SAMHSA_FILTER_MODE, options.getSamhsaFilterMode().name()));
 
-    var bundle = FhirUtil.bundleOrDefault(filteredClaims, loadProgressRepository::lastUpdated);
+    var bundle =
+        FhirUtil.bundleOrDefault(
+            filteredClaims,
+            loadProgressRepository::lastUpdated,
+            requestDetails,
+            // we want the raw limit
+            Optional.of(repositoryCriteria.resolveLimit()),
+            Optional.of(repositoryCriteria.resolveOffset()));
     recordResultSize(bundle, options.getSamhsaFilterMode());
     return bundle;
   }
@@ -119,12 +131,21 @@ private Stream<? extends ClaimBase> filterSamhsaClaims(
     // Process claims in parallel
     // Note: DO NOT call toList() until the very end as materializing the list multiple times could
     // negatively impact perf.
-    var claimStream =
-        claims.parallelStream().sorted(Comparator.comparing(ClaimBase::getClaimUniqueId));
+    var claimStream = claims.parallelStream();
     return switch (samhsaFilterMode) {
-      case INCLUDE -> claimStream;
-      case ONLY_SAMHSA -> claimStream.filter(this::claimHasSamhsa);
-      case EXCLUDE -> claimStream.filter(claim -> !claimHasSamhsa(claim));
+      case INCLUDE -> claimStream.sorted(Comparator.comparing(ClaimBase::getClaimUniqueId));
+      // it is faster to filter unordered so if we are filtering we should do it unordered first
+      // before the id ordering
+      case ONLY_SAMHSA ->
+          claimStream
+              .unordered()
+              .filter(this::claimHasSamhsa)
+              .sorted(Comparator.comparing(ClaimBase::getClaimUniqueId));
+      case EXCLUDE ->
+          claimStream
+              .unordered()
+              .filter(claim -> !claimHasSamhsa(claim))
+              .sorted(Comparator.comparing(ClaimBase::getClaimUniqueId));
     };
   }
 

apps/bfd-server-ng/src/main/java/gov/cms/bfd/server/ng/eob/EobResourceProvider.java

@@ -1,11 +1,6 @@
 package gov.cms.bfd.server.ng.eob;
 
-import ca.uhn.fhir.rest.annotation.Count;
-import ca.uhn.fhir.rest.annotation.IdParam;
-import ca.uhn.fhir.rest.annotation.OptionalParam;
-import ca.uhn.fhir.rest.annotation.Read;
-import ca.uhn.fhir.rest.annotation.RequiredParam;
-import ca.uhn.fhir.rest.annotation.Search;
+import ca.uhn.fhir.rest.annotation.*;
 import ca.uhn.fhir.rest.api.Constants;
 import ca.uhn.fhir.rest.api.server.RequestDetails;
 import ca.uhn.fhir.rest.param.DateRangeParam;
@@ -82,12 +77,13 @@ public ExplanationOfBenefit find(
    * @param serviceDate service date
    * @param lastUpdated last updated
    * @param startIndex start index
+   * @param offset offset
    * @param tag tags to filter by
    * @param type claim type to filter by
    * @param source claim source to filter by
    * @param security security to filter SAMHSA by
-   * @param requestDetails request details object
    * @param request HTTP request details
+   * @param requestDetails HAPI FHIR request details
    * @return bundle
    */
   @Search
@@ -98,12 +94,13 @@ public Bundle searchByPatient(
       @OptionalParam(name = ExplanationOfBenefit.SP_RES_LAST_UPDATED)
           final DateRangeParam lastUpdated,
       @OptionalParam(name = START_INDEX) final NumberParam startIndex,
+      @Offset final Integer offset,
       @OptionalParam(name = Constants.PARAM_TAG) final TokenAndListParam tag,
       @OptionalParam(name = TYPE) final TokenAndListParam type,
       @OptionalParam(name = Constants.PARAM_SOURCE) final TokenAndListParam source,
       @OptionalParam(name = Constants.PARAM_SECURITY) final TokenAndListParam security,
-      final RequestDetails requestDetails,
-      final HttpServletRequest request) {
+      final HttpServletRequest request,
+      final RequestDetails requestDetails) {
 
     var includeTaxNumbers =
         FhirInputConverter.parseBooleanHeader(requestDetails, INCLUDE_TAX_NUMBERS_HEADER);
@@ -123,12 +120,14 @@ public Bundle searchByPatient(
             FhirInputConverter.toDateTimeRange(serviceDate),
             FhirInputConverter.toDateTimeRange(lastUpdated),
             Optional.ofNullable(count),
-            FhirInputConverter.toIntOptional(startIndex),
+            // we will support both offset and startIndex for now, but they can't be used together.
+            // If both are provided, offset will take precedence
+            Optional.ofNullable(offset).or(() -> FhirInputConverter.toIntOptional(startIndex)),
             tagCriteria,
             claimTypeCodes,
             FhirInputConverter.parseSourceParameter(source));
 
-    return eobHandler.searchByBene(criteria, options);
+    return eobHandler.searchByBene(criteria, options, Optional.of(requestDetails));
   }
 
   /**

apps/bfd-server-ng/src/main/java/gov/cms/bfd/server/ng/input/ClaimSearchCriteria.java

@@ -42,7 +42,17 @@ public Integer resolveOffset() {
    * @return limit
    */
   public Integer resolveLimit() {
-    return limit.orElse(5000);
+    return resolveLimitWithExtra(0);
+  }
+
+  /**
+   * Returns the limit or the default.
+   *
+   * @param extra extra to add for pagination checking than the requested limit
+   * @return limit
+   */
+  public Integer resolveLimitWithExtra(int extra) {
+    return limit.orElse(5000) + extra;
   }
 
   /**

apps/bfd-server-ng/src/main/java/gov/cms/bfd/server/ng/util/FhirUtil.java

@@ -1,21 +1,28 @@
 package gov.cms.bfd.server.ng.util;
 
+import ca.uhn.fhir.rest.api.Constants;
+import ca.uhn.fhir.rest.api.server.RequestDetails;
 import java.time.ZonedDateTime;
+import java.util.List;
 import java.util.Optional;
 import java.util.function.Supplier;
 import java.util.regex.Pattern;
+import java.util.stream.Collectors;
 import java.util.stream.Stream;
 import org.hl7.fhir.r4.model.Bundle;
 import org.hl7.fhir.r4.model.CodeableConcept;
 import org.hl7.fhir.r4.model.Coding;
 import org.hl7.fhir.r4.model.Meta;
 import org.hl7.fhir.r4.model.Resource;
+import org.springframework.web.util.UriComponentsBuilder;
 
 /** FHIR-related utility methods. */
 public class FhirUtil {
   private FhirUtil() {}
 
   private static final Pattern IS_INTEGER = Pattern.compile("\\d+");
+  private static final String OFFSET_PARAM = "_offset";
+  private static final String START_INDEX_PARAM = "startIndex";
 
   /**
    * Adds a data absent reason of the coding is empty.
@@ -50,37 +57,82 @@ public static String getHcpcsSystem(String code) {
 
   /**
    * Creates a bundle from the resource, returning a default bundle with lastUpdated populated if
-   * empty.
+   * adds previous link if an offset exists add a next link if the stream contains at least one more
+   * than the limit empty.
    *
    * @param resources resources
    * @param batchLastUpdated last updated
+   * @param requestDetails request details
+   * @param limit record count
+   * @param offset start index
    * @return bundle
    */
   public static Bundle bundleOrDefault(
-      Stream<? extends Resource> resources, Supplier<ZonedDateTime> batchLastUpdated) {
-    var bundle = getBundle(resources);
+      Stream<? extends Resource> resources,
+      Supplier<ZonedDateTime> batchLastUpdated,
+      Optional<RequestDetails> requestDetails,
+      Optional<Integer> limit,
+      Optional<Integer> offset) {
+    var bundle = getBundle(resources, requestDetails, limit, offset);
 
     if (bundle.getEntry().isEmpty()) {
       return defaultBundle(batchLastUpdated);
     }
     return bundle;
   }
 
+  /**
+   * Creates a bundle from the resource, returning a default bundle with lastUpdated populated if
+   * empty.
+   *
+   * @param resources resources
+   * @param batchLastUpdated last updated
+   * @return bundle
+   */
+  public static Bundle bundleOrDefault(
+      Stream<? extends Resource> resources, Supplier<ZonedDateTime> batchLastUpdated) {
+    return bundleOrDefault(
+        resources, batchLastUpdated, Optional.empty(), Optional.empty(), Optional.empty());
+  }
+
   /**
    * Creates a bundle from the resource, returning a default bundle with lastUpdated populated if
    * empty.
    *
    * @param resource resource
    * @param batchLastUpdated last updated
+   * @param requestDetails request details
+   * @param limit record count
+   * @param offset start index
    * @return bundle
    */
   public static Bundle bundleOrDefault(
-      Optional<Resource> resource, Supplier<ZonedDateTime> batchLastUpdated) {
+      Optional<Resource> resource,
+      Supplier<ZonedDateTime> batchLastUpdated,
+      Optional<RequestDetails> requestDetails,
+      Optional<Integer> limit,
+      Optional<Integer> offset) {
     return resource
-        .map(value -> bundleOrDefault(Stream.of(value), batchLastUpdated))
+        .map(
+            value ->
+                bundleOrDefault(Stream.of(value), batchLastUpdated, requestDetails, limit, offset))
         .orElseGet(() -> defaultBundle(batchLastUpdated));
   }
 
+  /**
+   * Creates a bundle from the resource, returning a default bundle with lastUpdated populated if
+   * empty.
+   *
+   * @param resource resource
+   * @param batchLastUpdated last updated
+   * @return bundle
+   */
+  public static Bundle bundleOrDefault(
+      Optional<Resource> resource, Supplier<ZonedDateTime> batchLastUpdated) {
+    return bundleOrDefault(
+        resource, batchLastUpdated, Optional.empty(), Optional.empty(), Optional.empty());
+  }
+
   /**
    * Builds the bundle and includes full urls to every entry in the bundle.
    *
@@ -112,9 +164,47 @@ public static Bundle bundleWithFullUrls(
     return bundle;
   }
 
-  private static Bundle getBundle(Stream<? extends Resource> resources) {
-    return new Bundle()
-        .setEntry(resources.map(r -> new Bundle.BundleEntryComponent().setResource(r)).toList());
+  private static Bundle getBundle(
+      Stream<? extends Resource> resources,
+      Optional<RequestDetails> requestDetails,
+      Optional<Integer> limit,
+      Optional<Integer> offset) {
+
+    record Page(List<Bundle.BundleEntryComponent> items, boolean hasMore) {}
+
+    var page =
+        resources
+            .map(r -> new Bundle.BundleEntryComponent().setResource(r))
+            .collect(
+                Collectors.teeing(
+                    Collectors.toList(),
+                    Collectors.counting(),
+                    // collecting and counting to see if we do have a next
+                    // limits the stream to only return the requested limit
+                    (list, count) ->
+                        new Page(
+                            trimEntriesToLimit(list, count, limit),
+                            determineHasMore(count, limit))));
+
+    var bundle = new Bundle().setEntry(page.items());
+
+    // if we do not have a request we cannot build the links
+    requestDetails.ifPresent(
+        details -> applyBundleLinks(bundle, details, page.hasMore(), offset, limit));
+
+    return bundle;
+  }
+
+  private static List<Bundle.BundleEntryComponent> trimEntriesToLimit(
+      List<Bundle.BundleEntryComponent> entries, long count, Optional<Integer> limit) {
+    if (limit.isPresent() && count > limit.get().longValue()) {
+      return entries.subList(0, limit.get());
+    }
+    return entries;
+  }
+
+  private static boolean determineHasMore(long count, Optional<Integer> limit) {
+    return limit.isPresent() && count > limit.get().longValue();
   }
 
   /**
@@ -128,4 +218,44 @@ public static Bundle defaultBundle(Supplier<ZonedDateTime> batchLastUpdated) {
     bundle.setMeta(new Meta().setLastUpdated(DateUtil.toDate(batchLastUpdated.get())));
     return bundle;
   }
+
+  private static void applyBundleLinks(
+      Bundle bundle,
+      RequestDetails requestDetails,
+      boolean hasMore,
+      Optional<Integer> offset,
+      Optional<Integer> limit) {
+    // check if a link is needed
+    if (hasMore) {
+      var nextOffset = Math.max(0, offset.orElse(0) + limit.orElse(0));
+      bundle
+          .addLink()
+          .setRelation(Constants.LINK_NEXT)
+          .setUrl(buildLinkURL(requestDetails, nextOffset));
+    }
+    // check if a previous link is needed
+    if (offset.isPresent() && offset.get() > 0) {
+      // get previous offset
+      var previousOffset = Math.max(0, offset.get() - limit.orElse(0));
+      bundle
+          .addLink()
+          .setRelation(Constants.LINK_PREVIOUS)
+          .setUrl(buildLinkURL(requestDetails, previousOffset));
+    }
+  }
+
+  private static String buildLinkURL(RequestDetails requestDetails, Integer offset) {
+    var uriBuilder = UriComponentsBuilder.fromUriString(requestDetails.getCompleteUrl());
+
+    // Remove offset and startIndex parameters
+    uriBuilder.replaceQueryParam(OFFSET_PARAM);
+    uriBuilder.replaceQueryParam(START_INDEX_PARAM);
+
+    // Add the new offset if it's not 0
+    if (offset != 0) {
+      uriBuilder.queryParam(OFFSET_PARAM, offset);
+    }
+
+    return uriBuilder.build().toUriString();
+  }
 }

apps/bfd-server-ng/src/test/java/gov/cms/bfd/server/ng/EobSamhsaFilterIT.java

@@ -162,7 +162,7 @@ private List<ExplanationOfBenefit> getClaimsByBene(long beneSk, ClaimFilterOptio
             Collections.emptyList(),
             List.of(),
             Collections.emptyList());
-    var claims = eobHandler.searchByBene(criteria, options);
+    var claims = eobHandler.searchByBene(criteria, options, Optional.empty());
     return getEobFromBundle(claims);
   }