Support cursor-based pagination (RFC 9865) #280
Conversation
RFC 9865 is an update to the SCIM 2 standard that defines cursor pagination, an alternative to the index-based API pagination defined in RFC 7644. This allows SCIM services to offer an alternative means for paginating list responses if index-based pagination is not feasible to implement. For more background on cursor-based pagination, see the documentation for the new PaginationConfig class. The SCIM SDK has been updated to support all newly defined parameters in this standard update, including new exception types. This includes updates to the client, server, and common libraries. These changes are designed to preserve backward compatibility for SCIM applications that do not need cursor-based pagination, so the SDK is still compatible with clients and services that do not yet support RFC 9865. Reviewer: vyhhuang Reviewer: dougbulkley JiraIssue: DS-50973
| * | ||
| * @since 5.0.0 | ||
| */ | ||
| void previousCursor(@Nullable final String previousCursor); |
There was a problem hiding this comment.
Because of the update to this interface, this technically requires a major version bump if any client code is implementing this handler. Fortunately, the next release is already going to be 5.0.0.
| * @since 5.0.0 | ||
| */ | ||
| @NotNull | ||
| public SearchRequestBuilder firstPageCursorWithCount(final int count) |
There was a problem hiding this comment.
I included "WithCount" because a call like firstPageCursor(10) seemed very confusing.
| public ListResponse(final int totalResults, | ||
| @NotNull final List<T> resources, | ||
| @Nullable final Integer startIndex, | ||
| @Nullable final Integer itemsPerPage) |
There was a problem hiding this comment.
This constructor matches the old @JsonCreator one for backward compatibility.
| public ListResponse(final int totalResults, | ||
| @Nullable final String nextCursor, | ||
| @Nullable final Integer itemsPerPage, | ||
| @NotNull final List<T> resources) |
There was a problem hiding this comment.
This constructor felt useful. Note that I placed resources last because without this, existing code like following would result in compile errors after an upgrade to 5.0.0:
new ListResponse<>(100, List.of(), null, null);Placing resources last resolves this problem so that the compiler knows there is only one constructor that matches this. To make this much more apparent, I've added unit test cases that explicitly pass null here if we update these in the future.
| public void testSerialization() throws Exception | ||
| { | ||
| // Test case insensitivity | ||
| SearchRequest searchRequest = JsonUtils.getObjectReader(). |
There was a problem hiding this comment.
I added my new test case and realized it also encompassed some behavior of this existing test. I replaced the old one since the class now matches other serialization tests in the SDK better.
| * @throws IOException If an exception occurs while writing to the output | ||
| * stream. | ||
| */ | ||
| public void nextCursor(@NotNull final String nextCursor) throws IOException |
There was a problem hiding this comment.
This is specifically used by SimpleSearchResults.
RFC 9865 is an update to the SCIM 2 standard that defines cursor pagination, an alternative to the index-based API pagination defined in RFC 7644. This allows SCIM services to offer an alternative means for paginating list responses if index-based pagination is not feasible to implement. For more background on cursor-based pagination, see the documentation for the new PaginationConfig class.
The SCIM SDK has been updated to support all newly defined parameters in this standard update, including new exception types. This includes updates to the client, server, and common libraries. These changes are designed to preserve backward compatibility for SCIM applications that do not need cursor-based pagination, so the SDK is still compatible with clients and services that do not yet support RFC 9865.
Reviewer: vyhhuang
Reviewer: dougbulkley
JiraIssue: DS-50973