feat: Introduce API extension point and enhance builder usage (#252)

- Added SPI-based extension points for `DoclingServeApi` using `DoclingServeApiBuilderFactory`.
- Replaced `DoclingServeClientBuilderFactory` with a unified `DoclingServeApi.builder()` factory method.
- Updated API and client layers to align with the new builder factory model.
- Simplified documentation and examples to reflect the updated API usage.
- Enhanced test coverage for SPI-based customization and factory functionality.

Signed-off-by: Eric Deandrea <[email protected]>

Author: edeandrea

README.md

@@ -45,16 +45,17 @@ This project provides the following artifacts:
 
 ## Getting started
 
-Use `DoclingServeApi.convertSource()` to convert individual documents. For example:
+Use `DoclingServeApi.convertSource()` to convert individual documents (make sure both `docling-serve-api` and `docling-serve-client` are on your classpath).
+
+For example:
 
 ```java
 import ai.docling.serve.api.DoclingServeApi;
 import ai.docling.serve.api.convert.request.ConvertDocumentRequest;
 import ai.docling.serve.api.convert.request.source.HttpSource;
 import ai.docling.serve.api.convert.response.ConvertDocumentResponse;
-import ai.docling.serve.client.DoclingServeClientBuilderFactory;
 
-DoclingServeApi doclingServeApi = DoclingServeClientBuilderFactory.newBuilder()
+DoclingServeApi doclingServeApi = DoclingServeApi.builder()
     .baseUrl("<location of docling serve instance>")
     .build();
 
@@ -124,5 +125,3 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome!
-
-### IBM ❤️ Open Source AI

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

@@ -1,17 +1,52 @@
 package ai.docling.serve.api;
 
+import static ai.docling.serve.api.util.ValidationUtils.ensureNotBlank;
+
+import java.net.URI;
 import java.time.Duration;
+import java.util.stream.Collectors;
 
 import org.jspecify.annotations.Nullable;
 
 import ai.docling.serve.api.convert.request.ConvertDocumentRequest;
+import ai.docling.serve.api.spi.DoclingServeApiBuilderFactory;
+import ai.docling.serve.api.spi.ServiceLoaderHelper;
 
 /**
  * Docling Serve API interface.
  */
 public interface DoclingServeApi
     extends DoclingServeHealthApi, DoclingServeConvertApi, DoclingServeChunkApi, DoclingServeClearApi, DoclingServeTaskApi {
 
+  /**
+   * Creates and returns a builder instance capable of constructing implementations of {@link DoclingServeApi}.
+   * The method ensures that exactly one factory capable of building a builder instance is available
+   * via the {@link DoclingServeApiBuilderFactory} interface.
+   *
+   * If no factories are found, or if multiple factories are found, an {@link IllegalStateException} is thrown.
+   *
+   * @param <T> the type of the {@link DoclingServeApi} implementation being built
+   * @param <B> the type of the builder implementation for the {@link DoclingServeApi}
+   * @return a builder instance of type {@code B} constructed using the available factory
+   * @throws IllegalStateException if no factories or more than one factory are found
+   */
+  static <T extends DoclingServeApi, B extends DoclingApiBuilder<T, B>> B builder() {
+    var factories = ServiceLoaderHelper.loadFactories(DoclingServeApiBuilderFactory.class);
+
+    if (factories.isEmpty()) {
+      // No factory found
+      throw new IllegalStateException("No instance of %s found to build a %s instance. You are probably missing a library on your classpath.".formatted(DoclingServeApiBuilderFactory.class.getName(), DoclingApiBuilder.class.getName()));
+    }
+
+    if (factories.size() > 1) {
+      // Multiple factories found
+      throw new IllegalStateException("Multiple instances of %s found to build a %s instance: [%s]".formatted(DoclingServeApiBuilderFactory.class.getName(), DoclingApiBuilder.class.getName(), factories.stream().map(f -> f.getClass().getName()).collect(Collectors.joining(", "))));
+    }
+
+    // Only 1 factory (what we want)
+    return factories.iterator().next().getBuilder();
+  }
+
   /**
    * 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
@@ -30,6 +65,31 @@ public interface DoclingServeApi
    * @param <B> the type of the concrete builder implementation.
    */
   interface DoclingApiBuilder<T extends DoclingServeApi, B extends DoclingApiBuilder<T, B>> {
+    /**
+     * Sets the base URL for the client.
+     *
+     * <p>This method configures the base URL that will be used for all API requests
+     * executed by the client. The provided URL must be non-null and not blank.
+     *
+     * @param baseUrl the base URL to use, as a {@code String}
+     * @return this builder instance for method chaining
+     * @throws IllegalArgumentException if {@code baseUrl} is null, blank, or invalid
+     */
+    default B baseUrl(String baseUrl) {
+      return baseUrl(URI.create(ensureNotBlank(baseUrl, "baseUrl")));
+    }
+
+    /**
+     * Sets the base URL for the client.
+     *
+     * <p>This method configures the base URL that will be used for all API requests
+     * executed by the client. The provided URL must be non-null.
+     *
+     * @param baseUrl the base URL to use, as a {@link URI}
+     * @return this builder instance for method chaining
+     */
+    B baseUrl(URI baseUrl);
+
     /**
      * Sets the API key for authenticating requests made by the client being built.
      *

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/spi/DoclingServeApiBuilderFactory.java

@@ -0,0 +1,20 @@
+package ai.docling.serve.api.spi;
+
+import ai.docling.serve.api.DoclingServeApi;
+import ai.docling.serve.api.DoclingServeApi.DoclingApiBuilder;
+
+/**
+ * Factory interface for creating builder instances to construct implementations of {@link DoclingServeApi}.
+ */
+public interface DoclingServeApiBuilderFactory {
+  /**
+   * Retrieves a builder instance for constructing implementations of {@link DoclingServeApi}.
+   * The returned builder allows customization of various configurations and properties
+   * before creating an instance of the API.
+   *
+   * @param <T> the type of the {@link DoclingServeApi} implementation being built
+   * @param <B> the type of the concrete builder implementation
+   * @return a builder of type {@code B}, which is used to construct instances of {@code T}
+   */
+  <T extends DoclingServeApi, B extends DoclingApiBuilder<T, B>> B getBuilder();
+}

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/spi/ServiceLoaderHelper.java

@@ -0,0 +1,89 @@
+package ai.docling.serve.api.spi;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.ServiceLoader;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Utility wrapper around {@code ServiceLoader.load()}.
+ */
+public final class ServiceLoaderHelper {
+    private ServiceLoaderHelper() {
+    }
+
+    /**
+     * Load the first available service of a given type.
+     *
+     * @param clazz the type of service
+     * @param <T>   the type of service
+     * @return the first service, or {@link Optional#empty()} if none
+     */
+    public static <T> Optional<T> loadFactory(Class<T> clazz) {
+        var factories = loadFactories(clazz, null);
+        return factories.isEmpty() ? Optional.empty() : Optional.ofNullable(factories.iterator().next());
+    }
+
+    /**
+     * Load all the services of a given type.
+     *
+     * @param clazz the type of service
+     * @param <T>   the type of service
+     * @return the list of services, empty if none
+     */
+    public static <T> Collection<T> loadFactories(Class<T> clazz) {
+        return loadFactories(clazz, null);
+    }
+
+    /**
+     * Load all the services of a given type.
+     *
+     * <p>Utility mechanism around {@code ServiceLoader.load()}</p>
+     *
+     * <ul>
+     *     <li>If classloader is {@code null}, will try {@code ServiceLoader.load(clazz)}</li>
+     *     <li>If classloader is not {@code null}, will try {@code ServiceLoader.load(clazz, classloader)}</li>
+     *     </ul>
+     *
+     * <p>If the above return nothing, will fall back to {@code ServiceLoader.load(clazz, $this class loader$)}</p>
+     *
+     * @param clazz       the type of service
+     * @param classLoader the classloader to use, may be null
+     * @param <T>         the type of service
+     * @return the list of services, empty if none
+     */
+    public static <T> Collection<T> loadFactories(Class<T> clazz, @Nullable ClassLoader classLoader) {
+      var factories = Optional.ofNullable(classLoader)
+          .map(cl -> loadAll(ServiceLoader.load(clazz, cl)))
+          .orElseGet(() -> loadAll(ServiceLoader.load(clazz)));
+
+      // By default, ServiceLoader.load uses the TCCL, this may not be enough in environment dealing with
+      // classloaders differently such as OSGi. So we should try to use the classloader having loaded this
+      // class. In OSGi it would be the bundle exposing vert.x and so have access to all its classes.
+      var factoriesToReturn =  factories.isEmpty() ?
+          loadAll(ServiceLoader.load(clazz, ServiceLoaderHelper.class.getClassLoader())) :
+          factories;
+
+      return factoriesToReturn.stream()
+          .filter(Objects::nonNull)
+          .toList();
+    }
+
+    /**
+     * Load all the services from a ServiceLoader.
+     *
+     * @param loader the loader
+     * @param <T>    the type of service
+     * @return the list of services, empty if none
+     */
+    private static <T> List<T> loadAll(ServiceLoader<T> loader) {
+        List<T> list = new ArrayList<>();
+        loader.iterator().forEachRemaining(list::add);
+
+        return list;
+    }
+}

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

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

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

@@ -39,4 +39,8 @@
 
   // Validation API
   exports ai.docling.serve.api.validation;
+
+  // SPI
+  exports ai.docling.serve.api.spi;
+  uses ai.docling.serve.api.spi.DoclingServeApiBuilderFactory;
 }

docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/DoclingServeApiTests.java

@@ -0,0 +1,17 @@
+package ai.docling.serve.api;
+
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+
+import org.junit.jupiter.api.Test;
+
+import ai.docling.serve.api.DoclingServeApi.DoclingApiBuilder;
+import ai.docling.serve.api.spi.DoclingServeApiBuilderFactory;
+
+class DoclingServeApiTests {
+  @Test
+  void noFactoryFound() {
+    assertThatExceptionOfType(IllegalStateException.class)
+        .isThrownBy(() -> DoclingServeApi.builder())
+        .withMessage("No instance of %s found to build a %s instance. You are probably missing a library on your classpath.", DoclingServeApiBuilderFactory.class.getName(), DoclingApiBuilder.class.getName());
+  }
+}

docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/DoclingServeClient.java

@@ -1,6 +1,5 @@
 package ai.docling.serve.client;
 
-import static ai.docling.serve.api.util.ValidationUtils.ensureNotBlank;
 import static ai.docling.serve.api.util.ValidationUtils.ensureNotNull;
 
 import java.io.IOException;
@@ -398,21 +397,6 @@ protected DoclingServeClientBuilder(DoclingServeClient doclingClient) {
       this.apiKey = doclingClient.apiKey;
     }
 
-    /**
-     * Sets the base URL for the client.
-     *
-     * <p>This method configures the base URL that will be used for all API requests
-     * executed by the client. The provided URL must be non-null and not blank.
-     *
-     * @param baseUrl the base URL to use, as a {@code String}
-     * @return this builder instance for method chaining
-     * @throws IllegalArgumentException if {@code baseUrl} is null, blank, or invalid
-     */
-    public B baseUrl(String baseUrl) {
-      this.baseUrl = URI.create(ensureNotBlank(baseUrl, "baseUrl"));
-      return (B) this;
-    }
-
     /**
      * Sets the base URL for the client.
      *
@@ -423,6 +407,7 @@ public B baseUrl(String baseUrl) {
      * @return this builder instance for method chaining
      * @throws IllegalArgumentException if {@code baseUrl} is null
      */
+    @Override
     public B baseUrl(URI baseUrl) {
       this.baseUrl = baseUrl;
       return (B) this;

docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/DoclingServeClientBuilderFactory.java

@@ -1,5 +1,8 @@
 package ai.docling.serve.client;
 
+import ai.docling.serve.api.DoclingServeApi;
+import ai.docling.serve.api.DoclingServeApi.DoclingApiBuilder;
+import ai.docling.serve.api.spi.DoclingServeApiBuilderFactory;
 import ai.docling.serve.client.DoclingServeClient.DoclingServeClientBuilder;
 
 /**
@@ -15,10 +18,7 @@
  * <p>The factory uses a type-safe generic method to support custom subclasses of
  * {@link DoclingServeClient} and {@link DoclingServeClientBuilder}.
  */
-public final class DoclingServeClientBuilderFactory {
-  private DoclingServeClientBuilderFactory() {
-  }
-
+public final class DoclingServeClientBuilderFactory implements DoclingServeApiBuilderFactory {
   /**
    * Creates and returns a new instance of a {@link DoclingServeClientBuilder} compatible
    * with the Jackson version present on the provided classloader's classpath.
@@ -70,6 +70,11 @@ public static <C extends DoclingServeClient, B extends DoclingServeClientBuilder
     return newBuilder(Thread.currentThread().getContextClassLoader());
   }
 
+  @Override
+  public <T extends DoclingServeApi, B extends DoclingApiBuilder<T, B>> B getBuilder() {
+    return (B) newBuilder();
+  }
+
   private enum JacksonVersion {
     JACKSON_2("com.fasterxml.jackson.databind.json.JsonMapper"),
     JACKSON_3("tools.jackson.databind.json.JsonMapper");

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

@@ -9,4 +9,5 @@
   requires java.net.http;
 
   exports ai.docling.serve.client;
+  provides ai.docling.serve.api.spi.DoclingServeApiBuilderFactory with ai.docling.serve.client.DoclingServeClientBuilderFactory;
 }