REGI-470: Added lightweight catalog endpoint for location + location kind (#1230)

Adds support for lightweight data retrieval on locations getAll
endpoint.

Returns location ID, office ID, and location kind ID.

To be used by REGI in
AtLocationManager::retrieveAllLocationTemplatesWithKinds method.

Author: zack-rma

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

@@ -138,6 +138,7 @@
 import cwms.cda.api.project.UpdateLockRevokerRights;
 import cwms.cda.api.rating.ReverseRateTimeSeriesController;
 import cwms.cda.api.rating.ReverseRateValuesController;
+import cwms.cda.api.LocationKindController;
 import cwms.cda.api.watersupply.AccountingCatalogController;
 import cwms.cda.api.watersupply.AccountingCreateController;
 import cwms.cda.api.timeseriesprofile.TimeSeriesProfileCatalogController;
@@ -532,6 +533,7 @@ protected void configureRoutes() {
                 new LocationCategoryController(metrics), requiredRoles, 5, TimeUnit.MINUTES);
         cdaCrudCache("/location/group/{group-id}",
                 new LocationGroupController(metrics), requiredRoles, 5, TimeUnit.MINUTES);
+        get("/locations/with-kinds/", new LocationKindController(metrics));
         cdaCrudCache("/locations/{location-id}",
                 new LocationController(metrics), requiredRoles, 5, TimeUnit.MINUTES);
         cdaCrudCache("/states/{state}",
@@ -703,7 +705,6 @@ protected void configureRoutes() {
         addProjectLocksHandlers("/project-locks/{name}", requiredRoles);
         addProjectLockRightsHandlers("/project-lock-rights/{project-id}", requiredRoles);
 
-
         addUserManagementHandlers();
     }
 

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

@@ -156,7 +156,6 @@ public final class Controllers {
     public static final String AGENCY = "agency";
     public static final String QUALITY = "quality";
     public static final String NAMES = "names";
-    public static final String EXCLUDE_KINDS = "exclude-kinds";
     public static final String FILTER_BASE_LOCATIONS = "filter-base-locations";
 
     public static final String GROUP_ID = "group-id";

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

@@ -0,0 +1,120 @@
+/*
+ *
+ * MIT License
+ *
+ * Copyright (c) 2025 Hydrologic Engineering Center
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package cwms.cda.api;
+
+import static com.codahale.metrics.MetricRegistry.name;
+import static cwms.cda.api.Controllers.LOCATION_KIND_LIKE;
+import static cwms.cda.api.Controllers.NAMES;
+import static cwms.cda.api.Controllers.OFFICE;
+import static cwms.cda.api.Controllers.RESULTS;
+import static cwms.cda.api.Controllers.SIZE;
+import static cwms.cda.api.Controllers.STATUS_200;
+import static cwms.cda.api.LocationController.getLocationsDao;
+import static cwms.cda.data.dao.JooqDao.getDslContext;
+
+import com.codahale.metrics.Histogram;
+import com.codahale.metrics.MetricRegistry;
+import cwms.cda.data.dao.LocationsDao;
+import cwms.cda.data.dto.CwmsIdLocationKind;
+import cwms.cda.data.dto.Location;
+import cwms.cda.formatters.ContentType;
+import cwms.cda.formatters.Formats;
+import io.javalin.core.util.Header;
+import io.javalin.http.Context;
+import io.javalin.http.Handler;
+import io.javalin.plugin.openapi.annotations.HttpMethod;
+import io.javalin.plugin.openapi.annotations.OpenApi;
+import io.javalin.plugin.openapi.annotations.OpenApiContent;
+import io.javalin.plugin.openapi.annotations.OpenApiParam;
+import io.javalin.plugin.openapi.annotations.OpenApiResponse;
+import java.util.List;
+import javax.servlet.http.HttpServletResponse;
+import org.jetbrains.annotations.NotNull;
+import org.jooq.DSLContext;
+
+public class LocationKindController implements Handler {
+    public static final String TAG = "REGI";
+
+    private final Histogram requestResultSize;
+
+    public LocationKindController(MetricRegistry metrics) {
+        MetricRegistry controllerMetrics = metrics;
+        String className = this.getClass().getName();
+        requestResultSize = controllerMetrics.histogram((name(className, RESULTS, SIZE)));
+    }
+
+    @OpenApi(
+        queryParams = {
+            @OpenApiParam(name = NAMES, description = "Specifies the name(s) of the "
+                + "location(s) whose data is to be included in the response. This parameter is a "
+                + "Posix <a href=\"regexp.html\">regular expression</a> matching against the id"),
+            @OpenApiParam(name = LOCATION_KIND_LIKE, description = "Specifies the location kind(s) "
+                + "whose data is to be included in the response. This parameter is a "
+                + "Posix <a href=\"regexp.html\">regular expression</a> matching against the location kind. "
+                + "If this field is not specified, all location kinds shall be returned."),
+            @OpenApiParam(name = OFFICE, description = "Specifies the owning office of "
+                + "the location level(s) whose data is to be included in the response"
+                + ". If this field is not specified, matching location level "
+                + "information from all offices shall be returned."),
+        },
+        responses = {
+            @OpenApiResponse(status = STATUS_200,
+                content = {
+                    @OpenApiContent(isArray = true, type = Formats.JSONV2, from = Location.class),
+                })
+        },
+        description = "Returns CWMS Location Data.  The Catalog end-point is also capable of "
+            + "retrieving lists of locations and can filter on additional fields.",
+        method = HttpMethod.GET,
+        path = "/locations/with-kind",
+        tags = {TAG}
+    )
+    @Override
+    public void handle(@NotNull Context ctx) {
+        DSLContext dsl = getDslContext(ctx);
+
+        LocationsDao locationsDao = getLocationsDao(dsl);
+
+        String names = ctx.queryParam(NAMES);
+        String kindRegexMask = ctx.queryParam(LOCATION_KIND_LIKE);
+        String office = ctx.queryParam(OFFICE);
+
+        String formatParm = ctx.queryParamAsClass(Formats.JSONV2, String.class).getOrDefault("");
+        String formatHeader = ctx.header(Header.ACCEPT);
+        ContentType contentType = Formats.parseHeaderAndQueryParm(formatHeader, formatParm, Location.class);
+
+        String results;
+
+        List<CwmsIdLocationKind> locationKinds = locationsDao.getLocationKinds(names, kindRegexMask, office);
+        results = Formats.format(contentType, locationKinds, CwmsIdLocationKind.class);
+        ctx.result(results);
+        requestResultSize.update(results.length());
+
+        ctx.contentType(contentType.toString());
+        ctx.status(HttpServletResponse.SC_OK);
+    }
+}

cwms-data-api/src/main/java/cwms/cda/data/dao/LocationsDao.java

@@ -25,6 +25,7 @@
 package cwms.cda.data.dao;
 
 import cwms.cda.data.dto.Catalog;
+import cwms.cda.data.dto.CwmsIdLocationKind;
 import cwms.cda.data.dto.Location;
 import java.io.IOException;
 import java.util.List;
@@ -35,6 +36,8 @@ public interface LocationsDao {
 
     List<Location> getLocations(String names, String units, String datum, String officeId);
 
+    List<CwmsIdLocationKind> getLocationKinds(String idRegexMask, String kindRegexMask, String officeId);
+
     Location getLocation(String locationName, String unitSystem, String officeId) throws IOException;
 
     void deleteLocation(String locationName, String officeId);

cwms-data-api/src/main/java/cwms/cda/data/dao/LocationsDaoImpl.java

@@ -47,10 +47,13 @@
 import cwms.cda.api.errors.NotFoundException;
 import cwms.cda.data.dao.location.kind.LocationUtil;
 import cwms.cda.data.dto.Catalog;
+import cwms.cda.data.dto.CwmsId;
+import cwms.cda.data.dto.CwmsIdLocationKind;
 import cwms.cda.data.dto.Location;
 import cwms.cda.data.dto.catalog.CatalogEntry;
 import cwms.cda.data.dto.catalog.LocationAlias;
 import cwms.cda.data.dto.catalog.LocationCatalogEntry;
+import cwms.cda.helpers.ZoneIdHelper;
 import java.io.IOException;
 import java.math.BigDecimal;
 import java.time.ZoneId;
@@ -64,7 +67,6 @@
 import java.util.Set;
 import java.util.logging.Level;
 import java.util.logging.Logger;
-import cwms.cda.helpers.ZoneIdHelper;
 import org.geojson.Feature;
 import org.geojson.FeatureCollection;
 import org.geojson.Point;
@@ -131,6 +133,24 @@ public List<Location> getLocations(String nameRegex, String unitSystem, String d
                     .fetch(this::buildLocation);
     }
 
+    @Override
+    public List<CwmsIdLocationKind> getLocationKinds(String idRegexMask, String kindRegexMask, String officeId) {
+        Condition whereCondition = JooqDao.caseInsensitiveLikeRegexNullTrue(AV_LOC.LOCATION_ID, idRegexMask);
+
+        whereCondition = whereCondition
+            .and(JooqDao.caseInsensitiveLikeRegexNullTrue(AV_LOC.LOCATION_KIND_ID, kindRegexMask));
+
+        if (officeId != null) {
+            whereCondition = whereCondition.and(AV_LOC.DB_OFFICE_ID.equalIgnoreCase(officeId));
+        }
+
+        return dsl.selectDistinct(AV_LOC.LOCATION_ID, AV_LOC.DB_OFFICE_ID, AV_LOC.LOCATION_KIND_ID)
+                    .from(AV_LOC)
+                    .where(whereCondition)
+                    .fetchSize(DEFAULT_SMALL_FETCH_SIZE)
+                    .fetch(this::buildLocationKind);
+    }
+
     @Override
     public Location getLocation(String locationName, String unitSystem, String officeId) {
         Record loc = dsl.select(AV_LOC.asterisk())
@@ -146,6 +166,13 @@ public Location getLocation(String locationName, String unitSystem, String offic
         return buildLocation(loc);
     }
 
+    private CwmsIdLocationKind buildLocationKind(Record loc) {
+        CwmsIdLocationKind.Builder builder = new CwmsIdLocationKind.Builder();
+        builder.withLocationKindId(loc.get(AV_LOC.LOCATION_KIND_ID));
+        builder.withLocationId(CwmsId.buildCwmsId(loc.get(AV_LOC.DB_OFFICE_ID), loc.get(AV_LOC.LOCATION_ID)));
+        return builder.build();
+    }
+
     private Location buildLocation(Record loc) {
         String timeZoneName = loc.get(AV_LOC.TIME_ZONE_NAME); // may be null...
         ZoneId zone = null;

cwms-data-api/src/main/java/cwms/cda/data/dto/CwmsIdLocationKind.java

@@ -0,0 +1,77 @@
+/*
+ *
+ * MIT License
+ *
+ * Copyright (c) 2025 Hydrologic Engineering Center
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package cwms.cda.data.dto;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.databind.PropertyNamingStrategies;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonNaming;
+import cwms.cda.formatters.Formats;
+import cwms.cda.formatters.annotations.FormattableWith;
+import cwms.cda.formatters.json.JsonV2;
+
+@FormattableWith(contentType = Formats.JSONV2, formatter = JsonV2.class,
+    aliases = {Formats.JSON, Formats.DEFAULT})
+@JsonInclude(JsonInclude.Include.NON_NULL)
+@JsonDeserialize(builder = CwmsIdLocationKind.Builder.class)
+@JsonNaming(PropertyNamingStrategies.KebabCaseStrategy.class)
+public final class CwmsIdLocationKind extends CwmsDTOBase {
+    private final CwmsId location;
+    private final String locationKindId;
+
+    public CwmsIdLocationKind(Builder builder) {
+        this.location = builder.id;
+        this.locationKindId = builder.locationKindId;
+    }
+
+    public CwmsId getLocationId() {
+        return location;
+    }
+
+    public String getLocationKindId() {
+        return locationKindId;
+    }
+
+    public static final class Builder {
+        private CwmsId id;
+        private String locationKindId;
+
+        public Builder withLocationId(CwmsId id) {
+            this.id = id;
+            return this;
+        }
+
+        public Builder withLocationKindId(String locationKindId) {
+            this.locationKindId = locationKindId;
+            return this;
+        }
+
+        public CwmsIdLocationKind build() {
+            return new CwmsIdLocationKind(this);
+        }
+    }
+}

cwms-data-api/src/main/java/cwms/cda/formatters/Formats.java

@@ -103,8 +103,7 @@ public class Formats {
     private Formats() {
     }
 
-    public static String getLegacyTypeFromContentType(ContentType contentType)
-    {
+    public static String getLegacyTypeFromContentType(ContentType contentType) {
         return typeMap.entrySet()
                       .stream()
                       .filter(e -> e.getValue().equals(contentType.getType()))
@@ -287,7 +286,7 @@ public static ContentType parseHeaderAndQueryParm(String header, String queryPar
     /**
      * For endpoints that still allow either for transition, favors the query parameter as that's the likely user
      * expectation since machine systems wouldn't said both.
-     * @param header content type from a header
+     * @param headerParam content type from a header
      * @param queryParam content type from a query parameter
      * @param klass DTO to find a matching formatter for.
      * @return ContentType appropriate to the given selection.