[MODFQMMGR-1043] Make user address fields queryable (#1142)

Author: bvsharp

src/main/java/org/folio/fqm/service/EntityTypeService.java

@@ -44,6 +44,7 @@
 import org.folio.querytool.domain.dto.ValueSourceApi;
 import org.folio.querytool.domain.dto.ValueWithLabel;
 import org.folio.spring.FolioExecutionContext;
+import org.folio.spring.i18n.service.TranslationService;
 import org.springframework.lang.Nullable;
 import org.springframework.stereotype.Service;
 
@@ -86,6 +87,8 @@ public class EntityTypeService {
     "XBC", "XBD", "FIM", "FRF", "XFO", "XFU", "GHC", "DEM", "XAU", "GRD", "GWP", "IEP", "ITL", "LVL", "LTL", "LUF", "MGF", "MTL", "MRO", "MXV",
     "MZM", "XPD", "PHP", "XPT", "PTE", "ROL", "RUR", "CSD", "SLE", "SLL", "XAG", "SKK", "SIT", "ESP", "XDR", "XSU", "SDD", "SRG", "STD", "XTS",
     "TPE", "TRL", "TMM", "USN", "USS", "XXX", "UYI", "VEB", "VEF", "VED", "CHE", "CHW", "YUM", "ZWN", "ZMK", "ZWD", "ZWR");
+  private static final String COUNTRIES_FILEPATH = "country_codes.json";
+  private static final String COUNTRY_TRANSLATION_TEMPLATE = "mod-fqm-manager.countries.%s";
 
   private final EntityTypeRepository entityTypeRepository;
   private final EntityTypeFlatteningService entityTypeFlatteningService;
@@ -99,6 +102,7 @@ public class EntityTypeService {
   private final FolioExecutionContext folioExecutionContext;
   private final ClockService clockService;
   private final SimpleHttpClient simpleHttpClient;
+  private final TranslationService translationService;
 
   /**
    * Returns the list of all entity types.
@@ -211,11 +215,14 @@ public ColumnValues getFieldValues(UUID entityTypeId, String fieldName, @Nullabl
           // entity types using this MUST declare a dependency on view `_mod_search_languages_availability_indicator`
           // to ensure that this source is available
           case "languages" -> getLanguages(searchText, tenantsToQuery);
+          case "countries" -> getCountries();
           case "tenant_id" -> getTenantIds(entityType);
           case "tenant_name" -> getTenantNames(entityType);
           // instructs query builder to provide organization finder plugin, so no values need be returned here
           case "organization", "donor_organization" -> ColumnValues.builder().content(List.of()).build();
-          default -> throw new InvalidEntityTypeDefinitionException("Unhandled source name \"" + field.getSource().getName() + "\" for the FQM value source type in column \"" + fieldName + '"', entityType);
+          default -> throw new InvalidEntityTypeDefinitionException("Unhandled source name \""
+            + field.getSource().getName() + "\" for the FQM value source type in column \""
+            + fieldName + '"', entityType);
         };
       }
     }
@@ -309,8 +316,7 @@ private ColumnValues getFieldValuesFromApi(Field field, String searchText, List<
         log.error("Failed to get column values from {} tenant due to exception:", tenantId, e);
         failureCount++;
         lastException = e;
-      }
-      catch (FeignException.NotFound e) {
+      } catch (FeignException.NotFound e) {
         log.error("Value source API {} not found in tenant {}", field.getValueSourceApi().getPath(), tenantId);
         failureCount++;
         lastException = e;
@@ -433,6 +439,40 @@ private ColumnValues getLanguages(String searchText, List<String> tenantsToQuery
     return new ColumnValues().content(results);
   }
 
+  private ColumnValues getCountries() {
+    ObjectMapper mapper = new ObjectMapper();
+    try (InputStream input = getClass().getClassLoader().getResourceAsStream(COUNTRIES_FILEPATH)) {
+      if (input == null) {
+        log.warn("Country code file {} not found on classpath", COUNTRIES_FILEPATH);
+        return new ColumnValues().content(List.of());
+      }
+
+      // List of ISO 3166-1 alpha-2 codes
+      List<String> codes = mapper.readValue(input, new TypeReference<>() {
+      });
+
+      List<ValueWithLabel> values = codes.stream()
+        .map(code -> {
+          String translationKey = COUNTRY_TRANSLATION_TEMPLATE.formatted(code);
+          String label = translationService.format(translationKey);
+
+          // Use original code as label if translation is missing
+          if (label == null || StringUtils.isBlank(label) || label.equals(translationKey)) {
+            label = code;
+          }
+
+          return new ValueWithLabel().value(code).label(label);
+        })
+        .sorted(comparing(ValueWithLabel::getLabel, String.CASE_INSENSITIVE_ORDER))
+        .toList();
+
+      return new ColumnValues().content(values);
+    } catch (IOException e) {
+      log.warn("Failed to read countries from {}", COUNTRIES_FILEPATH, e);
+      return new ColumnValues().content(List.of());
+    }
+  }
+
   private static ValueWithLabel toValueWithLabel(Map<String, Object> allValues, String fieldName) {
     var valueWithLabel = new ValueWithLabel().label(getFieldValue(allValues, fieldName));
     return allValues.containsKey(ID_FIELD_NAME)
@@ -688,7 +728,7 @@ static List<JoinFieldPair> discoverJoinConditions(EntityType customEntityType, E
     }
     return joinConditions.stream()
       .sorted(comparing((JoinFieldPair pair) -> pair.getSourceField().getLabel(), String.CASE_INSENSITIVE_ORDER)
-                .thenComparing(pair -> pair.getTargetField().getLabel(), String.CASE_INSENSITIVE_ORDER))
+        .thenComparing(pair -> pair.getTargetField().getLabel(), String.CASE_INSENSITIVE_ORDER))
       .toList();
   }
 

src/main/java/org/folio/fqm/service/ResultSetService.java

@@ -1,11 +1,17 @@
 package org.folio.fqm.service;
 
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
 import lombok.extern.log4j.Log4j2;
+import org.apache.commons.collections4.CollectionUtils;
+import org.apache.commons.lang3.StringUtils;
 import org.folio.fqm.client.SettingsClient;
 import org.folio.fqm.repository.ResultSetRepository;
 import org.folio.fqm.utils.EntityTypeUtils;
 import org.folio.querytool.domain.dto.EntityType;
 import org.folio.spring.FolioExecutionContext;
+import org.folio.spring.i18n.service.TranslationService;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Service;
 
@@ -21,6 +27,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.UUID;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.function.Function;
@@ -36,10 +43,15 @@ public class ResultSetService {
     .optionalStart().appendOffsetId() // optional Z/timezone at end
     .toFormatter().withZone(ZoneOffset.UTC); // force interpretation as UTC
   private static final String DATE_TIME_REGEX = "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}([+-]\\d{2}:\\d{2}(:\\d{2})?|Z|)$";
+  private static final String COUNTRY_TRANSLATION_TEMPLATE = "mod-fqm-manager.countries.%s";
+  private static final String NESTED_FIELD_MARKER = "[*]->";
+  private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
   private final ResultSetRepository resultSetRepository;
   private final EntityTypeFlatteningService entityTypeFlatteningService;
   private final SettingsClient settingsClient;
   private final FolioExecutionContext executionContext;
+  private final TranslationService translationService;
 
   public List<Map<String, Object>> getResultSet(UUID entityTypeId,
                                                 List<String> fields,
@@ -64,6 +76,7 @@ private List<Map<String, Object>> getSortedContents(UUID entityTypeId, List<List
 
     List<String> dateFields = localize ? EntityTypeUtils.getDateTimeFields(entityType) : List.of();
     ZoneId tenantTimezone = localize ? settingsClient.getTenantTimezone() : null;
+    List<String> countryFields = EntityTypeUtils.getCountryLocalizationFieldPaths(entityType);
 
     return contentIds
       .stream()
@@ -79,6 +92,7 @@ private List<Map<String, Object>> getSortedContents(UUID entityTypeId, List<List
         }
 
         Map<String, Object> copiedContents = new HashMap<>(contents);
+        localizeCountries(copiedContents, countryFields);
         if (localize) {
           localizeContent(copiedContents, dateFields, tenantTimezone);
         }
@@ -100,6 +114,99 @@ private void localizeContent(Map<String, Object> contents, List<String> dateFiel
     }
   }
 
+  private void localizeCountries(Map<String, Object> contents, List<String> countryFieldPaths) {
+    if (CollectionUtils.isEmpty(countryFieldPaths)) {
+      return;
+    }
+    for (String fieldPath : countryFieldPaths) {
+      localizeCountryField(contents, fieldPath);
+    }
+  }
+
+  private void localizeCountryField(Map<String, Object> contents, String fieldPath) {
+    if (StringUtils.isEmpty(fieldPath)) {
+      return;
+    }
+
+    int markerIndex = fieldPath.indexOf(NESTED_FIELD_MARKER);
+    if (markerIndex < 0) {
+      localizeTopLevelCountryField(contents, fieldPath);
+      return;
+    }
+
+    String rootField = fieldPath.substring(0, markerIndex);
+    String nestedField = fieldPath.substring(markerIndex + NESTED_FIELD_MARKER.length());
+    localizeNestedCountryField(contents, rootField, nestedField);
+  }
+
+  private void localizeTopLevelCountryField(Map<String, Object> contents, String fieldName) {
+    Object value = contents.get(fieldName);
+    if (!(value instanceof String code) || code.isBlank()) {
+      return;
+    }
+    localizeCountryCode(code).ifPresent(translated -> contents.put(fieldName, translated));
+  }
+
+  private void localizeNestedCountryField(Map<String, Object> contents, String rootField, String nestedField) {
+    if (rootField.isBlank() || nestedField.isBlank()) {
+      return;
+    }
+
+    Object root = contents.get(rootField);
+    if (!(root instanceof String rootJson) || rootJson.isBlank()) {
+      return;
+    }
+
+    try {
+      JsonNode node = OBJECT_MAPPER.readTree(rootJson);
+      if (!node.isArray()) {
+        return;
+      }
+
+      boolean changed = false;
+      for (JsonNode elementNode : node) {
+        changed |= localizeCountryCodeIfPresent(elementNode, nestedField);
+      }
+      if (changed) {
+        contents.put(rootField, OBJECT_MAPPER.writeValueAsString(node));
+      }
+    } catch (Exception e) {
+      log.debug("Unable to localize country field '{}[*]->{}' (unexpected JSON): {}", rootField, nestedField, e.getMessage());
+    }
+  }
+
+  private boolean localizeCountryCodeIfPresent(JsonNode elementNode, String fieldName) {
+    if (!elementNode.isObject()) {
+      return false;
+    }
+
+    ObjectNode objectNode = (ObjectNode) elementNode;
+    JsonNode valueNode = objectNode.get(fieldName);
+    if (valueNode == null || !valueNode.isTextual()) {
+      return false;
+    }
+
+    String code = valueNode.asText();
+    Optional<String> localized = localizeCountryCode(code);
+    if (localized.isEmpty()) {
+      return false;
+    }
+
+    objectNode.put(fieldName, localized.get());
+    return true;
+  }
+
+  private Optional<String> localizeCountryCode(String code) {
+    String translationKey = COUNTRY_TRANSLATION_TEMPLATE.formatted(code);
+    String localized = translationService.format(translationKey);
+
+    // If translation is missing, don't modify the original value
+    if (localized == null || localized.isBlank() || localized.equals(translationKey)) {
+      return Optional.empty();
+    }
+    return Optional.of(localized);
+  }
+
   private static String adjustDate(Instant instant, ZoneId tenantTimezone) {
     return instant.atZone(tenantTimezone).toLocalDate().toString();
   }

src/main/java/org/folio/fqm/utils/EntityTypeUtils.java

@@ -5,6 +5,7 @@
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
+
 import java.io.UncheckedIOException;
 import java.util.ArrayList;
 import java.util.Comparator;
@@ -14,9 +15,11 @@
 import java.util.SortedMap;
 import java.util.TreeMap;
 import java.util.function.BiConsumer;
+
 import lombok.experimental.UtilityClass;
 import lombok.extern.log4j.Log4j2;
 import org.apache.commons.codec.digest.DigestUtils;
+import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.lang3.tuple.Pair;
 import org.folio.fqm.domain.Query;
 import org.folio.fqm.exception.InvalidEntityTypeDefinitionException;
@@ -33,6 +36,7 @@
 import org.folio.querytool.domain.dto.Join;
 import org.folio.querytool.domain.dto.NestedObjectProperty;
 import org.folio.querytool.domain.dto.ObjectType;
+import org.folio.querytool.domain.dto.SourceColumn;
 import org.jooq.SortField;
 import org.jooq.impl.DSL;
 
@@ -45,6 +49,8 @@ public class EntityTypeUtils {
 
   public static final org.jooq.Field<String[]> RESULT_ID_FIELD = field("result_id", String[].class);
 
+  private static final String COUNTRIES_SOURCE = "countries";
+
   /**
    * Returns a list of strings corresponding to the names of the id columns of an entity type.
    *
@@ -149,7 +155,7 @@ public static Optional<Join> findJoinBetween(EntityTypeColumn source, EntityType
       .stream()
       .filter(j ->
         j.getTargetId().equals(target.getOriginalEntityTypeId()) &&
-        j.getTargetField().equals(splitFieldIntoAliasAndField(target.getName()).getRight())
+          j.getTargetField().equals(splitFieldIntoAliasAndField(target.getName()).getRight())
       )
       .findFirst();
   }
@@ -189,8 +195,10 @@ private static List<EntityTypeColumn> getIdColumns(EntityType entityType) {
    * No guarantees are made about the order in which fields are visited, however, this will include
    * every field, no matter how deeply nested.
    *
-   * @example
-   * An entity type with columns `obj` and `arrobj`, where `obj` is an object with two properties
+   * @param entityType the entity to traverse
+   * @param consumer   the consumer to run on each field. The first parameter is the
+   *                   {@link Field field} itself and the second parameter is the path to that field
+   * @example An entity type with columns `obj` and `arrobj`, where `obj` is an object with two properties
    * and `arrobj` is an array of objects with three properties, the following calls will be made:
    * <pre>
    * - consumer.accept(obj, "") // base column
@@ -201,10 +209,6 @@ private static List<EntityTypeColumn> getIdColumns(EntityType entityType) {
    * - consumer.accept(arrChild2, "arrobj[*]->") // second property
    * - consumer.accept(arrChild3, "arrobj[*]->") // third property
    * </pre>
-   *
-   * @param entityType the entity to traverse
-   * @param consumer the consumer to run on each field. The first parameter is the
-   *                 {@link Field field} itself and the second parameter is the path to that field
    */
   public static void runOnEveryField(EntityType entityType, BiConsumer<Field, String> consumer) {
     if (entityType.getColumns() == null) {
@@ -245,13 +249,13 @@ private static void runOnEveryField(String parentPath, Field field, BiConsumer<F
    * <strong>NOT</strong> consider the entire entity type definition, only some properties used in
    * querying. Notable exclusions include owner information, any localized fields, and the ordering
    * of sources and columns.
-   *
+   * <p>
    * This DOES take into effect values which affect queries and results, including but not limited
    * to:
    * - Sources (alias, type, target)
    * - Columns (name, data type, ID state, getters)
    * - Cross-tenant status
-   *
+   * <p>
    * No assumptions should be made about the specific algorithm used to compute the hash, the hash
    * length, and the result should never be used to check if two entity types are equivalent. It
    * is only intended to detect changes which may affect query results. Additionally, no guarantees
@@ -344,4 +348,25 @@ public static void verifyEntityTypeHasNotChangedDuringQueryLifetime(Query query,
       );
     }
   }
+
+  public static List<String> getCountryLocalizationFieldPaths(EntityType entityType) {
+    List<String> paths = new ArrayList<>();
+    EntityTypeUtils.runOnEveryField(entityType, (field, parentPath) -> {
+      if (field.getSource() == null
+        || field.getSource().getType() != SourceColumn.TypeEnum.FQM
+        || !COUNTRIES_SOURCE.equals(field.getSource().getName())) {
+        return;
+      }
+
+      // Use the underlying JSON property name for nested fields
+      String leaf = (field instanceof NestedObjectProperty prop
+        && !StringUtils.isEmpty(prop.getProperty()))
+        ? prop.getProperty()
+        : field.getName();
+
+      paths.add(parentPath + leaf);
+    });
+
+    return paths;
+  }
 }