Class ContinentCodes

java.lang.Object
com.iizix.selector.ContinentCodes
public class ContinentCodes extends Object
The continent codes and associated country code.

This class maps a two-letter country code onto one of the seven continent codes AF, AN, AS, EU, NA, OC and SA, and a continent code onto its English name. The country code to country NAME mapping is NOT done here: LanguageMatch.countryNames already does it, and this class supplies the continent axis only.

Codes are case insensitive. Every method taking a code upper-cases it with Locale.ENGLISH before the look-up, never the no-argument form, so a Turkish default locale cannot turn "mc" into anything but "MC".

A null argument is a caller defect and throws NullPointerException; every other failure to resolve a code returns null and throws nothing -- an unknown code, an empty string and a string of the wrong length are all ordinary look-up misses. The two are kept apart deliberately: if a null argument also returned null, a null return would mean two different things and no caller could tell which.

Three codes in the table belong to no continent and carry "--" as their continent: A1, A2 and O1. The table builder skips them, so getContinentFromCountryCode(String) returns null for them exactly as it does for a code that is not in the table at all -- the two cases are indistinguishable through this API. They ARE included in getSupportedCountryCodes(), which is built from the table itself and not from the continent maps.

Six codes are both a country code and a continent code and mean different things in the two look-ups: AF is Afghanistan as a country and Africa as a continent, AN is Netherlands Antilles and Antarctica, AS is American Samoa and Asia, NA is Namibia and North America, SA is Saudi Arabia and South America, and EU is both. Never feed the result of one look-up into the other, other than through getEnglishContinentNameFromCountryCode(String).

The table is not ISO 3166, and it is not current. It carries four codes that ISO 3166 does not define -- A1, A2, O1 and AP -- plus EU and FX, which makes it a MaxMind GeoIP country-continent table rather than an ISO list. Its vintage is readable from what it holds: it HAS AN (Netherlands Antilles, withdrawn 2010-12-15) and it LACKS BQ, CW and SX (the three codes that replaced it), SS (South Sudan, 2011) and XK, so it is a snapshot from 2010 or earlier. All five presence checks were made against the table text, not assumed. LanguageMatch.countryNames in this same package DOES have SS, so the two tables in one package disagree about which countries exist -- registered as IIZI-SELECTOR-COUNTRY-TABLES-DISAGREE, and neither table is changed until that is ruled on.

Author:
Christopher Mindus

  • Constructor Details

    • ContinentCodes

      public ContinentCodes()

  • Method Details

    • getEnglishContinentName

      public static String getEnglishContinentName(String continentCode)
      Gets the English name of a continent code, e.g. "EU" gives "Europe".
      Parameters:
      continentCode - The continent code, case insensitive, upper-cased with Locale.ENGLISH before the look-up.
      Returns:
      The English continent name, or null when the code is not a continent code, including an empty string or a string of the wrong length. Only a null argument throws.
      Throws:
      NullPointerException - If continentCode is null.

    • getContinentFromCountryCode

      public static String getContinentFromCountryCode(String countryCodeISO3166)
      Gets the continent code for a country code formatted as EU....
      Parameters:
      countryCodeISO3166 - The ISO 3166 country code, case insensitive, upper-cased with Locale.ENGLISH before the look-up.
      Returns:
      The continent code, or null when the country code is unknown, when it is one of the "--" countries A1, A2 and O1 that belong to no continent, or when it is empty or of the wrong length. Only a null argument throws.
      Throws:
      NullPointerException - If countryCodeISO3166 is null.

    • getEnglishContinentNameFromCountryCode

      public static String getEnglishContinentNameFromCountryCode(String countryCodeISO3166)
      Gets the English continent name for a country code, e.g. "MC" gives "Europe".
      Parameters:
      countryCodeISO3166 - The ISO 3166 country code, case insensitive, upper-cased with Locale.ENGLISH before the look-up.
      Returns:
      The English continent name, or null in every case where getContinentFromCountryCode(String) returns null. Only a null argument throws.
      Throws:
      NullPointerException - If countryCodeISO3166 is null.

    • getSupportedCountryCodes

      public static List<String> getSupportedCountryCodes()
      Gets all the country codes this class knows.
      Returns:
      An unmodifiable list of the country codes of the table, sorted with Utilities.COLLATOR, never null. It includes A1, A2 and O1, which belong to no continent -- see the class documentation for why.

    • getContinentCountryCodes

      public static Map<String, List<String>> getContinentCountryCodes()
      Gets the countries of each continent, by continent code.

      The map and every list in it are unmodifiable in depth, which is deliberate: the tables are static and shared for the life of the JVM, so a caller able to write through the returned reference would corrupt them for every other caller. Nothing mutable is exposed, and for that reason nothing is copied on the way out either -- the same instance is returned on every call.

      Returns:
      An unmodifiable map, never null, with the seven continent codes as keys sorted with Utilities.COLLATOR, each mapped to its country codes, also sorted. A1, A2 and O1 appear in no list -- see getSupportedCountryCodes().

    • getContinentCountryNames

      public static Map<String, List<String>> getContinentCountryNames()
      Gets the countries of each continent, by English continent name.

      The same map as getContinentCountryCodes() keyed by the English continent name instead of the code, and unmodifiable in depth for the same reason. The lists are the same instances, so the two maps cannot drift apart.

      Returns:
      An unmodifiable map, never null, with the seven English continent names as keys in the order of their continent codes sorted with Utilities.COLLATOR, each mapped to its country codes, also sorted.