swagger: Fix specification for sampling in xy output (#238)

server: Fix SeriesModel xValues swagger definition/serializers/tests

Use xValues for array of longs for x values, e.g. timestamps
Use xCategoires for array of category strings for x values
use XRanges for arrays of range (start/stop) for x values

This simplifies the swagger definition and implemntation for xValues of
SeriesModel for both server and client side.

Update TSP version to 0.6.0

Signed-off-by: Bernd Hufmann <[email protected]>
Signed-off-by: Siwei Zhang <[email protected]>
Co-authored-by: Siwei Zhang <[email protected]>
Co-authored-by: Bernd Hufmann <[email protected]>

Author: 3 people

trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.tests/src/org/eclipse/tracecompass/incubator/trace/server/jersey/rest/core/tests/webapp/SamplingSerializerTest.java

@@ -11,8 +11,10 @@
 
 package org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.tests.webapp;
 
-import static org.junit.Assert.*;
+import static org.junit.Assert.assertEquals;
 
+import java.io.IOException;
+import java.io.Serializable;
 import java.util.List;
 
 import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.webapp.SamplingSerializer;
@@ -24,18 +26,22 @@
 import org.junit.Before;
 import org.junit.Test;
 
+import com.fasterxml.jackson.core.JsonGenerator;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializerProvider;
 import com.fasterxml.jackson.databind.module.SimpleModule;
+import com.fasterxml.jackson.databind.ser.std.StdSerializer;
 
 /**
- * Test suite for {@link SamplingSerializer} and {@link SamplingDeserializer}.
+ * Test suite for {@link SamplingSerializer}.
  * <p>
  * Validates JSON round-trip behavior for different {@link ISampling}
  * subtypes: {@link Timestamps}, {@link Categories}, and {@link Ranges}.
  *
  * @author Siwei Zhang
  */
+@SuppressWarnings("null")
 public class SamplingSerializerTest {
 
     private ObjectMapper fMapper;
@@ -49,53 +55,85 @@ public void setup() {
         fMapper = new ObjectMapper();
         SimpleModule module = new SimpleModule();
         module.addSerializer(ISampling.class, new SamplingSerializer());
+        module.addSerializer(TestSampling.class, new TestSamplingSerializer());
         fMapper.registerModule(module);
     }
 
     /**
-     * Test round-trip serialization and deserialization for
-     * {@link ISampling.Timestamps}. The format is a flat array of @NonNull Longs.
+     * Test round-trip serialization {@link ISampling.Timestamps}.
+     * The format is a flat array of @NonNull Longs.
      *
      * @throws JsonProcessingException
      *             if JSON processing fails
      */
     @Test
     public void testTimestampsRoundTrip() throws JsonProcessingException {
-        ISampling original = new Timestamps(new long[] { 1, 2, 3 });
+        TestSampling original = new TestSampling(new Timestamps(new long[] { 1, 2, 3 }));
         String json = fMapper.writeValueAsString(original);
-        assertEquals("[1,2,3]", json);
+        assertEquals("{\"xValues\":[1,2,3]}", json);
     }
 
     /**
-     * Test round-trip serialization and deserialization for
-     * {@link ISampling.Categories}. The format is an array of strings.
+     * Test round-trip serialization {@link ISampling.Categories}.
+     * The format is an array of strings.
      *
      * @throws JsonProcessingException
      *             if JSON processing fails
      */
     @Test
     public void testCategoriesRoundTrip() throws JsonProcessingException {
-        ISampling original = new Categories(List.of("Read", "Write", "Idle"));
+        TestSampling original = new TestSampling(new Categories(List.of("Read", "Write", "Idle")));
         String json = fMapper.writeValueAsString(original);
-        assertEquals("[\"Read\",\"Write\",\"Idle\"]", json);
+        assertEquals("{\"xCategories\":[\"Read\",\"Write\",\"Idle\"]}", json);
     }
 
     /**
-     * Test round-trip serialization and deserialization for
-     * {@link ISampling.Ranges}. The format is a 2D array of timestamp
-     * ranges, i.e., {@code [[start, end], ...]}.
+     * Test round-trip serialization {@link ISampling.Ranges}.
+     * The format is an array of range json objects.
      *
      * @throws JsonProcessingException
      *             if JSON processing fails
      */
     @Test
     public void testTimeRangesRoundTrip() throws JsonProcessingException {
-        ISampling original = new Ranges(List.of(
+        TestSampling original = new TestSampling(new Ranges(List.of(
                 new Range<>(1L, 2L),
                 new Range<>(2L, 3L),
-                new Range<>(3L, 4L)
+                new Range<>(3L, 4L))
         ));
         String json = fMapper.writeValueAsString(original);
-        assertEquals("[[1,2],[2,3],[3,4]]", json);
+        assertEquals("{\"xRanges\":[{\"start\":1,\"end\":2},{\"start\":2,\"end\":3},{\"start\":3,\"end\":4}]}", json);
+    }
+
+    private class TestSampling implements Serializable {
+        private static final long serialVersionUID = 4522987850097455165L;
+        ISampling fSampling;
+
+        public TestSampling(ISampling sampling) {
+            fSampling = sampling;
+        }
+
+        public ISampling getSampling() {
+            return fSampling;
+        }
+    }
+
+    private class TestSamplingSerializer extends StdSerializer<TestSampling> {
+
+        private static final long serialVersionUID = 4522987850097455165L;
+
+        /**
+         * Constructor
+         */
+        public TestSamplingSerializer() {
+            super(TestSampling.class);
+        }
+
+        @Override
+        public void serialize(TestSampling value, JsonGenerator gen, SerializerProvider provider) throws IOException {
+            gen.writeStartObject();
+            gen.writeObject(value.getSampling());
+            gen.writeEndObject();
+        }
     }
 }

trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/Range.java

@@ -0,0 +1,32 @@
+package org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
+
+/**
+ * Represents a closed interval [start, end] for a sampling range.
+ */
+@Schema(
+     name = "Range",
+     description = "An object representing a closed interval with a start and end."
+)
+class Range {
+    @Schema(description = "Start of the range (inclusive).", requiredMode = RequiredMode.REQUIRED)
+    private final long start;
+
+    @Schema(description = "End of the range (inclusive).", requiredMode = RequiredMode.REQUIRED)
+    private final long end;
+
+    public Range(long start, long end) {
+        this.start = start;
+        this.end = end;
+    }
+
+    public long getStart() {
+        return start;
+    }
+
+    public long getEnd() {
+        return end;
+    }
+}

trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/Sampling.java

@@ -11,6 +11,8 @@
 
 package org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model;
 
+import java.util.List;
+
 import org.eclipse.jdt.annotation.NonNull;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
@@ -39,15 +41,25 @@ public interface SeriesModel {
     String getSeriesName();
 
     /**
-     * @return The X values.
+     * @return The X values as list of longs
      */
     @JsonProperty("xValues")
-    @Schema(description = "Sampling values", requiredMode = RequiredMode.REQUIRED, oneOf = {
-            Sampling.TimestampSampling.class,
-            Sampling.CategorySampling.class,
-            Sampling.RangeSampling.class
-    })
-    Sampling getXValues();
+    @Schema(description = "X values as list of int64 values (e.g. timestamps). Example: [100, 200, 350]. Mutually exclusive with xCategories/xRanges.")
+    public List<Long> getXValues();
+
+    /**
+     * @return The X values as list of strings
+     */
+    @JsonProperty("xCategories")
+    @Schema(description = "X values as list of category strings. Example: [\"READ\", \"WRITE\"]. Mutually exclusive with xValues/xRanges.")
+    public List<String> getXCategories();
+
+    /**
+     * @return The X values as list of ranges
+     */
+    @JsonProperty("xRanges")
+    @Schema(description = "X values as list of start/end range objects. Example: [{\"start\": 10, \"end\": 20}, {\"start\": 50, \"end\": 75}]. Mutually exclusive with xValues/xCategories.")
+    public List<Range> getXRanges();
 
     /**
      * @return The Y values.

trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/SeriesModel.java

@@ -84,7 +84,7 @@ public final class EndpointConstants {
     static final String LICENSE = "Apache 2"; //$NON-NLS-1$
     static final String LICENSE_URL = "http://www.apache.org/licenses/"; //$NON-NLS-1$
     /** The TSP version */
-    public static final String VERSION = "0.5.0"; //$NON-NLS-1$
+    public static final String VERSION = "0.6.0"; //$NON-NLS-1$
     static final String SERVER = "https://localhost:8080/tsp/api"; //$NON-NLS-1$
 
     /**

trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/services/EndpointConstants.java

@@ -26,9 +26,13 @@
 
 /**
  * Custom serializer for all Sampling subtypes.
- * - Timestamps → flat array: [1, 2, 3]
- * - Categories → array of strings: ["Read", "Write"]
- * - TimeRanges → array of arrays: [[1, 2], [2, 3]]
+ *
+ * Note: It serializes only the object content without JSON object start and end marker. Hence
+ * ISampling has to be embedded inside an outer JSON object
+ *
+ * - Timestamps → flat array → "xValues": [1, 2, 3]
+ * - Categories → array of strings → "xCategories": ["Read", "Write"]
+ * - Ranges → array of Range → "xRanges": [{ "start": 1, "end": 2 }, { "start": 3, "end": 4 }]
  */
 public class SamplingSerializer extends StdSerializer<ISampling> {
 
@@ -43,23 +47,20 @@ public SamplingSerializer() {
 
     @Override
     public void serialize(ISampling value, JsonGenerator gen, SerializerProvider provider) throws IOException {
+        // Note that ISampling is not serialized as a json object, but only as json field.
+        // Hence it has to be embedded in an outer JSON object
         if (value instanceof Timestamps timestamps) {
-            gen.writeArray(timestamps.timestamps(), 0, timestamps.timestamps().length);
-
+            gen.writeObjectField("xValues", timestamps.timestamps()); //$NON-NLS-1$
         } else if (value instanceof Categories categories) {
-            gen.writeStartArray();
-            for (String category : categories.categories()) {
-                gen.writeString(category);
-            }
-            gen.writeEndArray();
-
+            gen.writeObjectField("xCategories", categories.categories()); //$NON-NLS-1$
         } else if (value instanceof Ranges timeRanges) {
+            gen.writeFieldName("xRanges"); //$NON-NLS-1$
             gen.writeStartArray();
             for (Range<@NonNull Long> range : timeRanges.ranges()) {
-                gen.writeStartArray();
-                gen.writeNumber(range.start());
-                gen.writeNumber(range.end());
-                gen.writeEndArray();
+                gen.writeStartObject();
+                gen.writeNumberField("start", range.start()); //$NON-NLS-1$
+                gen.writeNumberField("end", range.end()); //$NON-NLS-1$
+                gen.writeEndObject();
             }
             gen.writeEndArray();
         } else {

trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/webapp/SamplingSerializer.java

@@ -16,6 +16,11 @@
 import org.eclipse.jdt.annotation.NonNull;
 import org.eclipse.tracecompass.tmf.core.model.OutputElementStyle;
 import org.eclipse.tracecompass.tmf.core.model.StyleProperties;
+import org.eclipse.tracecompass.tmf.core.model.ISampling;
+import org.eclipse.tracecompass.tmf.core.model.ISampling.Categories;
+import org.eclipse.tracecompass.tmf.core.model.ISampling.Range;
+import org.eclipse.tracecompass.tmf.core.model.ISampling.Ranges;
+import org.eclipse.tracecompass.tmf.core.model.ISampling.Timestamps;
 import org.eclipse.tracecompass.tmf.core.model.xy.ISeriesModel;
 
 import com.fasterxml.jackson.core.JsonGenerator;
@@ -47,7 +52,27 @@ public void serialize(ISeriesModel value, JsonGenerator gen, SerializerProvider
         gen.writeStartObject();
         gen.writeNumberField("seriesId", value.getId()); //$NON-NLS-1$
         gen.writeStringField("seriesName", value.getName()); //$NON-NLS-1$
-        gen.writeObjectField("xValues", value.getSampling()); //$NON-NLS-1$
+
+        // Serialize the sampling
+        ISampling sampling = value.getSampling();
+        if (sampling instanceof Timestamps timestamps) {
+            gen.writeObjectField("xValues", timestamps.timestamps()); //$NON-NLS-1$
+        } else if (sampling instanceof Categories categories) {
+            gen.writeObjectField("xCategories", categories.categories()); //$NON-NLS-1$
+        } else if (sampling instanceof Ranges timeRanges) {
+            gen.writeFieldName("xRanges"); //$NON-NLS-1$
+            gen.writeStartArray();
+            for (Range<@NonNull Long> range : timeRanges.ranges()) {
+                gen.writeStartObject();
+                gen.writeNumberField("start", range.start()); //$NON-NLS-1$
+                gen.writeNumberField("end", range.end()); //$NON-NLS-1$
+                gen.writeEndObject();
+            }
+            gen.writeEndArray();
+        } else {
+            throw new IllegalArgumentException("Unknown Sampling type: " + value.getClass().getName()); //$NON-NLS-1$
+        }
+
         gen.writeObjectField("yValues", value.getData()); //$NON-NLS-1$
 
         // no-op trim below, null-related (unlikely case) warning otherwise-