swagger: Add configuration service and model

This can be used for configuration of the trace server using e.g. files. Common use cases are: - Manage custom analysis (e.g. Trace Compass's XML analysis) - Manage In-And-Out descriptions - Manage custom parsers (trace types) - Manage filter descriptions (e.g. Trace Compass filters) and more. Change-Id: I1ae19e1f67635bd2720c181113e4950a3c315d79 Signed-off-by: Bernd Hufmann <bernd.hufmann@ericsson.com> Reviewed-on: https://git.eclipse.org/r/c/tracecompass.incubator/org.eclipse.tracecompass.incubator/+/204457 Tested-by: Patrick Tasse <patrick.tasse@gmail.com> Tested-by: Trace Compass Bot <tracecompass-bot@eclipse.org> Reviewed-by: Patrick Tasse <patrick.tasse@gmail.com>
eclipse-tracecompass-incubator · Sep 26, 2023 · 468310b · 468310b
1 parent 70285ea
commit 468310b
Show file tree

Hide file tree

Showing 7 changed files with 361 additions and 0 deletions.
diff --git a/...se/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/Configuration.java b/...se/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/Configuration.java
@@ -0,0 +1,55 @@
+/*******************************************************************************
+ * Copyright (c) 2023 Ericsson
+ *
+ * All rights reserved. This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0 which
+ * accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+
+package org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model;
+
+import java.util.Map;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+/**
+ * Contributes to the model used for TSP swagger-core annotations.
+ */
+@NonNullByDefault
+public interface Configuration {
+    /**
+     * @return the name of configuration instance
+     */
+    @Schema(description = "The human readable name")
+    String getName();
+
+    /**
+     * @return the ID for of the configuration instance.
+     */
+    @Schema(description = "The unique ID of the configuration instance")
+    String getId();
+
+    /**
+     * @return a short description of this configuration instance.
+     */
+    @Schema(description = "Describes the configuration instance")
+    String getDescription();
+
+    /**
+     * @return the configuration source type
+     */
+    @Schema(description = "The ID of the configuration source type")
+    String getSourceTypeId();
+
+    /**
+     * @return parameters to return. Can be used to show
+     *         more details to users of the configuration instance
+     */
+    @Schema(description = "Optional informational parameters to return. Can be used to show more details to users of the configuration instance.")
+    Map<String, Object> getParameters();
+}
diff --git a/.../incubator/internal/trace/server/jersey/rest/core/model/ConfigurationQueryParameters.java b/.../incubator/internal/trace/server/jersey/rest/core/model/ConfigurationQueryParameters.java
@@ -0,0 +1,31 @@
+/**********************************************************************
+ * Copyright (c) 2023 Ericsson
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License 2.0 which
+ * accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ **********************************************************************/
+
+package org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model;
+
+import java.util.Map;
+
+import org.eclipse.jdt.annotation.NonNull;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+/**
+ * Contributes to the model used for TSP swagger-core annotations.
+ */
+public interface ConfigurationQueryParameters {
+
+    /**
+     * @return The query parameter map.
+     */
+    @NonNull
+    @Schema(required = true, description = "Parameters as specified in corresponding ConfigurationTypeDescriptor. Use key `path` for file URI string values.")
+    Map<String, Object> getParameters();
+}
diff --git a/...mpass/incubator/internal/trace/server/jersey/rest/core/model/ConfigurationSourceType.java b/...mpass/incubator/internal/trace/server/jersey/rest/core/model/ConfigurationSourceType.java
@@ -0,0 +1,51 @@
+/*******************************************************************************
+ * Copyright (c) 2023 Ericsson
+ *
+ * All rights reserved. This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0 which
+ * accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+
+package org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model;
+
+import java.util.List;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+/**
+ * Contributes to the model used for TSP swagger-core annotations.
+ */
+@NonNullByDefault
+public interface ConfigurationSourceType {
+
+    /**
+     * @return the name of the configuration source type
+     */
+    @Schema(description = "The human readable name")
+    String getName();
+
+    /**
+     * @return the ID for of the configuration source type
+     */
+    @Schema(description = "The unique ID of the configuration source type")
+    String getId();
+
+    /**
+     * @return a short description of this configuration source type
+     */
+    @Schema(description = "Describes the configuration source type")
+    String getDescription();
+
+    /**
+     * @returns a list of query parameter keys to be passed when creating
+     *          configuration instance of this type. Use 'path' key for file
+     *          URIs.
+     */
+    @Schema(description = "A list of query parameter keys to be passed when creating configuration instance of this type. Use 'path' key for file URIs")
+    List<String> getQueryParameterKeys();
+}
diff --git a/...ncubator/internal/trace/server/jersey/rest/core/services/ConfigurationManagerService.java b/...ncubator/internal/trace/server/jersey/rest/core/services/ConfigurationManagerService.java
@@ -0,0 +1,212 @@
+/*******************************************************************************
+ * Copyright (c) 2023 Ericsson
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License 2.0 which
+ * accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+
+package org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services;
+
+import static org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.EndpointConstants.CFG_CONFIG_ID;
+import static org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.EndpointConstants.CFG_CREATE_DESC;
+import static org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.EndpointConstants.CFG_KEYS_DESC;
+import static org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.EndpointConstants.CFG_PATH_EX;
+import static org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.EndpointConstants.CFG_TYPE_ID;
+import static org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.EndpointConstants.CFG_UPDATE_DESC;
+import static org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.EndpointConstants.INVALID_PARAMETERS;
+
+import java.util.Collections;
+
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.Response.Status;
+
+import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.ConfigurationQueryParameters;
+import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.QueryParameters;
+
+import io.swagger.v3.oas.annotations.Hidden;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.ExampleObject;
+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;
+
+/**
+ * Service to manage configurations
+ *
+ * @author Bernd Hufmann
+ */
+@Hidden
+@Path("/config")
+@Tag(name = EndpointConstants.CFG)
+public class ConfigurationManagerService {
+
+    /**
+     * GET a list of available configuration source types
+     *
+     * @return list of available configuration source types
+     */
+    @GET
+    @Path("/types/")
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Get the list of configuration source types defined on the server", responses = {
+            @ApiResponse(responseCode = "200", description = "Returns a list of configuration source types", content = @Content(array = @ArraySchema(schema = @Schema(implementation = org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.ConfigurationSourceType.class))))
+    })
+    public Response getConfigurationTypes() {
+        return Response.ok(Collections.emptyList()).build();
+    }
+
+    /**
+     * GET a single configuration source type
+     *
+     * @param typeId
+     *            the configuration source type ID
+     *
+     * @return a configuration source type
+     */
+    @GET
+    @Path("/types/{typeId}")
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Get a single configuration source type defined on the server", responses = {
+            @ApiResponse(responseCode = "200", description = "Returns a single configuration source type", content = @Content(array = @ArraySchema(schema = @Schema(implementation = org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.ConfigurationSourceType.class))))
+    })
+    public Response getConfigurationType(@Parameter(description = CFG_TYPE_ID) @PathParam("typeId") String typeId) {
+        return Response.status(Status.NOT_IMPLEMENTED).entity("Not Implemented").build(); //$NON-NLS-1$
+    }
+
+    /**
+     * GET a list of configuration instances of a given configuration source
+     * type.
+     *
+     * @param typeId
+     *            the configuration source type ID
+     * @return list of configuration instances of a given configuration source
+     *         type.
+     */
+    @GET
+    @Path("/types/{typeId}/configs")
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Get the list of configurations that are instantiated of a given configuration source type", responses = {
+            @ApiResponse(responseCode = "200", description = "Get the list of configuration descriptors ", content = @Content(array = @ArraySchema(schema = @Schema(implementation = org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.Configuration.class)))),
+            @ApiResponse(responseCode = "404", description = EndpointConstants.NO_SUCH_CONFIGURATION, content = @Content(schema = @Schema(implementation = String.class)))
+    })
+    public Response getConfigurations(@Parameter(description = CFG_TYPE_ID) @PathParam("typeId") String typeId) {
+        return Response.ok(Collections.emptyList()).build();
+    }
+
+    /**
+     * POST a custom configuration to the server
+     *
+     * @param typeId
+     *            the configuration source type ID
+     * @param queryParameters
+     *            the query parameters
+     * @return status and collection of configuration descriptor, if successful
+     */
+    @POST
+    @Path("/types/{typeId}/configs")
+    @Consumes(MediaType.APPLICATION_JSON)
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Create a configuration instance for the given configuration source type", responses = {
+            @ApiResponse(responseCode = "200", description = "The configuration instance was successfully created", content = @Content(schema = @Schema(implementation = org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.Configuration.class))),
+            @ApiResponse(responseCode = "400", description = INVALID_PARAMETERS, content = @Content(schema = @Schema(implementation = String.class))),
+            @ApiResponse(responseCode = "404", description = EndpointConstants.NO_SUCH_CONFIGURATION, content = @Content(schema = @Schema(implementation = String.class))),
+            @ApiResponse(responseCode = "500", description = "Internal trace-server error while trying to create configuration instance", content = @Content(schema = @Schema(implementation = String.class)))
+    })
+    public Response postConfiguration(@Parameter(description = CFG_TYPE_ID) @PathParam("typeId") String typeId,
+            @RequestBody(description = CFG_CREATE_DESC + " " + CFG_KEYS_DESC, content = {
+                    @Content(examples = @ExampleObject("{\"parameters\":{" + CFG_PATH_EX +
+                            "}}"), schema = @Schema(implementation = ConfigurationQueryParameters.class))
+            }, required = true) QueryParameters queryParameters) {
+        return Response.status(Status.NOT_IMPLEMENTED).entity("Not Implemented").build(); //$NON-NLS-1$
+    }
+
+    /**
+     * GET a custom configuration by ID
+     *
+     * @param typeId
+     *            the configuration source type ID
+     * @param configId
+     *            the configuration instance ID
+     * @return status and the configuration instance, if successful
+     */
+    @GET
+    @Path("/types/{typeId}/configs/{configId}")
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Get a configuration instance of a given configuration source type", responses = {
+            @ApiResponse(responseCode = "200", description = "Get a configuration instance", content = @Content(schema = @Schema(implementation = org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.Configuration.class))),
+            @ApiResponse(responseCode = "404", description = EndpointConstants.NO_SUCH_CONFIGURATION, content = @Content(schema = @Schema(implementation = String.class)))
+    })
+    public Response getConfiguration(@Parameter(description = CFG_TYPE_ID) @PathParam("typeId") String typeId,
+            @Parameter(description = CFG_CONFIG_ID) @PathParam("configId") String configId) {
+        return Response.status(Status.NOT_IMPLEMENTED).entity("Not Implemented").build(); //$NON-NLS-1$
+    }
+
+    /**
+     * PUT a custom configuration to the server
+     *
+     * @param typeId
+     *            the configuration source type ID
+     * @param configId
+     *            the configuration instance ID
+     * @param queryParameters
+     *            the query parameters
+     * @return status and the updated configuration instance, if successful
+     */
+    @PUT
+    @Path("/types/{typeId}/configs/{configId}")
+    @Consumes(MediaType.APPLICATION_JSON)
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Update a configuration instance of a given configuration source type", responses = {
+            @ApiResponse(responseCode = "200", description = "The configuration instance was successfully updated", content = @Content(schema = @Schema(implementation = org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.Configuration.class))),
+            @ApiResponse(responseCode = "400", description = INVALID_PARAMETERS, content = @Content(schema = @Schema(implementation = String.class))),
+            @ApiResponse(responseCode = "404", description = EndpointConstants.NO_SUCH_CONFIGURATION, content = @Content(schema = @Schema(implementation = String.class))),
+            @ApiResponse(responseCode = "500", description = "Internal trace-server error while trying to update configuration instance", content = @Content(schema = @Schema(implementation = String.class)))
+    })
+    public Response putConfiguration(@Parameter(description = CFG_TYPE_ID) @PathParam("typeId") String typeId,
+            @Parameter(description = CFG_CONFIG_ID) @PathParam("configId") String configId,
+            @RequestBody(description = CFG_UPDATE_DESC + " " + CFG_KEYS_DESC, content = {
+                    @Content(examples = @ExampleObject("{\"parameters\":{" + CFG_PATH_EX +
+                            "}}"), schema = @Schema(implementation = ConfigurationQueryParameters.class))
+            }, required = true) QueryParameters queryParameters) {
+        return Response.status(Status.NOT_IMPLEMENTED).entity("Not Implemented").build(); //$NON-NLS-1$
+    }
+
+    /**
+     * DELETE a configuration by type and instance id
+     *
+     * @param typeId
+     *            the configuration source type ID
+     * @param configId
+     *            the configuration instance ID
+     * @return status and the deleted configuration instance, if successful
+     */
+    @DELETE
+    @Path("/types/{typeId}/configs/{configId}")
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Delete a configuration instance of a given configuration source type", responses = {
+            @ApiResponse(responseCode = "200", description = "The configuration instance was successfully deleted", content = @Content(schema = @Schema(implementation = org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.Configuration.class))),
+            @ApiResponse(responseCode = "404", description = EndpointConstants.NO_SUCH_CONFIGURATION, content = @Content(schema = @Schema(implementation = String.class))),
+            @ApiResponse(responseCode = "500", description = "Internal trace-server error while trying to delete configuration instance", content = @Content(schema = @Schema(implementation = String.class)))
+    })
+    public Response deleteConfiguration(@Parameter(description = CFG_TYPE_ID) @PathParam("typeId") String typeId,
+            @Parameter(description = CFG_CONFIG_ID) @PathParam("configId") String configId) {
+        return Response.status(Status.NOT_IMPLEMENTED).entity("Not Implemented").build(); //$NON-NLS-1$
+    }
+}
diff --git a/...ompass/incubator/internal/trace/server/jersey/rest/core/services/DataProviderService.java b/...ompass/incubator/internal/trace/server/jersey/rest/core/services/DataProviderService.java
@@ -12,6 +12,7 @@
 package org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services;
 
 import static org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.EndpointConstants.ANN;
+import static org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.EndpointConstants.CFG;
 import static org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.EndpointConstants.COLUMNS;
 import static org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.EndpointConstants.COLUMNS_EX;
 import static org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.EndpointConstants.CONSISTENT_PARENT;
@@ -197,6 +198,7 @@
         @Server(url = SERVER)
 }, tags = {
         @Tag(name = ANN, description = "Retrieve annotations for different outputs."),
+        @Tag(name = CFG, description = "How to manage configuration source types and configurations."),
         @Tag(name = DIA, description = "Refer to the server's status."),
         @Tag(name = EXP, description = "How to manage experiments on your server; an experiment represents a collection of traces, which can produce output models."),
         @Tag(name = STY, description = "Retrieve styles for different outputs."),