feat: pagination support for api calls (#128)

This commit adds implementation for 4 pagination types in API Calls, along with their unit tests.

Author: asadali214

src/main/java/io/apimatic/core/ApiCall.java

@@ -8,8 +8,8 @@
 import io.apimatic.core.logger.SdkLoggerFactory;
 import io.apimatic.core.request.async.AsyncExecutor;
 import io.apimatic.core.types.CoreApiException;
+import io.apimatic.coreinterfaces.http.Context;
 import io.apimatic.coreinterfaces.http.request.Request;
-import io.apimatic.coreinterfaces.http.request.configuration.CoreEndpointConfiguration;
 import io.apimatic.coreinterfaces.http.response.Response;
 import io.apimatic.coreinterfaces.logger.ApiLogger;
 
@@ -27,19 +27,19 @@ public final class ApiCall<ResponseType, ExceptionType extends CoreApiException>
     private final GlobalConfiguration globalConfig;
 
     /**
-     * An instance of {@link Request}
+     * An instance of {@link HttpRequest.Builder}
      */
-    private final Request request;
+    private final HttpRequest.Builder requestBuilder;
 
     /**
      * An instance of {@link ResponseHandler.Builder}.
      */
     private final ResponseHandler<ResponseType, ExceptionType> responseHandler;
 
     /**
-     * An instance of {@link CoreEndpointConfiguration}.
+     * An instance of {@link EndpointConfiguration}.
      */
-    private final CoreEndpointConfiguration endpointConfiguration;
+    private final EndpointConfiguration endpointConfiguration;
 
     /**
      * An instance of {@link ApiLogger} for logging.
@@ -50,17 +50,18 @@ public final class ApiCall<ResponseType, ExceptionType extends CoreApiException>
     /**
      * ApiCall constructor.
      * @param globalConfig the required configuration to built the ApiCall.
-     * @param coreHttpRequest Http request for the api call.
+     * @param endpointConfiguration The endPoint configuration.
+     * @param requestBuilder Http request builder for the api call.
      * @param responseHandler the handler for the response.
-     * @param coreEndpointConfiguration endPoint configuration.
      */
-    private ApiCall(final GlobalConfiguration globalConfig, final Request coreHttpRequest,
-            final ResponseHandler<ResponseType, ExceptionType> responseHandler,
-            final CoreEndpointConfiguration coreEndpointConfiguration) {
+    private ApiCall(final GlobalConfiguration globalConfig,
+            final EndpointConfiguration endpointConfiguration,
+            final HttpRequest.Builder requestBuilder,
+            final ResponseHandler<ResponseType, ExceptionType> responseHandler) {
         this.globalConfig = globalConfig;
-        this.request = coreHttpRequest;
+        this.requestBuilder = requestBuilder;
         this.responseHandler = responseHandler;
-        this.endpointConfiguration = coreEndpointConfiguration;
+        this.endpointConfiguration = endpointConfiguration;
         this.apiLogger = SdkLoggerFactory.getLogger(globalConfig.getLoggingConfiguration());
     }
 
@@ -71,24 +72,31 @@ private ApiCall(final GlobalConfiguration globalConfig, final Request coreHttpRe
      * @throws ExceptionType Represents error response from the server.
      */
     public ResponseType execute() throws IOException, ExceptionType {
+        Request request = requestBuilder.build(globalConfig);
         apiLogger.logRequest(request);
-        Response httpResponse = globalConfig.getHttpClient()
-            .execute(request, endpointConfiguration);
-        apiLogger.logResponse(httpResponse);
+        Response response = globalConfig.getHttpClient().execute(request, endpointConfiguration);
+        apiLogger.logResponse(response);
 
-        return responseHandler.handle(request, httpResponse, globalConfig, endpointConfiguration);
+        Context context = globalConfig.getCompatibilityFactory()
+                .createHttpContext(request, response);
+
+        return responseHandler.handle(context, endpointConfiguration, globalConfig, requestBuilder);
     }
 
     /**
      * Execute the Api call asynchronously and returns the expected response in CompletableFuture.
      * @return the instance of {@link CompletableFuture}.
      */
     public CompletableFuture<ResponseType> executeAsync() {
-        return AsyncExecutor.makeHttpCallAsync(() -> request,
-                request -> globalConfig.getHttpClient().executeAsync(request,
-                        endpointConfiguration),
-                (httpRequest, httpResponse) -> responseHandler.handle(httpRequest, httpResponse,
-                        globalConfig, endpointConfiguration), apiLogger);
+        return AsyncExecutor.makeHttpCallAsync(() -> requestBuilder.build(globalConfig),
+                request -> globalConfig.getHttpClient()
+                        .executeAsync(request, endpointConfiguration),
+                (request, response) -> {
+                    Context context = globalConfig.getCompatibilityFactory()
+                            .createHttpContext(request, response);
+                    return responseHandler.handle(context, endpointConfiguration, globalConfig,
+                            requestBuilder);
+                }, apiLogger);
     }
 
     /**
@@ -139,6 +147,16 @@ public Builder<ResponseType, ExceptionType> requestBuilder(
             return this;
         }
 
+        /**
+         * @param builder requestBuilder {@link HttpRequest.Builder}.
+         * @return {@link ApiCall.Builder}.
+         */
+        public Builder<ResponseType, ExceptionType> requestBuilder(
+                HttpRequest.Builder builder) {
+            requestBuilder = builder;
+            return this;
+        }
+
         /**
          * @param action responseHandler {@link Consumer}.
          * @return {@link ApiCall.Builder}.
@@ -161,15 +179,25 @@ public Builder<ResponseType, ExceptionType> endpointConfiguration(
             return this;
         }
 
+        /**
+         * @param builder endpointConfigurationBuilder {@link EndpointConfiguration.Builder}.
+         * @return {@link ApiCall.Builder}.
+         */
+        public Builder<ResponseType, ExceptionType> endpointConfiguration(
+                EndpointConfiguration.Builder builder) {
+            endpointConfigurationBuilder = builder;
+            return this;
+        }
+
         /**
          * build the {@link ApiCall}.
          * @return the instance of {@link ApiCall}.
          * @throws IOException Signals that an I/O exception of some sort has occurred.
          */
         public ApiCall<ResponseType, ExceptionType> build() throws IOException {
             return new ApiCall<ResponseType, ExceptionType>(globalConfig,
-                    requestBuilder.build(globalConfig), responseHandlerBuilder.build(),
-                    endpointConfigurationBuilder.build());
+                    endpointConfigurationBuilder.build(), requestBuilder,
+                    responseHandlerBuilder.build());
         }
     }
 }

src/main/java/io/apimatic/core/ErrorCase.java

@@ -1,14 +1,13 @@
 package io.apimatic.core;
 
-import java.io.StringReader;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import javax.json.Json;
 import javax.json.JsonException;
 import javax.json.JsonPointer;
-import javax.json.JsonReader;
 import javax.json.JsonStructure;
 import io.apimatic.core.types.CoreApiException;
+import io.apimatic.core.utilities.CoreHelper;
 import io.apimatic.coreinterfaces.http.Context;
 import io.apimatic.coreinterfaces.http.HttpHeaders;
 import io.apimatic.coreinterfaces.http.response.Response;
@@ -140,14 +139,7 @@ private String replaceHeadersFromTemplate(HttpHeaders headers, String reason) {
 
     private String replaceBodyFromTemplate(String responseBody, String reason) {
         StringBuilder formatter = new StringBuilder(reason);
-        JsonReader jsonReader = Json.createReader(new StringReader(responseBody));
-        JsonStructure jsonStructure = null;
-        try {
-            jsonStructure = jsonReader.read();
-        } catch (Exception e) {
-            // No need to do anything here
-        }
-        jsonReader.close();
+        JsonStructure jsonStructure = CoreHelper.createJsonStructure(responseBody);
         Matcher matcher = Pattern.compile("\\{(.*?)\\}").matcher(reason);
         while (matcher.find()) {
             String key = matcher.group(1);

src/main/java/io/apimatic/core/HttpRequest.java

@@ -3,13 +3,17 @@
 import java.io.IOException;
 import java.util.AbstractMap.SimpleEntry;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Map.Entry;
 import java.util.Set;
 import java.util.function.Consumer;
+import java.util.function.UnaryOperator;
+
 import io.apimatic.core.authentication.AuthBuilder;
 import io.apimatic.core.exceptions.AuthValidationException;
 import io.apimatic.core.types.http.request.MultipartFileWrapper;
@@ -84,10 +88,12 @@ private HttpRequest(final GlobalConfiguration coreConfig, final String server,
         // Creating a basic request to provide it to auth instances
         Request request = buildBasicRequest(httpMethod, requestHeaders);
 
-        applyAuthentication(request, authentication);
-        // include auth query parameters in request query params to have them in the query url
-        if (request.getQueryParameters() != null) {
-            queryParams.putAll(request.getQueryParameters());
+        if (request != null) {
+            applyAuthentication(request, authentication);
+            // include auth query parameters in request query params to have them in the query url
+            if (request.getQueryParameters() != null) {
+                queryParams.putAll(request.getQueryParameters());
+            }
         }
 
         queryUrlBuilder = getStringBuilder(server, path, queryParams, arraySerializationFormat);
@@ -284,7 +290,7 @@ public static class Builder {
         /**
          * A map of header parameters.
          */
-        private Map<String, List<String>> headerParams = new HashMap<>();
+        private Map<String, List<Object>> headerParams = new HashMap<>();
 
         /**
          * A set of {@link Parameter}.
@@ -322,6 +328,78 @@ public static class Builder {
          */
         private Parameter.Builder parameterBuilder = new Parameter.Builder();
 
+        /**
+         * Update the request parameters using a setter.
+         *
+         * @param pointer A JSON pointer pointing to any request field.
+         * @param setter A function that takes in an old value and returns a new value.
+         * @return The updated instance of current request builder.
+         */
+        public Builder updateByReference(String pointer, UnaryOperator<Object> setter) {
+            if (pointer == null) {
+                return this;
+            }
+
+            String[] pointerParts = pointer.split("#");
+            String prefix = pointerParts[0];
+            String point = pointerParts.length > 1 ? pointerParts[1] : "";
+
+            switch (prefix) {
+            case "$request.path":
+                updateTemplateParams(setter, point);
+                return this;
+            case "$request.query":
+                queryParams = CoreHelper.updateValueByPointer(queryParams, point, setter);
+                return this;
+            case "$request.headers":
+                updateHeaderParams(setter, point);
+                return this;
+            default:
+                return this;
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private void updateHeaderParams(UnaryOperator<Object> setter, String point) {
+            Map<String, Object> simplifiedHeaders = new HashMap<>();
+            for (Entry<String, List<Object>> entry : headerParams.entrySet()) {
+                if (entry.getValue().size() == 1) {
+                    simplifiedHeaders.put(entry.getKey(), entry.getValue().get(0));
+                } else {
+                    simplifiedHeaders.put(entry.getKey(), entry.getValue());
+                }
+            }
+
+            simplifiedHeaders = CoreHelper.updateValueByPointer(simplifiedHeaders, point, setter);
+
+            for (Map.Entry<String, Object> entry : simplifiedHeaders.entrySet()) {
+                if (entry.getValue() instanceof List<?>) {
+                    headerParams.put(entry.getKey(), (List<Object>) entry.getValue());
+                } else {
+                    headerParams.put(entry.getKey(), Arrays.asList(entry.getValue()));
+                }
+            }
+        }
+
+        private void updateTemplateParams(UnaryOperator<Object> setter, String point) {
+            Map<String, Object> simplifiedPath = new HashMap<>();
+            for (Map.Entry<String, SimpleEntry<Object, Boolean>> entry
+                    : templateParams.entrySet()) {
+                simplifiedPath.put(entry.getKey(), entry.getValue().getKey());
+            }
+
+            simplifiedPath = CoreHelper.updateValueByPointer(simplifiedPath, point, setter);
+
+            for (Map.Entry<String, Object> entry : simplifiedPath.entrySet()) {
+                // Preserve the original boolean if it exists, otherwise set default (e.g., false)
+                Boolean originalFlag = templateParams.containsKey(entry.getKey())
+                    ? templateParams.get(entry.getKey()).getValue()
+                    : false;
+                templateParams.put(entry.getKey(),
+                        new SimpleEntry<>(entry.getValue(), originalFlag));
+            }
+        }
+
         /**
          * Base uri server address.
          * @param server the base uri address.
@@ -372,7 +450,6 @@ public Builder queryParam(Map<String, Object> queryParameters) {
             return this;
         }
 
-
         /**
          * To configure the query paramater.
          * @param action the query parameter {@link Consumer}.
@@ -414,32 +491,17 @@ public Builder headerParam(Consumer<Parameter.Builder> action) {
             Parameter httpHeaderParameter = parameterBuilder.build();
             httpHeaderParameter.validate();
             String key = httpHeaderParameter.getKey();
-            String value = getSerializedHeaderValue(httpHeaderParameter.getValue());
 
             if (headerParams.containsKey(key)) {
-                headerParams.get(key).add(value);
+                headerParams.get(key).add(httpHeaderParameter.getValue());
             } else {
-                List<String> headerValues = new ArrayList<String>();
-                headerValues.add(value);
+                List<Object> headerValues = new ArrayList<Object>();
+                headerValues.add(httpHeaderParameter.getValue());
                 headerParams.put(key, headerValues);
             }
             return this;
         }
 
-        private static String getSerializedHeaderValue(Object obj) {
-            if (obj == null) {
-                return null;
-            }
-
-            if (CoreHelper.isTypeCombinatorStringCase(obj)
-                    || CoreHelper.isTypeCombinatorDateTimeCase(obj)
-                    || obj instanceof String) {
-                return obj.toString();
-            }
-
-            return CoreHelper.trySerialize(obj);
-        }
-
         /**
          * To configure the form parameter.
          * @param action the form parameter {@link Consumer}.
@@ -505,6 +567,38 @@ public Builder arraySerializationFormat(ArraySerializationFormat arraySerializat
             return this;
         }
 
+        private Map<String, List<String>> getHeaderParams() {
+            Map<String, List<String>> converted = new HashMap<>();
+
+            for (Map.Entry<String, List<Object>> entry : headerParams.entrySet()) {
+                String key = entry.getKey();
+                List<Object> originalList = entry.getValue();
+
+                List<String> serializedList = new ArrayList<>();
+                for (Object obj : originalList) {
+                    serializedList.add(getSerializedHeaderValue(obj));
+                }
+
+                converted.put(key, serializedList);
+            }
+
+            return converted;
+        }
+
+        private static String getSerializedHeaderValue(Object obj) {
+            if (obj == null) {
+                return null;
+            }
+
+            if (CoreHelper.isTypeCombinatorStringCase(obj)
+                    || CoreHelper.isTypeCombinatorDateTimeCase(obj)
+                    || obj instanceof String) {
+                return obj.toString();
+            }
+
+            return CoreHelper.trySerialize(obj);
+        }
+
         /**
          * Initialise the CoreHttpRequest.
          * @param coreConfig the configuration for the Http request.
@@ -515,8 +609,9 @@ public Request build(GlobalConfiguration coreConfig) throws IOException {
             Authentication authentication = authBuilder.build(coreConfig.getAuthentications());
             HttpRequest coreRequest =
                     new HttpRequest(coreConfig, server, path, httpMethod, authentication,
-                            queryParams, templateParams, headerParams, formParams, formParamaters,
-                            body, bodySerializer, bodyParameters, arraySerializationFormat);
+                            queryParams, templateParams, getHeaderParams(), formParams,
+                            formParamaters, body, bodySerializer, bodyParameters,
+                            arraySerializationFormat);
             Request coreHttpRequest = coreRequest.getCoreHttpRequest();
 
             if (coreConfig.getHttpCallback() != null) {