Package com.shri.restinpeace.annotation.pagination

Annotation Type Paginated

@Target(METHOD) @Retention(RUNTIME) public @interface Paginated
Declares that a method's response is paginated - following a next-page pointer automatically, extracting each page's items into a Page<T>, instead of leaving the fetch-extract-repeat loop to hand-written code. See docs/design/pagination-helper.md for the full design, every default, and the exhaustive catalogue of real-world shapes this is built to cover (§9). 
 @GET("/orders")
 @Paginated(itemsField = "orders", pointerField = "next")
 Page<Order> listOrders(@QueryParam("cursor") @PaginationCursor String cursor);

Every rollout chunk in the design doc's plan (§12) has landed: a PointerKind.FULL_URL/PointerKind.VALUE pointer sourced from PaginationSignalSource.RESPONSE_BODY/ PaginationSignalSource.RESPONSE_HEADER/ PaginationSignalSource.ITEM_FIELD (keyset pagination, including an N-way composite key, and RFC 8288 Link response headers), resent via @QueryParam/@PathParam/@HeaderParam/ @Body, with hasMoreSource/totalSource/ totalPagesSource termination signals, PaginationAdvance client-driven offset/page-number advancement when there's no server-given pointer at all (pointerSource = NONE), and a Page<T>/Stream<T>/Iterator<T> return type, including an async first fetch via CompletableFuture<Page<T>>. Whatever this closed attribute vocabulary can't reach, a PaginationStrategy parameter is the fully programmatic escape hatch instead - mutually exclusive with this annotation on the same method. Only a fully async iteration protocol (Page<T>.next() itself returning a future) remains deliberately deferred (§11) - RIP.getClient(...) rejects that shape by name rather than silently misbehaving at call time.

  • Element Details

    • itemsField

      String itemsField
      Dotted path to the items array within the response body; empty means the response body itself is the array (no wrapper object).
      Returns:
      the dotted path to the items array, or "" for the response body itself
      Default:
      ""

    • pointerKind

      PointerKind pointerKind
      Whether the extracted pointer is a complete URL or a bare value to resend via a @PaginationCursor carrier.
      Returns:
      the pointer's kind
      Default:
      VALUE

    • pointerSource

      PaginationSignalSource pointerSource
      Where the next-page pointer is read from.
      Returns:
      the pointer's source
      Default:
      RESPONSE_BODY

    • pointerField

      String pointerField
      Where the pointer is read from within that source: a dotted body path, a header name, or - for PaginationSignalSource.ITEM_FIELD keyset pagination - a comma-separated list of item field names for an N-way composite key.
      Returns:
      the pointer's field/header name, or comma-separated names for a composite keyset
      Default:
      ""

    • advance

      PaginationAdvance advance
      How the client advances when there's no server-given pointer at all (pointerSource = NONE) - only meaningful together with pointerSource = NONE; a hasMoreSource/totalSource/ totalPagesSource termination signal, if set, still takes precedence over the advance-based fallback (§6.5).
      Returns:
      the client-driven advancement style
      Default:
      NONE

    • pageSize

      int pageSize
      The page size PaginationAdvance.INCREMENT_BY_PAGE_SIZE advances the offset by, and - absent any other termination signal - compares against the fetched item count to detect a short (final) page.
      Returns:
      the page size, meaningless unless advance() is INCREMENT_BY_PAGE_SIZE
      Default:
      0

    • hasMoreSource

      PaginationSignalSource hasMoreSource
      Where a "more pages exist" boolean signal is read from, if any - authoritative over pointer presence when set (§6.5).
      Returns:
      the hasMore signal's source, or NONE if the API gives no such signal
      Default:
      NONE

    • hasMoreField

      String hasMoreField
      Where the hasMoreSource() boolean is read from within that source.
      Returns:
      the hasMore field's dotted path or header name
      Default:
      ""

    • totalSource

      PaginationSignalSource totalSource
      Where a total-record-count signal is read from, if any - compared against a running fetched-items counter for termination (§6.5).
      Returns:
      the total-record-count signal's source, or NONE if the API gives no such signal
      Default:
      NONE

    • totalField

      String totalField
      Where the totalSource() record count is read from within that source.
      Returns:
      the total-record-count field's dotted path or header name
      Default:
      ""

    • totalPagesSource

      PaginationSignalSource totalPagesSource
      Where a total-page-count signal is read from, if any - compared against a running fetched-pages counter for termination (§6.5).
      Returns:
      the total-page-count signal's source, or NONE if the API gives no such signal
      Default:
      NONE

    • totalPagesField

      String totalPagesField
      Where the totalPagesSource() page count is read from within that source.
      Returns:
      the total-page-count field's dotted path or header name
      Default:
      ""