Merge commit from fork

Fix memory leak and thread-safety issues in pagination

Author: sameerbamanha-okta

api/src/main/java/com/okta/sdk/helper/PaginationUtil.java

@@ -15,11 +15,6 @@
  */
 packagecom.okta.sdk.helper;
 
-importcom.okta.commons.lang.Assert;
-importcom.okta.sdk.resource.client.ApiClient;
-importorg.slf4j.Logger;
-importorg.slf4j.LoggerFactory;
-
 importjava.io.UnsupportedEncodingException;
 importjava.net.MalformedURLException;
 importjava.net.URL;
@@ -29,6 +24,12 @@
 importjava.util.List;
 importjava.util.Map;
 
+importorg.slf4j.Logger;
+importorg.slf4j.LoggerFactory;
+
+importcom.okta.commons.lang.Assert;
+importcom.okta.sdk.resource.client.ApiClient;
+
 /**
  * Helper class for Pagination related functions.
  *
@@ -45,7 +46,9 @@ public class PaginationUtil{
  *
  * @param apiClient{@link ApiClient} instance
  * @return the 'after' resource id
+ * @deprecated Use{@link com.okta.sdk.resource.client.PagedIterable} instead for automatic pagination
  */
+@Deprecated(forRemoval = true, since = "24.1.0")
 publicstaticStringgetAfter(ApiClientapiClient){
 returngetAfter(getNextPage(apiClient));
  }
@@ -79,6 +82,7 @@ private static String getAfter(String nextPage){
  * @param apiClient the{@link ApiClient} instance
  * @return the next page URL string
  */
+@SuppressWarnings("removal")
 privatestaticStringgetNextPage(ApiClientapiClient){
 
 Assert.notNull(apiClient, "apiClient cannot be null");

api/src/main/java/com/okta/sdk/resource/client/ApiResponse.java

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2025-Present, Okta, Inc.
+ *
+ * Licensed 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.
+ */
+packagecom.okta.sdk.resource.client;
+
+importjava.util.List;
+importjava.util.Map;
+
+/**
+ * A stateless data object that represents a complete API response.
+ * 
+ * This class packages together everything from an HTTP response:
+ * - The response body (deserialized data)
+ * - The response headers (including Link headers for pagination)
+ * - The HTTP status code (200, 404, etc.)
+ * 
+ * Unlike the old approach which stored headers in a shared HashMap,
+ * ApiResponse is an immutable, thread-safe object that can be passed
+ * around without side effects.
+ * 
+ * Example usage:
+ * <pre>
+ * ApiResponse&lt;List&lt;User&gt;&gt; response = apiClient.invokeAPIWithHttpInfo(...);
+ * 
+ * int status = response.getStatusCode(); // e.g., 200
+ * List&lt;User&gt; users = response.getBody(); // The actual data
+ * Map&lt;String, List&lt;String&gt;&gt; headers = response.getHeaders(); // Response headers
+ * 
+ * // Check for pagination
+ * List&lt;String&gt; linkHeaders = headers.get("Link");
+ * </pre>
+ *
+ * @param <T> The type of the response body (e.g., List&lt;User&gt;, Group, etc.)
+ * @since 17.0.0
+ */
+publicclassApiResponse<T>{
+
+privatefinalintstatusCode;
+privatefinalMap<String, List<String>> headers;
+privatefinalTbody;
+
+/**
+ * Constructs a new ApiResponse with the given status code, headers, and body.
+ *
+ * @param statusCode the HTTP status code (e.g., 200, 404, 500)
+ * @param headers the response headers as a map (header name → list of values)
+ * @param body the deserialized response body (can be null for 204 No Content)
+ */
+publicApiResponse(intstatusCode, Map<String, List<String>> headers, Tbody){
+this.statusCode = statusCode;
+this.headers = headers;
+this.body = body;
+ }
+
+/**
+ * Gets the HTTP status code from the response.
+ *
+ * @return the status code (e.g., 200 for success, 404 for not found)
+ */
+publicintgetStatusCode(){
+returnstatusCode;
+ }
+
+/**
+ * Gets the response headers.
+ * 
+ * Common headers include:
+ * - "Link": Pagination links (e.g., rel="next")
+ * - "Content-Type": Response content type
+ * - "X-Rate-Limit-Remaining": API rate limit info
+ *
+ * @return a map of header names to lists of header values
+ */
+publicMap<String, List<String>> getHeaders(){
+returnheaders;
+ }
+
+/**
+ * Gets the deserialized response body.
+ * 
+ * This is the actual data returned by the API, already converted
+ * from JSON into Java objects.
+ *
+ * @return the response body, or null if the response was empty (204 No Content)
+ */
+publicTgetBody(){
+returnbody;
+ }
+
+@Override
+publicStringtoString(){
+return"ApiResponse{" +
+"statusCode=" + statusCode +
+", headersCount=" + (headers != null ? headers.size() : 0) +
+", body=" + (body != null ? body.getClass().getSimpleName() : "null") +
+'}';
+ }
+}

api/src/main/java/com/okta/sdk/resource/client/PagedIterable.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2025-Present, Okta, Inc.
+ *
+ * Licensed 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.
+ */
+packagecom.okta.sdk.resource.client;
+
+importjava.util.Iterator;
+importjava.util.List;
+importjava.util.function.Function;
+
+/**
+ * A new lazy, paginated iterable.
+ *
+ * This class is a "recipe" for fetching paginated data. It does no
+ * work until the iterator() method is called (e.g., by a for-each loop).
+ *
+ * Each call to iterator() creates a new, independent PagedIterator instance,
+ * ensuring thread-safety and isolation of pagination state.
+ *
+ * @param <T> The type of item in the collection (e.g., User)
+ */
+publicclassPagedIterable<T> implementsIterable<T>{
+
+/**
+ * The "strategy" or "recipe" for fetching one page.
+ * The String input is the 'nextUrl' (or null for the first page).
+ * The ApiResponse output contains the page of results.
+ */
+privatefinalFunction<String, ApiResponse<List<T>>> pageFetcher;
+
+/**
+ * Constructs a new PagedIterable with the given page fetching strategy.
+ *
+ * @param pageFetcher A function that takes a next URL (or null for the first page)
+ * and returns an ApiResponse containing a list of items and headers.
+ */
+publicPagedIterable(Function<String, ApiResponse<List<T>>> pageFetcher){
+this.pageFetcher = pageFetcher;
+ }
+
+/**
+ * Creates a new, stateful iterator.
+ * This is the key to thread-safety: every loop gets its
+ * own private iterator to manage its own private state.
+ *
+ * @return A new PagedIterator instance for this iteration.
+ */
+@Override
+publicIterator<T> iterator(){
+returnnewPagedIterator<>(pageFetcher);
+ }
+}

api/src/main/java/com/okta/sdk/resource/client/PagedIterator.java

@@ -0,0 +1,136 @@
+/*
+ * Copyright (c) 2025-Present, Okta, Inc.
+ *
+ * Licensed 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.
+ */
+packagecom.okta.sdk.resource.client;
+
+importcom.okta.commons.lang.Collections;
+
+importjava.util.Iterator;
+importjava.util.LinkedList;
+importjava.util.List;
+importjava.util.Map;
+importjava.util.NoSuchElementException;
+importjava.util.Queue;
+importjava.util.function.Function;
+importjava.util.regex.Matcher;
+importjava.util.regex.Pattern;
+
+/**
+ * The new stateful, but *isolated*, iterator for pagination.
+ *
+ * This object is created for each loop and holds the state
+ * (the next page URL and the current page's items) for that
+ * loop *only*. It is not shared, making it thread-safe.
+ *
+ * @param <T> The type of item in the collection (e.g., User)
+ */
+publicclassPagedIterator<T> implementsIterator<T>{
+
+// Regex to find the "next" link in a Link header
+privatestaticfinalPatternNEXT_LINK_PATTERN = Pattern.compile("<([^>]+)>\\s*rel=\"next\"");
+
+privatefinalFunction<String, ApiResponse<List<T>>> pageFetcher;
+
+// --- THIS IS THE ISOLATED STATE ---
+privateStringnextUrl = null;
+privatebooleanisFirstPage = true;
+privateQueue<T> itemBuffer = newLinkedList<>();
+// ---
+
+/**
+ * Constructs a new PagedIterator with the given page fetching strategy.
+ *
+ * @param pageFetcher A function that takes a next URL (or null for the first page)
+ * and returns an ApiResponse containing a list of items and headers.
+ */
+publicPagedIterator(Function<String, ApiResponse<List<T>>> pageFetcher){
+this.pageFetcher = pageFetcher;
+ }
+
+@Override
+publicbooleanhasNext(){
+// 1. If we have items in our buffer, we're good.
+if (!itemBuffer.isEmpty()){
+returntrue;
+ }
+
+// 2. If it's the first page OR we have a next link,
+// we must try to fetch the next page.
+if (isFirstPage || nextUrl != null){
+fetchNextPage();
+ }
+
+// 3. After fetching, check the buffer again.
+// If it's still empty, we've reached the end.
+return !itemBuffer.isEmpty();
+ }
+
+@Override
+publicTnext(){
+// hasNext() ensures the buffer is populated if needed.
+if (!hasNext()){
+thrownewNoSuchElementException("No more items in pagination.");
+ }
+// Return the next item from the current page's buffer.
+returnitemBuffer.poll();
+ }
+
+/**
+ * The main engine. Calls the fetcher "strategy",
+ * fills the buffer, and saves the next link.
+ */
+privatevoidfetchNextPage(){
+// Call the "strategy" function from API class
+ApiResponse<List<T>> response = pageFetcher.apply(isFirstPage ? null : nextUrl);
+
+// Add all items from the response body to our buffer
+if (response.getBody() != null){
+itemBuffer.addAll(response.getBody());
+ }
+
+// Update our *private* state with the next link from the headers
+this.nextUrl = parseNextLinkFromHeaders(response.getHeaders());
+this.isFirstPage = false;
+ }
+
+/**
+ * Helper to parse the 'Link' header for rel="next"
+ *
+ * @param headers The response headers map
+ * @return The next URL if found, null otherwise
+ */
+privateStringparseNextLinkFromHeaders(Map<String, List<String>> headers){
+if (headers == null) returnnull;
+
+// Try both "Link" and "link" as HTTP headers can vary in case
+List<String> linkHeaders = headers.get("Link");
+if (Collections.isEmpty(linkHeaders)){
+linkHeaders = headers.get("link");
+ }
+if (Collections.isEmpty(linkHeaders)){
+returnnull;
+ }
+
+for (StringlinkHeader : linkHeaders){
+Matchermatcher = NEXT_LINK_PATTERN.matcher(linkHeader);
+if (matcher.find()){
+Stringurl = matcher.group(1);
+returnurl; // The URL
+ }
+ }
+
+returnnull; // No "next" link found
+ }
+}