CountryCodes (Commons)

java.lang.Object
- com.lf.commons.i18n.CountryCodes

```
public class CountryCodes
extends java.lang.Object
```
Provides support for ISO 3166-1 country codes and names in various translations.
The codes defined by this class have been extracted from the ISO website http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/index.html with the help of several XSLT scripts executed by CARAMEL. The ISO website offers the mappings from ISO 3166-1 and the country names in English and French. This class is a fast lightweight database for languages using efficient data caches which are installed when needed. Also the I18NFactory class provides support for a shared instance so application servers and KAT applications do not have to create multiple objects. Since the data provided here is static there is no need to have more than one single instance doing the job for you. The German language country names can be found on the German Wikipedia network site http://de.wikipedia.org/wiki/ISO-3166-1-Kodierliste.
You can request values in each direction: get an ISO 3166-1 code by country name and vice versa. For populating GUI lists and comboboxes you can request containers with all available codes and names.
Another key feature of this class is the translation support. At the moment the default language for country names is English. If you like to use a different language for example while running web applications you may equip the name-related methods of this class with a locale parameter. At the moment German and French are supported as translations. If you like the default language (English) you can pass null here. The localized definitions for all languages are loaded from the file countries.conf which is part of the locale specific sub-directory of the core package. The format of the definition file countries.conf is as follows:
```
 ...
 COUNTRY_1_ISO3166-1=AF
 COUNTRY_1_NAME=AFGHANISTAN
 COUNTRY_2_ISO3166-1=ZA
 COUNTRY_2_NAME=AFRIQUE DU SUD
 COUNTRY_3_ISO3166-1=AX
 COUNTRY_3_NAME=ELAND, ILES D'
 ...
 
```
If you plan to add new translation files for country names make sure to set all the codes defined by the English language default file. It is sufficient to set a new file within an appropriate sub-directory of the core package, the class will find and automatically load it if the supported locale is requested by programs. For example if you plan to add a Dutch translation you have to add the file countries.conf to the sub-directory dut_NL or any valid Dutch locale directory.
There is a specific code range defined by ISO which can be used for local codes (e.g. program specific identifiers). To use this range simply create a subclass of CountryCodes, execute super(); in order to have the initial caches properly installed, and then set your own local codes to the caches by calling the put method. For example a new mapping can be added with super.cacheNameBy3166_1.put("ZZ", "Region Alpha");. Normally you will not set any ISO 3166-1 codes but you could do so, as long as the official codes are not overwritten. If you implement a subclass the factory class cannot be used. Make sure to set also the translations currently in use in order to avoid unpredictable side effects.
Subclasses also have to take care of translations of country names in other languages than English (which is the default). If you set local codes as described above you must also set the corresponding translations in order to keep the class working. At the moment the class supports translations in French and German. You should also take care of the proper *.conf file encoding (UTF-8, ISO-8859-1 and so forth). At the moment all *.conf files used by the KAT framework are encoded with ISO-8859-1 since this is my default system encoding.
Since this class uses some amount of memory for the caches you could also create instances as usual if you only use this class once in your program. If you use the factory shared instance the memory will never be released during the JVM lifetime as long as you do not flush the factory. As you can see you can tune this class either for more performance or for a smaller memory footprint.
This class is tested in detail by the class TestCountryCodes which you can find in the test directory of the KAT framework. Let me encourage you to always adapt and execute this test class when changes are applied since also little changes can cause errors.
Since:

1.5

Version:

$Revision: 1.10 $, $Date: 2012/12/28 11:44:25 $

Author:

Axel Schwolow

See Also:
I18NFactory, I18NUtils

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.util.Hashtable<java.lang.String,java.lang.String>`	`cache3166_1ByName` Container for fast acquisition of ISO 3166-1 codes by country name.
`protected java.util.Hashtable<java.lang.String,java.lang.String>`	`cacheNameBy3166_1` Container for fast acquisition of country names by ISO 3166-1 code.
`protected java.util.Hashtable<Locale,java.util.Hashtable<java.lang.String,java.lang.String>>`	`cacheTranslations` Container for translations of the ISO country names (English is default).
`protected Locale`	`locale` Current default locale, normally "eng_US".

Constructor Summary

Constructors
Constructor and Description

CountryCodes()
Constructor method.

Constructors
Constructor and Description
`CountryCodes()` Constructor method.

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`finalize()` Cares for proper cleanup when is not needed any longer (helps gc).
`java.lang.String`	`get3166_1ByName(java.lang.String name, Locale locale)` Returns the ISO 3166-1 code associated with a certain country name.
`java.util.Vector<java.lang.String>`	`getAll3166_1()` Returns the sorted list with supported ISO 3166-1 codes.
`java.util.Vector<java.lang.String>`	`getAllNames3166_1(Locale locale)` Returns the sorted list with supported country names associated with ISO 3166-1 codes.
`Locale`	`getDefaultLocale()` Returns the default locale used for country names (normally "eng_US" = English).
`java.lang.String`	`getNameBy3166_1(java.lang.String code, Locale locale)` Returns the country name associated with a certain ISO 3166-1 code.
`java.util.Vector<Locale>`	`getSupportedLocales(boolean synonyms)` Returns the locales currently supported for the country names.
`protected void`	`installInitialCaches()` Installs the initial caches and loads ISO 3166-1 data from `*.conf` file.
`protected java.util.Hashtable<java.lang.String,java.lang.String>`	`loadTranslation(Locale locale)` Tries to load names translation data for a specific locale.
`static void`	`main(java.lang.String[] args)` This can be used for the debugging purposes.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - cacheNameBy3166_1
```
protected java.util.Hashtable<java.lang.String,java.lang.String> cacheNameBy3166_1
```
    Container for fast acquisition of country names by ISO 3166-1 code. Key is ISO 3166-1 code (String), value is country name (String).
  - cache3166_1ByName
```
protected java.util.Hashtable<java.lang.String,java.lang.String> cache3166_1ByName
```
    Container for fast acquisition of ISO 3166-1 codes by country name. Key is country name (String), value is ISO 3166-1 code (String).
  - cacheTranslations
```
protected java.util.Hashtable<Locale,java.util.Hashtable<java.lang.String,java.lang.String>> cacheTranslations
```
    Container for translations of the ISO country names (English is default).
  - locale
```
protected Locale locale
```
    Current default locale, normally "eng_US".
- Constructor Detail
  - CountryCodes
```
public CountryCodes()
```
    Constructor method.
    
    Since:
    
    1.5
- Method Detail
  - installInitialCaches
```
protected void installInitialCaches()
```
    Installs the initial caches and loads ISO 3166-1 data from *.conf file.
    Currently there is only one cache installed initially for some reason. The cache cacheNameBy3166_1 is created to store the country names by ISO 3166-1 code. The second cache cache3166_1ByName allows for getting the ISO 3166-1 codes by country name and is installed when needed in order to save resources.
    Throws java.lang.RuntimeException if the resource file could not be read or if another error occurs.
    
    Since:
    
    1.5
  - finalize
```
protected void finalize()
                 throws java.lang.Throwable
```
    Cares for proper cleanup when is not needed any longer (helps gc).
    The caches are cleared here to allow for a faster garbage collecting.
    
    Overrides:
    
    finalize in class java.lang.Object
    
    Throws:
    
    java.lang.Throwable - Error indication
    Since:
    
    1.5
  - getNameBy3166_1
```
public java.lang.String getNameBy3166_1(java.lang.String code,
                               Locale locale)
```
    Returns the country name associated with a certain ISO 3166-1 code.
    Throws NullPointerException if code is null. If a country name does not exist for the specified code or there is no appropriate names translation available then null is returned.
    If you like the names in a locale other than the default (currently English) simply set the locale parameter appropriately (e.g. "de" for German country names). If you pass null here the names for the default locale will be returned.
    
    Parameters:
    code - The ISO 3166-1 code of interest, don't pass null values
    locale - The locale for the name language, may be null
    
    Returns:
    The country name, null if code does not exist
    Since:
    
    1.5
  - loadTranslation
```
protected java.util.Hashtable<java.lang.String,java.lang.String> loadTranslation(Locale locale)
```
    Tries to load names translation data for a specific locale.
    The result container is null if the given locale code does not exist. The method also tries out all defined synonyms and associated codes (e.g. 639-2 for a given 639-1 code and vice versa). This way the method ensures that data is loaded even if the caller did not pass the exact locale code.
    Throws java.lang.RuntimeException if the resource file could not be imported properly.
    
    Parameters:
    locale - The locale code for which data shall be loaded
    
    Returns:
    The container with name translations, empty if translation file does not exist
    Since:
    
    1.5
  - get3166_1ByName
```
public java.lang.String get3166_1ByName(java.lang.String name,
                               Locale locale)
```
    Returns the ISO 3166-1 code associated with a certain country name.
    Throws NullPointerException if name is null. If an ISO 3166-1 code does not exist for the specified locale then null is returned.
    If you use names in a language other than the default (currently English) simply set the locale parameter appropriately (e.g. "de" for German language names). If you pass null here the names in the default language will be returned. Make sure that the given name is defined for the specified language.
    
    Parameters:
    name - The country name of interest, don't pass null values
    locale - The locale code for the name language, may be null
    
    Returns:
    The ISO 3166-1 code, null if country does not exist
    Since:
    
    1.5
  - getAllNames3166_1
```
public java.util.Vector<java.lang.String> getAllNames3166_1(Locale locale)
```
    Returns the sorted list with supported country names associated with ISO 3166-1 codes.
    If you like the names in a language other than the default (currently English) simply set the locale parameter appropriately (e.g. "de" for German language names). If you pass null here the names in the default language will be returned. If an appropriate translation is not available the result container will be empty.
    This method returns Vector containers with String objects ready to use with JComboBox instances.
    
    Parameters:
    locale - The locale code for the name language, may be null
    
    Returns:
    The sorted country names container with String objects
    Since:
    
    1.5
  - getAll3166_1
```
public java.util.Vector<java.lang.String> getAll3166_1()
```
    Returns the sorted list with supported ISO 3166-1 codes.
    This method returns Vector containers with String objects ready to use with JComboBox instances.
    
    Returns:
    The sorted ISO 3166-1 codes container with String objects
    Since:
    
    1.5
  - getDefaultLocale
```
public Locale getDefaultLocale()
```
    Returns the default locale used for country names (normally "eng_US" = English).
    
    Returns:
    The current default locale, be prepared for null
    Since:
    
    1.5
  - getSupportedLocales
```
public java.util.Vector<Locale> getSupportedLocales(boolean synonyms)
```
    Returns the locales currently supported for the country names.
    Remember that is is absolutely necessary to use the exact locale to acquire the language specific country names. Currently there is no fallback mechanism implemented like returning "eng_US" when "eng" is requested. Only language synonyms defined by ISO 639-1/2 are possible. For instance you will get country names for "ger_DE" if you request "de_DE" or "deu_DE" since these are synonyms for one and same language German. You can specify whether to return only the concrete locale candidates in the path or the candidates plus the synonyms like "deu_DE" and "de_DE" for "ger_DE".
    
    Parameters:
    synonyms - Also add the ISO 639-1/2 synonyms like "deu_DE" for "ger_DE"?
    
    Returns:
    The supported locales, maybe empty
    Since:
    
    1.5
  - main
```
public static void main(java.lang.String[] args)
```
    This can be used for the debugging purposes.
    
    Parameters:
    args - Array of strings with console arguments
    Since:
    
    1.6

Class CountryCodes

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

cacheNameBy3166_1

cache3166_1ByName

cacheTranslations

locale

Constructor Detail

CountryCodes

Method Detail

installInitialCaches

finalize

getNameBy3166_1

loadTranslation

get3166_1ByName

getAllNames3166_1

getAll3166_1

getDefaultLocale

getSupportedLocales

main