feat: Implement the clear and task APIs

Also enabled parallel builds for performance

Fixes #188

Signed-off-by: Eric Deandrea <eric.deandrea@ibm.com>

Author: edeandrea

README.md

@@ -3,6 +3,8 @@
 This is the repository for Docling Java, a Java API for using [Docling](https://github.com/docling-project).
 
 [![Docs](https://img.shields.io/badge/docs-live-brightgreen)](https://docling-project.github.io/docling-java/)
+[![docling-core version](https://img.shields.io/maven-central/v/ai.docling/docling-core?label=docling-core
+)](https://docling-project.github.io/docling-java/dev/core)
 [![docling-serve-api version](https://img.shields.io/maven-central/v/ai.docling/docling-serve-api?label=docling-serve-api
 )](https://docling-project.github.io/docling-java/dev/docling-serve/serve-api/)
 [![docling-serve-client version](https://img.shields.io/maven-central/v/ai.docling/docling-serve-client?label=docling-serve-client)](https://docling-project.github.io/docling-java/dev/docling-serve/serve-client/)

buildSrc/src/main/kotlin/docling-java-shared.gradle.kts

@@ -36,10 +36,13 @@ testing {
   }
 }
 
-tasks.withType<Test> {
+tasks.withType<Test>().configureEach {
   // Use JUnit Platform for unit tests.
   useJUnitPlatform()
 
+  maxParallelForks = (Runtime.getRuntime().availableProcessors() / 2).coerceAtLeast(1)
+  forkEvery = 100
+
   testLogging {
     events("PASSED", "FAILED", "SKIPPED", "STANDARD_OUT", "STANDARD_ERROR")
     showStandardStreams = true
@@ -65,6 +68,10 @@ tasks.withType<Test> {
   }
 }
 
+tasks.withType<JavaCompile>().configureEach {
+  options.isFork = true
+}
+
 tasks.withType<Javadoc> {
   isFailOnError = false
 

docling-serve/docling-serve-api/build.gradle.kts

@@ -20,5 +20,6 @@ dependencies {
 }
 
 tasks.withType<Javadoc> {
+  source = sourceSets["main"].allJava
   exclude("**/lombok.config")
 }

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

@@ -1,44 +1,10 @@
 package ai.docling.serve.api;
 
-import ai.docling.serve.api.chunk.request.HierarchicalChunkDocumentRequest;
-import ai.docling.serve.api.chunk.request.HybridChunkDocumentRequest;
-import ai.docling.serve.api.chunk.response.ChunkDocumentResponse;
-import ai.docling.serve.api.convert.request.ConvertDocumentRequest;
-import ai.docling.serve.api.convert.response.ConvertDocumentResponse;
-import ai.docling.serve.api.health.HealthCheckResponse;
-
 /**
  * Docling Serve API interface.
  */
-public interface DoclingServeApi {
-
-  /**
-   * Executes a health check for the API and retrieves the health status of the service.
-   *
-   * @return a {@link HealthCheckResponse} object containing the health status of the API.
-   */
-  HealthCheckResponse health();
-
-  /**
-   * Converts the provided document source(s) into a processed document based on the specified options.
-   *
-   * @param request the {@link ConvertDocumentRequest} containing the source(s), conversion options, and optional target.
-   * @return a {@link ConvertDocumentResponse} containing the processed document data, processing details, and any errors.
-   */
-  ConvertDocumentResponse convertSource(ConvertDocumentRequest request);
-
-  /**
-   * Converts and chunks the provided document source(s) into a processed document based on the specified options
-   * and using a hierarchical chunker for splitting the document into smaller chunks.
-   */
-  ChunkDocumentResponse chunkSourceWithHierarchicalChunker(HierarchicalChunkDocumentRequest request);
-
-  /**
-   * Converts and chunks the provided document source(s) into a processed document based on the specified options
-   * and using a hybrid chunker for splitting the document into smaller chunks.
-   */
-  ChunkDocumentResponse chunkSourceWithHybridChunker(HybridChunkDocumentRequest request);
-
+public interface DoclingServeApi
+    extends DoclingServeHealthApi, DoclingServeConvertApi, DoclingServeChunkApi, DoclingServeClearApi, DoclingServeTaskApi {
   /**
    * Creates and returns a builder instance capable of constructing a duplicate or modified
    * version of the current API instance. The builder provides a customizable way to adjust
@@ -98,6 +64,30 @@ default B logResponses() {
      */
     B logResponses(boolean logResponses);
 
+    /**
+     * Configures whether the API client should format JSON requests and responses in a "pretty" format.
+     * Pretty formatting organizes the response data to improve readability,
+     * typically by adding spacing and line breaks.
+     *
+     * This setting does not affect the functional content of the response but can
+     * assist with debugging or human-readable output for development purposes.
+     *
+     * @param prettyPrint {@code true} to enable pretty-printing of JSON requests and responses;
+     *                    {@code false} to use compact formatting.
+     * @return {@code this} builder instance for fluent API usage.
+     */
+    B prettyPrint(boolean prettyPrint);
+
+    /**
+     * Configures the API client to format JSON requests and responses in a "pretty" format.
+     * Pretty formatting improves readability by including spacing and line breaks.
+     *
+     * @return {@code this} builder instance for fluent API usage.
+     */
+    default B prettyPrint() {
+      return prettyPrint(true);
+    }
+
     /**
      * Builds and returns an instance of the specified type, representing the completed configuration
      * of the builder. The returned instance is typically an implementation of the Docling API.

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

@@ -0,0 +1,24 @@
+package ai.docling.serve.api;
+
+import ai.docling.serve.api.chunk.request.HierarchicalChunkDocumentRequest;
+import ai.docling.serve.api.chunk.request.HybridChunkDocumentRequest;
+import ai.docling.serve.api.chunk.response.ChunkDocumentResponse;
+
+/**
+ * Represents the Docling Serve Chunk API, providing methods for processing document sources
+ * by splitting them into smaller chunks using various chunking strategies. This interface
+ * ensures flexibility by supporting both hierarchical and hybrid chunking mechanisms.
+ */
+public interface DoclingServeChunkApi {
+  /**
+   * Converts and chunks the provided document source(s) into a processed document based on the specified options
+   * and using a hierarchical chunker for splitting the document into smaller chunks.
+   */
+  ChunkDocumentResponse chunkSourceWithHierarchicalChunker(HierarchicalChunkDocumentRequest request);
+
+  /**
+   * Converts and chunks the provided document source(s) into a processed document based on the specified options
+   * and using a hybrid chunker for splitting the document into smaller chunks.
+   */
+  ChunkDocumentResponse chunkSourceWithHybridChunker(HybridChunkDocumentRequest request);
+}

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

@@ -0,0 +1,33 @@
+package ai.docling.serve.api;
+
+import ai.docling.serve.api.clear.request.ClearResultsRequest;
+import ai.docling.serve.api.clear.response.ClearResponse;
+
+/**
+ * Interface representing the Docling Serve Clear API. This API provides functionality
+ * for managing and cleaning up converters and stale data retained by the service.
+ * It includes methods for clearing registered converters and stored results based
+ * on specified thresholds or default configurations.
+ */
+public interface DoclingServeClearApi {
+  /**
+   * Clears all registered converters associated with the API.
+   * This method removes any previously configured or cached converters,
+   * effectively resetting the converter state to an uninitialized state.
+   * After invoking this method, no converters will be available until new ones are added or configured.
+   */
+  ClearResponse clearConverters();
+
+  /**
+   * Clears previously stored results based on the criteria provided in the request.
+   * This method removes stale results or data that meet the threshold specified
+   * in the {@link ClearResultsRequest}. It is typically used to clean up older
+   * or unused data retained by the service.
+   *
+   * @param request the {@link ClearResultsRequest} containing the criteria for clearing
+   *        results, such as the threshold duration for identifying stale data.
+   * @return a {@link ClearResponse} indicating the outcome of the clear operation,
+   *         including status or potential errors, if applicable.
+   */
+  ClearResponse clearResults(ClearResultsRequest request);
+}

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

@@ -0,0 +1,19 @@
+package ai.docling.serve.api;
+
+import ai.docling.serve.api.convert.request.ConvertDocumentRequest;
+import ai.docling.serve.api.convert.response.ConvertDocumentResponse;
+
+/**
+ * Interface representing the Docling Serve Convert API.
+ * This API is responsible for processing and converting document source(s) into
+ * a structured or processed document format based on the specified conversion options.
+ */
+public interface DoclingServeConvertApi {
+    /**
+   * Converts the provided document source(s) into a processed document based on the specified options.
+   *
+   * @param request the {@link ConvertDocumentRequest} containing the source(s), conversion options, and optional target.
+   * @return a {@link ConvertDocumentResponse} containing the processed document data, processing details, and any errors.
+   */
+  ConvertDocumentResponse convertSource(ConvertDocumentRequest request);
+}

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

@@ -0,0 +1,16 @@
+package ai.docling.serve.api;
+
+import ai.docling.serve.api.health.HealthCheckResponse;
+
+/**
+ * Interface for performing health checks on the Docling service API.
+ * This API is designed to verify and report the operational status of the service.
+ */
+public interface DoclingServeHealthApi {
+    /**
+   * Executes a health check for the API and retrieves the health status of the service.
+   *
+   * @return a {@link HealthCheckResponse} object containing the health status of the API.
+   */
+  HealthCheckResponse health();
+}

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

@@ -0,0 +1,56 @@
+package ai.docling.serve.api;
+
+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;
+
+/**
+ * Defines the interface for the Docling Task API, which provides operations for
+ * managing and querying the status of asynchronous tasks.
+ *
+ * This interface supports task status polling with configurable wait durations
+ * and a default polling mechanism. It serves as the base for specific implementations
+ * such as {@link DoclingServeApi}.
+ */
+public interface DoclingServeTaskApi {
+  /**
+   * Polls the status of a task using the provided request object.
+   * This method allows querying the current status of an asynchronous task
+   * in progress or completed, based on its unique identifier and other
+   * optional parameters such as wait time.
+   *
+   * @param request the {@link TaskStatusPollRequest} containing the details
+   *        for polling, including the task identifier and optional wait duration.
+   * @return a {@link TaskStatusPollResponse} containing the task's current status,
+   *         including progress, position in the queue, and other metadata,
+   *         if available.
+   */
+  TaskStatusPollResponse pollTaskStatus(TaskStatusPollRequest request);
+
+  /**
+   * Converts the task result from a completed process into a document conversion response.
+   * This method processes the provided task result request, retrieves conversion data, and
+   * returns the resulting document conversion details.
+   *
+   * @param request the {@link TaskResultRequest} containing the task identifier for which
+   *                the result is being retrieved and converted.
+   * @return a {@link ConvertDocumentResponse} containing the details of the converted document,
+   *         such as the document data, processing time, status, and any associated errors.
+   */
+  ConvertDocumentResponse convertTaskResult(TaskResultRequest request);
+
+  /**
+   * Processes the result of a completed task request by transforming the task data into
+   * a chunked document response. This method retrieves conversion data specific to the
+   * requested task and generates a response containing the chunked document details.
+   *
+   * @param request the {@link TaskResultRequest} containing the unique task identifier
+   *                for which the result is being processed into chunks.
+   * @return a {@link ChunkDocumentResponse} containing the details of the chunked document,
+   *         including the generated chunks, associated documents, processing time, and any
+   *         relevant metadata.
+   */
+  ChunkDocumentResponse chunkTaskResult(TaskResultRequest request);
+}

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

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