Merge pull request #11 from swnck/dev

Enhance HTTP request handling

Author: swnck

README.md

@@ -22,18 +22,18 @@
 ---
 
 ## Features
-- [ ] Support for
+- [x] Support for
   - [x] GET requests
   - [x] POST requests
-  - [ ] PUT requests
-  - [ ] DELETE requests
-  - [ ] PATCH requests
+  - [x] PUT requests
+  - [x] DELETE requests
+  - [x] PATCH requests
 - [ ] Proxy configuration
 - [ ] Class (entity) mapping
 - [ ] Support for body (form-urlencoded, multipart, binary)
 - [ ] Retry request many times
 - [x] Query parameters 
-- [ ] Timeout configuration
+- [X] Timeout configuration
 - [x] CORS support
 
 ---

build.gradle.kts

@@ -5,7 +5,7 @@ plugins {
 }
 
 group = "io.github.swnck"
-version = "1.0.3"
+version = "1.0.4"
 
 repositories {
     mavenCentral()
@@ -17,6 +17,8 @@ dependencies {
 
     implementation("org.slf4j:slf4j-api:2.0.17")
 
+    implementation("org.json:json:20250517")
+
     compileOnly("org.projectlombok:lombok:1.18.38")
     annotationProcessor("org.projectlombok:lombok:1.18.38")
 }

src/main/java/io/github/swnck/JxRequest.java

@@ -1,25 +1,58 @@
 package io.github.swnck;
 
-import io.github.swnck.request.GetRequest;
-import io.github.swnck.request.PostRequest;
+import io.github.swnck.request.*;
 import lombok.Getter;
 
+/**
+ * Provides static factory methods to generate various types of HTTP requests.
+ * This class simplifies the creation of requests like GET, POST, PUT, PATCH, and DELETE,
+ * with or without URLs, providing flexibility for diverse use cases.
+ * Each method returns a specific request object tailored to the HTTP method being invoked.
+ */
 @Getter
 public class JxRequest {
 
     public static GetRequest get(String url) {
         return new GetRequest(url);
     }
 
-    public static PostRequest post(String url) {
-        return  new PostRequest(url);
-    }
-
     public static GetRequest get() {
         return new GetRequest();
     }
 
+
+    public static PostRequest post(String url) {
+        return new PostRequest(url);
+    }
+
     public static PostRequest post() {
-        return  new PostRequest();
+        return new PostRequest();
+    }
+
+
+    public static DeleteRequest delete(String url) {
+        return new DeleteRequest(url);
+    }
+
+    public static DeleteRequest delete() {
+        return new DeleteRequest();
+    }
+
+
+    public static PatchRequest patch(String url) {
+        return new PatchRequest(url);
+    }
+
+    public static PatchRequest patch() {
+        return new PatchRequest();
+    }
+
+
+    public static PutRequest put(String url) {
+        return new PutRequest(url);
+    }
+
+    public static PutRequest put() {
+        return new PutRequest();
     }
 }

src/main/java/io/github/swnck/JxResponse.java

@@ -1,7 +1,7 @@
 package io.github.swnck;
 
+import io.github.swnck.request.AbstractBody;
 import io.github.swnck.request.AbstractRequest;
-import io.github.swnck.request.PostRequest;
 import io.github.swnck.util.ContentType;
 import io.github.swnck.util.StatusCode;
 import lombok.Getter;
@@ -15,18 +15,22 @@
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import java.nio.charset.StandardCharsets;
+import java.time.Duration;
 import java.util.List;
 import java.util.Map;
-import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * Represents an HTTP response retrieved using an asynchronous HTTP client.
+ * This class is designed to process a given request, initiate the corresponding HTTP call,
+ * and handle the response data, including body, status code, headers, and timing.
+ */
 @Getter
 @Setter
 public class JxResponse {
     private static final HttpClient CLIENT = HttpClient.newBuilder().build();
     private static final Logger LOGGER = LoggerFactory.getLogger(JxResponse.class);
 
-
     private String body;
     private String contentType;
     private String uri;
@@ -36,15 +40,24 @@ public class JxResponse {
 
     private Map<String, List<String>> headers;
 
+    /**
+     * Constructs a JxResponse object by initiating and handling an asynchronous HTTP request based on the provided request object.
+     * Handles the composition of the request URI with query parameters, method type, headers, and optional body content.
+     * Completes the operation by storing the response details such as body, status code, headers, and execution duration.
+     *
+     * @param request the {@link AbstractRequest} object containing the details of the HTTP request,
+     *                including the URL, query parameters, headers, method, timeout, and body (if applicable).
+     */
     public JxResponse(AbstractRequest<?> request) {
-        String urlWithParams = buildUrlWithParams(request.url, request.getQueryParams());
-        String bodyContent = (request instanceof PostRequest) ? ((PostRequest) request).getBody() : null;
+        String urlWithParams = buildUrlWithParams(request.getUrl(), request.getQueryParams());
+        String bodyContent = (request instanceof AbstractBody<?>) ? ((AbstractBody<?>) request).getBody() : null;
 
         HttpRequest.Builder requestBuilder;
 
         try {
             requestBuilder = HttpRequest.newBuilder()
                     .uri(new URI(urlWithParams))
+                    .timeout(Duration.ofMillis(request.getTimeoutMillis()))
                     .method(request.getMethod().toString(),
                             (bodyContent == null) ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(bodyContent));
         } catch (Exception e) {
@@ -53,7 +66,6 @@ public JxResponse(AbstractRequest<?> request) {
         }
 
         request.getHeaders().forEach((key, value) -> requestBuilder.header(key, value.toString()));
-        requestBuilder.header("Content-Type", Objects.requireNonNullElse(request.contentType, ContentType.TEXT_PLAIN).getMimeType());
 
         HttpRequest httpRequest = requestBuilder.build();
 
@@ -63,7 +75,8 @@ public JxResponse(AbstractRequest<?> request) {
 
         response.thenAccept(httpResponse -> {
             this.body = httpResponse.body();
-            this.contentType = httpResponse.headers().firstValue("Content-Type").orElse(ContentType.TEXT_PLAIN.getMimeType());
+            this.contentType = httpResponse.headers().firstValue("Content-Type")
+                    .orElse(ContentType.TEXT_PLAIN.getMimeType());
             this.statusCode = httpResponse.statusCode();
             this.uri = httpResponse.uri().toString();
             this.headers = httpResponse.headers().map();
@@ -76,6 +89,15 @@ public JxResponse(AbstractRequest<?> request) {
         }).join();
     }
 
+    /**
+     * Constructs a complete URL by appending query parameters to the base URL.
+     * If the provided query parameters are null or empty, the original URL is returned as is.
+     * Handles encoding of both keys and values in the query parameters to ensure proper URL formatting.
+     *
+     * @param url the base URL to which query parameters will be appended
+     * @param queryParams a map containing query parameter keys and their corresponding values
+     * @return the complete URL with query parameters appended and properly encoded
+     */
     private String buildUrlWithParams(String url, Map<String, Object> queryParams) {
         if (queryParams == null || queryParams.isEmpty()) return url;
         StringBuilder sb = new StringBuilder(url);

src/main/java/io/github/swnck/cors/Cors.java

@@ -6,13 +6,41 @@
 import java.util.Map;
 
 /**
- * Cors is a builder class for creating CORS (Cross-Origin Resource Sharing) headers.
- * It allows you to specify the allowed origins, methods, headers, and whether credentials are allowed.
+ * The Cors class provides a mechanism for configuring Cross-Origin Resource Sharing (CORS) headers
+ * for an HTTP response. It allows customization of origins, HTTP methods, headers,
+ * and other CORS-related configurations.
+ * <p>
+ * This class uses a builder-style pattern, enabling chained method calls for setting
+ * various CORS options. The settings are maintained in an internal map, `corsMap`, where
+ * the configuration key-value pairs are stored.
  */
 @Getter
 public class Cors {
+    /**
+     * A map that stores CORS (Cross-Origin Resource Sharing) configuration settings.
+     * The keys represent specific configuration options, such as allowed origins,
+     * HTTP methods, headers, and other related parameters, while the values
+     * represent their corresponding settings.
+     * <p>
+     * This map is used internally to maintain the CORS configurations applied
+     * via various methods in the class. The settings stored in this map can
+     * be applied to HTTP response headers to enable the desired CORS behavior.
+     * <p>
+     * The `corsMap` is populated and modified using methods provided in the
+     * `Cors` class, allowing for dynamic and customizable CORS configurations.
+     */
     private final Map<String, Object> corsMap = new HashMap<>();
 
+    /**
+     * Configures the allowed origin for Cross-Origin Resource Sharing (CORS).
+     * This method sets the "Access-Control-Allow-Origin" header to the specified origin.
+     * The wildcard character "*" can be used to allow all origins.
+     *
+     * @param origin the allowed origin for CORS. The value can be a specific origin (e.g., "https://example.com")
+     *               or "*" to allow requests from any origin. Must not be null.
+     * @return the updated {@code Cors} instance, allowing for method chaining.
+     * @throws IllegalArgumentException if the origin is null.
+     */
     public Cors allowOrigin(String origin) {
         if (origin == null) {
             throw new IllegalArgumentException("Origin cannot be null");
@@ -27,6 +55,15 @@ public Cors allowOrigin(String origin) {
         return this;
     }
 
+    /**
+     * Configures the allowed HTTP methods for Cross-Origin Resource Sharing (CORS).
+     * This method sets the "Access-Control-Allow-Methods" header to the specified methods.
+     *
+     * @param methods the HTTP methods to allow for CORS (e.g., "GET", "POST", "PUT").
+     *                Must not be null or empty.
+     * @return the updated {@code Cors} instance, allowing for method chaining.
+     * @throws IllegalArgumentException if the methods array is null or empty.
+     */
     public Cors allowMethods(String... methods) {
         if (methods == null || methods.length == 0) {
             throw new IllegalArgumentException("Methods cannot be null or empty");
@@ -36,6 +73,14 @@ public Cors allowMethods(String... methods) {
         return this;
     }
 
+    /**
+     * Configures the allowed HTTP headers for Cross-Origin Resource Sharing (CORS).
+     * This method sets the "Access-Control-Allow-Headers" header to the specified headers.
+     *
+     * @param headers the HTTP headers to allow for CORS. Must not be null or empty.
+     * @return the updated {@code Cors} instance, allowing for method chaining.
+     * @throws IllegalArgumentException if the headers array is null or empty.
+     */
     public Cors allowHeaders(String... headers) {
         if (headers == null || headers.length == 0) {
             throw new IllegalArgumentException("Headers cannot be null or empty");
@@ -45,6 +90,17 @@ public Cors allowHeaders(String... headers) {
         return this;
     }
 
+    /**
+     * Configures whether credentials are allowed for Cross-Origin Resource Sharing (CORS).
+     * This method sets the "Access-Control-Allow-Credentials" header to the specified value.
+     * Setting this to true allows the sharing of credentials such as cookies, authentication headers, or
+     * TLS client certificates in cross-origin requests.
+     *
+     * @param allowCredentials a boolean indicating whether credentials are allowed. If true,
+     *                         the response indicates that the resource is prepared to
+     *                         share credentials with the client.
+     * @return the updated {@code Cors} instance, allowing for method chaining.
+     */
     public Cors allowCredentials(boolean allowCredentials) {
         this.corsMap.put("Access-Control-Allow-Credentials", allowCredentials);
         return this;

src/main/java/io/github/swnck/request/AbstractBody.java

@@ -0,0 +1,63 @@
+package io.github.swnck.request;
+
+import io.github.swnck.util.Method;
+import lombok.Getter;
+
+/**
+ * AbstractBody is an abstract base class to handle HTTP request bodies in concrete implementations of various HTTP methods.
+ * It provides mechanisms for setting and validating the body content of HTTP requests.
+ *
+ * @param <T> the type of the subclass extending AbstractBody
+ */
+@Getter
+public abstract class AbstractBody<T extends AbstractBody<T>> extends AbstractRequest<T> {
+
+    /**
+     * The `body` variable represents the content of the HTTP request body.
+     * It is used to store the data that will be transmitted in the request
+     * for HTTP methods supporting a body, such as POST, PUT, PATCH, and DELETE.
+     */
+    private String body;
+
+    /**
+     * Constructs a new {@code AbstractBody} instance with the specified URL and HTTP method.
+     * This constructor initializes the HTTP request body handler using the provided URL and method.
+     *
+     * @param url the URL to which the request will be sent; must not be null. If the URL does not
+     *            start with "http://" or "https://", "http://" will be prefixed.
+     * @param method the HTTP method to be used for the request; must not be null. Supported methods
+     *               include GET, POST, DELETE, PUT, and PATCH.
+     */
+    public AbstractBody(String url, Method method) {
+        super(url, method);
+    }
+
+    /**
+     * Constructs a new {@code AbstractBody} instance with the specified HTTP method.
+     * This constructor initializes the HTTP request body handler using the provided method.
+     *
+     * @param method the HTTP method to be used for the request; must not be null.
+     *               Supported methods include GET, POST, DELETE, PUT, and PATCH.
+     * @throws IllegalArgumentException if the method is null.
+     */
+    public AbstractBody(Method method) {
+        super(method);
+    }
+
+    /**
+     * Sets the body of the HTTP request.
+     *
+     * @param body the content to be set as the body of the HTTP request; must not be null
+     * @return the current instance of the subclass implementation for method chaining
+     * @throws IllegalArgumentException if the provided body is null
+     */
+    @SuppressWarnings("unchecked")
+    public T setBody(String body) {
+        if (body == null) {
+            throw new IllegalArgumentException("AbstractBody cannot be null");
+        }
+
+        this.body = body;
+        return (T) this;
+    }
+}