Merge pull request #11 from tomaytotomato/3-native-localised-name-fix

3 Fix localised names lookup (native name)

.github/workflows/build.yml

@@ -2,11 +2,16 @@ name: Build
 
 on:
   push:
+    branches:
+      - master
     paths:
       - 'library/src/**'
       - 'pom.xml'
       - '.github/**'
+
   pull_request:
+    branches:
+      - master
     paths:
       - 'library/src/**'
       - 'pom.xml'

README.md

@@ -47,25 +47,22 @@ public class Main {
 
 ```
 
-## What can location4j do?
-
-Here is an overview of the core functionality that location4j offers
-
-| Feature                      | Supported | Object   |
-|------------------------------|-----------|----------|
-| Search (free text)           | ✅         | Location |
-| Find All Countries           | ✅         | Country  |
-| Find Country by Id           | ✅         | Country  |
-| Find Country by ISO2 code    | ✅         | Country  |
-| Find Country by ISO3 code    | ✅         | Country  |
-| Find Country by name         | ✅         | Country  |
-| Find Country by Native name  | ✅         | Country  |
-| Find Countries by State name | ✅         | Country  |
-| Find States by State name    | ✅         | State    |
-| Find State by State Id       | ✅         | State    |
-| Find States by State code    | ✅         | State    |
-| Find City by City Id         | ✅         | City     |
-| Find Cities by City name     | ✅         | City     |
+| Feature                        | Supported | Object   | Example                                                                 |
+|--------------------------------|-----------|----------|-------------------------------------------------------------------------|
+| Search (free text)             | ✅         | Location | `search("Canada, Alberta")` -> `[Location("Alberta", "Canada")]`       |
+| Find All Countries             | ✅         | Country  | `findAllCountries()` -> `[Country("Belgium"), Country("Canada"), ...]` |
+| Find Country by Id             | ✅         | Country  | `findCountryById(1)` -> `Optional[Country("Afghanistan")]`             |
+| Find Country by ISO2 code      | ✅         | Country  | `findCountryByISO2Code("CA")` -> `Optional[Country("Canada")]`         |
+| Find Country by ISO3 code      | ✅         | Country  | `findCountryByISO3Code("CAN")` -> `Optional[Country("Canada")]`        |
+| Find Country by Name           | ✅         | Country  | `findCountryByName("Canada")` -> `Optional[Country("Canada")]`         |
+| Find Country by Localised name | ✅         | Country  | `findCountryByLocalisedName("Belgique")` -> `Optional[Country("Belgium")]` |
+| Find Countries by State name   | ✅         | Country  | `findAllCountriesByStateName("Texas")` -> `[Country("USA")]`           |
+| Find States by State name      | ✅         | State    | `findAllStatesByStateName("Texas")` -> `[State("Texas", "USA")]`       |
+| Find State by State Id         | ✅         | State    | `findStateById(5)` -> `Optional[State("California", "USA")]`           |
+| Find States by State code      | ✅         | State    | `findAllStatesByStateCode("CA")` -> `[State("California", "USA")]`     |
+| Find City by City Id           | ✅         | City     | `findCityById(10)` -> `Optional[City("Los Angeles", "California")]`    |
+| Find Cities by City name       | ✅         | City     | `findAllCitiesByCityName("San Francisco")` -> `[City("San Francisco", "California")]` |
+
 
 🟢 location4j can parse free text strings with or without punctuation or capitalisation e.g.
 > San Francisco, CA, USA

library/src/main/java/com/tomaytotomato/LocationService.java

@@ -16,22 +16,19 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
-import java.util.logging.Logger;
 
 /**
  * This class provides simple lookups for Country, State and City information.
  */
 public class LocationService implements FindCountry, FindState, FindCity {
 
-  private final Logger logger = Logger.getLogger(this.getClass().getPackage().getName() + this.getClass().getName());
-
   private final List<Country> countries;
   /**
    * One-to-one mappings (1:1)
    */
   private final Map<String, Country> countryNameToCountryMap = new HashMap<>();
   private final Map<Integer, Country> countryIdToCountryMap = new HashMap<>();
-  private final Map<String, Country> countryNativeNameToCountry = new HashMap<>();
+  private final Map<String, Country> localisedNameToCountryMap = new HashMap<>();
   private final Map<String, Country> iso2CodeToCountryMap = new HashMap<>();
   private final Map<String, Country> iso3CodeToCountryMap = new HashMap<>();
   private final Map<Integer, State> stateIdToStateMap = new HashMap<>();
@@ -73,11 +70,10 @@ private void buildDataStructures() {
     countries.forEach(country -> {
       countryIdToCountryMap.put(country.getId(), country);
       countryNameToCountryMap.put(keyMaker(country.getName()), country);
-      if (Objects.isNull(country.getNativeName()) || country.getNativeName().isEmpty()) {
-        logger.warning("Country has null native name, skipping mapping: " + country.getName());
-      } else {
-        countryNativeNameToCountry.put(keyMaker(country.getNativeName()), country);
-      }
+
+      localisedNameToCountryMap.put(keyMaker(country.getNativeName()), country);
+      country.getTranslations().values().stream().map(this::keyMaker)
+          .forEach(translatedName -> localisedNameToCountryMap.put(translatedName, country));
       iso2CodeToCountryMap.put(keyMaker(country.getIso2()), country);
       iso3CodeToCountryMap.put(keyMaker(country.getIso3()), country);
 
@@ -121,12 +117,12 @@ public Optional<Country> findCountryByName(String countryName) {
   }
 
   @Override
-  public Optional<Country> findCountryByNativeName(String nativeName) {
-    if (Objects.isNull(nativeName) || nativeName.isEmpty()) {
-      throw new IllegalArgumentException("Country Native Name cannot be null or empty");
+  public Optional<Country> findCountryByLocalisedName(String localisedName) {
+    if (Objects.isNull(localisedName) || localisedName.isEmpty()) {
+      throw new IllegalArgumentException("Country Localised Name cannot be null or empty");
     }
-    nativeName = textNormaliser.normalise(nativeName);
-    return Optional.ofNullable(countryNativeNameToCountry.get(nativeName));
+    localisedName = textNormaliser.normalise(localisedName);
+    return Optional.ofNullable(localisedNameToCountryMap.get(localisedName));
   }
 
   @Override

library/src/main/java/com/tomaytotomato/aliases/LocationAliases.java

@@ -3,7 +3,7 @@
 import java.util.Map;
 
 /**
- * Allows adding custom aliases for Country, State and City
+ * Allows adding custom aliases for countries, states and cities
  */
 public interface LocationAliases {
 

library/src/main/java/com/tomaytotomato/loader/CountriesDataLoader.java

@@ -3,8 +3,15 @@
 import com.tomaytotomato.model.Country;
 import java.util.List;
 
+/**
+ * Loads countries from the location4j.jar and provides it to any classes that need it.
+ */
 public interface CountriesDataLoader {
 
+  /**
+   * Returns a list of {@link Country} after loading them from disk
+   * @return list of countries
+   */
   List<Country> getCountries();
 
 }

library/src/main/java/com/tomaytotomato/loader/DefaultCountriesDataLoaderImpl.java

@@ -11,7 +11,6 @@
 
 /**
  * The default loader for retrieving Countries from the DEFAULT_FILE located in the location4j.jar
- *
  */
 public class DefaultCountriesDataLoaderImpl implements CountriesDataLoader {
 

library/src/main/java/com/tomaytotomato/mapper/LocationMapper.java

@@ -5,6 +5,9 @@
 import com.tomaytotomato.model.Location;
 import com.tomaytotomato.model.State;
 
+/**
+ * Converts {@link Country}, {@link State} and {@link City} objects into {@link Location} objects
+ */
 public interface LocationMapper {
 
   Location toLocation(Country country);

library/src/main/java/com/tomaytotomato/model/City.java

@@ -1,10 +1,16 @@
 package com.tomaytotomato.model;
 
-
 import java.io.Serializable;
 import java.math.BigDecimal;
 import java.util.Objects;
 
+/**
+ * Represents a city with various attributes such as name, state, and country.
+ * <p>
+ * This class provides methods to access city details including geographic coordinates,
+ * country and state associations, and other identifiers.
+ * </p>
+ */
 public class City implements Serializable {
 
   private static final long serialVersionUID = 1L;
@@ -21,6 +27,9 @@ public class City implements Serializable {
   private BigDecimal latitude;
   private BigDecimal longitude;
 
+  /**
+   * Default constructor for City.
+   */
   City() {}
 
   public Integer getId() {

library/src/main/java/com/tomaytotomato/model/Country.java

@@ -6,6 +6,12 @@
 import java.util.Map;
 import java.util.Objects;
 
+/**
+ * Represents a country with various attributes such as name, codes, and geographic information.
+ * <p>
+ * This class provides methods to access country details, including currency, region, and states.
+ * </p>
+ */
 public class Country implements Serializable {
 
   private static final long serialVersionUID = 1L;

library/src/main/java/com/tomaytotomato/model/Location.java

@@ -2,6 +2,13 @@
 
 import java.math.BigDecimal;
 
+/**
+ * Represents a location result class, used for returning information on a location search.
+ * <p>
+ * This class provides methods to access details of a location, including its geographic
+ * coordinates, country, state, and city information.
+ * </p>
+ */
 public class Location {
 
   private String countryName;
@@ -17,9 +24,28 @@ public class Location {
   private BigDecimal latitude;
   private BigDecimal longitude;
 
+  /**
+   * Default constructor for Location.
+   */
   public Location() {
   }
 
+  /**
+   * Constructs a new Location with the specified attributes.
+   *
+   * @param countryName the name of the country
+   * @param countryId the unique identifier of the country
+   * @param countryIso2Code the ISO 3166-1 alpha-2 code of the country
+   * @param countryIso3Code the ISO 3166-1 alpha-3 code of the country
+   * @param state the name of the state
+   * @param stateId the unique identifier of the state
+   * @param stateCode the code of the state
+   * @param stateName the full name of the state
+   * @param city the name of the city
+   * @param cityId the unique identifier of the city
+   * @param latitude the latitude of the location
+   * @param longitude the longitude of the location
+   */
   public Location(String countryName, Integer countryId, String countryIso2Code,
       String countryIso3Code, String state, Integer stateId, String stateCode, String stateName, String city,
       Integer cityId, BigDecimal latitude, BigDecimal longitude) {
@@ -218,6 +244,5 @@ public Location build() {
       return new Location(countryName, countryId, countryIso2Code, countryIso3Code, state, stateId,
           stateCode, stateName, city, cityId, latitude, longitude);
     }
-
   }
 }

library/src/main/java/com/tomaytotomato/model/State.java

@@ -5,6 +5,13 @@
 import java.util.List;
 import java.util.Objects;
 
+/**
+ * Represents a state data class.
+ * <p>
+ * This class provides methods to access state details, including its geographic coordinates,
+ * country association, and the list of cities within the state.
+ * </p>
+ */
 public class State implements Serializable {
 
   private static final long serialVersionUID = 1L;
@@ -21,8 +28,26 @@ public class State implements Serializable {
   private BigDecimal latitude;
   private BigDecimal longitude;
 
+  /**
+   * Default constructor for State.
+   */
   State() {}
 
+  /**
+   * Constructs a new State with the specified attributes.
+   *
+   * @param id the unique identifier of the state
+   * @param countryId the unique identifier of the country associated with the state
+   * @param countryName the name of the country associated with the state
+   * @param countryIso2Code the ISO 3166-1 alpha-2 code of the country
+   * @param countryIso3Code the ISO 3166-1 alpha-3 code of the country
+   * @param name the name of the state
+   * @param type the type or classification of the state (e.g., province, region)
+   * @param stateCode the code of the state
+   * @param cities the list of cities within the state
+   * @param latitude the latitude of the state's geographic center
+   * @param longitude the longitude of the state's geographic center
+   */
   public State(Integer id, Integer countryId, String countryName, String countryIso2Code,
       String countryIso3Code, String name, String type, String stateCode, List<City> cities,
       BigDecimal latitude, BigDecimal longitude) {

library/src/main/java/com/tomaytotomato/model/TimeZone.java

@@ -3,6 +3,13 @@
 import java.io.Serializable;
 import java.util.Objects;
 
+/**
+ * Represents a timezone data class.
+ * <p>
+ * This class provides methods to access timezone details, including the zone name,
+ * abbreviation, and GMT offset information.
+ * </p>
+ */
 public class TimeZone implements Serializable {
 
   private static final long serialVersionUID = 1L;
@@ -13,9 +20,21 @@ public class TimeZone implements Serializable {
   private Integer gmtOffset;
   private String gmtOffsetName;
 
+  /**
+   * Default constructor for TimeZone.
+   */
   TimeZone() {
   }
 
+  /**
+   * Constructs a new TimeZone with the specified attributes.
+   *
+   * @param zoneName the name of the timezone
+   * @param abbreviation the abbreviation of the timezone
+   * @param tzName the full name of the timezone
+   * @param gmtOffset the GMT offset in seconds
+   * @param gmtOffsetName the human-readable name for the GMT offset
+   */
   public TimeZone(String zoneName, String abbreviation, String tzName, Integer gmtOffset,
       String gmtOffsetName) {
     this.zoneName = zoneName;

library/src/main/java/com/tomaytotomato/text/normaliser/DefaultTextNormaliser.java

@@ -2,6 +2,9 @@
 
 import java.util.Objects;
 
+/**
+ * Default text normaliser, lowercases text, removes unnecessary punctuation characters and spaces
+ */
 public class DefaultTextNormaliser implements TextNormaliser {
 
   @Override

library/src/main/java/com/tomaytotomato/text/normaliser/TextNormaliser.java

@@ -1,5 +1,8 @@
 package com.tomaytotomato.text.normaliser;
 
+/**
+ * Normalises text input before being used in lookups or searches
+ */
 public interface TextNormaliser {
 
   String normalise(String text);