diff --git a/library/src/main/java/com/tomaytotomato/LocationService.java b/library/src/main/java/com/tomaytotomato/LocationService.java index e0748d1..57b39d3 100644 --- a/library/src/main/java/com/tomaytotomato/LocationService.java +++ b/library/src/main/java/com/tomaytotomato/LocationService.java @@ -121,12 +121,12 @@ public Optional findCountryByName(String countryName) { } @Override - public Optional findCountryByNativeName(String nativeName) { - if (Objects.isNull(nativeName) || nativeName.isEmpty()) { + public Optional findCountryByLocalisedName(String localisedName) { + if (Objects.isNull(localisedName) || localisedName.isEmpty()) { throw new IllegalArgumentException("Country Native Name cannot be null or empty"); } - nativeName = textNormaliser.normalise(nativeName); - return Optional.ofNullable(countryNativeNameToCountry.get(nativeName)); + localisedName = textNormaliser.normalise(localisedName); + return Optional.ofNullable(countryNativeNameToCountry.get(localisedName)); } @Override diff --git a/library/src/main/java/com/tomaytotomato/usecase/FindCity.java b/library/src/main/java/com/tomaytotomato/usecase/FindCity.java index 0b44c86..680f2a4 100644 --- a/library/src/main/java/com/tomaytotomato/usecase/FindCity.java +++ b/library/src/main/java/com/tomaytotomato/usecase/FindCity.java @@ -4,11 +4,31 @@ import java.util.List; import java.util.Optional; +/** + * Interface for finding cities based on various criteria. + */ public interface FindCity { + /** + * Find a city by its unique identifier (ID). + * + * @param id the unique identifier of the city + * @return an Optional containing the City if found, otherwise an empty Optional + */ Optional findCityById(Integer id); + /** + * Retrieve a list of all cities available in the data source. + * + * @return a List of all City objects + */ List findAllCities(); + /** + * Retrieve a list of all cities that match the specified city name. + * + * @param cityName the name of the city + * @return a List of City objects that match the specified city name + */ List findAllCitiesByCityName(String cityName); } diff --git a/library/src/main/java/com/tomaytotomato/usecase/FindCountry.java b/library/src/main/java/com/tomaytotomato/usecase/FindCountry.java index 8a2285a..96a669e 100644 --- a/library/src/main/java/com/tomaytotomato/usecase/FindCountry.java +++ b/library/src/main/java/com/tomaytotomato/usecase/FindCountry.java @@ -4,20 +4,76 @@ import java.util.List; import java.util.Optional; +/** + * Interface for finding countries based on various criteria. + */ public interface FindCountry { + /** + * Find a country by its unique identifier (ID), which represents a specific country. + * e.g. Afghanistan - 1, Belgium - 22 + * + * @param id the unique identifier of the country + * @return an Optional containing the Country if found, otherwise an empty Optional + */ Optional findCountryById(Integer id); + /** + * Find a country by its official name. + * + * @param countryName the official name of the country + * @return an Optional containing the Country if found, otherwise an empty Optional + */ Optional findCountryByName(String countryName); - Optional findCountryByNativeName(String nativeName); + /** + * Finds a country by its localized or native name. + *

+ * This method searches for a country using its localized name, which may vary + * depending on the language or region. For example, the country of Belgium + * may be referred to as: + *

    + *
  • "Belgien" (German)
    • + *
  • "Belgique" (French)
    • + *
  • "Belgium" (English)
    • + *
+ *

+ * + * @param localisedName the localized or native name of the country + * @return an Optional containing the Country if found, otherwise an empty Optional + */ + Optional findCountryByLocalisedName(String localisedName); + + /** + * Retrieve a list of all countries available in the data source. + * + * @return a List of all Country objects + */ List findAllCountries(); + /** + * Find a country by its ISO 3166-1 alpha-2 code, a two-letter country code. + * + * @param iso2Code the ISO 3166-1 alpha-2 code of the country + * @return an Optional containing the Country if found, otherwise an empty Optional + */ Optional findCountryByISO2Code(String iso2Code); + /** + * Find a country by its ISO 3166-1 alpha-3 code, a three-letter country code. + * + * @param iso3Code the ISO 3166-1 alpha-3 code of the country + * @return an Optional containing the Country if found, otherwise an empty Optional + */ Optional findCountryByISO3Code(String iso3Code); + /** + * Retrieve a list of all countries that have a state with the specified name. + * + * @param stateName the name of the state + * @return a List of Country objects that contain the specified state name + */ List findAllCountriesByStateName(String stateName); } diff --git a/library/src/main/java/com/tomaytotomato/usecase/FindState.java b/library/src/main/java/com/tomaytotomato/usecase/FindState.java index 8dd3c54..33197b4 100644 --- a/library/src/main/java/com/tomaytotomato/usecase/FindState.java +++ b/library/src/main/java/com/tomaytotomato/usecase/FindState.java @@ -4,12 +4,33 @@ import java.util.List; import java.util.Optional; +/** + * Interface for finding states based on various criteria. + */ public interface FindState { + /** + * Find a state by its unique identifier (ID). + * + * @param id the unique identifier of the state + * @return an Optional containing the State if found, otherwise an empty Optional + */ Optional findStateById(Integer id); + /** + * Retrieve a list of all states that match the specified state name. + * + * @param name the name of the state + * @return a List of State objects that match the specified state name + */ List findAllStatesByStateName(String name); + /** + * Retrieve a list of all states that match the specified state code. + * + * @param stateCode the code of the state + * @return a List of State objects that match the specified state code + */ List findAllStatesByStateCode(String stateCode); } diff --git a/library/src/main/java/com/tomaytotomato/usecase/SearchLocation.java b/library/src/main/java/com/tomaytotomato/usecase/SearchLocation.java index 1f979fb..967eb7e 100644 --- a/library/src/main/java/com/tomaytotomato/usecase/SearchLocation.java +++ b/library/src/main/java/com/tomaytotomato/usecase/SearchLocation.java @@ -3,14 +3,34 @@ import com.tomaytotomato.model.Location; import java.util.List; +/** + * Interface for searching locations based on a free-text input. + */ public interface SearchLocation { /** - * Searches for locations based off a text input e.g. - "Canada, Alberta" - "Santa Clara, CA, USA" - * - "Glasgow, GB" - "Glasgow, Scotland" - "San Francisco" + * Searches for locations based on a free-text input. + *

+ * This method accepts input strings that can be formatted in various ways, such as: + *

    + *
  • "Canada, Alberta"
    • + *
  • "Santa Clara, CA, USA"
    • + *
  • "Glasgow, GB"
    • + *
  • "Glasgow, Scotland"
    • + *
  • "San Francisco"
    • + *
+ * The input can be formatted or unformatted, for example: + *
    + *
  • "uk, glasgow"
    • + *
  • "glasgow UNITED KINGDOM"
    • + *
  • "USA san Francisco"
    • + *
  • "san Francisco United States"
    • + *
+ * The method normalizes and tokenizes the input to find matching locations. + *

* - * @param text free text input - * @return list of locations that match text input + * @param text the free-text input used to search for locations + * @return a List of Location objects that match the input text */ List search(String text); diff --git a/library/src/test/java/com/tomaytotomato/usecase/FindCountryTest.java b/library/src/test/java/com/tomaytotomato/usecase/FindCountryTest.java index ff8d3f6..c35ef6c 100644 --- a/library/src/test/java/com/tomaytotomato/usecase/FindCountryTest.java +++ b/library/src/test/java/com/tomaytotomato/usecase/FindCountryTest.java @@ -110,28 +110,30 @@ void findCountryByName_WhenCountryNameExists_ThenReturnCountry(String countryNam } - @DisplayName("Find Country By Native Name, when country name is null or blank, then throw exception") + @DisplayName("Find Country By Localised Name, when country name is null or blank, then throw exception") @Test void findCountryByNativeName_WhenNameIsNull_ThenThrowException() { - assertThatThrownBy(() -> locationService.findCountryByNativeName(null)) + assertThatThrownBy(() -> locationService.findCountryByLocalisedName(null)) .isInstanceOf(IllegalArgumentException.class) - .hasMessage("Country Native Name cannot be null or empty"); + .hasMessage("Country Localised Name cannot be null or empty"); } - @DisplayName("Find Country By Native Name, when native name exists then return country") + @DisplayName("Find Country By Localised Name, when name exists then return country") @ParameterizedTest @CsvSource({ "United Kingdom, United Kingdom", "Cote D'Ivoire, Ivory Coast", "Deutschland, Germany", "Nederland, Netherlands", - + "Belgique, Belgium", + "Belgio, Belgium", + "벨기에, Belgium" }) - void findCountryByNativeName_WhenNativeNameExists_ThenReturnCountry(String nativeName, String expectedCountryName) { + void findCountryByNativeName_WhenNativeNameExists_ThenReturnCountry(String localisedName, String expectedCountryName) { // When - var result = locationService.findCountryByNativeName(nativeName); + var result = locationService.findCountryByLocalisedName(localisedName); // Then assertThat(result).isNotEmpty().get().extracting("name").isEqualTo(expectedCountryName);