Perf: 1Million Challenge for CDA TS GET

cwms-data-api/build.gradle

@@ -304,6 +304,34 @@ task integrationTests(type: Test) {
     jvmArgs += "-Dcatalina.base=$buildDir/tomcat"
 }
 
+task timeseriesReadBenchmark(type: JavaExec) {
+    group "verification"
+    description = "Run the local time-series read benchmark harness"
+    dependsOn generateConfig
+    dependsOn war
+    dependsOn testClasses
+
+    workingDir = projectDir
+    classpath = sourceSets.test.runtimeClasspath
+    classpath += configurations.baseLibs
+    classpath += configurations.tomcatLibs
+
+    mainClass = "helpers.TimeSeriesReadBenchmark"
+
+    systemProperties += project.properties.findAll { k, v -> k.startsWith("CDA") && !k.startsWith("CDA_JDBC") }
+    systemProperties += project.properties.findAll { k, v -> k.startsWith("testcontainer") }
+    systemProperties += project.properties.findAll { k, v -> k.startsWith("benchmark.") }
+
+    jvmArgs += "-DwarFile=$buildDir/libs/${project.name}-${project.version}.war"
+    jvmArgs += "-DwarContext=/cwms-data"
+    jvmArgs += "-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"
+    jvmArgs += "-Djava.util.logging.config.file=$projectDir/logging.properties"
+    jvmArgs += "-Dorg.apache.tomcat.util.digester.PROPERTY_SOURCE=org.apache.tomcat.util.digester.EnvironmentPropertySource"
+    jvmArgs += "-Dcwms.dataapi.access.provider=MultipleAccessManager"
+    jvmArgs += "-Dcwms.dataapi.access.providers=KeyAccessManager,CwmsAccessManager"
+    jvmArgs += "-Dcatalina.base=$buildDir/tomcat"
+}
+
 task prepareDockerBuild(type: Copy, dependsOn: war) {
     doFirst {
         project.mkdir("$buildDir/docker")

cwms-data-api/src/main/java/cwms/cda/api/Controllers.java

@@ -257,6 +257,13 @@ private Controllers() {
 
     }
 
+    public static int validateTimeSeriesPageSize(int pageSize) {
+        if (pageSize < -1) {
+            throw new IllegalArgumentException(PAGE_SIZE + " must be -1, 0, or a positive integer");
+        }
+        return pageSize;
+    }
+
     /**
      * Marks a meter and starts a timer.
      *

cwms-data-api/src/main/java/cwms/cda/api/TimeSeriesController.java

@@ -354,7 +354,8 @@ public void delete(@NotNull Context ctx, @NotNull String timeseries) {
                         + "offset and timezone."),
                 @OpenApiParam(name = Controllers.TRIM, type = Boolean.class, description = "Specifies "
                         + "whether to trim missing values from the beginning and end of the "
-                        + "retrieved values. "
+                        + "retrieved values. When true and values are returned, the response "
+                        + BEGIN + " and " + END + " fields reflect the returned data window. "
                         + "Only supported for:" + Formats.JSONV2 + " and " + Formats.XMLV2 + ". "
                         + "Default is true."),
                 @OpenApiParam(name = FORMAT,  description = "Specifies the"
@@ -383,7 +384,9 @@ public void delete(@NotNull Context ctx, @NotNull String timeseries) {
                 @OpenApiParam(name = PAGE_SIZE,
                         type = Integer.class,
                         description = "How many entries per page returned. "
-                                + "Default " + DEFAULT_PAGE_SIZE + ".")
+                                + "Default " + DEFAULT_PAGE_SIZE + ". Use 0 to return an empty values array, "
+                                + "or -1 to return the entire window in one response without a next-page cursor. "
+                                + "Values less than -1 are invalid.")
             },
             responses = {
                 @OpenApiResponse(status = STATUS_200,
@@ -435,9 +438,10 @@ public void getAll(@NotNull Context ctx) {
                     String.class, "", metrics, name(TimeSeriesController.class.getName(),
                             GET_ALL));
 
-            int pageSize = queryParamAsClass(ctx, new String[]{PAGE_SIZE  },
+            final int pageSize = Controllers.validateTimeSeriesPageSize(queryParamAsClass(ctx,
+                    new String[]{PAGE_SIZE},
                     Integer.class, DEFAULT_PAGE_SIZE, metrics,
-                    name(TimeSeriesController.class.getName(), GET_ALL));
+                    name(TimeSeriesController.class.getName(), GET_ALL)));
 
             String acceptHeader = ctx.header(Header.ACCEPT);
             ContentType contentType = Formats.parseHeaderAndQueryParm(acceptHeader, format, TimeSeries.class);
@@ -468,7 +472,8 @@ public void getAll(@NotNull Context ctx) {
                         .build();
                 // Execute DAO call with a timeout so we can return a clearer message instead of a generic 500
                 int apiTimeoutMs = Integer.getInteger("cwms.cda.api.apiTimeoutMs", 45000);
-                CompletableFuture<TimeSeries> daoFuture = CompletableFuture.supplyAsync(() -> dao.getTimeseries(cursor, pageSize, requestParameters));
+                CompletableFuture<TimeSeries> daoFuture = CompletableFuture.supplyAsync(
+                        () -> dao.getTimeseries(cursor, pageSize, requestParameters));
                 TimeSeries ts;
                 try {
                     ts = daoFuture.get(apiTimeoutMs, TimeUnit.MILLISECONDS);

cwms-data-api/src/main/java/cwms/cda/api/TimeSeriesFilteredController.java

@@ -117,7 +117,9 @@ private TimeSeriesDao getTimeSeriesDao(DSLContext dsl) {
                             + "offset and timezone."),
                     @OpenApiParam(name = Controllers.TRIM, type = Boolean.class, description = "Specifies "
                             + "whether to trim missing values from the beginning and end of the "
-                            + "retrieved values. "
+                            + "retrieved values. When true and values are returned, the contained time-series "
+                            + Controllers.BEGIN + " and " + Controllers.END
+                            + " fields reflect the returned data window. "
                             + "Only supported for:" + Formats.JSONV2 + " and " + Formats.XMLV2 + ". "
                             + "Default is true."),
                     @OpenApiParam(name = INCLUDE_ENTRY_DATE, type = Boolean.class, description = "Specifies "
@@ -149,7 +151,9 @@ private TimeSeriesDao getTimeSeriesDao(DSLContext dsl) {
                     @OpenApiParam(name = PAGE_SIZE,
                             type = Integer.class,
                             description = "How many entries per page returned. "
-                                    + "Default " + DEFAULT_PAGE_SIZE + ".")
+                                    + "Default " + DEFAULT_PAGE_SIZE
+                                    + ". Use 0 to return an empty values array, or -1 to return the entire window "
+                                    + "in one response without a next-page cursor. Values less than -1 are invalid.")
             },
             responses = {
                     @OpenApiResponse(status = STATUS_200,
@@ -202,6 +206,7 @@ public void handle(@NotNull Context ctx) {
             int pageSize = queryParamAsClass(ctx, new String[]{PAGE_SIZE},
                     Integer.class, DEFAULT_PAGE_SIZE, metrics,
                     name(TimeSeriesController.class.getName(), GET_ALL));
+            pageSize = Controllers.validateTimeSeriesPageSize(pageSize);
 
             String acceptHeader = ctx.header(Header.ACCEPT);
             ContentType contentType = Formats.parseHeaderAndQueryParm(acceptHeader, format, TimeSeries.class);