refactor: Refactor clear and task APIs to utilize request objects

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeClearApi.java

@@ -1,9 +1,6 @@
 package ai.docling.serve.api;
 
-import java.time.Duration;
-
-import org.jspecify.annotations.Nullable;
-
+import ai.docling.serve.api.clear.request.ClearRequest;
 import ai.docling.serve.api.clear.response.ClearResponse;
 
 /**
@@ -13,15 +10,6 @@
  * on specified thresholds or default configurations.
  */
 public interface DoclingServeClearApi {
-  /**
-   * Represents the default duration used as a threshold for clearing stale results
-   * or data in the Docling Serve Clear API. Results older than this duration
-   * are considered stale and may be subject to cleanup.
-   *
-   * The value is predefined as 1 hour (3600 seconds).
-   */
-  Duration DEFAULT_OLDER_THAN = Duration.ofSeconds(3600);
-
   /**
    * Clears all registered converters associated with the API.
    * This method removes any previously configured or cached converters,
@@ -31,22 +19,15 @@ public interface DoclingServeClearApi {
   ClearResponse clearConverters();
 
   /**
-   * Clears stored results that are older than the specified duration threshold.
-   * This method is used for housekeeping to remove stale or outdated data from the system.
-   *
-   * @param olderThen the duration threshold; only results older than this duration will be cleared.
-   * @return a {@link ClearResponse} object containing the status of the clear operation.
-   */
-  ClearResponse clearResults(@Nullable Duration olderThen);
-
-  /**
-   * Clears stored results that are older than the default duration threshold.
-   * This method uses the pre-defined {@code DEFAULT_OLDER_THAN} as the threshold
-   * to determine which results are considered stale and should be removed.
+   * Clears stored results based on the specified {@link ClearRequest}.
+   * This method removes results that match the criteria provided in the
+   * request, such as results older than a specified duration.
    *
-   * @return a {@link ClearResponse} object containing the status of the clear operation.
+   * @param request an instance of {@link ClearRequest} containing the criteria
+   *                for clearing stored results, including the duration threshold
+   *                or other parameters.
+   * @return a {@link ClearResponse} object indicating the status of the clear
+   *         operation, such as success or failure.
    */
-  default ClearResponse clearResults() {
-    return clearResults(DEFAULT_OLDER_THAN);
-  }
+  ClearResponse clearResults(ClearRequest request);
 }

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeTaskApi.java

@@ -1,11 +1,9 @@
 package ai.docling.serve.api;
 
-import java.time.Duration;
-
-import org.jspecify.annotations.Nullable;
-
 import ai.docling.serve.api.chunk.response.ChunkDocumentResponse;
 import ai.docling.serve.api.convert.response.ConvertDocumentResponse;
+import ai.docling.serve.api.task.request.TaskResultRequest;
+import ai.docling.serve.api.task.request.TaskStatusPollRequest;
 import ai.docling.serve.api.task.response.TaskStatusPollResponse;
 
 /**
@@ -18,59 +16,46 @@
  */
 public interface DoclingServeTaskApi {
   /**
-   * The default wait time between status polling attempts for a task.
-   * <p>
-   * This value is used when no explicit wait time is specified in a
-   * {@code TaskStatusPollRequest} instance. It is set to {@link Duration#ZERO},
-   * meaning there is no delay by default between consecutive polling attempts.
-   * </p>
-   */
-  Duration DEFAULT_STATUS_POLL_WAIT_TIME = Duration.ZERO;
-
-  /**
-   * Polls the status of a task asynchronously and retrieves its current state.
-   * Allows for configurable wait time between polling attempts.
-   * If the wait time is {@code }, the default wait time ({@link #DEFAULT_STATUS_POLL_WAIT_TIME}) is used.
+   * Polls the status of an asynchronous task based on the provided request.
    *
-   * @param taskId the unique identifier of the task whose status is being polled
-   * @param waitTime the duration to wait before polling the status, or null to use the default polling interval
-   * @return a {@link TaskStatusPollResponse} containing the current status of the task and associated metadata
-   */
-  TaskStatusPollResponse pollTaskStatus(String taskId, @Nullable Duration waitTime);
-
-  /**
-   * Polls the status of a task asynchronously using the default wait time.
-   * This convenience method delegates to {@link #pollTaskStatus(String, Duration)}
-   * with {@code DEFAULT_STATUS_POLL_WAIT_TIME} as the wait time.
+   * This method retrieves the current status of a task using the task identifier specified
+   * in the request object. It allows monitoring of a task's progress, position in the queue,
+   * and detailed status metadata, if available. The polling behavior can be influenced by
+   * optional configurations such as the wait time between polling attempts provided in the request.
    *
-   * @param taskId the unique identifier of the task whose status is being polled
-   * @return a {@link TaskStatusPollResponse} containing the current status of the task
-   *         and associated metadata
+   * @param request the {@link TaskStatusPollRequest} containing the task identifier and optional
+   *                wait time between polling attempts
+   * @return a {@link TaskStatusPollResponse} encapsulating the current status, position in the
+   *         queue, and optional metadata for the specified task
    */
-  default TaskStatusPollResponse pollTaskStatus(String taskId) {
-    return pollTaskStatus(taskId, DEFAULT_STATUS_POLL_WAIT_TIME);
-  }
+  TaskStatusPollResponse pollTaskStatus(TaskStatusPollRequest request);
 
   /**
-   * Converts the completed task result identified by the provided task ID into a document response.
-   * This method processes the task data associated with the given ID and generates a response
-   * encapsulating the converted document details.
+   * Converts the result of a completed task into a document format as specified in the request.
    *
-   * @param taskId the unique identifier of the task whose result needs to be converted into a document response
-   * @return a {@link ConvertDocumentResponse} containing the details of the converted document, processing metadata,
-   *         errors (if any), and other relevant information
+   * This method processes the task result identified by the unique task ID provided in
+   * the request, performs any necessary transformation, and returns a response
+   * containing the converted document and related details.
+   *
+   * @param request the {@link TaskResultRequest} containing the unique task identifier
+   *                for which the result is to be converted
+   * @return a {@link ConvertDocumentResponse} encapsulating the converted document,
+   *         processing status, timings, and potential errors
    */
-  ConvertDocumentResponse convertTaskResult(String taskId);
+  ConvertDocumentResponse convertTaskResult(TaskResultRequest request);
 
   /**
-   * Processes the results of a completed task identified by the given task ID and generates a
-   * response containing chunked document details. This method is used to break down the document
-   * associated with the task into manageable chunks, making it suitable for subsequent processing
-   * or analysis.
+   * Processes the result of a completed task and splits it into smaller chunks as per
+   * the provided request specifications.
+   *
+   * The method uses the unique task identifier, provided in the request, to locate the
+   * task result. It then analyzes the result and breaks it into chunks, which are
+   * included in the response along with any relevant metadata.
    *
-   * @param taskId the unique identifier of the task whose result is to be processed and chunked into
-   *        a {@link ChunkDocumentResponse}
-   * @return a {@link ChunkDocumentResponse} containing the chunked document details and related metadata
+   * @param request the {@link TaskResultRequest} containing the unique identifier of
+   *                the task whose result is to be processed and chunked
+   * @return a {@link ChunkDocumentResponse} containing the chunked result,
+   *         associated documents, processing time, and additional relevant metadata
    */
-  ChunkDocumentResponse chunkTaskResult(String taskId);
+  ChunkDocumentResponse chunkTaskResult(TaskResultRequest request);
 }

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/clear/request/ClearRequest.java

@@ -0,0 +1,33 @@
+package ai.docling.serve.api.clear.request;
+
+import java.time.Duration;
+
+/**
+ * Represents a request to clear stale data via the Docling Serve Clear API.
+ * This class provides a mechanism to specify a threshold duration, after which data
+ * is considered stale and eligible for cleanup.
+ *
+ * The {@code olderThen} field specifies the duration threshold, with a default
+ * value of {@link #DEFAULT_OLDER_THAN}, predefined as 1 hour (3600 seconds).
+ * This default can be overridden using the builder or by explicitly passing a custom
+ * duration at runtime.
+ *
+ * Instances of this class are immutable and can be created or modified through its builder.
+ */
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public class ClearRequest {
+  /**
+   * Represents the default duration used as a threshold for clearing stale results
+   * or data in the Docling Serve Clear API. Results older than this duration
+   * are considered stale and may be subject to cleanup.
+   *
+   * The value is predefined as 1 hour (3600 seconds).
+   */
+  public static final Duration DEFAULT_OLDER_THAN = Duration.ofSeconds(3600);
+
+  @lombok.NonNull
+  @lombok.Builder.Default
+  private Duration olderThen = DEFAULT_OLDER_THAN;
+}

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/clear/request/package-info.java

@@ -0,0 +1,4 @@
+@NullMarked
+package ai.docling.serve.api.clear.request;
+
+import org.jspecify.annotations.NullMarked;

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/task/request/TaskResultRequest.java

@@ -0,0 +1,21 @@
+package ai.docling.serve.api.task.request;
+
+/**
+ * Represents a request to retrieve the result of a task.
+ *
+ * This class is used to encapsulate the necessary information required to
+ * request the result corresponding to the task identified by its unique task ID.
+ * Instances of this class are immutable and can be built using the provided
+ * builder methods.
+ *
+ * Attributes:
+ * - `taskId`: The unique identifier of the task whose result is being requested.
+ *             This field is mandatory and must not be null.
+ */
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public class TaskResultRequest {
+  @lombok.NonNull
+  private String taskId;
+}

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/task/request/TaskStatusPollRequest.java

@@ -0,0 +1,42 @@
+package ai.docling.serve.api.task.request;
+
+import java.time.Duration;
+
+/**
+ * Represents a request for polling the status of a task.
+ *
+ * This class encapsulates the information required to poll the status of a specific task.
+ * It includes the unique task identifier and an optional wait time between consecutive
+ * polling attempts. Instances of this class are immutable and can be built using the
+ * provided builder methods.
+ *
+ * Attributes:
+ * - `DEFAULT_STATUS_POLL_WAIT_TIME`: Specifies the default value for the wait time
+ *   between polling attempts. By default, this is set to {@link Duration#ZERO}, indicating
+ *   no delay between consecutive polling attempts.
+ * - `taskId`: The unique identifier of the task whose status is being polled. This field is
+ *   mandatory and must not be null.
+ * - `waitTime`: The duration to wait between consecutive polling attempts. If not explicitly
+ *   set, it defaults to {@link #DEFAULT_STATUS_POLL_WAIT_TIME}.
+ */
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public class TaskStatusPollRequest {
+  /**
+   * The default wait time between status polling attempts for a task.
+   * <p>
+   * This value is used when no explicit wait time is specified in a
+   * {@code TaskStatusPollRequest} instance. It is set to {@link Duration#ZERO},
+   * meaning there is no delay by default between consecutive polling attempts.
+   * </p>
+   */
+  public static final Duration DEFAULT_STATUS_POLL_WAIT_TIME = Duration.ZERO;
+
+  @lombok.NonNull
+  private String taskId;
+
+  @lombok.NonNull
+  @lombok.Builder.Default
+  private Duration waitTime = DEFAULT_STATUS_POLL_WAIT_TIME;
+}

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/task/request/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * The Docling task api
+ */
+@NullMarked
+package ai.docling.serve.api.task.request;
+
+import org.jspecify.annotations.NullMarked;

docling-serve/docling-serve-api/src/main/java/module-info.java

@@ -27,9 +27,11 @@
   exports ai.docling.serve.api.convert.response;
 
   // Clear API
+  exports ai.docling.serve.api.clear.request;
   exports ai.docling.serve.api.clear.response;
 
   // Task API
+  exports ai.docling.serve.api.task.request;
   exports ai.docling.serve.api.task.response;
 
   // Serialization helpers

docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/clear/request/ClearRequestTests.java

@@ -0,0 +1,25 @@
+package ai.docling.serve.api.clear.request;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+
+import org.assertj.core.api.InstanceOfAssertFactories;
+import org.junit.jupiter.api.Test;
+
+class ClearRequestTests {
+  @Test
+  void nullOlderThen() {
+    assertThatExceptionOfType(IllegalArgumentException.class)
+        .isThrownBy(() -> ClearRequest.builder().olderThen(null).build())
+        .withMessage("olderThen is marked non-null but is null");
+  }
+
+  @Test
+  void defaultOlderThen() {
+    assertThat(ClearRequest.builder().build())
+        .isNotNull()
+        .extracting(ClearRequest::getOlderThen)
+        .asInstanceOf(InstanceOfAssertFactories.DURATION)
+        .isEqualByComparingTo(ClearRequest.DEFAULT_OLDER_THAN);
+  }
+}

docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/task/request/TaskResultRequestTests.java

@@ -0,0 +1,21 @@
+package ai.docling.serve.api.task.request;
+
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+
+import org.junit.jupiter.api.Test;
+
+class TaskResultRequestTests {
+  @Test
+  void nullTaskId() {
+    assertThatExceptionOfType(IllegalArgumentException.class)
+        .isThrownBy(() -> TaskResultRequest.builder().taskId(null).build())
+        .withMessage("taskId is marked non-null but is null");
+  }
+
+  @Test
+  void noTaskId() {
+    assertThatExceptionOfType(IllegalArgumentException.class)
+        .isThrownBy(() -> TaskResultRequest.builder().build())
+        .withMessage("taskId is marked non-null but is null");
+  }
+}

docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/task/request/TaskStatusPollRequestTests.java

@@ -0,0 +1,39 @@
+package ai.docling.serve.api.task.request;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+
+import org.assertj.core.api.InstanceOfAssertFactories;
+import org.junit.jupiter.api.Test;
+
+class TaskStatusPollRequestTests {
+  @Test
+  void nullTaskId() {
+    assertThatExceptionOfType(IllegalArgumentException.class)
+        .isThrownBy(() -> TaskStatusPollRequest.builder().taskId(null).build())
+        .withMessage("taskId is marked non-null but is null");
+  }
+
+  @Test
+  void noTaskId() {
+    assertThatExceptionOfType(IllegalArgumentException.class)
+        .isThrownBy(() -> TaskStatusPollRequest.builder().build())
+        .withMessage("taskId is marked non-null but is null");
+  }
+
+  @Test
+  void nullWaitTime() {
+    assertThatExceptionOfType(IllegalArgumentException.class)
+        .isThrownBy(() -> TaskStatusPollRequest.builder().waitTime(null).build())
+        .withMessage("waitTime is marked non-null but is null");
+  }
+
+  @Test
+  void defaultWaitTime() {
+    assertThat(TaskStatusPollRequest.builder().taskId("1").build())
+        .isNotNull()
+        .extracting(TaskStatusPollRequest::getWaitTime)
+        .asInstanceOf(InstanceOfAssertFactories.DURATION)
+        .isEqualByComparingTo(TaskStatusPollRequest.DEFAULT_STATUS_POLL_WAIT_TIME);
+  }
+}