chore(api): use JsonObject for querying the Catalog API (#204)

* chore(api): use JsonObject for querying the Catalog API

* DEPENDENCIES

.github/workflows/verify.yaml

@@ -29,6 +29,15 @@ jobs:
       - name: Run Checkstyle
         run: ./gradlew checkstyleMain checkstyleTest checkstyleTestFixtures
 
+  Javadoc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: eclipse-edc/.github/.github/actions/setup-build@main
+
+      - name: Run Javadoc
+        run: ./gradlew javadoc
+
   Unit-Tests:
     runs-on: ubuntu-latest
     env:

DEPENDENCIES

@@ -26,7 +26,7 @@ maven/mavencentral/com.fasterxml.jackson.module/jackson-module-jakarta-xmlbind-a
 maven/mavencentral/com.fasterxml.jackson/jackson-bom/2.16.2, Apache-2.0, approved, #11852
 maven/mavencentral/com.fasterxml.jackson/jackson-bom/2.17.1, Apache-2.0, approved, #14162
 maven/mavencentral/com.github.docker-java/docker-java-api/3.3.6, Apache-2.0, approved, #10346
-maven/mavencentral/com.github.docker-java/docker-java-transport-zerodep/3.3.6, Apache-2.0 AND (Apache-2.0 AND BSD-3-Clause), approved, #7946
+maven/mavencentral/com.github.docker-java/docker-java-transport-zerodep/3.3.6, Apache-2.0 AND (Apache-2.0 AND BSD-3-Clause), approved, #15251
 maven/mavencentral/com.github.docker-java/docker-java-transport/3.3.6, Apache-2.0, approved, #7942
 maven/mavencentral/com.google.code.findbugs/jsr305/3.0.2, CC-BY-2.5, approved, #15220
 maven/mavencentral/com.google.code.gson/gson/2.10.1, Apache-2.0, approved, #6159
@@ -109,7 +109,7 @@ maven/mavencentral/org.apache.groovy/groovy/4.0.16, Apache-2.0 AND BSD-3-Clause
 maven/mavencentral/org.apache.httpcomponents.client5/httpclient5/5.1.3, Apache-2.0, approved, #6276
 maven/mavencentral/org.apache.httpcomponents.core5/httpcore5-h2/5.1.3, Apache-2.0, approved, clearlydefined
 maven/mavencentral/org.apache.httpcomponents.core5/httpcore5/5.1.3, Apache-2.0, approved, clearlydefined
-maven/mavencentral/org.apache.httpcomponents/httpclient/4.5.13, Apache-2.0 AND LicenseRef-Public-Domain, approved, CQ23527
+maven/mavencentral/org.apache.httpcomponents/httpclient/4.5.13, Apache-2.0, approved, #15248
 maven/mavencentral/org.apache.httpcomponents/httpcore/4.4.13, Apache-2.0, approved, CQ23528
 maven/mavencentral/org.apache.httpcomponents/httpcore/4.4.14, Apache-2.0, approved, CQ23528
 maven/mavencentral/org.apache.httpcomponents/httpmime/4.5.13, Apache-2.0, approved, CQ11718
@@ -251,6 +251,7 @@ maven/mavencentral/org.eclipse.jetty/jetty-servlet/11.0.21, EPL-2.0 OR Apache-2.
 maven/mavencentral/org.eclipse.jetty/jetty-util/11.0.21, EPL-2.0 OR Apache-2.0, approved, rt.jetty
 maven/mavencentral/org.eclipse.jetty/jetty-webapp/11.0.21, EPL-2.0 OR Apache-2.0, approved, rt.jetty
 maven/mavencentral/org.eclipse.jetty/jetty-xml/11.0.21, EPL-2.0 OR Apache-2.0, approved, rt.jetty
+maven/mavencentral/org.eclipse.parsson/parsson/1.1.6, EPL-2.0, approved, ee4j.parsson
 maven/mavencentral/org.glassfish.hk2.external/aopalliance-repackaged/3.0.6, EPL-2.0 OR GPL-2.0-only with Classpath-exception-2.0, approved, ee4j.glassfish
 maven/mavencentral/org.glassfish.hk2/hk2-api/3.0.6, EPL-2.0 OR GPL-2.0-only with Classpath-exception-2.0, approved, ee4j.glassfish
 maven/mavencentral/org.glassfish.hk2/hk2-locator/3.0.6, EPL-2.0 OR GPL-2.0-only with Classpath-exception-2.0, approved, ee4j.glassfish
@@ -288,8 +289,8 @@ maven/mavencentral/org.junit.jupiter/junit-jupiter-api/5.10.1, EPL-2.0, approved
 maven/mavencentral/org.junit.jupiter/junit-jupiter-api/5.10.2, EPL-2.0, approved, #9714
 maven/mavencentral/org.junit.jupiter/junit-jupiter-engine/5.10.1, EPL-2.0, approved, #9711
 maven/mavencentral/org.junit.jupiter/junit-jupiter-engine/5.10.2, EPL-2.0, approved, #9711
-maven/mavencentral/org.junit.jupiter/junit-jupiter-params/5.10.1, EPL-2.0, approved, #9708
-maven/mavencentral/org.junit.jupiter/junit-jupiter-params/5.10.2, EPL-2.0, approved, #9708
+maven/mavencentral/org.junit.jupiter/junit-jupiter-params/5.10.1, EPL-2.0, approved, #15304
+maven/mavencentral/org.junit.jupiter/junit-jupiter-params/5.10.2, EPL-2.0, approved, #15250
 maven/mavencentral/org.junit.platform/junit-platform-commons/1.10.1, EPL-2.0, approved, #9715
 maven/mavencentral/org.junit.platform/junit-platform-commons/1.10.2, EPL-2.0, approved, #9715
 maven/mavencentral/org.junit.platform/junit-platform-engine/1.10.1, EPL-2.0, approved, #9709

core/federated-catalog-core/src/main/java/org/eclipse/edc/catalog/cache/FederatedCatalogCacheExtension.java

@@ -49,6 +49,7 @@
 import org.eclipse.edc.spi.system.health.HealthCheckService;
 import org.eclipse.edc.spi.types.TypeManager;
 import org.eclipse.edc.transform.spi.TypeTransformerRegistry;
+import org.eclipse.edc.transform.transformer.edc.to.JsonObjectToQuerySpecTransformer;
 import org.eclipse.edc.transform.transformer.edc.to.JsonValueToGenericTypeTransformer;
 
 import java.util.Map;
@@ -148,6 +149,7 @@ private void registerTransformers(ServiceExtensionContext context) {
         transformerRegistry.register(new JsonObjectToDatasetTransformer());
         transformerRegistry.register(new JsonObjectToDataServiceTransformer());
         transformerRegistry.register(new JsonObjectToDistributionTransformer());
+        transformerRegistry.register(new JsonObjectToQuerySpecTransformer());
 
         var jsonFactory = Json.createBuilderFactory(Map.of());
         var mapper = context.getService(TypeManager.class).getMapper(JSON_LD);

extensions/api/federated-catalog-api/build.gradle.kts

@@ -24,6 +24,7 @@ dependencies {
     implementation(libs.edc.spi.transform)
     implementation(libs.edc.spi.web)
     implementation(libs.edc.lib.jerseyproviders)
+    implementation(libs.edc.core.api) // for the ApiCoreSchema
 
     runtimeOnly(libs.edc.spi.jsonld)
     runtimeOnly(libs.edc.json.ld.lib)

extensions/api/federated-catalog-api/src/main/java/org/eclipse/edc/catalog/api/query/FederatedCatalogApi.java

@@ -20,25 +20,28 @@
 import io.swagger.v3.oas.annotations.media.ArraySchema;
 import io.swagger.v3.oas.annotations.media.Content;
 import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.parameters.RequestBody;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.json.JsonArray;
-import org.eclipse.edc.spi.query.QuerySpec;
+import jakarta.json.JsonObject;
+import org.eclipse.edc.api.model.ApiCoreSchema;
 
 import javax.xml.catalog.Catalog;
 
 @OpenAPIDefinition(
         info = @Info(description = "This represents the Federated Catalog API. It serves the cached Catalogs fetched from the data providers.",
-                title = "Federated Catalog API", version = "1"))
+                title = "Federated Catalog API", version = "v1"))
 @Tag(name = "Federated Catalog")
 public interface FederatedCatalogApi {
     @Operation(description = "Obtains all Catalog currently held by this cache instance",
+            requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = ApiCoreSchema.QuerySpecSchema.class))),
             responses = {
                     @ApiResponse(responseCode = "200", description = "A list of Catalog is returned, potentially empty",
                             content = @Content(array = @ArraySchema(schema = @Schema(implementation = Catalog.class)))),
                     @ApiResponse(responseCode = "500", description = "A Query could not be completed due to an internal error")
             }
 
     )
-    JsonArray getCachedCatalog(QuerySpec catalogQuery);
+    JsonArray getCachedCatalog(JsonObject querySpec);
 }

extensions/api/federated-catalog-api/src/main/java/org/eclipse/edc/catalog/api/query/FederatedCatalogApiController.java

@@ -26,6 +26,7 @@
 import org.eclipse.edc.spi.result.AbstractResult;
 import org.eclipse.edc.spi.result.Result;
 import org.eclipse.edc.transform.spi.TypeTransformerRegistry;
+import org.eclipse.edc.web.spi.exception.InvalidRequestException;
 import org.eclipse.edc.web.spi.exception.ServiceResultHandler;
 
 import javax.xml.catalog.Catalog;
@@ -47,8 +48,11 @@ public FederatedCatalogApiController(QueryService queryService, TypeTransformerR
 
     @Override
     @POST
-    public JsonArray getCachedCatalog(QuerySpec catalogQuery) {
-        var catalogs = queryService.getCatalog(catalogQuery)
+    public JsonArray getCachedCatalog(JsonObject catalogQuery) {
+        var querySpec = transformerRegistry.transform(catalogQuery, QuerySpec.class)
+                .orElseThrow(InvalidRequestException::new);
+
+        var catalogs = queryService.getCatalog(querySpec)
                 .orElseThrow(ServiceResultHandler.exceptionMapper(Catalog.class));
 
         return catalogs.stream().map(c -> transformerRegistry.transform(c, JsonObject.class))

extensions/api/federated-catalog-api/src/main/java/org/eclipse/edc/catalog/api/query/FederatedCatalogCacheQueryApiExtension.java → extensions/api/federated-catalog-api/src/main/java/org/eclipse/edc/catalog/api/query/FederatedCatalogApiExtension.java

@@ -33,8 +33,8 @@
 import static org.eclipse.edc.policy.model.OdrlNamespace.ODRL_SCHEMA;
 import static org.eclipse.edc.spi.constants.CoreConstants.JSON_LD;
 
-@Extension(value = FederatedCatalogCacheQueryApiExtension.NAME)
-public class FederatedCatalogCacheQueryApiExtension implements ServiceExtension {
+@Extension(value = FederatedCatalogApiExtension.NAME)
+public class FederatedCatalogApiExtension implements ServiceExtension {
 
     public static final String NAME = "Cache Query API Extension";
     private static final String CATALOG_QUERY_SCOPE = "CATALOG_QUERY_API";

extensions/api/federated-catalog-api/src/main/resources/META-INF/services/org.eclipse.edc.spi.system.ServiceExtension

@@ -12,4 +12,4 @@
 #
 #
 
-org.eclipse.edc.catalog.api.query.FederatedCatalogCacheQueryApiExtension
+org.eclipse.edc.catalog.api.query.FederatedCatalogApiExtension

extensions/api/federated-catalog-api/src/test/java/org/eclipse/edc/catalog/api/query/FederatedCatalogApiControllerTest.java

@@ -17,7 +17,6 @@
 import io.restassured.specification.RequestSpecification;
 import jakarta.json.Json;
 import org.eclipse.edc.catalog.cache.query.QueryServiceImpl;
-import org.eclipse.edc.catalog.spi.model.FederatedCatalogCacheQuery;
 import org.eclipse.edc.catalog.store.InMemoryFederatedCatalogCache;
 import org.eclipse.edc.catalog.transform.JsonObjectToCatalogTransformer;
 import org.eclipse.edc.catalog.transform.JsonObjectToDataServiceTransformer;
@@ -30,8 +29,8 @@
 import org.eclipse.edc.protocol.dsp.catalog.transform.from.JsonObjectFromDataServiceTransformer;
 import org.eclipse.edc.protocol.dsp.catalog.transform.from.JsonObjectFromDatasetTransformer;
 import org.eclipse.edc.protocol.dsp.catalog.transform.from.JsonObjectFromDistributionTransformer;
-import org.eclipse.edc.spi.query.QuerySpec;
 import org.eclipse.edc.transform.TypeTransformerRegistryImpl;
+import org.eclipse.edc.transform.transformer.edc.to.JsonObjectToQuerySpecTransformer;
 import org.eclipse.edc.web.jersey.testfixtures.RestControllerTestBase;
 import org.junit.jupiter.api.Test;
 
@@ -56,7 +55,7 @@ void queryApi_whenEmptyResult() {
         when(store.query(any())).thenReturn(Collections.emptyList());
         baseRequest()
                 .contentType(JSON)
-                .body(FederatedCatalogCacheQuery.Builder.newInstance().build())
+                .body("{}")
                 .post("/federatedcatalog")
                 .then()
                 .log().ifError()
@@ -72,7 +71,7 @@ void queryApi_whenResultsReturned() {
 
         baseRequest()
                 .contentType(JSON)
-                .body(QuerySpec.none())
+                .body("{}")
                 .post("/federatedcatalog")
                 .then()
                 .log().ifError()
@@ -87,7 +86,7 @@ void queryApi_whenQueryUnsuccessful() {
 
         baseRequest()
                 .contentType(JSON)
-                .body(FederatedCatalogCacheQuery.Builder.newInstance().build())
+                .body("{}")
                 .post("/federatedcatalog")
                 .then()
                 .statusCode(500);
@@ -106,6 +105,7 @@ protected Object controller() {
         typeTransformerRegistry.register(new JsonObjectToDatasetTransformer());
         typeTransformerRegistry.register(new JsonObjectToDataServiceTransformer());
         typeTransformerRegistry.register(new JsonObjectToDistributionTransformer());
+        typeTransformerRegistry.register(new JsonObjectToQuerySpecTransformer());
         return new FederatedCatalogApiController(new QueryServiceImpl(store), typeTransformerRegistry);
     }
 

gradle/libs.versions.toml

@@ -16,6 +16,7 @@ edc-api-control-config = { module = "org.eclipse.edc:control-api-configuration",
 edc-api-observability = { module = "org.eclipse.edc:api-observability", version.ref = "edc" }
 edc-boot = { module = "org.eclipse.edc:boot", version.ref = "edc" }
 edc-config-filesystem = { module = "org.eclipse.edc:configuration-filesystem", version.ref = "edc" }
+edc-core-api = { module = "org.eclipse.edc:api-core", version.ref = "edc" }
 edc-core-connector = { module = "org.eclipse.edc:connector-core", version.ref = "edc" }
 edc-core-controlplane = { module = "org.eclipse.edc:control-plane-core", version.ref = "edc" }
 edc-core-dataPlane-selector = { module = "org.eclipse.edc:data-plane-selector-core", version.ref = "edc" }

spi/federated-catalog-spi/src/main/java/org/eclipse/edc/catalog/spi/QueryService.java

@@ -14,7 +14,6 @@
 
 package org.eclipse.edc.catalog.spi;
 
-import org.eclipse.edc.catalog.spi.model.FederatedCatalogCacheQuery;
 import org.eclipse.edc.connector.controlplane.asset.spi.domain.Asset;
 import org.eclipse.edc.connector.controlplane.catalog.spi.Catalog;
 import org.eclipse.edc.spi.query.QuerySpec;
@@ -23,7 +22,7 @@
 import java.util.Collection;
 
 /**
- * Accepts a {@link FederatedCatalogCacheQuery} and fetches a collection of {@link Asset} that conform to that query.
+ * Accepts a {@link QuerySpec} and fetches a collection of {@link Asset} that conform to that query.
  */
 @FunctionalInterface
 public interface QueryService {

system-tests/component-tests/src/test/java/org/eclipse/edc/catalog/CatalogRuntimeComponentTest.java

@@ -26,10 +26,10 @@
 import org.eclipse.edc.jsonld.spi.JsonLd;
 import org.eclipse.edc.junit.annotations.ComponentTest;
 import org.eclipse.edc.junit.extensions.EmbeddedRuntime;
+import org.eclipse.edc.junit.extensions.RuntimeExtension;
 import org.eclipse.edc.junit.extensions.RuntimePerMethodExtension;
 import org.eclipse.edc.protocol.dsp.http.spi.dispatcher.DspHttpRemoteMessageDispatcher;
 import org.eclipse.edc.spi.message.RemoteMessageDispatcherRegistry;
-import org.eclipse.edc.spi.monitor.Monitor;
 import org.eclipse.edc.spi.response.StatusResult;
 import org.eclipse.edc.transform.spi.TypeTransformerRegistry;
 import org.junit.jupiter.api.BeforeEach;
@@ -78,9 +78,9 @@ public class CatalogRuntimeComponentTest {
     public static final String TEST_CATALOG_ID = "test-catalog-id";
     private static final Duration TEST_TIMEOUT = ofSeconds(10);
     private static final ObjectMapper OBJECT_MAPPER = createObjectMapper();
-    private static final JsonLd JSON_LD_SERVICE = new TitaniumJsonLd(mock(Monitor.class));
+    private static final JsonLd JSON_LD_SERVICE = new TitaniumJsonLd(mock());
     @RegisterExtension
-    protected static RuntimePerMethodExtension runtimePerClassExtension = new RuntimePerMethodExtension(new EmbeddedRuntime("catalog", Map.of(
+    protected static RuntimeExtension runtimePerClassExtension = new RuntimePerMethodExtension(new EmbeddedRuntime("catalog", Map.of(
             // make sure only one crawl-run is performed
             "edc.catalog.cache.execution.period.seconds", "2",
             // number of crawlers will be limited by the number of crawl-targets